# Welcome to Coreflux
Source: https://docs.coreflux.org/latest/index

One MQTT broker that gets data from your devices, centralizes it, processes it with LoT (Language of Things), and sends it wherever it needs to go. Explore how the pieces fit together, or jump straight in.

# Welcome to Coreflux

One MQTT broker that gets data from your devices, centralizes it, processes it with LoT, and sends it wherever it needs to go.

[Get started](/latest/quick-start/getting-started)
[Install Coreflux](/latest/quick-start/installation)

## Quick Navigation

> **[Getting Started](/latest/quick-start/getting-started)**
>
> Go from zero to your first LoT Action in under 5 minutes.

> **[Installation](/latest/quick-start/installation)**
>
> Install Coreflux with Docker, Docker Compose, or a native binary.

> **[Coreflux HUB](/hub/overview)**
>
> Manage your broker from the browser—explore topics, edit LoT, configure connectors.

> **[LoT Language](/latest/lot-language/introduction)**
>
> Learn the Language of Things - Actions, Models, Rules, Connectors, and Panels.

> **[Using AI with Coreflux](/latest/quick-start/using-ai)**
>
> Connect your AI assistant to the docs and build LoT with it.

> **[Get Coreflux](https://portal.coreflux.org/downloads)**
>
> Download the MQTT broker and Coreflux HUB from the Downloads page.

Join the community on [Discord](https://discord.com/invite/A3pPrptNMm) or explore examples on [GitHub](https://github.com/CorefluxCommunity).


# Callable ACTIONs
Source: https://docs.coreflux.org/latest/lot-language/actions/callable-actions

Reuse LoT logic across ACTIONs with callable utilities—shared calculations, validations, and on-demand scripts invoked via CALL ACTION.

## Overview

Most ACTIONs start automatically—on a schedule, when an MQTT message arrives, or at broker startup. A **callable ACTION** has no trigger. It runs when another ACTION invokes it with `CALL ACTION`, or when you publish `-runAction` to `$SYS/Coreflux/Command`.

Callable ACTIONs let you extract logic into named, reusable blocks: unit conversions, threshold checks, aggregations, or short on-demand scripts (refresh a cache, recalculate totals) that run at a specific point in a workflow—not on their own timer or topic.

> [!TIP]
>
> **Think of callable ACTIONs as functions inside the broker.** Triggered ACTIONs decide *when* something happens; callables hold *how* to compute, validate, or transform—and run only when called.

***

## When to Use Callable ACTIONs

Before splitting logic out, understand where callables fit:

| Use Callable ACTIONs For | Use Triggered ACTIONs For |
| - | - |
| Shared calculations used in multiple places | Reacting to MQTT messages (`ON TOPIC`, `ON CHANGE`) |
| Validations and transformations with typed inputs | Scheduled polling and reports (`ON EVERY`, `ON TIMESTAMP`) |
| On-demand steps inside a workflow (cache refresh, prep) | One-time bootstrap at startup (`ON START`) |
| Keeping main ACTION bodies short and readable | Logic that must run on its own when an event occurs |

> [!NOTE]
>
> If an ACTION must run by itself when data arrives or on a clock, give it a trigger. Use a callable when the logic is shared or should run only as part of another ACTION's flow. To invoke a callable from MQTT with JSON `INPUT` values, see [Broker Commands — run an Action on demand](/latest/mqtt-broker/commands#run-an-action-on-demand).

***

## Defining a Callable ACTION

A callable is a normal `DEFINE ACTION` **without** an `ON …` clause. Optionally declare `INPUT` parameters and `RETURN` one or more `OUTPUT` values.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION <Name>
[INPUT <param> AS <TYPE> ...]
DO
    -- logic
[RETURN
    OUTPUT <variable> ...]
```

### Supported INPUT Types

| Type | Typical use |
| - | - |
| `STRING` | IDs, labels, status text |
| `INT` | Counts, discrete setpoints |
| `DOUBLE` | Sensor readings, analog values |
| `BOOL` | Flags and enable/disable state |

### Parameterless Callable

Use when the block has no inputs—common for on-demand scripts that read from topics or update cached state:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION RefreshDashboardCache
DO
    KEEP TOPIC "cache/dashboard/summary" WITH (GET TOPIC "data/live/summary")
    PUBLISH TOPIC "cache/dashboard/updated" WITH TIMESTAMP "UTC"
```

### Callable with Inputs and Return Value

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ConvertCelsiusToFahrenheit
INPUT celsius AS DOUBLE
DO
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
RETURN
    OUTPUT fahrenheit
```

***

## CALL ACTION Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL ACTION <Name>
    WITH <param> = <expression>, ...
    RETURN <var1>[, <var2>, ...]
```

* `WITH` argument names must match the callee's `INPUT` names.
* `RETURN` variables are local to the caller and receive `OUTPUT` values in declaration order.

## Parameter Passing

Pass one or more values with `WITH`. Each name must match an `INPUT` on the callable:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL ACTION CalculateAverage
    WITH value1 = {temp1}, value2 = {temp2}
    RETURN result
```

Define the callable with a matching `INPUT` for each parameter:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CalculateAverage
INPUT value1 AS DOUBLE
INPUT value2 AS DOUBLE
DO
    SET "avg" WITH (({value1} + {value2}) / 2)
RETURN
    OUTPUT avg
```

## Return Value Handling

The `RETURN` clause on the caller captures values from the callable's `OUTPUT` declarations.

### Single Return Value

Declare one `OUTPUT` on the callable and one variable on the caller:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ConvertCelsiusToFahrenheit
INPUT celsius AS DOUBLE
DO
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
RETURN
    OUTPUT fahrenheit
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL ACTION ConvertCelsiusToFahrenheit
    WITH celsius = {temp_c}
    RETURN temp_f
```

### Multiple Return Values

Declare one `OUTPUT` per value. On the caller, list return variables in the **same order** as the `OUTPUT` lines:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AnalyzeValue
INPUT value AS DOUBLE
INPUT threshold AS DOUBLE
DO
    SET "is_above" WITH ({value} > {threshold})
    SET "difference" WITH ({value} - {threshold})
    SET "percentage" WITH ({value} / {threshold} * 100)
RETURN
    OUTPUT is_above
    OUTPUT difference
    OUTPUT percentage
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL ACTION AnalyzeValue
    WITH value = {reading}, threshold = {limit}
    RETURN above, diff, pct
```

The first `OUTPUT` (`is_above`) maps to `above`, the second to `diff`, and the third to `pct`.

***

## Usage Examples

**Reusable Logic**

Call a shared conversion from a topic-triggered ACTION instead of repeating the formula inline:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessTemperatureReading
ON TOPIC "sensors/+/celsius" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp_c" WITH PAYLOAD AS DOUBLE

    CALL ACTION ConvertCelsiusToFahrenheit
        WITH celsius = {temp_c}
        RETURN temp_f

    PUBLISH TOPIC "sensors/" + {sensor_id} + "/fahrenheit" WITH {temp_f}
```

**On-Demand Scripts**

A parameterless callable runs only when a triggered ACTION calls it—not on its own schedule or topic:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION HourlyDashboardReport
ON EVERY 1 HOUR DO
    CALL ACTION RefreshDashboardCache

    SET "summary" WITH (GET TOPIC "cache/dashboard/summary")
    PUBLISH TOPIC "reports/dashboard/hourly" WITH {summary}
```

**Composing Callables**

Chain callables in a triggered ACTION so the main body stays focused on orchestration:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessTankLevel
ON TOPIC "tanks/+/level" DO
    SET "tank_id" WITH TOPIC POSITION 2
    SET "level" WITH PAYLOAD AS DOUBLE
    SET "capacity" WITH (GET TOPIC "config/" + {tank_id} + "/capacity" AS DOUBLE)

    CALL ACTION CalculatePercentage
        WITH value = {level}, total = {capacity}
        RETURN fill_pct

    CALL ACTION AnalyzeReading
        WITH current = {level}, threshold = ({capacity} * 0.9)
        RETURN above, diff, pct_of_max

    PUBLISH TOPIC "processed/" + {tank_id} + "/fill_percent" WITH {fill_pct}
    PUBLISH TOPIC "processed/" + {tank_id} + "/over_threshold" WITH {above}
```

***

## Best Practices

> **One Callable, One Job**
>
> Each callable should do one clear thing—convert units, validate a range, compute an average. If a block grows large or handles unrelated steps, split it into separate callables and compose them with `CALL ACTION`.

> **Extract Before the Third Copy**
>
> The moment the same expression appears in two ACTIONs, consider a callable. Shared rules (thresholds, conversions, KPI formulas) belong in one place so fixes propagate to every caller on deploy.

> **Name for Intent**
>
> Use PascalCase, function-like names: `ConvertCelsiusToFahrenheit`, `CalculateAverage`, `ValidateReading`. See [Naming conventions](/latest/lot-language/usage-patterns/naming-conventions).

> **Keep Triggered ACTIONs Thin**
>
> Triggered ACTIONs should read as workflows: read data, call utilities, publish results. Push calculations and validations into callables so topic and schedule handlers stay easy to scan and maintain.

***

## Next Steps

> **[Operations Reference](./operations)**
>
> Review all available LoT operations.

> **[ACTION Triggers](./events)**
>
> Time-based, topic-based, and initialization triggers.


# ACTION Triggers
Source: https://docs.coreflux.org/latest/lot-language/actions/events

Define when actions execute using time-based schedules (ON EVERY, ON TIMESTAMP), topic-based events, or manual invocation

## Overview

Every Action needs a trigger—the event that starts its execution. Choosing the right trigger type determines how your automation responds to real-world conditions.

> [!TIP]
>
> **Think of triggers like different ways to start your car.** A time-based trigger is like an auto-start that warms up your car every morning at 7 AM. A topic-based trigger is like pushing the start button when you get in. A callable action is like asking someone else to start it for you.

## When to Use Each Type

| Trigger Type | Use When | Example |
| - | - | - |
| **Time-Based** (`ON EVERY`, `ON TIMESTAMP`) | You need a clock-driven schedule (interval or wall-clock) | Heartbeats, polling, shift windows, one-shot cutovers |
| **Topic-Based** (`ON TOPIC`, `ON CHANGE`) | You need to react when MQTT data arrives | Sensor processing, commands; `ON CHANGE` when only new values matter |
| **Initialization** (`ON START`) | You need to run logic once when the broker starts | Bootstrap UNS structure, set default config values |
| **Client lifecycle** (`ON CONNECT`, `ON DISCONNECT`, `ON SUBSCRIBE`) | You need to react to MQTT session events | Connection audit, session dashboards, subscription tracking |
| **Callable** (no trigger) | You need reusable logic invoked by other actions | Utility functions, shared calculations |

***

## Time-Based Triggers

LoT supports several time-based trigger forms. All of them use the `ON` keyword and run the action's `DO` block automatically—no MQTT message is required to fire them. Together they cover recurring intervals, calendar rules (a specific weekday, Monday–Friday, or Saturday–Sunday), daily wall-clock times, and single one-shot executions.

### Quick reference

| Syntax | Pattern | Recurs? |
| - | - | - |
| `ON EVERY` *N* *UNIT* | Every *N* seconds, minutes, hours, and so on | Yes — indefinitely |
| `ON EVERY` *DAY* `AT` `"HH:mm"` | Named weekday at a fixed local time | Yes — every week |
| `ON EVERY WEEKDAY AT` `"HH:mm"` | Monday–Friday at a fixed local time | Yes — every weekday |
| `ON EVERY WEEKEND AT` `"HH:mm"` | Saturday–Sunday at a fixed local time | Yes — every weekend |
| `ON TIMESTAMP` `"HH:mm:ss"` | Every day at a fixed local time | Yes — every day |
| `ON TIMESTAMP` `"dd-MM-yyyy HH:mm:ss"` | Exact date and time | No — one-shot |

> [!NOTE]
>
> **Time zone:** For `HH:mm` and `HH:mm:ss` in `ON EVERY … AT` and in daily `ON TIMESTAMP`, values are interpreted in the **local time of the machine running the broker**, then converted to UTC internally. The action is scheduled for the correct wall-clock time across daylight saving changes. The one-shot form `dd-MM-yyyy HH:mm:ss` is interpreted as **UTC**, as described below.

> [!NOTE]
>
> **Structured payloads:** `PUBLISH TOPIC` does not support inline JSON object literals. For multi-field records, define a **COLLAPSED** model and use `PUBLISH MODEL … TO … WITH` (see [Publishing Models](/latest/lot-language/models/publish-model)). The timed-action examples below use that pattern.

### 1. `ON EVERY` *N* *UNIT* — fixed interval

Fires repeatedly every *N* units of time. Common for monitoring, polling, and heartbeats.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION <Name>
ON EVERY <N> <UNIT> DO
    -- body
```

#### Supported units

| Keyword(s) | Example |
| - | - |
| `MILLISECOND` / `MS` | `ON EVERY 500 MS` |
| `SECOND` / `SECONDS` | `ON EVERY 30 SECONDS` |
| `MINUTE` / `MINUTES` | `ON EVERY 5 MINUTES` |
| `HOUR` / `HOURS` | `ON EVERY 1 HOUR` |
| `DAY` / `DAYS` | `ON EVERY 1 DAY` |
| `WEEK` / `WEEKS` | `ON EVERY 2 WEEKS` |
| `MONTH` / `MONTHS` | `ON EVERY 1 MONTH` |
| `YEAR` / `YEARS` | `ON EVERY 1 YEAR` |

> [!NOTE]
>
> Singular and plural unit names are interchangeable (for example, `1 SECOND` and `1 SECONDS`). `ON EVERY 1 DAY` fires every 24 hours from the last run; for the same clock time every calendar day, use daily `ON TIMESTAMP` instead.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SystemHeartbeat
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH "alive"
    PUBLISH TOPIC "system/heartbeat/timestamp" WITH TIMESTAMP "UTC"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PollMachineTemperature
ON EVERY 30 SECONDS DO
    SET "temp" WITH GET TOPIC "machine/sensor/temperature"
    IF {temp} > 85 THEN
        PUBLISH TOPIC "alerts/temperature/high" WITH {temp}
    PUBLISH TOPIC "machine/temperature/last_check" WITH TIMESTAMP "UTC"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION FastSensorSample
ON EVERY 500 MS DO
    PUBLISH TOPIC "sensors/vibration/sample" WITH GET TOPIC "sensors/vibration/raw"
```

### 2. `ON EVERY` *DAY* `AT` — weekly, specific day

Fires once per week on the named weekday at the given **local** time. Use `"HH:mm"` or `"HH:mm:ss"`; seconds are optional.

| Keyword | Fires on |
| - | - |
| `MONDAY` … `SUNDAY` | That weekday each week |

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION <Name>
ON EVERY MONDAY AT "08:00:00" DO
    -- body
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ProductionWeeklyReport COLLAPSED
    ADD STRING "week"
    ADD INT "total_parts"
    ADD INT "total_rejects"

DEFINE ACTION WeeklyProductionReport
ON EVERY MONDAY AT "08:00:00" DO
    SET "week_total" WITH GET TOPIC "factory/line1/parts_produced"
    SET "week_rejects" WITH GET TOPIC "factory/line1/rejects"
    PUBLISH MODEL ProductionWeeklyReport TO "reports/weekly/production" WITH
        week = TIMESTAMP "UTC"
        total_parts = {week_total}
        total_rejects = {week_rejects}
    PUBLISH TOPIC "factory/line1/parts_produced" WITH 0
    PUBLISH TOPIC "factory/line1/rejects" WITH 0
```

### 3. `ON EVERY WEEKDAY AT` — Monday–Friday

Fires Monday through Friday at the same **local** time—one action instead of five separate daily schedules.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ShiftMorningBriefing COLLAPSED
    ADD STRING "line_status"
    ADD STRING "pending_orders"
    ADD STRING "shift_start"

DEFINE ACTION ShiftStartBriefing
ON EVERY WEEKDAY AT "07:30" DO
    SET "line_status" WITH GET TOPIC "factory/line1/status"
    SET "pending_orders" WITH GET TOPIC "erp/orders/pending"
    PUBLISH MODEL ShiftMorningBriefing TO "shift/briefing/morning" WITH
        line_status = {line_status}
        pending_orders = {pending_orders}
        shift_start = TIMESTAMP "UTC"
```

### 4. `ON EVERY WEEKEND AT` — Saturday and Sunday

Fires on both weekend days at the specified **local** time—useful for maintenance windows or weekend-only reporting.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION WeekendMaintenanceWindow
ON EVERY WEEKEND AT "06:00:00" DO
    PUBLISH TOPIC "maintenance/window/open" WITH "true"
    PUBLISH TOPIC "maintenance/window/start" WITH TIMESTAMP "UTC"
    PUBLISH TOPIC "notifications/maintenance" WITH "Weekend maintenance window is now open"
```

### 5. `ON TIMESTAMP` — daily fixed time

Fires **every day** at the given **local** wall-clock time. Unlike `ON EVERY 1 DAY`, this tracks clock time, not elapsed time since the broker or last run started.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION <Name>
ON TIMESTAMP "08:00:00" DO
    -- body
```

`"HH:mm"` without seconds is accepted.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DailyCounterReset
ON TIMESTAMP "00:00:00" DO
    PUBLISH TOPIC "factory/line1/parts_produced" WITH 0
    PUBLISH TOPIC "factory/line1/rejects" WITH 0
    PUBLISH TOPIC "factory/line1/day_start" WITH TIMESTAMP "UTC"
```

### 6. `ON TIMESTAMP` — one-shot, exact date and time

Fires **once** at the exact instant given, then never again (the scheduler moves the next run far into the future). Format is strictly **`dd-MM-yyyy HH:mm:ss`** (day–month–year). The timestamp is treated as **UTC**.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SystemCutoverNotice
ON TIMESTAMP "01-04-2026 06:00:00" DO
    PUBLISH TOPIC "system/cutover/notice" WITH "New firmware version going live in 1 hour"
    PUBLISH TOPIC "notifications/all" WITH "Scheduled maintenance begins at 07:00 UTC"
```

### Combination patterns

Real systems often split schedules across several actions—one trigger per concern.

> **Fast poll + daily summary**
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL DailyTemperatureReport COLLAPSED
>     ADD DOUBLE "max"
>     ADD DOUBLE "min"
>     ADD STRING "date"
>
> DEFINE ACTION SensorPoll
> ON EVERY 10 SECONDS DO
>     SET "value" WITH GET TOPIC "sensors/temperature/raw"
>     PUBLISH TOPIC "sensors/temperature/current" WITH {value}
>
> DEFINE ACTION DailySensorSummary
> ON TIMESTAMP "00:00:00" DO
>     SET "max" WITH GET TOPIC "sensors/temperature/max"
>     SET "min" WITH GET TOPIC "sensors/temperature/min"
>     PUBLISH MODEL DailyTemperatureReport TO "reports/daily/temperature" WITH
>         max = {max}
>         min = {min}
>         date = TIMESTAMP "UTC"
>     PUBLISH TOPIC "sensors/temperature/max" WITH 0
>     PUBLISH TOPIC "sensors/temperature/min" WITH 0
> ```

> **Weekday operations + weekend maintenance**
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE ACTION WeekdayProductionStart
> ON EVERY WEEKDAY AT "06:00" DO
>     PUBLISH TOPIC "factory/line1/mode" WITH "production"
>     PUBLISH TOPIC "factory/line1/shift_start" WITH TIMESTAMP "UTC"
>
> DEFINE ACTION WeekendMaintenance
> ON EVERY WEEKEND AT "07:00" DO
>     PUBLISH TOPIC "factory/line1/mode" WITH "maintenance"
>     PUBLISH TOPIC "notifications/maintenance/start" WITH TIMESTAMP "UTC"
> ```

> **Weekly reset + daily snapshot + live throughput**
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL DashboardThroughput COLLAPSED
>     ADD INT "parts"
>     ADD DOUBLE "rate_per_min"
>     ADD INT "updated"
>
> DEFINE ACTION WeeklyKpiReset
> ON EVERY MONDAY AT "00:00:00" DO
>     PUBLISH TOPIC "kpi/weekly/parts_produced" WITH 0
>     PUBLISH TOPIC "kpi/weekly/reset_time" WITH TIMESTAMP "UTC"
>
> DEFINE ACTION DailyKpiSnapshot
> ON TIMESTAMP "23:59:00" DO
>     SET "daily_parts" WITH GET TOPIC "factory/line1/parts_produced"
>     PUBLISH TOPIC "kpi/daily/snapshot" WITH {daily_parts}
>     PUBLISH TOPIC "kpi/daily/snapshot_time" WITH TIMESTAMP "UTC"
>
> DEFINE ACTION LiveThroughput
> ON EVERY 1 MINUTE DO
>     SET "parts" WITH GET TOPIC "factory/line1/parts_produced"
>     SET "rate" WITH GET TOPIC "factory/line1/production_rate"
>     PUBLISH MODEL DashboardThroughput TO "dashboard/live/throughput" WITH
>         parts = {parts}
>         rate_per_min = {rate}
>         updated = TIMESTAMP "UNIX"
> ```

> **One-shot cutover + ongoing heartbeat**
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE ACTION CutoverActivation
> ON TIMESTAMP "01-07-2026 06:00:00" DO
>     PUBLISH TOPIC "system/version" WITH "2.0"
>     PUBLISH TOPIC "system/cutover/complete" WITH TIMESTAMP "UTC"
>
> DEFINE ACTION V2Heartbeat
> ON EVERY 30 SECONDS DO
>     SET "ver" WITH GET TOPIC "system/version"
>     IF {ver} EQUALS "2.0" THEN
>         PUBLISH TOPIC "system/v2/heartbeat" WITH "running"
> ```

### Error handling

If a time string does not match an expected format, the broker logs an error similar to:

`Invalid DATE_TIME format: <value>. Expected formats:`

* `dd-MM-yyyy HH:mm:ss` (one-time)
* `HH:mm:ss` / `HH:mm` (daily)
* Weekly forms using a day name with `AT` and a time string

Errors are also published (retained) to:

`$SYS/Coreflux/Actions/<ActionName>/Error`

Subscribe to `$SYS/Coreflux/Actions/+/Error` to observe failures from any action.

### At a glance — valid time triggers

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ON EVERY 500 MS DO
ON EVERY 10 SECONDS DO
ON EVERY 5 MINUTES DO
ON EVERY 1 HOUR DO
ON EVERY 1 DAY DO
ON EVERY 1 WEEK DO
ON EVERY 1 MONTH DO
ON EVERY MONDAY AT "08:00:00" DO
ON EVERY WEEKDAY AT "07:30" DO
ON EVERY WEEKEND AT "06:00" DO
ON TIMESTAMP "07:00" DO
ON TIMESTAMP "00:00:00" DO
ON TIMESTAMP "25-12-2026 09:00:00" DO
```

### More examples

> **System heartbeat**
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE ACTION SystemHeartbeat
> ON EVERY 5 SECONDS DO
>     PUBLISH TOPIC "system/status" WITH "online"
>     PUBLISH TOPIC "system/timestamp" WITH TIMESTAMP "UTC"
> ```

> **Counter with state**
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE ACTION IncrementCounter
> ON EVERY 10 SECONDS DO
>     IF GET TOPIC "counter/value" == EMPTY THEN
>         PUBLISH TOPIC "counter/value" WITH 0
>     ELSE
>         PUBLISH TOPIC "counter/value" WITH (GET TOPIC "counter/value" + 1)
> ```

***

## Topic-Based Triggers

MQTT-driven actions use a **topic trigger** — the condition that tells the broker *when* to run the action body. Both triggers share the same topic patterns and wildcards; the difference is whether repeated identical payloads should be ignored.

| Trigger | When the action runs |
| - | - |
| **`ON TOPIC`** | On **every** message that matches the topic pattern |
| **`ON CHANGE`** | When the message matches the pattern **and** the payload is **different** from the last message on that same topic |

### `ON TOPIC` — react to every message

Use `ON TOPIC` when each publish matters: commands, alarms, counters, or any flow where duplicate payloads still need processing.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessTemperature
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "processed/" + {sensor_id} + "/temperature" WITH {temp}
```

**Key characteristics:**

* Any client (or connector) that publishes to a matching topic runs the action.
* Publishing the same value twice runs the action **twice**.
* Wildcard `+` matches one topic level (same rules as [MQTT wildcards](/latest/mqtt-broker/protocol#wildcards)).

> [!NOTE]
>
> **Same topic, in order.** On one concrete topic the broker runs the action in publish order and gives that run the exact bytes of the message that fired it (`PAYLOAD AS BYTES`, `GET PROTO … IN PAYLOAD`). A slow action on that topic waits for earlier messages on the same topic instead of overlapping them. Messages on other topics still run at the same time.

### `ON CHANGE` — react only when the value changes

Use `ON CHANGE` for telemetry, status fields, or setpoints that are published often but only need logic when the reading actually changes. This reduces CPU load, database writes, and downstream noise.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessTemperatureOnChange
ON CHANGE "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "processed/" + {sensor_id} + "/temperature" WITH {temp}
```

**Key characteristics:**

* The **first** message on a given topic always runs the action (there is no previous value yet).
* Later messages run the action only if the **payload bytes** are not identical to the last message on that **exact** topic name.
* Example: `sensors/line1/temperature` and `sensors/line2/temperature` are tracked separately.
* Wildcard patterns work the same as `ON TOPIC`; change is evaluated per real topic, not per pattern.

> [!NOTE]
>
> **What counts as “changed”?** Comparison is on the **raw message body** (bytes), not on parsed numbers or JSON. `25` and `25.0` are different payloads. `{"temp":25}` and `{"temp": 25}` (different spacing) are different payloads. If you need semantic equality (for example, treat `25` and `25.0` as the same), handle that inside an `ON TOPIC` action with your own logic.

### Choosing between `ON TOPIC` and `ON CHANGE`

| Situation | Recommended trigger |
| - | - |
| Commands, events, “do something” signals | `ON TOPIC` |
| Alarms that must fire on every notification | `ON TOPIC` |
| High-frequency sensor values (temperature, level, status) | `ON CHANGE` |
| Writing to a database or historian only when value moves | `ON CHANGE` |
| Forwarding data only when it differs | `ON CHANGE` |
| Same pattern, but some actions need every message and others only on change | Use **both** (two actions on the same pattern) |

You can deploy two actions on the same topic pattern: one with `ON TOPIC` and one with `ON CHANGE`. The broker runs `ON TOPIC` every time and skips the `ON CHANGE` action when the payload is unchanged.

### Side-by-side example

Two devices publish temperature every second. Only `22.5` → `23.1` should trigger heavy processing.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION LogEveryReading
ON TOPIC "sensors/+/temperature" DO
    PUBLISH TOPIC "logs/all" WITH PAYLOAD
```

On value change only:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessWhenDifferent
ON CHANGE "sensors/+/temperature" DO
    SET "temp" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "analytics/updated" WITH {temp}
```

| Publish to | Payload | `LogEveryReading` | `ProcessWhenDifferent` |
| - | - | - | - |
| `sensors/a/temperature` | `22.5` | Runs | Runs (first value) |
| `sensors/a/temperature` | `22.5` | Runs | Skipped (unchanged) |
| `sensors/a/temperature` | `23.1` | Runs | Runs (changed) |

Inside the action body, **`PAYLOAD`** is the content of the message that fired the trigger, and **`TOPIC POSITION N`** is segment *N* of the actual topic (1-based), useful with `+`.

### Wildcard Patterns

LoT supports MQTT wildcards for flexible topic matching:

**Single-Level (+)**

The `+` wildcard matches exactly one topic level:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SensorRouter
ON TOPIC "sensors/+/temperature" DO
    // POSITION 1="sensors", POSITION 2=wildcard (sensor_id), POSITION 3="temperature"
    SET "sensor_id" WITH TOPIC POSITION 2
    PUBLISH TOPIC "processed/" + {sensor_id} + "/temp" WITH PAYLOAD
```

> [!TIP]
>
> **Matches:** `sensors/room1/temperature`, `sensors/room2/temperature`

> [!WARNING]
>
> **Does NOT match:** `sensors/building1/floor2/temperature` (too many levels)

**Multi-Level (+/+)**

Use multiple single-level wildcards for deeper hierarchies:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION FactoryMonitor
ON TOPIC "factory/+/+/status" DO
    // POSITION 1="factory", POSITION 2=line_id, POSITION 3=machine_id, POSITION 4="status"
    SET "line_id" WITH TOPIC POSITION 2
    SET "machine_id" WITH TOPIC POSITION 3
    
    PUBLISH TOPIC "monitoring/" + {line_id} + "/" + {machine_id} WITH PAYLOAD
```

> [!TIP]
>
> **Matches:** `factory/line1/machine1/status`, `factory/line2/press3/status`

> [!WARNING]
>
> **Does NOT match:** `factory/line1/status` (missing one level), `factory/status` (missing two levels)

***

## Initialization Triggers

Use `ON START` to execute logic exactly once when the broker starts **or when the action is first deployed on a live broker**. This is the right place to bootstrap a Unified Namespace (UNS) structure, publish retained default configurations, and log startup events.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION InitUNSRoot
ON START DO
    PUBLISH TOPIC "config/uns_root" WITH "factory/lisbon" RETAIN
    PUBLISH TOPIC "factory/info/name" WITH "Lisbon Plant" RETAIN
    PUBLISH TOPIC "factory/info/timezone" WITH "Europe/Lisbon" RETAIN
    PUBLISH TOPIC "system/log" WITH "UNS root initialised"
```

**Key characteristics:**

* Runs once when the broker starts, and again when you first deploy (or redeploy) the action while the broker is already up — you do not need a restart to seed bootstrap topics
* Cold-start behaviour is unchanged: every `ON START` action still runs once after the MQTT broker is ready. Deploying before the broker is ready defers until startup so the body is not double-run
* A failing `ON START` body is logged but does not fail the deploy
* Optional `RETAIN` on `PUBLISH TOPIC` sets the MQTT retain flag on the published message, so a new subscriber receives the last payload. Optional `QOS0`, `QOS1`, or `QOS2` select MQTT QoS; the default remains QoS 0. Omitting `RETAIN` keeps the historical non-retained behaviour. `RETAIN` and a QoS keyword can appear in either order
* `KEEP TOPIC` is different: it stores a value for `GET TOPIC` in the broker cache and does not set the MQTT retain flag. `KEEP` does not accept `RETAIN` (use `PUBLISH TOPIC ... RETAIN`)
* There is no `ON STOP` equivalent — `ON START` is the correct place for setup logic

> [!NOTE]
>
> Action `PUBLISH TOPIC` puts the payload on MQTT. It skips the **publish ACL** that applies to connected MQTT users — a restrictive rule on that topic does not stop the action from publishing, so bootstrap publishes from `ON START` (and other actions) are not silently dropped. Clients still need subscribe permission to receive those messages, and anything a client publishes itself remains fully subject to rules. `KEEP TOPIC` is different: it stores a value for `GET TOPIC` in the broker cache and does not set the MQTT retain flag.

***

## Client Lifecycle Triggers

Use **`ON CONNECT`**, **`ON DISCONNECT`**, and **`ON SUBSCRIBE`** when automation must react to MQTT session events instead of publishes. Typical uses include audit trails, connection dashboards, onboarding a UI client with `PUBLISH TOPIC ... RETAIN`, or tracking which topics clients subscribe to.

| Trigger | When the action runs |
| - | - |
| **`ON CONNECT DO`** | After a client passes authentication and the broker accepts the MQTT CONNECT packet |
| **`ON DISCONNECT DO`** | When the broker detects a client disconnection (clean, unclean, or session takeover) |
| **`ON SUBSCRIBE ["pattern"] DO`** | After the broker accepts a subscription (RBAC check passed); optional pattern limits which subscriptions fire the action |

> [!NOTE]
>
> If no action in the broker uses `ON CONNECT`, `ON DISCONNECT`, or `ON SUBSCRIBE`, the broker does not dispatch those lifecycle hooks — there is no overhead when the triggers are unused.

### `ON CONNECT DO`

Runs once after a client successfully authenticates and the broker accepts the MQTT CONNECT packet.

```lot wrap focus={2} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AuditConnect
ON CONNECT DO
    PUBLISH TOPIC "audit/connect/" + CLIENTID WITH USER + "@" + ENDPOINT
    KEEP TOPIC "sessions/" + CLIENTID + "/clean" WITH CLEANSESSION
```

**Key characteristics:**

* Fires for every successful client connection, including connectors and HUB clients.
* Session context variables (`CLIENTID`, `USER`, `ENDPOINT`, `CLEANSESSION`) reflect the connecting client.
* `USER IN GROUP`, `USER EQUALS`, and `USER HAS` evaluate against the session user, the same way they do for `ON TOPIC`.

### `ON DISCONNECT DO`

Runs when the broker detects a client disconnection — clean disconnect, unclean disconnect, or session takeover.

```lot wrap focus={2} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AuditDisconnect
ON DISCONNECT DO
    PUBLISH TOPIC "audit/disconnect/" + CLIENTID WITH DISCONNECTREASON
```

**Key characteristics:**

* `DISCONNECTREASON` carries the disconnect type or MQTT reason code for the session that ended.
* `CLIENTID`, `USER`, and `ENDPOINT` reflect the disconnecting session when available from the connect handshake.

### `ON SUBSCRIBE DO`

Runs after the broker accepts a subscription and RBAC allows it. Use a topic pattern to limit which subscriptions fire the action; omit the pattern to run on **every** allowed subscription.

```lot wrap focus={2} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TrackSensorSubscriptions
ON SUBSCRIBE "sensors/#" DO
    PUBLISH TOPIC "audit/subscriptions" WITH CLIENTID + " -> " + SUBSCRIBETOPIC + " qos=" + SUBSCRIBEQOS
```

Track every allowed subscription:

```lot wrap focus={2} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TrackAllSubscriptions
ON SUBSCRIBE DO
    KEEP TOPIC "audit/last/subscribe" WITH SUBSCRIBETOPIC
```

**Key characteristics:**

* Supports the same MQTT wildcards as `ON TOPIC`: `+` (single level) and `#` (multi-level).
* `SUBSCRIBETOPIC` is the topic filter the client subscribed to; `SUBSCRIBEQOS` is the requested QoS (`0`, `1`, or `2`).
* Lifecycle subscribe dispatch runs for all allowed subscriptions, including Visu and system topics, unless you filter them in the action body.

### Session context variables

Available inside lifecycle-triggered actions (and still available on `ON TOPIC` / `ON CHANGE` for the **publisher**):

| Variable | `ON CONNECT` | `ON DISCONNECT` | `ON SUBSCRIBE` | `ON TOPIC` / `ON CHANGE` |
| - | - | - | - | - |
| `CLIENTID` | Connecting client | Disconnecting client | Subscribing client | Publishing client |
| `USER` | Authenticated username | Session username | Session username | Publisher username |
| `ENDPOINT` | Client address (`ip:port`) | Last known address | Address from connect | Empty |
| `CLEANSESSION` | `"true"` / `"false"` | Value from connect | Value from connect | Empty |
| `DISCONNECTREASON` | Empty | Disconnect type / MQTT reason | Empty | Empty |
| `SUBSCRIBETOPIC` | Empty | Empty | Subscribed topic filter | Empty |
| `SUBSCRIBEQOS` | `-1` | `-1` | QoS level (`0`, `1`, or `2`) | `-1` |

### Not the same as Visu `ON CHANGE`

In **dashboard / Visu (LoTV)** panels, `ON CHANGE DO` on a slider or text field is a **UI event** in the browser (user edits a control). That is separate from broker **`ON CHANGE "topic" DO`**, which reacts to **MQTT publishes** inside the broker.

Lifecycle triggers (`ON CONNECT`, `ON DISCONNECT`, `ON SUBSCRIBE`) are also broker-side only. The broker still publishes `$SYS/Coreflux/Comms/Logins` on connect for observability, but LoT lifecycle actions give you programmatic automation with session context variables.

| Context | Syntax | What fires it |
| - | - | - |
| Broker LoT action | `ON CHANGE "sensors/temp" DO` | MQTT message with changed payload |
| Broker LoT action | `ON CONNECT DO` | MQTT client connects |
| Broker LoT action | `ON DISCONNECT DO` | MQTT client disconnects |
| Broker LoT action | `ON SUBSCRIBE "pattern" DO` | Client subscribes to a matching filter |
| Visu component | `ON CHANGE DO PUBLISH …` | User changing a control in the UI |

***

## Callable Actions

Actions **without** a trigger clause (`ON TOPIC`, `ON EVERY`, `ON START`, `ON CONNECT`, and so on) are **callable**—they run only when another ACTION calls them with `CALL ACTION`.

Use callables for reusable logic (conversions, validation, shared math) that several trigger-based Actions need. They accept typed `INPUT` parameters and can `RETURN` one or more `OUTPUT` values.

> [!NOTE]
>
> **Full guide:** [Callable ACTIONs](./callable-actions)—reusable logic, on-demand scripts, and `CALL ACTION` syntax.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CalculateAverage
INPUT value1 AS DOUBLE
INPUT value2 AS DOUBLE
DO
    SET "avg" WITH (({value1} + {value2}) / 2)
RETURN
    OUTPUT avg

DEFINE ACTION ProcessSensorPair
ON TOPIC "sensors/pair/data" DO
    SET "temp1" WITH (GET JSON "sensor1" IN PAYLOAD AS DOUBLE)
    SET "temp2" WITH (GET JSON "sensor2" IN PAYLOAD AS DOUBLE)
    CALL ACTION CalculateAverage
        WITH value1 = {temp1}, value2 = {temp2}
        RETURN result
    PUBLISH TOPIC "sensors/average" WITH {result}
```

***

## Comparing Trigger Types

| Aspect | Time-Based | Topic-Based | ON START | Client lifecycle | Callable |
| - | - | - | - | - | - |
| **Trigger** | Clock interval or schedule | MQTT message | Broker startup or first deploy | Connect, disconnect, subscribe | Manual command |
| **Frequency** | Interval, daily, weekly, or once | Event-driven | Once | Per session event | On-demand |
| **Payload Access** | No | Yes (`PAYLOAD`) | No | Session context (`CLIENTID`, `USER`, …) | Via parameters |
| **Best For** | Monitoring, reporting | Data processing | Initialization | Audit, session automation | Reusable utilities |

***

## Next Steps

> **[Callable ACTIONs](./callable-actions)**
>
> Reusable logic, on-demand scripts, and `CALL ACTION`.

> **[Operations](./operations)**
>
> Learn about SET, GET, PUBLISH, and conditional logic.


# ACTION Operations Reference
Source: https://docs.coreflux.org/latest/lot-language/actions/operations

Complete reference for LoT operations: variables, arithmetic, strings, RANDOM, transformations, and control flow

## Overview

Complete reference for all LoT operations available within actions. These operations allow you to manipulate variables, perform calculations, transform strings, read and write MQTT topics, and implement conditional logic.

> [!TIP]
>
> **Quick Reference:** Use the sidebar to jump to specific operations.

***

## Variable Operations

> [!NOTE]
>
> SET, GET TOPIC, GET JSON, and GET PROTO are the core operations for working with data in actions. They allow you to store values, read from MQTT topics, extract fields from JSON payloads, and decode protobuf fields.

### SET

Creates or assigns a value to an internal variable:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "variable_name" WITH <value>
```

Variables exist only during action execution and are referenced using `{variable_name}`.

**Static Value**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "threshold" WITH 100
SET "status" WITH "active"
SET "enabled" WITH TRUE
```

**From Topic**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "current_temp" WITH (GET TOPIC "sensors/temperature")
// For topic "sensors/temp001/data": POSITION 2 gets the sensor ID
SET "sensor_id" WITH TOPIC POSITION 2
```

**Calculated**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "total" WITH (GET TOPIC "count/a" + GET TOPIC "count/b")
SET "average" WITH ({sum} / {count})
```

> [!NOTE]
>
> Variable names must be enclosed in double quotes when using SET, but referenced with curly braces: `SET "myVar" WITH 10` then use `{myVar}`.

### GET TOPIC

Retrieves the last known value from a topic. If the topic has no value, the broker returns a default based on the requested type.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET TOPIC "topic/path"
GET TOPIC "topic/path" AS <TYPE>
```

#### Default Values for Missing Topics

| Type | Default Value |
| - | - |
| `STRING` | `""` (empty string) |
| `DOUBLE` | `0.0` |
| `INT` | `0` |
| `BOOL` | `FALSE` |

#### Type Casting

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET TOPIC "sensors/temp" AS DOUBLE
GET TOPIC "config/count" AS INT
GET TOPIC "flags/enabled" AS BOOL
```

#### Wildcard Inheritance

When an action is triggered by a wildcard topic pattern, GET TOPIC inherits the matched wildcard values:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessWithContext
ON TOPIC "sensors/+/temperature" DO
    // If triggered by "sensors/temp001/temperature"
    // The + wildcard matches "temp001"
    
    // This GET TOPIC uses the same wildcard value:
    SET "humidity" WITH (GET TOPIC "sensors/+/humidity" AS DOUBLE)
    // Reads from "sensors/temp001/humidity"
```

#### Example Usage

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Read and process
SET "last_temp" WITH (GET TOPIC "sensors/temperature" AS DOUBLE)

// Check before using (EMPTY check)
IF GET TOPIC "config/threshold" == EMPTY THEN
    SET "threshold" WITH 80
ELSE
    SET "threshold" WITH (GET TOPIC "config/threshold" AS DOUBLE)

// Combine multiple topic values
SET "total" WITH (GET TOPIC "counters/a" AS INT + GET TOPIC "counters/b" AS INT)
```

### GET JSON

Extracts fields from JSON payloads with support for nested paths and arrays.

> [!NOTE]
>
> For narrative patterns, missing-field workflows, and end-to-end `PUBLISH MODEL` examples, see [Working with JSON](/latest/lot-language/usage-patterns/working-with-json).

#### Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET JSON "field_name" IN PAYLOAD AS <TYPE>
```

#### Supported Types

| Type | Use For | Example |
| - | - | - |
| `STRING` | Text values | `GET JSON "name" IN PAYLOAD AS STRING` |
| `DOUBLE` | Decimal numbers | `GET JSON "temperature" IN PAYLOAD AS DOUBLE` |
| `INT` | Whole numbers | `GET JSON "count" IN PAYLOAD AS INT` |
| `BOOL` | True/false values | `GET JSON "enabled" IN PAYLOAD AS BOOL` |

#### Nested Path Extraction

Use dot notation to access nested objects and bracket notation for arrays:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Nested object access
SET "nested" WITH (GET JSON "data.sensors.temperature" IN PAYLOAD AS DOUBLE)
SET "deep" WITH (GET JSON "metadata.config.threshold" IN PAYLOAD AS INT)

// Array access (0-indexed)
SET "first_reading" WITH (GET JSON "readings[0].value" IN PAYLOAD AS DOUBLE)
SET "second_sensor" WITH (GET JSON "data.sensors[1].id" IN PAYLOAD AS STRING)
```

For a payload like:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "data": {
    "sensors": [
      { "id": "temp001", "value": 23.5 },
      { "id": "temp002", "value": 24.1 }
    ]
  },
  "metadata": { "config": { "threshold": 80 } }
}
```

#### Error Handling

If a field doesn't exist, the result depends on the requested type:

| Type | Missing Field Result |
| - | - |
| `STRING` | `""` (empty string) |
| `DOUBLE` | `0.0` |
| `INT` | `0` |
| `BOOL` | `FALSE` |

Use EMPTY check for conditional handling:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "value" WITH (GET JSON "optional_field" IN PAYLOAD AS DOUBLE)
IF {value} == EMPTY THEN
    SET "value" WITH 100  // Default fallback
```

#### Complete Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessComplexJSON
ON TOPIC "sensors/data" DO
    // Top-level fields
    SET "sensor_id" WITH (GET JSON "id" IN PAYLOAD AS STRING)
    SET "timestamp" WITH (GET JSON "timestamp" IN PAYLOAD AS STRING)
    
    // Nested fields
    SET "temp" WITH (GET JSON "readings.temperature" IN PAYLOAD AS DOUBLE)
    SET "humidity" WITH (GET JSON "readings.humidity" IN PAYLOAD AS DOUBLE)
    
    // Array access
    SET "latest" WITH (GET JSON "history[0].value" IN PAYLOAD AS DOUBLE)
    
    PUBLISH TOPIC "processed/" + {sensor_id} + "/temp" WITH {temp}
    PUBLISH TOPIC "processed/" + {sensor_id} + "/humidity" WITH {humidity}
```

### GET PROTO

Extracts fields from **binary protobuf** MQTT payloads. `GET PROTOBUF` is the same verb. You need a matching `DEFINE MODEL` with `WITH FORMAT PROTOBUF` (or `BOTH`) and `PROTO_TAG` values that follow the vendor `.proto`. Full models, type mapping, and pitfalls: [Protobuf Models](/latest/lot-language/models/protobuf).

#### Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET PROTO "field_name" IN PAYLOAD AS <TYPE> USING MODEL "ModelName"
```

| Source | Bytes come from |
| - | - |
| `IN PAYLOAD` | The MQTT payload that fired the Action |
| `IN GET TOPIC "…"` | Last payload stored for that topic |
| `IN` a LoT variable | A Base64 string in that variable |

`USING MODEL` names the top-level message, even on a nested dotted path. Supported `AS` types: `INT`, `DOUBLE`, `FLOAT` (alias `SINGLE`), `STRING`, `BOOL`, `BYTES`.

A missing or mismatched field returns `null` (not a type default). That usually means a wire-type mismatch, for example `ADD DOUBLE` on a proto `float`.

Declare the parent message (unused arms stay as `ADD OBJECT` so wire numbers do not shift):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL DeviceCommand WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "command_type" PROTO_TAG 1
    ADD OBJECT "header" PROTO_TAG 2
```

Then read a field from the triggering payload:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION OnPlcCommand
ON TOPIC "plant/+/+/command" DO
    SET "cmd" WITH (GET PROTO "command_type" IN PAYLOAD AS INT USING MODEL "DeviceCommand")
    KEEP TOPIC "plant/pending_command" WITH {cmd}
```

A dotted path reads a nested message. Declare that arm with `ADD MODEL`, and keep `USING MODEL` on the top-level message:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ReadSnapshot WITH FORMAT PROTOBUF COLLAPSED
    ADD STRING "tag_group" PROTO_TAG 1
    ADD INT "max_age_ms" PROTO_TAG 2

DEFINE MODEL DeviceCommand WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "command_type" PROTO_TAG 1
    ADD MODEL ReadSnapshot "read_snapshot" PROTO_TAG 6
```

```lot wrap focus={4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION OnPlcCommand
ON TOPIC "plant/+/+/command" DO
    SET "cmd" WITH (GET PROTO "command_type" IN PAYLOAD AS INT USING MODEL "DeviceCommand")
    SET "tag_group" WITH (GET PROTO "read_snapshot.tag_group" IN PAYLOAD AS STRING USING MODEL "DeviceCommand")
    KEEP TOPIC "plant/pending_group" WITH {tag_group}
```

### GET MODEL

`GET MODEL` reads one record from a database connector and returns it shaped as a model: a JSON object with that model's fields.

#### Basic Syntax

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET MODEL "<model_name>" FROM "<connector_name>" [WHERE <field> <operator> <value> [AND …]]
```

* The query reads the table, collection, or index with the **same name as the model**, not the `STORE IN` table.
* `WHERE` (or `WHEN`) filters on columns. Operators are `EQUALS`, `==`, `!=`, `>`, `<`, `>=`, and `<=`. Join conditions with `AND` in any mix of text and numeric comparisons. Text values are single-quoted, and a literal `'` is written `''` (the name `O'Brien` is `'O''Brien'`). A `{var}` value is resolved when the action runs. `OR` is not supported and is a syntax error.
* The first matching record is returned. A model field the record doesn't have gets its type's default (`0`, `0.0`, `false`, or `""`).
* With no match, an unknown model, or a query error, the result is an empty object `{}`, and the error goes to the broker log.

Supported connectors: PostgreSQL, MySQL, MariaDB, SQL Server, MongoDB, OpenSearch, `FILE_STORAGE`, and `REST_API`.

#### Example Usage

Read the press row when its id, state, and temperature all match. `{machine}` is filled in when the action runs.

```lot wrap focus={8-11} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MachineState
    ADD STRING "machine_id"
    ADD STRING "state"
    ADD DOUBLE "temperature"

DEFINE ACTION ReportPress1
ON TOPIC "plant/press1/report/request" DO
    SET "machine" WITH "press1"
    SET "press" WITH GET MODEL "MachineState" FROM "PlantDB" WHERE machine_id EQUALS {machine} AND state EQUALS 'running' AND temperature > 80
    PUBLISH TOPIC "plant/press1/report" WITH {press}
    PUBLISH TOPIC "plant/press1/hot" WITH GET MODEL "MachineState" FROM "PlantDB" WHERE temperature > 80
```

`GET MODEL` runs inside the action and waits for the database. Keep it off high-rate triggers. In a cluster, a connector that runs only on its owner node, such as `FILE_STORAGE`, answers there only: on another node the call fails and names the owner.

***

## Environment Variables & Secrets

> [!NOTE]
>
> **Version Requirement:** `GET ENV`, `GET SECRET`, `KEEP ENV`, `KEEP SECRET`, `DELETE ENV`, and `DELETE SECRET` are available from **Coreflux Broker v1.9.3** and above.

LoT Actions can read, write, and delete environment variables and encrypted secrets at runtime. Environment variables store non-sensitive configuration (hostnames, ports, URLs). Secrets store sensitive credentials encrypted with AES-256-GCM.

> [!TIP]
>
> Use environment variables for configuration that can safely appear in logs (hostnames, ports, feature flags). Use secrets for anything sensitive (passwords, API keys, tokens).

### GET ENV

Reads an environment variable. The broker checks the managed `.env` file first, then falls back to process, user, and machine environment variables. Returns an empty string if not found.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET ENV "NAME"
```

#### Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Read connection settings
SET "host" WITH (GET ENV "DB_HOST")
SET "port" WITH (GET ENV "DB_PORT")
SET "apiUrl" WITH (GET ENV "API_BASE_URL")

-- Use in conditional logic
IF GET ENV "FEATURE_FLAG" == "enabled" THEN
    PUBLISH TOPIC "features/new" WITH "active"
```

### KEEP ENV

Persists a new environment variable to the `.env` file on disk:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP ENV "NAME" WITH <value>
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Save a timestamp
KEEP ENV "LAST_RUN" WITH TIMESTAMP "UTC"

-- Save a computed value
KEEP ENV "DEVICE_COUNT" WITH {count}
```

### DELETE ENV

Removes an environment variable from the managed `.env` file:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DELETE ENV "NAME"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DELETE ENV "OLD_CONFIG"
```

### GET SECRET

Reads an encrypted secret from `secrets.json`, decrypting it at runtime. Returns an empty string if the secret does not exist.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET SECRET "NAME"
```

#### Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Read credentials
SET "dbPass" WITH (GET SECRET "DB_PASSWORD")
SET "apiKey" WITH (GET SECRET "API_KEY")

-- Use in conditional logic
IF GET SECRET "LICENSE_KEY" == EMPTY THEN
    PUBLISH TOPIC "system/warnings" WITH "No license key configured"
```

### KEEP SECRET

Encrypts and persists a new secret to `secrets.json`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP SECRET "NAME" WITH "value"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP SECRET "API_KEY" WITH "sk-abc123"
```

### DELETE SECRET

Removes a secret from `secrets.json`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DELETE SECRET "NAME"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DELETE SECRET "OLD_API_KEY"
```

### Complete Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SecureDataForwarder
ON TOPIC "sensors/+/data" DO
    SET "sensor_id" WITH TOPIC POSITION 2

    -- Read configuration from environment
    SET "apiUrl" WITH (GET ENV "API_BASE_URL")
    SET "region" WITH (GET ENV "DEPLOY_REGION")

    -- Read credentials from secrets
    SET "apiKey" WITH (GET SECRET "API_KEY")

    IF {apiUrl} == EMPTY THEN
        PUBLISH TOPIC "system/errors" WITH "API_BASE_URL not configured"
    ELSE
        -- Forward sensor data with region tag
        PUBLISH TOPIC "forwarded/" + {region} + "/" + {sensor_id} WITH PAYLOAD
        PUBLISH TOPIC "forwarded/" + {sensor_id} + "/timestamp" WITH TIMESTAMP "UTC"

    -- Track last forwarded sensor
    KEEP ENV "LAST_FORWARDED_SENSOR" WITH {sensor_id}
```

> [!NOTE]
>
> For full details on environment variable resolution order, encryption key management, and deployment configuration, see [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env).

***

## Arithmetic Operators

LoT supports standard arithmetic operations that work with numeric types (INT, DOUBLE) and can be combined with GET TOPIC, PAYLOAD, and variables.

### Supported Operators

| Operator | Symbol | Description |
| - | - | - |
| Addition | `+` | Adds two values together |
| Subtraction | `-` | Subtracts right value from left |
| Multiplication | `*` | Multiplies two values |
| Division | `/` | Divides left value by right |
| Modulo | `%` | Returns remainder of division |
| Unary Negative | `-` | Negates a value |

### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
<expression> + <expression>
<expression> - <expression>
<expression> * <expression>
<expression> / <expression>
<expression> % <expression>
-<expression>
```

### Basic Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Simple arithmetic with literals
SET "sum" WITH (10 + 5)
SET "difference" WITH (100 - 25)
SET "product" WITH (6 * 7)
SET "quotient" WITH (100 / 4)
SET "remainder" WITH (17 % 5)
SET "negative" WITH (-42)
```

### Using with Variables

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "a" WITH 100
SET "b" WITH 25
SET "result" WITH ({a} + {b})
SET "average" WITH (({a} + {b}) / 2)
```

### Using with GET TOPIC

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Add values from two different topics
SET "total" WITH (GET TOPIC "sensors/count/a" AS INT + GET TOPIC "sensors/count/b" AS INT)

// Calculate percentage
SET "percentage" WITH (GET TOPIC "current/value" AS DOUBLE / GET TOPIC "max/value" AS DOUBLE * 100)

// Temperature conversion (Celsius to Fahrenheit)
SET "fahrenheit" WITH (GET TOPIC "sensors/temp/celsius" AS DOUBLE * 9 / 5 + 32)
```

### Using with PAYLOAD

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CalculateWithPayload
ON TOPIC "input/value" DO
    SET "doubled" WITH (PAYLOAD AS DOUBLE * 2)
    SET "incremented" WITH (PAYLOAD AS INT + 1)
    PUBLISH TOPIC "output/doubled" WITH {doubled}
```

### Operator Precedence

Operations follow standard mathematical precedence:

1. Parentheses `()` - highest priority
2. Unary negation `-`
3. Multiplication `*`, Division `/`, Modulo `%`
4. Addition `+`, Subtraction `-`

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Without parentheses: 2 + 3 * 4 = 14 (multiplication first)
SET "result1" WITH (2 + 3 * 4)

// With parentheses: (2 + 3) * 4 = 20
SET "result2" WITH ((2 + 3) * 4)
```

### Complete Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureProcessor
ON TOPIC "sensors/+/temperature" DO
    // POSITION 1="sensors", POSITION 2=sensor_id (wildcard), POSITION 3="temperature"
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "celsius" WITH PAYLOAD AS DOUBLE
    
    // Convert to Fahrenheit
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
    
    // Calculate deviation from setpoint
    SET "setpoint" WITH (GET TOPIC "config/setpoint" AS DOUBLE)
    SET "deviation" WITH ({celsius} - {setpoint})
    SET "deviation_percent" WITH ({deviation} / {setpoint} * 100)
    
    PUBLISH TOPIC "processed/" + {sensor_id} + "/fahrenheit" WITH {fahrenheit}
    PUBLISH TOPIC "processed/" + {sensor_id} + "/deviation" WITH {deviation_percent}
```

***

## String Concatenation

The `+` operator concatenates strings, allowing dynamic construction of topics, messages, and values.

### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
<string_expression> + <string_expression>
```

### Basic Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "greeting" WITH ("Hello, " + "World!")
SET "fullname" WITH ({firstname} + " " + {lastname})
```

### Dynamic Topic Construction

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Build topic paths dynamically
PUBLISH TOPIC "devices/" + {device_id} + "/status" WITH "online"
PUBLISH TOPIC "sensors/" + {sensor_type} + "/" + {location} + "/reading" WITH {value}

// Using with KEEP
KEEP TOPIC "cache/" + {sensor_id} + "/last_reading" WITH PAYLOAD
```

### Combining Strings with Other Types

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// String + Number (number is converted to string)
SET "message" WITH ("Temperature is: " + {temp})
PUBLISH TOPIC "alerts/temperature" WITH ("High temp: " + {celsius} + "°C")
```

### Complete Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DynamicPublisher
ON TOPIC "input/+/+/data" DO
    // POSITION 1="input", POSITION 2=region, POSITION 3=device, POSITION 4="data"
    SET "region" WITH TOPIC POSITION 2
    SET "device" WITH TOPIC POSITION 3
    SET "timestamp" WITH TIMESTAMP "UTC"
    
    // Build dynamic output topic
    SET "output_topic" WITH ("processed/" + {region} + "/" + {device})
    
    // Build descriptive message
    SET "message" WITH ("Device " + {device} + " in " + {region} + " reported at " + {timestamp})
    
    PUBLISH TOPIC {output_topic} WITH {message}
```

***

## RANDOM Function

Generates random values of various types including numeric ranges and unique identifiers.

### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Random integer in range (inclusive)
RANDOM BETWEEN <min> AND <max>
RANDOM INT BETWEEN <min> AND <max>

// Random double/float in range
RANDOM DOUBLE BETWEEN <min> AND <max>

// Unique identifiers
RANDOM UUID
RANDOM GUID
RANDOM ULID
```

### Random Integers

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Random integer between 1 and 100
SET "dice_roll" WITH (RANDOM BETWEEN 1 AND 6)
SET "random_percent" WITH (RANDOM INT BETWEEN 0 AND 100)

// Using expressions for range
SET "random_in_range" WITH (RANDOM INT BETWEEN {min_value} AND {max_value})
```

### Random Doubles

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Random double between 0.0 and 1.0
SET "probability" WITH (RANDOM DOUBLE BETWEEN 0.0 AND 1.0)

// Random temperature for simulation
SET "simulated_temp" WITH (RANDOM DOUBLE BETWEEN 18.5 AND 25.5)
```

### Unique Identifiers

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Generate UUID (e.g., "550e8400-e29b-41d4-a716-446655440000")
SET "transaction_id" WITH (RANDOM UUID)

// Generate GUID (same format as UUID)
SET "session_id" WITH (RANDOM GUID)

// Generate ULID (e.g., "01ARZ3NDEKTSV4RRFFQ69G5FAV")
// ULIDs are sortable by time
SET "event_id" WITH (RANDOM ULID)
```

### Use Cases

**Simulation**

Generate test data for sensors:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SimulateSensor
ON EVERY 5 SECONDS DO
    SET "temperature" WITH (RANDOM DOUBLE BETWEEN 20.0 AND 30.0)
    SET "humidity" WITH (RANDOM INT BETWEEN 40 AND 80)
    SET "pressure" WITH (RANDOM DOUBLE BETWEEN 1000.0 AND 1020.0)
    
    PUBLISH TOPIC "simulated/sensor/temperature" WITH {temperature}
    PUBLISH TOPIC "simulated/sensor/humidity" WITH {humidity}
    PUBLISH TOPIC "simulated/sensor/pressure" WITH {pressure}
```

**Unique IDs**

Generate unique record identifiers:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CreateRecord
ON TOPIC "records/create" DO
    SET "record_id" WITH (RANDOM UUID)
    SET "timestamp" WITH TIMESTAMP "UTC"
    
    PUBLISH TOPIC "records/" + {record_id} WITH PAYLOAD
    PUBLISH TOPIC "records/index/latest" WITH {record_id}
```

**Load Balancing**

Distribute work across workers:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION RandomRouter
ON TOPIC "incoming/requests" DO
    SET "worker" WITH (RANDOM INT BETWEEN 1 AND 4)
    PUBLISH TOPIC "workers/" + {worker} + "/queue" WITH PAYLOAD
```

***

## String Transformations

LoT provides string transformation operations for filtering, replacing, and parsing text data.

### FILTER

Extracts content from a string using a regular expression pattern.

#### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
FILTER <source> USING REGEX "<pattern>"
```

#### Supported Sources

* `PAYLOAD` - The incoming message payload
* `GET TOPIC "path"` - Value from an MQTT topic
* `{variable}` - A previously set variable
* `"string literal"` - A hardcoded string

#### Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Extract all digits from payload
SET "numbers" WITH FILTER PAYLOAD USING REGEX "[0-9]+"

// Extract from a topic value
SET "extracted" WITH FILTER (GET TOPIC "data/raw") USING REGEX "[a-zA-Z]+"

// Extract email pattern
SET "email" WITH FILTER PAYLOAD USING REGEX "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"

// Extract numbers from mixed content
SET "value" WITH FILTER "Temperature: 23.5°C" USING REGEX "[0-9]+\\.?[0-9]*"
```

#### Common Regex Patterns

| Pattern | Description | Example Match |
| - | - | - |
| `[0-9]+` | One or more digits | "123", "4567" |
| `[a-zA-Z]+` | One or more letters | "Hello", "World" |
| `[0-9]+\\.?[0-9]*` | Decimal numbers | "23.5", "100" |
| `[^\\s]+` | Non-whitespace | "word" |
| `\\w+` | Word characters | "test\_123" |

### REPLACE

Replaces occurrences of a pattern with a new value.

#### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
REPLACE "<find>" WITH "<replacement>" IN <source>
```

#### Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Replace in payload
SET "cleaned" WITH REPLACE "old" WITH "new" IN PAYLOAD

// Replace in topic value
SET "modified" WITH REPLACE "error" WITH "warning" IN (GET TOPIC "logs/latest")

// Replace in variable
SET "formatted" WITH REPLACE " " WITH "_" IN {sensor_name}

// Remove characters by replacing with empty string
SET "digits_only" WITH REPLACE "[^0-9]" WITH "" IN {mixed_content}
```

#### Multiple Replacements

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "step1" WITH REPLACE "," WITH ";" IN PAYLOAD
SET "step2" WITH REPLACE " " WITH "_" IN {step1}
SET "final" WITH REPLACE "'" WITH "" IN {step2}
```

### SPLIT CSV

Parses CSV (Comma-Separated Values) data from the payload into a structured format.

#### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SPLIT PAYLOAD CSV [SEPARATOR "<char>"] [HEADERS PRESENT|NONE]
```

#### Parameters

| Parameter | Description | Default |
| - | - | - |
| `SEPARATOR` | The delimiter character | `,` (comma) |
| `HEADERS PRESENT` | First row contains column names | - |
| `HEADERS NONE` | No header row | - |

#### Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessCSVData
ON TOPIC "import/csv" DO
    // Payload: "name,value,unit\nTemperature,23.5,C\nHumidity,65,percent"
    SET "parsed" WITH SPLIT PAYLOAD CSV SEPARATOR "," HEADERS PRESENT
    
    PUBLISH TOPIC "import/parsed" WITH {parsed}
```

> [!NOTE]
>
> SPLIT CSV currently only supports PAYLOAD as input. Support for GET TOPIC and variables is planned for future releases.

***

## Topic Operations

### PUBLISH vs KEEP — When to Use Which

| Operation | MQTT retain | Typical use |
| - | - | - |
| `PUBLISH TOPIC` | Only when you add `RETAIN` | Current subscribers, connectors, dashboards, and external systems |
| `KEEP TOPIC` | Never | Broker-internal cache for `GET TOPIC` — not an MQTT publish |

Use `KEEP TOPIC` for inter-action state (counters, mode flags, last-known values). Use `PUBLISH TOPIC` when connectors, UIs, or other subscribers must react to the message. Use `PUBLISH TOPIC ... RETAIN` when new subscribers must receive the last payload.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP TOPIC "state/mode" WITH "running"
KEEP TOPIC "state/lastTemp" WITH {temp}
SET "mode" WITH (GET TOPIC "state/mode" AS STRING)

PUBLISH TOPIC "sensors/data" WITH {temp}
PUBLISH TOPIC "alerts/zone1" WITH "CRITICAL"
```

> [!WARNING]
>
> Do **not** use `KEEP TOPIC` to drive connector events — that path is unreliable. Use `PUBLISH TOPIC` when a connector or external consumer must react to the message.

### PUBLISH TOPIC

Sends a message to an MQTT topic. Current subscribers receive it immediately; the message can trigger other actions or connectors listening on that topic.

Optional `RETAIN` sets the MQTT retain flag on the published message (the same keyword as on `DEFINE MODEL`). Optional `QOS0`, `QOS1`, or `QOS2` select MQTT QoS; the default remains QoS 0. Omitting `RETAIN` keeps the historical non-retained behaviour. `RETAIN` and a QoS keyword can appear in either order (`RETAIN QOS1` or `QOS1 RETAIN`).

`KEEP TOPIC` is different: it stores a value for `GET TOPIC` in the broker cache and does **not** set the MQTT retain flag. Use `PUBLISH TOPIC ... RETAIN` when new subscribers must receive the last payload. `KEEP` does not accept `RETAIN`.

Several `PUBLISH TOPIC` or `KEEP TOPIC` lines to the same topic in one run each go out, in the order the action wrote them, with that line's own retain, QoS, and keep setting. A later `GET TOPIC` in the same run still reads the value just written. In a cluster, only the last `KEEP` of each topic is replicated.

#### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
PUBLISH TOPIC "<topic>" WITH <expression> [RETAIN] [QOS0|QOS1|QOS2]
```

**Retain**

Store the last status so a new subscriber receives the last payload:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PublishOnline
ON START DO
    PUBLISH TOPIC "status/last" WITH "online" RETAIN
```

**Retain and QoS 1**

Set the MQTT retain flag and publish at QoS 1:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PublishOnlineQos1
ON START DO
    PUBLISH TOPIC "status/last" WITH "online" RETAIN QOS1
```

**QoS only**

Choose QoS without retaining the message. Omit the QoS keyword and the publish stays QoS 0:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PublishOnlineQos2
ON START DO
    PUBLISH TOPIC "status/last" WITH "online" QOS2
```

#### Value Types

You can publish various value types:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// String
PUBLISH TOPIC "system/status" WITH "online"

// Number
PUBLISH TOPIC "sensors/reading" WITH 23.5

// Variable
PUBLISH TOPIC "output/value" WITH {calculated_result}

// Payload passthrough (string path — may corrupt non-UTF-8 data)
PUBLISH TOPIC "forwarded/data" WITH PAYLOAD

// Timestamp
PUBLISH TOPIC "events/timestamp" WITH TIMESTAMP "UTC"
```

#### Binary passthrough — `PAYLOAD AS BYTES`

Use `AS BYTES` when the incoming MQTT payload must be forwarded, or stored with `KEEP TOPIC`, bit-for-bit — for example protobuf messages, Modbus frames, or image chunks. Untyped `WITH PAYLOAD` still uses the string publish path and may corrupt non-UTF-8 data. To **decode or encode** protobuf fields rather than forward the blob, use [Protobuf Models](/latest/lot-language/models/protobuf) (`GET PROTO` / `PUBLISH MODEL`). To hand those bytes to an external gRPC service, publish them on the source topic of a [gRPC connector](/latest/lot-language/routes/streaming/grpc) (`TYPE GRPC`). There is no `CALL GRPC`.

```lot wrap focus={3} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ForwardBinary
ON TOPIC "binary/in" DO
    PUBLISH TOPIC "binary/out" WITH PAYLOAD AS BYTES
```

`KEEP TOPIC` and `SET` accept the same binary form, so you can store raw frames for later reads with `GET TOPIC`:

```lot wrap focus={3-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION KeepBinaryState
ON TOPIC "binary/in" DO
    KEEP TOPIC "state/raw" WITH PAYLOAD AS BYTES
    SET "frame" WITH PAYLOAD AS BYTES
```

> [!WARNING]
>
> **Binary path limitations**
>
> * Do **not** chain string transforms (`TRIM`, `FILTER`, `REPLACE`, `SPLIT`) after `PAYLOAD AS BYTES` on publish or keep — the parser rejects that combination.
> * Empty payloads are not published or stored on the binary path.

> [!WARNING]
>
> **Cannot Use Inline JSON Objects**
>
> `PUBLISH TOPIC` does **not** support inline JSON object literals. This will NOT work:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // ❌ WRONG - This does not work
> PUBLISH TOPIC "output/data" WITH {"temperature": 23.5, "humidity": 65}
> ```
>
> **Why?** `PUBLISH TOPIC` is designed for simple scalar values (strings, numbers, timestamps, variables). It doesn't have the type system or schema validation needed for structured JSON data.
>
> **Solution:** For structured JSON output, use [Models](/latest/lot-language/models/overview) with `PUBLISH MODEL`:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // ✅ CORRECT - Define a model and publish it
> DEFINE MODEL SensorData COLLAPSED
>     ADD DOUBLE "temperature"
>     ADD DOUBLE "humidity"
>
> DEFINE ACTION PublishStructuredData
> ON TOPIC "sensors/input" DO
>     PUBLISH MODEL SensorData TO "output/data" WITH
>         temperature = 23.5
>         humidity = 65
> ```
>
> Models provide type safety, schema validation, and proper JSON serialization. See [Publishing Models](/latest/lot-language/models/publish-model) for complete guidance.

#### Dynamic Topics

Build topic paths dynamically using string concatenation:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
PUBLISH TOPIC "devices/" + {device_id} + "/status" WITH "active"
PUBLISH TOPIC "sensors/" + {sensor_type} + "/" + {location} + "/reading" WITH {value}
```

#### Multiple Publishes

Actions can publish to multiple topics:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION MultiPublish
ON TOPIC "input/data" DO
    PUBLISH TOPIC "output/raw" WITH PAYLOAD
    PUBLISH TOPIC "output/timestamp" WITH TIMESTAMP "UTC"
    PUBLISH TOPIC "output/source" WITH "sensor_001"
```

> [!TIP]
>
> **Triggering Other Actions:** When you publish to a topic, any action with `ON TOPIC` matching that path will execute. This enables chaining actions together for complex workflows.

### KEEP TOPIC

Stores a value for `GET TOPIC` in the broker cache. Unlike `SET` (which exists only during one execution), a `KEEP` value stays available to later runs on this broker. It is a broker-internal cache and never sets the MQTT retain flag. `KEEP` does not accept `RETAIN` (use `PUBLISH TOPIC ... RETAIN`).

> [!WARNING]
>
> `KEEP TOPIC` does **not** publish to MQTT. The value stays inside the broker: subscribers, MQTT clients, the HUB Data Viewer, dashboards and connectors never receive it. Only `GET TOPIC` can read it. Use `PUBLISH TOPIC` (with `RETAIN` if new subscribers need the last value) whenever the value must be visible.

#### When to Use KEEP

| Use Case | Example |
| - | - |
| Cache last known value | `KEEP TOPIC "cache/last_temp" WITH {temperature}` |
| Store state between runs | `KEEP TOPIC "state/counter" WITH {count}` |
| Save intermediate calculations | `KEEP TOPIC "calc/running_avg" WITH {avg}` |

#### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP TOPIC "<topic>" WITH <expression>
KEEP TOPIC "<topic>" WITH PAYLOAD AS BYTES
```

Store string or variable state, including dynamic topic paths:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP TOPIC "state/mode" WITH "running"
KEEP TOPIC "device/" + {id} + "/config" WITH {config}
```

#### Example: Persistent Counter

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PersistentCounter
ON EVERY 10 SECONDS DO
    SET "current" WITH (GET TOPIC "state/counter")
    IF {current} == EMPTY THEN
        KEEP TOPIC "state/counter" WITH 1
    ELSE
        KEEP TOPIC "state/counter" WITH ({current} + 1)
    
    PUBLISH TOPIC "stats/count" WITH (GET TOPIC "state/counter")
```

#### KEEP vs PUBLISH Comparison

| Operation | MQTT retain | Delivered to subscribers | Readable with `GET TOPIC` | Typical use |
| - | - | - | - | - |
| `PUBLISH TOPIC` | Only with `RETAIN` | Yes | Yes (until overwritten) | Connectors, dashboards, external subscribers |
| `KEEP TOPIC` | No | No | Yes | Broker-internal cache for `GET TOPIC` |

***

## Control Flow

### IF ... THEN ... ELSE

Execute different logic based on conditions.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
IF <condition> THEN
    <statements>
ELSE
    <statements>
```

#### Comparison Operators

| Operator | Description | Example |
| - | - | - |
| `EQUALS` or `==` | Equality | `IF {value} EQUALS 100` |
| `!=` | Not equal | `IF {status} != "error"` |
| `>` | Greater than | `IF {temp} > 80` |
| `<` | Less than | `IF {count} < 10` |
| `>=` | Greater or equal | `IF {level} >= 50` |
| `<=` | Less or equal | `IF {pressure} <= 100` |

#### Basic Conditionals

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
IF {temperature} > 80 THEN
    PUBLISH TOPIC "alerts/high_temp" WITH {temperature}
ELSE
    PUBLISH TOPIC "status/normal" WITH "OK"
```

#### Nested Conditionals

For multiple conditions, nest IF statements:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
IF {temperature} > 90 THEN
    PUBLISH TOPIC "alerts/critical" WITH "CRITICAL: " + {temperature}
ELSE
    IF {temperature} > 80 THEN
        PUBLISH TOPIC "alerts/warning" WITH "WARNING: " + {temperature}
    ELSE
        IF {temperature} > 70 THEN
            PUBLISH TOPIC "alerts/info" WITH "Elevated: " + {temperature}
        ELSE
            PUBLISH TOPIC "status/normal" WITH "OK"
```

#### Checking for Empty Topics

Use `EMPTY` to check if a topic has no value:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
IF GET TOPIC "data/value" == EMPTY THEN
    PUBLISH TOPIC "data/value" WITH 0
ELSE
    PUBLISH TOPIC "data/value" WITH (GET TOPIC "data/value" + 1)
```

#### Combining with Expressions

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Check calculated values
SET "average" WITH (({temp1} + {temp2}) / 2)
IF {average} > {threshold} THEN
    PUBLISH TOPIC "alerts/average_high" WITH {average}

// String comparisons
IF {status} EQUALS "active" THEN
    PUBLISH TOPIC "devices/active_count" WITH (GET TOPIC "devices/active_count" + 1)
```

***

## Timestamps

Add timestamps to your messages for tracking, logging, and debugging. LoT supports two timestamp formats.

### Supported Formats

| Format | Output | Use Case |
| - | - | - |
| `TIMESTAMP "UTC"` | `2025-10-25T14:30:15Z` | Human-readable logs, APIs, ISO 8601 compliance |
| `TIMESTAMP "UNIX"` | `1729864215` | Databases, calculations, cross-platform compatibility |

### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
TIMESTAMP "UTC"   // ISO 8601 format
TIMESTAMP "UNIX"  // Unix epoch (seconds since 1970-01-01)
```

### Using with PUBLISH and KEEP

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Add timestamp to published messages
PUBLISH TOPIC "events/created" WITH TIMESTAMP "UTC"
PUBLISH TOPIC "sensors/reading/time" WITH TIMESTAMP "UNIX"

// Store timestamp for later reference
KEEP TOPIC "cache/last_update" WITH TIMESTAMP "UNIX"
```

### Using with SET

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Store timestamp in a variable
SET "event_time" WITH TIMESTAMP "UTC"
SET "process_start" WITH TIMESTAMP "UNIX"

// Use in string concatenation
SET "log_message" WITH ("Event occurred at " + TIMESTAMP "UTC")
PUBLISH TOPIC "logs/events" WITH {log_message}
```

### Complete Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AuditLogger
ON TOPIC "actions/+/executed" DO
    SET "action_name" WITH TOPIC POSITION 2
    SET "utc_time" WITH TIMESTAMP "UTC"
    SET "unix_time" WITH TIMESTAMP "UNIX"
    
    // Human-readable log
    PUBLISH TOPIC "audit/" + {action_name} + "/log" 
        WITH ("Action " + {action_name} + " executed at " + {utc_time})
    
    // Machine-readable timestamp for database storage
    PUBLISH TOPIC "audit/" + {action_name} + "/timestamp" WITH {unix_time}
```

***

## Callable Actions

LoT supports callable actions - actions that can be invoked by other actions with input parameters and return values. This enables modular, reusable logic blocks.

> [!NOTE]
>
> For reusable logic, on-demand scripts, and composition patterns, see [Callable ACTIONs](./callable-actions).

### Defining a Callable Action

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ActionName
INPUT param1 AS <TYPE>
INPUT param2 AS <TYPE>
DO
    <action_logic>
RETURN
    OUTPUT variable1
    OUTPUT variable2
```

#### Supported Input Types

* `STRING`
* `INT`
* `DOUBLE`
* `BOOL`
* `JSON`

### Calling an Action

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL ACTION ActionName
    WITH param1 = <value>, param2 = <value>
    RETURN var1, var2
```

### Basic Example

**Define**

Create a reusable calculation:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CalculateAverage
INPUT value1 AS DOUBLE
INPUT value2 AS DOUBLE
DO
    SET "sum" WITH ({value1} + {value2})
    SET "avg" WITH ({sum} / 2)
RETURN
    OUTPUT avg
```

**Call**

Use the callable action:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessSensorPair
ON TOPIC "sensors/pair/data" DO
    SET "temp1" WITH (GET JSON "sensor1" IN PAYLOAD AS DOUBLE)
    SET "temp2" WITH (GET JSON "sensor2" IN PAYLOAD AS DOUBLE)
    
    CALL ACTION CalculateAverage
        WITH value1 = {temp1}, value2 = {temp2}
        RETURN result
    
    PUBLISH TOPIC "sensors/average" WITH {result}
```

### Multiple Outputs

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AnalyzeValue
INPUT value AS DOUBLE
INPUT threshold AS DOUBLE
DO
    SET "is_above" WITH ({value} > {threshold})
    SET "difference" WITH ({value} - {threshold})
    SET "percentage" WITH ({value} / {threshold} * 100)
RETURN
    OUTPUT is_above
    OUTPUT difference
    OUTPUT percentage
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CheckThreshold
ON TOPIC "sensors/+/value" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "current_value" WITH PAYLOAD AS DOUBLE
    SET "threshold" WITH (GET TOPIC "config/threshold" AS DOUBLE)
    
    CALL ACTION AnalyzeValue
        WITH value = {current_value}, threshold = {threshold}
        RETURN above, diff, pct
    
    PUBLISH TOPIC "analysis/" + {sensor_id} + "/above_threshold" WITH {above}
    PUBLISH TOPIC "analysis/" + {sensor_id} + "/difference" WITH {diff}
    PUBLISH TOPIC "analysis/" + {sensor_id} + "/percentage" WITH {pct}
```

### Utility Action Library

Build reusable utility actions for common operations:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Reusable temperature conversion
DEFINE ACTION ConvertCelsiusToFahrenheit
INPUT celsius AS DOUBLE
DO
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
RETURN
    OUTPUT fahrenheit

// Reusable percentage calculation
DEFINE ACTION CalculatePercentage
INPUT value AS DOUBLE
INPUT total AS DOUBLE
DO
    SET "pct" WITH ({value} / {total} * 100)
RETURN
    OUTPUT pct

// Main processing action using utilities
DEFINE ACTION ProcessTemperatureReading
ON TOPIC "sensors/+/celsius" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp_c" WITH PAYLOAD AS DOUBLE
    SET "max_temp" WITH (GET TOPIC "config/max_temperature" AS DOUBLE)
    
    CALL ACTION ConvertCelsiusToFahrenheit
        WITH celsius = {temp_c}
        RETURN temp_f
    
    CALL ACTION CalculatePercentage
        WITH value = {temp_c}, total = {max_temp}
        RETURN capacity
    
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/fahrenheit" WITH {temp_f}
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/capacity_percent" WITH {capacity}
```

***

## TRIGGER Statement

The TRIGGER statement allows actions to programmatically trigger connector events or mappings. This is useful for initiating data pipeline operations or triggering external integrations.

### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
TRIGGER "<connector_name>" TO <data> FOR <mapping_name>
```

### Components

| Component | Description |
| - | - |
| `connector_name` | The name of the connector to trigger |
| `data` | The data to send (PAYLOAD, variable, or expression) |
| `mapping_name` | The specific mapping or event within the connector |

### Basic Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Trigger a connector with payload data
TRIGGER "EmailRoute" TO PAYLOAD FOR "SendAlert"

// Trigger with a variable
SET "message" WITH ("Alert: " + {sensor_id} + " exceeded threshold")
TRIGGER "NotificationRoute" TO {message} FOR "EmailMapping"

// Trigger with a literal value
TRIGGER "DatabaseRoute" TO "backup_requested" FOR "BackupEvent"
```

### Complete Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AlertHandler
ON TOPIC "alerts/+/critical" DO
    SET "alert_type" WITH TOPIC POSITION 2
    SET "alert_data" WITH PAYLOAD
    SET "timestamp" WITH TIMESTAMP "UTC"
    
    // Build alert message
    SET "message" WITH ("Critical alert [" + {alert_type} + "] at " + {timestamp})
    
    // Trigger email notification connector
    TRIGGER "EmailNotification" TO {message} FOR "CriticalAlertEmail"
    
    // Also trigger database storage
    TRIGGER "DatabaseStorage" TO {alert_data} FOR "StoreAlert"
    
    PUBLISH TOPIC "alerts/processed" WITH {alert_type}
```

### Use Cases

**Email Notifications**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SendDailyReport
ON EVERY 24 HOURS DO
    SET "report_data" WITH (GET TOPIC "reports/daily/summary")
    TRIGGER "EmailRoute" TO {report_data} FOR "DailyReportEmail"
```

**Database Operations**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ArchiveOldData
ON EVERY 1 HOUR DO
    SET "cutoff_time" WITH TIMESTAMP "UNIX"
    TRIGGER "DatabaseRoute" TO {cutoff_time} FOR "ArchiveEvent"
```

**External APIs**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION NotifyExternalSystem
ON TOPIC "events/important" DO
    TRIGGER "RestAPIRoute" TO PAYLOAD FOR "WebhookEvent"
```

***

## CALL MCP

CALL MCP allows actions to invoke tools provided by MCP (Model Context Protocol) connectors. This enables integration with AI assistants and external tools.

> [!NOTE]
>
> `CALL MCP` talks to an [MCP connector](/latest/lot-language/routes/mcp-routes) (`TYPE MCP`) — the broker as a **client** of an external server. To let an AI client operate **this** broker, enable the [MCP Server](/latest/mqtt-broker/mcp-server) instead. `TYPE MCP_SERVER` was removed.
>
> A [gRPC connector](/latest/lot-language/routes/streaming/grpc) (`TYPE GRPC`) is also a client connector, and it is not invoked with `CALL`. It forwards MQTT payloads from `SOURCE_TOPIC`.

### Prerequisites

* An MCP connector must be defined and active
* The connector must expose the tool you want to call

### Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL MCP "RouteName.tool_name"
    WITH (arg1 = <value1>, arg2 = <value2>, ...)
    RETURN AS {variable_name}
```

### Example MCP Connector

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FileSystem WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "npx"
        WITH SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-filesystem, /data"
        WITH CLIENT_NAME "CorefluxBroker"
```

### Basic Examples

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Call an MCP tool with arguments
CALL MCP "FileSystem.read_file"
    WITH (path = "/data/config.json")
    RETURN AS {file_content}

// Call without arguments
CALL MCP "MyMCPRoute.list_resources"
    RETURN AS {resources}

// Call with multiple arguments
CALL MCP "MyMCPRoute.echo"
    WITH (message = "Hello", count = 3)
    RETURN AS {response}
```

### Return Value

`RETURN AS` receives a JSON string with `success`, `tool_name`, `route_name`, `timestamp`, and `execution_time_ms`. A successful call adds `result`, the server's tool result. A failed call adds `error` instead. See [Return Value](/latest/lot-language/routes/mcp-routes#return-value).

### Complete Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ReadDeviceConfig
ON TOPIC "devices/+/request_config" DO
    SET "device_id" WITH TOPIC POSITION 2
    SET "config_path" WITH "/configs/" + {device_id} + ".json"
    
    CALL MCP "FileSystem.read_file"
        WITH (path = {config_path})
        RETURN AS {config_data}
    
    SET "read_ok" WITH (GET JSON "success" IN {config_data} AS BOOL)
    IF {read_ok} EQUALS FALSE THEN
        PUBLISH TOPIC "devices/" + {device_id} + "/config/error" WITH (GET JSON "error" IN {config_data} AS STRING)
    ELSE
        PUBLISH TOPIC "devices/" + {device_id} + "/config" WITH {config_data}
```

***

## CALL LLM

`CALL LLM` sends a prompt to a [TYPE LLM connector](/latest/lot-language/routes/ai-routes) and returns JSON. The connector does not call tools. For an assistant that can read topics or publish, use `CALL AGENT`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantModel WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"

DEFINE ACTION ExplainAlarm
ON TOPIC "alarms/raw/+" DO
    CALL LLM "PlantModel.generate"
        WITH (prompt = PAYLOAD)
        RETURN AS {result}
    PUBLISH TOPIC "alarms/explained" WITH (GET JSON "response" IN {result} AS STRING)
```

`generate` is one turn. `chat` with `use_history = "true"` keeps an in-memory thread per `session_id`. `clear_history` drops that thread. `INVOKE LLM` is the same call. Check `success` in the JSON before you use `response`.

***

## CALL AGENT

`CALL AGENT` runs a [DEFINE AGENT](/latest/lot-language/routes/ai-routes) and waits for the answer. The call runs as the agent's `DEFAULT_USER`. `execute` returns the answer text, or JSON `{ "success": false, "status", "code", "message" }` when the task is refused or fails.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH MODEL "llama3.2"

DEFINE AGENT Classifier
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    WITH SYSTEM_PROMPT "Answer with one word: safety, quality or other."
    WITH MEMORY "none"

DEFINE ACTION ClassifyNote
ON TOPIC "operators/notes" DO
    CALL AGENT "Classifier.execute"
        WITH (task = PAYLOAD)
        RETURN AS {label}
    PUBLISH TOPIC "operators/notes/classified" WITH {label}
```

`clear_history` takes `session_id` and forgets that session for `DEFAULT_USER`. A name that is not a running agent returns `unknown_agent`.

***

## Complete Example

This example combines the key operations covered on this page—SET, GET TOPIC, GET JSON, arithmetic, IF/THEN, PUBLISH, and KEEP—in a realistic sensor processing action.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ComprehensiveProcessor
ON TOPIC "sensors/+/data" DO
    // Extract sensor ID from topic path (POSITION 2 = the wildcard)
    SET "sensor_id" WITH TOPIC POSITION 2
    
    // Parse JSON payload
    SET "temperature" WITH (GET JSON "temp" IN PAYLOAD AS DOUBLE)
    
    // Convert to Fahrenheit
    SET "fahrenheit" WITH ({temperature} * 9 / 5 + 32)
    
    // Conditional alerting
    IF {temperature} > 80 THEN
        PUBLISH TOPIC "alerts/" + {sensor_id} WITH "High temp: " + {temperature}
    
    // Publish processed data
    PUBLISH TOPIC "processed/" + {sensor_id} + "/temperature" WITH {temperature}
    PUBLISH TOPIC "processed/" + {sensor_id} + "/fahrenheit" WITH {fahrenheit}
    PUBLISH TOPIC "processed/" + {sensor_id} + "/timestamp" WITH TIMESTAMP "UTC"
    
    // Cache for later reference
    KEEP TOPIC "cache/" + {sensor_id} + "/last_reading" WITH PAYLOAD
```

### What This Action Does

1. **Triggers** on any message to `sensors/+/data` topics
2. **Extracts** the sensor ID from the topic path
3. **Parses** the JSON payload to get temperature value
4. **Converts** Celsius to Fahrenheit using arithmetic
5. **Alerts** if temperature exceeds threshold
6. **Publishes** formatted data to processed topics
7. **Caches** the raw payload for future reference

***

## Quick Reference

| Operation | Category | Description |
| - | - | - |
| `+, -, *, /, %` | Arithmetic | Mathematical operations |
| `+ (strings)` | String | Concatenation |
| `RANDOM BETWEEN` | Generation | Random numbers |
| `RANDOM UUID/GUID/ULID` | Generation | Unique identifiers |
| `FILTER ... USING REGEX` | Transformation | Extract with regex |
| `REPLACE ... WITH ... IN` | Transformation | String replacement |
| `SPLIT ... CSV` | Transformation | Parse CSV data |
| `GET ENV` | Configuration | Read environment variable |
| `GET SECRET` | Configuration | Read encrypted secret |
| `KEEP ENV` | Configuration | Persist environment variable |
| `KEEP SECRET` | Configuration | Persist encrypted secret |
| `DELETE ENV` | Configuration | Remove environment variable |
| `DELETE SECRET` | Configuration | Remove secret |
| `CALL PYTHON` | Integration | Execute Python functions |
| `CALL MCP` | Integration | Invoke MCP tools |
| `CALL LLM` | Integration | Prompt a TYPE LLM connector |
| `CALL AGENT` | Integration | Run a DEFINE AGENT and wait for the answer |
| `CALL ACTION` | Control | Call other actions |
| `TRIGGER` | Control | Trigger connector events |
| `PUBLISH TOPIC` | Topic | Publish to connectors, dashboards, and subscribers. Optional `RETAIN` and `QOS0` / `QOS1` / `QOS2`. Omitting `RETAIN` keeps the historical non-retained behaviour. |
| `PUBLISH TOPIC ... WITH PAYLOAD AS BYTES` | Topic | Forward binary payloads bit-for-bit |
| `KEEP TOPIC` | Topic | Broker-internal cache for `GET TOPIC`. Never sets the MQTT retain flag. Does not accept `RETAIN`. |
| `KEEP TOPIC ... WITH PAYLOAD AS BYTES` | Topic | Store binary payloads in the broker cache without string conversion |

***

## Next Steps

> **[Python Integration](./python-integration)**
>
> Extend actions with Python functions for complex logic.

> **[LoT Notebooks](/lot-notebooks/usage)**
>
> Run and deploy these operations from VS Code with LoT Notebooks.


# ACTION Overview
Source: https://docs.coreflux.org/latest/lot-language/actions/overview

Learn how LoT Actions automate MQTT data processing with event-driven logic that runs inside the broker

## Overview

Actions are executable logic blocks that run directly inside the Coreflux MQTT broker. They react to events—incoming messages, time intervals, or manual triggers—and perform operations like data transformation, routing, and alerting.

> [!TIP]
>
> **Think of Actions like a mail sorting machine.** When a letter (message) arrives, the machine reads the address (topic), decides where it should go (routing logic), and sends it to the right mailbox (publishes to a topic). All of this happens instantly, without needing a person to manually sort each letter.

## Action Capabilities

| Capability | Description |
| - | - |
| **Event-Driven Execution** | Trigger on MQTT messages with wildcard support for flexible topic matching |
| **Time-Based Scheduling** | Execute at regular intervals—seconds to weeks—for monitoring and reporting |
| **Data Transformation** | Extract JSON fields, perform calculations, and restructure payloads inline |
| **Conditional Logic** | Connector data, set thresholds, and make decisions with IF/THEN/ELSE |

***

## When to Use Each Pattern

| Pattern | Use When |
| - | - |
| **Time-Based** (`ON EVERY`) | Periodic tasks: heartbeats, polling, scheduled reports |
| **Topic-Based** (`ON TOPIC`, `ON CHANGE`) | Event-driven processing: every message (`ON TOPIC`) or only when the payload changes (`ON CHANGE`) |
| **Client lifecycle** (`ON CONNECT`, `ON DISCONNECT`, `ON SUBSCRIBE`) | Session events: audit connections, track subscriptions, react when clients join or leave |
| **Callable** (no trigger) | Reusable utilities invoked by other actions or commands |
| **Python-Extended** (`CALL PYTHON`) | Complex calculations, external libraries, data validation |

***

## In This Section

> **[Syntax Reference](./syntax)**
>
> Start here to learn the DEFINE ACTION structure and build your first action.

> **[Action Triggers](./events)**
>
> Choose the right trigger type for your use case: time-based, topic-based, or callable.

> **[Operations](./operations)**
>
> Master SET, GET, PUBLISH, conditionals, and all available LoT operations.

> **[Python Integration](./python-integration)**
>
> Extend actions with Python when you need complex logic or external libraries.

***

## Action Types

LoT supports three action patterns:

### Time-Based Actions

Execute at regular intervals using `ON EVERY`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SystemHeartbeat
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "system/status" WITH "online"
    PUBLISH TOPIC "system/timestamp" WITH TIMESTAMP "UTC"
```

**Key characteristics:**

* Runs on a schedule regardless of incoming data
* Useful for monitoring, polling, and periodic reports
* Supported units: MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS, WEEKS, MONTHS, YEARS
* Calendar-aware scheduling: `ON EVERY WEEKDAY AT "HH:MM:SS"` and `ON EVERY WEEKEND AT "HH:MM:SS"`

### Topic-Based Actions

Execute when MQTT messages arrive using `ON TOPIC` (every matching message) or `ON CHANGE` (only when the payload differs from the last message on that topic):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureProcessor
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    
    IF {temp} > 80 THEN
        PUBLISH TOPIC "alerts/high_temp/" + {sensor_id} WITH PAYLOAD
    ELSE
        PUBLISH TOPIC "processed/" + {sensor_id} WITH PAYLOAD
```

Trigger only when the message payload changes from the last published value with `ON CHANGE`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureOnChange
ON CHANGE "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "analytics/" + {sensor_id} WITH {temp}
```

**Key characteristics:**

* `ON TOPIC` runs on every matching publish; `ON CHANGE` skips identical payloads on the same topic
* Supports `+` (single-level) and `#` (multi-level) [MQTT wildcards](/latest/mqtt-broker/protocol#wildcards)
* Access payload data via `PAYLOAD` and `GET JSON`
* Extract topic segments with `TOPIC POSITION`

See [Action Triggers](./events#topic-based-triggers) for when to choose each trigger and a side-by-side comparison.

### Client Lifecycle Actions

Execute when MQTT clients connect, disconnect, or subscribe using `ON CONNECT`, `ON DISCONNECT`, or `ON SUBSCRIBE`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AuditConnect
ON CONNECT DO
    PUBLISH TOPIC "audit/connect/" + CLIENTID WITH USER + "@" + ENDPOINT

DEFINE ACTION TrackSubscriptions
ON SUBSCRIBE "sensors/#" DO
    PUBLISH TOPIC "audit/subscriptions" WITH CLIENTID + " -> " + SUBSCRIBETOPIC
```

**Key characteristics:**

* Runs on session events instead of publishes — useful for audit trails and connection dashboards
* Access session context via `CLIENTID`, `USER`, `ENDPOINT`, `CLEANSESSION`, `DISCONNECTREASON`, `SUBSCRIBETOPIC`, and `SUBSCRIBEQOS`
* `ON SUBSCRIBE` supports optional MQTT wildcard patterns, same semantics as `ON TOPIC`
* The broker only evaluates lifecycle hooks when at least one action defines them

See [Client Lifecycle Triggers](./events#client-lifecycle-triggers) for examples and the session context variable reference.

### Callable Actions

Actions without triggers are invoked manually or by other actions:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CalculateAverage
INPUT value1 AS DOUBLE
INPUT value2 AS DOUBLE
DO
    SET "avg" WITH (({value1} + {value2}) / 2)
RETURN
    OUTPUT avg
```

**Key characteristics:**

* No automatic trigger—must be invoked explicitly
* Can accept input parameters and return values
* Invoked via `CALL ACTION` from other ACTIONs
* Ideal for reusable utility functions

> [!NOTE]
>
> Learn more in [Callable ACTIONs](./callable-actions)—reusable logic, on-demand scripts, and `CALL ACTION`.

***

## Core Operations

Actions use these operations to process data:

> [!NOTE]
>
> SET, GET TOPIC, GET JSON, PUBLISH, and IF/THEN are the core operations for working with data in actions. See the [Operations Reference](./operations) for complete details.

**Variables**

Create and use variables within an action:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "sensor_id" WITH TOPIC POSITION 2
SET "temperature" WITH (GET TOPIC "sensors/temp" AS DOUBLE)
SET "humidity" WITH (GET JSON "humidity" IN PAYLOAD AS DOUBLE)

PUBLISH TOPIC "output/" + {sensor_id} WITH {temperature}
```

**Topic Operations**

Read from and write to MQTT topics:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Read from a topic
SET "last_value" WITH (GET TOPIC "sensors/temperature" AS DOUBLE)

// Publish to subscribers
PUBLISH TOPIC "output/data" WITH {temperature}

// Store internally (not broadcast)
KEEP TOPIC "cache/last_reading" WITH PAYLOAD
```

**JSON Extraction**

Parse JSON payloads and extract fields:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// For payload: {"temp": 23.5, "humidity": 65}
SET "temp" WITH (GET JSON "temp" IN PAYLOAD AS DOUBLE)
SET "humidity" WITH (GET JSON "humidity" IN PAYLOAD AS INT)

// Nested paths
SET "city" WITH (GET JSON "location.city" IN PAYLOAD AS STRING)
```

**Conditionals**

Implement branching logic:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
IF {temperature} > 80 THEN
    PUBLISH TOPIC "alerts/high" WITH {temperature}
ELSE IF {temperature} < 20 THEN
    PUBLISH TOPIC "alerts/low" WITH {temperature}
ELSE
    PUBLISH TOPIC "status/normal" WITH "OK"
```

***

## Example: Complete Sensor Processor

This example combines topic matching, JSON extraction, conditional routing, and state updates in a realistic sensor processing action.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SensorDataProcessor
ON TOPIC "sensors/+/raw" DO
    // Extract sensor ID from topic path
    // Topic: sensors/temp001/raw → POSITION 2 = "temp001"
    SET "sensor_id" WITH TOPIC POSITION 2
    
    // Parse JSON payload
    SET "temp_value" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    SET "humidity" WITH (GET JSON "humidity" IN PAYLOAD AS DOUBLE)
    
    // Conditional routing based on thresholds
    IF {temp_value} > 80 THEN
        PUBLISH TOPIC "alerts/high_temp/" + {sensor_id} WITH PAYLOAD
    ELSE IF {temp_value} < 10 THEN
        PUBLISH TOPIC "alerts/low_temp/" + {sensor_id} WITH PAYLOAD
    ELSE
        PUBLISH TOPIC "sensors/normal/" + {sensor_id} WITH PAYLOAD
    
    // Always update the processed output
    PUBLISH TOPIC "sensors/processed/" + {sensor_id} WITH PAYLOAD
    
    // Record the last update timestamp
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/last_update" WITH TIMESTAMP "UTC"
```

**What this does:**

1. Triggers when any message arrives at `sensors/*/raw`
2. Extracts the sensor ID from the topic path
3. Parses temperature and humidity from the JSON payload
4. Connectors alerts based on temperature thresholds
5. Publishes processed data and timestamps

***

## Actions vs. Models

Actions and Models serve different purposes in LoT:

| Aspect | Actions | Models |
| - | - | - |
| **Purpose** | Process and connector data | Structure and format data |
| **Execution** | Event-driven logic | Schema definition |
| **Output** | Any MQTT operation | Structured JSON |
| **Complexity** | Conditionals, loops, Python | Field mapping, calculations |
| **Best For** | Routing, alerting, transformation | Data aggregation, formatting |

Use them together: Actions process and connector data, then publish it using a Model to produce structured JSON output.

***

## Next Steps

> **[Syntax Reference](./syntax)**
>
> Learn the complete DEFINE ACTION syntax and components.

> **[Action Triggers](./events)**
>
> Master time-based, topic-based, lifecycle, and ON START triggers.

> **[Callable ACTIONs](./callable-actions)**
>
> Reusable logic, on-demand scripts, and `CALL ACTION`.


# ACTION Python Integration
Source: https://docs.coreflux.org/latest/lot-language/actions/python-integration

Extend LoT actions with Python functions for complex calculations and data processing

## Overview

While LoT handles most IoT automation elegantly, some tasks need the full power of a programming language. Python integration lets you call Python functions directly from your LoT actions—no external services, no network calls, no containers. Your Python code runs inside the broker alongside your actions.

> [!TIP]
>
> **Think of Python as a specialist you can call for help.** Your LoT action handles the routine work (reading sensors, routing messages, checking thresholds), but when it encounters something complex—statistical analysis, regex parsing, or calling an external library—it hands the task to Python and gets the result back instantly.

***

## When to Use Python vs. LoT

Before diving into syntax, understand when Python makes sense:

| Use Python For | Use LoT For |
| - | - |
| Complex calculations (statistics, ML) | Simple math (+, -, \*, /) |
| Regex and advanced string parsing | String concatenation |
| Data validation with complex rules | Basic conditionals (IF/THEN) |
| External library calls (numpy, pandas) | MQTT operations (PUBLISH, GET TOPIC) |
| JSON transformation and restructuring | Field extraction (GET JSON) |

> [!NOTE]
>
> If you can do it in LoT, do it in LoT. Python adds overhead—use it when LoT's built-in operations aren't enough.

***

## Writing Python Scripts

Every Python script in LoT must declare its name on the **first line** using a `# Script Name:` comment. That name is what you use in `CALL PYTHON "ScriptName.function_name"`—the part before the dot must match the header exactly.

```python wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Script Name: Calculator

def add(a, b):
    return a + b

def multiply(a, b):
    return a * b
```

> [!WARNING]
>
> The first line must be `# Script Name: YourScriptName`. Without this header, the broker does not register the script and `CALL PYTHON` cannot find it.

| Header | LoT call |
| - | - |
| `# Script Name: Calculator` | `CALL PYTHON "Calculator.add"` |
| `# Script Name: DataProcessor` | `CALL PYTHON "DataProcessor.calculate_average"` |

Define one or more functions below the header. Each function is callable from LoT by name.

***

## CALL PYTHON Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL PYTHON "ScriptName.function_name"
    WITH (parameter1, parameter2, ...)
    RETURN AS {variable_name}
```

> [!NOTE]
>
> Put `WITH` and `RETURN AS` on their own indented lines under `CALL PYTHON`. The one-line form `CALL PYTHON "X.f" WITH (…) RETURN AS {r}` is not supported and fails to parse.

## Parameter Passing

### Single Parameter

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL PYTHON "Processor.validate" 
    WITH (PAYLOAD) 
    RETURN AS {result}
```

### Multiple Parameters

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "min_val" WITH (GET TOPIC "config/min")
SET "max_val" WITH (GET TOPIC "config/max")

CALL PYTHON "Validator.check_range" 
    WITH (PAYLOAD, {min_val}, {max_val}) 
    RETURN AS {result}
```

## Return Value Handling

Python functions can return simple values or complex JSON objects. The `RETURN AS` clause captures the result into a LoT variable.

### Simple Values

For basic calculations, return a single value:

**Python script:**

```python wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Script Name: Calculator

def add_numbers(a, b):
    return float(a) + float(b)
```

**LoT action calling the function:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL PYTHON "Calculator.add_numbers"
    WITH (5, 3)
    RETURN AS {result}
PUBLISH TOPIC "math/result" WITH {result}
```

### JSON Objects

For richer data, return a dictionary—it becomes JSON that LoT can parse:

**Python script returning a dictionary:**

```python wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Script Name: Analyzer

def analyze_data(value):
    return {
        "original": float(value),
        "doubled": float(value) * 2,
        "squared": float(value) ** 2
    }
```

**LoT action extracting fields from the result:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL PYTHON "Analyzer.analyze_data"
    WITH (5)
    RETURN AS {result}

PUBLISH TOPIC "analysis/full" WITH {result}
PUBLISH TOPIC "analysis/doubled" WITH (GET JSON "doubled" IN {result} AS DOUBLE)
```

## Error Handling

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL PYTHON "Calculator.safe_division"
    WITH (10, 2)
    RETURN AS {result}

SET "success" WITH (GET JSON "success" IN {result} AS BOOL)

IF {success} EQUALS TRUE THEN
    PUBLISH TOPIC "calculation/result" WITH (GET JSON "result" IN {result} AS DOUBLE)
ELSE
    PUBLISH TOPIC "calculation/error" WITH (GET JSON "error" IN {result} AS STRING)
```

## Best Practices

> **Always Set the Script Name Header**
>
> Put `# Script Name: YourScriptName` on line 1 of every Python script. The name must match the script name in `CALL PYTHON "YourScriptName.function_name"`. If calls fail with an unknown script, check spelling and that the header is the very first line.

> **Keep Functions Fast**
>
> Target execution times under 100ms. Long-running Python functions block your action and can delay message processing. For heavy computations, consider offloading to an external service.

> **Always Handle Errors**
>
> Wrap Python logic in try/except blocks and return structured error responses. This lets your LoT action gracefully handle failures instead of crashing.

> **Return JSON-Serializable Types**
>
> Return dictionaries, lists, strings, numbers, and booleans. Custom objects and classes won't serialize properly. When in doubt, convert to a dictionary.

> **Validate Input Parameters**
>
> Python functions receive parameters as strings by default. Always convert types explicitly (e.g., `float(value)`, `int(count)`) and validate ranges before processing.

***

## Next Steps

> **[Operations Reference](./operations)**
>
> Review all available LoT operations.

> **[Actions Overview](./overview)**
>
> Return to the Actions overview for pattern guidance.


# ACTION Syntax Reference
Source: https://docs.coreflux.org/latest/lot-language/actions/syntax

Complete syntax reference for defining LoT actions - event-driven logic executed by the Coreflux MQTT broker

Actions are executable logic blocks triggered by events such as timed intervals, topic updates, or explicit calls. They are the primary way to implement automation in LoT.

> [!TIP]
>
> Actions run inside the MQTT broker itself, eliminating the need for external middleware or application servers.

***

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION <action_name>
ON <EVENT_TRIGGER>
DO
    <action_logic>
```

### Components

**action\_name** `string` *required*

A unique identifier for the action. Use descriptive names that indicate the action's purpose (e.g., `SensorDataProcessor`, `HeartbeatMonitor`).

**EVENT\_TRIGGER** `trigger` *required*

Specifies when the action executes. Can be time-based (`ON EVERY`, `ON TIMESTAMP`), topic-based (`ON TOPIC`, `ON CHANGE`), initialization (`ON START`), client lifecycle (`ON CONNECT`, `ON DISCONNECT`, `ON SUBSCRIBE`), or omitted for callable actions.

**action\_logic** `statements` *required*

One or more LoT statements that execute when the action triggers. These can include publishing, variable assignment, conditionals, and Python calls.

## Action Structure

Every action follows this general structure:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ActionName
ON <trigger_type> DO
    // Variable assignment
    SET "variable" WITH <value>
    
    // Conditional logic
    IF <condition> THEN
        // Statements
    ELSE
        // Alternative statements
    
    // Topic operations
    PUBLISH TOPIC "output/topic" WITH <payload>
    KEEP TOPIC "internal/topic" WITH <payload>
```

## Disable an Action

Add `DISABLE true` on its own line to switch an action off without deleting it:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION Heartbeat
DISABLE true
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

A disabled action stays defined and listed, but no trigger runs it: topics, `ON EVERY`, schedules, `ON START`, and client connect, disconnect, or subscribe. `-runAction` refuses it, and an action that calls it with `CALL ACTION` fails to compile until it is enabled again. `DISABLE false`, or no `DISABLE` line, means enabled. A `DISABLE` line inside a comment is ignored.

The line is saved with the definition, so the action stays disabled after a restart and in a project export. To switch it without editing the code, use `-disableAction <name>` and `-enableAction <name>`. See [Disable and enable](/latest/mqtt-broker/commands#disable-and-enable).

## Trigger Types

**Time-Based**

Execute at regular intervals:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PeriodicTask
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH "alive"
```

Supported units: `SECOND(S)`, `MINUTE(S)`, `HOUR(S)`, `DAY(S)`, `WEEK(S)`

**Topic-Based**

Execute when a topic receives data. Use `ON TOPIC` for every message, or `ON CHANGE` to run only when the payload differs from the last message on that topic:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION MessageProcessor
ON TOPIC "sensors/temperature" DO
    PUBLISH TOPIC "processed/temp" WITH PAYLOAD
```

Detection of values changed:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION OnValueChange
ON CHANGE "sensors/+/temperature" DO
    PUBLISH TOPIC "analytics/updated" WITH PAYLOAD
```

Supports wildcards: `+` (single level), `#` (multi-level). See [Action Triggers](./events#topic-based-triggers) for details.

**Client lifecycle**

Execute when MQTT clients connect, disconnect, or subscribe:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AuditConnect
ON CONNECT DO
    PUBLISH TOPIC "audit/connect/" + CLIENTID WITH USER + "@" + ENDPOINT

DEFINE ACTION AuditDisconnect
ON DISCONNECT DO
    PUBLISH TOPIC "audit/disconnect/" + CLIENTID WITH DISCONNECTREASON

DEFINE ACTION TrackSubscriptions
ON SUBSCRIBE "sensors/#" DO
    PUBLISH TOPIC "audit/sub" WITH SUBSCRIBETOPIC + " qos=" + SUBSCRIBEQOS
```

Omit the pattern on `ON SUBSCRIBE` to run on every allowed subscription. See [Client Lifecycle Triggers](./events#client-lifecycle-triggers).

**Callable**

No trigger - called manually or by other actions:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION UtilityFunction
DO
    KEEP TOPIC "cache/data" WITH (GET TOPIC "source/data")
```

Invoked via `CALL ACTION` from other ACTIONs. See [Callable ACTIONs](./callable-actions).

## Compatible Keywords

Keywords that can be used within action logic:

### Variable Operations

| Keyword | Description |
| - | - |
| `SET` | Create or assign a variable |
| `GET TOPIC` | Retrieve data from a topic |
| `GET JSON` | Extract fields from JSON payloads — see [Working with JSON](/latest/lot-language/usage-patterns/working-with-json) |
| `GET PROTO` | Extract fields from protobuf payloads (`GET PROTOBUF` is the same) — see [Protobuf Models](/latest/lot-language/models/protobuf) |

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// For topic "sensors/temp001/data": POSITION 1="sensors", POSITION 2="temp001", POSITION 3="data"
SET "sensor_id" WITH TOPIC POSITION 2
SET "temperature" WITH (GET TOPIC "sensors/temp" AS DOUBLE)
SET "humidity" WITH (GET JSON "humidity" IN PAYLOAD AS DOUBLE)
```

### Topic Operations

| Keyword | Description |
| - | - |
| `PUBLISH TOPIC` | Publish to subscribers, connectors, and dashboards. Optional `RETAIN` sets the MQTT retain flag on the published message. Optional `QOS0`, `QOS1`, or `QOS2` select MQTT QoS; the default remains QoS 0. Omitting `RETAIN` keeps the historical non-retained behaviour. |
| `KEEP TOPIC` | Broker-internal cache for `GET TOPIC`. Never sets the MQTT retain flag. Does not accept `RETAIN`. |

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
PUBLISH TOPIC "output/data" WITH {temperature}
PUBLISH TOPIC "devices/" + {device_id} + "/status" WITH "online"
PUBLISH TOPIC "status/last" WITH "online" RETAIN
PUBLISH TOPIC "status/last" WITH "online" RETAIN QOS1
PUBLISH TOPIC "status/last" WITH "online" QOS2
KEEP TOPIC "cache/last_reading" WITH PAYLOAD
```

`KEEP TOPIC` is different: it stores a value for `GET TOPIC` in the broker cache and does not set the MQTT retain flag. `KEEP` does not accept `RETAIN` (use `PUBLISH TOPIC ... RETAIN` when new subscribers must receive the last payload). `RETAIN` and a QoS keyword can appear in either order (`RETAIN QOS1` or `QOS1 RETAIN`).

Each `PUBLISH TOPIC` and each `KEEP TOPIC` in one run is sent in the order it is written, including several writes to the same topic. Full actions are in [ACTION Operations](./operations#publish-topic).

### Control Flow

| Keyword | Description |
| - | - |
| `IF ... THEN ... ELSE` | Conditional execution |

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
IF {temperature} > 80 THEN
    PUBLISH TOPIC "alerts/high_temp" WITH {temperature}
ELSE
    PUBLISH TOPIC "status/normal" WITH "OK"
```

### Entities

| Entity | Description |
| - | - |
| `PAYLOAD` | The data that triggered the action; use `PAYLOAD AS BYTES` for binary passthrough |
| `CLIENTID` | MQTT client ID for the session or publisher that fired the trigger |
| `USER` | Authenticated username for the session or publisher |
| `ENDPOINT` | Client address (`ip:port`) on connect and lifecycle events |
| `CLEANSESSION` | `"true"` or `"false"` from the client's CONNECT packet |
| `DISCONNECTREASON` | Disconnect type or MQTT reason on `ON DISCONNECT` |
| `SUBSCRIBETOPIC` | Topic filter from an `ON SUBSCRIBE` event |
| `SUBSCRIBEQOS` | Requested QoS (`0`, `1`, or `2`) from an `ON SUBSCRIBE` event |
| `TOPIC POSITION n` | Extract segment from topic path |
| `TIMESTAMP` | Generate timestamps (UTC, UNIX) |
| `EMPTY` | Check if a topic has no data |

### Python Integration

| Keyword | Description |
| - | - |
| `CALL PYTHON` | Execute Python functions |

> [!NOTE]
>
> **Extend LoT with Python:** Use `CALL PYTHON` to execute complex calculations, data validation, or integrate external libraries. See the [Python Integration guide](/latest/lot-language/actions/python-integration) for complete syntax and examples.

***

## Type Casting

Use `AS` to cast values when performing comparisons or calculations:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
GET TOPIC "sensors/value" AS DOUBLE
GET TOPIC "config/enabled" AS BOOL
GET TOPIC "settings/count" AS INT
GET JSON "temperature" IN PAYLOAD AS DOUBLE
```

Supported types: `STRING`, `INT`, `DOUBLE`, `FLOAT` (alias `SINGLE`, for protobuf `float`), `BOOL`, `TIMESTAMP`, `BYTES`

For binary MQTT payloads you want to **forward unchanged** (protobuf, Modbus frames, image chunks), use `PAYLOAD AS BYTES` with `PUBLISH TOPIC` or `KEEP TOPIC`. See [Binary passthrough](/latest/lot-language/actions/operations#binary-passthrough--payload-as-bytes). To **read or write protobuf fields**, use `GET PROTO` and `PUBLISH MODEL` — see [Protobuf Models](/latest/lot-language/models/protobuf).

***

## Complete Example

> [!NOTE]
>
> **Putting It All Together:** This example demonstrates topic extraction, JSON parsing, conditional logic, and publishing - the core patterns you'll use in most actions.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SensorDataProcessor
ON TOPIC "sensors/+/raw" DO
    // Extract sensor ID from topic (position 2 = the wildcard)
    // Topic: sensors/temp001/raw → POSITION 1="sensors", POSITION 2="temp001", POSITION 3="raw"
    SET "sensor_id" WITH TOPIC POSITION 2
    
    // Get the temperature value
    SET "temp_value" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    
    // Check thresholds
    IF {temp_value} > 80 THEN
        PUBLISH TOPIC "alerts/high_temp/" + {sensor_id} WITH PAYLOAD
    ELSE
        PUBLISH TOPIC "sensors/processed/" + {sensor_id} WITH PAYLOAD
    
    // Always update the last reading timestamp
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/last_update" WITH TIMESTAMP "UTC"
```

***

## Next Steps

> **[Action Triggers](./events)**
>
> Learn about time-based, topic-based, and client lifecycle triggers in detail.

> **[Operations](./operations)**
>
> Master GET, SET, PUBLISH, and conditional logic.


# Introduction to LoT
Source: https://docs.coreflux.org/latest/lot-language/introduction

Learn what LoT (Language of Things) is and see it in action with simple examples

## What is LoT?

LoT (Language of Things) is a human-readable language for IoT automation. It uses near-English syntax to define logic, data structures, and integrations—all executed directly within the Coreflux MQTT broker.

LoT is built by defining **Actions**, **Models**, **Connectors**, and **Rules**. Each one handles a different part of your automation, and inside them you use commands like `PUBLISH`, `SET`, and `GET` to make things happen. An **agent** (`DEFINE AGENT`) is a further entity: a tool-using assistant that runs on a `TYPE LLM` connector. See [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

> [!TIP]
>
> Think of LoT as SQL for real-time MQTT data. Just as SQL transforms database records, LoT transforms live MQTT streams.

> [!TIP]
>
> **Like building with LEGO blocks.** You pick the right block for the job — Actions for logic, Models for data structure, Connectors for connections, Rules for security — and snap them together into a complete system.

## The Building Blocks

Each construct is created with the `DEFINE` keyword:

| Construct | Purpose | Trigger Types |
| - | - | - |
| **Actions** | Execute logic when events occur | Time, Topic, System events, Manual |
| **Models** | Structure MQTT data into JSON schemas | Topic values, Action calls |
| **Connectors** | Connect to external systems | Topic patterns |
| **Rules** | Control who can publish/subscribe | Client identity, Topic patterns |
| **Agents** | A tool-using assistant on a `TYPE LLM` connector | MQTT, another agent, or `CALL AGENT` |

> **[Actions](./actions/overview)**
>
> Event-driven logic triggered by time or MQTT topics.

> **[Models](./models/overview)**
>
> Data schemas that structure MQTT messages into JSON.

> **[Rules](./rules/overview)**
>
> Access control for topics and operations.

> **[Connectors](./routes/overview)**
>
> Connect to databases, brokers, and external services.

> **[Agents](./routes/ai-routes)**
>
> A tool-using assistant on a TYPE LLM connector.

***

## How They Work Together

A typical LoT solution combines all four building blocks. Each definition below uses valid LoT syntax — the same patterns you will see in the [Models](/latest/lot-language/models/overview), [Actions](/latest/lot-language/actions/overview), [Connectors](/latest/lot-language/routes/overview), and [Rules](/latest/lot-language/rules/overview) references.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- 1. MODEL: When raw temperature updates, publish structured JSON per sensor
DEFINE MODEL SensorReading WITH TOPIC "sensors/+/formatted"
    ADD STRING "sensor_id" WITH TOPIC "sensors/+/id"
    ADD DOUBLE "temperature" WITH TOPIC "sensors/+/raw" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"

-- 2. ACTION: React to formatted readings and raise alerts
DEFINE ACTION TemperatureAlert
ON TOPIC "sensors/+/formatted" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    IF {temp} > 80 THEN
        PUBLISH TOPIC "alerts/" + {sensor_id} + "/high_temp" WITH "Temperature above threshold"

-- 3. CONNECTOR: Persist sensor traffic to PostgreSQL
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "INSERT INTO sensor_readings (topic, payload) VALUES ('{topic}', '{value.json}')"

-- 4. RULE: Only supervisors (or root) may publish to alert topics
DEFINE RULE RestrictAlertPublish WITH PRIORITY 100 FOR Publish TO TOPIC "alerts/#"
    IF USER IN GROUP "supervisors" OR USER IS "root" THEN
        ALLOW
    ELSE
        DENY
```

| Step | What Happens |
| - | - |
| 1 | When `sensors/temp001/raw` updates, the Model publishes JSON to `sensors/temp001/formatted` |
| 2 | The Action reads `temperature` from that JSON and publishes to `alerts/temp001/high_temp` when it exceeds 80 |
| 3 | The Connector inserts every message under `sensors/#` (raw, formatted, and related topics) into PostgreSQL |
| 4 | The Rule denies publish to `alerts/#` unless the client is in `supervisors` or is `root` |

***

## What You'll Learn on This Page

Below you'll find practical examples showing LoT in action - from simple heartbeats to data transformation. Each example demonstrates a core capability you can implement immediately.

***

## Hello World

Three examples showing what LoT can do:

```lot Time-Based Action wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION Heartbeat
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "system/alive" WITH "ok"
```

```lot Topic-Based Action wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION Echo
ON TOPIC "input/message" DO
    PUBLISH TOPIC "output/message" WITH PAYLOAD
```

```lot Data Model wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorData WITH TOPIC "sensors/formatted"
    ADD STRING "id" WITH "TEMP001"
    ADD DOUBLE "value" WITH TOPIC "sensors/raw" AS TRIGGER
```

| Example | Trigger | What it does |
| - | - | - |
| **Heartbeat** | Every 5 seconds | Publishes "ok" to indicate the system is alive |
| **Echo** | Message on `input/message` | Forwards the payload to another topic |
| **SensorData** | Value on `sensors/raw` | Formats raw sensor data into structured JSON |

***

## Next Steps

> **[Best Practices & Patterns](/latest/quick-start/best-practices)**
>
> Naming, topic design, reusable logic, and pitfalls to avoid.

> **[Actions Overview](/latest/lot-language/actions/overview)**
>
> Learn how Actions automate MQTT data processing.


# MODEL Examples
Source: https://docs.coreflux.org/latest/lot-language/models/examples

Practical examples of LoT models for common IoT data structuring scenarios.

## Examples Index

Find the right pattern for your use case:

| Example | Pattern | Best For |
| - | - | - |
| [Simple Sensor Reading](#simple-sensor-reading) | Basic | Single source, static metadata |
| [Multi-Source Equipment](#multi-source-equipment-status) | Basic | Combining multiple topics |
| [Production Record](#production-record-with-calculations) | Calculated | Derived metrics |
| [Multi-Instance Sensor](#multi-instance-sensor-model) | Wildcard | Multiple similar devices |
| [Factory Hierarchy](#factory-hierarchy-model) | Wildcard | Multi-level topic structures |
| [Alarm Record](#alarm-record-from-json) | Action-Published | JSON processing, conditional logic |
| [Production Event](#production-event-with-calculations) | Action-Published | Complex calculations |
| [Quality Check](#quality-check-with-validation) | Action-Published | Pass/fail determination |
| [Alert Family](#alert-model-family) | Inheritance | Related data types |
| [Sensor with Metadata](#sensor-with-metadata) | Nested Objects | Grouped configuration |
| [Protobuf command and telemetry](#protobuf-command-and-telemetry) | Protobuf (beta) | Binary gateway `.proto` on MQTT |

***

## Basic Model Examples

### Simple Sensor Reading

A straightforward model that formats raw sensor data with static metadata.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Input
        A[sensors/raw/temperature]
    end
    subgraph Model
        B[SensorReading]
    end
    subgraph Output
        C[sensors/formatted/temperature]
    end
    A -->|triggers| B
    B -->|publishes| C
```

This model adds context (sensor ID, unit, status) to a raw temperature value:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorReading WITH TOPIC "sensors/formatted/temperature"
    ADD STRING "sensor_id" WITH "TEMP001"
    ADD DOUBLE "value" WITH TOPIC "sensors/raw/temperature" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
    ADD STRING "status" WITH "ACTIVE"
```

When a value arrives at `sensors/raw/temperature`, the model publishes:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "sensor_id": "TEMP001",
  "value": 25.5,
  "unit": "celsius",
  "timestamp": "2025-10-25T14:30:15Z",
  "status": "ACTIVE"
}
```

***

### Multi-Source Equipment Status

Combine data from multiple topics into a unified equipment status report.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Inputs
        A[equipment/current/id]
        B[equipment/current/status]
        C[equipment/current/runtime]
        D[equipment/current/efficiency]
    end
    subgraph Model
        E[EquipmentStatus]
    end
    subgraph Output
        F[equipment/status/formatted]
    end
    A --> E
    B -->|triggers| E
    C --> E
    D --> E
    E -->|publishes| F
```

Each field pulls from a different source topic. The status topic acts as the trigger:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL EquipmentStatus WITH TOPIC "equipment/status/formatted"
    ADD STRING "equipment_id" WITH TOPIC "equipment/current/id"
    ADD STRING "status" WITH TOPIC "equipment/current/status" AS TRIGGER
    ADD INT "runtime_hours" WITH TOPIC "equipment/current/runtime"
    ADD DOUBLE "efficiency" WITH TOPIC "equipment/current/efficiency"
    ADD BOOL "maintenance_required" WITH TOPIC "equipment/current/maintenance_flag"
    ADD STRING "last_update" WITH TIMESTAMP "UTC"
    ADD STRING "location" WITH "Factory Floor A"
```

When the status topic updates, the model publishes a combined report to `equipment/status/formatted`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "equipment_id": "CNC-4500",
  "status": "RUNNING",
  "runtime_hours": 1823,
  "efficiency": 92.4,
  "maintenance_required": false,
  "last_update": "2025-10-25T14:30:15Z",
  "location": "Factory Floor A"
}
```

***

### Production Record with Calculations

Automatically calculate derived values like efficiency percentages.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Inputs
        A[quantity]
        B[target]
    end
    subgraph Calculation
        C["efficiency = quantity / target × 100"]
    end
    subgraph Output
        D[ProductionRecord]
    end
    A --> C
    B --> C
    C --> D
```

The `efficiency_percent` field is calculated inline from other topic values:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ProductionRecord WITH TOPIC "production/records/completed"
    ADD STRING "batch_id" WITH TOPIC "production/current/batch_id"
    ADD STRING "product_code" WITH TOPIC "production/current/product_code"
    ADD INT "quantity_produced" WITH TOPIC "production/current/quantity" AS TRIGGER
    ADD INT "quantity_target" WITH TOPIC "production/current/target"
    ADD DOUBLE "efficiency_percent" WITH (GET TOPIC "production/current/quantity" AS DOUBLE / GET TOPIC "production/current/target" AS DOUBLE * 100)
    ADD STRING "operator" WITH TOPIC "production/current/operator"
    ADD STRING "completion_time" WITH TIMESTAMP "UTC"
```

Example output when 95 of 100 units are produced:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "batch_id": "BATCH_2025_001",
  "product_code": "WIDGET_A",
  "quantity_produced": 95,
  "quantity_target": 100,
  "efficiency_percent": 95.0,
  "operator": "John Smith",
  "completion_time": "2025-10-25T14:30:15Z"
}
```

***

## Wildcard Model Examples

### Multi-Instance Sensor Model

Handle multiple sensors with a single model definition using the `+` wildcard.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart TB
    subgraph Inputs
        A[sensors/temp001/value]
        B[sensors/pressure002/value]
        C[sensors/humidity003/value]
    end
    subgraph SingleModel
        D["GenericSensorData<br/>sensors/+/formatted"]
    end
    subgraph Outputs
        E[sensors/temp001/formatted]
        F[sensors/pressure002/formatted]
        G[sensors/humidity003/formatted]
    end
    A -->|triggers| D
    B -->|triggers| D
    C -->|triggers| D
    D --> E
    D --> F
    D --> G
```

The `+` wildcard matches any single level in the topic hierarchy:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL GenericSensorData WITH TOPIC "sensors/+/formatted"
    ADD STRING "sensor_id" WITH TOPIC "sensors/+/id"
    ADD DOUBLE "value" WITH TOPIC "sensors/+/value" AS TRIGGER
    ADD STRING "unit" WITH TOPIC "sensors/+/unit"
    ADD STRING "location" WITH TOPIC "sensors/+/location"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

When `sensors/temp001/value` receives data, the model publishes to `sensors/temp001/formatted`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "sensor_id": "TEMP001",
  "value": 23.7,
  "unit": "celsius",
  "location": "Building A - Room 101",
  "timestamp": "2025-10-25T14:30:15Z"
}
```

> [!NOTE]
>
> Each sensor instance (temp001, pressure002, etc.) gets its own output topic automatically. The wildcard maintains topic context through the model.

***

### Factory Hierarchy Model

Handle multi-level topic hierarchies with multiple wildcards.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart TB
    subgraph Factory
        A["factory/line1/machine1/status"]
        B["factory/line1/machine2/status"]
        C["factory/line2/machine1/status"]
    end
    subgraph Model
        D["MachineData<br/>factory/+/+/data/formatted"]
    end
    subgraph Outputs
        E["factory/line1/machine1/data/formatted"]
        F["factory/line1/machine2/data/formatted"]
        G["factory/line2/machine1/data/formatted"]
    end
    A -->|triggers| D
    B -->|triggers| D
    C -->|triggers| D
    D --> E
    D --> F
    D --> G
```

Multiple `+` wildcards capture different levels of the hierarchy:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MachineData WITH TOPIC "factory/+/+/data/formatted"
    ADD STRING "line_id" WITH TOPIC "factory/+/id"
    ADD STRING "machine_id" WITH TOPIC "factory/+/+/id"
    ADD STRING "status" WITH TOPIC "factory/+/+/status" AS TRIGGER
    ADD DOUBLE "output_rate" WITH TOPIC "factory/+/+/output_rate"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

When `factory/line1/machine1/status` updates, the model publishes to `factory/line1/machine1/data/formatted`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "line_id": "LINE_01",
  "machine_id": "MACH_01",
  "status": "RUNNING",
  "output_rate": 145.8,
  "timestamp": "2025-10-25T14:30:15Z"
}
```

***

## Models Published by Actions Examples

> [!TIP]
>
> Use this pattern when you need **full control** over publishing logic—conditional decisions, complex calculations, JSON extraction, or custom routing. The action determines when and where to publish.

### Alarm Record from JSON

Process incoming JSON payloads into structured alarm records.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Input
        A["alarms/+/json_input<br/>{type, value, threshold, ...}"]
    end
    subgraph Action
        B[ProcessAlarmJSON]
    end
    subgraph Output
        C["alarms/structured/{equipment_id}<br/>AlarmRecord model"]
    end
    A -->|triggers| B
    B -->|PUBLISH MODEL| C
```

First, define the model schema with `COLLAPSED` (no automatic trigger):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL AlarmRecord COLLAPSED
    ADD STRING "alarm_id"
    ADD STRING "equipment_id"
    ADD STRING "alarm_type"
    ADD DOUBLE "trigger_value"
    ADD DOUBLE "threshold"
    ADD STRING "severity"
    ADD STRING "message"
    ADD STRING "timestamp"
    ADD BOOL "auto_generated"
```

Then create an action that extracts JSON fields and publishes the model:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessAlarmJSON
ON TOPIC "alarms/+/json_input" DO
    SET "equipment_id" WITH TOPIC POSITION 2
    
    PUBLISH MODEL AlarmRecord TO "alarms/structured/" + {equipment_id} WITH
        alarm_id = (RANDOM UUID)
        equipment_id = {equipment_id}
        alarm_type = (GET JSON "type" IN PAYLOAD AS STRING)
        trigger_value = (GET JSON "value" IN PAYLOAD AS DOUBLE)
        threshold = (GET JSON "threshold" IN PAYLOAD AS DOUBLE)
        severity = (GET JSON "severity" IN PAYLOAD AS STRING)
        message = (GET JSON "message" IN PAYLOAD AS STRING)
        timestamp = TIMESTAMP "UTC"
        auto_generated = TRUE
```

When a JSON payload arrives at `alarms/pump003/json_input`, the action publishes to `alarms/structured/pump003`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "alarm_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "equipment_id": "pump003",
  "alarm_type": "OVERHEAT",
  "trigger_value": 95.3,
  "threshold": 85.0,
  "severity": "CRITICAL",
  "message": "Motor temperature exceeded safe limit",
  "timestamp": "2025-10-25T14:30:15Z",
  "auto_generated": true
}
```

***

### Production Event with Calculations

Create production records with computed metrics like efficiency.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Input
        A["production/+/events<br/>{parts, cycle_time, target, ...}"]
    end
    subgraph Action
        B["ProcessProductionEvent<br/>Calculate efficiency"]
    end
    subgraph Output
        C["production/events/structured/{line}<br/>ProductionEvent model"]
    end
    A -->|triggers| B
    B -->|PUBLISH MODEL| C
```

Define the schema for production events:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ProductionEvent COLLAPSED
    ADD STRING "event_id"
    ADD STRING "line_id"
    ADD STRING "event_type"
    ADD INT "parts_count"
    ADD DOUBLE "cycle_time"
    ADD DOUBLE "efficiency_percent"
    ADD STRING "operator"
    ADD STRING "timestamp"
```

The action performs calculations before publishing:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessProductionEvent
ON TOPIC "production/+/events" DO
    SET "line_id" WITH TOPIC POSITION 2
    SET "parts" WITH (GET JSON "parts_produced" IN PAYLOAD AS INT)
    SET "cycle" WITH (GET JSON "cycle_time" IN PAYLOAD AS DOUBLE)
    SET "target" WITH (GET JSON "target_cycle_time" IN PAYLOAD AS DOUBLE)
    SET "eff" WITH ({target} / {cycle} * 100)
    
    PUBLISH MODEL ProductionEvent TO "production/events/structured/" + {line_id} WITH
        event_id = (RANDOM UUID)
        line_id = {line_id}
        event_type = (GET JSON "event_type" IN PAYLOAD AS STRING)
        parts_count = {parts}
        cycle_time = {cycle}
        efficiency_percent = {eff}
        operator = (GET JSON "operator" IN PAYLOAD AS STRING)
        timestamp = TIMESTAMP "UTC"
```

When a production event arrives at `production/line2/events` with a target cycle time of 10s and an actual cycle time of 8.5s, the action publishes to `production/events/structured/line2`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "line_id": "line2",
  "event_type": "BATCH_COMPLETE",
  "parts_count": 250,
  "cycle_time": 8.5,
  "efficiency_percent": 117.6,
  "operator": "Maria Garcia",
  "timestamp": "2025-10-25T14:30:15Z"
}
```

***

### Quality Check with Validation

Determine pass/fail status based on measurement tolerances.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Input
        A["quality/+/measurement<br/>{value, target, tolerance}"]
    end
    subgraph Action
        B["ValidateQuality<br/>Check tolerance range"]
    end
    subgraph Outputs
        C["quality/passed/{id}"]
        D["quality/failed/{id}"]
    end
    A -->|triggers| B
    B -->|if within tolerance| C
    B -->|if outside tolerance| D
```

> [!NOTE]
>
> Complex conditional logic (like tolerance checking) is cleaner in an action than inline in a model. The action can also connector to different topics based on the result.

Define the quality reading schema:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL QualityReading COLLAPSED
    ADD STRING "inspection_id"
    ADD STRING "part_id"
    ADD DOUBLE "measurement"
    ADD DOUBLE "target"
    ADD DOUBLE "tolerance"
    ADD STRING "result"
    ADD STRING "timestamp"
```

The action checks if the measurement is within tolerance and connectors accordingly:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ValidateQuality
ON TOPIC "quality/+/measurement" DO
    SET "part_id" WITH TOPIC POSITION 2
    SET "value" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    SET "target" WITH (GET JSON "target" IN PAYLOAD AS DOUBLE)
    SET "tolerance" WITH (GET JSON "tolerance" IN PAYLOAD AS DOUBLE)
    SET "min_allowed" WITH ({target} - {tolerance})
    SET "max_allowed" WITH ({target} + {tolerance})
    
    IF {value} >= {min_allowed} AND {value} <= {max_allowed} THEN
        PUBLISH MODEL QualityReading TO "quality/passed/" + {part_id} WITH
            inspection_id = (RANDOM UUID)
            part_id = {part_id}
            measurement = {value}
            target = {target}
            tolerance = {tolerance}
            result = "PASS"
            timestamp = TIMESTAMP "UTC"
    ELSE
        PUBLISH MODEL QualityReading TO "quality/failed/" + {part_id} WITH
            inspection_id = (RANDOM UUID)
            part_id = {part_id}
            measurement = {value}
            target = {target}
            tolerance = {tolerance}
            result = "FAIL"
            timestamp = TIMESTAMP "UTC"
```

When a measurement of 10.02 mm arrives for a part with a target of 10.00 mm and tolerance of 0.05 mm, it passes and publishes to `quality/passed/PART_A1`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "inspection_id": "b7e8f9a0-1234-5678-90ab-cdef01234567",
  "part_id": "PART_A1",
  "measurement": 10.02,
  "target": 10.0,
  "tolerance": 0.05,
  "result": "PASS",
  "timestamp": "2025-10-25T14:30:15Z"
}
```

***

## Model Inheritance Examples

> [!NOTE]
>
> For complete inheritance patterns and syntax, see [Model Inheritance](./model-inheritance).

### Alert Model Family

Create specialized alert types from a common base model.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart TB
    subgraph BaseModel
        A["BaseAlert<br/>alert_id, source, timestamp,<br/>severity, message, acknowledged"]
    end
    subgraph SpecializedModels
        B["TemperatureAlert<br/>+ temperature_value<br/>+ threshold_exceeded<br/>+ sensor_location"]
        C["PressureAlert<br/>+ pressure_value<br/>+ max_safe_pressure<br/>+ system_affected"]
        D["MaintenanceAlert<br/>+ equipment_id<br/>+ hours_since_service<br/>+ maintenance_type"]
    end
    A --> B
    A --> C
    A --> D
```

First, define the base model with common fields:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL BaseAlert COLLAPSED
    ADD STRING "alert_id"
    ADD STRING "source_system"
    ADD STRING "timestamp"
    ADD STRING "severity"
    ADD STRING "message"
    ADD BOOL "acknowledged"
```

Then create specialized models that inherit and extend it:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TemperatureAlert FROM BaseAlert
    ADD DOUBLE "temperature_value"
    ADD DOUBLE "threshold_exceeded"
    ADD STRING "sensor_location"
    ADD STRING "unit"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL PressureAlert FROM BaseAlert
    ADD DOUBLE "pressure_value"
    ADD DOUBLE "max_safe_pressure"
    ADD STRING "pressure_unit"
    ADD STRING "system_affected"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MaintenanceAlert FROM BaseAlert
    ADD STRING "equipment_id"
    ADD STRING "maintenance_type"
    ADD INT "hours_since_service"
    ADD INT "recommended_interval"
```

Use the specialized model in an action:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION GenerateTemperatureAlert
ON TOPIC "sensors/temperature/+/alert" DO
    SET "sensor_id" WITH TOPIC POSITION 3
    
    PUBLISH MODEL TemperatureAlert TO "alerts/temperature/" + {sensor_id} WITH
        alert_id = (RANDOM UUID)
        source_system = "TemperatureMonitor"
        timestamp = TIMESTAMP "UTC"
        severity = "HIGH"
        message = "Temperature threshold exceeded"
        acknowledged = FALSE
        temperature_value = (GET JSON "value" IN PAYLOAD AS DOUBLE)
        threshold_exceeded = (GET JSON "threshold" IN PAYLOAD AS DOUBLE)
        sensor_location = (GET JSON "location" IN PAYLOAD AS STRING)
        unit = "celsius"
```

When an alert triggers for sensor `TH_042`, the action publishes to `alerts/temperature/TH_042` with both inherited and specialized fields:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "alert_id": "c3d4e5f6-7890-1234-abcd-ef5678901234",
  "source_system": "TemperatureMonitor",
  "timestamp": "2025-10-25T14:30:15Z",
  "severity": "HIGH",
  "message": "Temperature threshold exceeded",
  "acknowledged": false,
  "temperature_value": 92.7,
  "threshold_exceeded": 85.0,
  "sensor_location": "Boiler Room B",
  "unit": "celsius"
}
```

***

## Nested Object Examples

### Sensor with Metadata

Group related configuration and context fields into nested sub-objects using the `OBJECT` type and indentation.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Inputs
        A[sensors/+/value]
        B[sensors/+/id]
        C[sensors/+/location]
        D[sensors/+/floor]
        E[sensors/+/building]
        F[sensors/+/unit]
    end
    subgraph Model
        G["SensorWithMetadata<br/>sensors/+/formatted"]
    end
    subgraph Output
        H["sensors/{id}/formatted<br/>{value, metadata: {location, ...}}"]
    end
    A -->|triggers| G
    B --> G
    C --> G
    D --> G
    E --> G
    F --> G
    G -->|publishes| H
```

The `metadata` field uses `OBJECT` to group location details into a nested object. Fields indented under `ADD OBJECT` become its properties. When indentation returns to the parent level, fields belong to the top-level model again:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorWithMetadata WITH TOPIC "sensors/+/formatted"
    ADD STRING "sensor_id" WITH TOPIC "sensors/+/id"
    ADD DOUBLE "value" WITH TOPIC "sensors/+/value" AS TRIGGER
    ADD OBJECT "metadata"
        ADD STRING "unit" WITH TOPIC "sensors/+/unit"
        ADD STRING "location" WITH TOPIC "sensors/+/location"
        ADD INT "floor" WITH TOPIC "sensors/+/floor"
        ADD STRING "building" WITH TOPIC "sensors/+/building"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

When `sensors/temp001/value` receives data, the model publishes to `sensors/temp001/formatted`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "sensor_id": "TEMP001",
  "value": 25.5,
  "metadata": {
    "unit": "celsius",
    "location": "Room 101",
    "floor": 3,
    "building": "Building A"
  },
  "timestamp": "2025-10-25T14:30:15Z"
}
```

> [!NOTE]
>
> The indentation rule applies everywhere `OBJECT` is used — in basic models, wildcard models, and `COLLAPSED` templates published from actions.

***

## Protobuf Examples

> [!NOTE]
>
> Dynamic protobuf encoding and decoding in LoT is **beta**. Field numbers must match your vendor `.proto` — see [Protobuf Models](./protobuf) for `PROTO_TAG`, type mapping, and pitfalls.

### Protobuf command and telemetry

Decode a binary command from a gateway, keep the command type on a topic, then pack JSON tag values back into protobuf telemetry the gateway already understands.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Input
        A["plant/+/+/command<br/>protobuf bytes"]
        B["plant/+/+/tags<br/>JSON tags"]
    end
    subgraph Actions
        C[OnPlcCommand]
        D[PublishTelemetry]
    end
    subgraph Output
        E["plant/.../pending_command"]
        F["plant/.../telemetry<br/>protobuf bytes"]
    end
    A -->|GET PROTO| C
    C --> E
    B --> D
    D -->|PUBLISH MODEL| F
```

Declare every command arm on the parent so unused submessages do not shift wire numbers. `ADD OBJECT` holds a slot open; you only need `GET PROTO` for the fields you read:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL DeviceCommand WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "command_type" PROTO_TAG 1
    ADD OBJECT "header" PROTO_TAG 2
    ADD OBJECT "write_setpoint" PROTO_TAG 3
    ADD OBJECT "ack_alarm" PROTO_TAG 4
    ADD OBJECT "reserved_slot" PROTO_TAG 5
    ADD OBJECT "read_snapshot" PROTO_TAG 6
```

When protobuf bytes arrive on `plant/line1/plc01/command`, the action reads `command_type` and stores it for later:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION OnPlcCommand
ON TOPIC "plant/+/+/command" DO
    SET "line" WITH TOPIC POSITION 2
    SET "device_id" WITH TOPIC POSITION 3
    SET "cmd" WITH (GET PROTO "command_type" IN PAYLOAD AS INT USING MODEL "DeviceCommand")
    KEEP TOPIC "plant/" + {line} + "/" + {device_id} + "/pending_command" WITH {cmd}
```

Nested messages you fill on publish use `ADD MODEL`, not indented `ADD OBJECT`. Tag the sparse fields explicitly:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MessageHeader WITH FORMAT PROTOBUF COLLAPSED
    ADD STRING "device_id" PROTO_TAG 1
    ADD STRING "timestamp" PROTO_TAG 2

DEFINE MODEL ProcessValues WITH FORMAT PROTOBUF COLLAPSED
    ADD DOUBLE "temperature" PROTO_TAG 1
    ADD DOUBLE "pressure" PROTO_TAG 2

DEFINE MODEL TelemetryMessage WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "message_type" PROTO_TAG 1
    ADD MODEL MessageHeader "header" PROTO_TAG 2
    ADD MODEL ProcessValues "process_values" PROTO_TAG 3
```

When JSON tags arrive on `plant/line1/plc01/tags`, the action publishes **raw protobuf bytes** to `plant/line1/plc01/telemetry`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PublishTelemetry
ON TOPIC "plant/+/+/tags" DO
    SET "line" WITH TOPIC POSITION 2
    SET "device_id" WITH TOPIC POSITION 3
    SET "temp" WITH (GET JSON "Temperature" IN PAYLOAD AS DOUBLE)
    SET "pressure" WITH (GET JSON "Pressure" IN PAYLOAD AS DOUBLE)
    SET "ts" WITH TIMESTAMP "UNIX"
    PUBLISH MODEL TelemetryMessage TO "plant/" + {line} + "/" + {device_id} + "/telemetry" WITH
        message_type = 2
        header.device_id = {device_id}
        header.timestamp = {ts}
        process_values.temperature = {temp}
        process_values.pressure = {pressure}
```

Example JSON on `plant/line1/plc01/tags` that this action encodes:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Temperature": 72.4,
  "Pressure": 1.18
}
```

The destination topic carries binary protobuf, not JSON. A payload that matches this schema has field **1** = `2` (message type), field **2** = the header (`device_id` + Unix timestamp), and field **3** = process values (`temperature` + `pressure`). Decode a captured payload with `protoc --decode_raw` to confirm those field numbers.

> [!NOTE]
>
> Trigger-based models (`WITH TOPIC` + `AS TRIGGER`) still auto-publish JSON. Use `COLLAPSED` plus `PUBLISH MODEL` whenever the edge must see protobuf bytes. Full type mapping and `GET PROTO` sources: [Protobuf Models](./protobuf).

***

## Choosing the Right Pattern

> **Basic Models (WITH TOPIC + AS TRIGGER)**
>
> **Use when:** Data flows continuously and formatting is straightforward.
>
> **Best for:** Sensor readings, status updates, simple aggregation.
>
> **Trigger:** Automatic when source topic updates.

> **Calculated Fields**
>
> **Use when:** You need derived metrics computed from source values.
>
> **Best for:** Percentages, totals, averages, unit conversions.
>
> **Note:** Keep calculations simple; use actions for complex logic.

> **Wildcard Models (+)**
>
> **Use when:** You have multiple instances of the same data structure.
>
> **Best for:** Fleets of sensors, multi-line factories, device groups.
>
> **Benefit:** One model definition handles all instances.

> **Action-Published Models (COLLAPSED)**
>
> **Use when:** You need control over timing, routing, or complex logic.
>
> **Best for:** JSON extraction, conditional publishing, pass/fail routing, complex calculations.
>
> **Benefit:** Full action power with structured output.

> **Inherited Models (FROM)**
>
> **Use when:** You have related data types sharing common fields.
>
> **Best for:** Alert families, equipment types, event categories.
>
> **Benefit:** DRY principle—define common fields once.

> **Nested Objects (OBJECT)**
>
> **Use when:** Your JSON output needs grouped or hierarchical data.
>
> **Best for:** Metadata grouping, configuration objects, multi-level status reports.
>
> **Benefit:** Clean nested JSON without external formatting. Indentation controls structure.

> **Protobuf (WITH FORMAT PROTOBUF)**
>
> **Use when:** A gateway or SCADA system already speaks a `.proto` on MQTT.
>
> **Best for:** Decoding binary commands with `GET PROTO` and emitting telemetry bytes with `PUBLISH MODEL`.
>
> **Benefit:** Match vendor field numbers without a separate transformation service. See [Protobuf Models](./protobuf).

***

## Next Steps

> **[Connectors Overview](/latest/lot-language/routes/overview)**
>
> Connect your broker to external systems and databases.

> **[Actions Syntax](/latest/lot-language/actions/syntax)**
>
> Master the action syntax for publishing models.


# MODEL Inheritance
Source: https://docs.coreflux.org/latest/lot-language/models/model-inheritance

Create model families with shared fields using the FROM keyword for code reuse and consistency

## Why Use Model Inheritance?

When your system has related data types—different kinds of alerts, equipment, or events—you often repeat the same fields across multiple models. Model inheritance lets you define common fields once in a **base model**, then extend it with specialized fields for each variant.

> [!TIP]
>
> **Like a family tree for data.** A "TemperatureAlert" is a child of "Alert"—it inherits all the standard alert properties (ID, timestamp, severity) but adds its own temperature-specific fields. Change the parent, and all children get the update.

### When to Use Inheritance

| Scenario | Example |
| - | - |
| **Alert systems** | Base alert + temperature, pressure, maintenance alerts |
| **Equipment monitoring** | Base equipment + pumps, conveyors, motors |
| **Event tracking** | Base event + production, quality, safety events |
| **Sensor networks** | Base sensor + temperature, pressure, flow sensors |

***

## Inheritance Syntax

The `FROM` keyword creates a child model that inherits all fields from a parent:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ChildModel FROM ParentModel
    ADD STRING "specialized_field"
    ADD DOUBLE "another_field"
```

The child model automatically includes every field from the parent, plus any additional fields you define.

### How It Works

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Parent model with common fields
DEFINE MODEL BaseAlert COLLAPSED
    ADD STRING "alert_id"
    ADD STRING "timestamp"
    ADD STRING "severity"
    ADD STRING "message"
    ADD BOOL "acknowledged"

// Child model inherits all parent fields + adds specialized ones
DEFINE MODEL TemperatureAlert FROM BaseAlert
    ADD DOUBLE "temperature_value"
    ADD DOUBLE "threshold_exceeded"
    ADD STRING "sensor_location"
```

**Result:** `TemperatureAlert` has 8 fields total:

* 5 inherited from `BaseAlert` (alert\_id, timestamp, severity, message, acknowledged)
* 3 specialized fields (temperature\_value, threshold\_exceeded, sensor\_location)

> [!TIP]
>
> Base models are typically defined with `COLLAPSED` since they're meant to be extended, not used directly. The child models inherit this behavior.

***

## Designing Base Models

A good base model contains fields that **every variant needs**. Put yourself in the position of someone processing alerts, equipment data, or events—what fields do they always expect?

### Base Model Best Practices

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL BaseEquipment COLLAPSED
    // Identification - always needed
    ADD STRING "equipment_id"
    ADD STRING "equipment_name"
    
    // Context - helps locate and categorize
    ADD STRING "location"
    ADD STRING "status"
    
    // Operational data - common across equipment
    ADD INT "runtime_hours"
    ADD STRING "last_maintenance"
    
    // Metadata - for tracking and auditing
    ADD STRING "operator"
    ADD STRING "timestamp"
```

> [!WARNING]
>
> Don't include type-specific fields in base models. If only some variants need a field, it belongs in the child model.

### What to Include in Base Models

| Field Category | Examples | Why |
| - | - | - |
| **Identifiers** | `id`, `name`, `code` | Every record needs to be identifiable |
| **Timestamps** | `timestamp`, `created_at` | Essential for ordering and debugging |
| **Status** | `status`, `severity`, `state` | Common across most data types |
| **Context** | `location`, `source`, `operator` | Helps downstream processing |
| **Flags** | `acknowledged`, `processed` | Common workflow states |

***

## Creating Specialized Models

Child models add fields specific to their domain. Keep these focused—only add what that particular variant needs.

### Alert Family Example

Starting from a common base, create specialized alert types:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL BaseAlert COLLAPSED
    ADD STRING "alert_id"
    ADD STRING "source_system"
    ADD STRING "timestamp"
    ADD STRING "severity"
    ADD STRING "message"
    ADD BOOL "acknowledged"
```

**Temperature Alert**

Temperature alerts add measurement data and thresholds:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TemperatureAlert FROM BaseAlert
    ADD DOUBLE "temperature_value"
    ADD DOUBLE "threshold_exceeded"
    ADD STRING "sensor_location"
    ADD STRING "unit"
```

**Pressure Alert**

Pressure alerts track system-level concerns:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL PressureAlert FROM BaseAlert
    ADD DOUBLE "pressure_value"
    ADD DOUBLE "max_safe_pressure"
    ADD STRING "pressure_unit"
    ADD STRING "system_affected"
```

**Maintenance Alert**

Maintenance alerts focus on service schedules:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MaintenanceAlert FROM BaseAlert
    ADD STRING "equipment_id"
    ADD STRING "maintenance_type"
    ADD INT "hours_since_service"
    ADD INT "recommended_interval"
    ADD STRING "priority_level"
```

***

## Publishing Inherited Models

Inherited models work exactly like regular COLLAPSED models—use `PUBLISH MODEL` from an Action and provide values for all fields (inherited + specialized):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION GenerateTemperatureAlert
ON TOPIC "sensors/temperature/+/alert" DO
    SET "sensor_id" WITH TOPIC POSITION 3
    
    PUBLISH MODEL TemperatureAlert TO "alerts/temperature/" + {sensor_id} WITH
        // Inherited fields from BaseAlert
        alert_id = (RANDOM UUID)
        source_system = "TemperatureMonitor"
        timestamp = TIMESTAMP "UTC"
        severity = "HIGH"
        message = "Temperature threshold exceeded"
        acknowledged = FALSE
        
        // Specialized fields for TemperatureAlert
        temperature_value = (GET JSON "value" IN PAYLOAD AS DOUBLE)
        threshold_exceeded = (GET JSON "threshold" IN PAYLOAD AS DOUBLE)
        sensor_location = (GET JSON "location" IN PAYLOAD AS STRING)
        unit = "celsius"
```

### Polymorphic Action Pattern

One Action can handle multiple model types by checking the incoming data and publishing the appropriate variant:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PolymorphicAlertGenerator
ON TOPIC "sensors/+/+/alert" DO
    SET "sensor_type" WITH TOPIC POSITION 2
    SET "sensor_id" WITH TOPIC POSITION 3
    
    IF {sensor_type} EQUALS "temperature" THEN
        PUBLISH MODEL TemperatureAlert TO "alerts/temperature/" + {sensor_id} WITH
            alert_id = (RANDOM UUID)
            source_system = "SensorNetwork"
            timestamp = TIMESTAMP "UTC"
            severity = (GET JSON "severity" IN PAYLOAD AS STRING)
            message = "Temperature alert triggered"
            acknowledged = FALSE
            temperature_value = (GET JSON "value" IN PAYLOAD AS DOUBLE)
            threshold_exceeded = (GET JSON "threshold" IN PAYLOAD AS DOUBLE)
            sensor_location = (GET JSON "location" IN PAYLOAD AS STRING)
            unit = "celsius"
    
    ELSE IF {sensor_type} EQUALS "pressure" THEN
        PUBLISH MODEL PressureAlert TO "alerts/pressure/" + {sensor_id} WITH
            alert_id = (RANDOM UUID)
            source_system = "SensorNetwork"
            timestamp = TIMESTAMP "UTC"
            severity = (GET JSON "severity" IN PAYLOAD AS STRING)
            message = "Pressure alert triggered"
            acknowledged = FALSE
            pressure_value = (GET JSON "value" IN PAYLOAD AS DOUBLE)
            max_safe_pressure = (GET JSON "max_pressure" IN PAYLOAD AS DOUBLE)
            pressure_unit = "PSI"
            system_affected = (GET JSON "system" IN PAYLOAD AS STRING)
```

> [!NOTE]
>
> All alert types share the same base structure, so downstream systems can process common fields (like `severity` and `acknowledged`) without knowing the specific alert type.

***

## Complete Examples

**Equipment Hierarchy**

A complete equipment monitoring system with specialized equipment types:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Base model with common equipment fields
DEFINE MODEL BaseEquipment COLLAPSED
    ADD STRING "equipment_id"
    ADD STRING "equipment_name"
    ADD STRING "location"
    ADD STRING "status"
    ADD INT "runtime_hours"
    ADD STRING "last_maintenance"
    ADD STRING "operator"
    ADD STRING "timestamp"

// Pump-specific model
DEFINE MODEL PumpEquipment FROM BaseEquipment
    ADD DOUBLE "flow_rate"
    ADD DOUBLE "pressure_output"
    ADD INT "rpm"
    ADD DOUBLE "power_consumption"
    ADD STRING "pump_type"

// Conveyor-specific model
DEFINE MODEL ConveyorEquipment FROM BaseEquipment
    ADD DOUBLE "belt_speed"
    ADD INT "items_per_minute"
    ADD DOUBLE "belt_tension"
    ADD BOOL "emergency_stop_active"
    ADD STRING "direction"
```

**Action to publish equipment reports:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION EquipmentReporter
ON TOPIC "equipment/+/+/status_update" DO
    SET "equipment_type" WITH TOPIC POSITION 2
    SET "equipment_id" WITH TOPIC POSITION 3
    
    IF {equipment_type} EQUALS "pump" THEN
        PUBLISH MODEL PumpEquipment TO "equipment/reports/pump/" + {equipment_id} WITH
            equipment_id = {equipment_id}
            equipment_name = (GET JSON "name" IN PAYLOAD AS STRING)
            location = (GET JSON "location" IN PAYLOAD AS STRING)
            status = (GET JSON "status" IN PAYLOAD AS STRING)
            runtime_hours = (GET JSON "runtime" IN PAYLOAD AS INT)
            last_maintenance = (GET JSON "last_service" IN PAYLOAD AS STRING)
            operator = (GET JSON "operator" IN PAYLOAD AS STRING)
            timestamp = TIMESTAMP "UTC"
            flow_rate = (GET JSON "flow_rate" IN PAYLOAD AS DOUBLE)
            pressure_output = (GET JSON "pressure" IN PAYLOAD AS DOUBLE)
            rpm = (GET JSON "rpm" IN PAYLOAD AS INT)
            power_consumption = (GET JSON "power" IN PAYLOAD AS DOUBLE)
            pump_type = "Centrifugal"
    
    ELSE IF {equipment_type} EQUALS "conveyor" THEN
        PUBLISH MODEL ConveyorEquipment TO "equipment/reports/conveyor/" + {equipment_id} WITH
            equipment_id = {equipment_id}
            equipment_name = (GET JSON "name" IN PAYLOAD AS STRING)
            location = (GET JSON "location" IN PAYLOAD AS STRING)
            status = (GET JSON "status" IN PAYLOAD AS STRING)
            runtime_hours = (GET JSON "runtime" IN PAYLOAD AS INT)
            last_maintenance = (GET JSON "last_service" IN PAYLOAD AS STRING)
            operator = (GET JSON "operator" IN PAYLOAD AS STRING)
            timestamp = TIMESTAMP "UTC"
            belt_speed = (GET JSON "speed" IN PAYLOAD AS DOUBLE)
            items_per_minute = (GET JSON "throughput" IN PAYLOAD AS INT)
            belt_tension = (GET JSON "tension" IN PAYLOAD AS DOUBLE)
            emergency_stop_active = (GET JSON "estop" IN PAYLOAD AS BOOL)
            direction = (GET JSON "direction" IN PAYLOAD AS STRING)
```

**Event Tracking**

An event system for production, maintenance, and quality events:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Base event structure
DEFINE MODEL BaseEvent COLLAPSED
    ADD STRING "event_id"
    ADD STRING "event_category"
    ADD STRING "source"
    ADD STRING "timestamp"
    ADD STRING "severity"
    ADD STRING "description"

// Production-specific events
DEFINE MODEL ProductionEvent FROM BaseEvent
    ADD STRING "line_id"
    ADD STRING "batch_id"
    ADD INT "parts_affected"
    ADD STRING "operator"
    ADD DOUBLE "production_impact"

// Quality-specific events
DEFINE MODEL QualityEvent FROM BaseEvent
    ADD STRING "inspection_station"
    ADD STRING "product_batch"
    ADD INT "items_tested"
    ADD INT "items_failed"
    ADD STRING "failure_reason"

// Maintenance-specific events
DEFINE MODEL MaintenanceEvent FROM BaseEvent
    ADD STRING "equipment_id"
    ADD STRING "maintenance_type"
    ADD INT "downtime_minutes"
    ADD STRING "technician"
    ADD DOUBLE "cost_estimate"
```

**Sensor Network**

A sensor hierarchy for different measurement types:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// Base sensor structure
DEFINE MODEL BaseSensor COLLAPSED
    ADD STRING "sensor_id"
    ADD STRING "sensor_name"
    ADD STRING "location"
    ADD STRING "status"
    ADD STRING "last_calibration"
    ADD BOOL "calibration_valid"
    ADD STRING "timestamp"
    ADD INT "reading_count"

// Temperature sensor
DEFINE MODEL TemperatureSensor FROM BaseSensor
    ADD DOUBLE "temperature"
    ADD STRING "temperature_unit"
    ADD DOUBLE "min_range"
    ADD DOUBLE "max_range"
    ADD DOUBLE "accuracy"

// Pressure sensor
DEFINE MODEL PressureSensor FROM BaseSensor
    ADD DOUBLE "pressure"
    ADD STRING "pressure_unit"
    ADD DOUBLE "max_working_pressure"
    ADD STRING "connection_type"
    ADD BOOL "overpressure_protection"

// Flow sensor
DEFINE MODEL FlowSensor FROM BaseSensor
    ADD DOUBLE "flow_rate"
    ADD STRING "flow_unit"
    ADD DOUBLE "pipe_diameter"
    ADD STRING "fluid_type"
    ADD DOUBLE "viscosity"
```

***

## Best Practices

> **Keep Base Models Focused**
>
> Only include fields that **every** child model needs. If only some variants use a field, it belongs in the child model, not the base.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // Good - base has universal fields only
> DEFINE MODEL BaseAlert COLLAPSED
>     ADD STRING "alert_id"
>     ADD STRING "timestamp"
>     ADD STRING "severity"
>
> // Bad - 'temperature_unit' doesn't apply to all alerts
> DEFINE MODEL BaseAlert COLLAPSED
>     ADD STRING "alert_id"
>     ADD STRING "timestamp"
>     ADD STRING "severity"
>     ADD STRING "temperature_unit"  // Too specific!
> ```

> **Use Descriptive Model Names**
>
> Name child models to clearly indicate their specialization:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // Good - clear inheritance relationship
> DEFINE MODEL TemperatureAlert FROM BaseAlert
> DEFINE MODEL PressureAlert FROM BaseAlert
>
> // Bad - unclear relationship
> DEFINE MODEL TempData FROM BaseAlert
> DEFINE MODEL PressData FROM BaseAlert
> ```

> **Document the Hierarchy**
>
> When you have multiple inheritance levels, keep the structure clear:
>
> ```
> BaseEntity
> └── BaseEquipment
>     ├── PumpEquipment
>     ├── ConveyorEquipment
>     └── MotorEquipment
> ```

> **Provide All Fields When Publishing**
>
> When using `PUBLISH MODEL`, you must provide values for both inherited and specialized fields:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> PUBLISH MODEL TemperatureAlert TO "alerts/temp" WITH
>     // Don't forget inherited fields!
>     alert_id = (RANDOM UUID)
>     timestamp = TIMESTAMP "UTC"
>     severity = "HIGH"
>
>     // Plus specialized fields
>     temperature_value = 85.5
>     threshold_exceeded = 80.0
> ```

***

## Limitations

> [!WARNING]
>
> **Current limitations of model inheritance:**
>
> * **Single inheritance only** — A model can only inherit from one parent (no multiple inheritance)
> * **No field override** — Child models cannot redefine fields from the parent with different types
> * **COLLAPSED required** — Base models should use `COLLAPSED` since they're templates, not triggered models

***

## Next Steps

> **[Publishing Models](./publish-model)**
>
> Master the PUBLISH MODEL syntax for dynamic data creation.

> **[Model Examples](./examples)**
>
> See more inheritance examples in context.


# MODEL Overview
Source: https://docs.coreflux.org/latest/lot-language/models/overview

Learn how LoT models transform, structure, and format MQTT data into consistent JSON schemas

## What are Models?

Models in LoT are like database schemas for MQTT data. They define the structure of your data, ensure consistency across your system, and provide automatic JSON formatting.

> [!TIP]
>
> Models transform raw MQTT messages into structured, typed data - eliminating the need for external data transformation layers.

## Model Capabilities

> **Data Structuring**
>
> Define fields with specific types (STRING, INT, DOUBLE, BOOL, ARRAY) to create consistent data schemas.

> **Auto JSON Handling**
>
> Automatically explode incoming JSON payloads into individual topics for easy field access.

> **Data Aggregation**
>
> Combine data from multiple MQTT topics into a single structured output.

> **Calculations**
>
> Perform inline calculations and conditional logic to derive new values.

***

## How Models Work

Models do more than format data. They aggregate values from multiple MQTT topics, scale across device fleets with wildcards, compute derived metrics inline, and apply conditional logic — all within the broker, with zero external code. Here's how the core flow works.

### Receiving JSON Payloads

When a device sends a full telemetry payload, you often need to access individual fields independently — for threshold alerts, dashboard widgets, or other models. All models automatically handle this by "exploding" incoming JSON payloads into individual topics:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorData WITH TOPIC "sensors/device1/data"
```

**When JSON arrives at** `sensors/device1/data`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "temperature": 23.5,
  "humidity": 65,
  "status": "active"
}
```

**LoT automatically creates:**

* `sensors/device1/data/temperature` → `23.5`
* `sensors/device1/data/humidity` → `65`
* `sensors/device1/data/status` → `"active"`

> [!NOTE]
>
> This "explosion" behavior allows you to subscribe to individual fields or use them in other models and actions.

### Producing Structured Output

When downstream systems — databases, dashboards, REST APIs — expect a specific JSON schema, a model guarantees that format on every publish. When a model triggers (either automatically or via action), it publishes structured JSON combining all its fields:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL EquipmentStatus WITH TOPIC "equipment/formatted"
    ADD STRING "equipment_id" WITH TOPIC "equipment/id"
    ADD STRING "status" WITH TOPIC "equipment/status" AS TRIGGER
    ADD INT "runtime_hours" WITH TOPIC "equipment/runtime"
    ADD STRING "last_update" WITH TIMESTAMP "UTC"
```

**Produces:**

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "equipment_id": "PUMP001",
  "status": "RUNNING",
  "runtime_hours": 1250,
  "last_update": "2025-10-25T14:30:15Z"
}
```

### Aggregating Multiple Sources

When you need a unified equipment dashboard from scattered PLC topics, or a combined production report from sensors across different lines, a single model pulls live values from many independent topics and merges them into one structured output — replacing external aggregation scripts or middleware entirely.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Inputs
        A[equipment/current/id]
        B[equipment/current/status]
        C[equipment/current/runtime]
        D[equipment/current/efficiency]
    end
    subgraph Model
        E[EquipmentStatus]
    end
    subgraph Output
        F[equipment/status/formatted]
    end
    A --> E
    B -->|triggers| E
    C --> E
    D --> E
    E -->|publishes| F
```

Each field draws from a different source topic, but the model waits for the trigger field (`status`) to update before publishing a combined snapshot:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL EquipmentStatus WITH TOPIC "equipment/status/formatted"
    ADD STRING "equipment_id" WITH TOPIC "equipment/current/id"
    ADD STRING "status" WITH TOPIC "equipment/current/status" AS TRIGGER
    ADD INT "runtime_hours" WITH TOPIC "equipment/current/runtime"
    ADD DOUBLE "efficiency" WITH TOPIC "equipment/current/efficiency"
    ADD BOOL "maintenance_required" WITH TOPIC "equipment/current/maintenance_flag"
    ADD STRING "last_update" WITH TIMESTAMP "UTC"
```

### Building Nested Objects with Indentation

When your API or database expects grouped fields — such as a `metadata` object inside a sensor reading, or a `status` block with nested `maintenance` details — use the `OBJECT` type to produce nested JSON directly. Fields indented one level deeper than `ADD OBJECT` become properties of that sub-object — the same way `ADD` fields under `DEFINE MODEL` become top-level properties.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorWithMetadata WITH TOPIC "sensors/+/formatted"
    ADD STRING "sensor_id" WITH TOPIC "sensors/+/id"
    ADD DOUBLE "value" WITH TOPIC "sensors/+/value" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD OBJECT "metadata"
        ADD STRING "location" WITH TOPIC "sensors/+/location"
        ADD INT "floor" WITH TOPIC "sensors/+/floor"
        ADD STRING "building" WITH TOPIC "sensors/+/building"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

**Produces:**

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "sensor_id": "TEMP001",
  "value": 25.5,
  "unit": "celsius",
  "metadata": {
    "location": "Room 101",
    "floor": 3,
    "building": "Building A"
  },
  "timestamp": "2025-10-25T14:30:15Z"
}
```

The indentation level determines the nesting. Fields at the same depth as `ADD OBJECT` (like `"timestamp"` above) return to the parent object.

> [!WARNING]
>
> Indentation must be consistent. Use either tabs or spaces throughout your model — mixing them will cause parsing errors. Each nesting level adds one indentation step.

### What Else Can Models Do?

The examples above cover the fundamentals, but models go much further:

> [!NOTE]
>
> * **Nested Objects** — Use the `OBJECT` type with indentation to group related fields into sub-objects, producing clean nested JSON hierarchies. [See examples →](./examples#sensor-with-metadata)
> * **Wildcard Models** — Define one model with `+` wildcards and it automatically handles every matching device. One definition, hundreds of instances, zero duplication. [See examples →](./examples#multi-instance-sensor-model)
> * **Inline Calculations** — Compute efficiency percentages, unit conversions, and running averages directly inside the model definition — no external processing needed. [See examples →](./examples#production-record-with-calculations)
> * **Conditional Logic** — Dynamically tag field values based on live data: label readings as `"HIGH"` or `"NORMAL"`, flag quality as `"PASS"` or `"FAIL"`, assign priority levels.
> * **Action-Published Templates** — Use `COLLAPSED` models as reusable schemas, then publish them from actions with full control over timing, routing, and conditional decisions. [Learn more →](./publish-model)
> * **Protobuf (beta)** — Match a vendor `.proto` with `WITH FORMAT PROTOBUF`, `PROTO_TAG`, and `ADD MODEL`, then decode with `GET PROTO` or emit bytes with `PUBLISH MODEL`. [Learn more →](./protobuf)

For example, a single wildcard model automatically scales across every matching device — one definition handles your entire fleet:

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph singleDef [Single Definition]
        A["GenericSensor<br/>sensors/+/formatted"]
    end
    subgraph autoInst [Auto-Created Instances]
        B[sensors/temp001/formatted]
        C[sensors/pressure002/formatted]
        D[sensors/humidity003/formatted]
    end
    A --> B
    A --> C
    A --> D
```

[See the full wildcard example →](./examples#multi-instance-sensor-model)

***

## Model Types

LoT supports three model patterns, each suited for different scenarios:

| Pattern | Use When |
| - | - |
| **Basic Model** | You want automatic triggering on data changes |
| **Template Model (COLLAPSED)** | You need control over when and where data is created |
| **Inheritance (FROM)** | You have related data types sharing common fields |

### Basic Models

Basic models automatically trigger and publish structured data when their trigger field updates:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorReading WITH TOPIC "sensors/formatted/temperature"
    ADD STRING "sensor_id" WITH "TEMP001"
    ADD DOUBLE "value" WITH TOPIC "sensors/raw/temperature" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

**Key characteristics:**

* `WITH TOPIC` specifies where output is published
* `AS TRIGGER` defines which field change causes publication
* Runs automatically when trigger field updates

### Template Models (COLLAPSED)

Template models are reusable schemas for dynamic data creation from within actions. The `COLLAPSED` keyword indicates they have no automatic trigger:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL AlarmRecord COLLAPSED
    ADD STRING "alarm_id"
    ADD STRING "equipment_id"
    ADD STRING "severity"
    ADD STRING "timestamp"

DEFINE ACTION ProcessAlarm
ON TOPIC "alarms/+/input" DO
    SET "equip_id" WITH TOPIC POSITION 2
    
    PUBLISH MODEL AlarmRecord TO "alarms/structured/" + {equip_id} WITH
        alarm_id = (RANDOM UUID)
        equipment_id = {equip_id}
        severity = (GET JSON "severity" IN PAYLOAD AS STRING)
        timestamp = TIMESTAMP "UTC"
```

**Key characteristics:**

* `COLLAPSED` means no automatic trigger
* Published explicitly with `PUBLISH MODEL`
* Full control over when and where data is created

> [!NOTE]
>
> Learn how to publish template models from actions in [Publishing Models](./publish-model).

### Model Inheritance (FROM)

Create model families with shared fields using the `FROM` keyword:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL BaseAlert COLLAPSED
    ADD STRING "alert_id"
    ADD STRING "timestamp"
    ADD STRING "severity"

DEFINE MODEL TemperatureAlert FROM BaseAlert
    ADD DOUBLE "temperature_value"
    ADD DOUBLE "threshold"
```

**Key characteristics:**

* Child models inherit all parent fields
* Add specialized fields as needed
* Promotes code reuse and consistency

> [!NOTE]
>
> Learn more about designing model hierarchies in [Model Inheritance](./model-inheritance).

***

## Data Sources

Model fields can be populated from various sources:

**Static Values**

Use static values for constants like units, default thresholds, or fixed identifiers that never change:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL StaticExample WITH TOPIC "output/static"
    ADD STRING "unit" WITH "celsius"
    ADD INT "default_threshold" WITH 100
    ADD BOOL "enabled" WITH TRUE
```

**Topic Data**

Pull live values from MQTT topics. Use `AS TRIGGER` on the field that should cause the model to publish:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TopicExample WITH TOPIC "output/dynamic"
    ADD DOUBLE "temperature" WITH TOPIC "sensors/raw/temp"
    ADD STRING "status" WITH TOPIC "equipment/status" AS TRIGGER
```

**Timestamps**

Add automatic timestamps in UTC format or as Unix epoch integers for time-series data:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TimestampExample WITH TOPIC "output/timed"
    ADD STRING "created_at" WITH TIMESTAMP "UTC"
    ADD INT "unix_time" WITH TIMESTAMP "UNIX"
```

**Calculations**

Compute derived values inline using arithmetic operations on topic data:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL CalculatedExample WITH TOPIC "output/calculated"
    ADD DOUBLE "efficiency" WITH (GET TOPIC "produced" AS DOUBLE / GET TOPIC "target" AS DOUBLE * 100)
```

**Conditionals**

Apply conditional logic to set field values based on dynamic conditions:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ConditionalExample WITH TOPIC "output/conditional"
    ADD STRING "status" WITH IF (GET TOPIC "value" > 80) THEN "HIGH" ELSE "NORMAL"
```

***

## Next Steps

> **[Model Syntax](./schema-definition)**
>
> Learn the complete syntax for defining model fields and triggers.

> **[Model Inheritance](./model-inheritance)**
>
> Create model families with shared fields using FROM.


# MODEL Protobuf
Source: https://docs.coreflux.org/latest/lot-language/models/protobuf

Decode and encode binary protobuf on MQTT with LoT models, GET PROTO, and PUBLISH MODEL

## Speak the same binary schema as your gateway

Industrial gateways and PLCs often publish **binary protobuf** on MQTT while the broker maps plant tags (Modbus, S7, OPC UA) to plain topics. LoT models let you **decode** those commands, run normal tag logic in the middle, and **encode** telemetry back — without a separate transformation service.

> [!NOTE]
>
> Dynamic protobuf encoding and decoding in LoT is **beta**. Prefer **`PUBLISH MODEL`** for binary MQTT output. Match your vendor `.proto` with `PROTO_TAG` and report issues with that layout and your broker version.

> [!TIP]
>
> **Wire numbers are mailbox slots, not labels.** Protobuf finds a field by its number (`PROTO_TAG`), not by the LoT or `.proto` field name. If the slot numbers drift, the message still arrives — it just lands in the wrong boxes, or looks empty.

### When to use this

Use protobuf models when:

* a gateway or SCADA system publishes **raw protobuf bytes** on MQTT;
* you must **emit protobuf** that a vendor decoder already understands;
* field numbers in the `.proto` are **sparse** (for example `101`) or nested;
* a [gRPC connector](/latest/lot-language/routes/streaming/grpc) should forward those bytes to a gRPC service. The connector does not decode protobuf.

Use [JSON models](./overview) and [`GET JSON`](/latest/lot-language/actions/operations#get-json) when payloads are JSON. Use the [Sparkplug B Connector](/latest/lot-language/routes/system/sparkplug-b) when the schema is Sparkplug B (`spBv1.0/#`), not a custom plant `.proto`.

***

Start from the direction you need: decode inbound bytes, publish outbound bytes, or both.

## Quick Start

**Decode a command**

Read top-level fields from a binary command payload with `GET PROTO`. Declare every command arm so unused submessages keep their wire numbers:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL DeviceCommand WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "command_type" PROTO_TAG 1
    ADD OBJECT "header" PROTO_TAG 2
    ADD OBJECT "write_setpoint" PROTO_TAG 3
    ADD OBJECT "ack_alarm" PROTO_TAG 4
    ADD OBJECT "reserved_slot" PROTO_TAG 5
    ADD OBJECT "read_snapshot" PROTO_TAG 6
```

The Action reads `command_type` from the triggering payload:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION OnPlcCommand
ON TOPIC "plant/+/+/command" DO
    SET "cmd" WITH (GET PROTO "command_type" IN PAYLOAD AS INT USING MODEL "DeviceCommand")
    KEEP TOPIC "plant/pending_command" WITH {cmd}
```

**Publish telemetry**

Nested messages you fill on publish use `ADD MODEL`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MessageHeader WITH FORMAT PROTOBUF COLLAPSED
    ADD STRING "device_id" PROTO_TAG 1
    ADD STRING "timestamp" PROTO_TAG 2

DEFINE MODEL ProcessValues WITH FORMAT PROTOBUF COLLAPSED
    ADD DOUBLE "temperature" PROTO_TAG 1
    ADD DOUBLE "pressure" PROTO_TAG 2

DEFINE MODEL TelemetryMessage WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "message_type" PROTO_TAG 1
    ADD MODEL MessageHeader "header" PROTO_TAG 2
    ADD MODEL ProcessValues "process_values" PROTO_TAG 3
```

The Action packs JSON tag values into that envelope and publishes **bytes** on the gateway topic:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PublishTelemetry
ON TOPIC "plant/+/+/tags" DO
    SET "line" WITH TOPIC POSITION 2
    SET "device_id" WITH TOPIC POSITION 3
    SET "temp" WITH GET JSON "Temperature" IN PAYLOAD AS DOUBLE
    SET "pressure" WITH GET JSON "Pressure" IN PAYLOAD AS DOUBLE
    SET "ts" WITH TIMESTAMP "UNIX"
    PUBLISH MODEL TelemetryMessage TO "plant/" + {line} + "/" + {device_id} + "/telemetry" WITH
        message_type = 2
        header.timestamp = {ts}
        process_values.temperature = {temp}
        process_values.pressure = {pressure}
```

**Nested float fields**

Declare proto `float` with `ADD FLOAT` and nested messages with `ADD MODEL`. A dotted path walks into the child:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL AudioInfo WITH FORMAT PROTOBUF COLLAPSED
    ADD FLOAT "sample_rate_hz" PROTO_TAG 1
    ADD INT "channels" PROTO_TAG 2

DEFINE MODEL AudioFrame WITH FORMAT PROTOBUF COLLAPSED
    ADD STRING "service" PROTO_TAG 1
    ADD MODEL AudioInfo "audio_info" PROTO_TAG 2
```

Read the nested float and the top-level string. `USING MODEL` names the top-level message:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ReadAudioFrame
ON TOPIC "edge/+/audio" DO
    SET "rate" WITH (GET PROTO "audio_info.sample_rate_hz" IN PAYLOAD AS FLOAT USING MODEL "AudioFrame")
    SET "service" WITH (GET PROTO "service" IN PAYLOAD AS STRING USING MODEL "AudioFrame")
    PUBLISH TOPIC "edge/audio/rate" WITH {rate}
```

***

## Where protobuf applies

| Mechanism | Protobuf on MQTT? |
| - | - |
| **`PUBLISH MODEL … TO "topic"`** in an Action | **Yes** — binary (or JSON plus a `/protobuf` sidecar topic for `BOTH`) |
| **Trigger-based `DEFINE MODEL … WITH TOPIC` + `AS TRIGGER`** | **No** — still JSON on the base topic; use **`PUBLISH MODEL`** for binary |
| **OT connector tag topics** (Modbus, S7, OPC UA mappings) | Usually **JSON or plain values** — not protobuf unless you add it |

Define protobuf models for **edge** topics. Use **`GET PROTO`** to read and **`PUBLISH MODEL`** to write. Tag reads and writes stay on your existing OT connectors.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sequenceDiagram
  participant GW as Gateway or SCADA
  participant Broker
  participant PLC as PLC via OT connector
  GW->>Broker: DeviceCommand proto bytes
  Broker->>Broker: GET PROTO command_type
  Broker->>PLC: TRIGGER connector or tag write
  PLC->>Broker: tag values on MQTT topics
  Broker->>GW: PUBLISH MODEL TelemetryMessage proto bytes
```

***

## Match your `.proto`

To stay aligned with a hand-written schema (including **non-contiguous** field numbers and nested messages):

1. **`PROTO_TAG`** — wire numbers must match the `.proto` (not field names).
2. **Nested messages you fill on publish** — **`ADD MODEL ChildName "field"`** where `ChildName` is a `DEFINE MODEL`.
3. **Reserved wire slots** — **`ADD OBJECT "field" PROTO_TAG n`** when the parent must keep empty submessage fields so later tags stay aligned.

`GET PROTO` and `GET PROTOBUF` are the same verb. `PROTO` and `PROTOBUF` are the same format keyword.

### Type mapping

A field is only decoded when the **wire type** the sender used matches the type your model implies. Get this wrong and that field is skipped — there is no error on the wire.

| Proto type | Declare in LoT | Read with `GET PROTO … AS` |
| - | - | - |
| `double` | `ADD DOUBLE` | `DOUBLE` |
| `float` | `ADD FLOAT` (alias `ADD SINGLE`) | `FLOAT`, `SINGLE`, or `DOUBLE` |
| `int32` · `int64` · `uint32` · `uint64` · `sint32` · `sint64` · enum | `ADD INT` | `INT` |
| `bool` | `ADD BOOL` | `BOOL` |
| `string` | `ADD STRING` | `STRING` |
| `bytes` | `ADD OBJECT` | `BYTES` |
| nested `message` (publishing a filled body) | `ADD MODEL Child "field"` | — (fill via `PUBLISH MODEL`) |
| nested `message` (holding a wire slot open) | `ADD OBJECT "field"` | `BYTES` |

`ADD FLOAT` is protobuf `float` — **not** a nested model named `FLOAT`. `FLOAT` and `SINGLE` are reserved type keywords; outside protobuf they behave as aliases of `DOUBLE`.

After a `float` is decoded it becomes a LoT number, so `AS DOUBLE` on a `FLOAT` field is valid. LoT has no separate 32-bit numeric type.

`ADD INT` is a **varint**. Proto `fixed32`, `sfixed32`, `fixed64`, and `sfixed64` use a different wire encoding and have no LoT keyword (`ADD FIXED32` does not exist). If those types appear in the vendor schema, declaring them as `ADD INT` will skip or misread the field.

### What happens on a mismatch

The decoder follows the protobuf unknown-field rule rather than failing the whole message:

| Situation | Result |
| - | - |
| Declared type matches the incoming wire type | Field decodes |
| Field number not in your model | Skipped |
| Truncated or malformed field | Decoding of that message stops there; fields already read are kept |
| Declared `DOUBLE`, sender sent `float` (or the reverse) | That field is skipped; every other field still decodes |

A skipped field is **absent**, and `GET PROTO` returns `null` for it. There is no error log — an unexpected `null` almost always means a wire-type mismatch.

### How field numbers are assigned

The broker does not ship a plant schema. Numbers come from your `DEFINE MODEL`:

| Your model definition | Wire field numbers |
| - | - |
| No `PROTO_TAG` | **1, 2, 3, …** in LoT source order |
| Every field tagged | Exactly those tags |
| Mixed | Tagged = explicit; untagged = next free integer |

If the `.proto` uses field **101** but LoT omits `PROTO_TAG 101`, the next sequential number is used and the gateway decoder fails.

***

## Inbound: `GET PROTO`

Prefer **`IN PAYLOAD`** on the triggering topic. Use the other sources when the bytes are already cached or wrapped as Base64:

| Source | Bytes come from |
| - | - |
| **`IN PAYLOAD`** | The MQTT payload that fired the Action |
| **`IN GET TOPIC "…"`** | Last payload stored for that topic |
| **`IN` a LoT variable** | A Base64 string in that variable (decoded before parse) |

Pass **`USING MODEL "Name"`** unless a `DEFINE MODEL … WITH TOPIC` already registered that schema on the topic. **`AS INT` / `DOUBLE` / `FLOAT` / `SINGLE` / `STRING` / `BOOL` / `BYTES`** selects the LoT type after decode. On a nested path, `USING MODEL` still names the top-level message.

Read from the last payload stored on another topic:

```lot wrap focus={3} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION RetryCachedCommand
ON TOPIC "plant/+/+/command/retry" DO
    SET "cmd" WITH (GET PROTO "command_type" IN GET TOPIC "plant/line1/plc01/command" AS INT USING MODEL "DeviceCommand")
```

Or decode Base64 that arrived as JSON:

```lot wrap focus={4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DecodeBase64Command
ON TOPIC "plant/+/encoded" DO
    SET "b64" WITH GET JSON "payload_b64" IN PAYLOAD AS STRING
    SET "cmd" WITH (GET PROTO "command_type" IN {b64} AS INT USING MODEL "DeviceCommand")
```

Notes that matter in practice:

* **Each `GET PROTO` decodes the payload from scratch.** Reading two fields means two independent passes.
* **`USING MODEL` always names the top-level message**, even when the path is nested.
* **A mismatch inside the child does not fail the parent.** Sibling fields still decode.
* **`ADD FLOAT` is what makes a 32-bit field readable.** Declaring it `ADD DOUBLE` makes the decoder expect 8 bytes where the sender wrote 4 — the field is skipped.

Do not use `IF PAYLOAD IS PROTO` to detect binary MQTT. Call **`GET PROTO … IN PAYLOAD`** instead.

### Parent command with reserved field numbers

Vendor `.proto` files often declare several command arms but send only one. List **every** submessage slot on the parent so unused fields do not shift wire numbers. Use **`ADD OBJECT`** for unused slots. When **publishing** a filled nested message, use **`ADD MODEL`** on the parent instead.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL DeviceCommand WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "command_type" PROTO_TAG 1
    ADD OBJECT "header" PROTO_TAG 2
    ADD OBJECT "write_setpoint" PROTO_TAG 3
    ADD OBJECT "ack_alarm" PROTO_TAG 4
    ADD OBJECT "reserved_slot" PROTO_TAG 5
    ADD MODEL ReadSnapshot "read_snapshot" PROTO_TAG 6

DEFINE MODEL ReadSnapshot WITH FORMAT PROTOBUF COLLAPSED
    ADD STRING "tag_group" PROTO_TAG 1
    ADD INT "max_age_ms" PROTO_TAG 2
```

`ADD OBJECT` holds a wire slot open but carries no schema, so a dotted path through an `ADD OBJECT` field cannot resolve. Use `ADD MODEL` on the arm you read.

***

## Middle: tags stay JSON

Between command and telemetry, most OT setups already have **tag values** on topics — from a `DEFINE CONNECTOR` mapping, a collapsed JSON model, or single-value publishes. That step stays JSON or plain text unless your plant standard requires protobuf on those topics too.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ReadPlcTags
ON TOPIC "plant/line1/plc01/tags" DO
    SET "temp" WITH GET JSON "Temperature" IN PAYLOAD AS DOUBLE
    SET "pressure" WITH GET JSON "Pressure" IN PAYLOAD AS DOUBLE
    SET "speed" WITH GET JSON "MotorSpeed" IN PAYLOAD AS DOUBLE
    PUBLISH TOPIC "plant/line1/plc01/snapshot/temperature" WITH {temp}
```

***

## Outbound: `PUBLISH MODEL`

### Topic vs format

| Model format | Payload on **`TO "…"`** topic |
| - | - |
| **`WITH FORMAT JSON`** (default) | JSON string |
| **`WITH FORMAT PROTOBUF`** / **`PROTO`** | Raw protobuf **bytes** |
| **`WITH FORMAT BOTH`** | JSON on the main topic + binary on a `/protobuf` sidecar topic |

The next `PUBLISH MODEL` to the same topic **merges**: binary for `PROTO` only; JSON from the main topic for `JSON` / `BOTH`. **`KEEP` + protobuf** updates the byte cache without per-field JSON fan-out.

Trigger-based models (`WITH TOPIC` + `AS TRIGGER`) still auto-publish **JSON** on the base topic. Use `PUBLISH MODEL` when the edge must see binary.

### Response envelope with sparse tags

Alarms and events often use high field numbers (**101**, **102**). Tag them explicitly; use **`ADD MODEL`** for nested bodies you fill on publish. `MessageHeader` and `ProcessValues` match Quick Start — the new pieces are `AlarmEvent` and field **101**:

```lot wrap focus={10-18} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MessageHeader WITH FORMAT PROTOBUF COLLAPSED
    ADD STRING "device_id" PROTO_TAG 1
    ADD STRING "timestamp" PROTO_TAG 2

DEFINE MODEL ProcessValues WITH FORMAT PROTOBUF COLLAPSED
    ADD DOUBLE "temperature" PROTO_TAG 1
    ADD DOUBLE "pressure" PROTO_TAG 2
    ADD INT "motor_speed" PROTO_TAG 3

DEFINE MODEL AlarmEvent WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "alarm_code" PROTO_TAG 1
    ADD STRING "alarm_text" PROTO_TAG 2

DEFINE MODEL TelemetryMessage WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "message_type" PROTO_TAG 1
    ADD MODEL MessageHeader "header" PROTO_TAG 2
    ADD MODEL ProcessValues "process_values" PROTO_TAG 3
    ADD MODEL AlarmEvent "alarm_event" PROTO_TAG 101
```

LoT names are for **`PUBLISH MODEL`** / **`GET PROTO`**. Wire numbers come only from **`PROTO_TAG`**. Set `message_type` to the enum integer your `.proto` expects.

### Raw `bytes` fields

Some messages carry opaque **`bytes`** (recipe blob, certificate, file chunk). Assign them with **`BYTES FROM BASE64`**:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL RecipeBlock WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "recipe_id" PROTO_TAG 1
    ADD OBJECT "payload" PROTO_TAG 2
```

Then the Action fills `payload` from a Base64 JSON field:

```lot wrap focus={3-5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION StoreRecipe
ON TOPIC "plant/+/recipe/upload" DO
    PUBLISH MODEL RecipeBlock TO "plant/archive/recipe" WITH
        recipe_id = 42
        payload = BYTES FROM BASE64 (GET JSON "data_b64" IN PAYLOAD AS STRING)
```

To forward an entire protobuf payload unchanged (no field access), use [`PAYLOAD AS BYTES`](/latest/lot-language/actions/operations#binary-passthrough--payload-as-bytes) instead of `GET PROTO`.

***

## Common pitfalls

> **ADD OBJECT vs ADD MODEL**
>
> **`ADD OBJECT`** when **publishing** a populated nested **message** produces JSON-in-bytes. Use **`ADD MODEL`**.

> **Missing PROTO\_TAG on sparse fields**
>
> Events at **101+** need an explicit tag. Omitting unused command slots on the parent also shifts later wire indexes.

> **GET PROTO needs ADD MODEL**
>
> Dotted **`GET PROTO`** paths require the parent to declare the child with **`ADD MODEL`**.

> **ADD DOUBLE on proto float**
>
> The field is skipped. Use **`ADD FLOAT`** (or **`ADD SINGLE`**).

> **USING MODEL names the top**
>
> On a nested read, name the **top-level** message, not the child model.

> **Reserved words as variable names**
>
> A variable may use a name shaped like a LoT keyword (`store`, `unit`, `limit`, `device`, and the rest). Inside `{…}` — expressions, conditions, topic strings, payloads, and `PUBLISH MODEL … WITH` field values — that name is a variable reference. Keyword matching is case-insensitive, so `{Device}` and `{device}` are the same variable.
>
> A protobuf field name is not that reference. The model can still declare a field called `device`; `{device}` reads the variable, not the field label.

***

## Troubleshooting

`GET PROTO` returns `"null"` rather than raising, so a wrong schema looks like missing data.

| Symptom | Likely cause | Fix |
| - | - | - |
| Every field is `null` | Wrong model in `USING MODEL`, or the payload is not protobuf | Confirm the message name and that the publisher sends raw bytes, not JSON |
| Values decode but the gateway rejects what you publish | Field numbers drifted from the `.proto` | Add explicit `PROTO_TAG` to every field |
| Numbers are wildly wrong (huge or negative) | Fixed-width integer read as a varint, or signedness mismatch | Check `fixed32` vs `sfixed32` in the `.proto` |
| One field is `null`, the rest decode | Wire-type mismatch on that field | Check `float` vs `double` and fixed-width vs varint in the `.proto` |
| A field and **everything after it** is missing | Field declared at the wrong width, truncating the read | Same as above — most often `ADD DOUBLE` on a proto `float` |
| A nested path is `null` but the parent decodes | Parent declares the child as `ADD OBJECT` | Use `ADD MODEL Child "field"` |

To confirm what is on the wire, decode a captured payload with a protobuf raw decoder (`protoc --decode_raw`). It reports field numbers and wire types without needing the schema — that pair must match your `DEFINE MODEL`.

> [!WARNING]
>
> **Beta limitations**
>
> * Trigger-based models auto-publish JSON only — use `PUBLISH MODEL` for binary.
> * No native `google.protobuf.Timestamp`; carry timestamps as `STRING` or Unix `INT`.
> * The sidecar topic for `BOTH` is a `/protobuf` suffix on the destination topic (not `/proto`).
> * No protobuf **groups** (wire types 3 and 4) — a group stops decoding of that message.
> * Packed repeated scalars are skipped so decoding can continue; they are not expanded into LoT arrays.
> * A `float` is promoted to a LoT number after decode, so a round-trip re-encodes at the width the field declares.

***

## Next Steps

> **[Publishing Models](./publish-model)**
>
> Control when and where COLLAPSED models publish, including protobuf bytes.

> **[GET PROTO in Actions](/latest/lot-language/actions/operations#get-proto)**
>
> Full GET PROTO syntax, sources, and types.


# MODEL Publishing
Source: https://docs.coreflux.org/latest/lot-language/models/publish-model

Create structured data dynamically from actions using COLLAPSED models and PUBLISH MODEL

## When to Use Action Models

Action models (COLLAPSED models) are templates for structured data that you publish explicitly from within actions. They're ideal when you need:

* **Control over timing** - Publish only when specific conditions are met
* **Dynamic routing** - Send data to different topics based on logic
* **Data transformation** - Process and enrich data before structuring

> [!TIP]
>
> Unlike basic models that trigger automatically on topic changes, action models let you decide exactly when and where structured data is created. With `WITH FORMAT PROTOBUF`, that output is binary protobuf bytes rather than JSON — see [Protobuf Models](./protobuf).

### Example Use Case

Imagine you receive raw alarm data and need to:

1. Extract relevant fields from JSON
2. Add a unique ID and timestamp
3. Connector critical alarms to a special topic
4. Publish a structured record

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL AlarmRecord COLLAPSED
    ADD STRING "alarm_id"
    ADD STRING "equipment_id"
    ADD STRING "severity"
    ADD STRING "timestamp"

DEFINE ACTION ProcessAlarm
ON TOPIC "alarms/+/input" DO
    SET "equipment_id" WITH TOPIC POSITION 2
    SET "severity" WITH (GET JSON "severity" IN PAYLOAD AS STRING)
    
    PUBLISH MODEL AlarmRecord TO "alarms/structured/" + {equipment_id} WITH
        alarm_id = (RANDOM UUID)
        equipment_id = {equipment_id}
        severity = {severity}
        timestamp = TIMESTAMP "UTC"
    
    IF {severity} EQUALS "CRITICAL" THEN
        PUBLISH TOPIC "alerts/critical/" + {equipment_id} WITH PAYLOAD
```

***

## Step-by-Step Guide

**1. Define a COLLAPSED Model**

Create a template with all required fields. The `COLLAPSED` keyword indicates this model has no automatic trigger:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorRecord COLLAPSED
    ADD STRING "sensor_id"
    ADD STRING "sensor_type"
    ADD DOUBLE "temperature"
    ADD DOUBLE "humidity"
    ADD STRING "quality_status"
    ADD STRING "timestamp"
```

**2. Create the Processing Action**

Define an action that extracts data and publishes the model:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessSensorJSON
ON TOPIC "sensors/+/json_data" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    
    // Extract from JSON payload
    SET "temp" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    SET "hum" WITH (GET JSON "humidity" IN PAYLOAD AS DOUBLE)
    SET "type" WITH (GET JSON "type" IN PAYLOAD AS STRING)
    SET "quality" WITH (GET JSON "quality" IN PAYLOAD AS STRING)
    
    // Publish structured record
    PUBLISH MODEL SensorRecord TO "sensors/processed/" + {sensor_id} WITH
        sensor_id = {sensor_id}
        sensor_type = {type}
        temperature = {temp}
        humidity = {hum}
        quality_status = {quality}
        timestamp = TIMESTAMP "UTC"
```

**3. Test the Flow**

**Publish to:** `sensors/temp001/json_data`

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "temperature": 23.5,
  "humidity": 65,
  "type": "environmental",
  "quality": "GOOD"
}
```

**Result at:** `sensors/processed/temp001`

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "sensor_id": "temp001",
  "sensor_type": "environmental",
  "temperature": 23.5,
  "humidity": 65,
  "quality_status": "GOOD",
  "timestamp": "2025-10-25T14:30:15Z"
}
```

***

## Use Case Examples

**Alarm Processing**

Connector alarms by severity while creating structured records:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL AlarmRecord COLLAPSED
    ADD STRING "alarm_id"
    ADD STRING "equipment_id"
    ADD STRING "alarm_type"
    ADD DOUBLE "trigger_value"
    ADD STRING "severity"
    ADD STRING "timestamp"

DEFINE ACTION ProcessAlarmJSON
ON TOPIC "alarms/+/input" DO
    SET "equipment_id" WITH TOPIC POSITION 2
    
    PUBLISH MODEL AlarmRecord TO "alarms/structured/" + {equipment_id} WITH
        alarm_id = (RANDOM UUID)
        equipment_id = {equipment_id}
        alarm_type = (GET JSON "type" IN PAYLOAD AS STRING)
        trigger_value = (GET JSON "value" IN PAYLOAD AS DOUBLE)
        severity = (GET JSON "severity" IN PAYLOAD AS STRING)
        timestamp = TIMESTAMP "UTC"
    
    // Connector critical alarms
    SET "sev" WITH (GET JSON "severity" IN PAYLOAD AS STRING)
    IF {sev} EQUALS "CRITICAL" THEN
        PUBLISH TOPIC "alerts/critical/" + {equipment_id} WITH PAYLOAD
```

**Quality Reports**

Calculate metrics and generate quality reports:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL QualityReport COLLAPSED
    ADD STRING "report_id"
    ADD STRING "station_id"
    ADD INT "items_tested"
    ADD INT "items_passed"
    ADD DOUBLE "pass_rate"
    ADD STRING "timestamp"

DEFINE ACTION GenerateQualityReport
ON TOPIC "quality/+/results" DO
    SET "station" WITH TOPIC POSITION 2
    SET "tested" WITH (GET JSON "total" IN PAYLOAD AS INT)
    SET "passed" WITH (GET JSON "passed" IN PAYLOAD AS INT)
    SET "rate" WITH ({passed} AS DOUBLE / {tested} AS DOUBLE * 100)
    
    PUBLISH MODEL QualityReport TO "reports/quality/" + {station} WITH
        report_id = (RANDOM UUID)
        station_id = {station}
        items_tested = {tested}
        items_passed = {passed}
        pass_rate = {rate}
        timestamp = TIMESTAMP "UTC"
    
    IF {rate} < 90 THEN
        PUBLISH TOPIC "alerts/quality/low_rate" WITH {station} + ": " + {rate} + "%"
```

**Event Logging**

Create structured event logs with context:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL EventLog COLLAPSED
    ADD STRING "event_id"
    ADD STRING "event_type"
    ADD STRING "source"
    ADD STRING "description"
    ADD STRING "severity"
    ADD STRING "timestamp"

DEFINE ACTION LogEvent
ON TOPIC "events/+/occurred" DO
    SET "event_type" WITH TOPIC POSITION 2
    
    PUBLISH MODEL EventLog TO "logs/events/" + {event_type} WITH
        event_id = (RANDOM UUID)
        event_type = {event_type}
        source = (GET JSON "source" IN PAYLOAD AS STRING)
        description = (GET JSON "message" IN PAYLOAD AS STRING)
        severity = (GET JSON "severity" IN PAYLOAD AS STRING)
        timestamp = TIMESTAMP "UTC"
```

***

## JSON vs protobuf on the destination topic

`PUBLISH MODEL` writes whatever format the model declares:

| Model format | Payload on **`TO "…"`** |
| - | - |
| `WITH FORMAT JSON` (default) | JSON string |
| `WITH FORMAT PROTOBUF` / `PROTO` | Raw protobuf **bytes** |
| `WITH FORMAT BOTH` | JSON on the main topic + binary on a `/protobuf` sidecar topic |

Trigger-based models (`WITH TOPIC` + `AS TRIGGER`) still auto-publish JSON. Use a `COLLAPSED` model and `PUBLISH MODEL` when a gateway must receive protobuf. Nested messages you fill on publish use `ADD MODEL Child "field"`, not indented `ADD OBJECT`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TelemetryMessage WITH FORMAT PROTOBUF COLLAPSED
    ADD INT "message_type" PROTO_TAG 1
    ADD DOUBLE "temperature" PROTO_TAG 2
    ADD DOUBLE "pressure" PROTO_TAG 3
```

The Action copies JSON tags into that envelope and publishes **bytes**:

```lot wrap focus={6-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PublishTelemetry
ON TOPIC "plant/+/tags" DO
    SET "temp" WITH GET JSON "Temperature" IN PAYLOAD AS DOUBLE
    SET "pressure" WITH GET JSON "Pressure" IN PAYLOAD AS DOUBLE
    PUBLISH MODEL TelemetryMessage TO "plant/gateway/telemetry" WITH
        message_type = 2
        temperature = {temp}
        pressure = {pressure}
```

Full type mapping, `PROTO_TAG`, and `GET PROTO` are on [Protobuf Models](./protobuf).

***

## Best Practices

> **Always Use Type Casting with GET JSON**
>
> Explicit type casting prevents runtime errors:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // Good
> SET "temp" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
>
> // Risky
> SET "temp" WITH (GET JSON "temperature" IN PAYLOAD)
> ```

> **Validate Extracted Data**
>
> Check data before publishing:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> SET "value" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
>
> IF {value} >= 0 AND {value} <= 100 THEN
>     PUBLISH MODEL ValidData TO "output" WITH value = {value}
> ELSE
>     PUBLISH TOPIC "errors/validation" WITH "Invalid value: " + {value}
> ```

> **Use Dynamic Topics**
>
> Include identifiers in output topics for easy filtering:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // For topic "sensors/temp001/data" - wildcard is at position 2
> SET "sensor_id" WITH TOPIC POSITION 2
> PUBLISH MODEL SensorData TO "processed/" + {sensor_id} + "/data" WITH ...
> ```

> **Generate Unique IDs**
>
> Use `RANDOM UUID` for record identification:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> PUBLISH MODEL Record TO "records/new" WITH
>     record_id = (RANDOM UUID)
>     ...
> ```

## Next Steps

> **[Model Examples](./examples)**
>
> See complete examples for common use cases.

> **[Action Operations](../actions/operations)**
>
> Review available operations for action logic.


# MODEL Syntax and Components
Source: https://docs.coreflux.org/latest/lot-language/models/schema-definition

Complete reference for defining model schemas, field types, data sources, and triggers

## Why Define a Schema?

Models transform scattered MQTT data into structured, predictable JSON. Instead of parsing raw payloads in your application, you define *once* how data should look—and Coreflux handles the rest.

> [!TIP]
>
> **Like a form that fills itself out.** You define what fields the form should have (temperature, humidity, timestamp), and the model automatically grabs the latest values from different sources whenever it needs to publish.

### When to Use This Reference

Use this page when you need to:

* Define field types for your model (STRING, INT, DOUBLE, etc.)
* Pull values from multiple MQTT topics into a single output
* Calculate or transform values inline
* Control *when* your model publishes using triggers
* Align protobuf field numbers with a vendor `.proto` (`PROTO_TAG`, `WITH FORMAT PROTOBUF`)

***

## Basic Model Syntax

Every model follows this structure:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL <ModelName> WITH TOPIC "<output/topic>"
    ADD <FIELD_TYPE> "<field_name>" WITH <data_source> [AS TRIGGER]
    ADD <FIELD_TYPE> "<field_name>" WITH <data_source>
    ...
```

### Components

**ModelName** `string` *required*

Unique identifier for the model. Use descriptive names like `SensorReading`, `EquipmentStatus`, `ProductionRecord`.

**WITH TOPIC** `string` *required*

The MQTT topic where the model's JSON output will be published. Supports wildcards for multi-instance models. Not required on `COLLAPSED` templates published with `PUBLISH MODEL`.

**WITH FORMAT** `enum`

Optional. `JSON` (default), `PROTOBUF` / `PROTO`, or `BOTH`. Controls what `PUBLISH MODEL` puts on the destination topic. See [Protobuf Models](./protobuf).

**FIELD\_TYPE** `type` *required*

One of: `STRING`, `INT`, `DOUBLE`, `FLOAT` (alias `SINGLE`), `BOOL`, `ARRAY`, `OBJECT`, or `MODEL` (nested protobuf message)

**AS TRIGGER** `modifier`

Optional. Marks this field as the trigger—the model publishes only when this field's source topic updates.

***

## Trigger Mechanism

The `AS TRIGGER` modifier controls *when* your model publishes. Without it, you'd flood your broker with updates every time *any* source topic changes.

> [!TIP]
>
> **Like a doorbell that takes a photo.** The model waits quietly until the trigger topic "rings," then takes a snapshot of all fields and publishes the complete picture. No ring, no photo.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TriggeredModel WITH TOPIC "output/triggered"
    ADD STRING "equipment_id" WITH TOPIC "equipment/id"
    ADD STRING "status" WITH TOPIC "equipment/status" AS TRIGGER
    ADD INT "runtime" WITH TOPIC "equipment/runtime"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

**Behavior:**

* Model publishes **only** when `equipment/status` changes
* Changes to `equipment/id` or `equipment/runtime` alone do not trigger publication
* All field values are fetched at trigger time

### No Trigger Specified

If no field has `AS TRIGGER`, the model acts as a template. You must publish it explicitly using `PUBLISH MODEL` from an Action.

> [!NOTE]
>
> Learn how to publish models on-demand in [Publishing Models](./publish-model).

### Multiple Data Sources, Single Trigger

You can pull data from many topics but trigger on just one:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MultiSourceModel WITH TOPIC "output/multi"
    ADD STRING "sensor_a" WITH TOPIC "sensors/a/value"
    ADD STRING "sensor_b" WITH TOPIC "sensors/b/value"
    ADD STRING "sensor_c" WITH TOPIC "sensors/c/value" AS TRIGGER
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

**Only publishes when sensor C updates**, but includes current values from sensors A and B.

***

## Field Types

Each field in your model has a type that determines how the value is serialized to JSON (or to protobuf when the model uses `WITH FORMAT PROTOBUF`).

### STRING

Text data of any length:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD STRING "sensor_id" WITH "TEMP001"
ADD STRING "status" WITH TOPIC "equipment/status"
ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

### INT

Whole numbers (integers):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD INT "count" WITH 0
ADD INT "runtime_hours" WITH TOPIC "equipment/runtime"
ADD INT "total" WITH (GET TOPIC "passed" + GET TOPIC "failed")
```

### DOUBLE

Decimal numbers (floating-point):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD DOUBLE "temperature" WITH 23.5
ADD DOUBLE "efficiency" WITH TOPIC "metrics/efficiency"
ADD DOUBLE "percentage" WITH (GET TOPIC "actual" AS DOUBLE / GET TOPIC "target" AS DOUBLE * 100)
```

### FLOAT

Protobuf `float` (32-bit). Alias: `ADD SINGLE`. Use this when the `.proto` field is `float`, not `double`. After decode the value is a LoT number, so `GET PROTO … AS DOUBLE` on a `FLOAT` field is valid.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD FLOAT "sample_rate_hz" PROTO_TAG 1
ADD SINGLE "gain" PROTO_TAG 2
```

> [!NOTE]
>
> Outside protobuf, `FLOAT` and `SINGLE` behave as aliases of `DOUBLE`. For binary schemas, `ADD DOUBLE` on a proto `float` skips that field. See [Protobuf Models](./protobuf#type-mapping).

### BOOL

Boolean values (true/false):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD BOOL "enabled" WITH TRUE
ADD BOOL "maintenance_required" WITH TOPIC "equipment/needs_maintenance"
ADD BOOL "is_valid" WITH (GET TOPIC "value" > 0)
```

### ARRAY

JSON arrays:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD ARRAY "readings" WITH TOPIC "sensors/batch/readings"
ADD ARRAY "tags" WITH ["production", "line1", "active"]
```

### OBJECT

Nested JSON objects. Fields indented one level deeper than `ADD OBJECT` become properties of the sub-object. When the indentation returns to the parent level, subsequent fields belong to the parent again.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD OBJECT "metadata"
    ADD STRING "location" WITH "Building A"
    ADD INT "floor" WITH 3
```

Produces a nested structure in the JSON output:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "metadata": {
    "location": "Building A",
    "floor": 3
  }
}
```

> [!WARNING]
>
> Indentation must be consistent throughout the model. Use either tabs or spaces — mixing them causes parsing errors.

### MODEL (nested protobuf)

Names another `DEFINE MODEL` as a nested protobuf message. Required when you **publish** a filled submessage, and when you read a dotted `GET PROTO` path. Pair with `PROTO_TAG` so the wire number matches the `.proto`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MODEL AudioInfo "audio_info" PROTO_TAG 2
```

Do not confuse this with indented `ADD OBJECT` for JSON nesting. For protobuf wire layout, see [Protobuf Models](./protobuf).

### PROTO\_TAG

Sets the protobuf field number. Without it, tags are assigned **1, 2, 3, …** in source order. Use an explicit tag whenever the `.proto` is not sequential.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD INT "message_type" PROTO_TAG 1
ADD MODEL AlarmEvent "alarm_event" PROTO_TAG 101
```

***

## Data Sources

Fields can pull values from several sources. Mix and match as needed.

### Static Values

Fixed values that never change—useful for metadata, units, or default settings:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL StaticExample WITH TOPIC "output/static"
    ADD STRING "unit" WITH "celsius"
    ADD INT "default_threshold" WITH 100
    ADD DOUBLE "conversion_factor" WITH 1.8
    ADD BOOL "enabled" WITH TRUE
    ADD STRING "location" WITH "Factory Floor A"
```

### Topic Data

Pull live values from other MQTT topics. The value is fetched *at publish time*, not when the model is defined.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TopicExample WITH TOPIC "output/dynamic"
    ADD DOUBLE "temperature" WITH TOPIC "sensors/raw/temperature"
    ADD STRING "status" WITH TOPIC "equipment/current/status" AS TRIGGER
    ADD INT "count" WITH TOPIC "production/count"
```

> [!TIP]
>
> **Example:** If `sensors/raw/temperature` currently holds `23.5`, the model's `temperature` field will be `23.5` when it publishes. If the value changes to `24.0` before the next publish, the model will output `24.0`.

### Timestamps

Built-in timestamp generation—no external time source needed:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD STRING "timestamp" WITH TIMESTAMP "UTC"      // "2025-10-25T14:30:15Z"
ADD STRING "iso_time" WITH TIMESTAMP "ISO"       // ISO 8601 format
ADD INT "unix_time" WITH TIMESTAMP "UNIX"        // 1729864215
ADD INT "unix_ms" WITH TIMESTAMP "UNIX-MS"       // Milliseconds since epoch
```

### Calculated Values

Perform inline math using topic data:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL CalculatedExample WITH TOPIC "output/calculated"
    ADD DOUBLE "efficiency" WITH (GET TOPIC "produced" AS DOUBLE / GET TOPIC "target" AS DOUBLE * 100)
    ADD INT "total" WITH (GET TOPIC "passed" + GET TOPIC "failed")
    ADD DOUBLE "fahrenheit" WITH (GET TOPIC "celsius" AS DOUBLE * 9 / 5 + 32)
    ADD DOUBLE "average" WITH ((GET TOPIC "val1" + GET TOPIC "val2" + GET TOPIC "val3") / 3)
```

> [!WARNING]
>
> Always use `AS DOUBLE` or `AS INT` when performing mathematical operations to ensure correct type handling.

### Conditional Values

Dynamic values based on conditions:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ConditionalExample WITH TOPIC "output/conditional"
    ADD STRING "status" WITH IF (GET TOPIC "value" > 80) THEN "HIGH" ELSE "NORMAL"
    ADD STRING "quality" WITH IF (GET TOPIC "defects" = 0) THEN "PASS" ELSE "FAIL"
    ADD INT "priority" WITH IF (GET TOPIC "severity" EQUALS "CRITICAL") THEN 1 
                            ELSE IF (GET TOPIC "severity" EQUALS "HIGH") THEN 2 
                            ELSE 3
```

***

## Wildcard Topics

### Multi-Instance Models

Use `+` wildcards to create models that handle multiple instances automatically:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MultiInstanceModel WITH TOPIC "sensors/+/formatted"
```

**Matches:**

* `sensors/temp001/formatted`
* `sensors/pressure002/formatted`
* `sensors/humidity003/formatted`

Each unique topic creates a separate model instance.

### JSON Reception with Wildcards

When JSON arrives at a wildcard topic, the broker "explodes" it into individual topics:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL MaterialData WITH TOPIC "Process/+/+/Material/Content"
```

**When JSON arrives at** `Process/Machine/33/Material/Content`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"MaterialID": 132323, "Name": "Peppers", "Quantity": 21}
```

**Explodes to:**

* `Process/Machine/33/Material/Content/MaterialID` → `132323`
* `Process/Machine/33/Material/Content/Name` → `Peppers`
* `Process/Machine/33/Material/Content/Quantity` → `21`

***

## Complete Examples

**Equipment Status**

This model aggregates equipment data from multiple topics into a single, structured output. It triggers whenever the status changes.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL EquipmentStatus WITH TOPIC "equipment/status/formatted"
    ADD STRING "equipment_id" WITH TOPIC "equipment/current/id"
    ADD STRING "status" WITH TOPIC "equipment/current/status" AS TRIGGER
    ADD INT "runtime_hours" WITH TOPIC "equipment/current/runtime"
    ADD DOUBLE "efficiency" WITH TOPIC "equipment/current/efficiency"
    ADD BOOL "maintenance_required" WITH TOPIC "equipment/current/maintenance_flag"
    ADD STRING "last_update" WITH TIMESTAMP "UTC"
    ADD STRING "location" WITH "Factory Floor A"
```

**Output:**

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "equipment_id": "PUMP001",
  "status": "RUNNING",
  "runtime_hours": 1250,
  "efficiency": 87.5,
  "maintenance_required": false,
  "last_update": "2025-10-25T14:30:15Z",
  "location": "Factory Floor A"
}
```

**Production Record**

This model calculates efficiency metrics inline. It triggers when the quantity updates, capturing a snapshot of the production run.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ProductionRecord WITH TOPIC "production/records/completed"
    ADD STRING "batch_id" WITH TOPIC "production/current/batch_id"
    ADD STRING "product_code" WITH TOPIC "production/current/product_code"
    ADD INT "quantity_produced" WITH TOPIC "production/current/quantity" AS TRIGGER
    ADD INT "quantity_target" WITH TOPIC "production/current/target"
    ADD DOUBLE "efficiency_percent" WITH (GET TOPIC "production/current/quantity" AS DOUBLE / GET TOPIC "production/current/target" AS DOUBLE * 100)
    ADD STRING "operator" WITH TOPIC "production/current/operator"
    ADD STRING "completion_time" WITH TIMESTAMP "UTC"
```

**Output:**

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "batch_id": "BATCH-2025-1025",
  "product_code": "PRD-A1234",
  "quantity_produced": 850,
  "quantity_target": 1000,
  "efficiency_percent": 85.0,
  "operator": "John Smith",
  "completion_time": "2025-10-25T16:45:30Z"
}
```

***

## Best Practices

> **Use Consistent Field Naming**
>
> Establish naming conventions and follow them across all models:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // Good - consistent across models
> ADD STRING "timestamp"
> ADD STRING "sensor_id"
> ADD STRING "equipment_id"
>
> // Avoid - inconsistent
> ADD STRING "time_stamp"
> ADD STRING "sensorID"
> ADD STRING "equip_ID"
> ```

> **Always Type Cast in Calculations**
>
> Explicit type casting prevents errors and ensures predictable results:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // Good
> ADD DOUBLE "efficiency" WITH (GET TOPIC "produced" AS DOUBLE / GET TOPIC "target" AS DOUBLE * 100)
>
> // Risky - implicit type handling
> ADD DOUBLE "efficiency" WITH (GET TOPIC "produced" / GET TOPIC "target" * 100)
> ```

> **Include Essential Context**
>
> Always include fields that help downstream consumers understand the data:
>
> * Identification fields (IDs, names)
> * Timestamps
> * Units of measurement
> * Status or quality indicators

> **Choose Triggers Carefully**
>
> Trigger on the primary data field, not metadata:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> // Good - trigger on the main measurement
> ADD DOUBLE "value" WITH TOPIC "sensors/temperature" AS TRIGGER
>
> // Bad - triggers too frequently or unpredictably
> ADD STRING "timestamp" WITH TIMESTAMP "UTC" AS TRIGGER
> ```

***

## Next Steps

> **[Publishing Models](./publish-model)**
>
> Learn to publish models dynamically from Actions.

> **[Model Examples](./examples)**
>
> See complete model examples for common use cases.


# CrateDB Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/cratedb

Store MQTT data in CrateDB for distributed time-series analytics and SQL queries

## CrateDB Overview

The `CRATEDB` connector stores MQTT messages in CrateDB, a distributed SQL database optimized for time-series and machine data. It combines the familiarity of SQL with the scalability needed for IoT workloads.

> [!NOTE]
>
> CrateDB excels at high-volume time-series data with fast ingestion and SQL query capabilities. Use it when you need real-time analytics on sensor data at scale.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO sensor_data (ts, sensor_id, value) VALUES (?, ?, ?)"
```

***

## Connection Configuration

### CRATEDB\_CONFIG Parameters

**HOST** `string` *required*

CrateDB server hostname or IP address.

**USERNAME** `string` *required*

Database username.

**PASSWORD** `string` *required*

Database password.

> **Optional Settings**
>
> **PORT** `integer`
>
> CrateDB PostgreSQL protocol port. Default: 5432.
>
> **DATABASE** `string`
>
> Target database/schema name.

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH HOST GET ENV "DB_HOST"
> WITH USERNAME GET ENV "DB_USER"
> WITH PASSWORD GET SECRET "DB_PASSWORD"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## Writing Data

**Basic Time-Series**

Store sensor readings with timestamps:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TimeSeriesDB WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreTimeSeries
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH DESTINATION_TOPIC "db/crate/status"
        WITH QUERY "INSERT INTO sensor_data (ts, sensor_id, value) VALUES (?, ?, ?)"
```

**High-Volume Metrics**

Optimized for high ingestion rates:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MetricsDB WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "metrics"
        WITH USERNAME "metrics_writer"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreMetrics
        WITH SOURCE_TOPIC "metrics/#"
        WITH QUERY "INSERT INTO metrics (ts, topic, data) VALUES (?, ?, ?)"
```

**Multiple Tables**

Connector to different tables by topic:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiTableDB WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    
    ADD EVENT StoreSensors
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "INSERT INTO sensors (ts, topic, data) VALUES (?, ?, ?)"
    
    ADD EVENT StoreAlerts
        WITH SOURCE_TOPIC "alerts/#"
        WITH QUERY "INSERT INTO alerts (ts, topic, data) VALUES (?, ?, ?)"
```

**UPSERT**

Insert or ignore on conflict. CrateDB supports `ON CONFLICT DO NOTHING` to skip duplicate inserts for idempotent ingestion:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EventLog WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreUniqueEvent
        WITH SOURCE_TOPIC "events/+/occurred"
        WITH QUERY "INSERT INTO events (event_id, device_id, event_type, ts) VALUES ('{value.json.event_id}', '{value.json.device_id}', '{value.json.event_type}', '{value.json.timestamp}') ON CONFLICT (event_id) DO NOTHING"
```

`ON CONFLICT (event_id) DO NOTHING` ensures duplicate messages — common in IoT delivery — never create duplicate rows.

**UPDATE**

Modify existing records when a status change arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    ADD EVENT UpdateDeviceStatus
        WITH SOURCE_TOPIC "devices/+/status"
        WITH QUERY "UPDATE devices SET current_status = '{value.json.status}', last_seen = NOW() WHERE device_id = '{value.json.device_id}'"
```

**DELETE**

Remove records on a decommission or cleanup event:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    ADD EVENT DecommissionDevice
        WITH SOURCE_TOPIC "devices/+/decommissioned"
        WITH QUERY "DELETE FROM devices WHERE device_id = '{value.json.device_id}'"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "TimeSeriesDB"
>         WITH TABLE "sensor_data"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support SELECT queries to read data back from the database. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "SELECT sensor_id, value FROM sensor_data WHERE sensor_id = '{payload}' ORDER BY ts DESC LIMIT 1"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   db/query/latest
Payload: temp001
```

The query result is published to `db/result/latest`, where your actions or external clients can consume it.

> [!NOTE]
>
> CrateDB makes new rows visible to reads about once a second. A `SELECT` event that runs right after an insert may not see that row yet. Run `REFRESH TABLE <table>` first when you need it.

### Timed Polling

EVENTs can also run SELECT queries on a fixed schedule using `WITH EVERY`. This is especially powerful with CrateDB's fast aggregations:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TimeSeriesDB WITH TYPE CRATEDB
    ADD CRATEDB_CONFIG
        WITH HOST "cratedb.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot"
        WITH USERNAME "crate"
        WITH PASSWORD "secure_password"
    ADD EVENT PollLatestReadings
        WITH EVERY 5 SECONDS
        WITH DESTINATION_TOPIC "dashboard/sensors/latest"
        WITH QUERY "SELECT device_id, AVG(value) as avg_value, MAX(ts) as last_seen FROM sensor_data WHERE ts > NOW() - INTERVAL '1 minute' GROUP BY device_id ORDER BY device_id"
```

***

## Table Schema Examples

Create tables optimized for time-series:

```sql wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Partitioned time-series table
CREATE TABLE sensor_data (
    ts TIMESTAMP WITH TIME ZONE,
    sensor_id TEXT,
    value DOUBLE PRECISION
) PARTITIONED BY (ts);

-- Metrics with JSON storage
CREATE TABLE metrics (
    ts TIMESTAMP WITH TIME ZONE,
    topic TEXT,
    data OBJECT(DYNAMIC)
) PARTITIONED BY (ts);
```

***

## Troubleshooting

> **Connection Failed**
>
> * Verify HOST and PORT are correct
> * Check CrateDB is running and accepting connections
> * Verify firewall allows connections on port 5432

> **Authentication Failed**
>
> * Verify USERNAME and PASSWORD are correct
> * Check user has permissions on the DATABASE

> **Query Errors**
>
> * Verify table exists and has correct schema
> * Check column types match inserted data

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[Snowflake Connector](./snowflake)**
>
> Configure Snowflake cloud data warehouse.


# File Storage Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/file-storage

Store MQTT data to local CSV and JSON files for simple persistence and backups

## File Storage Overview

The `FILE_STORAGE` connector writes MQTT messages to local CSV or JSON files. It provides simple persistence for logging, backups, and data export without requiring a database server.

> [!NOTE]
>
> File storage is ideal for simple logging, local backups, and exporting data for offline analysis. Use it when you don't need a full database but want persistent records.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DataLogger WITH TYPE FILE_STORAGE
    ADD FILE_STORAGE_CONFIG
        WITH STORAGE_DIR "/data/logs"
        WITH FORMAT "CSV"
        WITH FILE_PATTERN "{0}.csv"
        WITH APPEND "true"
    ADD EVENT LogSensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "CLEAN:{table: sensor_data, data: {value.json}}"
```

***

## Connection Configuration

### FILE\_STORAGE\_CONFIG Parameters

**STORAGE\_DIR** `string` *required*

Directory path for storing files.

> **Storage Location Options**
>
> **FILE\_PATTERN** `string`
>
> File name pattern. `{0}` is replaced with the table name. Default: `{0}.csv` for CSV and `{0}.json` for JSON.
>
> `{0}` is the only placeholder. Others, such as `{date}`, are not supported: the connector fails when it writes. For daily files, publish to a table name that includes the date.

> **Format**
>
> **FORMAT** `string`
>
> File format: `CSV` or `JSON`. Default: JSON.
>
> **CSV\_DELIMITER** `string`
>
> CSV delimiter character. Default: comma (`,`).

> **Write Options**
>
> **APPEND** `boolean`
>
> Append to existing files. Default: true.
>
> **INCLUDE\_TIMESTAMP** `boolean`
>
> Auto-add timestamp field. Default: false.
>
> **MAX\_RECORDS** `integer`
>
> JSON only: the most records a file keeps. Older records are dropped once the file is full. Default: 10000. Files are not rotated.

> **Timestamp**
>
> **DATE\_FORMAT** `string`
>
> Timestamp format string. Default: `yyyy-MM-dd HH:mm:ss`.

> [!WARNING]
>
> **Use environment variables for paths in production.** Keep deployment-specific values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH STORAGE_DIR GET ENV "STORAGE_PATH"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## CLEAN Query Format

File storage connectors use the CLEAN format:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH QUERY "CLEAN:{table: <name>, data: {value.json}}"
```

The `table` name is used in the file pattern with `{0}`.

***

## Writing Data

**CSV Logging**

Log sensor data to daily CSV files:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CSVLogger WITH TYPE FILE_STORAGE
    ADD FILE_STORAGE_CONFIG
        WITH STORAGE_DIR "/data/logs"
        WITH FORMAT "CSV"
        WITH FILE_PATTERN "{0}.csv"
        WITH APPEND "true"
        WITH CSV_DELIMITER ","
        WITH INCLUDE_TIMESTAMP "true"
        WITH MAX_RECORDS "10000"
    ADD EVENT LogSensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "file/status"
        WITH QUERY "CLEAN:{table: sensor_data, data: {value.json}}"
```

Creates files like: `sensor_data_2025-01-15.csv`

**JSON Storage**

Store events as JSON lines:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR JSONLogger WITH TYPE FILE_STORAGE
    ADD FILE_STORAGE_CONFIG
        WITH STORAGE_DIR "/data/json"
        WITH FORMAT "JSON"
        WITH FILE_PATTERN "{0}.json"
        WITH APPEND "true"
        WITH INCLUDE_TIMESTAMP "true"
        WITH MAX_RECORDS "5000"
    ADD EVENT LogEvents
        WITH SOURCE_TOPIC "events/#"
        WITH DESTINATION_TOPIC "file/json/status"
        WITH QUERY "CLEAN:{table: events, data: {value.json}}"
```

**Multiple Files**

Connector to different files by data type:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiFileLogger WITH TYPE FILE_STORAGE
    ADD FILE_STORAGE_CONFIG
        WITH STORAGE_DIR "/data/logs"
        WITH FORMAT "CSV"
        WITH FILE_PATTERN "{0}.csv"
        WITH APPEND "true"
        WITH INCLUDE_TIMESTAMP "true"
    
    ADD EVENT LogTemperature
        WITH SOURCE_TOPIC "sensors/+/temperature"
        WITH QUERY "CLEAN:{table: temperature, data: {value.json}}"
    
    ADD EVENT LogPressure
        WITH SOURCE_TOPIC "sensors/+/pressure"
        WITH QUERY "CLEAN:{table: pressure, data: {value.json}}"
    
    ADD EVENT LogAlerts
        WITH SOURCE_TOPIC "alerts/#"
        WITH QUERY "CLEAN:{table: alerts, data: {value.json}}"
```

Creates: `temperature_2025-01-15.csv`, `pressure_2025-01-15.csv`, `alerts_2025-01-15.csv`

**Backup Storage**

Create a rolling backup file that keeps the newest records:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BackupStorage WITH TYPE FILE_STORAGE
    ADD FILE_STORAGE_CONFIG
        WITH STORAGE_DIR "/backup/mqtt"
        WITH FORMAT "JSON"
        WITH FILE_PATTERN "{0}.json"
        WITH APPEND "true"
        WITH MAX_RECORDS "100000"
        WITH INCLUDE_TIMESTAMP "true"
    ADD EVENT BackupAll
        WITH SOURCE_TOPIC "#"
        WITH QUERY "CLEAN:{table: mqtt_backup, data: {value.json}}"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "DataLogger"
>         WITH TABLE "sensor_data"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support read queries to retrieve data from stored files. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`. File Storage read queries use the CLEAN format with `filter`, `sort`, and `limit` instead of SQL:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DataLogger WITH TYPE FILE_STORAGE
    ADD FILE_STORAGE_CONFIG
        WITH STORAGE_DIR "/data/logs"
        WITH FORMAT "CSV"
        WITH FILE_PATTERN "{0}.csv"
        WITH APPEND "true"
    ADD EVENT GetLatestEntry
        WITH SOURCE_TOPIC "file/query/latest"
        WITH DESTINATION_TOPIC "file/result/latest"
        WITH QUERY "CLEAN:{table: sensor_data, filter: {\"sensor_id\": \"{payload}\"}, sort: {\"timestamp\": -1}, limit: 1}"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   file/query/latest
Payload: temp001
```

The matching record is published to `file/result/latest`, where your actions or external clients can consume it.

### CLEAN Read Operators

| SQL Equivalent | File Storage CLEAN Syntax |
| - | - |
| `SELECT *` | `{"table": "x"}` |
| `WHERE a = 1` | `filter: {"a": 1}` |
| `WHERE a > 10` | `filter: {"a": {"$gt": 10}}` |
| `ORDER BY a DESC` | `sort: {"a": -1}` |
| `LIMIT 10` | `limit: 10` |
| `OFFSET 5` | `skip: 5` |
| `SELECT a, b` | `projection: {"a": 1, "b": 1}` |

***

## File Pattern Placeholders

| Placeholder | Description | Example |
| - | - | - |
| `{0}` | Table name from CLEAN query | `sensor_data` |

`{0}` is the only supported placeholder. A pattern with others, such as `{date}`, fails when the connector writes.

***

## Output Examples

### CSV Output

```csv wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
timestamp,sensor_id,temperature,humidity
2025-01-15 10:30:00,temp001,23.5,65
2025-01-15 10:30:05,temp002,24.1,62
```

### JSON Output (JSON Lines format)

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"timestamp":"2025-01-15T10:30:00Z","sensor_id":"temp001","temperature":23.5,"humidity":65}
{"timestamp":"2025-01-15T10:30:05Z","sensor_id":"temp002","temperature":24.1,"humidity":62}
```

***

## Troubleshooting

> **Permission Denied**
>
> * Verify STORAGE\_DIR exists
> * Check write permissions on directory
> * Ensure Coreflux process has access

> **File Not Created**
>
> * Verify STORAGE\_DIR path is correct
> * Check disk space is available
> * Ensure directory is writable

> **Data Not Appearing**
>
> * Verify SOURCE\_TOPIC matches incoming messages
> * Check QUERY syntax is correct
> * Verify APPEND is set correctly

> **Connector fails to write**
>
> * `FILE_PATTERN` accepts only `{0}` (the table name). Remove other placeholders such as `{date}`.
> * For JSON, `MAX_RECORDS` caps the file and drops the oldest records. Files are not rotated.

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[PostgreSQL Connector](./postgresql)**
>
> Configure PostgreSQL database storage.


# MariaDB Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/mariadb

Store MQTT data in MariaDB with automatic query execution and MySQL compatibility

## MariaDB Overview

The `MARIADB` connector stores MQTT messages in MariaDB databases. MariaDB is a MySQL-compatible database with enhanced features and performance optimizations.

> [!NOTE]
>
> MariaDB offers drop-in MySQL compatibility with additional features like improved replication and storage engines. Use the same configuration as MySQL with the `MARIADB` connector type.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO readings (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
```

***

## Connection Configuration

### SQL\_CONFIG Parameters

**SERVER** `string` *required*

MariaDB server hostname or IP address.

**DATABASE** `string` *required*

Target database name.

**USERNAME** `string` *required*

Database username.

**PASSWORD** `string` *required*

Database password.

> **Optional Settings**
>
> **PORT** `integer`
>
> MariaDB port. Default: 3306.
>
> **USE\_SSL** `boolean`
>
> Enable SSL connection. Default: false.

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH SERVER GET ENV "DB_HOST"
> WITH USERNAME GET ENV "DB_USER"
> WITH PASSWORD GET SECRET "DB_PASSWORD"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## Writing Data

**Basic Storage**

Store sensor data in MariaDB:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorStorage WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "INSERT INTO sensor_data (timestamp, topic, payload) VALUES (NOW(), '{source_topic}', '{value.json}')"
```

**With SSL**

Secure connection:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecureStorage WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.cloud.com"
        WITH PORT '3306'
        WITH DATABASE "production"
        WITH USERNAME "app_user"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
    ADD EVENT StoreEvent
        WITH SOURCE_TOPIC "events/#"
        WITH QUERY "INSERT INTO events (ts, topic, data) VALUES (NOW(), '{source_topic}', '{value.json}')"
```

**UPSERT**

Insert a record or update it if a duplicate key exists. MariaDB supports both `ON DUPLICATE KEY UPDATE` (MySQL-compatible) and `ON CONFLICT` (PostgreSQL-compatible in newer versions):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT RegisterDevice
        WITH SOURCE_TOPIC "devices/+/registered"
        WITH QUERY "INSERT INTO devices (device_id, name, area, active, updated_at) VALUES ('{value.json.device_id}', '{value.json.name}', '{value.json.area}', 1, NOW()) ON DUPLICATE KEY UPDATE name = VALUES(name), area = VALUES(area), updated_at = NOW()"
```

**UPDATE**

Modify existing records when a status change arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT UpdateDeviceStatus
        WITH SOURCE_TOPIC "devices/+/status"
        WITH QUERY "UPDATE devices SET current_status = '{value.json.status}', last_seen = NOW() WHERE device_id = '{value.json.device_id}'"
```

**DELETE**

Remove records on a decommission or cleanup event:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT DecommissionDevice
        WITH SOURCE_TOPIC "devices/+/decommissioned"
        WITH QUERY "DELETE FROM devices WHERE device_id = '{value.json.device_id}' AND active = 0"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "SensorStorage"
>         WITH TABLE "sensor_data"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support SELECT queries to read data back from the database. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "SELECT sensor_id, value FROM sensor_data WHERE sensor_id = '{payload}' ORDER BY timestamp DESC LIMIT 1"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   db/query/latest
Payload: temp001
```

The query result is published to `db/result/latest`, where your actions or external clients can consume it.

### Timed Polling

EVENTs can also run SELECT queries on a fixed schedule using `WITH EVERY`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MARIADB
    ADD SQL_CONFIG
        WITH SERVER "mariadb.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT PollActiveDevices
        WITH EVERY 10 SECONDS
        WITH DESTINATION_TOPIC "dashboard/devices/active"
        WITH QUERY "SELECT device_id, name, current_status, last_seen FROM devices WHERE active = 1 ORDER BY name"
```

***

## Troubleshooting

> **Connection Refused**
>
> * Verify SERVER and PORT are correct
> * Check MariaDB is running and accepting connections
> * Verify firewall allows connections on port 3306

> **Authentication Failed**
>
> * Verify USERNAME and PASSWORD are correct
> * Check user has permissions on the DATABASE
> * Verify user can connect from your host

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[SQL Server Connector](./sqlserver)**
>
> Configure Microsoft SQL Server storage.


# MongoDB Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/mongodb

Store MQTT data in MongoDB with flexible document schemas and CLEAN query format

## MongoDB Overview

The `MONGODB` connector stores MQTT messages as documents in MongoDB collections. It uses the CLEAN query format for simplified JSON syntax and supports flexible schemas for IoT data.

> [!NOTE]
>
> MongoDB is ideal for IoT data with varying schemas. Store sensor readings, events, and logs without defining rigid table structures upfront.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:password@mongodb.example.com:27017/iot?authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "CLEAN:{collection: readings, document: {sensor_id: {sensor_id}, value: {value.json}, timestamp: {timestamp}}}"
```

***

## Connection Configuration

### MONGODB\_CONFIG Parameters

**CONNECTION\_STRING** `string` *required*

MongoDB connection URI. Format: `mongodb://user:password@host:port/database?options`

> **Optional Settings**
>
> **DATABASE** `string`
>
> Target database name (can also be specified in connection string).

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH CONNECTION_STRING GET SECRET "MONGO_CONNECTION_STRING"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## CLEAN Query Format

MongoDB connectors use the CLEAN format for simplified document insertion:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH QUERY "CLEAN:{collection: <name>, document: {<field>: <value>, ...}}"
```

### CLEAN Placeholders

| Placeholder | Description |
| - | - |
| `{value.json}` | Full JSON payload as embedded document |
| `{value.json.field}` | Specific field from JSON payload |
| `{timestamp}` | Message timestamp |
| `{source_topic}` | Original MQTT topic |
| `{field}` | Field extracted from topic path |

***

## Event Configuration

### EVENT Parameters

**SOURCE\_TOPIC** `string` *required*

MQTT topic pattern that triggers the INSERT. Supports wildcards.

**QUERY** `string` *required*

CLEAN format query for document insertion.

> **Optional Settings**
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to publish operation status.

***

## Writing Data

**Basic Document Storage**

Store sensor readings as documents:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorStorage WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://iot_user:password@mongodb.example.com:27017/iot?authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH DESTINATION_TOPIC "db/mongo/status"
        WITH QUERY "CLEAN:{collection: readings, document: {timestamp: {timestamp}, topic: {source_topic}, data: {value.json}}}"
```

**Structured Documents**

Create structured documents with specific fields:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR StructuredStorage WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:pass@mongodb.example.com:27017/iot"
        WITH DATABASE "iot"
    ADD EVENT StoreSensor
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH QUERY "CLEAN:{collection: sensor_data, document: {sensor_id: {sensor_id}, temperature: {value.json.temperature}, humidity: {value.json.humidity}, recorded_at: {timestamp}}}"
```

**Input at** `sensors/temp001/data`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"temperature": 23.5, "humidity": 65}
```

**Stored document:**

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "sensor_id": "temp001",
  "temperature": 23.5,
  "humidity": 65,
  "recorded_at": "2025-01-15T10:30:00Z"
}
```

**Multiple Collections**

Connector to different collections based on topic:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiCollection WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:pass@mongodb.example.com:27017/iot"
        WITH DATABASE "iot"
    
    ADD EVENT StoreSensors
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "CLEAN:{collection: sensors, document: {topic: {source_topic}, data: {value.json}, ts: {timestamp}}}"
    
    ADD EVENT StoreAlerts
        WITH SOURCE_TOPIC "alerts/#"
        WITH QUERY "CLEAN:{collection: alerts, document: {topic: {source_topic}, alert: {value.json}, ts: {timestamp}}}"
    
    ADD EVENT StoreEvents
        WITH SOURCE_TOPIC "events/#"
        WITH QUERY "CLEAN:{collection: events, document: {topic: {source_topic}, event: {value.json}, ts: {timestamp}}}"
```

**Replica Set**

Connect to a MongoDB replica set:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ReplicaSetStorage WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:pass@mongo1.example.com:27017,mongo2.example.com:27017,mongo3.example.com:27017/iot?replicaSet=rs0&authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT StoreData
        WITH SOURCE_TOPIC "data/#"
        WITH QUERY "CLEAN:{collection: data, document: {topic: {source_topic}, payload: {value.json}, timestamp: {timestamp}}}"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "SensorStorage"
>         WITH TABLE "readings"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support read queries to retrieve data from the database. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`. MongoDB read queries use the CLEAN format with `filter`, `sort`, and `limit` instead of SQL:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:password@mongodb.example.com:27017/iot?authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "CLEAN:{collection: readings, filter: \"{\"sensor_id\": \"{payload}\"}\", sort: \"timestamp desc\", limit: 1}"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   db/query/latest
Payload: temp001
```

The matching document is published to `db/result/latest`, where your actions or external clients can consume it.

### CLEAN Read Operators

| SQL Equivalent | MongoDB CLEAN Syntax |
| - | - |
| `SELECT *` | `{}` |
| `WHERE a = 1` | `filter: "{\"a\": 1}"` |
| `WHERE a > 10` | `filter: "{\"a\": {\"$gt\": 10}}"` |
| `ORDER BY a DESC` | `sort: "a desc"` |
| `LIMIT 10` | `limit: 10` |
| `SELECT a, b` | `projection: "a, b"` |

***

## Connection String Examples

| Scenario | Connection String |
| - | - |
| Local | `mongodb://localhost:27017/iot` |
| Authenticated | `mongodb://user:password@host:27017/iot?authSource=admin` |
| Replica Set | `mongodb://host1:27017,host2:27017/iot?replicaSet=rs0` |
| Atlas | `mongodb+srv://user:password@cluster.mongodb.net/iot` |

***

## Troubleshooting

> **Connection Failed**
>
> * Verify CONNECTION\_STRING is correct
> * Check MongoDB is running and accessible
> * Verify firewall allows connections on port 27017
> * For Atlas, ensure IP whitelist includes your server

> **Authentication Failed**
>
> * Verify username and password in connection string
> * Check authSource parameter matches authentication database
> * Verify user has permissions on target database

> **CLEAN Query Errors**
>
> * Verify collection name is valid
> * Check placeholder names match topic structure
> * Ensure document structure is valid JSON

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[OpenSearch Connector](./opensearch)**
>
> Configure OpenSearch for search and analytics.


# MySQL Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/mysql

Store MQTT data in MySQL with automatic query execution and SSL support

## MySQL Overview

The `MYSQL` connector stores MQTT messages in MySQL databases. It supports SSL connections, parameterized queries, and automatic reconnection for reliable data persistence.

> [!NOTE]
>
> MySQL is ideal for web applications and general-purpose data storage. Its wide ecosystem support makes it a reliable choice for most IoT data persistence needs.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO readings (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
```

***

## Connection Configuration

### SQL\_CONFIG Parameters

**SERVER** `string` *required*

MySQL server hostname or IP address.

**DATABASE** `string` *required*

Target database name.

**USERNAME** `string` *required*

Database username.

**PASSWORD** `string` *required*

Database password.

> **Optional Settings**
>
> **PORT** `integer`
>
> MySQL port. Default: 3306.
>
> **USE\_SSL** `boolean`
>
> Enable SSL connection. Default: false.
>
> **CONNECTION\_TIMEOUT** `integer`
>
> Connection timeout in seconds. Default: 30.

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH SERVER GET ENV "DB_HOST"
> WITH USERNAME GET ENV "DB_USER"
> WITH PASSWORD GET SECRET "DB_PASSWORD"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## Event Configuration

### EVENT Parameters

**SOURCE\_TOPIC** `string` *required*

MQTT topic pattern that triggers the INSERT. Supports wildcards.

**QUERY** `string` *required*

SQL INSERT statement with placeholders for dynamic values.

> **Optional Settings**
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to publish query result status.

### Query Placeholders

| Placeholder | Description |
| - | - |
| `{value.json}` | Full JSON payload |
| `{value.json.field}` | Specific field from JSON |
| `{timestamp}` | Message timestamp |
| `{source_topic}` | Original MQTT topic |
| `{field}` | Field extracted from topic path |

***

## Writing Data

**Basic Sensor Storage**

Store sensor readings with timestamps:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TemperatureDB WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreTemperature
        WITH SOURCE_TOPIC "sensors/+/temperature"
        WITH QUERY "INSERT INTO temperature_readings (recorded_at, sensor_id, value) VALUES (NOW(), '{sensor_id}', {value.json.value})"
```

**With SSL**

Secure connection with SSL:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecureDB WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.cloud.com"
        WITH PORT '3306'
        WITH DATABASE "production"
        WITH USERNAME "app_user"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
    ADD EVENT StoreEvent
        WITH SOURCE_TOPIC "events/#"
        WITH QUERY "INSERT INTO events (ts, topic, payload) VALUES (NOW(), '{source_topic}', '{value.json}')"
```

**Multiple Events**

Different tables for different data types:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiTableDB WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    
    ADD EVENT StoreSensorData
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH QUERY "INSERT INTO sensor_data (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
    
    ADD EVENT StoreAlerts
        WITH SOURCE_TOPIC "alerts/+"
        WITH QUERY "INSERT INTO alerts (ts, alert_type, message) VALUES (NOW(), '{alert_type}', '{value.json}')"
```

**UPSERT**

Insert a record or update it if a duplicate key exists. MySQL uses `ON DUPLICATE KEY UPDATE`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT RegisterDevice
        WITH SOURCE_TOPIC "devices/+/registered"
        WITH QUERY "INSERT INTO devices (device_id, name, area, active, updated_at) VALUES ('{value.json.device_id}', '{value.json.name}', '{value.json.area}', 1, NOW()) ON DUPLICATE KEY UPDATE name = VALUES(name), area = VALUES(area), updated_at = NOW()"
```

`ON DUPLICATE KEY UPDATE` fires only when a row with the same unique key already exists — the existing row is updated instead of inserting a duplicate.

**UPDATE**

Modify existing records when a status or value change arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT UpdateDeviceStatus
        WITH SOURCE_TOPIC "devices/+/status"
        WITH QUERY "UPDATE devices SET current_status = '{value.json.status}', last_seen = NOW() WHERE device_id = '{value.json.device_id}'"
```

**DELETE**

Remove records on a decommission or cleanup event:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT DecommissionDevice
        WITH SOURCE_TOPIC "devices/+/decommissioned"
        WITH QUERY "DELETE FROM devices WHERE device_id = '{value.json.device_id}' AND active = 0"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "TemperatureDB"
>         WITH TABLE "temperature_readings"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support SELECT queries to read data back from the database. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "SELECT sensor_id, value FROM readings WHERE sensor_id = '{payload}' ORDER BY ts DESC LIMIT 1"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   db/query/latest
Payload: temp001
```

The query result is published to `db/result/latest`, where your actions or external clients can consume it.

### Timed Polling

EVENTs can also run SELECT queries on a fixed schedule using `WITH EVERY`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE MYSQL
    ADD SQL_CONFIG
        WITH SERVER "mysql.example.com"
        WITH PORT '3306'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT PollActiveDevices
        WITH EVERY 10 SECONDS
        WITH DESTINATION_TOPIC "dashboard/devices/active"
        WITH QUERY "SELECT device_id, name, current_status, last_seen FROM devices WHERE active = 1 ORDER BY name"
```

***

## Table Schema Examples

```sql wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Basic sensor readings
CREATE TABLE sensor_readings (
    id INT AUTO_INCREMENT PRIMARY KEY,
    recorded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    sensor_id VARCHAR(50),
    value DOUBLE
);

-- Event log
CREATE TABLE events (
    id INT AUTO_INCREMENT PRIMARY KEY,
    ts TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    topic VARCHAR(255),
    payload JSON
);
```

***

## Troubleshooting

> **Connection Refused**
>
> * Verify SERVER and PORT are correct
> * Check MySQL is running and accepting connections
> * Verify firewall allows connections on port 3306
> * Check `bind-address` in MySQL configuration

> **Authentication Failed**
>
> * Verify USERNAME and PASSWORD are correct
> * Check user has permissions on the DATABASE
> * Verify user can connect from your host

> **Query Syntax Errors**
>
> * Check placeholder names match topic structure
> * Verify table and column names exist
> * Test query manually in MySQL client first

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[MariaDB Connector](./mariadb)**
>
> Configure MariaDB storage (MySQL-compatible).


# OpenSearch Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/opensearch

Index MQTT data in OpenSearch for real-time search, analytics, and visualization

## OpenSearch Overview

The `OPENSEARCH` connector indexes MQTT messages in OpenSearch for full-text search, real-time analytics, and dashboard visualization. It uses the CLEAN query format for simplified document indexing.

> [!NOTE]
>
> OpenSearch is ideal for log aggregation, metrics visualization, and full-text search across IoT data. Connect it to OpenSearch Dashboards for powerful visualizations.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorIndex WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://opensearch.example.com:9200"
        WITH USERNAME "admin"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
    ADD EVENT IndexSensorReading
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH QUERY "CLEAN:{index: sensor-data, body: {@timestamp: {timestamp}, sensor: {sensor_id}, reading: {value.json}}}"
```

***

## Connection Configuration

### OPENSEARCH\_CONFIG Parameters

**BASE\_URL** `string` *required*

OpenSearch endpoint URL including port (e.g., `https://opensearch.example.com:9200`).

**USERNAME** `string` *required*

OpenSearch username.

**PASSWORD** `string` *required*

OpenSearch password.

> **SSL/Security**
>
> **USE\_SSL** `boolean`
>
> Enable HTTPS. Default: false.
>
> **IGNORE\_CERT\_ERRORS** `boolean`
>
> Ignore certificate validation errors. Default: false.

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH BASE_URL GET ENV "OPENSEARCH_URL"
> WITH USERNAME GET ENV "OPENSEARCH_USER"
> WITH PASSWORD GET SECRET "OPENSEARCH_PASSWORD"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## CLEAN Query Format

OpenSearch connectors use the CLEAN format for document indexing:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH QUERY "CLEAN:{index: <index_name>, body: {<field>: <value>, ...}}"
```

### CLEAN Placeholders

| Placeholder | Description |
| - | - |
| `{value.json}` | Full JSON payload as embedded object |
| `{value.json.field}` | Specific field from JSON payload |
| `{timestamp}` | Message timestamp (use `@timestamp` for Kibana) |
| `{source_topic}` | Original MQTT topic |
| `{field}` | Field extracted from topic path |

***

## Writing Data

**Basic Indexing**

Index sensor data for search:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorIndex WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://opensearch.example.com:9200"
        WITH USERNAME "admin"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
    ADD EVENT IndexReading
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH DESTINATION_TOPIC "search/status"
        WITH QUERY "CLEAN:{index: sensor-data, body: {@timestamp: {timestamp}, sensor_id: {sensor_id}, data: {value.json}}}"
```

**Log Aggregation**

Aggregate application logs:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LogIndex WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://opensearch.example.com:9200"
        WITH USERNAME "admin"
        WITH PASSWORD "admin_password"
        WITH USE_SSL "true"
    ADD EVENT IndexLogs
        WITH SOURCE_TOPIC "logs/+/+"
        WITH QUERY "CLEAN:{index: application-logs, body: {@timestamp: {timestamp}, source: {source_topic}, level: {value.json.level}, message: {value.json.message}}}"
```

**Time-Series Index**

Use date-based index names for time-series:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TimeSeriesIndex WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://opensearch.example.com:9200"
        WITH USERNAME "admin"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
    ADD EVENT IndexMetrics
        WITH SOURCE_TOPIC "metrics/#"
        WITH QUERY "CLEAN:{index: metrics, body: {@timestamp: {timestamp}, topic: {source_topic}, metrics: {value.json}}}"
```

Configure Index Lifecycle Management (ILM) in OpenSearch for automatic rollover.

**Self-Signed Certs**

Connect with certificate validation disabled:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DevIndex WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://localhost:9200"
        WITH USERNAME "admin"
        WITH PASSWORD "admin"
        WITH USE_SSL "true"
        WITH IGNORE_CERT_ERRORS "true"
    ADD EVENT IndexData
        WITH SOURCE_TOPIC "data/#"
        WITH QUERY "CLEAN:{index: dev-data, body: {@timestamp: {timestamp}, topic: {source_topic}, payload: {value.json}}}"
```

> [!WARNING]
>
> Only use IGNORE\_CERT\_ERRORS in development environments.

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "SensorIndex"
>         WITH TABLE "sensor-data"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support search queries to retrieve data from the index. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`. OpenSearch read queries use the CLEAN format with `query`, `sort`, and `size` instead of SQL:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorIndex WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://opensearch.example.com:9200"
        WITH USERNAME "admin"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "search/query/latest"
        WITH DESTINATION_TOPIC "search/result/latest"
        WITH QUERY "CLEAN:{index: sensor-data, query: {\"match\": {\"sensor_id\": \"{payload}\"}}, sort: [{\"@timestamp\": {\"order\": \"desc\"}}], size: 1}"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   search/query/latest
Payload: temp001
```

The matching document is published to `search/result/latest`, where your actions or external clients can consume it.

### CLEAN Read Operators

| SQL Equivalent | OpenSearch CLEAN Syntax |
| - | - |
| `SELECT *` | `query: {"match_all": {}}` |
| `WHERE a = 1` | `query: {"match": {"a": 1}}` |
| `WHERE a > 10` | `query: {"range": {"a": {"gt": 10}}}` |
| `ORDER BY a DESC` | `sort: [{"a": {"order": "desc"}}]` |
| `LIMIT 10` | `size: 10` |
| `OFFSET 5` | `from: 5` |

***

## Index Mapping Example

Create an index with explicit mappings for better search and aggregation:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
PUT /sensor-data
{
  "mappings": {
    "properties": {
      "@timestamp": { "type": "date" },
      "sensor_id": { "type": "keyword" },
      "data": {
        "properties": {
          "temperature": { "type": "float" },
          "humidity": { "type": "float" }
        }
      }
    }
  }
}
```

***

## Troubleshooting

> **Connection Failed**
>
> * Verify BASE\_URL is correct including port
> * Check OpenSearch is running and accessible
> * Verify firewall allows connections on port 9200

> **Authentication Failed**
>
> * Verify USERNAME and PASSWORD are correct
> * Check user has permissions to index documents

> **SSL/Certificate Errors**
>
> * Ensure USE\_SSL matches the endpoint (http vs https)
> * For self-signed certs, set IGNORE\_CERT\_ERRORS "true"
> * Verify certificate chain is complete

> **Index Errors**
>
> * Verify index name is valid (lowercase, no special chars)
> * Check field mappings don't conflict
> * Review OpenSearch logs for detailed errors

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[CrateDB Connector](./cratedb)**
>
> Configure CrateDB for time-series data.


# Data Storage Connectors Overview
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/overview

Store MQTT data in databases including PostgreSQL, MySQL, MongoDB, OpenSearch, Snowflake, and file storage

## Data Storage Integration

Data storage connectors enable automatic persistence of MQTT messages to databases and files. Store sensor data for analytics, create historical archives, aggregate logs, and build time-series datasets—all configured through LoT syntax.

> [!TIP]
>
> **Like a filing cabinet with an assistant.** You can hand your assistant a form (STORE IN with models) and they file it automatically, or you can write specific filing instructions yourself (EVENTs with queries). Either way, your data ends up organized in the right drawer.

## Supported Databases

> **[PostgreSQL](./postgresql)**
>
> Open-source relational database for structured data storage.

> **[MySQL](./mysql)**
>
> Popular relational database with wide ecosystem support.

> **[MariaDB](./mariadb)**
>
> MySQL-compatible database with enhanced features.

> **[SQL Server](./sqlserver)**
>
> Microsoft SQL Server for enterprise environments.

> **[MongoDB](./mongodb)**
>
> Document database for flexible JSON storage.

> **[OpenSearch](./opensearch)**
>
> Real-time analytics, search, and visualization.

> **[CrateDB](./cratedb)**
>
> Distributed SQL optimized for time-series data.

> **[Snowflake](./snowflake)**
>
> Cloud data warehouse for large-scale analytics.

> **[File Storage](./file-storage)**
>
> CSV and JSON file storage for simple persistence.

***

## Database Comparison

| Database | Type | Best For | Query Format |
| - | - | - | - |
| PostgreSQL | Relational | Structured data, complex queries | SQL |
| MySQL | Relational | Web applications, general purpose | SQL |
| MariaDB | Relational | MySQL compatibility with extras | SQL |
| SQL Server | Relational | Enterprise, Windows environments | SQL |
| MongoDB | Document | Flexible schemas, JSON data | CLEAN |
| OpenSearch | Search/Analytics | Full-text search, dashboards | CLEAN |
| CrateDB | Time-Series | High-volume sensor data | SQL |
| Snowflake | Cloud Warehouse | Large-scale analytics | SQL |
| File Storage | File | Simple logging, backups | CLEAN |

> [!NOTE]
>
> **SQL** databases use standard SQL queries. **CLEAN** is a simplified document-style syntax used by non-relational databases and file storage — see [Query Formats](#query-formats) below for details.

***

## How to Build a Data Storage Connector

A data storage connector needs two things: a connection to your database and at least one rule for what to store. You define the connection once, then add events that listen for MQTT messages and run queries — or use a model with `STORE IN` to save data automatically without writing queries at all.

### Quick Example

This complete connector connects to a PostgreSQL database and automatically stores every sensor reading that arrives on `sensors/+/reading`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH DESTINATION_TOPIC "db/status"
        WITH QUERY "INSERT INTO readings (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
```

That's it — the broker handles the rest. The sections below break down each part in detail.

### Step 1: Define the Connector Connection

Every data storage connector starts with a connection configuration. Define the connector type and provide the connection details for your database:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
```

> [!NOTE]
>
> Each database type has its own config block (`SQL_CONFIG`, `MONGODB_CONFIG`, `OPENSEARCH_CONFIG`, etc.). See the specific database page for exact parameters.

> [!WARNING]
>
> The examples on this page use hardcoded credentials for clarity. In production, use environment variables and encrypted secrets to keep sensitive values out of your LoT definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
>     ADD SQL_CONFIG
>         WITH SERVER GET ENV "DB_HOST"
>         WITH PORT GET ENV "DB_PORT"
>         WITH DATABASE GET ENV "DB_NAME"
>         WITH USERNAME GET ENV "DB_USER"
>         WITH PASSWORD GET SECRET "DB_PASSWORD"
> ```
>
> See [Environment Variables and Secrets](/latest/mqtt-broker/secrets-and-env) for setup instructions across Windows, Linux, Docker, and Kubernetes.

### Step 2: Store Data

There are two ways to write data into your database. Choose the approach that fits your use case:

**With Models (STORE IN)**

The `STORE IN` approach ties a model directly to a database connector. Every time an action publishes this model, the record is automatically inserted into the specified table — no EVENT or query needed.

**1. Define a model with STORE IN:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ProductionCount
    ADD "f_event_time" WITH TIMESTAMP "UNIX"
    ADD STRING "machine_id"
    ADD STRING "product_type"
    ADD INT "count"
    STORE IN "ProductionDB"
        WITH TABLE "production_counts"
```

**Store only some records.** Add `WHEN` with a condition on the model's fields. The row is inserted only when the condition is true:

```lot wrap focus={8} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ProductionCount
    ADD "f_event_time" WITH TIMESTAMP "UNIX"
    ADD STRING "machine_id"
    ADD STRING "product_type"
    ADD INT "count"
    STORE IN "ProductionDB"
        WITH TABLE "production_counts"
        WHEN {count} > 0
```

Conditions support comparisons, `AND`/`OR`, string comparisons, and nested fields such as `{data.temperature}`. A field the model doesn't define is rejected at deploy.

**2. Define the connector the model stores into:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "localhost"
        WITH PORT '5432'
        WITH DATABASE "factory"
        WITH USERNAME "postgres"
        WITH PASSWORD "secure_password"
```

**3. Publish the model from an action:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION RecordProduction
ON TOPIC "factory/+/production" DO
    SET "machine" WITH TOPIC POSITION 2
    SET "product" WITH (GET JSON "product_type" IN PAYLOAD AS STRING)
    SET "qty" WITH (GET JSON "count" IN PAYLOAD AS INT)

    PUBLISH MODEL ProductionCount TO "factory/production/recorded" WITH
        machine_id = {machine}
        product_type = {product}
        count = {qty}
```

Every `PUBLISH MODEL` call automatically inserts a row into the `production_counts` table with all the model fields as columns.

**With Events (INSERT)**

The EVENT approach uses explicit SQL or CLEAN queries triggered by MQTT messages arriving on a source topic. You write the query yourself, giving full control over column mapping and transformations.

**Define an EVENT inside the connector:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH DESTINATION_TOPIC "db/status"
        WITH QUERY "INSERT INTO readings (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
```

When a message arrives on any topic matching `sensors/+/reading`, the INSERT query runs with placeholders replaced by actual values from the message.

### Step 3: Read Data (SELECT)

EVENTs also support SELECT queries to read data back from the database. Publish a message to the event's `SOURCE_TOPIC` with your query parameters, and the result is published to `DESTINATION_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "localhost"
        WITH PORT '5432'
        WITH DATABASE "factory"
        WITH USERNAME "postgres"
        WITH PASSWORD "secure_password"
    ADD EVENT GetLatestCount
        WITH QUERY "SELECT MAX(count) as count FROM production_counts WHERE machine_id = '{payload}'"
        WITH SOURCE_TOPIC "factory/production/getLatestCount"
        WITH DESTINATION_TOPIC "factory/production/latest_count_from_db"
```

To trigger this query, publish the machine ID to the source topic:

```
Topic:   factory/production/getLatestCount
Payload: MACHINE-001
```

The query result is published to `factory/production/latest_count_from_db`, where your actions or external clients can consume it.

***

## Common Query Placeholders

These placeholders work across all database connectors:

| Placeholder | Description |
| - | - |
| `{payload}` | Raw MQTT payload (useful in SELECT queries as a parameter) |
| `{value}` | Full MQTT payload as string |
| `{value.json}` | Parsed JSON payload |
| `{value.json.field}` | Specific field from JSON |
| `{timestamp}` | Message timestamp |
| `{source_topic}` | Original MQTT topic |
| `{field}` | Field extracted from topic path |

### Extracting Fields from Topics

For topic `sensors/temp001/reading`, use these placeholders:

| Placeholder | Value |
| - | - |
| `{source_topic}` | `sensors/temp001/reading` |
| `{sensor_id}` | `temp001` (position 2 in topic) |

***

## Query Formats

### SQL Format

For relational databases (PostgreSQL, MySQL, MariaDB, SQL Server, CrateDB, Snowflake):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH QUERY "INSERT INTO sensor_readings (timestamp, sensor_id, value) VALUES ('{timestamp}', '{sensor_id}', '{value.json}')"
```

### CLEAN Format

For document databases and search engines (MongoDB, OpenSearch, File Storage):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH QUERY "CLEAN:{collection: readings, document: {sensor_id: {sensor_id}, value: {value.json}, timestamp: {timestamp}}}"
```

The CLEAN format provides simplified JSON syntax without requiring proper escaping.

***

## Common EVENT Parameters

> **Trigger & Routing**
>
> **SOURCE\_TOPIC** `string` *required*
>
> MQTT topic pattern that triggers the query. For INSERT operations, incoming message data is used to populate placeholders. For SELECT operations, the payload can be used as a query parameter via `{payload}`.
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to publish query results. Required for SELECT queries so the result can be consumed by actions or external clients. Optional for INSERT queries (publishes operation status).

> **Query**
>
> **QUERY** `string` *required*
>
> SQL statement or CLEAN format query with placeholders. Supports both write operations (`INSERT INTO ...`) and read operations (`SELECT ... FROM ...`).

***

## Best Practices

> **Use SSL and Certificates in Production**
>
> Always enable SSL for database connections. Most database connectors support SSL configuration through the config block:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH USE_SSL "true"
> WITH TRUST_SERVER_CERTIFICATE "false"
> ```
>
> When using certificate-based authentication, store certificate passphrases as encrypted secrets rather than in plain text. See [Environment Variables and Secrets](/latest/mqtt-broker/secrets-and-env#secrets) for details.

> **Secure Your Credentials**
>
> Never hardcode passwords or API keys in connector definitions. Use `GET SECRET` for sensitive values and `GET ENV` for non-sensitive configuration like hostnames and ports. Create dedicated database users with minimal permissions for each connector.
>
> See [Environment Variables and Secrets](/latest/mqtt-broker/secrets-and-env) for full setup and deployment instructions.

> **Monitor Database Size**
>
> Implement data retention policies:
>
> * Index lifecycle management
> * Time-based partitioning
> * Automatic cleanup jobs

> **Use STORE IN for Automatic Persistence**
>
> When your data has a consistent schema, use `STORE IN` on a model to automatically insert records every time the model is published. This eliminates the need to write INSERT queries manually:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     ADD STRING "timestamp" WITH TIMESTAMP "UTC"
>     STORE IN "SensorDB"
>         WITH TABLE "sensor_readings"
> ```

> **Use Connection Pooling**
>
> For high-throughput scenarios, configure connection pools where supported.

***

## Next Steps

Choose the database that matches your requirements:

> **[PostgreSQL](./postgresql)**
>
> Start with the most popular open-source database.

> **[MongoDB](./mongodb)**
>
> Store flexible JSON documents.


# PostgreSQL Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/postgresql

Store MQTT data in PostgreSQL and PostgreSQL-compatible databases with automatic query execution and SSL support

## PostgreSQL Overview

The `POSTGRESQL` connector stores MQTT messages in PostgreSQL databases. It supports SSL connections, parameterized queries, and automatic reconnection for reliable data persistence.

Because the connector speaks the **PostgreSQL wire protocol**, it also works with any service built on PostgreSQL — you use the same `POSTGRESQL` connector type and point `SQL_CONFIG` at that provider's host, port, database, and credentials.

| Platform | Typical use |
| - | - |
| **PostgreSQL** | Self-hosted, on-premises, or VM deployments |
| **Tiger Data** | Managed Postgres with TimescaleDB (Tiger Cloud) for time-series and IoT workloads |
| **TimescaleDB** | PostgreSQL extension for hypertables and time-series SQL (self-hosted or on Tiger Data) |
| **Amazon RDS / Aurora PostgreSQL** | AWS-managed relational storage |
| **Azure Database for PostgreSQL** | Microsoft Azure managed Postgres |
| **Google Cloud SQL for PostgreSQL** | GCP managed Postgres |
| **Supabase** | Managed Postgres with realtime APIs, often used for app and dashboard backends |

> [!NOTE]
>
> PostgreSQL is ideal for structured data that requires complex queries, joins, and ACID compliance. Use it when you need relational integrity and powerful SQL capabilities.

> [!TIP]
>
> For **TimescaleDB** or **Tiger Data** (Tiger Cloud), use standard PostgreSQL connection settings — host, port `5432`, database, user, and password from your service dashboard. Create hypertables and time-series schemas in SQL as you would in any Postgres client; the connector executes your `QUERY` strings against that database.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO readings (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
```

***

## Connection Configuration

### SQL\_CONFIG Parameters

**SERVER** `string` *required*

PostgreSQL server hostname or IP address.

**DATABASE** `string` *required*

Target database name.

**USERNAME** `string` *required*

Database username.

**PASSWORD** `string` *required*

Database password.

> **Optional Settings**
>
> **PORT** `integer`
>
> PostgreSQL port. Default: 5432.

> **SSL/Security**
>
> **USE\_SSL** `boolean`
>
> Enable SSL connection. Default: false.
>
> **TRUST\_SERVER\_CERTIFICATE** `boolean`
>
> Trust server certificate without validation. Default: false.

> **Timeouts**
>
> **CONNECTION\_TIMEOUT** `integer`
>
> Connection timeout in seconds. Default: 30.
>
> **COMMAND\_TIMEOUT** `integer`
>
> Command timeout in seconds. Default: 30.

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH SERVER GET ENV "DB_HOST"
> WITH USERNAME GET ENV "DB_USER"
> WITH PASSWORD GET SECRET "DB_PASSWORD"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## Event Configuration

### EVENT Parameters

**SOURCE\_TOPIC** `string` *required*

MQTT topic pattern that triggers the INSERT. Supports wildcards.

**QUERY** `string` *required*

SQL INSERT statement with placeholders for dynamic values.

> **Optional Settings**
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to publish query result status.

### Query Placeholders

| Placeholder | Description |
| - | - |
| `{value.json}` | Full JSON payload |
| `{value.json.field}` | Specific field from JSON |
| `{timestamp}` | Message timestamp |
| `{source_topic}` | Original MQTT topic |
| `{field}` | Field extracted from topic path |

***

## Writing Data

**Basic Sensor Storage**

Store temperature readings with timestamps:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TemperatureDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreTemperature
        WITH SOURCE_TOPIC "sensors/+/temperature"
        WITH DESTINATION_TOPIC "db/status/temperature"
        WITH QUERY "INSERT INTO temperature_readings (recorded_at, sensor_id, value, unit) VALUES (NOW(), '{sensor_id}', {value.json.value}, '{value.json.unit}')"
```

**Input at** `sensors/temp001/temperature`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"value": 23.5, "unit": "celsius"}
```

**With SSL**

Secure connection with SSL:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecureDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.cloud.com"
        WITH PORT '5432'
        WITH DATABASE "production"
        WITH USERNAME "app_user"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
        WITH TRUST_SERVER_CERTIFICATE "false"
    ADD EVENT StoreEvent
        WITH SOURCE_TOPIC "events/#"
        WITH QUERY "INSERT INTO events (ts, topic, payload) VALUES (NOW(), '{source_topic}', '{value.json}')"
```

**Multiple Events**

Different tables for different data types:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiTableDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    
    ADD EVENT StoreSensorData
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH QUERY "INSERT INTO sensor_data (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
    
    ADD EVENT StoreAlerts
        WITH SOURCE_TOPIC "alerts/+"
        WITH QUERY "INSERT INTO alerts (ts, alert_type, message) VALUES (NOW(), '{alert_type}', '{value.json}')"
    
    ADD EVENT StoreMetrics
        WITH SOURCE_TOPIC "metrics/#"
        WITH QUERY "INSERT INTO metrics (ts, topic, data) VALUES (NOW(), '{source_topic}', '{value.json}')"
```

**JSON Column**

Store full payload in JSONB column:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR JSONStorage WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreJSON
        WITH SOURCE_TOPIC "devices/#"
        WITH QUERY "INSERT INTO device_data (ts, topic, payload) VALUES (NOW(), '{source_topic}', '{value.json}'::jsonb)"
```

This allows powerful JSON queries in PostgreSQL:

```sql wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SELECT * FROM device_data WHERE payload->>'temperature' > '25';
```

**UPSERT**

Insert a record, or update it if a conflict on the unique key occurs. Useful for device registration or status tables where duplicate messages are possible:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT RegisterDevice
        WITH SOURCE_TOPIC "devices/+/registered"
        WITH QUERY "INSERT INTO devices (device_id, name, area, active, updated_at) VALUES ('{value.json.device_id}', '{value.json.name}', '{value.json.area}', TRUE, NOW()) ON CONFLICT (device_id) DO UPDATE SET name = EXCLUDED.name, area = EXCLUDED.area, updated_at = NOW()"
```

`ON CONFLICT (device_id) DO UPDATE SET` updates only the changed columns when the device already exists — the row is never duplicated.

**UPDATE**

Modify existing records when a status change or update arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT UpdateDeviceStatus
        WITH SOURCE_TOPIC "devices/+/status"
        WITH QUERY "UPDATE devices SET current_status = '{value.json.status}', last_seen = NOW() WHERE device_id = '{value.json.device_id}'"
```

Only rows matching the `WHERE` clause are modified. Unmatched messages produce no change — no error is raised.

**DELETE**

Remove records when a decommission or cleanup event arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT DecommissionDevice
        WITH SOURCE_TOPIC "devices/+/decommissioned"
        WITH QUERY "DELETE FROM devices WHERE device_id = '{value.json.device_id}' AND active = FALSE"
```

The `AND active = FALSE` guard prevents accidental deletes if a message arrives before the device is properly deactivated.

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "SensorDB"
>         WITH TABLE "sensor_readings"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support SELECT queries to read data back from the database. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "SELECT sensor_id, value FROM readings WHERE sensor_id = '{payload}' ORDER BY ts DESC LIMIT 1"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   db/query/latest
Payload: temp001
```

The query result is published to `db/result/latest`, where your actions or external clients can consume it.

### Timed Polling

EVENTs can also run SELECT queries on a schedule instead of waiting for an MQTT trigger. Use `WITH EVERY` to publish fresh data at a fixed interval:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT PollActiveDevices
        WITH EVERY 10 SECONDS
        WITH DESTINATION_TOPIC "dashboard/devices/active"
        WITH QUERY "SELECT device_id, name, current_status, last_seen FROM devices WHERE active = TRUE ORDER BY name"
```

The query result is published to `dashboard/devices/active` every 10 seconds — no trigger message needed.

***

## Table Schema Examples

Create tables to match your data:

```sql wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Basic sensor readings
CREATE TABLE sensor_readings (
    id SERIAL PRIMARY KEY,
    recorded_at TIMESTAMP DEFAULT NOW(),
    sensor_id VARCHAR(50),
    value DOUBLE PRECISION,
    unit VARCHAR(20)
);

-- Full JSON storage
CREATE TABLE device_data (
    id SERIAL PRIMARY KEY,
    ts TIMESTAMP DEFAULT NOW(),
    topic VARCHAR(255),
    payload JSONB
);

-- Alerts table
CREATE TABLE alerts (
    id SERIAL PRIMARY KEY,
    ts TIMESTAMP DEFAULT NOW(),
    alert_type VARCHAR(50),
    message TEXT
);
```

***

## Troubleshooting

> **Connection Refused**
>
> * Verify SERVER and PORT are correct
> * Check PostgreSQL is running and accepting connections
> * Verify firewall allows connections on port 5432
> * Check `pg_hba.conf` allows your IP address

> **Authentication Failed**
>
> * Verify USERNAME and PASSWORD are correct
> * Check user has permissions on the DATABASE
> * Verify authentication method in `pg_hba.conf`

> **SSL Connection Errors**
>
> * Ensure USE\_SSL matches server requirements
> * For self-signed certs, set TRUST\_SERVER\_CERTIFICATE "true"
> * Verify SSL is enabled on PostgreSQL server

> **Query Syntax Errors**
>
> * Check placeholder names match topic structure
> * Verify table and column names exist
> * Test query manually in psql first
> * Ensure proper escaping for special characters

> **Timeout Errors**
>
> * Increase CONNECTION\_TIMEOUT for slow networks
> * Increase COMMAND\_TIMEOUT for complex queries
> * Check server load and query performance

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[MySQL Connector](./mysql)**
>
> Configure MySQL database storage.


# Snowflake Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/snowflake

Store MQTT data in Snowflake cloud data warehouse for large-scale analytics

## Snowflake Overview

The `SNOWFLAKE` connector stores MQTT messages in Snowflake, a cloud-native data warehouse. It supports high-volume data ingestion with automatic scaling and powerful SQL analytics.

> [!NOTE]
>
> Snowflake is ideal for large-scale analytics, data lakes, and enterprise reporting. Use it when you need to analyze IoT data alongside other business data in the cloud.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorWarehouse WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=myuser;password=mypassword"
        WITH WAREHOUSE "COMPUTE_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "SENSORS"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO SENSOR_READINGS (TIMESTAMP, SENSOR_ID, VALUE) VALUES (CURRENT_TIMESTAMP(), '{sensor_id}', PARSE_JSON('{value.json}'))"
```

***

## Connection Configuration

### SNOWFLAKE\_CONFIG Parameters

**CONNECTION\_STRING** `string` *required*

Snowflake connection string with account, user, and password.

> **Connection Options**
>
> **WAREHOUSE** `string`
>
> Snowflake compute warehouse name.
>
> **DATABASE** `string`
>
> Target database name.
>
> **SCHEMA** `string`
>
> Target schema name. Default: PUBLIC.

> **Authentication**
>
> **ROLE** `string`
>
> Snowflake user role.

> **Performance**
>
> **QUERY\_TIMEOUT** `integer`
>
> Query timeout in seconds. Default: 60.
>
> **POOL\_SIZE** `integer`
>
> Connection pool size. Default: 10.

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH CONNECTION_STRING GET SECRET "SNOWFLAKE_CONNECTION_STRING"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## Writing Data

**Basic Storage**

Store sensor data in Snowflake:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorWarehouse WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=iot_user;password=secure_password"
        WITH WAREHOUSE "IOT_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "SENSORS"
        WITH ROLE "IOT_WRITER"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH DESTINATION_TOPIC "snowflake/status"
        WITH QUERY "INSERT INTO SENSOR_READINGS (TIMESTAMP, SENSOR_ID, VALUE) VALUES (CURRENT_TIMESTAMP(), '{sensor_id}', PARSE_JSON('{value.json}'))"
```

**With Connection Pool**

Optimized for high throughput:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HighVolumeWarehouse WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=iot_user;password=secure_password"
        WITH WAREHOUSE "IOT_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "EVENTS"
        WITH QUERY_TIMEOUT '60'
        WITH POOL_SIZE '20'
    ADD EVENT StoreEvents
        WITH SOURCE_TOPIC "events/#"
        WITH QUERY "INSERT INTO EVENT_LOG (TIMESTAMP, TOPIC, PAYLOAD) VALUES (CURRENT_TIMESTAMP(), '{source_topic}', PARSE_JSON('{value.json}'))"
```

**Multiple Tables**

Connector to different tables:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiTableWarehouse WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=iot_user;password=secure_password"
        WITH WAREHOUSE "IOT_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "PUBLIC"
    
    ADD EVENT StoreSensors
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "INSERT INTO SENSORS (TS, TOPIC, DATA) VALUES (CURRENT_TIMESTAMP(), '{source_topic}', PARSE_JSON('{value.json}'))"
    
    ADD EVENT StoreAlerts
        WITH SOURCE_TOPIC "alerts/#"
        WITH QUERY "INSERT INTO ALERTS (TS, TOPIC, DATA) VALUES (CURRENT_TIMESTAMP(), '{source_topic}', PARSE_JSON('{value.json}'))"
```

**UPSERT**

Snowflake uses `MERGE INTO` to insert or update depending on whether a matching row exists:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=iot_user;password=secure_password"
        WITH WAREHOUSE "IOT_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "DEVICES"
    ADD EVENT RegisterDevice
        WITH SOURCE_TOPIC "devices/+/registered"
        WITH QUERY "MERGE INTO DEVICES AS target USING (SELECT '{value.json.device_id}' AS device_id, '{value.json.name}' AS name, '{value.json.area}' AS area) AS source ON target.DEVICE_ID = source.device_id WHEN MATCHED THEN UPDATE SET NAME = source.name, AREA = source.area, UPDATED_AT = CURRENT_TIMESTAMP() WHEN NOT MATCHED THEN INSERT (DEVICE_ID, NAME, AREA, ACTIVE, UPDATED_AT) VALUES (source.device_id, source.name, source.area, TRUE, CURRENT_TIMESTAMP())"
```

**UPDATE**

Modify existing records when a status change arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=iot_user;password=secure_password"
        WITH WAREHOUSE "IOT_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "DEVICES"
    ADD EVENT UpdateDeviceStatus
        WITH SOURCE_TOPIC "devices/+/status"
        WITH QUERY "UPDATE DEVICES SET CURRENT_STATUS = '{value.json.status}', LAST_SEEN = CURRENT_TIMESTAMP() WHERE DEVICE_ID = '{value.json.device_id}'"
```

**DELETE**

Remove records on a decommission or cleanup event:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=iot_user;password=secure_password"
        WITH WAREHOUSE "IOT_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "DEVICES"
    ADD EVENT DecommissionDevice
        WITH SOURCE_TOPIC "devices/+/decommissioned"
        WITH QUERY "DELETE FROM DEVICES WHERE DEVICE_ID = '{value.json.device_id}' AND ACTIVE = FALSE"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "SensorWarehouse"
>         WITH TABLE "SENSOR_READINGS"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support SELECT queries to read data back from the database. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorWarehouse WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=myuser;password=mypassword"
        WITH WAREHOUSE "COMPUTE_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "SENSORS"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "SELECT SENSOR_ID, VALUE FROM SENSOR_READINGS WHERE SENSOR_ID = '{payload}' ORDER BY TIMESTAMP DESC LIMIT 1"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   db/query/latest
Payload: temp001
```

The query result is published to `db/result/latest`, where your actions or external clients can consume it.

### Timed Polling

EVENTs can also run SELECT queries on a fixed schedule using `WITH EVERY`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SNOWFLAKE
    ADD SNOWFLAKE_CONFIG
        WITH CONNECTION_STRING "account=myaccount;user=iot_user;password=secure_password"
        WITH WAREHOUSE "IOT_WH"
        WITH DATABASE "IOT_DATA"
        WITH SCHEMA "DEVICES"
    ADD EVENT PollActiveDevices
        WITH EVERY 30 SECONDS
        WITH DESTINATION_TOPIC "dashboard/devices/active"
        WITH QUERY "SELECT DEVICE_ID, NAME, CURRENT_STATUS, LAST_SEEN FROM DEVICES WHERE ACTIVE = TRUE ORDER BY NAME"
```

***

## Table Schema Examples

```sql wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Sensor readings with VARIANT for JSON
CREATE TABLE SENSOR_READINGS (
    ID NUMBER AUTOINCREMENT,
    TIMESTAMP TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP(),
    SENSOR_ID VARCHAR(50),
    VALUE VARIANT
);

-- Event log
CREATE TABLE EVENT_LOG (
    ID NUMBER AUTOINCREMENT,
    TIMESTAMP TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP(),
    TOPIC VARCHAR(255),
    PAYLOAD VARIANT
);
```

***

## Connection String Format

```
account=<account_identifier>;user=<username>;password=<password>
```

| Component | Description |
| - | - |
| `account` | Snowflake account identifier (e.g., `xy12345.us-east-1`) |
| `user` | Snowflake username |
| `password` | User password |

***

## Troubleshooting

> **Connection Failed**
>
> * Verify account identifier is correct
> * Check username and password
> * Ensure warehouse exists and is running
> * Verify network allows Snowflake connections

> **Permission Errors**
>
> * Verify ROLE has INSERT permissions
> * Check user has access to WAREHOUSE
> * Ensure user can access DATABASE and SCHEMA

> **Query Timeout**
>
> * Increase QUERY\_TIMEOUT value
> * Check warehouse size is adequate
> * Verify warehouse is not suspended

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[File Storage Connector](./file-storage)**
>
> Configure local file storage.


# SQL Server Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/data-storage/sqlserver

Store MQTT data in Microsoft SQL Server with automatic query execution and enterprise features

## SQL Server Overview

The `SQLSERVER` connector stores MQTT messages in Microsoft SQL Server databases. It supports Windows and SQL authentication, SSL connections, and enterprise features.

> [!NOTE]
>
> SQL Server is ideal for enterprise environments, especially those integrated with Microsoft ecosystems. It offers advanced features like Always On availability and native JSON support.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.example.com"
        WITH PORT '1433'
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO Readings (RecordedAt, SensorId, Value) VALUES (GETDATE(), '{sensor_id}', '{value.json}')"
```

***

## Connection Configuration

### SQL\_CONFIG Parameters

**SERVER** `string` *required*

SQL Server hostname or IP address. Can include instance name (e.g., `server\instance`).

**DATABASE** `string` *required*

Target database name.

**USERNAME** `string` *required*

SQL Server username.

**PASSWORD** `string` *required*

SQL Server password.

> **Optional Settings**
>
> **PORT** `integer`
>
> SQL Server port. Default: 1433.
>
> **USE\_SSL** `boolean`
>
> Enable SSL connection. Default: false.
>
> **TRUST\_SERVER\_CERTIFICATE** `boolean`
>
> Trust server certificate without validation. Default: false.

> [!WARNING]
>
> **Never hardcode credentials in production.** Use environment variables and encrypted secrets to keep sensitive values out of your connector definitions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH SERVER GET ENV "DB_HOST"
> WITH USERNAME GET ENV "DB_USER"
> WITH PASSWORD GET SECRET "DB_PASSWORD"
> ```
>
> See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for setup and usage.

***

## Writing Data

**Basic Storage**

Store sensor data in SQL Server:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorStorage WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.example.com"
        WITH PORT '1433'
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO SensorReadings (Timestamp, SensorId, Value) VALUES (GETDATE(), '{sensor_id}', '{value.json}')"
```

**With SSL**

Secure connection with trusted certificate:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecureStorage WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.cloud.com"
        WITH PORT '1433'
        WITH DATABASE "Production"
        WITH USERNAME "app_user"
        WITH PASSWORD "secure_password"
        WITH USE_SSL "true"
        WITH TRUST_SERVER_CERTIFICATE "true"
    ADD EVENT StoreEvent
        WITH SOURCE_TOPIC "events/#"
        WITH QUERY "INSERT INTO Events (Timestamp, Topic, Payload) VALUES (GETDATE(), '{source_topic}', '{value.json}')"
```

**Named Instance**

Connect to a named SQL Server instance:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR InstanceStorage WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "server.example.com\\MSSQLSERVER"
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreData
        WITH SOURCE_TOPIC "data/#"
        WITH QUERY "INSERT INTO DataLog (Timestamp, Topic, Data) VALUES (GETDATE(), '{source_topic}', '{value.json}')"
```

**UPSERT**

SQL Server uses the `MERGE` statement for upsert logic — insert a row if it doesn't exist, update it if it does:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.example.com"
        WITH PORT '1433'
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT RegisterDevice
        WITH SOURCE_TOPIC "devices/+/registered"
        WITH QUERY "MERGE Devices AS target USING (SELECT '{value.json.device_id}' AS device_id, '{value.json.name}' AS name, '{value.json.area}' AS area) AS source ON (target.DeviceId = source.device_id) WHEN MATCHED THEN UPDATE SET Name = source.name, Area = source.area, UpdatedAt = GETDATE() WHEN NOT MATCHED THEN INSERT (DeviceId, Name, Area, Active, UpdatedAt) VALUES (source.device_id, source.name, source.area, 1, GETDATE());"
```

**UPDATE**

Modify existing records when a status change arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.example.com"
        WITH PORT '1433'
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT UpdateDeviceStatus
        WITH SOURCE_TOPIC "devices/+/status"
        WITH QUERY "UPDATE Devices SET CurrentStatus = '{value.json.status}', LastSeen = GETDATE() WHERE DeviceId = '{value.json.device_id}'"
```

**DELETE**

Remove records on a decommission or cleanup event:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.example.com"
        WITH PORT '1433'
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT DecommissionDevice
        WITH SOURCE_TOPIC "devices/+/decommissioned"
        WITH QUERY "DELETE FROM Devices WHERE DeviceId = '{value.json.device_id}' AND Active = 0"
```

> [!NOTE]
>
> **Alternative: STORE IN with Models** — Instead of writing EVENT queries, you can bind a [model](/latest/lot-language/models/overview) directly to this connector. Every `PUBLISH MODEL` call automatically inserts a row — no query needed:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> DEFINE MODEL SensorReading
>     ADD STRING "sensor_id"
>     ADD DOUBLE "value"
>     STORE IN "SensorStorage"
>         WITH TABLE "SensorReadings"
> ```
>
> See [Data Storage Overview](./overview#with-models-store-in) for the full STORE IN workflow.

***

## Reading Data

EVENTs also support SELECT queries to read data back from the database. Publish a message to the event's `SOURCE_TOPIC`, and the query result is published to `DESTINATION_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.example.com"
        WITH PORT '1433'
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT GetLatestReading
        WITH SOURCE_TOPIC "db/query/latest"
        WITH DESTINATION_TOPIC "db/result/latest"
        WITH QUERY "SELECT TOP 1 SensorId, Value FROM Readings WHERE SensorId = '{payload}' ORDER BY RecordedAt DESC"
```

To trigger this query, publish the sensor ID to the source topic:

```
Topic:   db/query/latest
Payload: temp001
```

The query result is published to `db/result/latest`, where your actions or external clients can consume it.

### Timed Polling

EVENTs can also run SELECT queries on a fixed schedule using `WITH EVERY`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceRegistry WITH TYPE SQLSERVER
    ADD SQL_CONFIG
        WITH SERVER "sqlserver.example.com"
        WITH PORT '1433'
        WITH DATABASE "IoTData"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT PollActiveDevices
        WITH EVERY 10 SECONDS
        WITH DESTINATION_TOPIC "dashboard/devices/active"
        WITH QUERY "SELECT DeviceId, Name, CurrentStatus, LastSeen FROM Devices WHERE Active = 1 ORDER BY Name"
```

***

## Table Schema Examples

```sql wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Basic sensor readings
CREATE TABLE SensorReadings (
    Id INT IDENTITY(1,1) PRIMARY KEY,
    Timestamp DATETIME2 DEFAULT GETDATE(),
    SensorId NVARCHAR(50),
    Value FLOAT
);

-- JSON storage (SQL Server 2016+)
CREATE TABLE Events (
    Id INT IDENTITY(1,1) PRIMARY KEY,
    Timestamp DATETIME2 DEFAULT GETDATE(),
    Topic NVARCHAR(255),
    Payload NVARCHAR(MAX)
);
```

***

## Troubleshooting

> **Connection Refused**
>
> * Verify SERVER and PORT are correct
> * Check SQL Server is running and accepting TCP connections
> * Enable TCP/IP in SQL Server Configuration Manager
> * Verify firewall allows connections on port 1433

> **Authentication Failed**
>
> * Verify USERNAME and PASSWORD are correct
> * Ensure SQL Server authentication is enabled (mixed mode)
> * Check user has permissions on the DATABASE

> **SSL/Certificate Errors**
>
> * Set TRUST\_SERVER\_CERTIFICATE "true" for self-signed certs
> * Verify SSL is configured on SQL Server

***

## Next Steps

> **[Data Storage Connectors Overview](./overview)**
>
> Compare all storage options.

> **[MongoDB Connector](./mongodb)**
>
> Configure MongoDB document storage.


# ADS Connector (Beckhoff)
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/ads

Connect to Beckhoff TwinCAT PLCs using ADS protocol with AutoDiscovery and comprehensive data type support

## ADS Overview

The `ADS` connector enables communication with Beckhoff TwinCAT PLCs and systems using the ADS (Automation Device Specification) protocol. It supports automatic symbol discovery, bidirectional communication, and complex data types including arrays and structures.

> [!TIP]
>
> ADS provides direct, high-performance access to TwinCAT variables. The AutoDiscovery feature can automatically find and expose all PLC symbols as MQTT topics.

> [!WARNING]
>
> The ADS connector is on beta testing. It is planned for a future release.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BeckhoffPLC WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
    ADD MAPPING ProcessData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "GVL_Process.rTemperature"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
```

Set the PLC's AMS Net ID, IP, and ADS port in `ADS_CONFIG`. The broker connects through the AMS router on the broker host, so create that route on the router or the PLC. See [AMS route setup](#ams-route-setup).

***

## AMS Net ID Basics

ADS uses an AMS Net ID for the broker host and one for the PLC. Set the broker host's id on the AMS router. An AMS Net ID is typically the IP address followed by `.1.1`.

| Component | Format | Example |
| - | - | - |
| AMS Net ID | `x.x.x.x.y.y` | `192.168.1.100.1.1` |
| IP portion | First 4 octets | `192.168.1.100` |
| Node portion | Last 2 octets | `.1.1` (usually) |

> [!NOTE]
>
> You can find your TwinCAT system's AMS Net ID in TwinCAT XAE under **SYSTEM** → **Connectors** or by running `adsInfo` on the target.

***

## Connection Configuration

### ADS\_CONFIG Parameters

**LOCAL\_NET\_ID** `string`

Not required. Accepted and not used yet.

**LOCAL\_ROUTE\_TO\_TARGET** `string`

Not required. Accepted and not used yet.

**LOCAL\_HOST\_NAME** `string`

Local host name (optional).

**TARGET\_NET\_ID** `string` *required*

Target PLC's AMS Net ID (format: x.x.x.x.x.x).

**TARGET\_IP** `string` *required*

Target PLC's IP address.

**TARGET\_PORT** `integer`

ADS port. Typically 851 for TwinCAT 3, 801 for TwinCAT 2.

**TARGET\_ROUTE\_TO\_LOCAL** `string`

Not required. Accepted and not used yet.

**TARGET\_USER** `string`

Not required. Accepted and not used yet.

**TARGET\_PASSWORD** `string`

Not required. Accepted and not used yet.

> [!NOTE]
>
> The broker connects through the AMS router on the broker host. Create the AMS route on the router or the PLC yourself. `LOCAL_NET_ID`, `LOCAL_ROUTE_TO_TARGET`, `TARGET_ROUTE_TO_LOCAL`, `TARGET_USER`, and `TARGET_PASSWORD` do not create that route.

**TIMEOUT** `integer`

Limit for each ADS request, in milliseconds. Default: 5000. A value of 0 or below falls back to 5000.

> [!NOTE]
>
> A `SYMBOL` read is 1 request by name. A `SYMBOL` write takes 3 round trips (create handle, write, release handle), so it can take up to 3 × `TIMEOUT` plus a margin of at least 1 s. `INDEX` reads and writes are 1 request. When an ADS error means the PLC is unreachable, such as a timeout or target not found, the route goes to **Reconnecting** instead of staying Connected with BAD tags. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).

### Connection Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD ADS_CONFIG
    WITH TARGET_NET_ID "192.168.1.100.1.1"
    WITH TARGET_IP "192.168.1.100"
    WITH TARGET_PORT 851
    WITH TIMEOUT 5000
```

***

## AutoDiscovery

AutoDiscovery automatically finds all PLC symbols and exposes them as MQTT topics.

### AutoDiscovery Parameters

**AUTO\_DISCOVERY** `boolean`

Enable automatic symbol discovery. Default: false.

**DISCOVERY\_BASE\_TOPIC** `string`

Base MQTT topic for discovered symbols. Default: ads/discovery.

**DISCOVERY\_DEFAULT\_QOS** `integer`

Default QoS for discovered symbols (0-2). Default: 0.

**DISCOVERY\_DEFAULT\_RETAIN** `boolean`

Default retain flag for discovered symbols. Default: false.

**DISCOVERY\_DEFAULT\_TRIGGER** `integer`

Default trigger mode:

* `0` - OnStart (read once at connection)
* `1` - OnChange (publish on value change)
* `2` - Cyclic (poll at interval)

Default: 2.

**DISCOVERY\_DEFAULT\_CYCLE** `integer`

Default polling cycle in milliseconds. Default: 1000.

**DISCOVERY\_FILTER\_INCLUDES** `string`

Include patterns (comma-separated, \* wildcard). Default: \* (all symbols).

**DISCOVERY\_FILTER\_EXCLUDES** `string`

Exclude patterns (comma-separated, \* wildcard).

**DISCOVERY\_MAX\_DEPTH** `integer`

Structure expansion depth. Default: 3.

**DISCOVERY\_PARALLEL\_READING** `boolean`

Enable parallel reading for large projects. Default: false.

**DISCOVERY\_BATCH\_SIZE** `integer`

Batch size for parallel reading. Default: 50.

### AutoDiscovery Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BeckhoffAutoDiscover WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
        WITH AUTO_DISCOVERY "true"
        WITH DISCOVERY_BASE_TOPIC "beckhoff/plc"
        WITH DISCOVERY_FILTER_INCLUDES "GVL_*"
        WITH DISCOVERY_FILTER_EXCLUDES "*_Internal*"
        WITH DISCOVERY_DEFAULT_CYCLE 500
        WITH DISCOVERY_MAX_DEPTH 3
```

***

## TwinCAT Data Types

| Data Type | TwinCAT Type | Size | Description |
| - | - | - | - |
| `BOOL` | BOOL | 1 bit | Boolean value |
| `BYTE` | BYTE | 8 bits | Unsigned 8-bit |
| `SINT` | SINT | 8 bits | Signed 8-bit integer |
| `USINT` | USINT | 8 bits | Unsigned 8-bit integer |
| `WORD` | WORD | 16 bits | Unsigned 16-bit |
| `INT` | INT | 16 bits | Signed 16-bit integer |
| `UINT` | UINT | 16 bits | Unsigned 16-bit integer |
| `DWORD` | DWORD | 32 bits | Unsigned 32-bit |
| `DINT` | DINT | 32 bits | Signed 32-bit integer |
| `UDINT` | UDINT | 32 bits | Unsigned 32-bit integer |
| `LWORD` | LWORD | 64 bits | Unsigned 64-bit |
| `LINT` | LINT | 64 bits | Signed 64-bit integer |
| `ULINT` | ULINT | 64 bits | Unsigned 64-bit integer |
| `REAL` / `FLOAT` | REAL | 32 bits | 32-bit floating point |
| `LREAL` / `DOUBLE` | LREAL | 64 bits | 64-bit floating point |
| `CHAR` | CHAR | 8 bits | Single character |
| `WCHAR` | WCHAR | 16 bits | Wide character |
| `TIME` | TIME | 32 bits | Time duration |
| `DATE` | DATE | 16 bits | Date value |
| `TOD` | TOD | 32 bits | Time of day |
| `STRING` | STRING | Variable | ASCII string; sized with `LENGTH` |
| `ARRAY` | ARRAY | Variable | Array of elements (requires `ARRAY_ELEMENT_TYPE`) |
| `STRUCT` | STRUCT | Variable | Structured data type |

### String sizing

For `STRING` tags, `WITH LENGTH` is the total size in **bytes**, **including the ADS length byte**. It defaults to **256** bytes for reads; writes use an **80**-byte default when no size is supplied. `STRING_SIZE` is accepted as an alias for the same field.

`ARRAY_ELEMENT_LENGTH` is a separate setting for `ARRAY` tags whose elements are `STRING` or `STRUCT` — it does not replace `LENGTH` on scalar string tags.

Read a TwinCAT `STRING` symbol with an explicit read size (256 bytes here; writes default to 80 bytes when `LENGTH` is omitted):

```lot wrap focus={15} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TwinCATStrings WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
    ADD MAPPING Labels
        WITH EVERY 1 SECOND
        ADD TAG ProductLabel
            WITH ADDRESS "GVL_Process.sProductName"
            WITH ADDRESS_TYPE "SYMBOL"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 256
            WITH SOURCE_TOPIC "production/label"
```

***

## TAG Configuration

### Symbol-Based Addressing

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG Temperature
    WITH ADDRESS "GVL_Process.rTemperature"
    WITH ADDRESS_TYPE "SYMBOL"
    WITH DATA_TYPE "REAL"
    WITH SOURCE_TOPIC "plc/temperature"
```

### Index-Based Addressing

For direct memory access using index group and offset:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG DirectValue
    WITH ADDRESS "16448.0"
    WITH ADDRESS_TYPE "INDEX"
    WITH DATA_TYPE "DINT"
    WITH SOURCE_TOPIC "plc/direct"
```

### Array Handling

**ARRAY\_ELEMENT\_TYPE** `string`

Array element type (required for ARRAY): BOOL, INT, REAL, STRING, STRUCT, etc.

**ARRAY\_SIZE** `integer`

Number of elements in the array.

**ARRAY\_ELEMENT\_LENGTH** `integer`

Length of each element in bytes (for STRING/STRUCT arrays).

**ARRAY\_START\_OFFSET** `integer`

Offset in bytes to skip before array data. Default: 0.

**ARRAY\_ELEMENT\_HEADER\_SIZE** `integer`

Header bytes to skip per element. Default: 0.

### Structure Handling

**STRUCT\_FIELD\_DEFINITIONS** `string`

Structure field definitions in format: `name:offset:type:size` (comma-separated).

### String sizing parameter

**LENGTH** `integer`

Total string size in bytes, including the ADS length byte. Default: **256** for reads; **80** for writes when omitted. Alias: `STRING_SIZE`.

***

## Event-Based Operations

For on-demand ADS operations (not polling), use the EVENT syntax. Publish a message to SOURCE\_TOPIC to trigger the operation; the connector executes it and publishes the result to DESTINATION\_TOPIC.

### Supported Operations

| Operation | Description | Query Parameters |
| - | - | - |
| `READ` | Read a symbol value on demand | `symbol`, `data_type` |
| `WRITE` | Write a value to a symbol | `symbol`, `data_type`, `value` |

### Query Parameters

| Parameter | Description | Example |
| - | - | - |
| `operation` | Operation type: `READ` or `WRITE` | `READ` |
| `symbol` | TwinCAT symbol path | `GVL_Process.rTemperature`, `GVL_Control.rSP` |
| `data_type` | TwinCAT data type | `REAL`, `LREAL`, `DINT`, `BOOL`, `INT` |
| `value` | Value to write (WRITE only) | `75.0`, `42`, `true` |

### Read Example

Read a process variable on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadSymbol
    WITH SOURCE_TOPIC "ads/commands/read"
    WITH DESTINATION_TOPIC "ads/responses/read"
    WITH QUERY "{operation: READ, symbol: GVL_Process.rTemperature, data_type: REAL}"
```

### Write Example

Write a setpoint on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT WriteSetpoint
    WITH SOURCE_TOPIC "ads/commands/write"
    WITH DESTINATION_TOPIC "ads/responses/write"
    WITH QUERY "{operation: WRITE, symbol: GVL_Control.rSP, data_type: REAL, value: 75.0}"
```

***

## Complete Examples

**Basic Symbol Reading**

Read PLC variables using symbol names:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TwinCATBasic WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
    ADD MAPPING ProcessVariables
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "GVL_Process.rTemperature"
            WITH ADDRESS_TYPE "SYMBOL"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/process/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "GVL_Process.rPressure"
            WITH ADDRESS_TYPE "SYMBOL"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/process/pressure"
            WITH UNIT "bar"
        ADD TAG RunningState
            WITH ADDRESS "GVL_Process.bRunning"
            WITH ADDRESS_TYPE "SYMBOL"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/process/running"
```

**AutoDiscovery**

Automatically discover and expose all GVL variables:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TwinCATAutoDiscover WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
        WITH AUTO_DISCOVERY "true"
        WITH DISCOVERY_BASE_TOPIC "twincat"
        WITH DISCOVERY_FILTER_INCLUDES "GVL_Production.*,GVL_Process.*"
        WITH DISCOVERY_FILTER_EXCLUDES "*_Debug*,*_Test*"
        WITH DISCOVERY_DEFAULT_CYCLE 500
        WITH DISCOVERY_MAX_DEPTH 2
        WITH DISCOVERY_PARALLEL_READING "true"
        WITH DISCOVERY_BATCH_SIZE 100
```

**Bidirectional Control**

Read process values and write setpoints:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TwinCATControl WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
    ADD MAPPING ControlLoop
        WITH EVERY 200 MILLISECONDS
        ADD TAG ProcessValue
            WITH ADDRESS "GVL_Control.rPV"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/pv"
            WITH UNIT "°C"
        ADD TAG Setpoint
            WITH ADDRESS "GVL_Control.rSP"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/sp"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/sp/write"
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
        ADD TAG Output
            WITH ADDRESS "GVL_Control.rOutput"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/output"
            WITH UNIT "%"
        ADD TAG AutoMode
            WITH ADDRESS "GVL_Control.bAutoMode"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "control/auto"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/auto/write"
```

**Array Data**

Read array values:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TwinCATArrays WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
    ADD MAPPING ArrayData
        WITH EVERY 1 SECOND
        ADD TAG TemperatureArray
            WITH ADDRESS "GVL_Data.arTemperatures"
            WITH DATA_TYPE "ARRAY"
            WITH ARRAY_ELEMENT_TYPE "REAL"
            WITH ARRAY_SIZE 10
            WITH SOURCE_TOPIC "plc/temperatures"
            WITH PUBLISH_MODE "JSON"
        ADD TAG StatusBits
            WITH ADDRESS "GVL_Data.arStatus"
            WITH DATA_TYPE "ARRAY"
            WITH ARRAY_ELEMENT_TYPE "BOOL"
            WITH ARRAY_SIZE 16
            WITH SOURCE_TOPIC "plc/status"
```

**Structure Data**

Read structured data:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TwinCATStruct WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
    ADD MAPPING StructData
        WITH EVERY 500 MILLISECONDS
        ADD TAG MachineData
            WITH ADDRESS "GVL_Machine.stMachineData"
            WITH DATA_TYPE "STRUCT"
            WITH STRUCT_FIELD_DEFINITIONS "Speed:0:REAL:4,Current:4:REAL:4,Status:8:INT:2,ErrorCode:10:WORD:2"
            WITH SOURCE_TOPIC "plc/machine"
            WITH PUBLISH_MODE "JSON"
```

**Combined (Cyclic + On-Demand)**

Continuous monitoring with on-demand read and write events in the same connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FullADSSetup WITH TYPE ADS
    ADD ADS_CONFIG
        WITH TARGET_NET_ID "192.168.1.100.1.1"
        WITH TARGET_IP "192.168.1.100"
        WITH TARGET_PORT 851
    ADD MAPPING ProcessVariables
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "GVL_Process.rTemperature"
            WITH ADDRESS_TYPE "SYMBOL"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "GVL_Process.rPressure"
            WITH ADDRESS_TYPE "SYMBOL"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/pressure"
            WITH UNIT "bar"
    
    ADD EVENT ReadSymbol
        WITH SOURCE_TOPIC "ads/commands/read"
        WITH DESTINATION_TOPIC "ads/responses/read"
        WITH QUERY "{operation: READ, symbol: GVL_Process.rOutput, data_type: REAL}"
    
    ADD EVENT WriteSetpoint
        WITH SOURCE_TOPIC "ads/commands/write"
        WITH DESTINATION_TOPIC "ads/responses/write"
        WITH QUERY "{operation: WRITE, symbol: GVL_Control.rSP, data_type: REAL, value: 0}"
```

The MAPPING continuously reads temperature and pressure. To trigger an on-demand read of the output value, publish any message to `ads/commands/read`. To write a setpoint, publish to `ads/commands/write`.

***

## AMS route setup

The broker connects through the AMS router on the broker host. It does not create the route. Add the AMS route on the router or the PLC yourself.

### On the TwinCAT system

1. Open TwinCAT XAE
2. Go to **SYSTEM** → **Connectors**
3. Add a static route to the broker host:
   * **AMS Net ID**: the broker host's AMS Net ID
   * **Transport Type**: TCP/IP
   * **Address**: the broker host's IP address

`LOCAL_NET_ID`, `LOCAL_ROUTE_TO_TARGET`, `TARGET_ROUTE_TO_LOCAL`, `TARGET_USER`, and `TARGET_PASSWORD` are not required and are not used yet.

***

## Troubleshooting

> **Connection Failed**
>
> * Verify the target AMS Net ID and the route on the router or the PLC
> * Ensure TARGET\_PORT is correct (851 for TC3, 801 for TC2)
> * Verify the firewall allows the ADS port (typically 48898)

> **Symbol Not Found**
>
> * Verify symbol path matches exactly (case-sensitive)
> * Check symbol exists in PLC project
> * Ensure PLC is in RUN mode
> * Use AutoDiscovery to find correct symbol names

> **AutoDiscovery Issues**
>
> * Check DISCOVERY\_FILTER\_INCLUDES patterns
> * Verify DISCOVERY\_MAX\_DEPTH is sufficient
> * For large projects, enable DISCOVERY\_PARALLEL\_READING
> * Check PLC project is compiled and deployed

> **Write Operations Fail**
>
> * Ensure WRITABLE is set to "true"
> * Verify PLC variable is not constant
> * Check value is within MIN\_VALUE/MAX\_VALUE
> * Verify PLC is in RUN mode

> **Timeout Errors**
>
> * Increase TIMEOUT value
> * Check network connectivity
> * Verify TwinCAT runtime is running
> * Reduce DISCOVERY\_BATCH\_SIZE if using AutoDiscovery

***

## Next Steps

> **[Allen-Bradley](./allen-bradley)**
>
> Connect to Rockwell Automation PLCs.

> **[OPC UA Client](./opcua-client)**
>
> Cross-platform OPC UA communication.


# Allen-Bradley Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/allen-bradley

Connect to Rockwell Automation PLCs over EtherNet/IP with symbolic tag names, program scope, UDTs, arrays, and bidirectional writes.

## Connect to Rockwell PLCs by Tag Name

The `ALLEN_BRADLEY` connector connects Coreflux to Rockwell Automation PLCs using **symbolic tag names** over EtherNet/IP. Define an `ALLEN_BRADLEY_CONFIG` block, add TAGs with PLC tag addresses, and publish each data point to its own MQTT topic — with optional scaling, units, deadband, and bidirectional writes.

> [!TIP]
>
> **Like reading labels on a control panel.** Instead of numeric register addresses, you use the same tag names you see in Studio 5000 — `MainCounter`, `Program:MainProgram.Temperature`, `Motor1.Speed`.

> [!NOTE]
>
> For **explicit CIP paths** (`4.100.3.0`), use the [EtherNet/IP connector](./ethernetip) instead. This connector is for symbolic tag-name access; EtherNet/IP is for Class/Instance/Attribute addressing.

### Connector and config aliases

| Alias | Canonical form |
| - | - |
| `TYPE AB` or `TYPE ALLENBRADLEY` | `TYPE ALLEN_BRADLEY` |
| `ADD AB_CONFIG` | `ADD ALLEN_BRADLEY_CONFIG` |

### Key capabilities

* **Symbolic tag names** — controller-scoped, program-scoped, UDT members, and arrays
* **Multiple PLC families** — ControlLogix, CompactLogix, Micro800, MicroLogix, PLC5, SLC500
* **TAG-based polling** — per-point MQTT topics with configurable intervals
* **Bidirectional writes** — `WRITABLE` tags with `DESTINATION_TOPIC`
* **Engineering units** — `SCALING`, `OFFSET`, `UNIT`, `DECIMAL_PLACES`, min/max clamping
* **Publish modes** — `VALUE_ONLY` (default) or `JSON` with quality metadata

***

## Quick Start

**Poll a controller tag**

Read a controller-scoped DINT counter every second:

```lot wrap focus={9-13} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ControlLogixPLC WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_FAMILY 0
        WITH PATH "1,0"
    ADD MAPPING ProductionData
        WITH EVERY 1 SECOND
        ADD TAG ProductCounter
            WITH ADDRESS "MainCounter"
            WITH DATA_TYPE "DINT"
            WITH SOURCE_TOPIC "production/counter"
```

**Program-scoped tags**

Read tags inside a specific program with units and deadband:

```lot wrap focus={9-16} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ControlLogix WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.20"
        WITH DEVICE_FAMILY 0
    ADD MAPPING ProcessControl
        WITH EVERY 500 MILLISECONDS
        ADD TAG ReactorTemp
            WITH ADDRESS "Program:MainProgram.Temperature"
            WITH DATA_TYPE "REAL"
            WITH UNIT "°C"
            WITH DECIMAL_PLACES 2
            WITH DEADBAND 0.5
            WITH SOURCE_TOPIC "process/reactor/temperature"
```

**Read and write**

Poll a setpoint and accept MQTT writes to update it:

```lot wrap focus={9-18} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TemperatureControl WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.60"
        WITH DEVICE_FAMILY 0
    ADD MAPPING ControlLoop
        WITH EVERY 1 SECOND
        ADD TAG TempSetpoint
            WITH ADDRESS "TempSetpoint"
            WITH DATA_TYPE "REAL"
            WITH UNIT "°C"
            WITH MIN_VALUE 0.0
            WITH MAX_VALUE 100.0
            WITH SOURCE_TOPIC "control/temperature/setpoint"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/temperature/setpoint/write"
```

**Micro800**

Read built-in I/O on a Micro800 controller:

```lot wrap focus={9-14} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Micro800PLC WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.70"
        WITH DEVICE_FAMILY 4
    ADD MAPPING Micro800Data
        WITH EVERY 1 SECOND
        ADD TAG DigitalIn
            WITH ADDRESS "_IO_EM_DI_00"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "micro800/input0"
```

***

## Connection Configuration

### ALLEN\_BRADLEY\_CONFIG Parameters

| Parameter | Required | Default | Description |
| - | - | - | - |
| `IP` | Yes | — | PLC IP address |
| `DEVICE_FAMILY` | No | `0` | Device family code (0–6, see table below) |
| `PORT` | No | `44818` | EtherNet/IP port. Honored for every device family. Default is `44818`. |
| `SLOT` | No | `0` | Parsed for legacy parity only. Backplane routing uses **`PATH`, not `SLOT`** — set the CPU slot in `PATH` (for example `"1,0"`). |
| `PATH` | No | `"1,0"` | Routing path (`backplane,slot`) for families that use a backplane. Micro800 (`DEVICE_FAMILY 4`) has no backplane: omit `PATH`. If you set one, the broker ignores it and logs a warning. |
| `TIMEOUT` | No | `5000` | Per-tag read/write timeout in milliseconds. Default is `5000`. Minimum accepted value is `1000`; values below that fail route add validation. |

> [!NOTE]
>
> The config block may be declared as `ADD ALLEN_BRADLEY_CONFIG` or `ADD AB_CONFIG` — both are equivalent.

> [!NOTE]
>
> The connector reports **Connected** only after the PLC answers. With at least one tag, it opens one tag using the same settings a read uses. With no tags, it checks the EtherNet/IP session. If the controller later drops, the route moves to **Reconnecting** and recovers on its own.
>
> Each read or write opens the tag and then reads or writes it, and each step has its own `TIMEOUT`. The route waits 2 × `TIMEOUT` plus a margin, at least 1 s, before it gives up. That's about 5 s at `TIMEOUT 2000`. So a dead PLC is detected later than `TIMEOUT` alone suggests, and the first read after a reconnect can take up to twice as long. A write that times out publishes `"success": false` with `"outcome": "unknown"`, because the PLC may still apply it. See [Write results](/latest/lot-language/routes/industrial/overview#write-results). Publish `-checkConnectorConnection <name>` to `$SYS/Coreflux/Command` to run that same test.

### Device Family Codes

| Code | Family | Use when |
| - | - | - |
| `0` | ControlLogix / CompactLogix | 1756-L6x, L7x, L8x, 1769-Lxx (most common) |
| `1` | PLC5 | 1785-L series (legacy) |
| `2` | SLC500 | 1747-L series (legacy) |
| `3` | ControlLogix PLC5 | Mixed environment |
| `4` | Micro800 | 2080-LC series |
| `5` | MicroLogix | 1766, 1764 series |
| `6` | Omron | NJ/NX with CIP support |

### Connection Examples

**ControlLogix / CompactLogix**

Standard backplane path to CPU in slot 0:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD ALLEN_BRADLEY_CONFIG
    WITH IP "192.168.1.100"
    WITH DEVICE_FAMILY 0
    WITH PATH "1,0"
    WITH TIMEOUT 5000
```

**MicroLogix**

MicroLogix 1100/1400:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD ALLEN_BRADLEY_CONFIG
    WITH IP "192.168.1.50"
    WITH DEVICE_FAMILY 5
    WITH TIMEOUT 5000
```

**Through backplane**

CPU in slot 2 on backplane 1:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD ALLEN_BRADLEY_CONFIG
    WITH IP "192.168.1.100"
    WITH DEVICE_FAMILY 0
    WITH PATH "1,2"
    WITH TIMEOUT 5000
```

**Micro800**

Micro800 has no backplane, so omit `PATH`. A `PATH` on this family is ignored and logged as a warning:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD ALLEN_BRADLEY_CONFIG
    WITH IP "192.168.1.70"
    WITH DEVICE_FAMILY 4
    WITH TIMEOUT 5000
```

***

## Tag Addressing

Allen-Bradley PLCs use **tag-based addressing** (not register numbers). Tag names are case-sensitive.

| Scope | Format | Example |
| - | - | - |
| Controller | `TagName` | `MainCounter` |
| Program | `Program:ProgramName.TagName` | `Program:MainProgram.Counter` |
| Array element | `TagName[index]` | `Temps[5]` |
| UDT member | `UDTInstance.Member` | `Valve1.Status` |
| Nested UDT | `Parent.Child.GrandChild` | `Tank1.Level.Current` |
| I/O tags | `Local:Slot:Type.Data[index]` | `Local:1:I.Data[0]` |

### Tag naming rules

* Letters, numbers, and underscore only
* Must start with a letter or underscore
* Case-sensitive
* No spaces

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Valid
WITH ADDRESS "MainCounter"
WITH ADDRESS "Program:MainProgram.Temperature"
WITH ADDRESS "Valve1.Status"
WITH ADDRESS "Temps[5]"
```

***

## Data Types

| Coreflux `DATA_TYPE` | AB type | Notes |
| - | - | - |
| `BOOL` | BOOL | Boolean |
| `SINT` | SINT | Signed 8-bit |
| `USINT` / `BYTE` | USINT | Unsigned 8-bit |
| `INT` | INT | Signed 16-bit |
| `UINT` / `WORD` | UINT | Unsigned 16-bit |
| `DINT` | DINT | Signed 32-bit |
| `UDINT` / `DWORD` | UDINT | Unsigned 32-bit |
| `LINT` | LINT | Signed 64-bit |
| `ULINT` / `LWORD` | ULINT | Unsigned 64-bit |
| `REAL` / `FLOAT` | REAL | 32-bit float |
| `LREAL` / `DOUBLE` | LREAL | 64-bit float — MQTT values round to `DECIMAL_PLACES` (default `2`) |
| `CHAR` | CHAR | Single character |
| `WCHAR` | WCHAR | Published as the character |
| `STRING` | STRING | CIP string with a length prefix — see [STRING encoding](#string-encoding) |
| `TIME` | TIME | Duration in ms — published as `T#XdXhXmXsXms` |
| `DATE` | DATE | Published as `yyyy-MM-dd` (the PLC stores seconds since 1970) |
| `TOD` | TOD | Published as `hh:mm:ss.fff` |

> [!NOTE]
>
> `DATE`, `TOD`, and `WCHAR` publish in these forms on every Allen-Bradley family. Measured on a Micro850: `1790553600` seconds publishes `2026-09-28`, and `65535` ms publishes `00:01:05.535`. Connected Components Workbench has no creatable `CHAR`, `WCHAR`, or `TOD` variable on Micro800, so those types apply to Logix families.

> [!WARNING]
>
> A tag's `DATA_TYPE` must match the PLC tag's actual type. On a mismatch the tag is refused: no value is published, the tag goes BAD, and the log names both types. Route health leaves Green and goes Yellow. The check is strict. A PLC `INT` declared as `DINT` is refused too. That case used to read correctly by luck.

### STRING encoding

Writes include the CIP length prefix. The layout depends on `DEVICE_FAMILY`.

* **ControlLogix / CompactLogix (default):** fixed 88-byte CIP `STRING` — a 4-byte DINT length prefix plus up to 82 ASCII characters. Neither `LENGTH` nor `STRING_SIZE` resizes this layout. `STRING_SIZE` is accepted as an alias for the same field and has the same limitation.
* **Micro800:** a 1-byte length prefix plus the characters. A write can be longer than the value currently stored in the tag. The broker sizes the tag so the new string fits, up to the String Size configured for that tag in Connected Components Workbench (for example, 80 characters). A longer string is rejected with an error instead of being truncated.

### TIME encoding

Raw value is a signed 32-bit millisecond count. MQTT publishes Allen-Bradley-style duration strings (for example `T#1h1m1s1ms`).

### Write value formats

Publish a payload to `DESTINATION_TOPIC` on a tag with `WRITABLE "true"`. Multi-byte values are written little-endian, the byte order CIP expects.

| `DATA_TYPE` | Accepted write value | Example |
| - | - | - |
| `WORD`, `DWORD`, `LWORD` | Decimal, the same form a read publishes, or hex with a `16#` or `0x` prefix | `500` or `16#01F4` |
| `TIME` | A `T#` duration, or a millisecond count. `T#10s` writes 10000 ms | `T#10s` |
| `DATE` | An ISO date `yyyy-MM-dd`, written as seconds since 1970-01-01 UTC | `2025-01-01` |
| `TOD` | Milliseconds since midnight. A read publishes `hh:mm:ss.fff`; a write does not accept that string | `65535` |
| `STRING` | The characters to store. The broker sends the CIP length prefix. On Micro800, see [STRING encoding](#string-encoding) for the String Size limit | `Pump-01` |

An on-demand `ADD EVENT` write accepts `T#` durations and sends the `STRING` length prefix. For `WORD`, `DWORD`, `LWORD`, and `DATE`, put the decimal or seconds form in the event `value` field. The `16#` / `0x` and `yyyy-MM-dd` forms apply to writable-tag payloads.

***

## TAG Configuration

Every polled data point is an `ADD TAG` inside an `ADD MAPPING` block.

### Complete TAG Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG MotorSpeed
    WITH ADDRESS "Motor1.ActualSpeed"
    WITH ADDRESS_TYPE "SYMBOL"
    WITH DATA_TYPE "REAL"
    WITH SOURCE_TOPIC "plc/motor1/speed"
    WITH SCALING 1
    WITH OFFSET 0
    WITH UNIT "RPM"
    WITH DECIMAL_PLACES 2
    WITH MIN_VALUE 0
    WITH MAX_VALUE 3600
    WITH DEADBAND 10
    WITH PUBLISH_MODE "JSON"
    WITH DESCRIPTION "Motor 1 actual speed in RPM"
```

### TAG Parameters

> **Address and data type**
>
> **ADDRESS** `string` *required*
>
> PLC tag name — controller-scoped (`MainCounter`), program-scoped (`Program:MainProgram.Counter`), UDT member (`Valve1.Status`), or array (`Temps[0]`).
>
> **ADDRESS\_TYPE** `string`
>
> `SYMBOL` (default) or `PATH`.
>
> **DATA\_TYPE** `string` *required*
>
> Logix data type: `BOOL`, `SINT`, `INT`, `DINT`, `LINT`, `USINT`, `UINT`, `UDINT`, `ULINT`, `REAL`, `LREAL`, `STRING`, `TIME`, etc. It must match the PLC tag's actual type. A mismatch publishes no value, marks the tag BAD, and route health goes Yellow. See [Data Types](#data-types).

> **Value transformation**
>
> **SCALING** `decimal`
>
> Multiply the parsed value after read. Alias: `SCALING_FACTOR`. Default: `1.0`.
>
> **OFFSET** `decimal`
>
> Add after scaling. Default: `0.0`.
>
> **UNIT** `string`
>
> Engineering unit (for example `°C`, `bar`, `RPM`). Included in JSON publish mode.
>
> **DECIMAL\_PLACES** `integer`
>
> Rounding precision for float MQTT payloads. Default: `2`.

> **Filtering**
>
> **MIN\_VALUE** `double`
>
> Clamp minimum allowed value (especially for writable tags).
>
> **MAX\_VALUE** `double`
>
> Clamp maximum allowed value.
>
> **DEADBAND** `double`
>
> Suppress MQTT publish when the change is below this threshold. Default: `0.0`.

> **Publishing and writes**
>
> **SOURCE\_TOPIC** `string` *required*
>
> MQTT topic where polled values are published.
>
> **PUBLISH\_MODE** `string`
>
> `VALUE_ONLY` (default) or `JSON` (value, unit, quality, timestamp, description).
>
> **WRITABLE** `boolean`
>
> When `"true"`, subscribe to `DESTINATION_TOPIC` and write incoming MQTT values to the PLC.
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to receive write commands. Required when `WRITABLE` is `"true"`.
>
> **DESCRIPTION** `string`
>
> Human-readable description (included in JSON publish mode).

### Publish Modes

**VALUE\_ONLY** (default) — publishes just the scaled value:

```
12345
```

**JSON** — metadata wrapper when explicitly set:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "tag_name": "SafetyPressure",
  "value": 8.456,
  "unit": "bar",
  "quality": "GOOD",
  "timestamp": "2025-12-17T10:30:45.123Z",
  "description": "Critical safety pressure sensor"
}
```

***

## Event-Based Operations

For on-demand tag reads and writes (not continuous polling), add an `ADD EVENT` block. Publish any message to `SOURCE_TOPIC` to trigger the operation; results appear on `DESTINATION_TOPIC`.

### Query Parameters

| Parameter | Description | Example |
| - | - | - |
| `operation` | `READ` or `WRITE` | `READ` |
| `variable` | PLC tag name | `Program:MainProgram.Counter`, `MainCounter` |
| `data_type` | Logix data type | `DINT`, `REAL`, `BOOL` |
| `value` | Value to write (WRITE only) | `42`, `75.0` |

### Read Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadOnDemand
    WITH SOURCE_TOPIC "ab/commands/read"
    WITH DESTINATION_TOPIC "ab/responses/read"
    WITH QUERY "{operation: READ, variable: Program:MainProgram.Counter, data_type: DINT}"
```

### Write Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT WriteSetpoint
    WITH SOURCE_TOPIC "ab/commands/write"
    WITH DESTINATION_TOPIC "ab/responses/write"
    WITH QUERY "{operation: WRITE, variable: TIC100.SP, data_type: REAL, value: 150.0}"
```

***

## Examples

**Multiple data types**

Monitor BOOL, DINT, and REAL tags in one mapping:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionLine WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.30"
        WITH DEVICE_FAMILY 0
    ADD MAPPING MachineMonitor
        WITH EVERY 1 SECOND
        ADD TAG MachineRunning
            WITH ADDRESS "MachineStatus.Running"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "machine/status/running"
        ADD TAG ProductCount
            WITH ADDRESS "ProductionCounters.TotalCount"
            WITH DATA_TYPE "DINT"
            WITH SOURCE_TOPIC "machine/production/total"
        ADD TAG LineSpeed
            WITH ADDRESS "LineSpeed"
            WITH DATA_TYPE "REAL"
            WITH UNIT "units/min"
            WITH SOURCE_TOPIC "machine/speed"
```

**UDT members**

Read User-Defined Type structure members:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR UDTAccess WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.40"
        WITH DEVICE_FAMILY 0
    ADD MAPPING ValveControl
        WITH EVERY 500 MILLISECONDS
        ADD TAG Valve1Position
            WITH ADDRESS "Valve1.Position"
            WITH DATA_TYPE "INT"
            WITH UNIT "%"
            WITH SOURCE_TOPIC "valves/valve1/position"
        ADD TAG Valve1Status
            WITH ADDRESS "Valve1.Status"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "valves/valve1/status"
```

**Array elements**

Read specific array indices:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ArrayData WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.50"
        WITH DEVICE_FAMILY 0
    ADD MAPPING ArrayMonitor
        WITH EVERY 1 SECOND
        ADD TAG Zone1Temp
            WITH ADDRESS "ZoneTemperatures[0]"
            WITH DATA_TYPE "REAL"
            WITH UNIT "°C"
            WITH SOURCE_TOPIC "zones/zone1/temperature"
        ADD TAG Zone2Temp
            WITH ADDRESS "ZoneTemperatures[1]"
            WITH DATA_TYPE "REAL"
            WITH UNIT "°C"
            WITH SOURCE_TOPIC "zones/zone2/temperature"
```

**Control loop**

Read process value and write setpoint from MQTT:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ControlLoop WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.100"
        WITH DEVICE_FAMILY 0
    ADD MAPPING TempControl
        WITH EVERY 200 MILLISECONDS
        ADD TAG PV
            WITH ADDRESS "TIC100.PV"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/tic100/pv"
            WITH UNIT "°F"
        ADD TAG SP
            WITH ADDRESS "TIC100.SP"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/tic100/sp"
            WITH UNIT "°F"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/tic100/sp/set"
            WITH MIN_VALUE 32
            WITH MAX_VALUE 212
```

**Scaled analog**

Scale a 4–20 mA sensor to engineering units:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AnalogSensors WITH TYPE ALLEN_BRADLEY
    ADD ALLEN_BRADLEY_CONFIG
        WITH IP "192.168.1.80"
        WITH DEVICE_FAMILY 0
    ADD MAPPING AnalogData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Pressure
            WITH ADDRESS "AI_Pressure"
            WITH DATA_TYPE "REAL"
            WITH UNIT "bar"
            WITH DECIMAL_PLACES 3
            WITH DEADBAND 0.01
            WITH SOURCE_TOPIC "sensors/pressure"
```

***

## Best Practices

> **Choose the correct device family**
>
> Use `DEVICE_FAMILY 0` for ControlLogix and CompactLogix (most common), `4` for Micro800, and `5` for MicroLogix. Legacy PLC5/SLC500 families (`1`/`2`) only for existing installations.

> **Program scope**
>
> Controller-scoped tags use the name alone (`GlobalCounter`). Program-scoped tags need the full prefix: `Program:MainProgram.LocalCounter`.

> **PATH vs SLOT**
>
> Set the CPU slot in `PATH` (`"1,0"` for backplane 1, slot 0). `SLOT` is kept for legacy parity, but routing is resolved from `PATH`. Micro800 (`DEVICE_FAMILY 4`) has no backplane: omit `PATH`. A `PATH` on a Micro800 route is ignored and logged as a warning.

> **Writable tags**
>
> Use `WRITABLE "true"` with `MIN_VALUE` / `MAX_VALUE` on setpoints. Publish values in the forms under [Write value formats](#write-value-formats). Ensure the PLC is in Remote Run mode for writes to succeed.

> **Deadbands and polling**
>
> Use `DEADBAND` on noisy analog values. Match `EVERY` to how fast the value changes — 500 ms for critical data, 1–5 s for slow status.

***

## Troubleshooting

> **Connection failed**
>
> * Verify IP with `ping`
> * Confirm the EtherNet/IP port is open (default `44818`, or the `PORT` you set)
> * Ensure PLC is powered on and in **RUN** mode
> * Check `DEVICE_FAMILY` matches your controller type
> * Increase `TIMEOUT` on slow networks
> * Publish `-checkConnectorConnection <name>` to test the connection: with tags, the broker opens one tag the way a read does; with no tags, it checks the EtherNet/IP session

> **Tag not found**
>
> * Tag names are **case-sensitive** — match Studio 5000 exactly
> * Program-scoped tags need `Program:ProgramName.TagName` (not `ProgramName:Tag`)
> * Verify the tag exists in Controller Tags or Program Tags in Studio 5000
> * For UDTs, include the member: `Valve1.Status` not `Valve1`
> * For arrays, include the index: `Temps[0]` not `Temps`

> **Path errors**
>
> * Use `PATH "1,0"` for standard backplane routing (backplane, slot)
> * For Micro800, omit `PATH`. If you set one, the broker ignores it and logs a warning
> * Multi-hop paths use comma-separated segments: `"1,2,2,1"` through bridge modules

> **Micro800 issues**
>
> * Set `DEVICE_FAMILY 4`
> * Omit `PATH`. Micro800 has no backplane; a `PATH` on this family is ignored and logged as a warning
> * Use Micro800 I/O tag names (`_IO_EM_DI_00`, `_IO_EM_AI_00`)
> * STRING uses a 1-byte length prefix (not the ControlLogix 4-byte format). A write can grow up to the tag's String Size in Connected Components Workbench; a longer string is rejected

> **Write operations fail**
>
> * Set `WRITABLE "true"` and provide `DESTINATION_TOPIC`
> * PLC must be in **Remote Run** mode
> * Verify `DATA_TYPE` matches the PLC tag definition
> * Check value is within `MIN_VALUE` / `MAX_VALUE` if set
> * For `TOD`, publish milliseconds since midnight. The read form `hh:mm:ss.fff` is not a write payload

> **No value published, route Yellow**
>
> * `DATA_TYPE` must match the PLC tag's actual type. On a mismatch the tag is refused: no value is published, the tag goes BAD, the log names both types, and route health leaves Green and goes Yellow
> * The check is strict. A PLC `INT` declared as `DINT` is refused too. That case used to read correctly by luck
> * Match PLC types exactly: DINT → `DINT`, REAL → `REAL`, BOOL → `BOOL`
> * `TIME` tags publish as `T#...` duration strings on MQTT
> * `DATE` publishes as `yyyy-MM-dd`. `TOD` publishes as `hh:mm:ss.fff`
> * For now, one failing tag can back off its whole mapping

***

## Next Steps

> **[EtherNet/IP Connector](./ethernetip)**
>
> Explicit CIP Class/Instance/Attribute addressing for assembly objects and legacy devices.

> **[Industrial Connectors Overview](./overview)**
>
> Compare OT connectors and choose the right protocol for your devices.


# BACnet/IP Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/bacnet

Connect Coreflux to building automation controllers over BACnet/IP with TAG polling, COV subscriptions, alarms, and bidirectional writes.

## Connect Coreflux to Building Automation

The BACnet connector connects Coreflux to building automation controllers (ASHRAE 135) using the unified OT TAG system. Define the BACnet configuration, add Tags for continuous polling or COV subscriptions, and handle alarm operations.

> [!TIP]
>
> BACnet is the dominant protocol for building management systems. If your controller supports BACnet/IP, this connector maps each data point to an MQTT topic using the same TAG model as every other Coreflux industrial connector.

### When to use this

Use the BACnet connector when you need to integrate HVAC, lighting, metering, or access-control controllers that expose **BACnet/IP** — read live values on a schedule, subscribe to change notifications, write setpoints from MQTT, receive intrinsic alarms, or run ad-hoc reads and writes triggered by MQTT commands.

### Key capabilities

* **BACnet/IP over UDP** — standard port 47808 (0xBAC0) with broadcast or direct-IP discovery
* **TAG-based polling** — per-point MQTT topics with a configurable polling interval
* **Change-of-Value (COV)** — push subscriptions per tag (`WITH COV true`) without polling
* **Event alarms** — BACnet Event-Notifications to MQTT with per-tag or device-wide streams
* **Bidirectional writes** — MQTT-triggered writes to analog, binary, and value objects
* **On-demand events** — `ADD EVENT` with `READ`, `WRITE`, and `ACK` queries triggered by any MQTT publish
* **Operator ACK workflow** — auto-registered ACK handler per alarming tag
* **Direct IP mode** — connect to controllers that do not respond to Who-Is/I-Am
* **Docker and hostname support** — resolve container service names before opening the BACnet socket

***

## Quick Start

Pick the starting point that matches what you need. Each tag publishes to `{SOURCE_TOPIC}/{tagName}` unless the tag sets its own `SOURCE_TOPIC`.

**Poll sensor values**

Connect to a controller and read a room temperature every five seconds:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
    ADD MAPPING RoomSensors
        WITH SOURCE_TOPIC "bacnet/bms"
        WITH EVERY 5 SECONDS
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "degC"
```

**Read and write**

Read a setpoint and allow MQTT writes back to the device:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HVAC WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "10.0.0.50"
        WITH DEVICE_ID 2000
        WITH WRITE_PRIORITY 8
    ADD MAPPING Setpoints
        WITH SOURCE_TOPIC "bacnet/hvac"
        WITH EVERY 10 SECONDS
        ADD TAG CoolingSetpoint
            WITH ADDRESS "AV:1"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "degC"
            WITH WRITABLE true
            WITH DESTINATION_TOPIC "bacnet/hvac/CoolingSetpoint/set"
```

**Updates on change**

Subscribe to Change-of-Value so the device pushes updates only when values change — no polling interval needed:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
        WITH COV_LIFETIME 600
    ADD MAPPING CovPoints
        WITH SOURCE_TOPIC "bacnet/bms/cov"
        ADD TAG RoomTempCov
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH COV true
```

**Connect directly**

When the controller does not answer Who-Is/I-Am, connect straight to its IP address:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "10.0.0.50"
        WITH PORT 47808
        WITH DEVICE_ID 1234
        WITH DIRECT_IP true
    ADD MAPPING RoomSensors
        WITH SOURCE_TOPIC "bacnet/bms"
        WITH EVERY 5 SECONDS
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "degC"
```

**On-demand read/write**

Trigger a single BACnet read or write by publishing to an MQTT command topic:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
    ADD EVENT ReadProperty
        WITH SOURCE_TOPIC "bacnet/cmd/read"
        WITH DESTINATION_TOPIC "bacnet/cmd/read/result"
        WITH QUERY "READ:AI:0:PRESENT_VALUE"
    ADD EVENT WriteProperty
        WITH SOURCE_TOPIC "bacnet/cmd/write"
        WITH DESTINATION_TOPIC "bacnet/cmd/write/result"
        WITH QUERY "{payload}"
```

**Per-tag alarms**

Each alarming point gets its own MQTT alarm stream and auto-registered ACK topic:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
        WITH LOCAL_DEVICE_ID 4194300
    ADD MAPPING LimitPoints
        WITH SOURCE_TOPIC "bacnet/bms"
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH COV true
            WITH ALARM true
```

***

## Protocol Overview

BACnet (Building Automation and Control networks) is an open protocol for building automation, standardized as ANSI/ASHRAE 135 and ISO 16484-5. It enables interoperability between devices from different manufacturers in HVAC, lighting, fire detection, access control, and energy management.

| Concept | Description |
| - | - |
| **Object model** | Every data point is a typed object (Analog Input, Binary Value, etc.) identified by instance number, accessed by properties (Present Value, High Limit, Event State, …) |
| **Service model** | Clients read and write properties using BACnet services (ReadProperty, WriteProperty, SubscribeCOV, AcknowledgeAlarm) |
| **Device discovery** | Who-Is/I-Am broadcast locates devices by Device Instance without knowing the IP address |
| **Intrinsic alarming** | Controllers generate Event-Notifications when values cross configured limits — alarm logic lives in the device |

### BACnet variants

| Variant | Transport | Port / Layer | Notes |
| - | - | - | - |
| **BACnet/IP** | UDP/IP | 47808 (0xBAC0) | Most common; fully supported |
| **BACnet MSTP** | Serial RS-485 | N/A | Not supported |
| **BACnet over Ethernet** | Ethernet (Annex H) | — | Not supported |
| **BACnet/SC** | TLS/WebSocket | — | Not currently implemented |

> [!NOTE]
>
> Coreflux supports **BACnet/IP** (UDP). MS/TP parameters are parsed but the transport is not validated. Use BACnet/IP for all production deployments.

### Supported controllers and platforms

| Category | Examples |
| - | - |
| **HVAC controllers** | Siemens Desigo, Johnson Controls Metasys, Honeywell WEBs, Carrier i-Vu |
| **DDC / field panels** | Distech Controls ECB, Alerton Ascent, Delta Controls ORCAview |
| **Meters and sensors** | Veris BMeter, Onset HOBO, Accuenergy Acuvim |
| **Gateways** | Contemporary Controls BASRT-B, Babel Buster (Modbus→BACnet) |
| **Simulators** | IOTech BACnet device simulator (Docker); VTS (Visual Test Shell) |
| **Integration platforms** | Niagara (Tridium), EBO (Schneider) |

***

## Configuration

Only `DEVICE_ID` is strictly required. For a working connector, also set `IP` and add at least one `ADD MAPPING` with tags.

```lot wrap focus={2-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
    ADD MAPPING RoomSensors
        WITH SOURCE_TOPIC "bacnet/bms"
        WITH EVERY 5 SECONDS
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "degC"
```

### All configuration options

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH PORT 47808
        WITH LOCAL_PORT 0
        WITH DEVICE_ID 1234
        WITH TIMEOUT 3
        WITH DISCOVERY_TIMEOUT 5
        WITH DIRECT_IP false
        WITH WRITE_PRIORITY 8
        WITH RETRIES 3
        WITH MAX_APDU 1476
        WITH COV_LIFETIME 300
        WITH COV_CONFIRMED false
        WITH LOCAL_DEVICE_ID 4194300
        WITH ALARMS false
        WITH ALARMS_TOPIC "bacnet/bms/alarms"
```

### Configuration parameters

| Setting | Required | Default | Description |
| - | - | - | - |
| `DEVICE_ID` | **Yes** | `1` | Target BACnet device instance (Who-Is/I-Am and ReadProperty) |
| `IP` / `HOST` / `ADDRESS` | Conditional | `192.168.1.1` | Remote device IPv4 or hostname. **Required** when `WITH DIRECT_IP true`; strongly recommended for Docker and routed networks |
| `PORT` | No | `47808` | Remote device BACnet/IP UDP listen port |
| `LOCAL_PORT` | No | `0` | Local UDP port the broker binds on this host (`0` = OS ephemeral) |
| `TRANSPORT` | No | `IP` | `IP` or `MSTP` (MS/TP not validated — use BACnet/IP) |
| `TIMEOUT` | No | `3` | Read/write timeout in seconds |
| `DISCOVERY_TIMEOUT` | No | `5` | Who-Is/I-Am wait in seconds |
| `DIRECT_IP` | No | `false` | Skip discovery; connect to `IP:PORT` and verify with ReadProperty |
| `WRITE_PRIORITY` | No | `8` | BACnet command priority (1 = highest, 16 = lowest) |
| `RETRIES` | No | `3` | Retry count on failure |
| `MAX_APDU` | No | `1476` | Maximum BACnet/IP frame size in bytes; this is **not** a string-size setting |
| `COV_LIFETIME` | No | `300` | Default COV subscription lifetime in seconds (`0` = infinite) |
| `COV_CONFIRMED` | No | `false` | Request confirmed COV notifications by default |
| `LOCAL_DEVICE_ID` | Conditional | `0` | Local device instance for directed I-Am. **Required** when `WITH ALARMS true` or any TAG has `WITH ALARM true` |
| `ALARMS` | No | `false` | Publish all device Event-Notifications to `ALARMS_TOPIC` |
| `ALARMS_TOPIC` | No | `bacnet/{routeName}/alarms` | MQTT topic for device-wide alarms when `WITH ALARMS true` |
| `ALARM_TOPIC` | No | — | Alias for `ALARMS_TOPIC` on `BACNET_CONFIG` |

> [!NOTE]
>
> After 3 failed read cycles in a row on the current connection, the route goes to **Reconnecting**. Reads and writes still queued on a replaced connection give way at once and don't count against the new one. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).

### Network setup: IP, PORT, and LOCAL\_PORT

BACnet/IP is UDP. Three settings control two different endpoints — the BACnet device (remote) and the Coreflux broker (local).

| Setting | Side | What it is | Typical value |
| - | - | - | - |
| `IP` | Remote | IPv4 address or hostname of the BACnet controller | `192.168.1.10`, `coreflux-connector-bacnet` |
| `PORT` | Remote | UDP port where the device accepts BACnet/IP traffic | `47808` |
| `LOCAL_PORT` | Local | UDP port the broker binds on before sending/receiving | `0` (OS-assigned) |

| Scenario | `IP` | `PORT` | `LOCAL_PORT` |
| - | - | - | - |
| Sandbox simulator on the same host | `127.0.0.1` | `47808` | `0` |
| Simulator in Docker, broker in another container | `coreflux-connector-bacnet` (docker container name) | `47808` | `0` |
| Device on non-standard port | `10.0.0.5` | `47809` | `0` |
| Firewall requires fixed source port | `10.0.0.5` | `47808` | `47808` |

> [!TIP]
>
> `WITH IP` accepts hostnames and Docker service names (for example `coreflux-connector-bacnet`, `host.docker.internal`). The broker resolves them to IPv4 before opening the BACnet socket.

### Direct IP mode

Use when the controller does not respond to Who-Is/I-Am but accepts ReadProperty at a known UDP endpoint:

```lot wrap focus={6} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "10.0.0.50"
        WITH PORT 47808
        WITH DEVICE_ID 1234
        WITH DIRECT_IP true
```

### Write priority

Commandable objects (analog, binary and multi-state outputs and values) keep a 16-slot priority array. The device uses the value in the highest slot that holds one (1 = highest, 16 = lowest). If every slot is empty, it falls back to `RELINQUISH_DEFAULT`.

* **Default:** every write from the connector goes to slot **8**.
* **Set it:** `WITH WRITE_PRIORITY <1-16>` in the connector config. It applies to every write on that connector, and there is no per-tag override. A value outside 1–16 is refused when the connector is added.
* **Higher slots win:** a write at 8 doesn't change the present value while a BMS or operator holds slot 1–7.
* **Relinquish isn't supported:** the connector can't write `NULL` to free its slot. Its last value stays in that slot until you overwrite it, or until another tool relinquishes it.
* **Inspect it:** set a tag's `ADDRESS_TYPE` to `PRIORITY_ARRAY` or `RELINQUISH_DEFAULT` to see which slot is active.

The IOTech sandbox profile seeds `AO:0` at priority **1**. Use `WITH WRITE_PRIORITY 1` for that test device.

> [!WARNING]
>
> If a write appears to succeed but the present value does not change, the device may be holding the value at a higher priority. Try `WITH WRITE_PRIORITY 1` and check whether a BMS already owns the point.

***

## TAG System

### Mapping parameters

```lot wrap focus={1,2,3,4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
    ADD MAPPING RoomSensors
        WITH SOURCE_TOPIC "bacnet/bms"
        WITH EVERY 5 SECONDS
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "degC"
            WITH WRITABLE false
            WITH COV false
            WITH ALARM false
```

| Parameter | Required | Default | Description |
| - | - | - | - |
| `SOURCE_TOPIC` | **Yes**\* | — | Base MQTT topic; each tag publishes to `{SOURCE_TOPIC}/{tagName}` unless the tag sets its own |
| `EVERY` | Conditional | — | Polling interval (e.g. `1 SECONDS`, `200 MILLISECONDS`). Required when the mapping has polled tags; omit for COV-only mappings |
| `ADD TAG` | **Yes** | — | At least one tag per mapping |

\* You may set `SOURCE_TOPIC` on each tag instead of on the mapping, but one of the two is required.

### Tag parameters

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG RoomTemp
    WITH ADDRESS "AI:0"
    WITH DATA_TYPE "FLOAT"
    WITH UNIT "degC"
    WITH WRITABLE false
    WITH COV false
    WITH ALARM false
```

| Parameter | Required | Default | Description |
| - | - | - | - |
| `ADDRESS` | **Yes** | — | BACnet object `TYPE:INSTANCE` (e.g. `AI:0`, `AV:3`, `BI:0`) |
| `DATA_TYPE` | **Yes** | — | `BOOL`, `INT16`, `UINT16`, `INT32`, `UINT32`, `FLOAT`, `DOUBLE`, `STRING` |
| `SOURCE_TOPIC` | Conditional | `{mapping SOURCE_TOPIC}/{tagName}` | MQTT topic for tag data. Required on the tag **or** on the parent mapping |
| `DESTINATION_TOPIC` | Conditional | — | MQTT topic to subscribe for writes. Required when `WITH WRITABLE true` |
| `ADDRESS_TYPE` | No | `PRESENT_VALUE` | BACnet property to read/write (e.g. `OBJECT_NAME`, `HIGH_LIMIT`) |
| `LENGTH` | No | `256` | Maximum string size in bytes when `DATA_TYPE` is `STRING`. Alias: `STRING_SIZE`. |
| `WRITABLE` | No | `false` | Allow MQTT writes to this object |
| `SCALING` | No | `1.0` | Multiply raw value |
| `OFFSET` | No | `0.0` | Add after scaling |
| `UNIT` | No | `""` | Engineering unit label (e.g. `degC`, `%RH`) |
| `DECIMAL_PLACES` | No | `2` | Rounding precision |
| `DEADBAND` | No | `0.0` | Minimum change before republishing |
| `MIN_VALUE` / `MAX_VALUE` | No | — | Clamp published values |
| `PUBLISH_MODE` | No | `VALUE_ONLY` | `VALUE_ONLY` or `JSON` |
| `DESCRIPTION` | No | `""` | Documentation string only |
| `COV` | No | `false` | Subscribe to BACnet Change-of-Value instead of polling |
| `COV_LIFETIME` | No | connector `COV_LIFETIME` | Per-tag COV subscription lifetime in seconds |
| `COV_CONFIRMED` | No | connector `COV_CONFIRMED` | Request confirmed COV for this tag |
| `ALARM` | No | `false` | Enable MQTT alarm stream on `{tag_topic}/alarms` |
| `ALARM_TOPIC` | No | `{tag_topic}/alarms` | Override alarm MQTT topic (only when `WITH ALARM true`) |

### Object address format

| Shorthand | Full name | Example |
| - | - | - |
| `AI` | `ANALOG_INPUT` | `AI:0` |
| `AO` | `ANALOG_OUTPUT` | `AO:1` |
| `AV` | `ANALOG_VALUE` | `AV:0` |
| `BI` | `BINARY_INPUT` | `BI:0` |
| `BO` | `BINARY_OUTPUT` | `BO:0` |
| `BV` | `BINARY_VALUE` | `BV:0` |
| `MSV` | `MULTISTATE_VALUE` | `MSV:0` |

> [!NOTE]
>
> `ADDRESS_TYPE` is the **BACnet property** (e.g. `PRESENT_VALUE`, `OBJECT_NAME`), not the object type.

### String sizing

For `STRING` tags, `WITH LENGTH` is the maximum string size in bytes and defaults to **256**. `STRING_SIZE` is accepted as an alias for the same field. Connector-level `MAX_APDU` limits the BACnet/IP **frame** size — it does not size strings.

Read an object's name property as a STRING. `WITH LENGTH 64` overrides the 256-byte default to match a shorter BACnet property allocation:

```lot wrap focus={12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
    ADD MAPPING DeviceInfo
        WITH SOURCE_TOPIC "bacnet/bms"
        WITH EVERY 30 SECONDS
        ADD TAG RoomName
            WITH ADDRESS "AI:0"
            WITH ADDRESS_TYPE "OBJECT_NAME"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 64
            WITH SOURCE_TOPIC "bacnet/bms/RoomName"
```

### Change-of-Value (COV)

Tags with `WITH COV true` subscribe to BACnet Change-of-Value notifications instead of polling. A mapping with only COV tags does not need `WITH EVERY`. Mixed mappings poll non-COV tags on `EVERY` and receive COV tags via push.

> [!NOTE]
>
> COV requires support on the device side. If you receive no change notifications, confirm the controller supports COV and that `WITH COV true` is set on the tag.

***

## Alarms and Event Notifications

The broker receives BACnet **Event-Notification** messages from the field device and publishes them to MQTT. Alarm limits and Notification Class membership are configured on the controller — the broker only needs the device to send events to its `LOCAL_DEVICE_ID`.

### Alarm message format

Every time the BACnet device reports an alarm or state change, the broker publishes **one JSON object** to the alarm topic. Subscribe to that topic to see events as they happen, or subscribe to `{alarm_topic}/active` for a retained snapshot of alarms that are still open.

**Example** — a room temperature crosses its high limit (`bacnet/bms/RoomTemp/alarms`):

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "connector_name": "BMS",
  "device_id": 1234,
  "address": "AI:0",
  "tag_name": "RoomTemp",
  "tag_topic": "bacnet/bms/RoomTemp",
  "alarm_topic": "bacnet/bms/RoomTemp/alarms",
  "object_type": "ANALOG_INPUT",
  "instance": 0,
  "event_type": "EVENT_OUT_OF_RANGE",
  "from_state_short": "NORMAL",
  "to_state_short": "HIGH_LIMIT",
  "fundamental_state": "OFFNORMAL",
  "transition": "TO_OFFNORMAL",
  "event_state_to_ack": "HIGH_LIMIT",
  "ack_required": true,
  "present_value": 28.5,
  "bacnet_timestamp": "2026-06-10T15:28:21.000Z",
  "timestamp": "2026-06-10T16:28:21.003Z"
}
```

**Fields to know:**

| Field | What it tells you |
| - | - |
| `address` | Which BACnet point raised the alarm (e.g. `AI:0` = Analog Input 0) |
| `tag_name` / `tag_topic` | The connector TAG and MQTT topic for live values on that point |
| `from_state_short` → `to_state_short` | State change just reported (e.g. `NORMAL` → `HIGH_LIMIT`) |
| `transition` | Direction of the change: `TO_OFFNORMAL` (new alarm), `TO_NORMAL` (cleared), or `TO_FAULT` |
| `fundamental_state` | Overall condition: `OFFNORMAL` (limit alarm), `FAULT`, or `NORMAL` |
| `present_value` | Value on the device when the event fired (when provided) |
| `ack_required` | If `true`, an operator must acknowledge the alarm on the device |
| `event_state_to_ack` | State to send when acknowledging — use this in ACK payloads |
| `bacnet_timestamp` | When the device recorded the event — include when acknowledging |

**Common `to_state_short` values:**

| Value | Meaning |
| - | - |
| `HIGH_LIMIT` | Value rose above the configured high limit |
| `LOW_LIMIT` | Value fell below the configured low limit |
| `FAULT` | Device reported a fault condition |
| `NORMAL` | Point returned to normal (alarm cleared) |

### Setting Alarms on BACnet ROUTE

| Mode | Configuration | Default MQTT topic | Coverage |
| - | - | - | - |
| **Device-wide** | `WITH ALARMS true` on `BACNET_CONFIG` | `bacnet/{routeName}/alarms` (+ retained `…/active`) | Every Event-Notification from the device |
| **Per-tag** | `WITH ALARM true` on TAG | `{tag_topic}/alarms` (+ retained `…/active`) | Only events matching the TAG's `ADDRESS` |

Both modes can coexist. When both are enabled for the same object, the event is published to both topics.

**Device-wide**

Publish every Event-Notification from the device to a single MQTT topic — useful for commissioning and catch-all monitoring:

```lot wrap focus={6-7} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
        WITH LOCAL_DEVICE_ID 4194300
        WITH ALARMS true
        WITH ALARMS_TOPIC "bacnet/bms/alarms"
    ADD MAPPING CovPoints
        WITH SOURCE_TOPIC "bacnet/bms"
        ADD TAG CovCounter
            WITH ADDRESS "AV:0"
            WITH DATA_TYPE "FLOAT"
            WITH COV true
```

Alarm events appear on `bacnet/bms/alarms`. Operator ACK via `bacnet/bms/alarms/ack`.

**Per-tag**

Each alarming point gets its own MQTT alarm stream and ACK topic:

```lot wrap focus={12,17} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
        WITH LOCAL_DEVICE_ID 4194300
    ADD MAPPING LimitPoints
        WITH SOURCE_TOPIC "bacnet/bms"
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH COV true
            WITH ALARM true
        ADD TAG ChillerPressure
            WITH ADDRESS "AI:2"
            WITH DATA_TYPE "FLOAT"
            WITH EVERY 5 SECONDS
            WITH ALARM true
```

| Data topic | Alarm topic | ACK topic |
| - | - | - |
| `bacnet/bms/RoomTemp` | `bacnet/bms/RoomTemp/alarms` | `bacnet/bms/RoomTemp/alarms/ack` |
| `bacnet/bms/ChillerPressure` | `bacnet/bms/ChillerPressure/alarms` | `bacnet/bms/ChillerPressure/alarms/ack` |

On connect, when alarms are enabled and `LOCAL_DEVICE_ID` is set, the broker sends a **directed I-Am** so Notification Class recipients learn the broker's UDP endpoint.

> [!WARNING]
>
> Set a non-zero `WITH LOCAL_DEVICE_ID` before enabling alarms. Without it, Event-Notifications are unlikely to arrive because the field device does not know where to send them.

### Active alarm list

In addition to live events on `{alarm_topic}`, the broker maintains a **retained** snapshot on `{alarm_topic}/active`. Subscribe here to build an alarm panel — late subscribers receive the current state immediately without waiting for the next transition.

| Topic | Retain | Use for |
| - | - | - |
| `{alarm_topic}` | No | Live transitions as they happen (logging, notifications) |
| `{alarm_topic}/active` | **Yes** | Current open alarms (dashboards, alarm panels) |

**How the list updates:**

| Event | Effect on `/active` |
| - | - |
| `TO_OFFNORMAL` or `TO_FAULT` | Add or update the entry for that BACnet `address` |
| `TO_NORMAL` | Remove the entry for that `address` |
| Successful ACK on `{alarm_topic}/ack` | Remove the entry matching `address` + `event_state_to_ack` |

Per-tag lists usually hold **0 or 1** entry (one BACnet object per tag). Device-wide lists hold **one entry per alarming object** on the device.

**Example** — device-wide active list on `bacnet/bms/alarms/active`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "connector_name": "BMS",
  "device_id": 1234,
  "alarm_topic": "bacnet/bms/alarms",
  "active_topic": "bacnet/bms/alarms/active",
  "updated_at": "2026-06-16T12:00:00.000Z",
  "count": 2,
  "alarms": [
    {
      "address": "AI:0",
      "tag_name": "RoomTemp",
      "to_state_short": "HIGH_LIMIT",
      "fundamental_state": "OFFNORMAL",
      "transition": "TO_OFFNORMAL",
      "event_state_to_ack": "HIGH_LIMIT",
      "ack_required": true,
      "present_value": 28.5,
      "bacnet_timestamp": "2026-06-10T15:28:21.000Z"
    },
    {
      "address": "AI:2",
      "tag_name": "ChillerPressure",
      "to_state_short": "HIGH_LIMIT",
      "fundamental_state": "OFFNORMAL",
      "transition": "TO_OFFNORMAL",
      "event_state_to_ack": "HIGH_LIMIT",
      "ack_required": false,
      "present_value": 95.2,
      "bacnet_timestamp": "2026-06-10T15:30:05.000Z"
    }
  ]
}
```

Each object in the `alarms` array uses the same fields as a single live alarm event. When no alarms are active, `count` is `0` and `alarms` is `[]` — the broker still publishes valid retained JSON.

### Acknowledging alarms

When a BACnet device raises an alarm, the broker publishes it to MQTT. To clear or acknowledge it on the device, an operator publishes to the **ACK topic**. The broker sends `AcknowledgeAlarm` to the controller and replies with a result.

**How it works:**

1. **Subscribe** to the alarm topic (live events) or `{alarm_topic}/active` (current alarm list).
2. **Publish** your acknowledgement to `{alarm_topic}/ack`.
3. **Check** `{alarm_topic}/ack/result` for `success: true` or `false`.

No additional configuration is needed for ACK — the broker registers the handler automatically when you enable device-wide alarms or per-tag `WITH ALARM true`.

| Topic | What you see |
| - | - |
| `{alarm_topic}` | Live alarm events as they happen |
| `{alarm_topic}/active` | Retained list of alarms that are still active |
| `{alarm_topic}/ack` | **Publish here** to acknowledge |
| `{alarm_topic}/ack/result` | Success or failure of your acknowledgement |

**Recommended — echo the alarm**

Copy the alarm JSON you received, add an `ack_text` note, and publish it to the ACK topic. This is the safest approach because you keep all fields the device expects (`event_state_to_ack`, `bacnet_timestamp`, and so on).

**1. An alarm arrives** on `bacnet/bms/RoomTemp/alarms`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "address": "AI:0",
  "tag_name": "RoomTemp",
  "to_state_short": "HIGH_LIMIT",
  "event_state_to_ack": "HIGH_LIMIT",
  "ack_required": true,
  "present_value": 28.5,
  "bacnet_timestamp": "2026-06-10T15:28:21.000Z"
}
```

**2. Publish to** `bacnet/bms/RoomTemp/alarms/ack` — same JSON, plus your note:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "address": "AI:0",
  "tag_name": "RoomTemp",
  "to_state_short": "HIGH_LIMIT",
  "event_state_to_ack": "HIGH_LIMIT",
  "ack_required": true,
  "present_value": 28.5,
  "bacnet_timestamp": "2026-06-10T15:28:21.000Z",
  "ack_text": "Checked by operator — HVAC team notified"
}
```

Use any MQTT client (such as MQTT Explorer) to publish the payload above to the ACK topic.

**3. Result on** `bacnet/bms/RoomTemp/alarms/ack/result`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "connector_name": "BMS",
  "operation": "ACK",
  "address": "AI:0",
  "event_state": "HIGH_LIMIT",
  "timestamp": "2026-06-10T16:30:00.000Z"
}
```

> [!TIP]
>
> If `success` is `true`, the device accepted the acknowledgement. The alarm is removed from `{alarm_topic}/active`.

**Explicit command**

For scripts or integrations that do not store the full alarm JSON, publish a short text command to the ACK topic.

**Publish to** `bacnet/bms/RoomTemp/alarms/ack`:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ACK:AI:0:HIGH_LIMIT:Checked by operator
```

Format: `ACK:OBJECT:INSTANCE:STATE:optional note`

| Part | Example | Meaning |
| - | - | - |
| Object | `AI` | Analog Input |
| Instance | `0` | Object instance number |
| State | `HIGH_LIMIT` | Active alarm state to acknowledge |
| Note | `Checked by operator` | Optional operator comment |

Use the **state name** from the alarm (`HIGH_LIMIT`, `LOW_LIMIT`, `FAULT`, or `NORMAL`) — not labels like `OFFNORMAL`.

**Result on** `bacnet/bms/RoomTemp/alarms/ack/result`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "connector_name": "BMS",
  "operation": "ACK",
  "address": "AI:0",
  "event_state": "HIGH_LIMIT",
  "timestamp": "2026-06-10T16:30:00.000Z"
}
```

> [!WARNING]
>
> If `success` is `false`, the state or timestamp may not match what the device expects. Prefer the recommended method when possible — echo the alarm JSON and add `ack_text`.

> **Field device prerequisites**
>
> Before expecting MQTT alarms, confirm on the BMS or engineering tool:
>
> 1. **Notification Class** — recipient list includes `LOCAL_DEVICE_ID`
> 2. **Intrinsic alarming** on each object — `NOTIFICATION_CLASS`, `HIGH_LIMIT` / `LOW_LIMIT`, `EVENT_ENABLE`, `LIMIT_ENABLE`
> 3. **Present value** actually crosses a configured limit
>
> COV working does **not** guarantee alarms — they use separate BACnet services.

***

## On-Demand Events

Use `ADD EVENT` when you need a single read, write, or alarm acknowledgement triggered by an MQTT publish — instead of continuous TAG polling.

| Parameter | Required | Description |
| - | - | - |
| `SOURCE_TOPIC` | **Yes** | MQTT topic that triggers the BACnet operation |
| `DESTINATION_TOPIC` | **Yes** | MQTT topic where the JSON result is published |
| `QUERY` | **Yes** | BACnet operation: `READ:…`, `WRITE:…`, `ACK:…`, or JSON |
| `EVERY` | No | Not supported on BACnet events — use TAG polling instead |

### Query formats

| Style | Example | Notes |
| - | - | - |
| Colon-separated read | `READ:AI:0:PRESENT_VALUE` | Shorthand or full type name |
| Colon-separated write | `WRITE:AV:0:PRESENT_VALUE:72.5` | Value is everything after the property |
| JSON | `{"operation":"READ","object_type":"AI","instance":"0","property":"PRESENT_VALUE"}` | Also supports `"operation":"WRITE"` with `"value"` |
| Topic placeholder | `READ:{topic[0]}:0:PRESENT_VALUE` | `{topic[0]}` replaced from the matched MQTT topic segment |
| Dynamic payload | `{payload}` | Use the MQTT message body as the query (e.g. `WRITE:AV:0:PRESENT_VALUE:21.5`) |

Supported operations: **READ**, **WRITE**, and **ACK** (alarm acknowledgement).

```lot wrap focus={5-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
    ADD EVENT ReadProperty
        WITH SOURCE_TOPIC "bacnet/cmd/read"
        WITH DESTINATION_TOPIC "bacnet/cmd/read/result"
        WITH QUERY "READ:AI:0:PRESENT_VALUE"
```

Publish any message to `bacnet/cmd/read` and the result appears on `bacnet/cmd/read/result`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "connector_name": "BMS",
  "operation": "READ",
  "address": "AI:0",
  "property": "PRESENT_VALUE",
  "value": 22.5,
  "timestamp": "2026-05-31T10:00:00.000Z"
}
```

> [!WARNING]
>
> The connector must be connected before events run. If an event returns `"success": false`, check that the device is reachable and that the object and property in the query are correct.

### When to use what

| Need | Recommended approach |
| - | - |
| Periodic telemetry | `ADD MAPPING` + `ADD TAG` + `WITH EVERY` |
| Write from MQTT | `WITH WRITABLE true` + `WITH DESTINATION_TOPIC` on a tag |
| Ad-hoc read/write on command | `ADD EVENT` + `WITH QUERY` |
| Alarm acknowledgement | Auto-registered handler on `{tag_topic}/alarms/ack`, or custom `ADD EVENT` |

***

## Examples

**Simple polling**

Reads two analog inputs and one analog value every five seconds:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
    ADD MAPPING RoomSensors
        WITH SOURCE_TOPIC "bacnet/bms"
        WITH EVERY 5 SECONDS
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "degC"
        ADD TAG Humidity
            WITH ADDRESS "AI:1"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "%RH"
        ADD TAG Setpoint
            WITH ADDRESS "AV:0"
            WITH DATA_TYPE "FLOAT"
            WITH UNIT "degC"
```

Publishes to `bacnet/bms/RoomTemp` → `22.5`, `bacnet/bms/Humidity` → `55.0`, `bacnet/bms/Setpoint` → `21.0`.

**COV subscriptions**

Subscribe to Change-of-Value for fast-changing points — no polling interval needed:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
        WITH COV_LIFETIME 600
    ADD MAPPING CovPoints
        WITH SOURCE_TOPIC "bacnet/bms/cov"
        ADD TAG RoomTempCov
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
            WITH COV true
        ADD TAG OccupancyStatus
            WITH ADDRESS "BI:0"
            WITH DATA_TYPE "BOOL"
            WITH COV true
```

**Device-wide alarms**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
        WITH LOCAL_DEVICE_ID 4194300
        WITH ALARMS true
        WITH ALARMS_TOPIC "bacnet/bms/alarms"
    ADD MAPPING CovPoints
        WITH SOURCE_TOPIC "bacnet/bms"
        ADD TAG CovCounter
            WITH ADDRESS "AV:0"
            WITH DATA_TYPE "FLOAT"
            WITH COV true
```

Alarm events appear on `bacnet/bms/alarms`. Operator ACK via `bacnet/bms/alarms/ack`.

**Sandbox (Docker)**

Connects to the IOTech BACnet Docker simulator when the broker runs in another container:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Sandbox WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "coreflux-connector-bacnet"
        WITH PORT 47808
        WITH DEVICE_ID 1234
        WITH DIRECT_IP true
    ADD MAPPING TestPoints
        WITH SOURCE_TOPIC "bacnet/sandbox"
        WITH EVERY 2 SECONDS
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
        ADD TAG AnalogOut
            WITH ADDRESS "AO:0"
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
            WITH DESTINATION_TOPIC "bacnet/sandbox/AnalogOut/set"
```

***

## Combining with Models and Actions

A BACnet connector publishes each point to its own MQTT topic, so the rest of LoT can use that data like any other topic.

**Aggregate into a model**

First, the connector publishes each point under `bacnet/bms`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BMS WITH TYPE BACNET
    ADD BACNET_CONFIG
        WITH IP "192.168.1.10"
        WITH DEVICE_ID 1234
    ADD MAPPING RoomSensors
        WITH SOURCE_TOPIC "bacnet/bms"
        WITH EVERY 5 SECONDS
        ADD TAG RoomTemp
            WITH ADDRESS "AI:0"
            WITH DATA_TYPE "FLOAT"
        ADD TAG Humidity
            WITH ADDRESS "AI:1"
            WITH DATA_TYPE "FLOAT"
        ADD TAG Setpoint
            WITH ADDRESS "AV:0"
            WITH DATA_TYPE "FLOAT"
```

Then the model aggregates those topics into one object on `bacnet/bms/Info`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL BacnetRoomSensors COLLAPSED WITH TOPIC "bacnet/bms/Info"
    ADD DOUBLE "RoomTemp" WITH TOPIC "bacnet/bms/RoomTemp" AS TRIGGER
    ADD DOUBLE "Humidity" WITH TOPIC "bacnet/bms/Humidity"
    ADD DOUBLE "Setpoint" WITH TOPIC "bacnet/bms/Setpoint"
    ADD STRING "TimeStamp" WITH TIMESTAMP "ISO"
```

**Monitor alarm streams**

An action can watch per-tag alarm topics and forward events:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION BmsAlarmMonitor
ON TOPIC "bacnet/bms/+/alarms" DO
    PUBLISH TOPIC "site/alarm/log" WITH PAYLOAD
    PUBLISH TOPIC "site/alarm/last" WITH PAYLOAD
```

***

## Best Practices

> **Always set WITH IP explicitly**
>
> The default `192.168.1.1` is rarely correct. On Docker or routed networks, broadcast Who-Is may never reach the device. Set `WITH IP` to the controller's address or hostname.

> **Use Direct IP for unresponsive controllers**
>
> If a device does not answer Who-Is/I-Am, set `WITH DIRECT_IP true` to connect to `IP:PORT` and verify with ReadProperty. Otherwise the connector waits on discovery timeout every connect.

> **Use COV for fast-changing points**
>
> Polling at one-second intervals wastes bandwidth on BACnet/IP. Use `WITH COV true` for occupancy sensors, fast process variables, and alarm-related points.

> **Set LOCAL\_DEVICE\_ID before enabling alarms**
>
> The broker must announce itself as a BACnet device via directed I-Am so the field device knows where to send Event-Notifications.

> **Choose write priority deliberately**
>
> If a BMS holds a point at priority 1, a write at priority 8 will not change the present value. Match priority to your application and verify on the device.

> **Omit WITH EVERY from COV-only mappings**
>
> COV-only mappings do not need a polling interval. Adding `WITH EVERY` on a COV-only mapping adds confusion without benefit.

> **Use per-tag alarms for production points**
>
> Per-tag alarms (`WITH ALARM true`) give each monitoring point its own ACK topic. Use device-wide (`WITH ALARMS true`) as a catch-all or for commissioning.

> **Echo alarm JSON when acknowledging**
>
> Include `event_state_to_ack` and `bacnet_timestamp` from the received alarm message. Wrong state or missing timestamp causes ACK to fail.

***

## Troubleshooting

### Connection check

Publish `-checkConnectorConnection BMS` to `$SYS/Coreflux/Command`. The broker returns a JSON status for the named connector indicating whether the BACnet device was reached.

> **Discovery and connection issues**
>
> | Symptom | Check | Solution |
> | - | - | - |
> | Connector never connects | `IP` and `DEVICE_ID` correct? | Verify device IP; use Wireshark to confirm Who-Is packet sent |
> | Device not discovered | Device answers broadcast Who-Is? | Set `WITH DIRECT_IP true` if the device does not respond to Who-Is |
> | Docker: connector cannot reach device | `WITH IP "127.0.0.1"` in Docker? | Use the container hostname (e.g. `coreflux-connector-bacnet`) |
> | Discovery timeout on every connect | `DISCOVERY_TIMEOUT` too low? | Increase to 10+ seconds for slow devices |

> **Data issues**
>
> | Symptom | Check | Solution |
> | - | - | - |
> | No MQTT values | `DEVICE_ID` match device? | Sandbox default is `1234` — confirm with device profile |
> | Wrong object value | Instance number correct? | Verify object index in device BACnet browser or profile |
> | Write has no effect | Priority conflict? | Try `WITH WRITE_PRIORITY 1`; check if BMS holds a higher priority |
> | COV notifications not arriving | Device supports COV? | Check device profile; simulator may require `--cov` flag |

> **Alarm issues**
>
> | Symptom | Check | Solution |
> | - | - | - |
> | No MQTT alarms (COV works) | `LOCAL_DEVICE_ID` set? | Add non-zero `LOCAL_DEVICE_ID`; verify device Notification Class recipient |
> | Alarms on wrong topic | `SOURCE_TOPIC` or `ALARM_TOPIC` misconfigured? | Default is `{SOURCE_TOPIC}/{tagName}/alarms` |
> | ACK returns `success: false` | Wrong `event_state_to_ack`? | Echo the received alarm JSON with `ack_text` field added |
> | Events only after reconnect | Directed I-Am not sent? | Ensure `LOCAL_DEVICE_ID` is set and alarms are enabled before first connect |

> **Networking issues**
>
> | Symptom | Solution |
> | - | - |
> | `PORT` vs `LOCAL_PORT` confusion | `PORT` is the device's listen port (47808). `LOCAL_PORT` is the broker's bind port (leave `0`) |
> | Event returns `success: false` | Connector not connected, or wrong object/property in `QUERY`; check broker logs |
> | `LOCAL_DEVICE_ID is 0` warning | Set a non-zero device instance unique on the BACnet network |

### Additional resources

* [ASHRAE 135 Standard](https://www.ashrae.org/technical-resources/bookstore/bacnet) — official BACnet standard
* [BACnet International](https://www.bacnetinternational.org/) — conformance testing and product listings

***

## Next Steps

> **[Industrial Overview](./overview)**
>
> Learn the patterns shared across all OT connectors.

> **[OPC UA Client](./opcua-client)**
>
> Connect to cross-platform industrial servers with OPC UA.


# EtherNet/IP Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/ethernetip

Connect to CIP-compatible devices over EtherNet/IP with TAG polling, bit extraction, ARRAY/STRUCT decoding, and bidirectional writes.

## Connect to CIP Devices over EtherNet/IP

The `ETHERNETIP` connector connects Coreflux to CIP-compatible devices using EtherNet/IP **explicit messaging** (TCP port 44818). Define an `ETHERNETIP_CONFIG` block, add TAGs with CIP addresses, and publish each data point to its own MQTT topic — with optional scaling, bit extraction, joined attribute reads, and bidirectional writes.

> [!TIP]
>
> **Like reading labeled drawers in a filing cabinet.** Each CIP address (`Class.Instance.Attribute.Index`) points to a specific property on the device. The connector opens the drawer, reads the value, and places it on an MQTT topic — on a schedule or when you send a command.

### When to use this

Use the EtherNet/IP connector when you need explicit messaging to CIP objects on Allen-Bradley PLCs, remote I/O modules, VFDs, or other ODVA-compatible devices. Addresses use the numeric CIP path format `ClassID.InstanceID.AttributeID.AttributeIndex`.

> [!NOTE]
>
> For **symbolic tag names** (for example `Program:MainProgram.Temperature`), use the dedicated [Allen-Bradley connector](./allen-bradley) instead. The EtherNet/IP connector reads and writes via CIP class/instance/attribute paths.

### Key capabilities

* **Explicit messaging** — direct read/write to CIP attributes over TCP (port 44818)
* **TAG-based polling** — per-point MQTT topics with configurable intervals
* **Bit extraction** — `BIT_ADDRESS` to read a single bit from an integer word
* **Joined attribute reads** — combine bytes from two CIP attributes (legacy asset parity)
* **ARRAY and STRUCT decoding** — packed assembly buffers published as JSON arrays or objects
* **Bidirectional writes** — `WRITABLE` scalar tags with `DESTINATION_TOPIC`, and a result on `<DESTINATION_TOPIC>/result`
* **Engineering units** — `SCALING` / `OFFSET` / `DEADBAND` per tag

***

## Quick Start

**Poll a CIP attribute**

Read an analog input point every 500 ms and publish to MQTT:

```lot wrap focus={9-12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AnalogIO WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 44818
        WITH POLLING_MS 500
    ADD MAPPING AnalogInputs
        WITH EVERY 500 MILLISECONDS
        ADD TAG AnalogIn1
            WITH ADDRESS "102.1.3.0"
            WITH DATA_TYPE "FLOAT32"
            WITH SOURCE_TOPIC "io/analog/in/1"
```

**Read and write**

Poll an assembly output word and accept MQTT writes to update it:

```lot wrap focus={9-15} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AssemblyIO WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 44818
    ADD MAPPING Outputs
        WITH EVERY 500 MILLISECONDS
        ADD TAG OutputWord0
            WITH ADDRESS "4.104.3.0"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "eip/output/word0"
            WITH WRITABLE true
            WITH DESTINATION_TOPIC "eip/output/word0/set"
```

**Bit from a status word**

Extract alarm bit 5 from a UINT16 status attribute, joining a second CIP attribute for legacy device parity:

```lot wrap focus={12-22} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Kaeser WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "10.16.7.99"
        WITH PORT 44818
        WITH POLLING_MS 2000
    ADD MAPPING KaeserData
        WITH EVERY 1000 MILLISECONDS
        ADD TAG C1_Alarm
            WITH ADDRESS "4.100.3.1"
            WITH DATA_TYPE "BOOL"
            WITH BIT_ADDRESS 5
            WITH LENGTH 1
            WITH ENABLE_JOIN_ATTRIBUTE "true"
            WITH JOIN_CLASS_ID 120
            WITH JOIN_INSTANCE_ID 3711
            WITH JOIN_ATTRIBUTE_ID 1
            WITH JOIN_INDEX 0
            WITH JOIN_LENGTH 1
            WITH SOURCE_TOPIC "Air/Kaeser/Compressor/C1/Alerts/Alarm/Status"
```

**ARRAY from assembly**

Decode a packed INT32 array from an assembly buffer:

```lot wrap focus={9-14} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AssemblyArray WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 44818
    ADD MAPPING PackedData
        WITH EVERY 1 SECOND
        ADD TAG CounterArray
            WITH ADDRESS "4.104.1.0"
            WITH DATA_TYPE "ARRAY"
            WITH ARRAY_ELEMENT_TYPE "INT32"
            WITH ARRAY_SIZE 5
            WITH SOURCE_TOPIC "eip/assembly/counters"
```

***

## Connection Configuration

### ETHERNETIP\_CONFIG Parameters

| Parameter | Required | Default | Description |
| - | - | - | - |
| `IP` | Yes | — | Device IP address |
| `PORT` | No | `44818` | EtherNet/IP explicit messaging port (TCP) |
| `POLLING_MS` | No | `750` | Default polling interval in milliseconds |
| `CONNECTION_TIMEOUT` | No | `5000` | Connection timeout in milliseconds |
| `READ_WRITE_TIMEOUT` | No | `3000` | Longest wait for any reply, in milliseconds: session registration, reads and writes. A device slower than this is treated as disconnected and reconnected. |
| `RETRY_ATTEMPTS` | No | `3` | Retry count on failure (0–10) |
| `RETRY_TIME_SECONDS` | No | `5` | Delay between retries in seconds |

> [!NOTE]
>
> Raise `READ_WRITE_TIMEOUT` for slow devices or gateways. When a reply doesn't arrive in time, or the device closes the connection, the route goes to **Reconnecting**. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).

> [!NOTE]
>
> The config block may be declared as `ADD ETHERNETIP_CONFIG` or `ADD EIP_CONFIG` — both are equivalent.

### Connection Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD ETHERNETIP_CONFIG
    WITH IP "192.168.1.100"
    WITH PORT 44818
    WITH POLLING_MS 500
    WITH CONNECTION_TIMEOUT 5000
    WITH READ_WRITE_TIMEOUT 3000
    WITH RETRY_ATTEMPTS 3
    WITH RETRY_TIME_SECONDS 5
```

### Implicit I/O Mode (Forward Open)

> [!WARNING]
>
> **Not implemented in release 2.2.** The connector parser accepts `IO_MODE "IMPLICIT"` and related assembly/RPI settings for forward compatibility, but the broker does **not** establish Forward Open / cyclic UDP connections yet. Use explicit CIP assembly attributes (`4.x.y.z` paths) for I/O adapter devices until implicit mode ships.

Planned parameters (validated when present, not yet wired to the adapter):

| Parameter | Default | Description |
| - | - | - |
| `IO_MODE` | `EXPLICIT` | `EXPLICIT` (implemented) or `IMPLICIT` (planned) |
| `INPUT_ASSEMBLY` | `103` | T→O assembly instance (implicit mode) |
| `OUTPUT_ASSEMBLY` | `104` | O→T assembly instance (implicit mode) |
| `CONFIG_ASSEMBLY` | `1` | Configuration assembly for the connection path |
| `INPUT_SIZE` | `20` | Input assembly size in bytes |
| `OUTPUT_SIZE` | `12` | Output assembly size in bytes |
| `RPI` | `100000` | Requested Packet Interval in **microseconds** (e.g. `100000` = 100 ms) |

***

## CIP Addressing

EtherNet/IP uses CIP (Common Industrial Protocol) addressing. The adapter issues CIP `Get_Attribute_Single` / `Set_Attribute_Single` against numeric paths.

**Required format:** `ClassID.InstanceID.AttributeID.AttributeIndex` — four numeric segments, dot-separated.

| Component | Description | Example |
| - | - | - |
| ClassID | CIP object class | `4` (Assembly), `1` (Identity) |
| InstanceID | Object instance | `100`, `1` |
| AttributeID | Attribute number | `3` (Data on Assembly objects) |
| AttributeIndex | **Byte offset** within the attribute buffer where this tag's slice starts | `0` |

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Assembly attribute, full buffer from byte 0
WITH ADDRESS "4.100.3.0"

# Slice starting at byte 2 inside attribute 3 (packed bits)
WITH ADDRESS "4.110.1.2"

# Writable INT32 at instance 100, attribute 4
WITH ADDRESS "4.100.4.0"
```

### Common CIP Classes

| Class ID | Name | Description |
| - | - | - |
| 1 | Identity | Device identification |
| 2 | Message Router | Message routing |
| 4 | Assembly | I/O data assemblies |
| 6 | Connection Manager | Connection handling |
| 100 | Program Tags | Program-scoped tags (Allen-Bradley) |
| 107 | Controller Tags | Controller-scoped tags (Allen-Bradley) |
| 102 | Analog Input Point | Analog inputs |
| 103 | Analog Output Point | Analog outputs |
| 104 | Discrete Input Point | Digital inputs |
| 105 | Discrete Output Point | Digital outputs |

### EtherNet/IP Communication Types

| Type | Protocol | Port | Use case |
| - | - | - | - |
| Explicit messaging | TCP | 44818 | CIP read/write — **used by this connector** |
| Implicit messaging | UDP | 2222 | Cyclic real-time I/O — **not implemented in 2.2** |

***

## Data Types

| Data Type | Aliases | Size / format |
| - | - | - |
| `BOOLEAN` | `BOOL` | 1 bit |
| `BYTE` | `USINT` | 8 bits (unsigned) |
| `SINT` | — | 8 bits (signed) |
| `INT16` | `INT` | 16 bits |
| `UINT16` | `UINT` | 16 bits |
| `WORD` | — | 16 bits, published as IEC hex text (for example `16#ABCD`) |
| `INT32` | `DINT` | 32 bits |
| `UINT32` | `UDINT` | 32 bits |
| `DWORD` | — | 32 bits, published as IEC hex text (for example `16#DEAD_BEEF`) |
| `INT64` | `LINT` | 64 bits. Above `2^53`, every digit is published when no scaling, offset, minimum, or maximum is set |
| `UINT64` | `ULINT` | 64 bits. Same full-digit publishing as `INT64` when no scaling, offset, minimum, or maximum is set |
| `LWORD` | — | 64 bits, published as IEC hex text (for example `16#0123_4567_89AB_CDEF`) |
| `FLOAT32` | `REAL`, `FLOAT` | 32 bits |
| `FLOAT64` | `LREAL`, `DOUBLE` | 64 bits — MQTT values round to `DECIMAL_PLACES` (default `2`) |
| `CHAR` | — | Single ASCII character |
| `ASCII` | — | Read as `CHAR` (single-byte character) |
| `STRING` | — | CIP string: 2-byte `UINT16` length prefix + ASCII payload |
| `TIME` | — | Duration. Width and unit depend on the device |
| `TOD` | `TIME_OF_DAY` | Time of day. Width and unit depend on the device |
| `DATE` | — | Date. Width and unit depend on the device |
| `WCHAR` | — | 16-bit wide character, published as the character |
| `ARRAY` | — | Packed elements — requires `ARRAY_ELEMENT_TYPE` + `ARRAY_SIZE` |
| `STRUCT` | — | Packed fields — requires `LENGTH` + `STRUCT_FIELD_DEFINITIONS` |

> [!WARNING]
>
> `TIME`, `TOD`, and `DATE` width and unit are device-specific. Omron NJ/NX controllers store these values as 8 bytes in nanoseconds, which this connector does not decode. The published values come back wrong or as `0`.

> [!WARNING]
>
> `DATETIME`, `DTL`, and `DATE_AND_TIME` are rejected when the route is defined, with the message `DATETIME is not supported on ETHERNETIP`. The connector does not publish `0` for these types.

### String sizing

For `STRING` tags, `WITH LENGTH` sets the maximum string size in bytes. `STRING_SIZE` is accepted only as a parser alias for `STRING` sizing.

***

### Allen-Bradley Type Mapping

| Allen-Bradley | Coreflux `DATA_TYPE` |
| - | - |
| BOOL | `BOOL` |
| SINT | `SINT` |
| USINT | `BYTE` |
| INT | `INT16` |
| DINT | `INT32` |
| LINT | `INT64` |
| UINT | `UINT16` |
| UDINT | `UINT32` |
| ULINT | `UINT64` |
| REAL | `FLOAT32` |
| LREAL | `FLOAT64` |
| STRING | `STRING` |

`SINT` is signed. `BYTE` (alias `USINT`) is unsigned.

***

## TAG Configuration

Every polled data point is an `ADD TAG` inside an `ADD MAPPING` block. Tags without their own `SOURCE_TOPIC` inherit `{mapping SOURCE_TOPIC}/{tagName}` when the mapping sets a base topic.

### Complete TAG Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG ProcessTemperature
    WITH ADDRESS "102.1.3.0"
    WITH DATA_TYPE "FLOAT32"
    WITH SOURCE_TOPIC "eip/process/temperature"
    WITH SCALING_FACTOR 0.1
    WITH OFFSET 0
    WITH DEADBAND 0.5
    WITH PUBLISH_MODE "JSON"
    WITH LENGTH 1
```

### TAG Parameters

> **Address and data type**
>
> **ADDRESS** `string` *required*
>
> CIP path: `ClassID.InstanceID.AttributeID.AttributeIndex`
>
> **DATA\_TYPE** `string` *required*
>
> CIP data type (see table above).
>
> **LENGTH** `integer`
>
> Bytes to read from the primary CIP attribute starting at `AttributeIndex` (the fourth segment of `ADDRESS`). Default: `1`. For `STRING` tags, this is the maximum string size in bytes; `STRING_SIZE` is accepted only as a parser alias for that `STRING` sizing (not for join, `STRUCT`, or generic attribute-width uses). For numeric tags in join mode, `LENGTH + JOIN_LENGTH` must equal the byte width of `DATA_TYPE` (for example `1 + 1 = 2` for `INT16`).
>
> **BIT\_ADDRESS** `integer`
>
> Extract a single bit (0-based) from the underlying integer word. Alias: `BIT`. Use with integer types (`UINT16`, `INT32`, etc.) or with `BOOL` when the device returns a packed word. For `BOOL` + `BIT_ADDRESS`, read width auto-widens: bits 0–7 read 1 byte, 8–15 read 2 bytes, 16–31 read 4 bytes, 32–63 read 8 bytes.

> **Joined attribute reads**
>
> **ENABLE\_JOIN\_ATTRIBUTE** `string`
>
> When `"true"`, perform a second CIP `Get_Attribute_Single` against the join target and concatenate those bytes onto the primary read before parsing, scaling, or bit extraction. Default: `false`.
>
> **JOIN\_CLASS\_ID** `integer`
>
> CIP Class ID of the joined attribute. Required when `ENABLE_JOIN_ATTRIBUTE` is `true` (must be > 0).
>
> **JOIN\_INSTANCE\_ID** `integer`
>
> CIP Instance ID of the joined attribute. Required when join is enabled (must be >= 0; instance `0` is valid on some devices).
>
> **JOIN\_ATTRIBUTE\_ID** `integer`
>
> CIP Attribute ID of the joined attribute. Required when join is enabled (must be > 0).
>
> **JOIN\_INDEX** `integer`
>
> Byte offset within the joined CIP response where the slice starts. Default: `0`.
>
> **JOIN\_LENGTH** `integer`
>
> Bytes to take from the joined attribute starting at `JOIN_INDEX`. Required when join is enabled (must be > 0). **Not** related to `SCALING_FACTOR`.

> **Value transformation**
>
> **SCALING** `decimal`
>
> Multiply the parsed numeric value after byte parsing. Alias: `SCALING_FACTOR`. Default: `1.0`. **Unrelated to byte layout** — does not replace `JOIN_LENGTH`.
>
> **OFFSET** `decimal`
>
> Add after scaling. Default: `0.0`.
>
> **DEADBAND** `decimal`
>
> Suppress MQTT publish when the change is below this threshold. Default: `0.0`.
>
> **DECIMAL\_PLACES** `integer`
>
> Decimal places for `FLOAT32` / `FLOAT64` MQTT payloads. Default: `2`.

> **Publishing and writes**
>
> **SOURCE\_TOPIC** `string`
>
> MQTT topic where polled values are published.
>
> **PUBLISH\_MODE** `string`
>
> `VALUE_ONLY` (default — publish just the value) or `JSON` (value, quality, and timestamp). Aliases: `VALUE`, `SIMPLE` for value-only; `FULL`, `METADATA` for JSON.
>
> **WRITABLE** `boolean`
>
> When `true`, subscribe to `DESTINATION_TOPIC` and write incoming MQTT values to the device.
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to receive write commands. Required when `WRITABLE` is `true`. Each write publishes its outcome on `<DESTINATION_TOPIC>/result`.

### Publish Modes

**VALUE\_ONLY** (default) — publishes just the scaled scalar value:

```
75.5
```

**JSON** — publishes a metadata wrapper when explicitly set:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "tag_name": "AnalogIn1",
  "value": 75.5,
  "quality": "GOOD",
  "timestamp": "2025-12-17T10:30:45.123Z"
}
```

### Writes

Publish a value to `DESTINATION_TOPIC` on a tag with `WRITABLE true`. The connector sends a CIP `Set_Attribute_Single` and publishes the outcome on `<DESTINATION_TOPIC>/result`. The connection stays up whether the device accepts the write or rejects it.

When the device accepts the write, the result has `"success": true`.

When the device rejects the write, the result has `"success": false`, an `error` string, and a numeric `cip_status`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": false,
  "error": "CIP status 0x13 (Insufficient command data)",
  "cip_status": 19
}
```

| CIP status | Meaning |
| - | - |
| `0x13` | Not enough data (`cip_status` 19) |
| `0x15` | Too much data |
| `0x0E` | Attribute not settable |

`WORD`, `DWORD`, and `LWORD` write payloads are parsed as hexadecimal (`16#XXXX`, `0xXXXX`, or plain hex). A payload of `99` is written as `0x99` (153).

### Using an Omron NJ/NX

Through this connector, variables are reached as Tag Data Link Assemblies, not by name. A write to an input or output Assembly can be answered OK and ignored by the controller (measured on an NX1P2). Writing a variable by name needs CIP services this connector does not implement.

### ARRAY and STRUCT Tags

CIP assembly buffers often contain packed arrays or structured records. Use `DATA_TYPE "ARRAY"` or `DATA_TYPE "STRUCT"` to decode them into JSON on MQTT.

#### ARRAY

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG ArrInt32
    WITH ADDRESS "4.104.1.0"
    WITH DATA_TYPE "ARRAY"
    WITH ARRAY_ELEMENT_TYPE "INT32"
    WITH ARRAY_SIZE 5
    WITH SOURCE_TOPIC "eip/complex/arr_int32"
```

| Parameter | Required | Description |
| - | - | - |
| `ARRAY_ELEMENT_TYPE` | Yes | Element type (`INT32`, `FLOAT`, `BOOLEAN`, etc.) |
| `ARRAY_SIZE` | Yes | Number of elements |
| `ARRAY_ELEMENT_LENGTH` | No | Byte width per element (for `STRING` / nested `STRUCT` elements) |
| `ARRAY_START_OFFSET` | No | Skip N bytes before the first element |
| `ARRAY_ELEMENT_HEADER_SIZE` | No | Skip N bytes at the start of each element |

**MQTT payload:** JSON array, e.g. `[10, 20, 30, 40, 50]`.

#### STRUCT

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG StructTag
    WITH ADDRESS "4.105.1.0"
    WITH DATA_TYPE "STRUCT"
    WITH LENGTH 12
    WITH STRUCT_FIELD_DEFINITIONS "temp:0:FLOAT:4,pressure:4:FLOAT:4,status:8:INT32:4"
    WITH SOURCE_TOPIC "eip/complex/struct"
```

Field spec format: `name:byte_offset:type:size` (comma-separated). Field types accept the same aliases as scalar `DATA_TYPE`, including `FLOAT32` and `FLOAT64`. An unknown field type publishes `null` for that field and the broker logs a warning.

**MQTT payload:** JSON object, e.g. `{"temp":25.5,"pressure":101.325,"status":1}`.

> [!WARNING]
>
> ARRAY and STRUCT tags are **read-focused** in release 2.2. Writable scalar tags use normal CIP encoding; complex-type writes from JSON arrays/objects are not yet supported.

### Joined Attribute Reads

Some legacy CIP devices split a logical value across two attributes (for example a status word plus an extension attribute). When `ENABLE_JOIN_ATTRIBUTE` is `"true"`, the broker performs two `Get_Attribute_Single` reads per cycle, concatenates the byte buffers (primary first, joined second), then parses, scales, and applies `BIT_ADDRESS`.

If the join read fails, a warning is logged and the primary buffer is parsed alone — the polling loop continues.

> [!WARNING]
>
> For numeric `DATA_TYPE` values in join mode, `LENGTH + JOIN_LENGTH` must equal the type byte width (`2` for 16-bit, `4` for 32-bit, `8` for 64-bit). `BOOL` tags with `BIT_ADDRESS` are exempt (Kaeser-style alarm bit pattern).

> [!WARNING]
>
> `SCALING` / `SCALING_FACTOR` multiplies the parsed value — it does **not** replace `JOIN_LENGTH`. Using scaling to compensate for a missing join length produces silently wrong values.

***

## Migrating from a Legacy EtherNet/IP Asset

If you are converting an EtherNet/IP **Asset** (Coreflux HUB Configure / Tags panel) into a Connector, map each asset field to the LoT parameter below.

| Asset field (HUB) | Connector LoT parameter | Notes |
| - | - | - |
| Class Id / Instance Id / Attribute Id / Attribute Index | `WITH ADDRESS "C.I.A.Index"` | Four numeric segments separated by `.` |
| Data Type | `WITH DATA_TYPE "<type>"` | See aliases above |
| Bit | `WITH BIT_ADDRESS <n>` (alias `WITH BIT <n>`) | For boolean bits packed in an integer word |
| Length | `WITH LENGTH <n>` | Bytes from the primary attribute |
| Enable Join Attribute | `WITH ENABLE_JOIN_ATTRIBUTE "true"` | Quoted `"true"` / `"false"` |
| Join Class / Instance / Attribute Id | `JOIN_CLASS_ID`, `JOIN_INSTANCE_ID`, `JOIN_ATTRIBUTE_ID` | |
| Join Index | `WITH JOIN_INDEX <n>` | Byte offset in joined response |
| Join Length | `WITH JOIN_LENGTH <n>` | Bytes from joined attribute — **not** `SCALING` |
| Topic (Source) | `WITH SOURCE_TOPIC "<topic>"` | Where polled values publish |
| Write Direction | `WITH WRITABLE "true"` + `WITH DESTINATION_TOPIC "<topic>"` | For MQTT-to-device writes |

***

## Examples

**Device identity**

Read identity object attributes on a slow interval:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceIdentity WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 44818
    ADD MAPPING IdentityData
        WITH EVERY 30 SECONDS
        ADD TAG VendorID
            WITH ADDRESS "1.1.1.0"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "device/identity/vendor"
        ADD TAG SerialNumber
            WITH ADDRESS "1.1.6.0"
            WITH DATA_TYPE "UINT32"
            WITH SOURCE_TOPIC "device/identity/serial"
        ADD TAG ProductName
            WITH ADDRESS "1.1.7.0"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 32
            WITH SOURCE_TOPIC "device/identity/name"
```

**Scaled analog input**

Read a 4–20 mA value with engineering-unit scaling and deadband:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AnalogInputs WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "192.168.1.40"
    ADD MAPPING AnalogData
        WITH EVERY 500 MILLISECONDS
        ADD TAG TankLevel
            WITH ADDRESS "102.1.3.0"
            WITH DATA_TYPE "INT16"
            WITH SCALING_FACTOR 0.00625
            WITH OFFSET -25.0
            WITH DEADBAND 1.0
            WITH SOURCE_TOPIC "tank/level"
```

**Kaeser compressor status**

Three boolean status bits from one INT16 word with joined attributes (legacy asset parity):

```lot wrap focus={12-28} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Kaeser WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "10.16.7.99"
        WITH PORT 44818
        WITH POLLING_MS 2000
    ADD MAPPING KaeserData
        WITH EVERY 1000 MILLISECONDS
        ADD TAG C1_On
            WITH ADDRESS "4.100.3.1"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "Air/Kaeser/Compressor/C1/On"
        ADD TAG C1_Alarm
            WITH ADDRESS "4.100.3.1"
            WITH DATA_TYPE "BOOL"
            WITH BIT 5
            WITH LENGTH 1
            WITH ENABLE_JOIN_ATTRIBUTE "true"
            WITH JOIN_CLASS_ID 120
            WITH JOIN_INSTANCE_ID 3711
            WITH JOIN_ATTRIBUTE_ID 1
            WITH JOIN_INDEX 0
            WITH JOIN_LENGTH 1
            WITH SOURCE_TOPIC "Air/Kaeser/Compressor/C1/Alerts/Alarm/Status"
        ADD TAG C1_Alert
            WITH ADDRESS "4.100.3.1"
            WITH DATA_TYPE "BOOL"
            WITH BIT 6
            WITH LENGTH 1
            WITH ENABLE_JOIN_ATTRIBUTE "true"
            WITH JOIN_CLASS_ID 120
            WITH JOIN_INSTANCE_ID 3711
            WITH JOIN_ATTRIBUTE_ID 1
            WITH JOIN_INDEX 0
            WITH JOIN_LENGTH 1
            WITH SOURCE_TOPIC "Air/Kaeser/Compressor/C1/Alerts/Alert/Status"
```

**Multi-rate polling**

Fast critical data and slow diagnostics in one connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiRateEIP WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 44818
    ADD MAPPING FastData
        WITH EVERY 100 MILLISECONDS
        ADD TAG CriticalStatus
            WITH ADDRESS "104.1.3.0"
            WITH DATA_TYPE "BOOLEAN"
            WITH SOURCE_TOPIC "fast/status"
    ADD MAPPING SlowData
        WITH EVERY 5 SECONDS
        ADD TAG DeviceStatus
            WITH ADDRESS "1.1.5.0"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "slow/device_status"
```

**ARRAY and STRUCT**

Decode packed assembly data as JSON:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ComplexAssembly WITH TYPE ETHERNETIP
    ADD ETHERNETIP_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 44818
    ADD MAPPING PackedData
        WITH EVERY 1 SECOND
        ADD TAG TempArray
            WITH ADDRESS "4.104.1.0"
            WITH DATA_TYPE "ARRAY"
            WITH ARRAY_ELEMENT_TYPE "INT32"
            WITH ARRAY_SIZE 5
            WITH SOURCE_TOPIC "eip/array/counters"
        ADD TAG ProcessStruct
            WITH ADDRESS "4.105.1.0"
            WITH DATA_TYPE "STRUCT"
            WITH LENGTH 12
            WITH STRUCT_FIELD_DEFINITIONS "temp:0:FLOAT:4,pressure:4:FLOAT:4,status:8:INT32:4"
            WITH SOURCE_TOPIC "eip/struct/process"
```

***

## CIP Object Reference

> **Identity Object (Class 1)**
>
> | Attribute | Description | Data Type |
> | - | - | - |
> | 1 | Vendor ID | UINT16 |
> | 2 | Device Type | UINT16 |
> | 3 | Product Code | UINT16 |
> | 4 | Revision | UINT16\[2] |
> | 5 | Status | UINT16 |
> | 6 | Serial Number | UINT32 |
> | 7 | Product Name | STRING |

> **Analog Input Point (Class 102)**
>
> | Attribute | Description | Data Type |
> | - | - | - |
> | 3 | Value | FLOAT32 / INT16 |
> | 4 | Status | UINT16 |
> | 5 | Scaling Minimum | FLOAT32 |
> | 6 | Scaling Maximum | FLOAT32 |

> **Discrete Input Point (Class 104)**
>
> | Attribute | Description | Data Type |
> | - | - | - |
> | 3 | Value | BOOLEAN |
> | 4 | Status | UINT16 |

> **Assembly Object (Class 4)**
>
> | Attribute | Description | Data Type |
> | - | - | - |
> | 3 | Data | Variable |
> | 4 | Size | UINT16 |

***

## Best Practices

> **Polling intervals**
>
> Match the interval to how fast the value changes: 100 ms for safety-critical data, 1 s for process variables, 10 s or more for slow-changing status.

> **Deadbands**
>
> Use `DEADBAND` on noisy analog values to reduce MQTT traffic. Set `0.0` on digital status tags so every change publishes.

> **Timeouts on slow networks**
>
> Increase `CONNECTION_TIMEOUT` and `READ_WRITE_TIMEOUT` on congested or remote networks. Raise `RETRY_ATTEMPTS` when connections are intermittent.

> **Join attribute layout**
>
> Always set `JOIN_LENGTH` explicitly when `ENABLE_JOIN_ATTRIBUTE` is `"true"`. Verify `LENGTH + JOIN_LENGTH` matches the numeric type width before deploying to production.

> **Symbolic vs CIP paths**
>
> Use numeric CIP paths on this connector. For Rockwell tag-name access (`Program:MainProgram.Counter`), use the [Allen-Bradley connector](./allen-bradley).

***

## Troubleshooting

> **Connection failed**
>
> * Verify IP with `ping`
> * Confirm port 44818 (TCP) is open through firewalls
> * Ensure the device is powered and allows external connections
> * Increase `CONNECTION_TIMEOUT` and `RETRY_ATTEMPTS`

> **CIP path error**
>
> * Confirm four-segment format: `ClassID.InstanceID.AttributeID.AttributeIndex`
> * Check the device manual for valid class/instance/attribute numbers
> * Instance numbering varies by device (often starts at 1, not 0)

> **Wrong or stale values**
>
> * Verify `DATA_TYPE` matches the device attribute
> * Check `DEADBAND` is not suppressing small changes
> * For join tags, confirm `JOIN_LENGTH` and `LENGTH` byte layout
> * For bit tags, confirm `BIT_ADDRESS` is within the read width
> * `WORD`, `DWORD`, and `LWORD` publish IEC hex text (for example `16#ABCD`)
> * `INT64` and `UINT64` above `2^53` publish every digit when no scaling, offset, minimum, or maximum is set
> * On an Omron NJ/NX, `TIME`, `TOD`, and `DATE` are 8-byte nanosecond values this connector does not decode, so they come back wrong or as `0`

> **Route definition rejected**
>
> * `DATETIME`, `DTL`, and `DATE_AND_TIME` are rejected with the message `DATETIME is not supported on ETHERNETIP`

> **Write did not change the device**
>
> * Read `<DESTINATION_TOPIC>/result`. `"success": false` means the device rejected the CIP write. The connection stays up. `cip_status` 19 (`0x13`) is not enough data, `0x15` is too much data, and `0x0E` means the attribute is not settable
> * `WORD`, `DWORD`, and `LWORD` payloads are hexadecimal. `99` is written as `0x99` (153)
> * On an Omron NJ/NX, a write to an input or output Assembly can be answered OK and ignored by the controller

> **Join attribute rejected at startup**
>
> * `JOIN_CLASS_ID` and `JOIN_ATTRIBUTE_ID` must be > 0
> * `JOIN_INSTANCE_ID` must be present and >= 0
> * `JOIN_LENGTH` must be > 0
> * For numeric types, `LENGTH + JOIN_LENGTH` must equal the type byte width (unless `BOOL` + `BIT_ADDRESS`)

***

## Next Steps

> **[Allen-Bradley Connector](./allen-bradley)**
>
> Symbolic tag-name access for ControlLogix, CompactLogix, and MicroLogix PLCs.

> **[Industrial Connectors Overview](./overview)**
>
> Compare OT connectors and choose the right protocol for your devices.


# FINS Connector (Omron)
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/fins

Connect to Omron PLCs using FINS protocol with support for multiple memory areas and TCP/UDP transport

## FINS Overview

The `FINS` connector enables communication with Omron PLCs (CJ, CS, CP, and NJ/NX series) using the FINS (Factory Interface Network Service) protocol. It supports both TCP and UDP transport, multiple memory areas, and bit-level access.

> [!TIP]
>
> FINS is Omron's native protocol providing fast, efficient access to PLC memory. For newer NJ/NX series, consider OPC UA as an alternative.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronPLC WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
        WITH LOCAL_NODE 0
        WITH REMOTE_NODE 0
    ADD MAPPING ProcessData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
```

***

## Connection Configuration

### FINS\_CONFIG Parameters

**IP** `string` *required*

Target Omron device IP address.

**PORT** `integer`

FINS protocol port. Default: 9600.

**PROTOCOL** `string`

Protocol type: `TCP` or `UDP`. Default: TCP.

**LOCAL\_NODE** `integer`

Local node address (0-255). Default: 0.

**REMOTE\_NODE** `integer`

Remote node address - target PLC (0-255). Default: 0.

**TIMEOUT** `integer`

Reply timeout per attempt, in seconds. Default: 5. A read or write can take up to (`RETRIES` + 1) × `TIMEOUT`, plus backoff and 2 s, before it fails (33.5 s with the defaults).

**RETRIES** `integer`

Number of retries for FINS communication. Default: 5.

**POLLING** `integer`

Polling interval in milliseconds. Default: 200.

> [!NOTE]
>
> On FINS/UDP the route goes to **Reconnecting** after 2 commands in a row get no reply. On FINS/TCP a connection with no answered attempt is closed and reopened. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).

### Connection Examples

**TCP Connection**

Standard TCP connection (recommended):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD FINS_CONFIG
    WITH IP "192.168.1.100"
    WITH PORT 9600
    WITH PROTOCOL "TCP"
    WITH LOCAL_NODE 0
    WITH REMOTE_NODE 0
    WITH TIMEOUT 2
    WITH RETRIES 5
```

> [!NOTE]
>
> TCP transport for FINS is currently in development. Use UDP for production deployments.

**UDP Connection**

UDP for lower latency:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD FINS_CONFIG
    WITH IP "192.168.1.100"
    WITH PORT 9600
    WITH PROTOCOL "UDP"
    WITH LOCAL_NODE 1
    WITH REMOTE_NODE 0
    WITH TIMEOUT 2
```

> [!NOTE]
>
> UDP requires proper node addressing and may have firewall considerations.

***

## Memory Areas

Omron PLCs organize data in different memory areas:

| Memory Type | Code | Description | Access |
| - | - | - | - |
| `CIO` | 0 | Core I/O and work area | Read/Write |
| `WR` | 1 | Work area | Read/Write |
| `HR` | 2 | Holding area (retentive) | Read/Write |
| `AR` | 3 | Auxiliary area | Read-only |
| `DM` | 4 | Data Memory | Read/Write |
| `CNT` | 5 | Counter values | Read/Write |
| `TIM` | 6 | Timer values | Read/Write |
| `EM` | 7 | Extended Memory | Read/Write |

> [!NOTE]
>
> DM (Data Memory) is the most commonly used area for user data. CIO is typically used for I/O and internal relays.

***

## Data Types

| Data Type | Description | Size |
| - | - | - |
| `BOOL` | Boolean (single bit) | 1 bit |
| `BYTE` | Unsigned 8-bit | 8 bits |
| `SINT` | Signed 8-bit integer | 8 bits |
| `USINT` | Unsigned 8-bit integer | 8 bits |
| `INT` | Signed 16-bit integer | 16 bits |
| `UINT` / `WORD` | Unsigned 16-bit integer | 16 bits |
| `DINT` | Signed 32-bit integer | 32 bits |
| `UDINT` / `DWORD` | Unsigned 32-bit integer | 32 bits |
| `LINT` | Signed 64-bit integer | 64 bits |
| `ULINT` / `LWORD` | Unsigned 64-bit integer | 64 bits |
| `REAL` / `FLOAT` | 32-bit floating point | 32 bits |
| `LREAL` / `DOUBLE` | 64-bit floating point | 64 bits |
| `CHAR` | Single character | 8 bits |
| `WCHAR` | Wide character | 16 bits |
| `TIME` | Time duration | 32 bits |
| `DATE` | Date value | 16 bits |
| `TOD` | Time of day | 32 bits |
| `ASCII` | ASCII string | 8 bits |
| `STRING` | String value; sized with `LENGTH` | Variable |

### String sizing

For `STRING` tags, `WITH LENGTH` is the string **payload** size in bytes and defaults to **256**. `STRING_SIZE` is accepted as an alias for the same field. The FINS connector reserves **two additional header bytes**, so the protocol buffer is `LENGTH + 2` bytes.

Read a product label stored as a STRING in DM memory:

```lot wrap focus={14} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronStrings WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
        WITH LOCAL_NODE 176
        WITH REMOTE_NODE 201
    ADD MAPPING Labels
        WITH EVERY 1 SECOND
        ADD TAG ProductLabel
            WITH ADDRESS "500"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 256
            WITH SOURCE_TOPIC "production/label"
```

***

## TAG Configuration

### Complete TAG Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG ProcessTemperature
    WITH ADDRESS "100"
    WITH BIT_ADDRESS 0
    WITH DATA_TYPE "REAL"
    WITH MEMORY_TYPE "DM"
    WITH SOURCE_TOPIC "plc/process/temperature"
    WITH DESTINATION_TOPIC "plc/process/temperature/write"
    WITH WRITABLE "true"
    WITH SCALING 0.1
    WITH OFFSET 0
    WITH UNIT "°C"
    WITH DECIMAL_PLACES 2
    WITH MIN_VALUE -50
    WITH MAX_VALUE 500
    WITH DEADBAND 0.5
    WITH PUBLISH_MODE "JSON"
    WITH DESCRIPTION "Main process temperature sensor"
```

### TAG Parameters

> **Address Configuration**
>
> **ADDRESS** `string` *required*
>
> Word address in PLC memory (e.g., 100, 200, 500).
>
> **BIT\_ADDRESS** `integer`
>
> Bit address for bit-specific data types (0-15). Used for BOOL values within a word.
>
> **MEMORY\_TYPE** `string`
>
> Memory area: `CIO`, `WR`, `HR`, `AR`, `DM`, `CNT`, `TIM`, `EM`. Default: DM.
>
> **DATA\_TYPE** `string` *required*
>
> FINS data type: BOOL, BYTE, INT, UINT, DINT, UDINT, LINT, ULINT, REAL, LREAL, ASCII, STRING.
>
> **LENGTH** `integer`
>
> String payload size in bytes; FINS adds two header bytes (`LENGTH + 2` on the wire). Default: **256**. Alias: `STRING_SIZE`.

> **Value Transformation**
>
> **SCALING** `double`
>
> Multiplier for value transformation. Default: 1.0.
>
> **OFFSET** `double`
>
> Offset added after scaling. Default: 0.0.
>
> **DECIMAL\_PLACES** `integer`
>
> Decimal places in output. Default: 2.

> **Filtering**
>
> **MIN\_VALUE** `double`
>
> Minimum allowed value.
>
> **MAX\_VALUE** `double`
>
> Maximum allowed value.
>
> **DEADBAND** `double`
>
> Minimum change to trigger publish. Default: 0.0.

> **Publishing**
>
> **SOURCE\_TOPIC** `string` *required*
>
> Topic where PLC values are published. Subscribe here to receive sensor data.
>
> **DESTINATION\_TOPIC** `string`
>
> Topic to send write commands. Publish a value here to write it to the PLC.
>
> **PUBLISH\_MODE** `string`
>
> Output format: `VALUE_ONLY` or `JSON`. Default: VALUE\_ONLY.
>
> **UNIT** `string`
>
> Engineering unit for documentation.
>
> **DESCRIPTION** `string`
>
> Human-readable description.

> **Write Configuration**
>
> **WRITABLE** `boolean`
>
> Allow writing to this address. Default: false.

***

## Addressing Examples

### Word Addressing

Access data at word level:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG DataWord100
    WITH ADDRESS "100"
    WITH MEMORY_TYPE "DM"
    WITH DATA_TYPE "INT"
    WITH SOURCE_TOPIC "plc/dm/100"
```

### Bit Addressing

Access individual bits within a word:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG Bit0
    WITH ADDRESS "100"
    WITH BIT_ADDRESS 0
    WITH MEMORY_TYPE "DM"
    WITH DATA_TYPE "BOOL"
    WITH SOURCE_TOPIC "plc/dm/100.0"

ADD TAG Bit15
    WITH ADDRESS "100"
    WITH BIT_ADDRESS 15
    WITH MEMORY_TYPE "DM"
    WITH DATA_TYPE "BOOL"
    WITH SOURCE_TOPIC "plc/dm/100.15"
```

### 32-bit Values

32-bit values span two consecutive words:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG FloatValue
    WITH ADDRESS "200"
    WITH MEMORY_TYPE "DM"
    WITH DATA_TYPE "REAL"
    WITH SOURCE_TOPIC "plc/float"
```

> [!NOTE]
>
> REAL and DINT types use two consecutive words (e.g., DM200 and DM201).

***

## Event-Based Operations

For on-demand FINS operations (not polling), use the EVENT syntax. Publish a message to SOURCE\_TOPIC to trigger the operation; the connector executes it and publishes the result to DESTINATION\_TOPIC.

### Supported Operations

| Operation | Description | Query Parameters |
| - | - | - |
| `READ` | Read from a memory area on demand | `memory_type`, `address`, `data_type`, `count` |
| `WRITE` | Write a value to a memory area | `memory_type`, `address`, `data_type`, `value` |

### Query Parameters

| Parameter | Description | Example |
| - | - | - |
| `operation` | Operation type: `READ` or `WRITE` | `READ` |
| `memory_type` | Memory area: `DM`, `CIO`, `WR`, `HR`, `AR`, `TIM`, `CNT`, `EM` | `DM` |
| `address` | Word address in the memory area | `100`, `200` |
| `data_type` | FINS data type | `REAL`, `INT`, `UINT`, `DINT`, `BOOL` |
| `count` | Number of consecutive values to read (READ only) | `10` |
| `value` | Value to write (WRITE only) | `25.5`, `100`, `true` |

### Read Example

Read a REAL value from DM area on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadDM
    WITH SOURCE_TOPIC "fins/commands/read"
    WITH DESTINATION_TOPIC "fins/responses/read"
    WITH QUERY "{operation: READ, memory_type: DM, address: 100, data_type: REAL}"
```

### Write Example

Write a REAL value to DM area on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT WriteDM
    WITH SOURCE_TOPIC "fins/commands/write"
    WITH DESTINATION_TOPIC "fins/responses/write"
    WITH QUERY "{operation: WRITE, memory_type: DM, address: 200, data_type: REAL, value: 25.5}"
```

***

## Complete Examples

**Basic Data Memory Reading**

Read values from DM area:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronBasic WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
        WITH LOCAL_NODE 0
        WITH REMOTE_NODE 0
    ADD MAPPING DataMemory
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
            WITH SCALING 0.1
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "102"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/pressure"
            WITH UNIT "bar"
        ADD TAG Counter
            WITH ADDRESS "104"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "DINT"
            WITH SOURCE_TOPIC "plc/counter"
```

**I/O and Work Areas**

Read CIO and Work areas:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronIO WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
    ADD MAPPING IOStatus
        WITH EVERY 100 MILLISECONDS
        ADD TAG DigitalInputs
            WITH ADDRESS "0"
            WITH MEMORY_TYPE "CIO"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/io/di"
        ADD TAG DigitalOutputs
            WITH ADDRESS "100"
            WITH MEMORY_TYPE "CIO"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/io/do"
        ADD TAG WorkBits
            WITH ADDRESS "0"
            WITH MEMORY_TYPE "WR"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/work"
```

**Bit-Level Access**

Access individual bits:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronBits WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
    ADD MAPPING BitStatus
        WITH EVERY 100 MILLISECONDS
        ADD TAG StartButton
            WITH ADDRESS "0"
            WITH BIT_ADDRESS 0
            WITH MEMORY_TYPE "CIO"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/buttons/start"
        ADD TAG StopButton
            WITH ADDRESS "0"
            WITH BIT_ADDRESS 1
            WITH MEMORY_TYPE "CIO"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/buttons/stop"
        ADD TAG MotorRunning
            WITH ADDRESS "100"
            WITH BIT_ADDRESS 0
            WITH MEMORY_TYPE "CIO"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/motor/running"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "plc/motor/running/set"
```

**Timers and Counters**

Read timer and counter values:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronTimerCounter WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
    ADD MAPPING TimersCounters
        WITH EVERY 500 MILLISECONDS
        ADD TAG Timer0
            WITH ADDRESS "0"
            WITH MEMORY_TYPE "TIM"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/timer/0"
            WITH SCALING 0.1
            WITH UNIT "s"
        ADD TAG Timer1
            WITH ADDRESS "1"
            WITH MEMORY_TYPE "TIM"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/timer/1"
        ADD TAG Counter0
            WITH ADDRESS "0"
            WITH MEMORY_TYPE "CNT"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/counter/0"
        ADD TAG Counter1
            WITH ADDRESS "1"
            WITH MEMORY_TYPE "CNT"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/counter/1"
```

**Bidirectional Control**

Read and write process values:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronControl WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
    ADD MAPPING ControlLoop
        WITH EVERY 200 MILLISECONDS
        ADD TAG ProcessValue
            WITH ADDRESS "200"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/pv"
            WITH UNIT "°C"
            WITH PUBLISH_MODE "JSON"
        ADD TAG Setpoint
            WITH ADDRESS "202"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/sp"
            WITH UNIT "°C"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/sp/write"
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
        ADD TAG Output
            WITH ADDRESS "204"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/output"
            WITH UNIT "%"
        ADD TAG AutoMode
            WITH ADDRESS "206"
            WITH BIT_ADDRESS 0
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "control/auto"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/auto/write"
```

**Holding Area**

Read retentive data from HR area:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OmronHolding WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
    ADD MAPPING RetentiveData
        WITH EVERY 5 SECONDS
        ADD TAG TotalRuntime
            WITH ADDRESS "0"
            WITH MEMORY_TYPE "HR"
            WITH DATA_TYPE "DINT"
            WITH SOURCE_TOPIC "plc/stats/runtime"
            WITH UNIT "seconds"
        ADD TAG ProductionTotal
            WITH ADDRESS "2"
            WITH MEMORY_TYPE "HR"
            WITH DATA_TYPE "DINT"
            WITH SOURCE_TOPIC "plc/stats/production"
        ADD TAG LastErrorCode
            WITH ADDRESS "4"
            WITH MEMORY_TYPE "HR"
            WITH DATA_TYPE "UINT"
            WITH SOURCE_TOPIC "plc/stats/error"
```

**Combined (Cyclic + On-Demand)**

Continuous monitoring with on-demand read and write events in the same connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FullFINSSetup WITH TYPE FINS
    ADD FINS_CONFIG
        WITH IP "192.168.1.100"
        WITH PORT 9600
        WITH PROTOCOL "TCP"
        WITH LOCAL_NODE 0
        WITH REMOTE_NODE 0
    
    ADD MAPPING ProcessData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "102"
            WITH MEMORY_TYPE "DM"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/pressure"
            WITH UNIT "bar"
    
    ADD EVENT ReadDM
        WITH SOURCE_TOPIC "fins/commands/read"
        WITH DESTINATION_TOPIC "fins/responses/read"
        WITH QUERY "{operation: READ, memory_type: DM, address: 200, data_type: REAL}"
    
    ADD EVENT WriteDM
        WITH SOURCE_TOPIC "fins/commands/write"
        WITH DESTINATION_TOPIC "fins/responses/write"
        WITH QUERY "{operation: WRITE, memory_type: DM, address: 300, data_type: REAL, value: 0}"
```

The MAPPING continuously reads temperature and pressure from DM. To trigger an on-demand read, publish any message to `fins/commands/read`. To write a value, publish to `fins/commands/write`.

***

## Memory Area Details

> **CIO - Core I/O**
>
> * Used for I/O mapping and internal relays
> * Words 0-99: Typically input/output modules
> * Words 100-999: Work bits and internal relays
> * Addresses are PLC model dependent

> **DM - Data Memory**
>
> * Main user data storage
> * Typically DM0-DM32767
> * Best for process data, setpoints, configuration
> * Retentive (battery-backed)

> **HR - Holding Area**
>
> * Always retentive data
> * Survives power cycles
> * Use for counters, totals, settings
> * Typically HR0-HR511

> **WR - Work Area**
>
> * General purpose work bits
> * Non-retentive (cleared on power cycle)
> * Fast access for temporary data

> **TIM/CNT - Timers and Counters**
>
> * TIM: Timer present values
> * CNT: Counter present values
> * Values are 16-bit unsigned
> * Timer values often in 0.1s units

***

## Troubleshooting

> **Connection Failed**
>
> * Verify IP address is correct
> * Check firewall allows port 9600
> * Ensure PLC Ethernet module is configured
> * Try both TCP and UDP protocols
> * Verify node addresses match PLC configuration

> **Node Address Errors**
>
> * LOCAL\_NODE should be unique on the network
> * REMOTE\_NODE is the target PLC's node number
> * Check PLC's FINS settings for correct node configuration
> * For direct connections, try 0 for both nodes

> **Memory Address Errors**
>
> * Verify address is within valid range for memory type
> * Check MEMORY\_TYPE matches where data is stored
> * For 32-bit types, ensure two consecutive words are available
> * BIT\_ADDRESS must be 0-15

> **Timeouts with node mismatch**
>
> * The broker only accepts a reply that matches the request's service ID and comes from the node it addressed.
> * Some PLCs and gateways swap the client and server node in the FINS/TCP handshake reply. Their replies are dropped, so the route times out. The broker logs a warning naming the mismatched nodes.
> * Check `LOCAL_NODE` and `REMOTE_NODE`, or update the gateway firmware.

> **Timeout Errors**
>
> * Increase TIMEOUT value
> * Check network connectivity
> * Verify PLC is in RUN mode
> * Reduce POLLING rate if reading many tags
> * Try TCP instead of UDP

> **Write Operations Fail**
>
> * Ensure WRITABLE is "true"
> * Verify memory area is writable (not AR)
> * Check PLC is not in monitor mode
> * Verify value is within data type range

***

## Next Steps

> **[Modbus TCP Client](./modbus-tcp-client)**
>
> Universal industrial protocol support.

> **[Industrial Overview](./overview)**
>
> Common patterns for all industrial connectors.


# Modbus Serial Client Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/modbus-serial-client

Connect to PLCs and industrial devices using Modbus RTU over RS-232/RS-485 serial connections

## Modbus Serial Client

> [!NOTE]
>
> This page documents the **client** connector (`MODBUS_SERIAL`) over serial RTU—the broker connects **to** a remote Modbus device on a COM port. For Modbus TCP client, see [Modbus TCP Client](./modbus-tcp-client).

The `MODBUS_SERIAL` connector enables communication with industrial devices using Modbus RTU protocol over serial connections (RS-232 or RS-485). It supports the same TAG-based configuration as Modbus TCP but adds serial-specific parameters for baud rate, parity, and data bits. `WITH CONNECTION_TYPE "SERIAL"` is optional: the type already means serial. An explicit `CONNECTION_TYPE` still wins.

> [!TIP]
>
> Modbus Serial (RTU) is commonly used for legacy equipment, long-distance communication, and multi-drop RS-485 networks where multiple devices share a single bus.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SerialDevice WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "COM1"
        WITH BAUD_RATE 9600
        WITH PARITY "NONE"
        WITH DATA_BITS 8
        WITH STOP_BITS "ONE"
        WITH SLAVE_ID 1
    ADD MAPPING SensorReadings
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "serial/temperature"
```

***

## Serial Configuration

### MODBUS\_CONFIG Parameters

**CONNECTION\_TYPE** `string`

Optional. A connector with `TYPE MODBUS_SERIAL` already implies `SERIAL`, so you can omit this. If you set it, that value is the one the connector uses.

**COM\_PORT** `string` *required*

Serial port name. Windows: `COM1`, `COM2`, etc. Linux: `/dev/ttyUSB0`, `/dev/ttyS0`, etc.

**BAUD\_RATE** `integer` *required*

Communication speed in bits per second. Common values: 9600, 19200, 38400, 57600, 115200.

**PARITY** `string`

Parity checking: `NONE`, `ODD`, `EVEN`, `MARK`, or `SPACE`. Default: NONE.

**DATA\_BITS** `integer`

Number of data bits per character: 7 or 8. Default: 8.

**STOP\_BITS** `string`

Number of stop bits: `ONE`, `TWO`, or `ONEPOINTFIVE`. Default: ONE.

**SLAVE\_ID** `integer` *required*

Modbus slave/unit ID (1-247). Each device on the bus must have a unique ID.

**READ\_TIMEOUT** `integer`

Read operation timeout in milliseconds. Default: 1000.

**WRITE\_TIMEOUT** `integer`

Write operation timeout in milliseconds. Default: 1000.

**RETRY\_COUNT** `integer`

Number of retry attempts on failure. Default: 3.

**RETRY\_DELAY** `integer`

Delay between retries in milliseconds. Default: 100.

***

## Common Serial Settings

Different devices use different serial settings. Here are common configurations:

**Standard (Most Common)**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MODBUS_CONFIG
    WITH CONNECTION_TYPE "SERIAL"
    WITH COM_PORT "COM1"
    WITH BAUD_RATE 9600
    WITH PARITY "NONE"
    WITH DATA_BITS 8
    WITH STOP_BITS "ONE"
    WITH SLAVE_ID 1
```

Settings: 9600 8N1 (9600 baud, 8 data bits, No parity, 1 stop bit)

**Even Parity**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MODBUS_CONFIG
    WITH CONNECTION_TYPE "SERIAL"
    WITH COM_PORT "COM1"
    WITH BAUD_RATE 9600
    WITH PARITY "EVEN"
    WITH DATA_BITS 8
    WITH STOP_BITS "ONE"
    WITH SLAVE_ID 1
```

Settings: 9600 8E1 (9600 baud, 8 data bits, Even parity, 1 stop bit. Common in older equipment.)

**High Speed**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MODBUS_CONFIG
    WITH CONNECTION_TYPE "SERIAL"
    WITH COM_PORT "/dev/ttyUSB0"
    WITH BAUD_RATE 115200
    WITH PARITY "NONE"
    WITH DATA_BITS 8
    WITH STOP_BITS "ONE"
    WITH SLAVE_ID 1
```

Settings: 115200 8N1 (115200 baud, 8 data bits, No parity, 1 stop bit. For modern devices.)

**Linux USB Adapter**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MODBUS_CONFIG
    WITH CONNECTION_TYPE "SERIAL"
    WITH COM_PORT "/dev/ttyUSB0"
    WITH BAUD_RATE 9600
    WITH PARITY "NONE"
    WITH DATA_BITS 8
    WITH STOP_BITS "ONE"
    WITH SLAVE_ID 1
```

> [!NOTE]
>
> On Linux, USB-to-serial adapters typically appear as `/dev/ttyUSB0`, `/dev/ttyUSB1`, etc.

***

## RS-485 Multi-Drop Networks

RS-485 allows multiple devices on a single bus. Each device must have a unique slave ID:

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
graph LR
    subgraph bus [RS-485 Bus]
        Master[Coreflux]
        Device1[Device 1<br/>ID: 1]
        Device2[Device 2<br/>ID: 2]
        Device3[Device 3<br/>ID: 3]
    end
    
    Master --- Device1
    Master --- Device2
    Master --- Device3
```

### Multi-Device Configuration

Create separate connectors or use different slave IDs:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TemperatureController WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "COM1"
        WITH BAUD_RATE 9600
        WITH SLAVE_ID 1
    ADD MAPPING TempController
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "modbus/device1/temperature"

DEFINE CONNECTOR FlowMeter WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "COM1"
        WITH BAUD_RATE 9600
        WITH SLAVE_ID 2
    ADD MAPPING FlowMeter
        WITH EVERY 1 SECOND
        ADD TAG FlowRate
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "modbus/device2/flow"
```

> [!WARNING]
>
> When sharing a serial port between multiple slave IDs, ensure polling intervals are set to avoid bus collisions. The connector handles sequencing automatically, but very fast polling across many devices may cause timeouts.

***

## TAG Configuration

The TAG configuration for Modbus Serial matches Modbus TCP, including string sizing. See the [Modbus TCP Client documentation](./modbus-tcp-client) for the full TAG parameter reference.

### String sizing

For `STRING` tags, `WITH LENGTH` sets the maximum string size in **bytes** (default **256**). `STRING_SIZE` is accepted as an alias. Each register holds two bytes, so the connector reads enough **consecutive registers** from the tag's starting `ADDRESS` to cover the configured size.

```lot wrap focus={16} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ModbusStrings WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "/dev/ttyUSB0"
        WITH BAUD_RATE 9600
        WITH PARITY "NONE"
        WITH DATA_BITS 8
        WITH STOP_BITS "ONE"
        WITH SLAVE_ID 1
    ADD MAPPING ProductData
        WITH EVERY 1 SECOND
        ADD TAG ProductName
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 32
            WITH SOURCE_TOPIC "factory/product/name"
```

For cross-protocol defaults and caps, see [String sizing by Connector](./overview#string-sizing-by-connector) on the industrial overview.

### TAG parameters

**LENGTH** `integer` (default: 256)

**STRING only.** Maximum string size in bytes. The connector allocates consecutive registers from the starting `ADDRESS` (2 bytes per register). Alias: `STRING_SIZE`.

### Quick Reference

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG SensorValue
    WITH ADDRESS "100"
    WITH ADDRESS_TYPE "HOLDING_REGISTER"
    WITH DATA_TYPE "FLOAT"
    WITH SOURCE_TOPIC "serial/sensor"
    WITH SCALING 0.1
    WITH OFFSET 0
    WITH UNIT "°C"
    WITH DEADBAND 0.5
    WITH PUBLISH_MODE "JSON"
    WITH WRITABLE "true"
    WITH DESTINATION_TOPIC "serial/sensor/set"
    WITH BYTE_ORDER "BIGENDIAN"
    WITH WORD_ORDER "BIGENDIAN"
```

***

## Event-Based Operations

For on-demand Modbus Serial operations (not polling), use the EVENT syntax. Publish a message to SOURCE\_TOPIC to trigger the operation; the connector executes it and publishes the result to DESTINATION\_TOPIC.

Modbus Serial supports the same EVENT operations as Modbus TCP. See the [Modbus TCP Client Event-Based Operations](./modbus-tcp-client#event-based-operations) for the full supported operations table and query parameter details.

### Read Example

Read 10 holding registers on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadRegisters
    WITH SOURCE_TOPIC "serial/commands/read"
    WITH DESTINATION_TOPIC "serial/responses/read"
    WITH QUERY "{operation: READ_HOLDING_REGISTERS, start_address: 0, count: 10}"
```

### Write Example

Write a single register on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT WriteRegister
    WITH SOURCE_TOPIC "serial/commands/write"
    WITH DESTINATION_TOPIC "serial/responses/write"
    WITH QUERY "{operation: WRITE_SINGLE_REGISTER, address: 100, value: 500}"
```

***

## Complete Examples

**Single Device**

Basic connection to a single Modbus RTU device:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EnergyMeter WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "COM3"
        WITH BAUD_RATE 9600
        WITH PARITY "EVEN"
        WITH DATA_BITS 8
        WITH STOP_BITS "ONE"
        WITH SLAVE_ID 1
        WITH READ_TIMEOUT 1000
        WITH RETRY_COUNT 3
    ADD MAPPING Readings
        WITH EVERY 1 SECOND
        ADD TAG Voltage
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "meter/voltage"
            WITH UNIT "V"
        ADD TAG Current
            WITH ADDRESS "2"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "meter/current"
            WITH UNIT "A"
        ADD TAG Power
            WITH ADDRESS "4"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "meter/power"
            WITH UNIT "kW"
```

**Temperature Controller**

Read process value and write setpoint:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TempController WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "/dev/ttyUSB0"
        WITH BAUD_RATE 9600
        WITH PARITY "NONE"
        WITH DATA_BITS 8
        WITH STOP_BITS "ONE"
        WITH SLAVE_ID 1
    ADD MAPPING Control
        WITH EVERY 500 MILLISECONDS
        ADD TAG ProcessValue
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "INT16"
            WITH SOURCE_TOPIC "tempctrl/pv"
            WITH SCALING 0.1
            WITH UNIT "°C"
        ADD TAG Setpoint
            WITH ADDRESS "1"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "INT16"
            WITH SOURCE_TOPIC "tempctrl/sp"
            WITH SCALING 0.1
            WITH UNIT "°C"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "tempctrl/sp/set"
        ADD TAG Output
            WITH ADDRESS "2"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "INT16"
            WITH SOURCE_TOPIC "tempctrl/output"
            WITH SCALING 0.1
            WITH UNIT "%"
```

**VFD (Variable Frequency Drive)**

Control a motor drive:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR VFDControl WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "COM2"
        WITH BAUD_RATE 19200
        WITH PARITY "EVEN"
        WITH DATA_BITS 8
        WITH STOP_BITS "ONE"
        WITH SLAVE_ID 1
    ADD MAPPING DriveStatus
        WITH EVERY 200 MILLISECONDS
        ADD TAG ActualSpeed
            WITH ADDRESS "8451"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "vfd/speed/actual"
            WITH SCALING 0.1
            WITH UNIT "Hz"
        ADD TAG MotorCurrent
            WITH ADDRESS "8448"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "vfd/current"
            WITH SCALING 0.01
            WITH UNIT "A"
        ADD TAG SpeedReference
            WITH ADDRESS "8502"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "vfd/speed/reference"
            WITH SCALING 0.1
            WITH UNIT "Hz"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "vfd/speed/set"
        ADD TAG ControlWord
            WITH ADDRESS "8501"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "vfd/control"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "vfd/control/set"
```

**Combined (Cyclic + On-Demand)**

Continuous monitoring with on-demand read and write events in the same connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FullSerialSetup WITH TYPE MODBUS_SERIAL
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "SERIAL"
        WITH COM_PORT "COM3"
        WITH BAUD_RATE 9600
        WITH PARITY "EVEN"
        WITH DATA_BITS 8
        WITH STOP_BITS "ONE"
        WITH SLAVE_ID 1
    
    ADD MAPPING ProcessReadings
        WITH EVERY 1 SECOND
        ADD TAG Voltage
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "meter/voltage"
            WITH UNIT "V"
        ADD TAG Current
            WITH ADDRESS "2"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "meter/current"
            WITH UNIT "A"
    
    ADD EVENT ReadRegisters
        WITH SOURCE_TOPIC "serial/commands/read"
        WITH DESTINATION_TOPIC "serial/responses/read"
        WITH QUERY "{operation: READ_HOLDING_REGISTERS, start_address: 0, count: 10}"
    
    ADD EVENT WriteRegister
        WITH SOURCE_TOPIC "serial/commands/write"
        WITH DESTINATION_TOPIC "serial/responses/write"
        WITH QUERY "{operation: WRITE_SINGLE_REGISTER, address: 100, value: 0}"
```

The MAPPING continuously reads voltage and current. To trigger an on-demand register read, publish any message to `serial/commands/read`. To write, publish to `serial/commands/write`.

***

## Troubleshooting

> **No Communication**
>
> * Verify COM port is correct and not in use by another application
> * Check physical wiring (TX/RX, A/B for RS-485)
> * Ensure baud rate matches device settings
> * Verify slave ID is correct
> * Check device power and status indicators

> **CRC Errors**
>
> * CRC errors indicate data corruption
> * Check cable quality and length
> * For RS-485, ensure proper termination resistors (120Ω at each end)
> * Reduce baud rate for long cable runs
> * Check for electrical interference

> **Timeout Errors**
>
> * Increase `READ_TIMEOUT` value
> * Verify serial settings match device exactly
> * Check for bus conflicts (multiple masters)
> * For RS-485, ensure proper biasing

> **Incorrect Values**
>
> * Verify register addresses in device documentation
> * Check `BYTE_ORDER` and `WORD_ORDER` settings
> * Confirm `DATA_TYPE` matches register size
> * Some devices use 1-based addressing (subtract 1 from documented address)

> **Port Not Found**
>
> * Windows: Check Device Manager for correct COM port number
> * Linux: Check `/dev/tty*` with `ls -l /dev/tty*`
> * Ensure USB-to-serial driver is installed
> * Verify user has permissions to access serial port

***

## RS-485 Wiring Tips

> [!NOTE]
>
> Proper wiring is critical for reliable RS-485 communication.

| Wire | Function | Description |
| - | - | - |
| A (D-) | Data - | Negative data line |
| B (D+) | Data + | Positive data line |
| GND | Ground | Signal ground reference |

**Best Practices:**

* Use twisted pair cable for A and B lines
* Add 120Ω termination resistors at both ends of the bus
* Keep cable length under 1200m (4000ft)
* Use bias resistors if experiencing idle-line issues
* Ensure all grounds are connected

***

## Next Steps

> **[Modbus TCP Client](./modbus-tcp-client)**
>
> Connect to Modbus devices over Ethernet.

> **[Siemens S7](./siemens-s7)**
>
> Connect directly to Siemens PLCs.


# Modbus TCP Client Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/modbus-tcp-client

Connect to PLCs and industrial devices using Modbus TCP protocol with TAG-based polling and automatic batch optimization

## Modbus TCP Client

> [!NOTE]
>
> This page documents the **client** connector (`MODBUS_TCP`)—the broker connects **to** a remote Modbus device and polls registers over MQTT. To expose MQTT topics **to** Modbus masters instead (SCADA, HMIs connect to the broker), see [Modbus TCP Server](./modbus-tcp-server).

The `MODBUS_TCP` connector enables communication with PLCs, RTUs, and industrial devices using the Modbus TCP/IP protocol. It supports reading and writing registers and coils with configurable polling intervals and automatic batch optimization.

> [!TIP]
>
> Modbus TCP is one of the most widely supported industrial protocols. If your device supports Modbus, this connector provides a reliable way to integrate it with MQTT.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ModbusDevice WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT 502
        WITH SLAVE_ID 1
    ADD MAPPING SensorReadings
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "modbus/temperature"
```

***

## Connection Configuration

### MODBUS\_CONFIG Parameters

**HOST** `string` *required*

Modbus TCP server hostname or IP address.

**PORT** `integer`

Modbus TCP port. Default: 502.

**SLAVE\_ID** `integer`

Modbus slave/unit ID (1-247). Default: 1.

**CONNECTION\_TIMEOUT** `integer`

Connection timeout in milliseconds. Default: 5000.

**READ\_TIMEOUT** `integer`

Read operation timeout in milliseconds. Default: 1000.

**WRITE\_TIMEOUT** `integer`

Write operation timeout in milliseconds. Default: 1000.

**RETRY\_COUNT** `integer`

Number of retry attempts on failure. Default: 3.

**RETRY\_DELAY** `integer`

Delay between retries in milliseconds. Default: 100.

**ONE\_BASED\_ADDRESSES** `boolean` (default: false)

Treat plain numeric tag addresses as one-based (address `1` = PDU register 0). Modicon-style addresses (`400001+`, `300001+`, `100001+`) are always decoded regardless of this flag. See [Modbus addressing](#modbus-addressing).

### One request at a time

Each connection carries one request at a time. Mappings, events, and timers on that connector share the connection, so a poll of many tags runs one read after another.

A device that is merely slow fails that read and keeps the connection. Raise `READ_TIMEOUT` and set the poll interval long enough for those reads to finish. A connection that stops answering altogether is closed and reopened, so a stale reply never lands on the next request. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).

### Connection Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MODBUS_CONFIG
    WITH HOST "192.168.1.100"
    WITH PORT 502
    WITH SLAVE_ID 1
    WITH CONNECTION_TIMEOUT 5000
    WITH READ_TIMEOUT 1000
    WITH WRITE_TIMEOUT 1000
    WITH RETRY_COUNT 3
    WITH RETRY_DELAY 100
```

***

## Address Types

Modbus defines four address spaces:

| Address Type | Description | Function Codes | Typical Use |
| - | - | - | - |
| `HOLDING_REGISTER` | Read/Write 16-bit registers | FC03, FC06, FC16 | Setpoints, configuration |
| `INPUT_REGISTER` | Read-only 16-bit registers | FC04 | Sensor values, measurements |
| `COIL` | Read/Write single bits | FC01, FC05, FC15 | Digital outputs, controls |
| `DISCRETE_INPUT` | Read-only single bits | FC02 | Digital inputs, status |

> [!NOTE]
>
> Most Modbus devices use Holding Registers for configuration and Input Registers for measured values. Check your device documentation for the correct address type.

***

## Modbus Addressing

Modbus addressing varies by vendor. Coreflux supports three styles—choose the one that matches your device documentation.

### Style 1 — Zero-based PDU offsets (default)

The Modbus protocol uses zero-based addresses in the PDU. This is the default (`ONE_BASED_ADDRESSES = false`).

| Device manual label | Tag `ADDRESS` |
| - | - |
| Register 1 | `"0"` |
| Register 100 | `"99"` |

Use this when documentation labels the first register as `0`, or when targeting integration tests that follow PDU numbering.

### Style 2 — One-based plain addresses

Most device manuals label the first holding register as **1**, not 0. Set `WITH ONE_BASED_ADDRESSES true` on `MODBUS_CONFIG` to use those labels directly in tag addresses.

| Device manual label | Tag `ADDRESS` |
| - | - |
| Register 1 | `"1"` |
| Register 100 | `"100"` |

```lot wrap focus={5-11} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ModbusDevice WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT 502
        WITH SLAVE_ID 1
        WITH ONE_BASED_ADDRESSES true
    ADD MAPPING Sensors
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "1"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "sensors/temperature"
```

### Style 3 — Modicon notation

Traditional Modicon prefix notation is always accepted. The prefix determines the address type automatically:

| Modicon range | Address type | Example |
| - | - | - |
| 400001–465536 | Holding register | `400001` → PDU 0 |
| 300001–365536 | Input register | `300001` → PDU 0 |
| 100001–165536 | Discrete input | `100001` → PDU 0 |

```lot wrap focus={4-8} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ModbusDevice WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH SLAVE_ID 1
    ADD MAPPING Setpoints
        WITH EVERY 1 SECOND
        ADD TAG Setpoint
            WITH ADDRESS "400100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "INT16"
            WITH SOURCE_TOPIC "plc/setpoint"
```

> [!NOTE]
>
> Modicon-style addresses are decoded the same way regardless of `ONE_BASED_ADDRESSES`. The flag only affects plain numeric addresses (those without a Modicon prefix).

### Conversion reference

| Device manual label | `ONE_BASED_ADDRESSES false` | `ONE_BASED_ADDRESSES true` | Modicon notation |
| - | - | - | - |
| Register 1 | `"0"` | `"1"` | `"400001"` |
| Register 100 | `"99"` | `"100"` | `"400100"` |
| Register 1000 | `"999"` | `"1000"` | `"401000"` |

Multi-word types (`FLOAT`, `INT32`, and so on) occupy consecutive registers from the resolved starting address.

***

## Data Types

**DATA\_TYPE** `string` *required*

The data type determines how raw register values are interpreted:

| Data Type | Size | Description |
| - | - | - |
| `BOOL` | 1 bit | Boolean value (for coils/discrete inputs) |
| `BIT` | 1 bit | Alias for BOOL |
| `INT8` | 8 bits | Signed 8-bit integer |
| `UINT8` | 8 bits | Unsigned 8-bit integer |
| `INT16` | 16 bits | Signed 16-bit integer (1 register) |
| `UINT16` | 16 bits | Unsigned 16-bit integer (1 register) |
| `INT32` | 32 bits | Signed 32-bit integer (2 registers) |
| `UINT32` | 32 bits | Unsigned 32-bit integer (2 registers) |
| `INT64` | 64 bits | Signed 64-bit integer (4 registers) |
| `UINT64` | 64 bits | Unsigned 64-bit integer (4 registers) |
| `FLOAT` | 32 bits | 32-bit floating point (2 registers) |
| `DOUBLE` | 64 bits | 64-bit floating point (4 registers) |
| `STRING` | Variable | ASCII string across consecutive registers; sized with `LENGTH` (default 256 bytes) |

### String sizing

For `STRING` tags, `WITH LENGTH` sets the maximum string size in **bytes** (default **256**). `STRING_SIZE` is accepted as an alias for the same field. Each Modbus register holds two bytes, so the connector reads enough **consecutive registers** starting at the tag's `ADDRESS` to cover the configured size.

```lot wrap focus={12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ModbusStrings WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT 502
        WITH SLAVE_ID 1
    ADD MAPPING ProductData
        WITH EVERY 1 SECOND
        ADD TAG ProductName
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 32
            WITH SOURCE_TOPIC "factory/product/name"
```

For cross-protocol defaults and caps, see [String sizing by Connector](./overview#string-sizing-by-connector) on the industrial overview.

***

## TAG Configuration

### Complete TAG Parameters

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG TemperatureSensor
    WITH ADDRESS "100"
    WITH ADDRESS_TYPE "HOLDING_REGISTER"
    WITH DATA_TYPE "FLOAT"
    WITH SOURCE_TOPIC "modbus/sensors/temperature"
    WITH SCALING 0.1
    WITH OFFSET 0
    WITH UNIT "°C"
    WITH DECIMAL_PLACES 2
    WITH MIN_VALUE -40
    WITH MAX_VALUE 150
    WITH DEADBAND 0.5
    WITH PUBLISH_MODE "JSON"
    WITH WRITABLE "true"
    WITH DESTINATION_TOPIC "modbus/sensors/temperature/set"
    WITH BYTE_ORDER "BIGENDIAN"
    WITH WORD_ORDER "BIGENDIAN"
    WITH DESCRIPTION "Main process temperature sensor"
```

### TAG Parameters Reference

> **Address Configuration**
>
> **ADDRESS** `string` *required*
>
> Register or coil address. Plain numeric (0–65535 zero-based by default, or 1–65536 when `ONE_BASED_ADDRESSES true`), or Modicon notation (`400001+`, `300001+`, `100001+`). See [Modbus addressing](#modbus-addressing).
>
> **ADDRESS\_TYPE** `string` *required*
>
> Type of Modbus address: `HOLDING_REGISTER`, `INPUT_REGISTER`, `COIL`, or `DISCRETE_INPUT`.
>
> **LENGTH** `integer` (default: 256)
>
> **STRING only.** Maximum string size in bytes. The connector allocates consecutive registers from the starting `ADDRESS` (2 bytes per register). Alias: `STRING_SIZE`.

> **Value Transformation**
>
> **SCALING** `double`
>
> Multiplier applied to raw value. Default: 1.0. Example: Raw value 245 with SCALING 0.1 becomes 24.5.
>
> **OFFSET** `double`
>
> Value added after scaling. Default: 0.0. Formula: `result = (raw * scaling) + offset`.
>
> **DECIMAL\_PLACES** `integer`
>
> Number of decimal places in published value. Default: 2.

> **Filtering**
>
> **MIN\_VALUE** `double`
>
> Minimum allowed value. Values below this threshold are not published.
>
> **MAX\_VALUE** `double`
>
> Maximum allowed value. Values above this threshold are not published.
>
> **DEADBAND** `double`
>
> Minimum change required to publish a new value. Default: 0.0.

> **Publishing**
>
> **SOURCE\_TOPIC** `string`
>
> Topic where PLC values are published. Subscribe here to receive sensor data.
>
> **PUBLISH\_MODE** `string`
>
> Output format: `VALUE_ONLY` or `JSON`. Default: VALUE\_ONLY.
>
> **UNIT** `string`
>
> Engineering unit for documentation (e.g., °C, bar, RPM).
>
> **DESCRIPTION** `string`
>
> Human-readable description of the TAG.

> **Write Configuration**
>
> **WRITABLE** `boolean`
>
> Allow writing to this register/coil. Default: false.
>
> **DESTINATION\_TOPIC** `string`
>
> Topic to send write commands. Publish a value here to write it to the PLC.

> **Byte Ordering**
>
> **BYTE\_ORDER** `string`
>
> Byte order for multi-byte values: `BIGENDIAN` or `LITTLEENDIAN`. Default: BIGENDIAN.
>
> **WORD\_ORDER** `string`
>
> Word order for 32/64-bit values: `BIGENDIAN` or `LITTLEENDIAN`. Default: BIGENDIAN.
>
> > [!WARNING]
> >
> > Different manufacturers use different byte/word ordering. If values appear incorrect, try changing BYTE\_ORDER or WORD\_ORDER.

***

## Event-Based Operations

For on-demand Modbus operations (not polling), use the EVENT syntax. Publish a message to SOURCE\_TOPIC to trigger the operation; the connector executes it and publishes the result to DESTINATION\_TOPIC.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadOnDemand
    WITH SOURCE_TOPIC "modbus/commands/read"
    WITH DESTINATION_TOPIC "modbus/responses/read"
    WITH QUERY "{operation: READ_HOLDING_REGISTERS, start_address: 0, count: 10}"
```

### Query Syntax

The `WITH QUERY` value uses LoT object syntax: unquoted keys, unquoted identifiers, and numeric values. The entire query is wrapped in double quotes.

| Element | Format | Example |
| - | - | - |
| Keys | Unquoted | `operation`, `start_address`, `count` |
| Operation values | Unquoted identifiers | `READ_HOLDING_REGISTERS`, `READ_COILS` |
| Numeric values | Unquoted | `0`, `10`, `100` |
| String values | Unquoted (addresses) | `address: 100` |

### Supported Operations

| Operation | Description |
| - | - |
| `READ_HOLDING_REGISTERS` | Read holding registers (FC03) |
| `READ_INPUT_REGISTERS` | Read input registers (FC04) |
| `READ_COILS` | Read coils (FC01) |
| `READ_DISCRETE_INPUTS` | Read discrete inputs (FC02) |
| `WRITE_SINGLE_REGISTER` | Write single holding register (FC06) |
| `WRITE_MULTIPLE_REGISTERS` | Write multiple holding registers (FC16) |
| `WRITE_SINGLE_COIL` | Write single coil (FC05) |
| `WRITE_MULTIPLE_COILS` | Write multiple coils (FC15) |

### Query Parameters by Operation

| Operation | Parameters | Example |
| - | - | - |
| `READ_HOLDING_REGISTERS` | `start_address`, `count` | `{operation: READ_HOLDING_REGISTERS, start_address: 0, count: 10}` |
| `READ_INPUT_REGISTERS` | `start_address`, `count` | `{operation: READ_INPUT_REGISTERS, start_address: 0, count: 5}` |
| `READ_COILS` | `start_address`, `count` | `{operation: READ_COILS, start_address: 0, count: 8}` |
| `READ_DISCRETE_INPUTS` | `start_address`, `count` | `{operation: READ_DISCRETE_INPUTS, start_address: 0, count: 8}` |
| `WRITE_SINGLE_REGISTER` | `address`, `value` | `{operation: WRITE_SINGLE_REGISTER, address: 100, value: 42}` |
| `WRITE_MULTIPLE_REGISTERS` | `start_address`, `values` | `{operation: WRITE_MULTIPLE_REGISTERS, start_address: 0, values: [100, 200]}` |
| `WRITE_SINGLE_COIL` | `address`, `value` | `{operation: WRITE_SINGLE_COIL, address: 0, value: true}` |
| `WRITE_MULTIPLE_COILS` | `start_address`, `values` | `{operation: WRITE_MULTIPLE_COILS, start_address: 0, values: [true, false, true]}` |

To write a value on demand, publish a message to SOURCE\_TOPIC. The connector executes the write and publishes the result to DESTINATION\_TOPIC:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT WriteSetpoint
    WITH SOURCE_TOPIC "modbus/commands/write"
    WITH DESTINATION_TOPIC "modbus/responses/write"
    WITH QUERY "{operation: WRITE_SINGLE_REGISTER, address: 100, value: 42}"
```

***

## Complete Examples

**Basic Sensor Reading**

Read temperature and pressure from a Modbus device:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProcessSensors WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT 502
        WITH SLAVE_ID 1
    ADD MAPPING Sensors
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "process/temperature"
            WITH SCALING 0.1
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "102"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "process/pressure"
            WITH UNIT "bar"
```

**Multiple Polling Rates**

Group TAGs by update frequency:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PLCConnection WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.50"
        WITH PORT 502
        WITH SLAVE_ID 1
    
    ADD MAPPING FastLoop
        WITH EVERY 100 MILLISECONDS
        ADD TAG MotorSpeed
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "plc/motor/speed"
        ADD TAG MotorCurrent
            WITH ADDRESS "201"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/motor/current"
    
    ADD MAPPING SlowLoop
        WITH EVERY 5 SECONDS
        ADD TAG TotalRuntime
            WITH ADDRESS "300"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT32"
            WITH SOURCE_TOPIC "plc/stats/runtime"
        ADD TAG FaultCode
            WITH ADDRESS "400"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "plc/status/fault"
```

**Bidirectional Control**

Read values and write setpoints:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ControlSystem WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT 502
        WITH SLAVE_ID 1
    ADD MAPPING ControlLoop
        WITH EVERY 500 MILLISECONDS
        ADD TAG ProcessValue
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "control/pv"
            WITH PUBLISH_MODE "JSON"
        ADD TAG Setpoint
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "control/sp"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/sp/set"
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
        ADD TAG OutputValue
            WITH ADDRESS "300"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "control/output"
```

**Coils and Digital I/O**

Read digital inputs and control outputs:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DigitalIO WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.75"
        WITH PORT 502
        WITH SLAVE_ID 1
    ADD MAPPING DigitalInputs
        WITH EVERY 100 MILLISECONDS
        ADD TAG StartButton
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "DISCRETE_INPUT"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "io/inputs/start"
        ADD TAG StopButton
            WITH ADDRESS "1"
            WITH ADDRESS_TYPE "DISCRETE_INPUT"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "io/inputs/stop"
        ADD TAG RunningLight
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "COIL"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "io/outputs/running"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "io/outputs/running/set"
```

**Combined (Cyclic + On-Demand)**

Continuous monitoring with on-demand read and write events in the same connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FullModbusSetup WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT 502
        WITH SLAVE_ID 1
    
    ADD MAPPING ProcessSensors
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "process/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "102"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "process/pressure"
            WITH UNIT "bar"
    
    ADD EVENT ReadRegisters
        WITH SOURCE_TOPIC "modbus/commands/read"
        WITH DESTINATION_TOPIC "modbus/responses/read"
        WITH QUERY "{operation: READ_HOLDING_REGISTERS, start_address: 0, count: 10}"
    
    ADD EVENT WriteSetpoint
        WITH SOURCE_TOPIC "modbus/commands/write"
        WITH DESTINATION_TOPIC "modbus/responses/write"
        WITH QUERY "{operation: WRITE_SINGLE_REGISTER, address: 200, value: 0}"
```

To trigger the on-demand read, publish any message to `modbus/commands/read`. The connector reads registers 0-9 and publishes the result to `modbus/responses/read`. To write, publish to `modbus/commands/write`.

***

## Troubleshooting

> **Connection Timeout**
>
> * Verify IP address and port are correct
> * Check firewall settings (port 502 must be open)
> * Ensure device is powered on and connected to network
> * Try increasing `CONNECTION_TIMEOUT`

> **Mismatched responses**
>
> * Tags go BAD with "Response was not of expected transaction ID" or "Unexpected byte count" when replies get mixed on one connection. Upgrade to a newer broker.
> * Polling many tags is now serialized. Raise `READ_TIMEOUT` and the poll interval so each read can finish.

> **Incorrect Values**
>
> * Verify `ADDRESS` matches device documentation—try `WITH ONE_BASED_ADDRESSES true` if the manual labels registers starting at 1
> * Use Modicon notation (`400100`) when the datasheet shows prefixed addresses
> * Check `BYTE_ORDER` and `WORD_ORDER` settings
> * Confirm `DATA_TYPE` matches register size
> * Verify `SCALING` and `OFFSET` calculations

> **Write Operations Fail**
>
> * Ensure `WRITABLE` is set to "true"
> * Verify `ADDRESS_TYPE` is `HOLDING_REGISTER` or `COIL`
> * Check device permissions for write operations
> * Verify value is within `MIN_VALUE` and `MAX_VALUE`

> **Slave ID Errors**
>
> * Confirm correct `SLAVE_ID` (usually 1 for TCP devices)
> * Some gateways use different slave IDs for different devices
> * Check device documentation for correct unit ID

***

## Next Steps

> **[Modbus Serial Client](./modbus-serial-client)**
>
> Connect to RS-232/RS-485 Modbus RTU devices.

> **[Modbus TCP Server](./modbus-tcp-server)**
>
> Expose MQTT topics as Modbus registers for SCADA and HMIs.


# Modbus TCP Server Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/modbus-tcp-server

Expose MQTT topics as Modbus TCP registers and coils so SCADA, HMIs, and Modbus masters connect to your Coreflux broker

## Modbus TCP Server

> [!NOTE]
>
> This page documents the **server** connector (`MODBUS_SERVER`)—the broker **hosts** a Modbus TCP server and exposes MQTT topics as register and coil addresses. External masters connect to the broker over TCP. To connect the broker **to** a remote Modbus device instead, see [Modbus TCP Client](./modbus-tcp-client).

The `MODBUS_SERVER` connector makes your broker act as a **Modbus TCP server (slave)**. External masters—SCADA, HMIs, historians, PLCs—connect **to the broker** and read or write a declared register/coil address space that bridges bidirectionally to MQTT topics.

Use `MODBUS_TCP` when you need to **poll a device**. Use `MODBUS_SERVER` when OT systems need to **read and write** values that live on your MQTT bus—no separate gateway required.

> [!TIP]
>
> **Like a shop counter with a price list.** MQTT updates what's on the shelf (register values), and customers (Modbus masters) read the tags—or, for writable addresses, change items that publish back to MQTT.

## When to Use This Connector

* **SCADA / HMI integration** — Let plant-floor tools poll broker data over standard Modbus without custom drivers.
* **OT/IT bridge** — Expose IoT sensor streams to masters that only speak Modbus.
* **Bidirectional control** — Writable tags let masters adjust setpoints; the broker publishes the new value to MQTT on a cadence you choose.
* **Client-only field devices** — Integrate master-only equipment into MQTT with no middleware between the broker and the bus.

***

The sections below cover data flow, configuration, persistence, and production patterns.

## Quick Start

**Expose sensor values**

Map an MQTT topic to a holding register masters can poll:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TempServer WITH TYPE MODBUS_SERVER
    ADD MAPPING Sensors
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plant/line1/temperature"
```

Publish `23.5` to `plant/line1/temperature` → registers 100–101 hold the FLOAT; a master reading them gets `23.5`.

**Writable setpoint**

Allow a master to write a register; the broker publishes the value to MQTT within one `WITH EVERY` interval:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SetpointServer WITH TYPE MODBUS_SERVER
    ADD MAPPING Control
        WITH EVERY 500 MILLISECONDS
        WITH SOURCE_TOPIC "plant/line1"
        ADD TAG Setpoint
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "plant/line1/setpoint/written"
```

MQTT publishes to `plant/line1/Setpoint` update registers 200–201. A master write surfaces on `plant/line1/setpoint/written` within 500 ms.

**Full plant server**

Listen on port 502 as unit 1 with multiple tags and connection settings:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantModbusServer WITH TYPE MODBUS_SERVER
    ADD MODBUS_SERVER_CONFIG
        WITH HOST "0.0.0.0"
        WITH PORT 502
        WITH UNIT_ID 1
        WITH MAX_CONNECTIONS 64
    ADD MAPPING ServerTags
        WITH EVERY 500 MILLISECONDS
        WITH SOURCE_TOPIC "plant/modbus"
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
        ADD TAG Setpoint
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "plant/modbus/setpoint/set"
        ADD TAG Running
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "COIL"
            WITH DATA_TYPE "BOOL"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "plant/modbus/running/set"
```

Masters read `Temperature`; `Setpoint` and `Running` are bidirectional—MQTT drives them and master writes publish to their `DESTINATION_TOPIC` within 500 ms.

**Crash-resilient setpoints**

Persist master-written setpoints across broker restarts:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ResilientServer WITH TYPE MODBUS_SERVER
    ADD MODBUS_SERVER_CONFIG
        WITH PORT 502
        WITH UNIT_ID 1
        WITH PERSISTENCE true
    ADD MAPPING Control
        WITH EVERY 500 MILLISECONDS
        WITH SOURCE_TOPIC "plant/line1"
        ADD TAG Setpoint
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "plant/line1/setpoint/written"
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
```

After a restart, a master reading `Setpoint` (200–201) gets the last value it wrote. `Temperature` (100–101) refreshes from the live MQTT source, not the snapshot.

***

## How Data Flows

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
graph LR
    subgraph mqtt [MQTT]
        Topics[Topics]
    end

    subgraph broker [Coreflux Broker]
        Connector[MODBUS_SERVER Connector]
        Registers[Register / Coil Space]
    end

    subgraph ot [OT Masters]
        Master[SCADA / HMI / PLC]
    end

    Topics -->|publish sets value| Connector
    Connector --> Registers
    Registers -->|read / write| Master
    Master -->|write writable tag| Connector
    Connector -->|publish on EVERY cadence| Topics
```

Sync is **hybrid**—`WITH EVERY` controls outbound latency:

| Direction | Behavior |
| - | - |
| **MQTT → register (inbound)** | A publish on a tag's `SOURCE_TOPIC` updates the backing register or coil immediately. Works for every address type, including read-only `INPUT_REGISTER` and `DISCRETE_INPUT`. Retained MQTT values are seeded at startup. |
| **register → MQTT (outbound)** | When a master writes a `WRITABLE` `HOLDING_REGISTER` or `COIL`, the broker detects the change on the mapping's `WITH EVERY` cadence and publishes the decoded value to the tag's `DESTINATION_TOPIC` (rounded per `DECIMAL_PLACES`, retained). A master write surfaces on MQTT within one cadence interval. |

A master write never loops back into the register from MQTT, and an MQTT-driven change is never re-published to `DESTINATION_TOPIC` (direction guard).

On server connectors, connector status **Connected** means the endpoint is **listening**—not that a remote session is established.

***

## Server Configuration

All transport settings live in the `MODBUS_SERVER_CONFIG` block. A valid connector needs only `WITH TYPE MODBUS_SERVER` plus a mapping with one tag—it listens on `0.0.0.0:502` as unit 1 by default.

```lot wrap focus={2-6} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantModbusServer WITH TYPE MODBUS_SERVER
    ADD MODBUS_SERVER_CONFIG
        WITH HOST "0.0.0.0"
        WITH PORT 502
        WITH UNIT_ID 1
        WITH MAX_CONNECTIONS 64
```

### Connection parameters

**HOST** `string` (default: 0.0.0.0)

Bind interface to listen on (`0.0.0.0` = all interfaces). `IP` is accepted as an alias.

**PORT** `integer` (default: 502)

TCP listen port. Each server connector claims its port exclusively—a second connector on the same port is refused.

**MAX\_CONNECTIONS** `integer` (default: 64)

Best-effort soft cap on concurrent master connections. See [Connection-limit behavior](#connection-limit-behavior).

**UNIT\_ID** `integer` (default: 1)

Modbus unit ID the broker answers as (1–247). `SLAVE_ID` is accepted as an alias.

**PERSISTENCE** `boolean` (default: false)

Persist served values across broker restarts. See [Data persistence & recovery](#data-persistence--recovery).

**ONE\_BASED\_ADDRESSES** `boolean` (default: false)

Treat plain numeric tag addresses as one-based (address `1` = PDU register 0). Modicon-style addresses (`400001+`, `300001+`, `100001+`) are always decoded regardless of this flag. See [Address notation](#address-notation).

> [!NOTE]
>
> Modbus has no native authentication—there is no credential configuration. Bind to a specific interface and restrict access at the network layer; MQTT-side access is governed by HUB topic permissions. Use `GET ENV` / `GET SECRET` for environment-derived values (for example `WITH PORT GET ENV "MODBUS_PORT"`).

***

## Tag and Mapping Configuration

Each exposed register or coil is declared as an `ADD TAG`. Only declared addresses are served—reads or writes to undeclared addresses return a Modbus **Illegal Data Address** exception.

```lot wrap focus={7-20} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantModbusServer WITH TYPE MODBUS_SERVER
    ADD MODBUS_SERVER_CONFIG
        WITH HOST "0.0.0.0"
        WITH PORT 502
        WITH UNIT_ID 1
        WITH MAX_CONNECTIONS 64
    ADD MAPPING ServerTags
        WITH EVERY 500 MILLISECONDS
        WITH SOURCE_TOPIC "modbus/server"
        ADD TAG Setpoint
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "modbus/server/setpoint"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "modbus/server/setpoint/set"
            WITH BYTE_ORDER "BIGENDIAN"
            WITH WORD_ORDER "BIGENDIAN"
            WITH DECIMAL_PLACES 2
            WITH DESCRIPTION "Operator setpoint"
        ADD TAG ProductCode
            WITH ADDRESS "300"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 40
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "modbus/server/product/code"
```

### Server vs. client semantics

| Setting | Client (`MODBUS_TCP`) | Server (`MODBUS_SERVER`) |
| - | - | - |
| Role | Master—dials out to a device | Slave—listens for masters |
| `HOST` / `IP` | Device IP to dial | **Bind** interface to listen on |
| `SOURCE_TOPIC` | Register value → MQTT (read) | MQTT → register (write into address space) |
| `DESTINATION_TOPIC` | MQTT → device write | Register → MQTT when a master writes |
| `EVERY` | Poll interval | Outbound sync cadence (master write → MQTT) |
| Transport | TCP / Serial (RTU) | TCP |

### Modbus address banks

| `ADDRESS_TYPE` | Bank | Element | Master access | Function codes |
| - | - | - | - | - |
| `HOLDING_REGISTER` | Holding registers | 16-bit word | read / write | 3, 6, 16 |
| `INPUT_REGISTER` | Input registers | 16-bit word | read-only | 4 |
| `COIL` | Coils | 1 bit | read / write | 1, 5, 15 |
| `DISCRETE_INPUT` | Discrete inputs | 1 bit | read-only | 2 |

### Address notation

Tag `ADDRESS` values are converted to the **PDU offset** the broker exposes on the wire. External Modbus masters always use zero-based PDU addresses in their read/write requests—the `ONE_BASED_ADDRESSES` flag only affects how you label tags in LoT, not how masters address the server.

Three styles are supported (same rules as the [Modbus TCP Client](./modbus-tcp-client#modbus-addressing) connector):

| Style | Config | Tag address for PDU 0 | Tag address for PDU 99 |
| - | - | - | - |
| Zero-based plain (default) | `ONE_BASED_ADDRESSES false` | `"0"` | `"99"` |
| One-based plain | `ONE_BASED_ADDRESSES true` | `"1"` | `"100"` |
| Modicon holding register | either | `"400001"` | `"400100"` |

```lot wrap focus={2-12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantModbusServer WITH TYPE MODBUS_SERVER
    ADD MODBUS_SERVER_CONFIG
        WITH PORT 502
        WITH UNIT_ID 1
        WITH ONE_BASED_ADDRESSES true
    ADD MAPPING ServerTags
        WITH SOURCE_TOPIC "plant/modbus"
        ADD TAG Temperature
            WITH ADDRESS "1"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
```

> [!NOTE]
>
> Modicon-style addresses are decoded the same way regardless of `ONE_BASED_ADDRESSES`. The flag only affects plain numeric addresses.

### Tag parameters

**ADDRESS** `string` *required*

Register or coil address. Plain numeric (0–65535 zero-based by default, or 1–65536 when `ONE_BASED_ADDRESSES true`), or Modicon notation (`400001+`, `300001+`, `100001+`). Multi-word types occupy consecutive PDU addresses from the resolved offset. See [Address notation](#address-notation).

**ADDRESS\_TYPE** `string` *required*

Which bank the tag lives in: `HOLDING_REGISTER`, `INPUT_REGISTER`, `COIL`, or `DISCRETE_INPUT`.

**DATA\_TYPE** `string` (default: INT16)

Wire type: `BOOL`, `INT16`, `UINT16`, `INT32`, `UINT32`, `INT64`, `UINT64`, `FLOAT`, `DOUBLE`, or `STRING`. `INT32`/`UINT32`/`FLOAT` span 2 registers; `INT64`/`UINT64`/`DOUBLE` span 4.

**LENGTH** `integer` (default: 40)

**STRING only.** Maximum string size in **bytes** (2 bytes per register). Register count is `ceil(bytes / 2)` (integer form: `(bytes + 1) / 2`). When omitted, defaults to **40 bytes** (20 registers) and logs a Warning. Alias: `STRING_SIZE`. Must resolve to at most **123 registers** (**246 bytes**), the FC16 write cap; larger values are rejected during connector validation.

**SOURCE\_TOPIC** `string`

MQTT topic whose publishes set this register or coil. Defaults to `{mapping SOURCE_TOPIC}/{TagName}`.

**WRITABLE** `boolean` (default: false)

Allow masters to write the address. Only `HOLDING_REGISTER` and `COIL` are master-writable.

**DESTINATION\_TOPIC** `string`

Topic published to when a master writes this (writable) address.

**BYTE\_ORDER** `string` (default: BIGENDIAN)

Byte order within each register for multi-byte types: `BIGENDIAN` or `LITTLEENDIAN`.

**WORD\_ORDER** `string` (default: BIGENDIAN)

Word order across registers for 32-/64-bit types (high word first by default): `BIGENDIAN` or `LITTLEENDIAN`.

**DECIMAL\_PLACES** `integer` (default: 2)

Rounding applied to `FLOAT`/`DOUBLE` values published to `DESTINATION_TOPIC`.

**PERSISTENCE** `boolean`

Per-tag override of the connector persistence default. Precedence: tag → mapping → connector. See [Data persistence & recovery](#data-persistence--recovery).

**DESCRIPTION** `string`

Free-text documentation for the tag.

**EVERY** `duration` (default: 1 second)

On the mapping block: register → MQTT sync cadence for master writes.

### All four address types

One server exposing every bank type:

```lot wrap focus={4-22} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MixedServer WITH TYPE MODBUS_SERVER
    ADD MAPPING Points
        WITH SOURCE_TOPIC "plant/mixed"
        ADD TAG Pressure
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
        ADD TAG MotorSpeed
            WITH ADDRESS "50"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "UINT16"
        ADD TAG PumpEnable
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "COIL"
            WITH DATA_TYPE "BOOL"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "plant/mixed/pump/cmd"
        ADD TAG DoorClosed
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "DISCRETE_INPUT"
            WITH DATA_TYPE "BOOL"
```

All four points are fed from `plant/mixed/<TagName>`; only `PumpEnable` accepts master writes (→ `plant/mixed/pump/cmd`).

### STRING tag example

Reserve a writable 40-byte holding-register range for barcode values a master can write with FC16:

```lot wrap focus={7} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ScannerServer WITH TYPE MODBUS_SERVER
    ADD MAPPING ScannerTags
        ADD TAG Barcode
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 40
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "scanner/barcode"
```

`WITH LENGTH 40` reserves holding registers 0–19 (`ceil(40 / 2) = 20` registers). A master FC16 write to those 20 registers is decoded and published to `scanner/barcode`. `STRING_SIZE` is accepted as an alias for `LENGTH`.

***

## Protocol Conformance

This server implements Modbus Application Protocol **Conformance Class 0 and Class 1** over Modbus/TCP—the interoperability bar for standard masters:

| Class | Function codes | Supported |
| - | - | - |
| Class 0 | FC 03 Read Holding Registers, FC 16 Write Multiple Registers | ✅ |
| Class 1 | FC 01 Read Coils, FC 02 Read Discrete Inputs, FC 04 Read Input Registers, FC 05 Write Single Coil, FC 06 Write Single Register | ✅ |
| Class 2 | FC 15 Write Multiple Coils | ✅ |

Writes are accepted only on `WRITABLE` `HOLDING_REGISTER`/`COIL` addresses. Undeclared addresses and writes to read-only banks return exception **02 (Illegal Data Address)**.

> [!NOTE]
>
> Modbus/TCP is **plaintext**—the protocol has no native authentication or encryption. Secure deployments by binding to a specific interface and restricting access at the network layer (firewall, VLAN, VPN). Modbus/TCP Security (TLS on port 802) is not yet implemented.

***

## Data Persistence & Recovery

By default a server connector holds register and coil values **in memory only**—a broker restart resets every address to zero. Set `WITH PERSISTENCE true` on `MODBUS_SERVER_CONFIG` to snapshot served values and restore them on startup.

### Ownership-aware policy

What is safe to persist depends on who owns the value:

| Bank | Owner | Default | On restart |
| - | - | - | - |
| `HOLDING_REGISTER` / `COIL`, `WRITABLE true` | Master-written setpoint lives only in the slave | **Persisted** | Restored **authoritatively**—wins over retained MQTT |
| `INPUT_REGISTER` / `DISCRETE_INPUT`, and non-writable banks | Fed from live MQTT | **Not persisted** | Recovered from **live MQTT** (retained message / next publish) |

Master-written setpoints survive a restart; live telemetry always reflects the current MQTT source.

### Per-tag overrides

`WITH PERSISTENCE true|false` on an individual `ADD TAG` overrides the connector default:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OverrideServer WITH TYPE MODBUS_SERVER
    ADD MODBUS_SERVER_CONFIG
        WITH PORT 502
        WITH PERSISTENCE true
    ADD MAPPING Registers
        WITH SOURCE_TOPIC "plant/line1"
        ADD TAG Setpoint
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE "true"
        ADD TAG LastGoodTemp
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH PERSISTENCE "true"
        ADD TAG ScratchSetpoint
            WITH ADDRESS "300"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "INT16"
            WITH WRITABLE "true"
            WITH PERSISTENCE "false"
```

* `Setpoint` — restored authoritatively to the last master-written value.
* `LastGoodTemp` — served from snapshot until `plant/line1/LastGoodTemp` next publishes.
* `ScratchSetpoint` — always comes back at zero.

### Caching slow or infrequently-updated sources

Broker-fed tags are not persisted by default. When a source updates infrequently—an hourly energy total, a shift-latched value—force-persist with `WITH PERSISTENCE "true"` so the last received value is re-served on cold start until the next live publish overrides it.

```lot wrap focus={6-12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MeterServer WITH TYPE MODBUS_SERVER
    ADD MODBUS_SERVER_CONFIG
        WITH PORT 502
        WITH PERSISTENCE true
    ADD MAPPING Meters
        WITH SOURCE_TOPIC "plant/energy"
        ADD TAG TotalEnergy
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH PERSISTENCE "true"
```

If every tag in a mapping is a slow source, set `WITH PERSISTENCE "true"` once on the `ADD MAPPING` block instead of per tag.

### Storage & durability

* Values are written through a non-blocking background worker on every change (rapid updates coalesce to the latest value).
* The snapshot lives in an encrypted-at-rest database under the broker data directory.
* A snapshot is keyed to the connector's tag definitions by a fingerprint. If addresses or types change between runs, the stale snapshot is discarded rather than replayed into reshaped addresses.

***

## Verify Your Server

**1. Deploy the connector**

Add the connector definition to your broker and confirm connector status shows **Connected** (the endpoint is listening).

**2. Connect with a Modbus master**

Use any standards-compliant Modbus TCP master. Connect to `<HOST>:<PORT>` and address the connector's `UNIT_ID` (default 1).

**3. Confirm MQTT → register**

Publish a test value to a bound `SOURCE_TOPIC`. Read the corresponding address from the master and confirm the decoded value matches.

**4. Confirm register → MQTT**

For a writable tag with a `DESTINATION_TOPIC`, write a value from the master. Subscribe to the destination topic with MQTT Explorer or any MQTT client and confirm the publish arrives within one `WITH EVERY` interval.

***

## Limitations

> [!WARNING]
>
> Each `MODBUS_SERVER` connector binds exclusively to its `PORT`. A second connector on the same port fails to start. Give each connector its own port.

***

## Troubleshooting

Publish `-checkConnectorConnection <connector_name>` to `$SYS/Coreflux/Command`. For a server connector this reports whether the hosted endpoint is **listening**, along with the endpoint, port, unit ID, and current connection count.

> **Connector status never Connected**
>
> * **Port in use** — Another connector or process owns `PORT`. Choose a free port or stop the conflicting service.
> * **Bind error** — Check broker logs. Ensure `HOST` is a valid interface on the machine.

> **Master cannot connect**
>
> Confirm `HOST`/`PORT`, network path, and firewall rules. The master must target the connector's `UNIT_ID` (default 1).

> **Master reads zero or stale values**
>
> Registers default to zero until first set. Verify `SOURCE_TOPIC` has published; retained MQTT values are seeded at startup.

> **Master write not appearing on MQTT**
>
> * Confirm the tag is `WRITABLE` on a `HOLDING_REGISTER` or `COIL` with a `DESTINATION_TOPIC`.
> * The value surfaces within one `WITH EVERY` interval—verify the cadence.

> **Write rejected (Modbus exception)**
>
> Read-only banks (`INPUT_REGISTER`, `DISCRETE_INPUT`) and non-writable tags reject master writes by design. Undeclared addresses return Illegal Data Address.
>
> **Accepted master writes:** FC06 (Write Single Register) and FC16 (Write Multiple Registers) on `WRITABLE` `HOLDING_REGISTER` tags; FC05 (Write Single Coil) and FC15 (Write Multiple Coils) on `WRITABLE` `COIL` tags.
>
> **Rejected master writes:** any write to `INPUT_REGISTER` or `DISCRETE_INPUT`; writes to non-`WRITABLE` tags; writes to addresses outside the declared tag range (including partial FC16 ranges that extend beyond a STRING tag's reserved registers).

> **Master FC16 write fails on a STRING tag (Illegal Data Address)**
>
> **Problem:** A master writes a STRING with FC16, but the server returns Illegal Data Address.
>
> **Check:** Confirm the full holding-register range is declared by the tag. STRING capacity is `ceil(LENGTH / 2)` registers. An omitted `WITH LENGTH` reserves the default **40 bytes** (**20 registers**) and logs a Warning; older broker versions reserved only one register when the setting was omitted. `STRING_SIZE` remains accepted as an alias.
>
> **Solution:** Set `WITH LENGTH` to the complete byte width the master writes, up to **246 bytes** (**123 registers**). Rejected undeclared holding-register ranges log `Master write rejected: … Check WITH LENGTH on STRING tags.`

> **Master activity logging**
>
> The broker logs master activity for this connector in the broker log:
>
> * **Accepted writes** — FC06/FC16 on writable `HOLDING_REGISTER` tags; FC05/FC15 on writable `COIL` tags, with bank-aware function-code labels.
> * **Rejected writes** — read-only banks, non-writable tags, and undeclared address ranges (including partial FC16 spans beyond a STRING tag's reserved registers).
> * **Rejected reads** — undeclared or out-of-range read requests.
> * **Undeclared holding-register ranges** — rejection messages include `Check WITH LENGTH on STRING tags` when sizing is the likely cause.
> * **Connections** — open/close events with the active connection count from the existing watchdog.
>
> These logs **cannot identify the master's source IP** — it is not available to the server connector.

> **Wrong numeric value**
>
> Align `BYTE_ORDER` and `WORD_ORDER` with the master's expectation. Default is big-endian, high word first.

> **Address mismatch (Illegal Data Address)**
>
> Confirm tag `ADDRESS` values match how the master addresses the server. Use `WITH ONE_BASED_ADDRESSES true` when your tag labels follow device-manual numbering (register 1 = address `"1"`). Modicon notation (`400100`) works regardless of the flag.

> **Connection-limit behavior**
>
> `MAX_CONNECTIONS` is a **best-effort** soft cap—the underlying library exposes no per-connection control, so exceeding the cap is logged rather than enforced at accept time. Restrict concurrency at the network layer if a hard cap is required.

***

## Best Practices

> **Bind to a specific interface in production**
>
> Prefer `WITH HOST "192.168.10.5"` over `0.0.0.0` when only one network should reach the server.

> **Keep environment values out of connector text**
>
> Use `WITH PORT GET ENV "MODBUS_PORT"` instead of hard-coding environment-specific ports.

> **Declare each exposed address explicitly**
>
> Only declared addresses are served. One `ADD TAG` per register or coil a master needs.

> **Make tags WRITABLE only when needed**
>
> Leave `WRITABLE` unset for read-only points. Non-writable holding registers and read-only banks reject writes with a Modbus exception.

> **Match byte and word order to the master**
>
> Set `WORD_ORDER "LITTLEENDIAN"` when the master expects low word first. Default is big-endian, high word first.

> **Size WITH EVERY to outbound latency**
>
> Use a shorter interval for responsive control loops; a longer one to reduce churn for slowly-changing values.

> **Reserve ports per connector**
>
> Document which connector owns which port to avoid startup conflicts when adding connectors.

> **Restrict access at the network layer**
>
> Modbus TCP has no authentication. Place the server behind a firewall or VLAN and rely on HUB topic permissions for MQTT-side security.

> **Monitor connector status**
>
> Watch `$SYS/Coreflux/Routes/{connector_name}/status`. `Connected` means the server is listening—investigate `Error` immediately (usually a port conflict).

***

## Next Steps

> **[Modbus TCP Client](./modbus-tcp-client)**
>
> Connect to remote Modbus devices and poll register data into MQTT.

> **[Modbus Serial Client](./modbus-serial-client)**
>
> Connect to remote Modbus RTU devices over serial.


# OPC UA Client Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/opcua-client

Connect to remote OPC UA servers and poll device data into MQTT with security and BrowsePath support

## OPC UA Client

> [!NOTE]
>
> This page documents the **client** connector (`OPCUA`)—the broker connects **to** a remote OPC UA server and reads or writes device data over MQTT. To expose MQTT topics **to** OPC UA clients instead (SCADA, UaExpert, PLCs connect to the broker), see [OPC UA Server](./opcua-server).

The `OPCUA` connector enables communication with OPC UA servers, providing a standardized, cross-platform protocol for industrial automation. It supports multiple authentication modes, security policies, and both NodeId and BrowsePath addressing.

> [!TIP]
>
> OPC UA is vendor-neutral and widely supported by modern industrial equipment. Use it when you need secure, standardized communication across different manufacturer's devices.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OPCServer WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
        WITH AUTH_MODE 0
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
    ADD MAPPING ProcessData
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "ns=2;s=Channel1.Device1.Temperature"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "opcua/temperature"
```

***

## Connection Configuration

### OPCUA\_CONFIG Parameters

**ENDPOINT\_URL** `string` *required*

OPC UA server endpoint URL (e.g., `opc.tcp://localhost:4840`).

**AUTH\_MODE** `integer`

Authentication mode:

* `0` - Anonymous (no authentication)
* `1` - Username/Password
* `2` - Certificate

Default: 0.

**USERNAME** `string`

Username for authentication (required if AUTH\_MODE is 1).

**PASSWORD** `string`

Password for authentication (required if AUTH\_MODE is 1).

**USE\_SECURITY** `boolean`

Enable security mode. Default: false.

**SECURITY\_POLICY** `integer`

Security policy level:

* `0` - None
* `1` - Basic128Rsa15
* `2` - Basic256
* `3` - Basic256Sha256
* `4` - Aes128\_Sha256\_RsaOaep
* `5` - Aes256\_Sha256\_RsaPss

Default: 0.

**MESSAGE\_SECURITY** `integer`

Message security mode:

* `0` - None
* `1` - Sign
* `2` - SignAndEncrypt

Default: 0.

**PKI\_DIR** `string`

Root directory for the four-folder PKI store (`own`, `issuer`, `trusted`, `rejected`). Defaults to the OPC Foundation layout under local application data. Set an explicit path—and mount it as a volume in Docker—so certificates persist across restarts. See [Certificate Management](#certificate-management).

**CLIENT\_CERT\_PATH** `string`

Path to a PKCS#12 (`.pfx`) or PEM client certificate used when `AUTH_MODE` is `2`. The broker loads it, adopts its application URI, and stores it under `PKI_DIR/own`. When omitted, a self-signed certificate is auto-generated on first connect.

**CLIENT\_KEY\_PATH** `string`

Path to the private key PEM file when `CLIENT_CERT_PATH` points to a certificate-only PEM. Not needed for PKCS#12 bundles.

**CLIENT\_CERT\_PASSWORD** `string`

Password for the PKCS#12 bundle or encrypted private key. Use `GET SECRET`—never hard-code passwords in connector definitions.

**AUTO\_ACCEPT\_UNTRUSTED\_CERTIFICATES** `boolean`

Automatically accept untrusted server certificates. Default: false. For production, leave false and trust the server certificate explicitly—see [Certificate Management](#certificate-management).

**SUPPRESS\_NONCE\_VALIDATION\_ERRORS** `boolean`

Suppress nonce validation errors. Default: false.

**TIMEOUT** `integer`

Connection timeout in milliseconds. Default: 90000.

***

## Security Configuration

**Anonymous (No Security)**

For development or trusted networks:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD OPCUA_CONFIG
    WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
    WITH AUTH_MODE 0
    WITH USE_SECURITY "false"
    WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
```

**Username/Password**

Basic authentication:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD OPCUA_CONFIG
    WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
    WITH AUTH_MODE 1
    WITH USERNAME "opcuser"
    WITH PASSWORD "secure_password"
    WITH USE_SECURITY "true"
    WITH SECURITY_POLICY 3
    WITH MESSAGE_SECURITY 2
```

**Certificate Authentication**

Authenticate with an X.509 certificate identity. The application instance certificate secures the channel and identifies the client to the server:

```lot wrap focus={4-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD OPCUA_CONFIG
    WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
    WITH AUTH_MODE 2
    WITH USE_SECURITY true
    WITH SECURITY_POLICY 3
    WITH MESSAGE_SECURITY 2
    WITH PKI_DIR "/data/opcua/pki"
    WITH CLIENT_CERT_PATH "/certs/client.pfx"
    WITH CLIENT_CERT_PASSWORD GET SECRET "OPCUA_CLIENT_CERT_PASSWORD"
```

Omit `CLIENT_CERT_PATH` to auto-generate a self-signed certificate. You still need mutual trust between broker and server—see [Certificate Management](#certificate-management).

***

## Certificate Management

A secured OPC UA client connection requires **two certificates that trust each other**: the broker's **application instance certificate** (channel security and, with `AUTH_MODE 2`, user identity) and the **server's certificate** (must be in your `trusted` store). For server-side trust workflows, see [OPC UA Server](./opcua-server#certificate-management).

> [!TIP]
>
> **Like exchanging ID badges at a secure facility.** Both sides must recognize each other's badge before the door opens—moving a certificate from `rejected` to `trusted` is how you approve a new badge.

### PKI directory layout

Both client and server connectors store certificates in four folders under `PKI_DIR`:

| Folder | Holds | File form |
| - | - | - |
| `own` | This application's certificate (`own/certs`) and private key (`own/private`) | `*.der` + `*.pfx` |
| `issuer` | Trusted CA / issuer certificates for chain validation | `*.der` |
| `trusted` | Trusted peer certificates—the server you accept goes here (`trusted/certs`) | `*.der` |
| `rejected` | Certificates seen during a handshake but not yet trusted | `*.der` |

### Where certificates live

When `PKI_DIR` is not set, it defaults to `%LocalApplicationData%/OPC Foundation/pki`:

| OS | Default path |
| - | - |
| macOS | `~/Library/Application Support/OPC Foundation/pki` |
| Linux | `$XDG_DATA_HOME/OPC Foundation/pki` or `~/.local/share/OPC Foundation/pki` |
| Windows | `%LOCALAPPDATA%\OPC Foundation\pki` |

Relocate the store to a path you control:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD OPCUA_CONFIG
    WITH ENDPOINT_URL "opc.tcp://server:4840"
    WITH PKI_DIR "/data/opcua/pki"
```

> [!WARNING]
>
> In Docker, the default PKI location is ephemeral—the broker regenerates its certificate on every restart and any server that trusted the previous one will reject the new one. **Always set `PKI_DIR` to a mounted volume.**

### Inspecting and exporting certificates

Certificates are plain files you can inspect with `openssl`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# The broker's own certificate and private key
ls "$PKI_DIR"/own/certs/*.der
ls "$PKI_DIR"/own/private/*.pfx

# Inspect subject, validity, and application URI SAN
openssl x509 -inform der -in "$PKI_DIR"/own/certs/<name>.der -noout -subject -dates -ext subjectAltName

# Export public cert for the server's trust list
openssl x509 -inform der -in "$PKI_DIR"/own/certs/<name>.der -out broker-client.pem
```

Give peers the **public** certificate (`own/certs/*.der`). The private key (`own/private/*.pfx`) never leaves the broker.

### Auto-generated client certificate

With `AUTH_MODE 2` and no `CLIENT_CERT_PATH`, the broker auto-generates a self-signed certificate (`CN=CorefluxBroker_OpcUaClient, O=Coreflux`) in `PKI_DIR/own` on first connect:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantClient WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://server:4840"
        WITH AUTH_MODE 2
        WITH USE_SECURITY true
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH PKI_DIR "/data/opcua/pki"
```

You still must (1) get this broker certificate trusted by the server and (2) trust the server's certificate—see the workflows below.

> [!NOTE]
>
> An application instance certificate **must** carry an application URI in its Subject Alternative Name. The OPC UA stack matches certificates by that URI and rejects certificates without one.

### Supply your own client certificate

Use a certificate from your PKI via `CLIENT_CERT_PATH`. Generate it with a mandatory URI SAN:

**Generate certificate**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Self-signed example—use your CA in production. The URI SAN is mandatory.
openssl req -x509 -newkey rsa:2048 -keyout client-key.pem -out client-cert.pem -days 825 -nodes \
  -subj "/CN=PlantClient/O=ACME" \
  -addext "subjectAltName=URI:urn:acme:opcua:plant-client" \
  -addext "keyUsage=digitalSignature,keyEncipherment,dataEncipherment,nonRepudiation" \
  -addext "extendedKeyUsage=clientAuth,serverAuth"

# Bundle into PKCS#12 (.pfx)
openssl pkcs12 -export -inkey client-key.pem -in client-cert.pem \
  -out client.pfx -passout pass:CHANGEME -name plantclient
```

**Reference in connector (PKCS#12)**

```lot wrap focus={6-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantClient WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://server:4840"
        WITH AUTH_MODE 2
        WITH USE_SECURITY true
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH CLIENT_CERT_PATH "/certs/client.pfx"
        WITH CLIENT_CERT_PASSWORD GET SECRET "OPCUA_CLIENT_CERT_PASSWORD"
        WITH PKI_DIR "/data/opcua/pki"
```

**Reference in connector (PEM)**

Point `CLIENT_CERT_PATH` at the certificate PEM. If the key is in a separate file, add `CLIENT_KEY_PATH`:

```lot wrap focus={6-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantClient WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://server:4840"
        WITH AUTH_MODE 2
        WITH USE_SECURITY true
        WITH CLIENT_CERT_PATH "/certs/client-cert.pem"
        WITH CLIENT_KEY_PATH "/certs/client-key.pem"
        WITH CLIENT_CERT_PASSWORD GET SECRET "OPCUA_CLIENT_KEY_PASSWORD"
        WITH PKI_DIR "/data/opcua/pki"
```

### Trust the server's certificate

Required when `USE_SECURITY true` and `AUTO_ACCEPT_UNTRUSTED_CERTIFICATES false`:

**1. Deploy the connector**

The first handshake fails and the server's certificate is written to `PKI_DIR/rejected/certs`.

**2. Move to trusted**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mv "$PKI_DIR"/rejected/certs/<server-cert>.der "$PKI_DIR"/trusted/certs/
```

**3. Reconnect**

The connector reconnects automatically—the handshake now succeeds.

For testing only, skip this with `WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES true`.

### Get the broker trusted by the server

For `AUTH_MODE 2`, the server must trust the broker's client certificate:

**1. Export the broker certificate**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
openssl x509 -inform der -in "$PKI_DIR"/own/certs/<name>.der -out broker-client.pem
```

**2. Add to the server's trust list**

Import `broker-client.pem` (or the `.der`) into the server's trusted certificate store—via its PKI `trusted` folder or vendor certificate manager.

**3. Reconnect**

The server now accepts the certificate identity.

### Rotation and renewal

* **Auto-generated certificates** — Delete files in `PKI_DIR/own/certs` and `PKI_DIR/own/private`, then reconnect; the broker regenerates a new self-signed certificate.
* **Supplied certificates** — Replace the `.pfx`/PEM file, remove the old copy from `PKI_DIR/own`, and redeploy. Re-distribute the new public certificate to the server's trust list before the old one expires.
* Plan rotation **before expiry**—an expired application instance certificate fails the handshake.

### Verify the connection

After mutual trust is configured, confirm the connector connects:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-checkConnectorConnection PlantClient
```

Publish that command to `$SYS/Coreflux/Command`. A response with `"success": true` means the certificate-authenticated session is established.

***

## NodeId Addressing

OPC UA uses NodeIds to identify variables. The format is: `ns=<namespace>;s=<identifier>` or `ns=<namespace>;i=<numeric_id>`

| Format | Example | Description |
| - | - | - |
| String identifier | `ns=2;s=Channel1.Device1.Tag1` | Most common, human-readable |
| Numeric identifier | `ns=2;i=1234` | More efficient, used by some servers |
| GUID identifier | `ns=2;g=12345678-1234-1234-1234-123456789012` | Globally unique identifiers |

> [!WARNING]
>
> An `ADDRESS` that contains a slash (`/`) is treated as a browse path, even with `USE_BROWSE_PATH` off. So a string NodeId with a slash, such as the default `ns=2;s=PlantServer/Temperature` node of a Coreflux [OPC UA server](/latest/lot-language/routes/industrial/opcua-server), can't be read. Give the server tag an explicit `ADDRESS` without slashes, such as `"Line1.Oee"`, and read `ns=2;s=Line1.Oee`.

### Finding NodeIds

Use an OPC UA browser tool (like UaExpert, Prosys OPC UA Browser, or similar) to explore the server's address space and find the correct NodeIds.

### BrowsePath Mode

For servers that support it, you can use symbolic paths instead of NodeIds:

**USE\_BROWSE\_PATH** `boolean`

Enable BrowsePath mode - treat all TAG addresses as browse paths instead of NodeIds.

**BROWSE\_ROOT\_PATH** `string`

Root path for browsing when USE\_BROWSE\_PATH is enabled. Default: Objects.

#### BrowsePath Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD OPCUA_CONFIG
    WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
    WITH USE_BROWSE_PATH "true"
    WITH BROWSE_ROOT_PATH "Objects"
ADD MAPPING Tags
    WITH EVERY 1 SECOND
    ADD TAG Temperature
        WITH ADDRESS "Aliases/MyDevice/Temperature"
        WITH DATA_TYPE "FLOAT"
        WITH SOURCE_TOPIC "opcua/temperature"
```

***

## Data Types

| Data Type | OPC UA Type | Description |
| - | - | - |
| `BOOLEAN` / `BOOL` | Boolean | True/False value |
| `SBYTE` / `SINT` | SByte | Signed 8-bit integer |
| `BYTE` / `USINT` | Byte | Unsigned 8-bit integer |
| `INT16` / `INT` / `WORD` | Int16 | 16-bit integer |
| `UINT16` / `UINT` | UInt16 | Unsigned 16-bit integer |
| `INT32` / `DINT` | Int32 | Signed 32-bit integer |
| `UINT32` / `UDINT` / `DWORD` | UInt32 | Unsigned 32-bit integer |
| `INT64` / `LINT` | Int64 | Signed 64-bit integer |
| `UINT64` / `ULINT` / `LWORD` | UInt64 | Unsigned 64-bit integer |
| `FLOAT` / `FLOAT32` / `REAL` | Float | 32-bit floating point |
| `DOUBLE` / `FLOAT64` / `LREAL` | Double | 64-bit floating point |
| `CHAR` | Char | Single character |
| `WCHAR` | WChar | Wide character |
| `TIME` | Time | Time duration |
| `DATE` | Date | Date value |
| `TOD` | TimeOfDay | Time of day |
| `STRING` | String | Unicode string; sized with `LENGTH` (default 256 bytes) |

### String sizing

For `STRING` tags, `WITH LENGTH` sets the maximum string size in **bytes** (default **256**). `STRING_SIZE` is accepted as an alias for the same field.

```lot wrap focus={11} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OpcUaStrings WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
        WITH AUTH_MODE 0
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
    ADD MAPPING ProductData
        WITH EVERY 1 SECOND
        ADD TAG ProductName
            WITH ADDRESS "ns=2;s=Product.Name"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 128
            WITH SOURCE_TOPIC "opcua/product/name"
```

For cross-protocol defaults and caps, see [String sizing by Connector](./overview#string-sizing-by-connector) on the industrial overview.

***

## TAG Configuration

### Complete TAG Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG ProcessTemperature
    WITH ADDRESS "ns=2;s=Process.Temperature"
    WITH DATA_TYPE "FLOAT"
    WITH SOURCE_TOPIC "opcua/process/temperature"
    WITH SCALING 1
    WITH OFFSET 0
    WITH UNIT "°C"
    WITH DECIMAL_PLACES 2
    WITH MIN_VALUE -50
    WITH MAX_VALUE 500
    WITH DEADBAND 0.5
    WITH PUBLISH_MODE "JSON"
    WITH WRITABLE "true"
    WITH DESTINATION_TOPIC "opcua/process/temperature/set"
    WITH IS_ARRAY "false"
    WITH DESCRIPTION "Main process temperature sensor"
```

### TAG Parameters

> **Address Configuration**
>
> **ADDRESS** `string` *required*
>
> OPC UA NodeId (e.g., `ns=2;s=MyVariable` or `ns=2;i=1234`) or BrowsePath if USE\_BROWSE\_PATH is enabled.
>
> **DATA\_TYPE** `string` *required*
>
> OPC UA data type: `BOOLEAN`, `BYTE`, `INT16`, `UINT16`, `INT32`, `UINT32`, `INT64`, `UINT64`, `FLOAT`, `DOUBLE`, `STRING`.
>
> **IS\_ARRAY** `boolean`
>
> Indicates if the value is an array. Default: false.
>
> **LENGTH** `integer` (default: 256)
>
> **STRING only.** Maximum string size in bytes. Alias: `STRING_SIZE`.

> **Value Transformation**
>
> **SCALING** `double`
>
> Multiplier for value transformation. Default: 1.0.
>
> **OFFSET** `double`
>
> Offset added after scaling. Default: 0.0.
>
> **DECIMAL\_PLACES** `integer`
>
> Decimal places in output. Default: 2.

> **Filtering**
>
> **MIN\_VALUE** `double`
>
> Minimum allowed value.
>
> **MAX\_VALUE** `double`
>
> Maximum allowed value.
>
> **DEADBAND** `double`
>
> Minimum change to trigger publish. Default: 0.0.

> **Publishing**
>
> **SOURCE\_TOPIC** `string`
>
> Topic where PLC values are published. Subscribe here to receive sensor data.
>
> **PUBLISH\_MODE** `string`
>
> Output format: `VALUE_ONLY` or `JSON`. Default: VALUE\_ONLY.
>
> **UNIT** `string`
>
> Engineering unit for documentation.
>
> **DESCRIPTION** `string`
>
> Human-readable description.

> **Write Configuration**
>
> **WRITABLE** `boolean`
>
> Allow writing to this node. Default: false.
>
> **DESTINATION\_TOPIC** `string`
>
> Topic to send write commands. Publish a value here to write it to the PLC.

***

## Event-Based Operations

For on-demand OPC UA operations (not polling), use the EVENT syntax. Publish a message to SOURCE\_TOPIC to trigger the operation; the connector executes it and publishes the result to DESTINATION\_TOPIC.

### Supported Operations

| Operation | Description | Query Parameters |
| - | - | - |
| `READ` | Read a node value on demand | `node_id`, `data_type` |
| `WRITE` | Write a value to a node | `node_id`, `data_type`, `value` |

### Query Parameters

| Parameter | Description | Example |
| - | - | - |
| `operation` | Operation type: `READ` or `WRITE` | `READ` |
| `node_id` | OPC UA NodeId (string or numeric) | `ns=2;i=2`, `ns=2;s=Process.Temp` |
| `data_type` | OPC UA data type | `INT32`, `FLOAT`, `DOUBLE`, `STRING` |
| `value` | Value to write (WRITE only) | `42`, `23.5`, `"hello"` |

### Read Example

Read a node value on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadOnDemand
    WITH SOURCE_TOPIC "opcua/commands/read"
    WITH DESTINATION_TOPIC "opcua/responses/read"
    WITH QUERY "{operation: READ, node_id: ns=2;i=2, data_type: INT32}"
```

### Write Example

Write a FLOAT value to a node on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT WriteSetpoint
    WITH SOURCE_TOPIC "opcua/commands/write"
    WITH DESTINATION_TOPIC "opcua/responses/write"
    WITH QUERY "{operation: WRITE, node_id: ns=2;s=Process.Setpoint, data_type: FLOAT, value: 75.0}"
```

***

## Complete Examples

**Basic Connection**

Simple OPC UA connection with anonymous access:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OPCServer WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
        WITH AUTH_MODE 0
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
    ADD MAPPING ProcessData
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "ns=2;s=Channel1.Device1.Temperature"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "opcua/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "ns=2;s=Channel1.Device1.Pressure"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "opcua/pressure"
            WITH UNIT "bar"
        ADD TAG Status
            WITH ADDRESS "ns=2;s=Channel1.Device1.Status"
            WITH DATA_TYPE "INT32"
            WITH SOURCE_TOPIC "opcua/status"
```

**Secure Connection**

Production setup with encryption:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecureOPC WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
        WITH AUTH_MODE 1
        WITH USERNAME "operator"
        WITH PASSWORD "secure_password_here"
        WITH USE_SECURITY "true"
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH TIMEOUT 30000
    ADD MAPPING SecureData
        WITH EVERY 500 MILLISECONDS
        ADD TAG CriticalValue
            WITH ADDRESS "ns=2;s=Safety.CriticalValue"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "secure/critical"
            WITH PUBLISH_MODE "JSON"
```

**BrowsePath Mode**

Using symbolic paths:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BrowsePathOPC WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
        WITH AUTH_MODE 0
        WITH USE_BROWSE_PATH "true"
        WITH BROWSE_ROOT_PATH "Objects"
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
    ADD MAPPING ProcessTags
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "DataAccess/AnalogItems/Temperature"
            WITH DATA_TYPE "DOUBLE"
            WITH SOURCE_TOPIC "opcua/temperature"
        ADD TAG Setpoint
            WITH ADDRESS "DataAccess/AnalogItems/Setpoint"
            WITH DATA_TYPE "DOUBLE"
            WITH SOURCE_TOPIC "opcua/setpoint"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "opcua/setpoint/write"
```

**Array Values**

Reading array data:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ArrayOPC WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
        WITH AUTH_MODE 0
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
    ADD MAPPING ArrayData
        WITH EVERY 1 SECOND
        ADD TAG TemperatureArray
            WITH ADDRESS "ns=2;s=Process.TemperatureArray"
            WITH DATA_TYPE "FLOAT"
            WITH IS_ARRAY "true"
            WITH SOURCE_TOPIC "opcua/temperatures"
            WITH PUBLISH_MODE "JSON"
        ADD TAG StatusBits
            WITH ADDRESS "ns=2;s=Process.StatusBits"
            WITH DATA_TYPE "BOOLEAN"
            WITH IS_ARRAY "true"
            WITH SOURCE_TOPIC "opcua/status/bits"
```

**Kepware Connection**

Connecting to Kepware OPC UA server:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR KepwareServer WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.50:49320"
        WITH AUTH_MODE 0
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
    ADD MAPPING KepwareTags
        WITH EVERY 500 MILLISECONDS
        ADD TAG Motor1Speed
            WITH ADDRESS "ns=2;s=Channel1.Device1.Motor1_Speed"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "kepware/motor1/speed"
            WITH UNIT "RPM"
        ADD TAG Motor1Current
            WITH ADDRESS "ns=2;s=Channel1.Device1.Motor1_Current"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "kepware/motor1/current"
            WITH UNIT "A"
        ADD TAG Motor1Running
            WITH ADDRESS "ns=2;s=Channel1.Device1.Motor1_Running"
            WITH DATA_TYPE "BOOLEAN"
            WITH SOURCE_TOPIC "kepware/motor1/running"
```

**Combined (Cyclic + On-Demand)**

Continuous monitoring with on-demand read and write events in the same connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FullOPCSetup WITH TYPE OPCUA
    ADD OPCUA_CONFIG
        WITH ENDPOINT_URL "opc.tcp://192.168.1.100:4840"
        WITH AUTH_MODE 0
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES "true"
    
    ADD MAPPING ProcessData
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "ns=2;s=Channel1.Device1.Temperature"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "opcua/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "ns=2;s=Channel1.Device1.Pressure"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "opcua/pressure"
            WITH UNIT "bar"
    
    ADD EVENT ReadNode
        WITH SOURCE_TOPIC "opcua/commands/read"
        WITH DESTINATION_TOPIC "opcua/responses/read"
        WITH QUERY "{operation: READ, node_id: ns=2;s=Channel1.Device1.Status, data_type: INT32}"
    
    ADD EVENT WriteSetpoint
        WITH SOURCE_TOPIC "opcua/commands/write"
        WITH DESTINATION_TOPIC "opcua/responses/write"
        WITH QUERY "{operation: WRITE, node_id: ns=2;s=Channel1.Device1.Setpoint, data_type: FLOAT, value: 0}"
```

The MAPPING continuously reads temperature and pressure. To trigger an on-demand status read, publish any message to `opcua/commands/read`. To write a setpoint, publish to `opcua/commands/write`.

***

## Security Best Practices

> **Use Encryption in Production**
>
> Always enable security for production deployments:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH USE_SECURITY "true"
> WITH SECURITY_POLICY 3  // Basic256Sha256
> WITH MESSAGE_SECURITY 2  // SignAndEncrypt
> ```

> **Don't Auto-Accept Certificates**
>
> In production, properly configure certificate trust:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES false
> ```
>
> Move server certificates from `PKI_DIR/rejected/certs` to `PKI_DIR/trusted/certs` during commissioning. See [Certificate Management](#certificate-management).

> **Use Strong Authentication**
>
> Prefer username/password or certificate authentication over anonymous:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH AUTH_MODE 1  // or '2' for certificate
> WITH USERNAME "operator"
> WITH PASSWORD "strong_password_here"
> ```

***

## Troubleshooting

> **Connection Timeout**
>
> * Verify endpoint URL is correct
> * Check firewall allows TCP port (usually 4840)
> * Ensure server is running and accessible
> * Try increasing TIMEOUT value

> **Security Rejection**
>
> * Verify security policy matches server configuration
> * **Server certificate not trusted** — Move it from `PKI_DIR/rejected/certs` to `PKI_DIR/trusted/certs`, or set `AUTO_ACCEPT_UNTRUSTED_CERTIFICATES true` for testing only
> * **Supplied certificate ignored** — Reissue with a `subjectAltName=URI:...` SAN; certificates without an application URI are rejected
> * **Server rejects client certificate** — Export the broker's public cert from `PKI_DIR/own/certs` and add it to the server's trust list
> * **Certificate regenerates every restart** — Set `PKI_DIR` to a persistent volume (especially in Docker)
> * **`BadCertificateUriInvalid`** — Regenerate the certificate or set a stable application URI in the SAN

> **Connector with CLIENT\_CERT\_PATH fails to start**
>
> * Verify the file path is correct and readable by the broker
> * Check `CLIENT_CERT_PASSWORD` matches the PKCS#12 bundle or encrypted key
> * For a split PEM (certificate and key in separate files), set `CLIENT_KEY_PATH`
> * The broker log names the failing file—check it for the exact cause

> **NodeId Not Found**
>
> * Use OPC UA browser to verify correct NodeId
> * Check namespace index (ns=) is correct
> * Verify node exists in server's address space
> * Try BrowsePath mode if NodeId is unclear

> **Authentication Failed**
>
> * Verify username and password
> * Check user has appropriate permissions
> * Ensure AUTH\_MODE matches server requirements

> **Incorrect Values**
>
> * Verify DATA\_TYPE matches server variable type
> * Check IS\_ARRAY setting for array values
> * Verify SCALING and OFFSET calculations

***

## Next Steps

> **[OPC UA Server Connector](./opcua-server)**
>
> Expose MQTT topics as OPC UA nodes for SCADA and OT clients.

> **[ADS (Beckhoff)](./ads)**
>
> Connect to TwinCAT systems.


# OPC UA Server Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/opcua-server

Expose MQTT topics as OPC UA nodes so SCADA systems, PLCs, and OPC UA clients connect to your Coreflux broker

## OPC UA Server

> [!NOTE]
>
> This page documents the **server** connector (`OPCUA_SERVER`)—the broker **hosts** an OPC UA server and exposes MQTT topics as nodes. External clients connect to the broker. To connect the broker **to** a remote OPC UA device instead, see [OPC UA Client](./opcua-client).

The `OPCUA_SERVER` connector makes your broker **host** an OPC UA server. External clients—SCADA, UaExpert, PLCs—connect **to the broker** and see your MQTT topics as OPC UA nodes.

Use `OPCUA` when you need to **read from** a device. Use `OPCUA_SERVER` when OT systems need to **browse and write** values that live on your MQTT bus.

> [!TIP]
>
> **Like turning your broker into a shop window.** MQTT messages update what's on display (node values), and customers (OPC UA clients) can look—and, for writable tags, change items that publish back to MQTT.

## When to Use This Connector

* **SCADA integration** — Let a SCADA or HMI browse broker data without custom drivers.
* **OT/IT bridge** — Expose IoT sensor streams to plant-floor tools that speak OPC UA.
* **Bidirectional control** — Writable tags let clients adjust setpoints; the broker publishes the new value to MQTT.
* **Dynamic discovery** — Wildcard topic mappings create nodes automatically as matching topics first publish.

***

The sections below cover data flow, configuration, persistence, and production patterns.

## Quick Start

**Expose static tags**

Map MQTT topics to fixed OPC UA nodes. Each `ADD TAG` creates one node; publishing to `{SOURCE_TOPIC}/{TagName}` updates it.

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
    ADD MAPPING Line1
        WITH SOURCE_TOPIC "factory/line1"
        ADD TAG Temperature
            WITH DATA_TYPE "FLOAT"
        ADD TAG Counter
            WITH DATA_TYPE "INT32"
```

* Publish `23.5` to `factory/line1/Temperature` → node `ns=2;s=PlantServer/Temperature` reads `23.5`.
* Publish `1042` to `factory/line1/Counter` → node `ns=2;s=PlantServer/Counter` reads `1042`.

**Writable setpoints**

Allow OPC UA clients to write a node; the broker publishes the value back to MQTT on the same topic, retained.

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
    ADD MAPPING Line1
        WITH SOURCE_TOPIC "factory/line1"
        ADD TAG Setpoint
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
            WITH DECIMAL_PLACES 1
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
```

MQTT publishes set the node. A client writing `72.4` to the Setpoint node publishes `72.4` to `factory/line1/Setpoint` (clamped and rounded per tag settings).

**Dynamic wildcard topics**

Omit `ADD TAG` and use an MQTT wildcard in `SOURCE_TOPIC`. Nodes appear automatically when matching topics first publish—see [Dynamic topic handling](#dynamic-topic-handling).

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DynamicSensors WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
    ADD MAPPING Sensors
        WITH SOURCE_TOPIC "sensors/+/value"
```

First publish to `sensors/press1/value` creates node `ns=2;s=sensors/press1/value`. First publish to `sensors/tank2/value` creates another node. No connector edit required.

**Secure production server**

Encrypt traffic, require credentials, and combine static tags with dynamic discovery:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecurePlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH ROOT_FOLDER "Plant"
        WITH NAMESPACE_URI "urn:acme:plant"
        WITH USE_SECURITY true
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH ALLOW_ANONYMOUS false
        WITH USERNAME GET ENV "OPCUA_USER"
        WITH PASSWORD GET SECRET "OPCUA_PASSWORD"
    ADD MAPPING Line1
        WITH SOURCE_TOPIC "factory/line1"
        ADD TAG Setpoint
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
            WITH DECIMAL_PLACES 1
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
    ADD MAPPING Sensors
        WITH SOURCE_TOPIC "sensors/+/value"
```

Clients connect with `opc.tcp://<broker-host>:4840` using Basic256Sha256 and SignAndEncrypt. Store credentials with `GET ENV` / `GET SECRET`—never hard-code passwords.

**Crash-resilient setpoints**

Persist client-written setpoints across broker restarts:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ResilientServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH PERSISTENCE true
    ADD MAPPING Control
        WITH SOURCE_TOPIC "plant/line1"
        ADD TAG Setpoint
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
            WITH DECIMAL_PLACES 1
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
        ADD TAG Temperature
            WITH DATA_TYPE "FLOAT"
```

After a restart, a client reading `Setpoint` gets the last value it wrote instead of `BadWaitingForInitialData`. `Temperature` refreshes from the live MQTT source, not the snapshot.

***

## How Data Flows

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
graph LR
    subgraph mqtt [MQTT]
        Topics[Topics]
    end

    subgraph broker [Coreflux Broker]
        Connector[OPCUA_SERVER Connector]
        Nodes[OPC UA Nodes]
    end

    subgraph ot [OT Clients]
        Client[SCADA / UaExpert / PLC]
    end

    Topics -->|publish sets value| Connector
    Connector --> Nodes
    Nodes -->|browse / read| Client
    Client -->|write writable tag| Connector
    Connector -->|publish retained| Topics
```

| Direction | Behavior |
| - | - |
| **MQTT → node** | Each tag binds to an MQTT topic via `SOURCE_TOPIC`. A publish on that topic sets the node value. The MQTT payload is authoritative—no scaling or rounding is applied inbound. Retained values present before the connector starts are seeded at startup. |
| **node → MQTT** | When a tag has `WITH WRITABLE true`, an external client writing the node publishes the new value back to the **same** `SOURCE_TOPIC`, retained. `FLOAT` and `DOUBLE` values are rounded to `DECIMAL_PLACES` (default 2) and clamped by `MIN_VALUE` / `MAX_VALUE`. Client writes do not loop back into duplicate node updates. |
| **Wildcard mappings** | Wildcard `SOURCE_TOPIC` patterns create nodes on first publish. See [Dynamic topic handling](#dynamic-topic-handling). |

***

## Server Configuration

All settings live in the `OPCUA_SERVER_CONFIG` block. Store credentials with `GET ENV` or `GET SECRET`.

The example below shows a production-oriented config: custom identity, encrypted endpoint, username/password auth, and a persistent certificate store. Clients connect at `opc.tcp://<broker-host>:4840/coreflux`.

```lot wrap focus={2-16} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantOpcServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH ENDPOINT_PATH "/coreflux"
        WITH APPLICATION_NAME "Coreflux Plant Server"
        WITH APPLICATION_URI "urn:plant.example.com:Coreflux:PlantOpcServer"
        WITH NAMESPACE_URI "urn:plant.example.com:opcua"
        WITH ROOT_FOLDER "Plant"
        WITH PKI_DIR "/data/opcua-pki"
        WITH USE_SECURITY true
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH ALLOW_ANONYMOUS false
        WITH USERNAME GET ENV "OPCUA_USER"
        WITH PASSWORD GET SECRET "OPCUA_PASSWORD"
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES false
    ADD MAPPING Tags
        WITH SOURCE_TOPIC "plant/tags"
        ADD TAG Status
            WITH DATA_TYPE "INT32"
```

### Connection and identity

**SERVER\_PORT** `integer` (default: 4840)

TCP port the server listens on (`opc.tcp`). Each server connector claims its port process-wide—two connectors cannot share the same port.

**ENDPOINT\_PATH** `string`

Optional path appended to the base address, for example `/coreflux`. Default: empty.

**APPLICATION\_NAME** `string` (default: CorefluxBroker\_OpcUaServer)

Application display name and certificate common name (CN).

**APPLICATION\_URI** `string` (default: urn:\{host}:Coreflux:\{connector})

Application URI. Must match the certificate SAN URI. Changing this regenerates the certificate.

**NAMESPACE\_URI** `string` (default: urn:coreflux:opcua:\{connector})

Namespace URI for exposed nodes.

**ROOT\_FOLDER** `string` (default: connector name)

Root folder under `Objects` where tags are organized.

**PKI\_DIR** `string`

Directory for own, issuer, trusted, and rejected certificate stores. Defaults to the OPC Foundation PKI layout. In Docker, mount this path as a volume so certificates persist across restarts. See [Certificate Management](#certificate-management).

### Security

**USE\_SECURITY** `boolean` (default: true)

Offer a signed or encrypted endpoint.

> [!NOTE]
>
> This defaults to `true` to comply with OPC Foundation specifications, which require secure endpoints. For testing purposes, you might need to set it to `false`.

**SECURITY\_POLICY** `integer` (default: 0)

Security policy offered when `USE_SECURITY` is true:

| Value | Policy |
| - | - |
| `0` | None |
| `3` | Basic256Sha256 |
| `4` | Aes128\_Sha256\_RsaOaep |
| `5` | Aes256\_Sha256\_RsaPss |

**MESSAGE\_SECURITY** `integer` (default: 0)

Message security mode. Requires `SECURITY_POLICY` ≥ 1 when using Sign or SignAndEncrypt.

| Value | Mode |
| - | - |
| `0` | None |
| `1` | Sign |
| `2` | SignAndEncrypt |

**ALLOW\_NO\_SECURITY** `boolean` (default: false)

When `USE_SECURITY` is true, also offer a None/None endpoint. Use for testing only.

### Authentication

**ALLOW\_ANONYMOUS** `boolean` (default: true)

Offer anonymous login. Set to `false` for production and configure `USERNAME`/`PASSWORD` or `ALLOW_CERTIFICATE_AUTH`.

**USERNAME** `string`

Username for password-based login. Use `GET ENV` or `GET SECRET`.

**PASSWORD** `string`

Password for password-based login. Use `GET ENV` or `GET SECRET`.

**ALLOW\_CERTIFICATE\_AUTH** `boolean` (default: false)

Offer X.509 certificate user authentication.

**AUTO\_ACCEPT\_UNTRUSTED\_CERTIFICATES** `boolean` (default: false)

Automatically trust connecting client certificates. When false, untrusted client certs are placed in the `rejected` store.

**PERSISTENCE** `boolean` (default: false)

Persist served node values across broker restarts. See [Data persistence & recovery](#data-persistence--recovery).

> [!NOTE]
>
> An application instance certificate is auto-generated (self-signed) on first start under `PKI_DIR/own`. If you change `APPLICATION_URI`, the certificate is regenerated to match.

***

## Tag and Mapping Configuration

Tags reuse the same vocabulary as the [OPC UA client connector](./opcua-client), but several settings carry different meaning on the server side.

### Server vs. client semantics

| Setting | Client (`OPCUA`) | Server (`OPCUA_SERVER`) |
| - | - | - |
| `SOURCE_TOPIC` | Topic where read values are **published** | **Bidirectional binding** — MQTT sets the node; client writes publish back here |
| `WRITABLE` | Broker may write the remote device | External clients may write the node |
| `DESTINATION_TOPIC` | Write-command topic | Not used on server connectors |
| `ADDRESS` | Required remote NodeId | Optional explicit NodeId; default `s={ROOT_FOLDER}/{TagName}` |
| `EVERY` | Poll interval | Ignored — updates are event-driven from MQTT |
| `QUERY` events | On-demand read/write | Not supported |
| `SCALING` / `OFFSET` / `DEADBAND` | Applied to reads from the device | Not applied inbound — MQTT payload is authoritative |
| `DECIMAL_PLACES` / `MIN_VALUE` / `MAX_VALUE` | Applied to reads | Applied when a client write is published to MQTT |
| `ADD EVENT` / triggers | Supported on client connectors | Not supported |

On server connectors, connector status **Connected** means the endpoint is **listening**—not that a remote session is established.

### Explicit NodeId

By default, a tag named `Temperature` under connector `PlantServer` with `ROOT_FOLDER` defaulting to the connector name maps to `ns=2;s=PlantServer/Temperature`. Override it with `ADDRESS`. Give the string identifier only, without the `ns=2;s=` prefix:

```lot wrap focus={6,7} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
    ADD MAPPING Line1
        WITH SOURCE_TOPIC "factory/line1"
        ADD TAG Temperature
            WITH ADDRESS "Line1.Temp"
            WITH DATA_TYPE "FLOAT"
```

The node is then `ns=2;s=Line1.Temp`.

> [!WARNING]
>
> The Coreflux [OPC UA client](/latest/lot-language/routes/industrial/opcua-client) treats any address with a slash (`/`) as a browse path, not a NodeId. It can't read back a default node such as `ns=2;s=PlantServer/Temperature`, or a dynamic node named after its topic. If a Coreflux OPC UA client reads this server, set an explicit `ADDRESS` without slashes, such as `"Line1.Oee"`. Other OPC UA clients, such as UaExpert, are not affected.

### Writable tag parameters

For writable tags, configure outbound formatting the same way as on the client connector:

**WRITABLE** `boolean` (default: false)

Allow OPC UA clients to write this node. Writes publish to the tag's `SOURCE_TOPIC`.

**DECIMAL\_PLACES** `integer` (default: 2)

Decimal places applied to `FLOAT`/`DOUBLE` values when a client write is published to MQTT.

**MIN\_VALUE** `double`

Minimum value after a client write. Values below this are clamped.

**MAX\_VALUE** `double`

Maximum value after a client write. Values above this are clamped.

**PERSISTENCE** `boolean`

Per-tag override of the connector persistence default. Precedence: tag → mapping → connector. See [Data persistence & recovery](#data-persistence--recovery).

### Supported data types

Use the same `DATA_TYPE` values as the [OPC UA client connector](./opcua-client)—for example `BOOLEAN`, `INT32`, `FLOAT`, `DOUBLE`, and `STRING`. Tags can also expose one-dimensional **arrays** or **struct objects**—see [Array and struct nodes](#array--struct-nodes). For statically defined scalar tags, set `DATA_TYPE` explicitly. Dynamic nodes infer type from the first MQTT payload (see below).

> [!NOTE]
>
> **String sizing:** `STRING` nodes are natively variable-length in OPC UA. The `OPCUA_SERVER` connector does not accept `LENGTH` or `STRING_SIZE`—there is no string-size parameter for scalar string tags. For array tags, `ARRAY_SIZE` sets the **node dimension** only (how many elements the array node exposes), not a string buffer width.

***

## Dynamic Topic Handling

Wildcard mappings let you expose many MQTT topics without listing each one as an `ADD TAG`. When a topic matches the pattern for the first time, the connector creates a new OPC UA node automatically.

### How it works

1. Define a mapping with a wildcard `SOURCE_TOPIC`—for example `sensors/+/value` or `plant/#`.
2. Do **not** add `ADD TAG` entries under that mapping. The wildcard pattern alone drives node creation.
3. On the **first publish** to a matching topic, the connector creates an OPC UA node and sets its value from the payload.
4. Later publishes to the same topic update that node. High-frequency updates use an equality check so unchanged values do not spam change notifications.

Dynamic nodes are **read-only**. OPC UA clients cannot write them back to MQTT. Use static `ADD TAG` definitions with `WRITABLE true` when you need bidirectional control.

### Topic → node mapping

The NodeId string identifier mirrors the full MQTT topic path:

| MQTT topic (first publish) | OPC UA NodeId |
| - | - |
| `sensors/press1/value` | `ns=2;s=sensors/press1/value` |
| `sensors/tank2/value` | `ns=2;s=sensors/tank2/value` |
| `plant/line3/motor/rpm` | `ns=2;s=plant/line3/motor/rpm` |

Under `Objects`, folder nodes are created from topic segments so clients can browse a hierarchy that matches your MQTT layout—for example `sensors` → `press1` → `value`.

### Supported wildcards

| Pattern | Matches | Example |
| - | - | - |
| `+` (single level) | Exactly one topic segment | `sensors/+/value` matches `sensors/press1/value` but not `sensors/line1/temp/value` |
| `#` (multi-level) | Zero or more segments at the end | `plant/#` matches `plant/line1/temp` and `plant/line1/motor/rpm` |

> [!NOTE]
>
> Combine static and dynamic mappings in the same connector. Static `ADD TAG` entries under a non-wildcard `SOURCE_TOPIC` behave as fixed nodes; wildcard mappings handle everything else that matches.

### Type inference

Dynamic nodes have no `DATA_TYPE` in the connector definition. The broker infers the OPC UA type from the **first** payload and locks it for the lifetime of that node:

| First MQTT payload | Inferred OPC UA type |
| - | - |
| Numeric (`42`, `23.5`) | `Double` |
| `true` or `false` (case-insensitive) | `Boolean` |
| Anything else | `String` |

If a later publish cannot be converted to the pinned type, the node keeps its previous value and the broker logs an error. Publish a representative value first—do not send a placeholder string if you expect numeric updates later.

### Example

This mapping exposes every `sensors/<device>/value` topic as it appears on the bus:

```lot wrap focus={4-5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorGateway WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
    ADD MAPPING Sensors
        WITH SOURCE_TOPIC "sensors/+/value"
```

**Sequence:**

1. Connector starts; no dynamic nodes exist yet.
2. Device publishes `45.2` to `sensors/press1/value` → node `ns=2;s=sensors/press1/value` appears with value `45.2` (`Double`).
3. Device publishes `false` to `sensors/alarm1/value` → node `ns=2;s=sensors/alarm1/value` appears with value `false` (`Boolean`).
4. UaExpert refresh shows both nodes under the `sensors` folder. Further publishes update values in place.

Retained messages already on the broker when the connector starts are seeded the same way as for static tags—matching topics create nodes at startup.

### Dynamic node limits

> [!WARNING]
>
> Dynamic nodes are not removed while the connector is running. They persist until the connector is removed or the broker restarts. Plan wildcard patterns carefully in high-churn environments where topic names change frequently.

***

## Array & Struct Nodes

Scalar tags expose one value per node. Use an **array** tag when MQTT carries a list of values on one topic, or a **struct** tag when the payload is a JSON object with named fields. OPC UA clients then browse and write the same shape—no extra config block beyond the tag settings below.

### Array tags

An array tag turns a JSON list on MQTT into a single OPC UA array node. Publish a list; the client sees one node with multiple elements. With `WRITABLE true`, a client edit publishes the full list back to the same topic, retained.

**DATA\_TYPE** `string`

Set to `"ARRAY"` for list values.

**ARRAY\_ELEMENT\_TYPE** `string` (default: INT16)

Type of each element: `BOOL`, `INT16`, `UINT16`, `INT32`, `UINT32`, `INT64`, `UINT64`, `FLOAT`, `DOUBLE`, or `STRING`.

**ARRAY\_SIZE** `integer`

Number of elements in the array. Set this to match your payload length. If omitted, the dimension is unspecified.

Define the tag, then publish a JSON array to `{SOURCE_TOPIC}/{TagName}`:

```lot wrap focus={4-10} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
    ADD MAPPING Line1
        WITH SOURCE_TOPIC "factory/line1"
        ADD TAG Levels
            WITH DATA_TYPE "ARRAY"
            WITH ARRAY_ELEMENT_TYPE "DOUBLE"
            WITH ARRAY_SIZE 3
            WITH WRITABLE true
```

**What happens:**

* Publish `[1.5, 2.5, 3.5]` to `factory/line1/Levels` → node `ns=2;s=PlantServer/Levels` shows three values.
* Payloads wrapped as `{"value": [1.5, 2.5, 3.5]}` are accepted—the broker unwraps the list automatically.
* A client write to the array node publishes the updated list back to `factory/line1/Levels`.

### Struct tags

A struct tag maps a JSON object to a folder-like node with one child per field. Field names in MQTT must match the names you declare in `STRUCT_FIELD_DEFINITIONS`.

**DATA\_TYPE** `string`

Set to `"STRUCT"` for object payloads.

**STRUCT\_FIELD\_DEFINITIONS** `string`

Comma-separated field list in `name:type` form—for example `bRunning:BOOL,iRpm:INT,sState:STRING`. If you reuse a definition from an ADS or EtherNet/IP connector (`name:offset:type:size`), the server uses the name and type only; offset and size are ignored.

```lot wrap focus={4-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
    ADD MAPPING Line1
        WITH SOURCE_TOPIC "factory/line1"
        ADD TAG Motor
            WITH DATA_TYPE "STRUCT"
            WITH WRITABLE true
            WITH STRUCT_FIELD_DEFINITIONS "bRunning:BOOL,iRpm:INT,sState:STRING"
```

**What happens:**

* Publish `{"bRunning": true, "iRpm": 1450, "sState": "RUN"}` to `factory/line1/Motor` → clients see `Motor.bRunning`, `Motor.iRpm`, and `Motor.sState` under the struct node.
* With `WRITABLE true`, a client writing one field to OPC-UA (for example `1600` to `Motor.iRpm`) merges into the current struct and publishes the **full** object back to MQTT `factory/line1/Motor`—for example `{"bRunning": true, "iRpm": 1600, "sState": "RUN"}`.
* Fields that were never set by MQTT and were not written by the client are left out of that publish.

> [!NOTE]
>
> `DECIMAL_PLACES`, `MIN_VALUE`, and `MAX_VALUE` apply to scalar writable tags only—not to individual struct fields.

***

## Security Examples

**Anonymous (development)**

For lab or trusted networks where encryption is not required:

```lot wrap focus={3-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DevServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH ALLOW_ANONYMOUS true
    ADD MAPPING Demo
        WITH SOURCE_TOPIC "demo/tags"
        ADD TAG Value
            WITH DATA_TYPE "FLOAT"
```

**Username and encryption**

Require credentials and encrypt traffic:

```lot wrap focus={4-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProdServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH USE_SECURITY true
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH ALLOW_ANONYMOUS false
        WITH USERNAME GET ENV "OPCUA_USER"
        WITH PASSWORD GET SECRET "OPCUA_PASSWORD"
    ADD MAPPING Tags
        WITH SOURCE_TOPIC "plant/tags"
        ADD TAG Setpoint
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
```

**Certificate user auth**

Accept X.509 certificates for client login:

```lot wrap focus={4-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CertServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH USE_SECURITY true
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH ALLOW_ANONYMOUS false
        WITH ALLOW_CERTIFICATE_AUTH true
        WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES false
    ADD MAPPING Tags
        WITH SOURCE_TOPIC "plant/tags"
        ADD TAG Status
            WITH DATA_TYPE "INT32"
```

***

## Certificate Management

A secured OPC UA server connection requires **two certificates that trust each other**: the broker's **application instance certificate** (identifies and secures the server) and each **client's certificate** (must be in the server's `trusted` store when using certificate authentication). For client-side trust workflows when the broker dials out to remote servers, see [OPC UA Client](./opcua-client#certificate-management).

### PKI directory layout

Both client and server connectors store certificates in four folders under `PKI_DIR`:

| Folder | Holds | File form |
| - | - | - |
| `own` | This server's certificate (`own/certs`) and private key (`own/private`) | `*.der` + `*.pfx` |
| `issuer` | Trusted CA / issuer certificates for chain validation | `*.der` |
| `trusted` | Trusted client certificates (`trusted/certs`) | `*.der` |
| `rejected` | Client certificates seen during a handshake but not yet trusted | `*.der` |

### Where certificates live

When `PKI_DIR` is not set, it defaults to `%LocalApplicationData%/OPC Foundation/pki`:

| OS | Default path |
| - | - |
| macOS | `~/Library/Application Support/OPC Foundation/pki` |
| Linux | `$XDG_DATA_HOME/OPC Foundation/pki` or `~/.local/share/OPC Foundation/pki` |
| Windows | `%LOCALAPPDATA%\OPC Foundation\pki` |

Relocate the store to a path you control and mount it as a volume in Docker:

```lot wrap focus={4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD OPCUA_SERVER_CONFIG
    WITH SERVER_PORT 4840
    WITH PKI_DIR "/data/opcua/pki"
```

> [!WARNING]
>
> In Docker, the default PKI location is ephemeral—the broker regenerates its certificate on every restart and clients that trusted the previous one will reject the new one. **Always set `PKI_DIR` to a mounted volume.**

### Inspecting and exporting certificates

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# The server's own certificate and private key
ls "$PKI_DIR"/own/certs/*.der
ls "$PKI_DIR"/own/private/*.pfx

# Inspect subject, validity, and application URI SAN
openssl x509 -inform der -in "$PKI_DIR"/own/certs/<name>.der -noout -subject -dates -ext subjectAltName

# Export public cert for clients to trust
openssl x509 -inform der -in "$PKI_DIR"/own/certs/<name>.der -out server-public.pem
```

Give clients the **public** certificate (`own/certs/*.der`). The private key never leaves the broker.

### The server's own certificate

On first start the broker auto-generates a self-signed server certificate (`CN={APPLICATION_NAME}, O=Coreflux`; default `APPLICATION_NAME` is `CorefluxBroker_OpcUaServer`) in `PKI_DIR/own`. Its SAN URI matches `APPLICATION_URI` (default `urn:{host}:Coreflux:{connector}`):

```lot wrap focus={4-8} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH APPLICATION_NAME "AcmePlantServer"
        WITH APPLICATION_URI "urn:acme:opcua:plant-server"
        WITH SECURITY_POLICY 3
        WITH MESSAGE_SECURITY 2
        WITH PKI_DIR "/data/opcua/pki"
```

* **Keep `APPLICATION_URI` and the certificate SAN in sync.** Strict clients refuse the handshake on a mismatch; changing `APPLICATION_URI` regenerates the certificate to match.
* Clients trust this server by adding `PKI_DIR/own/certs/<name>.der` to their trusted list—the same workflow as [trusting a server certificate on the client connector](./opcua-client#trust-the-servers-certificate).

### Enable certificate user authentication

Offer the X.509 user token so clients authenticate with a certificate instead of—or alongside—username and password:

```lot wrap focus={6-7} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CertServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH USE_SECURITY true
        WITH ALLOW_ANONYMOUS false
        WITH ALLOW_CERTIFICATE_AUTH true
```

When `ALLOW_CERTIFICATE_AUTH true`, the application instance certificate doubles as the user identity—the client's certificate must be trusted and must carry a valid application URI SAN.

### Trust connecting client certificates

When a client connects with certificate authentication, its certificate must be in the server's trusted store:

**1. First connect**

The client's certificate lands in `PKI_DIR/rejected/certs`.

**2. Move to trusted**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mv "$PKI_DIR"/rejected/certs/<client-cert>.der "$PKI_DIR"/trusted/certs/
```

**3. Reconnect**

The client connects successfully.

For testing only, set `WITH AUTO_ACCEPT_UNTRUSTED_CERTIFICATES true` to auto-trust every connecting client certificate.

### Supply your own server certificate

The server connector has no `CLIENT_CERT_PATH`-style parameter. To run with a CA-issued certificate instead of the auto-generated one, place it in the `own` store **before first start**, with a subject matching `CN={APPLICATION_NAME}, O=Coreflux` and a SAN URI matching `APPLICATION_URI`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mkdir -p "$PKI_DIR"/own/certs "$PKI_DIR"/own/private
openssl x509 -in server-cert.pem -outform der -out "$PKI_DIR"/own/certs/server.der
openssl pkcs12 -export -inkey server-key.pem -in server-cert.pem \
  -out "$PKI_DIR"/own/private/server.pfx -passout pass:
```

If a valid matching certificate is already present, the broker uses it instead of generating one.

### Rotation and renewal

* **Auto-generated certificates** — Delete files in `PKI_DIR/own/certs` and `PKI_DIR/own/private`, then restart the connector; the broker regenerates.
* **Changing `APPLICATION_URI`** — Regenerates the certificate; re-trust it on every client.
* Plan rotation **before expiry**—an expired application instance certificate fails the handshake on both ends.

***

## Data Persistence & Recovery

By default a server connector holds node values **in memory only**—a broker restart resets them (nodes return to `BadWaitingForInitialData` until the next publish). Set `WITH PERSISTENCE true` on `OPCUA_SERVER_CONFIG` to snapshot served values and restore them on startup.

```lot wrap focus={3-12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH PERSISTENCE true
    ADD MAPPING Nodes
        WITH SOURCE_TOPIC "plant/line1"
        ADD TAG Setpoint
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
        ADD TAG Temperature
            WITH DATA_TYPE "FLOAT"
```

The same **ownership-aware policy** as the [Modbus TCP Server](./modbus-tcp-server#data-persistence--recovery) connector applies:

| Node | Owner | Default | On restart |
| - | - | - | - |
| `WRITABLE true` | Client-written setpoint lives only in the server | **Persisted** | Restored **authoritatively**—wins over retained MQTT; returns a good value instead of `BadWaitingForInitialData` |
| Read-only / MQTT-fed | Fed from live MQTT | **Not persisted** | Recovered from **live MQTT** (retained message / next publish) |

Client-written setpoints survive a restart; live telemetry always reflects the current MQTT source.

### Per-tag and mapping overrides

`WITH PERSISTENCE true|false` on an individual `ADD TAG`—or a whole `ADD MAPPING`—overrides the connector default:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OverrideServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH PERSISTENCE true
    ADD MAPPING Control
        WITH SOURCE_TOPIC "plant/line1"
        ADD TAG Setpoint
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
        ADD TAG LastGoodTemp
            WITH DATA_TYPE "FLOAT"
            WITH PERSISTENCE "true"
    ADD MAPPING Scratch
        WITH SOURCE_TOPIC "plant/scratch"
        WITH PERSISTENCE "false"
        ADD TAG TestpointA
            WITH DATA_TYPE "FLOAT"
            WITH WRITABLE true
        ADD TAG TestpointB
            WITH DATA_TYPE "INT32"
            WITH WRITABLE true
```

* `Setpoint` — restored authoritatively to the last client-written value.
* `LastGoodTemp` — served from snapshot until `plant/line1/LastGoodTemp` next publishes.
* `Scratch` mapping tags — never snapshotted; start cold on every restart.

### Caching slow or infrequently-updated sources

MQTT-fed nodes are not persisted by default. When a source updates infrequently—an hourly energy total, a shift-latched value—force-persist with `WITH PERSISTENCE "true"` so the last received value is re-served on cold start until the next live publish overrides it.

```lot wrap focus={6-12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MeterServer WITH TYPE OPCUA_SERVER
    ADD OPCUA_SERVER_CONFIG
        WITH SERVER_PORT 4840
        WITH PERSISTENCE true
    ADD MAPPING Meters
        WITH SOURCE_TOPIC "plant/energy"
        ADD TAG TotalEnergy
            WITH DATA_TYPE "DOUBLE"
            WITH PERSISTENCE "true"
        ADD TAG DailyPeak
            WITH DATA_TYPE "DOUBLE"
            WITH PERSISTENCE "true"
```

After a restart, a client browsing `TotalEnergy` or `DailyPeak` reads the last published value—a good value rather than `BadWaitingForInitialData`—until the next publish refreshes it.

> [!WARNING]
>
> Persistence applies only to **explicitly-declared** `ADD TAG` nodes. Wildcard/dynamic nodes created from MQTT topic patterns are not snapshotted—a slow source behind a wildcard mapping still starts cold.

### Storage & durability

* Values are written through a non-blocking background worker on every change (rapid updates coalesce to the latest value).
* The snapshot lives in an encrypted-at-rest database under the broker data directory.
* A snapshot is keyed to the connector's tag definitions by a fingerprint. If addresses or types change between runs, the stale snapshot is discarded rather than replayed into reshaped nodes.

***

## Verify Your Server

**1. Deploy the connector**

Add the connector definition to your broker and confirm connector status shows **Connected** (the endpoint is listening).

**2. Connect with an OPC UA client**

Use UaExpert or any OPC UA browser. Connect to `opc.tcp://<broker-host>:<SERVER_PORT>` (append `ENDPOINT_PATH` if configured). When using security, trust the server certificate—export it from `PKI_DIR/own/certs` or follow the trust workflow in [Certificate Management](#certificate-management).

**3. Confirm MQTT → node**

Publish a test value to a bound topic—for example `factory/line1/Temperature`. Refresh the client and confirm the node value updates.

**4. Confirm node → MQTT**

For a writable tag, write a value from the OPC UA client. Subscribe to the tag's `SOURCE_TOPIC` with MQTT Explorer or any MQTT client and confirm the retained publish arrives.

***

## Limitations

> [!WARNING]
>
> Each `OPCUA_SERVER` connector binds exclusively to its `SERVER_PORT`. A second connector on the same port fails to start and reports a red connector status.

***

## Troubleshooting

> **Connector status Red — failed to start server**
>
> * **Port in use** — Another process or server connector already uses `SERVER_PORT`. Choose a different port or stop the conflicting service.
> * **PKI directory not writable** — Ensure the broker can write to `PKI_DIR` (or the default PKI location).

> **Client rejects the server certificate on every reconnect**
>
> The application instance certificate regenerates when `PKI_DIR` is ephemeral—for example, an unmounted Docker volume. Mount `PKI_DIR` as a persistent volume so client trust stores remain valid across restarts.

> **Client certificate rejected**
>
> * **Client cert not trusted** — Move it from `PKI_DIR/rejected/certs` to `PKI_DIR/trusted/certs`, or set `AUTO_ACCEPT_UNTRUSTED_CERTIFICATES true` for testing only
> * **Client cert has no application URI SAN** — The connecting client must present a certificate with a valid URI in Subject Alternative Name

> **Strict client refuses the security handshake**
>
> `APPLICATION_URI` must match the certificate SAN URI. Leave both at their defaults, or change them together so they stay in sync.

> **Client write has no effect**
>
> * Confirm the tag has `WITH WRITABLE true`.
> * Subscribe to the tag's `SOURCE_TOPIC` and check for the retained publish after the write.
> * Verify `MIN_VALUE` / `MAX_VALUE` are not clamping the written value away from what you expect.

> **Client activity logging**
>
> The broker logs client activity for this connector in the broker log:
>
> * **Sessions** — client session create and close events.
> * **Accepted external writes** — writes accepted on tags and on individual STRUCT fields.
>
> Use these log lines to confirm which clients connected and which node writes reached MQTT.

> **Anonymous connection rejected**
>
> `ALLOW_ANONYMOUS` is `false`. Connect with the configured username and password, or use certificate authentication if enabled.

> **Node reads BadWaitingForInitialData**
>
> The `SOURCE_TOPIC` has not published yet (or no retained value). Publish the topic, enable connector persistence for client-written setpoints, or force-persist a slow MQTT-fed source with `WITH PERSISTENCE "true"`. See [Data persistence & recovery](#data-persistence--recovery).

***

## Best Practices

> **Persist PKI in production**
>
> Mount `PKI_DIR` as a persistent volume so server certificates survive broker restarts. Ephemeral storage regenerates the application instance certificate on every boot and breaks client trust stores. See [Certificate Management](#certificate-management).

> **Disable anonymous access**
>
> Set `ALLOW_ANONYMOUS false` on plant networks and require username/password or certificate authentication. Anonymous endpoints are appropriate for lab or isolated development only.

> **Reserve ports**
>
> Each server connector binds exclusively to its `SERVER_PORT`. Document which connector owns which port to avoid startup conflicts when adding connectors.

> **Use secrets for credentials**
>
> Prefer `GET ENV` and `GET SECRET` over literals in connector definitions. Never commit passwords or client credentials to version control.

> **Match security to the client**
>
> Align `SECURITY_POLICY` and `MESSAGE_SECURITY` with what your SCADA or HMI supports. If the client cannot negotiate encryption, enable `ALLOW_NO_SECURITY` for testing only—not in production.

> **Enable persistence for client-written setpoints**
>
> Set `WITH PERSISTENCE true` on `OPCUA_SERVER_CONFIG` so client-written values survive a broker restart instead of returning `BadWaitingForInitialData`. See [Data persistence & recovery](#data-persistence--recovery).

***

## Next Steps

> **[OPC UA Client Connector](./opcua-client)**
>
> Connect to remote OPC UA servers and poll device data into MQTT.

> **[Industrial Connectors Overview](./overview)**
>
> Compare protocols and choose the right industrial connector for your architecture.


# Industrial Connectors Overview
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/overview

Connect your Coreflux broker to PLCs, industrial controllers, and automation systems using industrial protocol connectors

## Why Industrial Connectors?

Bridge the gap between your PLCs and MQTT without custom middleware. Read sensor data, write setpoints, and integrate industrial equipment into your IoT pipeline—using a single, consistent configuration pattern across all supported protocols.

## Industrial Protocol Integration

Industrial connectors enable direct communication between your Coreflux MQTT broker and industrial automation equipment. Read data from PLCs, write setpoints, and bridge the gap between IT and OT systems - all through standardized LoT (Language of Things) syntax.

> [!TIP]
>
> **Like a translator at an international meeting.** Industrial connectors speak both PLC (Modbus, S7, OPC UA) and MQTT—so your broker can read sensor data and send commands without custom glue code.

## Supported Protocols

> **[Modbus TCP Client](./modbus-tcp-client)**
>
> Poll PLCs and industrial devices over Modbus TCP.

> **[Modbus Serial Client](./modbus-serial-client)**
>
> RS-232/RS-485 serial communication with Modbus RTU devices.

> **[Modbus TCP Server](./modbus-tcp-server)**
>
> Expose MQTT topics as Modbus registers and coils for SCADA and HMIs.

> **[Siemens S7](./siemens-s7)**
>
> Native S7 protocol for Siemens S7-200/300/400/1200/1500 PLCs.

> **[OPC UA Client](./opcua-client)**
>
> Connect to remote OPC UA servers and poll device data into MQTT.

> **[OPC UA Server](./opcua-server)**
>
> Expose MQTT topics as OPC UA nodes for SCADA and OT clients.

> **[ADS (Beckhoff)](./ads)**
>
> TwinCAT ADS protocol for Beckhoff PLCs with AutoDiscovery support.

> **[Allen-Bradley](./allen-bradley)**
>
> ControlLogix, CompactLogix, and other Rockwell Automation PLCs.

> **[EtherNet/IP](./ethernetip)**
>
> CIP-based communication for Allen-Bradley and compatible devices.

> **[FINS (Omron)](./fins)**
>
> Omron FINS protocol for CJ/CS/CP series PLCs.

> **[BACnet](./bacnet)**
>
> BACnet/IP for building automation controllers (ASHRAE 135) — HVAC, lighting, and metering.

***

## Protocol Comparison

| Protocol | Transport | Use Case | Vendor |
| - | - | - | - |
| Modbus TCP Client | TCP/IP | Poll remote Modbus devices | Multi-vendor |
| Modbus Serial Client | RS-232/485 | Legacy devices, long distances | Multi-vendor |
| Modbus TCP Server | TCP/IP | Expose MQTT to Modbus masters | Multi-vendor |
| Siemens S7 | TCP/IP | Siemens automation systems | Siemens |
| OPC UA Client | TCP/IP | Read from remote OPC UA servers | Multi-vendor |
| OPC UA Server | TCP/IP | Expose MQTT to SCADA/HMI clients | Multi-vendor |
| ADS | TCP/IP | Beckhoff TwinCAT systems | Beckhoff |
| Allen-Bradley | TCP/IP | Rockwell Automation | Rockwell |
| EtherNet/IP | TCP/IP | CIP devices, explicit messaging | Multi-vendor |
| FINS | TCP/UDP | Omron PLCs | Omron |
| BACnet | UDP (BACnet/IP) | Building automation (HVAC, lighting, metering) | Multi-vendor |

***

## Common Architecture

All industrial connectors share a common architecture with three key components:

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
graph LR
    subgraph broker [Coreflux Broker]
        Connector[Industrial Connector]
        Tags[TAG Definitions]
        Mapping[MAPPING Config]
    end
    
    subgraph plc [PLC / Controller]
        Registers[Registers/Variables]
    end
    
    subgraph mqtt [MQTT Topics]
        Pub[Published Data]
        Sub[Write Commands]
    end
    
    Connector --> Tags
    Tags --> Mapping
    Mapping -->|Poll| Registers
    Registers -->|Read| Pub
    Sub -->|Write| Registers
```

### 1. Connection Configuration

Each protocol has specific connection parameters:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD <PROTOCOL>_CONFIG
    WITH HOST "192.168.1.100"
    WITH PORT 502
    // Protocol-specific options...
```

### 2. MAPPING with Polling

**MAPPING Definition**

A **MAPPING** is a scheduled, continuous polling operation that automatically reads data from industrial devices (PLCs, Modbus devices, etc.) at regular intervals and publishes the values to MQTT topics.

* **Polls:** industrial device at regular intervals (`EVERY`)
* **Reads:** multiple data points (TAGs) in a single operation
* **Publishes:** each TAG value to its own MQTT topic

In LoT, you define a MAPPING like this:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MAPPING SensorGroup
    WITH EVERY 500 MILLISECONDS
    ADD TAG Temperature
        // TAG config...
    ADD TAG Pressure
        // TAG config...
```

#### Common MAPPING-level fields

These fields are available at the MAPPING level across all industrial protocols:

> **SOURCE\_TOPIC**
>
> **SOURCE\_TOPIC** `string`
>
> Base MQTT topic for publishing tag data. Each TAG publishes to `{SOURCE_TOPIC}/{TAG_NAME}`.

> **EVERY**
>
> **EVERY** `string` *required*
>
> Polling interval (e.g. `500 MILLISECONDS`, `1 SECOND`).

***

### 3. TAG Definitions

**TAG Definition**

A **TAG** is an individual data point within a MAPPING that represents a specific variable or register in an industrial device.

* **Identifies:** a specific memory address in the device
* **Transforms:** raw value using scaling, offset, and engineering units
* **Publishes:** to a dedicated MQTT topic
* **Monitors:** changes using deadband filtering

> **TAG capabilities**
>
> * **Data transformation:** Scaling, offset, min/max validation
> * **Change detection:** Deadband to filter noise
> * **Formatting:** Publish as JSON or raw value

In LoT, you define a TAG like this:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG Temperature
    WITH ADDRESS "100"
    WITH DATA_TYPE "FLOAT"
    WITH SOURCE_TOPIC "plc/temperature"
    WITH SCALING 0.1
    WITH UNIT "°C"
```

#### Common TAG Parameters

These parameters are available across all industrial protocols:

> **Addressing**
>
> **ADDRESS** `string` *required*
>
> Protocol-specific address (register number, variable path, NodeId, etc.).
>
> **ADDRESS\_TYPE** `string`
>
> Address type varies by protocol (e.g., HOLDING\_REGISTER, DATABLOCK, SYMBOL).

> **Data Types**
>
> **DATA\_TYPE** `string` *required*
>
> Data type for the value. Common types: `BOOL`, `INT16`, `UINT16`, `INT32`, `UINT32`, `FLOAT`, `DOUBLE`, `STRING`.
>
> **LENGTH** `integer`
>
> Maximum string size when `DATA_TYPE` is `STRING` on connectors that support configurable sizing. Units and defaults vary—see [String sizing by Connector](#string-sizing-by-connector). Preferred keyword; `STRING_SIZE` is accepted as an alias where sizing is supported.

> **Topics**
>
> **SOURCE\_TOPIC** `string`
>
> Topic where PLC values are published. Subscribe here to receive sensor data.
>
> **DESTINATION\_TOPIC** `string`
>
> Topic to send write commands. Publish a value here to write it to the PLC (requires WRITABLE true).

> **Value Transformation**
>
> **SCALING** `double`
>
> Multiplier applied to raw value. Formula: `published_value = (raw_value * SCALING) + OFFSET`. Default: 1.0.
>
> **OFFSET** `double`
>
> Value added after scaling. Default: 0.0.
>
> **DECIMAL\_PLACES** `integer`
>
> Number of decimal places in published value. Default: 2.

> **Filtering**
>
> **MIN\_VALUE** `double`
>
> Minimum allowed value. Values below this are filtered out.
>
> **MAX\_VALUE** `double`
>
> Maximum allowed value. Values above this are filtered out.
>
> **DEADBAND** `double`
>
> Minimum change required to publish a new value. Reduces network traffic for slowly changing values. Default: 0.0.

> **Publishing Options**
>
> **PUBLISH\_MODE** `string`
>
> Output format: `VALUE_ONLY` (just the value) or `JSON` (structured object with metadata). Default: VALUE\_ONLY.
>
> **UNIT** `string`
>
> Engineering unit for documentation and JSON output (e.g., °C, bar, RPM).
>
> **DESCRIPTION** `string`
>
> Human-readable description of the TAG.

> **Write Control**
>
> **WRITABLE** `boolean`
>
> Allow writing to this TAG via DESTINATION\_TOPIC. Default: false.

> **Byte Ordering**
>
> **BYTE\_ORDER** `string`
>
> Byte order for multi-byte values: `BIGENDIAN` or `LITTLEENDIAN`. Default: BIGENDIAN.
>
> **WORD\_ORDER** `string`
>
> Word order for 32-bit values: `BIGENDIAN` or `LITTLEENDIAN`. Default: BIGENDIAN.

### String sizing by Connector

When `DATA_TYPE` is `STRING`, connectors that support configurable sizing accept `WITH LENGTH` to declare how many bytes the tag occupies on the wire. Use `LENGTH` as the preferred keyword; `STRING_SIZE` is accepted as an alias where sizing is supported. OPC UA Server strings are natively variable-length (no sizing parameter); Allen-Bradley uses a fixed 88-byte CIP layout—`LENGTH`/`STRING_SIZE` do not resize it.

| Connector | Unit | Default | Constraint |
| - | - | - | - |
| Modbus Server | bytes, 2 bytes/register | 40 bytes | at most 246 bytes/123 registers |
| Modbus clients | bytes | 256 | consecutive registers |
| Siemens S7 | bytes including 2-byte header | 256 | — |
| EtherNet/IP | bytes | type-driven; 1 in join mode | separate join/array semantics |
| OPC UA client | bytes | 256 | — |
| OPC UA Server | natively variable | unbounded | no sizing parameter |
| ADS | bytes including length byte | read 256; write 80 | — |
| Allen-Bradley | fixed layout | 88-byte CIP STRING | sizing keywords do not resize |
| FINS | payload bytes plus 2-byte header | 256 | — |
| BACnet | bytes | 256 | `MAX_APDU` is unrelated |

See the protocol-specific connector guide for register math, validation limits, and complete examples.

***

### 4. SOURCE\_TOPIC Configuration

There are two ways to configure where TAG values are published. Use group-level when you want consistent topic structure across all TAGs in a MAPPING; use individual TAG when you need custom paths per sensor (e.g., different namespaces for temperature vs pressure).

**Group-level (Recommended)**

Define `SOURCE_TOPIC` at the MAPPING level. Each TAG automatically publishes to `{SOURCE_TOPIC}/{TAG_NAME}`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MAPPING ProductionLine
    WITH SOURCE_TOPIC "factory/line1"
    WITH EVERY 1 SECOND
    ADD TAG Temperature
        WITH ADDRESS "100"
        WITH DATA_TYPE "FLOAT"
    ADD TAG Pressure
        WITH ADDRESS "102"
        WITH DATA_TYPE "FLOAT"
```

**Result:** Temperature publishes to `factory/line1/Temperature`; Pressure publishes to `factory/line1/Pressure`.

**Individual TAG**

Define `SOURCE_TOPIC` at each TAG level for custom topic structure.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MAPPING ProductionLine
    WITH EVERY 1 SECOND
    ADD TAG Temperature
        WITH SOURCE_TOPIC "sensors/temp/line1"
        WITH ADDRESS "100"
        WITH DATA_TYPE "FLOAT"
    ADD TAG Pressure
        WITH SOURCE_TOPIC "sensors/pressure/line1"
        WITH ADDRESS "102"
        WITH DATA_TYPE "FLOAT"
```

**Result:** Temperature publishes to `sensors/temp/line1`; Pressure publishes to `sensors/pressure/line1`.

***

### 5. EVENT (On-Demand Operations)

Understanding on-demand operations in connectors.

**EVENT Definition**

An **EVENT** is an on-demand operation that waits for messages on an MQTT topic, executes a specific action when triggered, and publishes the results back to another MQTT topic.

Use EVENT when you need on-demand reads or writes (triggered by a message); use MAPPING for continuous polling. Syntax varies by protocol—see the protocol-specific docs (e.g., [Modbus TCP Client](./modbus-tcp-client#event-based-operations)) for details.

In LoT, you define an EVENT like this:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadOnDemand
    WITH SOURCE_TOPIC "plc/commands/read"
    WITH DESTINATION_TOPIC "plc/responses/read"
    WITH QUERY "<protocol_query>"
```

#### Common EVENT Parameters

These parameters are available across all industrial protocols for EVENT definitions:

> **SOURCE\_TOPIC**
>
> **SOURCE\_TOPIC** `string` *required*
>
> MQTT topic where the EVENT listens for trigger messages. Publish a message here to execute the operation.

> **DESTINATION\_TOPIC**
>
> **DESTINATION\_TOPIC** `string` *required*
>
> MQTT topic where the EVENT publishes the result of the operation.

> **QUERY**
>
> **QUERY** `string` *required*
>
> Protocol-specific specification of the operation (read or write) and its parameters. Uses LoT object syntax. See each protocol's documentation for supported operations.

### When to Use MAPPING vs EVENT

Use the right acquisition pattern for the job:

| | MAPPING (Cyclic) | EVENT (On-Demand) |
| - | - | - |
| **Trigger** | Automatic, on a timer (`WITH EVERY`) | Manual, via an MQTT message to SOURCE\_TOPIC |
| **Direction** | Reads from device, publishes to MQTT | Reads or writes on command, publishes result |
| **Best for** | Dashboards, alarms, continuous telemetry | Operator commands, diagnostics, recipe downloads |
| **Data volume** | Constant stream at defined interval | Only when requested |

> [!NOTE]
>
> Most real-world connectors combine both patterns: MAPPING for continuous monitoring and EVENT for on-demand operations within the same `DEFINE CONNECTOR`.

***

## Basic Example Pattern

### Cyclic Only

This minimal pattern works across all industrial protocols for continuous data acquisition:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MyPLCConnection WITH TYPE <PROTOCOL_TYPE>
    ADD <PROTOCOL>_CONFIG
        WITH HOST "192.168.1.100"
        // Connection parameters...
    
    ADD MAPPING CriticalSensors
        WITH EVERY 100 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/sensors/temperature"
        ADD TAG Pressure
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/sensors/pressure"
    
    ADD MAPPING SlowChangingData
        WITH EVERY 5 SECONDS
        ADD TAG ProductCount
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "INT32"
            WITH SOURCE_TOPIC "plc/production/count"
```

### Combined (Cyclic + On-Demand)

A production connector typically combines MAPPING for continuous monitoring with EVENT for on-demand operations. Publish a message to the EVENT's SOURCE\_TOPIC to trigger a one-shot read or write, and receive the result on the DESTINATION\_TOPIC:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MyPLCConnection WITH TYPE <PROTOCOL_TYPE>
    ADD <PROTOCOL>_CONFIG
        WITH HOST "192.168.1.100"
        // Connection parameters...
    
    // Continuous monitoring — polls every 500ms
    ADD MAPPING ProcessSensors
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/sensors/temperature"
        ADD TAG Pressure
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/sensors/pressure"
    
    // On-demand read — triggered by publishing to SOURCE_TOPIC
    ADD EVENT ReadRegister
        WITH SOURCE_TOPIC "plc/commands/read"
        WITH DESTINATION_TOPIC "plc/responses/read"
        WITH QUERY "{operation: READ, address: <protocol_specific_address>, data_type: FLOAT}"
    
    // On-demand write — triggered by publishing to SOURCE_TOPIC
    ADD EVENT WriteSetpoint
        WITH SOURCE_TOPIC "plc/commands/write"
        WITH DESTINATION_TOPIC "plc/responses/write"
        WITH QUERY "{operation: WRITE, address: <protocol_specific_address>, value: 0}"
```

***

## Advanced Example Pattern

When you need engineering-unit conversion, noise filtering, range validation, or bidirectional control, add transformation and publishing parameters to your TAGs. This pattern builds on the basic structure above to unlock the full power of industrial connectors.

### Scaled and Filtered Monitoring

Apply scaling and offset to convert raw PLC register values into meaningful engineering units, and use deadband to suppress noise:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AdvancedPLCConnection WITH TYPE <PROTOCOL_TYPE>
    ADD <PROTOCOL>_CONFIG
        WITH HOST "192.168.1.100"
        // Connection parameters...
    
    ADD MAPPING ProcessMonitoring
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/sensors/temperature"
            // Value transformation — raw 245 becomes (245 * 0.1) + (-40) = -15.5
            WITH SCALING 0.1
            WITH OFFSET -40
            WITH UNIT "°C"
            // Noise filtering — only publish when change exceeds 0.5
            WITH DEADBAND 0.5
            // Range validation — discard values outside physical limits
            WITH MIN_VALUE -20
            WITH MAX_VALUE 150
            // Precision — publish with 1 decimal place
            WITH DECIMAL_PLACES 1
            // Structured output — includes unit, description, and timestamp
            WITH PUBLISH_MODE "JSON"
        ADD TAG Pressure
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/sensors/pressure"
            WITH SCALING 0.01
            WITH UNIT "bar"
            WITH DEADBAND 0.1
```

### Writable Setpoints with Validation

Enable bidirectional control by marking TAGs as writable. Published values on the DESTINATION\_TOPIC are written to the PLC, with MIN/MAX enforcing safe limits:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
    ADD MAPPING Setpoints
        WITH EVERY 1 SECOND
        ADD TAG TemperatureSetpoint
            WITH ADDRESS "<protocol_specific_address>"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/setpoints/temperature"
            // Bidirectional — publish to DESTINATION_TOPIC to write a value
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "plc/setpoints/temperature/write"
            WITH UNIT "°C"
            // Safety limits — reject values outside the safe operating range
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
```

***

## Connection and Writes

### Connection status

Every OT connector reports one of these states:

* **Connected**: the device has answered. A route doesn't show Connected just because its socket is open.
* **Reconnecting**: reads keep failing with connection errors. The route drops the connection and rebuilds it with backoff (up to 30 s between attempts). The first successful read sets it back to Connected.

By default, 3 read cycles in a row that fail with a connection error move a route to Reconnecting. Data errors, such as an invalid address, don't change the state. A route restarted after `RECONNECT_MAX_ATTEMPTS` ran out starts retrying again.

| Connector | When it reports a lost device |
| - | - |
| [FINS](/latest/lot-language/routes/industrial/fins) | UDP: after 2 commands in a row get no reply after all `RETRIES`. TCP: when no attempt of a command is answered, the connection is closed and reopened. Connected only after the PLC answers a probe (UDP) or the node handshake succeeds (TCP). |
| [EtherNet/IP](/latest/lot-language/routes/industrial/ethernetip) | When the device doesn't reply within `READ_WRITE_TIMEOUT` or closes the connection. |
| [Allen-Bradley](/latest/lot-language/routes/industrial/allen-bradley) | When a read or write outlives the safety timeout: 2 × `TIMEOUT` plus a margin. |
| [BACnet](/latest/lot-language/routes/industrial/bacnet) | Default rule (3 failures). Only failures on the current connection count. |
| [Siemens S7](/latest/lot-language/routes/industrial/siemens-s7) | When the connect doesn't finish within `READ_TIMEOUT`, or a read fails with "Plc is not connected". Connected only once the PLC has answered. |
| [ADS](/latest/lot-language/routes/industrial/ads) | When a request times out or fails with an ADS error that means the PLC is unreachable (for example timeout, or target port or machine not found). |
| [OPC UA client](/latest/lot-language/routes/industrial/opcua-client) | A read interrupted by a reconnect or certificate rotation marks the tags BAD and backs off like a lost connection. |
| [Modbus TCP client](/latest/lot-language/routes/industrial/modbus-tcp-client) | When the connection stops answering altogether, it is closed and reopened. A slow read fails and the connection stays open. |
| Other OT connectors | Default rule. |

### Write results

A write to a writable tag with a `DESTINATION_TOPIC` publishes its result on `{DESTINATION_TOPIC}/result`:

| Case | Payload |
| - | - |
| Written | `{"success": true, "route_name", "tag", "address", "value", "timestamp"}` |
| Failed | `{"success": false, "route_name", "error", "timestamp"}`, plus `cip_status` on EtherNet/IP CIP errors |
| Outcome unknown | `{"success": false, "outcome": "unknown", "route_name", "tag", "address", "error", "timestamp"}` |

`"outcome": "unknown"` means the device didn't answer in time but may still apply the write. `success` stays `false`, so existing flows still treat the write as unconfirmed. Read the tag back before you retry, or the value may be written twice.

| Connector | Publishes `outcome: "unknown"` |
| - | - |
| Allen-Bradley | Yes, when a write outlives the safety timeout |
| FINS, EtherNet/IP, ADS, BACnet, Siemens S7, others | Not yet. A timed-out write is reported as a plain failure. |

***

## Best Practices

> **Optimize Polling Intervals**
>
> Group TAGs by update frequency:
>
> * **Fast (50-100ms)**: Safety signals, real-time control
> * **Medium (500ms-1s)**: Process values, sensor readings
> * **Slow (5-30s)**: Configuration, counters, status
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> ADD MAPPING FastLoop
>     WITH EVERY 100 MILLISECONDS
>     // Critical TAGs only
>
> ADD MAPPING SlowLoop
>     WITH EVERY 5 SECONDS
>     // Non-critical TAGs
> ```

> **Use Deadband for Analog Values**
>
> Reduce network traffic for slowly changing values:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> ADD TAG Temperature
>     WITH DEADBAND 0.5  // Only publish if change > 0.5
> ```

> **Apply Scaling at the Edge**
>
> Transform raw PLC values to engineering units in the connector:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> ADD TAG Temperature
>     WITH SCALING 0.1   // Raw 245 becomes 24.5
>     WITH OFFSET -40    // Apply offset if needed
>     WITH UNIT "°C"
> ```

> **Use JSON Mode for Rich Data**
>
> Include metadata in published messages:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> ADD TAG Temperature
>     WITH PUBLISH_MODE "JSON"
>     WITH UNIT "°C"
>     WITH DESCRIPTION "Main reactor temperature"
> ```
>
> Output:
>
> ```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> {
>   "value": 24.5,
>   "unit": "°C",
>   "description": "Main reactor temperature",
>   "timestamp": "2024-01-15T10:30:00Z"
> }
> ```

> **Secure Write Operations**
>
> Only enable WRITABLE for TAGs that need it, and use specific topics:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> ADD TAG Setpoint
>     WITH WRITABLE "true"
>     WITH DESTINATION_TOPIC "plc/setpoints/temperature/write"
>     WITH MIN_VALUE 0
>     WITH MAX_VALUE 100
> ```

***

## Next Steps

Choose the protocol that matches your equipment:

> **[Modbus TCP Client](./modbus-tcp-client)**
>
> Start with the most common industrial protocol.

> **[Siemens S7](./siemens-s7)**
>
> Connect to Siemens PLCs directly.


# Siemens S7 Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/industrial/siemens-s7

Connect to Siemens S7-200, S7-300, S7-400, S7-1200, and S7-1500 PLCs using native S7 protocol

## Siemens S7 Overview

The `SIEMENS_S7` connector enables direct communication with Siemens S7 PLCs using the native S7 protocol (ISO-on-TCP). It supports all major S7 PLC families and provides access to data blocks, memory areas, inputs, outputs, timers, and counters.

> [!TIP]
>
> The S7 connector uses native protocol communication, which is typically faster and more efficient than OPC UA for Siemens PLCs.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiemensPLC WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71500"
        WITH RACK 0
        WITH SLOT 1
    ADD MAPPING ProcessData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "DB1.DBD100"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
```

***

## Supported CPU Types

| CPU Type | Parameter Value | Typical Slot | Description |
| - | - | - | - |
| S7-200 | `S7200` | 0 | Compact micro PLCs |
| S7-300 | `S7300` | 2 | Modular PLCs |
| S7-400 | `S7400` | 2/3 | High-performance PLCs |
| S7-1200 | `S71200` | 1 | Compact controllers |
| S7-1500 | `S71500` | 1 | Advanced controllers |

> [!NOTE]
>
> For S7-1200/1500 PLCs, you may need to enable "Permit access with PUT/GET" in the PLC's protection settings (Hardware Configuration → Protection & Security).

***

## Connection Configuration

### S7\_CONFIG Parameters

**IP** `string` *required*

S7 PLC IP address.

**CPU\_TYPE** `string` *required*

CPU type: `S7200`, `S7300`, `S7400`, `S71200`, or `S71500`.

**RACK** `integer`

PLC rack number. Default: 0.

**SLOT** `integer`

PLC slot number. Default: 1 for S7-1200/1500, 2 for S7-300/400.

**CONNECTION\_TYPE** `string`

Connection type: `PG` (Programming device), `OP` (Operator Panel), or `S7BASIC`. Default: PG.

**RETRY\_ATTEMPTS** `integer`

Number of retry attempts on failure. Default: 3.

**RETRY\_TIME\_SECONDS** `integer`

Seconds to wait between retries. Default: 5.

**REFRESH\_TIME\_MS** `integer`

Refresh time in milliseconds. Default: 1000.

**READ\_TIMEOUT** `integer`

Read timeout in milliseconds. Default: 5000. It also limits the connection attempt: a PLC that accepts TCP but doesn't answer within this time is reported as not connected, and the route retries. The PLC socket also uses `READ_TIMEOUT` and `WRITE_TIMEOUT`, not the library's 10 s default, so a PLC or gateway that is slow to accept connections needs a higher `READ_TIMEOUT`.

**WRITE\_TIMEOUT** `integer`

Write timeout in milliseconds. Default: 5000.

### Connection Examples

**S7-1500**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD S7_CONFIG
    WITH IP "192.168.1.100"
    WITH CPU_TYPE "S71500"
    WITH RACK 0
    WITH SLOT 1
    WITH CONNECTION_TYPE "PG"
```

**S7-1200**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD S7_CONFIG
    WITH IP "192.168.1.50"
    WITH CPU_TYPE "S71200"
    WITH RACK 0
    WITH SLOT 1
```

**S7-300**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD S7_CONFIG
    WITH IP "192.168.1.30"
    WITH CPU_TYPE "S7300"
    WITH RACK 0
    WITH SLOT 2
```

**S7-400**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD S7_CONFIG
    WITH IP "192.168.1.20"
    WITH CPU_TYPE "S7400"
    WITH RACK 0
    WITH SLOT 3
```

***

## S7 Addressing

### Address Format

S7 addresses follow the pattern: `<Area><Number>.<Offset>` or `<DB>.<Type><Offset>`

| Address | Description | Example |
| - | - | - |
| `DBn.DBXx.y` | Data Block bit | `DB1.DBX0.0` - DB1, byte 0, bit 0 |
| `DBn.DBBx` | Data Block byte | `DB1.DBB0` - DB1, byte 0 |
| `DBn.DBWx` | Data Block word (16-bit) | `DB1.DBW100` - DB1, word at byte 100 |
| `DBn.DBDx` | Data Block double word (32-bit) | `DB1.DBD100` - DB1, dword at byte 100 |
| `Mx.y` | Memory bit | `M0.0` - Marker byte 0, bit 0 |
| `MBx` | Memory byte | `MB0` - Marker byte 0 |
| `MWx` | Memory word | `MW100` - Marker word at byte 100 |
| `MDx` | Memory double word | `MD100` - Marker dword at byte 100 |
| `Ix.y` | Input bit | `I0.0` - Input byte 0, bit 0 |
| `IBx` | Input byte | `IB0` - Input byte 0 |
| `IWx` | Input word | `IW0` - Input word at byte 0 |
| `Qx.y` | Output bit | `Q0.0` - Output byte 0, bit 0 |
| `QBx` | Output byte | `QB0` - Output byte 0 |
| `QWx` | Output word | `QW0` - Output word at byte 0 |
| `Tx` | Timer | `T0` - Timer 0 |
| `Cx` | Counter | `C0` - Counter 0 |

### Address Types

**ADDRESS\_TYPE** `string`

Memory area type: `DATABLOCK`, `MEMORY`, `INPUT`, `OUTPUT`, `TIMER`, `COUNTER`.

> [!NOTE]
>
> For most configurations, the ADDRESS\_TYPE is inferred from the address format. Use explicit ADDRESS\_TYPE when needed for clarity.

***

## Data Types

| Data Type | S7 Type | Size | Description |
| - | - | - | - |
| `BOOL` / `BIT` | BOOL | 1 bit | Boolean value |
| `BYTE` | BYTE | 8 bits | Unsigned 8-bit |
| `SINT` | SINT | 8 bits | Signed 8-bit integer |
| `USINT` | USINT | 8 bits | Unsigned 8-bit integer |
| `WORD` | WORD | 16 bits | Unsigned 16-bit |
| `INT` / `INT16` | INT | 16 bits | Signed 16-bit integer |
| `UINT` / `UINT16` | UINT | 16 bits | Unsigned 16-bit integer |
| `DWORD` | DWORD | 32 bits | Unsigned 32-bit |
| `DINT` / `INT32` | DINT | 32 bits | Signed 32-bit integer |
| `UDINT` / `UINT32` | UDINT | 32 bits | Unsigned 32-bit integer |
| `LWORD` | LWORD | 64 bits | Unsigned 64-bit |
| `LINT` / `INT64` | LINT | 64 bits | Signed 64-bit integer |
| `ULINT` / `UINT64` | ULINT | 64 bits | Unsigned 64-bit integer |
| `REAL` / `FLOAT` | REAL | 32 bits | 32-bit floating point |
| `LREAL` / `DOUBLE` | LREAL | 64 bits | 64-bit floating point |
| `STRING` | STRING | Variable | S7 string type; sized with `LENGTH` (default 256 bytes, includes two-byte header) |
| `CHAR` | CHAR | 8 bits | Single character |
| `WCHAR` | WCHAR | 16 bits | Wide character |
| `TIME` | TIME | 32 bits | Time duration |
| `DATE` | DATE | 16 bits | Date value |
| `TOD` | TOD | 32 bits | Time of day |
| `DTL` / `DATETIME` / `DATE_AND_TIME` | DTL | 12 bytes | Date and time combined |

### String sizing

For `STRING` tags, `WITH LENGTH` is the **total allocated buffer in bytes** on the wire—the S7 two-byte maximum-length/current-length header **plus** the maximum character payload. It is **not** the character count alone. Default: **256** bytes. `STRING_SIZE` is accepted as an alias for the same field.

In TIA Portal, a `STRING[n]` variable occupies **n + 2** bytes (two header bytes plus **n** characters of capacity). Set `WITH LENGTH` to that combined total so the connector reads the full allocation from the starting byte address—for example, `STRING[254]` occupies 256 bytes, so use `WITH LENGTH 256`.

```lot wrap focus={13} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR S7Strings WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71500"
        WITH RACK 0
        WITH SLOT 1
    ADD MAPPING ProductData
        WITH EVERY 1 SECOND
        ADD TAG ProductName
            WITH ADDRESS "DB1.DBB300"
            WITH ADDRESS_TYPE "DATABLOCK"
            WITH DATA_TYPE "STRING"
            WITH LENGTH 64
            WITH SOURCE_TOPIC "plc/product/name"
```

For cross-protocol defaults and caps, see [String sizing by Connector](./overview#string-sizing-by-connector) on the industrial overview.

***

## TAG Configuration

### Complete TAG Example

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD TAG ProcessTemperature
    WITH ADDRESS "DB1.DBD100"
    WITH ADDRESS_TYPE "DATABLOCK"
    WITH DATA_TYPE "REAL"
    WITH SOURCE_TOPIC "plc/process/temperature"
    WITH SCALING 1
    WITH OFFSET 0
    WITH UNIT "°C"
    WITH DECIMAL_PLACES 2
    WITH MIN_VALUE -50
    WITH MAX_VALUE 200
    WITH DEADBAND 0.5
    WITH PUBLISH_MODE "JSON"
    WITH WRITABLE "true"
    WITH DESTINATION_TOPIC "plc/process/temperature/set"
    WITH BYTE_ORDER "BIGENDIAN"
    WITH DESCRIPTION "Main process temperature"
```

### TAG Parameters

> **Address Configuration**
>
> **ADDRESS** `string` *required*
>
> S7 address in standard notation (e.g., `DB1.DBW100`, `M0.0`, `I0.0`, `Q0.0`).
>
> **ADDRESS\_TYPE** `string`
>
> Address type: `DATABLOCK`, `MEMORY`, `INPUT`, `OUTPUT`, `TIMER`, `COUNTER`.
>
> **DATA\_TYPE** `string` *required*
>
> S7 data type: `BOOL`, `BYTE`, `WORD`, `DWORD`, `INT`, `DINT`, `REAL`, `STRING`.
>
> **LENGTH** `integer` (default: 256)
>
> **STRING only.** Total string buffer size in bytes, including the two-byte S7 header. Alias: `STRING_SIZE`.

> **Value Transformation**
>
> **SCALING** `double`
>
> Multiplier applied to raw value. Default: 1.0.
>
> **OFFSET** `double`
>
> Value added after scaling. Default: 0.0.
>
> **DECIMAL\_PLACES** `integer`
>
> Number of decimal places in output. Default: 2.

> **Filtering**
>
> **MIN\_VALUE** `double`
>
> Minimum allowed value.
>
> **MAX\_VALUE** `double`
>
> Maximum allowed value.
>
> **DEADBAND** `double`
>
> Minimum change to trigger publish. Default: 0.0.

> **Publishing**
>
> **SOURCE\_TOPIC** `string`
>
> Topic where PLC values are published. Subscribe here to receive sensor data.
>
> **PUBLISH\_MODE** `string`
>
> Output format: `VALUE_ONLY` or `JSON`. Default: VALUE\_ONLY.
>
> **UNIT** `string`
>
> Engineering unit (e.g., °C, bar, RPM).

> **Write Configuration**
>
> **WRITABLE** `boolean`
>
> Allow writing to this address. Default: false.
>
> **DESTINATION\_TOPIC** `string`
>
> Topic to send write commands. Publish a value here to write it to the PLC.

***

## Event-Based Operations

For on-demand S7 operations (not polling), use the EVENT syntax. Publish a message to SOURCE\_TOPIC to trigger the operation; the connector executes it and publishes the result to DESTINATION\_TOPIC.

### Supported Operations

| Operation | Description | Query Parameters |
| - | - | - |
| `READ` | Read data from a memory address | `address`, `data_type`, `count` |
| `WRITE` | Write a value to a memory address | `address`, `data_type`, `value` |

### Query Parameters

| Parameter | Description | Example |
| - | - | - |
| `operation` | Operation type: `READ` or `WRITE` | `READ` |
| `address` | S7 address in standard notation | `DB1.DBW0`, `MW100`, `I0.0` |
| `data_type` | S7 data type | `WORD`, `REAL`, `BOOL`, `DINT` |
| `count` | Number of consecutive values to read (READ only) | `10` |
| `value` | Value to write (WRITE only) | `42`, `23.5`, `true` |

### Read Example

Read 10 words from Data Block 1 on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT ReadOnDemand
    WITH SOURCE_TOPIC "s7/commands/read"
    WITH DESTINATION_TOPIC "s7/responses/read"
    WITH QUERY "{operation: READ, address: DB1.DBW0, data_type: WORD, count: 10}"
```

### Write Example

Write a REAL value to Data Block 10 on demand:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT WriteSetpoint
    WITH SOURCE_TOPIC "s7/commands/write"
    WITH DESTINATION_TOPIC "s7/responses/write"
    WITH QUERY "{operation: WRITE, address: DB10.DBD4, data_type: REAL, value: 75.0}"
```

***

## Complete Examples

**Basic Data Block Reading**

Read values from a data block:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionPLC WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71500"
        WITH RACK 0
        WITH SLOT 1
    ADD MAPPING ProductionData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "DB1.DBD0"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "DB1.DBD4"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/pressure"
            WITH UNIT "bar"
        ADD TAG Speed
            WITH ADDRESS "DB1.DBW8"
            WITH DATA_TYPE "INT"
            WITH SOURCE_TOPIC "plc/speed"
            WITH UNIT "RPM"
        ADD TAG Running
            WITH ADDRESS "DB1.DBX10.0"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/running"
```

**Memory and I/O**

Read markers, inputs, and outputs:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR IOMonitor WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71200"
        WITH RACK 0
        WITH SLOT 1
    ADD MAPPING DigitalIO
        WITH EVERY 100 MILLISECONDS
        ADD TAG StartButton
            WITH ADDRESS "I0.0"
            WITH ADDRESS_TYPE "INPUT"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/io/start"
        ADD TAG StopButton
            WITH ADDRESS "I0.1"
            WITH ADDRESS_TYPE "INPUT"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/io/stop"
        ADD TAG MotorRunning
            WITH ADDRESS "Q0.0"
            WITH ADDRESS_TYPE "OUTPUT"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/io/motor"
        ADD TAG SystemReady
            WITH ADDRESS "M0.0"
            WITH ADDRESS_TYPE "MEMORY"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/status/ready"
```

**Bidirectional Control**

Read process values and write setpoints:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ControlLoop WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71500"
        WITH RACK 0
        WITH SLOT 1
    ADD MAPPING ControlData
        WITH EVERY 200 MILLISECONDS
        ADD TAG ProcessValue
            WITH ADDRESS "DB10.DBD0"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/pv"
            WITH UNIT "°C"
            WITH PUBLISH_MODE "JSON"
        ADD TAG Setpoint
            WITH ADDRESS "DB10.DBD4"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/sp"
            WITH UNIT "°C"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/sp/set"
            WITH MIN_VALUE 0
            WITH MAX_VALUE 100
        ADD TAG Output
            WITH ADDRESS "DB10.DBD8"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "control/output"
            WITH UNIT "%"
        ADD TAG ManualMode
            WITH ADDRESS "DB10.DBX12.0"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "control/manual"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/manual/set"
```

**Multiple Polling Rates**

Optimize with different update frequencies:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OptimizedPLC WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71500"
        WITH RACK 0
        WITH SLOT 1
    
    ADD MAPPING FastLoop
        WITH EVERY 100 MILLISECONDS
        ADD TAG CriticalAlarm
            WITH ADDRESS "DB1.DBX0.0"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "plc/alarms/critical"
        ADD TAG MotorSpeed
            WITH ADDRESS "DB1.DBD10"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/motor/speed"
    
    ADD MAPPING MediumLoop
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "DB2.DBD0"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/process/temp"
        ADD TAG Pressure
            WITH ADDRESS "DB2.DBD4"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/process/pressure"
    
    ADD MAPPING SlowLoop
        WITH EVERY 10 SECONDS
        ADD TAG ProductionCount
            WITH ADDRESS "DB3.DBD0"
            WITH DATA_TYPE "DINT"
            WITH SOURCE_TOPIC "plc/production/count"
        ADD TAG RuntimeHours
            WITH ADDRESS "DB3.DBD4"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/stats/runtime"
```

**Combined (Cyclic + On-Demand)**

Continuous monitoring with on-demand read and write events in the same connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FullS7Setup WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71500"
        WITH RACK 0
        WITH SLOT 1
    
    ADD MAPPING ProcessData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "DB1.DBD0"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "DB1.DBD4"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/pressure"
            WITH UNIT "bar"
    
    ADD EVENT ReadBlock
        WITH SOURCE_TOPIC "s7/commands/read"
        WITH DESTINATION_TOPIC "s7/responses/read"
        WITH QUERY "{operation: READ, address: DB2.DBW0, data_type: WORD, count: 20}"
    
    ADD EVENT WriteSetpoint
        WITH SOURCE_TOPIC "s7/commands/write"
        WITH DESTINATION_TOPIC "s7/responses/write"
        WITH QUERY "{operation: WRITE, address: DB1.DBD8, data_type: REAL, value: 0}"
```

The MAPPING continuously reads temperature and pressure from DB1. To trigger an on-demand read of 20 words from DB2, publish any message to `s7/commands/read`. To write a setpoint, publish to `s7/commands/write`.

***

## S7-1200/1500 Setup

> [!WARNING]
>
> S7-1200 and S7-1500 PLCs require additional configuration to allow external access.

### Enable PUT/GET Access

1. Open TIA Portal project
2. Navigate to **Device Configuration** → **Properties**
3. Go to **Protection & Security** → **Connection mechanisms**
4. Enable **Permit access with PUT/GET communication from remote partner**

### Optimized Block Access

For S7-1500, ensure data blocks are set to allow standard access:

1. Open the Data Block in TIA Portal
2. In Properties, uncheck **Optimized block access**
3. Compile and download to PLC

***

## Troubleshooting

> **Connection Refused**
>
> * Verify IP address is correct
> * Check PLC is in RUN mode
> * For S7-1200/1500: Enable PUT/GET access
> * Verify correct RACK and SLOT settings
> * Check firewall allows TCP port 102

> **Wrong Slot Error**
>
> Use correct slot for your CPU:
>
> * S7-1200/1500: Slot 1
> * S7-300: Slot 2
> * S7-400: Slot 2 or 3 (check hardware config)

> **Optimized Block Access Error**
>
> For S7-1500: Disable optimized block access in TIA Portal for data blocks you want to access.

> **Incorrect Values**
>
> * Verify address matches TIA Portal
> * Check DATA\_TYPE corresponds to PLC variable type
> * For multi-word types, verify byte offset is correct
> * Check BYTE\_ORDER if values seem swapped

> **Write Fails**
>
> * Ensure WRITABLE is set to "true"
> * Verify PLC is in RUN mode
> * Check access permissions in PLC
> * Confirm value is within MIN\_VALUE/MAX\_VALUE

***

## Next Steps

> **[OPC UA Client](./opcua-client)**
>
> Cross-platform industrial communication.

> **[ADS (Beckhoff)](./ads)**
>
> Connect to TwinCAT systems.


# Email Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/notifications/email

Send templated email notifications and alerts from MQTT messages over SMTP

## Email Overview

The `EMAIL` connector sends templated emails in response to MQTT messages. It's the simplest way to turn a broker event — a critical alarm, a daily report, a user notification — into a message that reaches a person's inbox.

> [!TIP]
>
> **Like an auto-reply rule in your mailbox.** When a message lands on a topic you're watching, the connector fills in a template and sends the email for you — no manual step required.

### When to use it

* Alert an operations team the moment a critical alarm fires.
* Email a stakeholder a daily or shift report.
* Notify an individual user using an address pulled from the message payload.

***

Let's look at how to define an email connector, starting with the most common scenarios.

## Quick Start

**Critical alert**

Send an immediate alert to a fixed team address when a critical event arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CriticalAlerts WITH TYPE EMAIL
    ADD SMTP_CONFIG
        WITH HOST "smtp.gmail.com"
        WITH PORT '587'
        WITH USERNAME "alerts@company.com"
        WITH PASSWORD "app-password-here"
        WITH USE_TLS "true"
    ADD EVENT criticalNotify
        WITH SOURCE_TOPIC "alerts/critical/+"
        WITH TEMPLATE_PATH "/templates/critical_alert.html"
        WITH SUBJECT "CRITICAL: {value.json.alert_type}"
        WITH RECIPIENT "ops-team@company.com"
```

**Dynamic recipient**

Send to an address taken from the message payload:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR UserNotifications WITH TYPE EMAIL
    ADD SMTP_CONFIG
        WITH HOST "smtp.office365.com"
        WITH PORT '587'
        WITH USERNAME "noreply@company.com"
        WITH PASSWORD "secure-password"
        WITH USE_TLS "true"
    ADD EVENT userNotify
        WITH SOURCE_TOPIC "users/+/notifications"
        WITH TEMPLATE_PATH "/templates/user_notification.html"
        WITH SUBJECT "Hello {value.json.username}"
        WITH RECIPIENT "{value.json.email}"
```

**Report with images**

Embed images (a logo, a chart) directly in the email:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ReportEmail WITH TYPE EMAIL
    ADD SMTP_CONFIG
        WITH HOST "smtp.company.com"
        WITH PORT '587'
        WITH USERNAME "reports@company.com"
        WITH PASSWORD "password"
        WITH USE_TLS "true"
    ADD EVENT sendReport
        WITH SOURCE_TOPIC "reports/daily"
        WITH TEMPLATE_PATH "/templates/daily_report.html"
        WITH SUBJECT "Daily Report - {value.json.date}"
        WITH RECIPIENT "management@company.com"
        WITH EMBED_RESOURCES
            ADD "/images/logo.png"
            ADD "/images/chart.png"
```

> [!NOTE]
>
> For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833) instead of your regular password. Enable 2FA on your Google account first.

***

## SMTP Configuration

The `SMTP_CONFIG` block tells the connector which mail server to send through and how to authenticate.

> **Server Settings**
>
> **HOST** `string` *required*
>
> SMTP server address (e.g., `smtp.gmail.com`, `smtp.office365.com`).
>
> **PORT** `integer` *required*
>
> SMTP port (typically 587 for TLS, 465 for SSL).
>
> **USE\_TLS** `boolean`
>
> Enable TLS encryption. Recommended: true.

> **Authentication**
>
> **USERNAME** `string` *required*
>
> Email account to send from.
>
> **PASSWORD** `string` *required*
>
> Email password or app-specific password.

***

## Event Configuration

Each `ADD EVENT` block defines a trigger topic and the content of the email it sends.

> **Trigger & Routing**
>
> **SOURCE\_TOPIC** `string`
>
> MQTT topic to trigger email sending.
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to publish send status.

> **Email Content**
>
> **TEMPLATE\_PATH** `string`
>
> Path to HTML email template file.
>
> **SUBJECT** `string`
>
> Email subject line (supports placeholders).
>
> **RECIPIENT** `string`
>
> Email recipient address (supports placeholders).

### Template Placeholders

Subjects, recipients, and templates support placeholders that are filled in from the triggering message:

| Placeholder | Description |
| - | - |
| `{value}` | Full JSON payload as string |
| `{value.json.field}` | Single field from JSON |
| `{value.json.nested.field}` | Nested field access |

***

## Troubleshooting

> **Email Not Sending**
>
> * Verify SMTP credentials are correct
> * For Gmail, ensure you're using an App Password
> * Check firewall allows outbound SMTP connections
> * Verify recipient email address is valid

> **Email Authentication Failed**
>
> * Double-check USERNAME and PASSWORD
> * Ensure 2FA is enabled if using app passwords
> * Some providers require enabling "less secure apps" access
> * Check for account lockouts due to failed attempts

***

## Next Steps

> **[LoT Actions](../../actions/overview)**
>
> Publish the MQTT events that trigger notifications.

> **[Data Storage Connectors](../data-storage/overview)**
>
> Store MQTT data in databases.


# Connectors Overview
Source: https://docs.coreflux.org/latest/lot-language/routes/overview

Connect your Coreflux broker to external systems, databases, industrial equipment, and other brokers using Connectors

## What are Connectors?

Connectors define connections between your Coreflux MQTT broker and external systems. They enable broker-to-broker communication, database storage, industrial protocol integration, REST API connectivity, email notifications, AI integration, and media processing — all without writing custom middleware.

> [!NOTE]
>
> Write `DEFINE CONNECTOR` and deploy it with `-addConnector`. `DEFINE ROUTE` and `-addRoute` remain supported aliases, as do the other Route command spellings. The broker stores each definition exactly as you typed it. Overload settings use `ADD CONNECTOR_CONFIG`; `ADD ROUTE_CONFIG` remains a supported alias. Older brokers accept only `DEFINE ROUTE` and `-addRoute`. See [Connector command spellings](/latest/mqtt-broker/commands#connector-command-spellings).

> [!TIP]
>
> **Like plugging a cable into a device.** A Connector is the cable between your broker and an external system — a database, a PLC, or another broker.

![Architecture diagram showing the Coreflux MQTT broker at the center connected to databases, PLCs, REST APIs, cloud brokers, email, and AI through Connectors](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/product-overview-diagram.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=8e40e7ae59a9ca0254a45a115bc4f448)

Connectors connect your Coreflux MQTT broker to databases, industrial equipment, APIs, cloud services, and more

## Connector Categories

> **[System Connectors](./system-routes)**
>
> Configure MQTT bridges and Sparkplug roles.

> **[Streaming Connectors](./streaming/kafka)**
>
> Connect MQTT topics to Apache Kafka.

> **[gRPC Connectors](./streaming/grpc)**
>
> Call an external gRPC service from MQTT (`TYPE GRPC`), with one bidirectional call per device topic by default.

> **[Notification Connectors](./notifications/email)**
>
> Send alerts and reports to people from MQTT events.

> **[Data Storage Connectors](./data-storage/overview)**
>
> Store MQTT data in PostgreSQL, MySQL, MongoDB, OpenSearch, Snowflake, and more.

> **[REST API Connectors](./rest-api-routes)**
>
> HTTP client/server for external API integration and webhook endpoints.

> **[Industrial Connectors](./industrial/overview)**
>
> Connect to PLCs via Modbus, Siemens S7, OPC UA, ADS, Allen-Bradley, and FINS.

> **[MCP Connectors](./mcp-routes)**
>
> Connect *out* to external MCP servers (`TYPE MCP` / `CALL MCP`). To expose this broker as an MCP server, see [MCP Server](/latest/mqtt-broker/mcp-server).

> **[AI Connectors and Agents](./ai-routes)**
>
> Call a model with a TYPE LLM connector, or define an agent that uses it.

> **[Media Connectors](./media/overview)**
>
> Decode barcodes, capture camera frames, and publish microphone audio.

> **[Overload configuration](./store-and-forward)**
>
> Choose wait or drop when a connector cannot keep up with incoming MQTT.

This page covers the fundamentals of connector configuration. Choose a specific connector category above for detailed syntax and examples.

***

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR <connector_name> WITH TYPE <connector_type>
    ADD <CONFIG_SECTION>
        WITH <parameter> "<value>"
    ADD MAPPING <mapping_name>
        WITH SOURCE_TOPIC "<source>"
        WITH DESTINATION_TOPIC "<destination>"
```

### Components

**connector\_name** `string` *required*

Unique identifier for the connector. Use descriptive names like `CloudBridge`, `SensorDataIndexer`, `AlertEmailer`.

**connector\_type** `type` *required*

The type of connector (see Available Connector Types below).

**CONFIG\_SECTION** `block`

Configuration blocks specific to the connector type (e.g., `MQTT_CONFIG`, `MONGODB_CONFIG`, `REST_API_CONFIG`).

**CONNECTOR\_CONFIG** `block`

Optional. Controls wait-or-drop behavior when this connector cannot keep up with incoming MQTT. Works on every connector type. `ADD ROUTE_CONFIG` remains a supported alias. See [Store and Forward Configuration](./store-and-forward).

**MAPPING** `block`

Defines topic mappings for data flow between source and destination.

### Disable a connector

Add `DISABLE true` on its own line to keep a connector defined but stopped:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantHistorian WITH TYPE POSTGRESQL
    DISABLE true
    ADD SQL_CONFIG
        WITH SERVER "historian.plant.local"
```

A disabled connector stays listed and its definition is still published, but it isn't started. It opens no connection, maps no topics, and uses no action slots. `DISABLE false`, or no `DISABLE` line, means enabled. The state survives a restart.

To switch it without editing the code, use `-disableConnector <name>` and `-enableConnector <name>` (aliases `-disableRoute` / `-enableRoute`). `-disableConnector` refuses a `TYPE LLM` connector that agents still use: disable those agents first. See [Disable and enable](/latest/mqtt-broker/commands#disable-and-enable).

***

## Available Connector Types

**System**

| Connector Type | Description |
| - | - |
| `MQTT_BRIDGE` | Broker-to-broker topic synchronization |
| `SPARKPLUG_B` | Sparkplug decoding and edge-node publishing |
| `SPARKPLUG_HOST` | Sparkplug Primary Host Application |

**Streaming**

| Connector Type | Description |
| - | - |
| `KAFKA` | Stream data both ways with Apache Kafka |
| `GRPC` | Call an external gRPC service from MQTT topics (unary and streaming) |

**Notification**

| Connector Type | Description |
| - | - |
| `EMAIL` | Send templated emails from MQTT messages |

**Data Storage**

| Connector Type | Description |
| - | - |
| `POSTGRESQL` | PostgreSQL database storage |
| `MYSQL` | MySQL database storage |
| `MARIADB` | MariaDB database storage |
| `SQLSERVER` | SQL Server database storage |
| `MONGODB` | MongoDB document database |
| `OPENSEARCH` | OpenSearch indexing and search |
| `CRATEDB` | CrateDB time-series database |
| `SNOWFLAKE` | Snowflake cloud data warehouse |
| `FILE_STORAGE` | CSV/JSON file storage |

**Industrial**

| Connector Type | Description |
| - | - |
| `MODBUS_TCP` | Modbus TCP protocol |
| `MODBUS_SERIAL` | Modbus RTU over RS-232/485 |
| `SIEMENS_S7` | Siemens S7 PLCs |
| `OPCUA` | OPC UA client |
| `ADS` | Beckhoff TwinCAT ADS |
| `ALLEN_BRADLEY` | Allen-Bradley/Rockwell PLCs |
| `ETHERNETIP` | EtherNet/IP CIP protocol |
| `FINS` | Omron FINS protocol |

**Other**

| Connector Type | Description |
| - | - |
| `REST_API` | REST API client/server |
| `MQTT_TO_REST` | Forward MQTT messages to REST endpoints |
| `MCP` | Model Context Protocol for external tools |
| `AGENT` | Autonomous AI assistant with tool access |
| `BARCODE` | Barcode encoding and decoding |
| `VIDEO_INPUT` | JPEG capture from a camera, stream, or file |
| `VIDEO_OUTPUT` | HTTP MJPEG from MQTT frames |
| `AUDIO_INPUT` | Raw PCM capture from a microphone, tone, silence, or file |

***

## Quick Examples

**Email Alerts**

Send email notifications from MQTT events:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AlertEmail WITH TYPE EMAIL
    ADD SMTP_CONFIG
        WITH HOST "smtp.gmail.com"
        WITH PORT '587'
        WITH USERNAME "alerts@company.com"
        WITH PASSWORD "app-password"
        WITH USE_TLS "true"
    ADD EVENT criticalAlert
        WITH SOURCE_TOPIC "alerts/critical/+"
        WITH SUBJECT "Critical Alert: {value.json.type}"
        WITH RECIPIENT "team@company.com"
```

**Modbus TCP**

Read data from PLCs via Modbus:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlcReader WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT '502'
        WITH SLAVE_ID '1'
    ADD MAPPING Sensors
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/temperature"
```

**REST API**

Connect to external REST APIs:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WeatherService WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_CLIENT "true"
        WITH BASE_ADDRESS "https://api.weather.com"
        WITH USE_SSL "true"
    ADD EVENT GetWeather
        WITH SOURCE_TOPIC "weather/request"
        WITH DESTINATION_TOPIC "weather/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/current?city={value.json.city}"
```

**PostgreSQL Storage**

Store MQTT data in PostgreSQL:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "postgres.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_user"
        WITH PASSWORD "secure_password"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO readings (ts, sensor, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
```

**MQTT Bridge**

Connect two brokers and sync topics:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CloudBridge WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "cloud.example.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "EdgeBridge"
        WITH USE_TLS "true"
    ADD MAPPING sensorSync
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH DESTINATION_TOPIC "edge/sensors/+/data"
        WITH DIRECTION "out"
```

***

## Understanding Connector Configuration

Connectors share two common building blocks: **MQTT configuration** and **topic mappings**. You'll see these across most connector types, so understanding them here saves time when setting up any specific connector.

### Connecting to a Broker

Connectors that communicate with MQTT brokers — like bridges — need to know which broker to talk to. The simplest option is `BROKER SELF`, which tells the connector to use your local Coreflux broker:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MQTT_CONFIG
    WITH BROKER SELF
```

When you need to reach a **remote** or **authenticated** broker (for example, a cloud broker or a second Coreflux instance on your network), provide the connection details explicitly:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MQTT_CONFIG
    WITH BROKER_ADDRESS "192.168.1.50"
    WITH BROKER_PORT '1883'
    WITH CLIENT_ID "MyRouteClient"
    WITH USERNAME "user"
    WITH PASSWORD "password"
```

> [!NOTE]
>
> Not every connector type requires an `MQTT_CONFIG` block. Database connectors, email connectors, and REST connectors have their own configuration sections. Check the specific connector page for details.

### Controlling Data Flow with Mappings

Mappings define **which MQTT topics** flow through a connector and **in which direction**. For example, to push local sensor readings to a cloud broker:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD MAPPING sensorSync
    WITH SOURCE_TOPIC "sensors/+/temperature"
    WITH DESTINATION_TOPIC "cloud/sensors/+/temperature"
    WITH DIRECTION "out"
```

The `DIRECTION` parameter controls where data goes:

| Direction | What it does | Example scenario |
| - | - | - |
| `out` | Local broker to destination | Push edge data to the cloud |
| `in` | Destination to local broker | Pull remote commands locally |
| `both` | Bidirectional sync | Keep two brokers in sync |

### When a connector cannot keep up

Incoming MQTT can outpace the destination. Add `ADD CONNECTOR_CONFIG` on any connector to choose whether that connector waits or drops the newest message (`ADD ROUTE_CONFIG` remains a supported alias). Connectors without the block use the broker default (`balanced`). See [Store and Forward Configuration](./store-and-forward).

***

## Connector Status Monitoring

Every connector automatically publishes real-time health and status information to a dedicated MQTT topic. No additional configuration is required — the status topic is created as soon as the connector is defined.

> [!NOTE]
>
> Status updates are published to a `$SYS` topic and are available to any client subscribed to the broker.

### Status Topic

The topic follows this pattern:

```
$SYS/Coreflux/Routes/<connector_name>/status
```

For example, a connector named `MyS7Route` publishes its status to `$SYS/Coreflux/Routes/MyS7Route/status`.

### Status Payload

The status topic publishes a JSON object with connection health, message statistics, and timing information:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "name": "MyS7Route",
  "type": "SIEMENS_S7",
  "connection": "Connected",
  "health": "Green",
  "errors": {
    "total": 0,
    "consecutive": 0,
    "rate": 0
  },
  "messages": {
    "total": 4749,
    "succeeded": 4749,
    "failed": 0
  },
  "lastActivity": "2026-03-03T15:03:14.563Z",
  "lastSuccess": "2026-03-03T15:03:14.563Z",
  "lastError": null,
  "uptime": "00:08:01",
  "connectedSince": "2026-03-03T14:55:13.299Z",
  "timestamp": "2026-03-03T15:03:14.590Z"
}
```

### Field Reference

| Field | Type | Description |
| - | - | - |
| `name` | string | The connector name as defined in LoT |
| `type` | string | The connector type (e.g., `SIEMENS_S7`, `MQTT_BRIDGE`, `POSTGRESQL`) |
| `connection` | string | Current connection state (`Connected`, `Disconnected`, etc.) |
| `health` | string | Overall health indicator (`Green`, `Yellow`, `Red`) |
| `errors.total` | integer | Total number of errors since the connector started |
| `errors.consecutive` | integer | Number of consecutive errors without a successful message |
| `errors.rate` | number | Current error rate |
| `messages.total` | integer | Total messages processed |
| `messages.succeeded` | integer | Messages processed successfully |
| `messages.failed` | integer | Messages that failed processing |
| `lastActivity` | string | ISO 8601 timestamp of the last message (success or failure) |
| `lastSuccess` | string | ISO 8601 timestamp of the last successful message |
| `lastError` | string \| null | ISO 8601 timestamp of the last error, or `null` if no errors occurred |
| `uptime` | string | Time the connector has been running (`HH:MM:SS`) |
| `connectedSince` | string | ISO 8601 timestamp of when the connector established its current connection |
| `timestamp` | string | ISO 8601 timestamp of when this status update was generated |

### Checking Connector Status

You can monitor any connector's health by subscribing to its status topic. Use MQTT Explorer or any MQTT client to subscribe:

```
$SYS/Coreflux/Routes/+/status
```

This wildcard subscription shows status updates for **all** active connectors at once.

***

## Use Cases

**Edge-to-Cloud Sync**

Bridge local edge data to cloud brokers:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EdgeToCloud WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloud-provider.com"
        WITH BROKER_PORT '8883'
        WITH USE_TLS "true"
    ADD MAPPING allSensors
        WITH SOURCE_TOPIC "local/sensors/#"
        WITH DESTINATION_TOPIC "edge-01/sensors/#"
        WITH DIRECTION "out"
```

**Industrial Integration**

Read data from PLCs via multiple protocols:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiemensPLC WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.100"
        WITH CPU_TYPE "S71500"
        WITH RACK '0'
        WITH SLOT '1'
    ADD MAPPING ProcessData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "DB1.DBD0"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/temperature"
```

**Real-Time Analytics**

Store sensor data for analysis:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AnalyticsStore WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://analytics.example.com:9200"
        WITH USERNAME "admin"
        WITH PASSWORD "password"
        WITH USE_SSL "true"
    ADD EVENT IndexReading
        WITH SOURCE_TOPIC "sensors/#"
        WITH QUERY "CLEAN:{index: sensor-data, body: {timestamp: {timestamp}, value: {value.json}}}"
```

**Alert Notifications**

Email stakeholders when critical events occur:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CriticalAlerts WITH TYPE EMAIL
    ADD SMTP_CONFIG
        WITH HOST "smtp.office365.com"
        WITH PORT '587'
        WITH USE_TLS "true"
        WITH USERNAME "alerts@company.com"
        WITH PASSWORD "password"
    ADD EVENT notify
        WITH SOURCE_TOPIC "alarms/critical/+"
        WITH SUBJECT "CRITICAL: {value.json.alarm_type}"
        WITH RECIPIENT "ops-team@company.com"
```

## Next Steps

> **[Industrial Connectors](./industrial/overview)**
>
> Connect to PLCs and industrial equipment.

> **[Data Storage](./data-storage)**
>
> Store MQTT data in databases.


# Acumatica Cloud ERP REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/acumatica-cloud-erp

Client-mode REST API connector for Acumatica contract-based REST (Production Orders, Stock Items, Adjustments)

Technical Preview

## Overview

Client-mode REST API connector for Acumatica contract-based REST (Production Orders, Stock Items, Adjustments). `BASE_ADDRESS` defaults to `https://YOUR_ACUMATICA_HOST`. Auth: **Session cookie (POST /entity/auth/login) or OAuth 2.0 Bearer**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

Session cookie (POST /entity/auth/login) or OAuth 2.0 Bearer. Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR AcumaticaCloudErpRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ACUMATICA_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Authorization Bearer {value.json.access_token} — prefer Hub secrets / GET SECRET.
        # Optional Basic: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Login
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Login"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Login"
        WITH METHOD "POST"
        WITH ENDPOINT "/entity/auth/login"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Logout
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Logout"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Logout"
        WITH METHOD "POST"
        WITH ENDPOINT "/entity/auth/logout"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Listproductionorders
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Listproductionorders"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Listproductionorders"
        WITH METHOD "GET"
        WITH ENDPOINT "/entity/Default/24.200.001/ProductionOrder"
        WITH HEADERS
            ADD "Accept" "application/json"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/acumatica-cloud-erp/request/...`; responses on `integrations/acumatica-cloud-erp/response/...`.

## Template reference

Generated from the shipped broker template `acumatica-cloud-erp` (`-connectorCode ACUMATICA_CLOUD_ERP`). It lists every event the template defines.

### Auth

Session cookie (POST /entity/auth/login) or OAuth 2.0 Bearer

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Acumatica Cloud ERP connector | no |
| `BaseUrl` | string | Acumatica Cloud ERP base URL without trailing slash (e.g. https\://YOUR\_ACUMATICA\_HOST) | yes |

`BASE_ADDRESS` default: `https://YOUR_ACUMATICA_HOST`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Login` | POST | `/entity/auth/login` | `integrations/acumatica-cloud-erp/request/Login` | `integrations/acumatica-cloud-erp/response/Login` | `access_token`, `body` |
| `Logout` | POST | `/entity/auth/logout` | `integrations/acumatica-cloud-erp/request/Logout` | `integrations/acumatica-cloud-erp/response/Logout` | `access_token`, `body` |
| `Listproductionorders` | GET | `/entity/MANUFACTURING/24.200.001/ProductionOrder` | `integrations/acumatica-cloud-erp/request/Listproductionorders` | `integrations/acumatica-cloud-erp/response/Listproductionorders` | `access_token` |
| `Getproductionorder` | GET | `/entity/MANUFACTURING/24.200.001/ProductionOrder/{value.json.id}` | `integrations/acumatica-cloud-erp/request/Getproductionorder` | `integrations/acumatica-cloud-erp/response/Getproductionorder` | `access_token`, `id` |
| `Putmoveentry` | PUT | `/entity/MANUFACTURING/24.200.001/MoveEntry` | `integrations/acumatica-cloud-erp/request/Putmoveentry` | `integrations/acumatica-cloud-erp/response/Putmoveentry` | `access_token`, `body` |
| `Liststockitems` | GET | `/entity/Default/24.200.001/StockItem` | `integrations/acumatica-cloud-erp/request/Liststockitems` | `integrations/acumatica-cloud-erp/response/Liststockitems` | `access_token` |
| `Getstockitem` | GET | `/entity/Default/24.200.001/StockItem/{value.json.id}` | `integrations/acumatica-cloud-erp/request/Getstockitem` | `integrations/acumatica-cloud-erp/response/Getstockitem` | `access_token`, `id` |
| `Putinventoryadjustment` | PUT | `/entity/Default/24.200.001/InventoryAdjustment` | `integrations/acumatica-cloud-erp/request/Putinventoryadjustment` | `integrations/acumatica-cloud-erp/response/Putinventoryadjustment` | `access_token`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode ACUMATICA_CLOUD_ERP"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AcumaticaCloudErpRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ACUMATICA_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Login
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Login"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Login"
        WITH METHOD "POST"
        WITH ENDPOINT "/entity/auth/login"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Logout
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Logout"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Logout"
        WITH METHOD "POST"
        WITH ENDPOINT "/entity/auth/logout"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Listproductionorders
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Listproductionorders"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Listproductionorders"
        WITH METHOD "GET"
        WITH ENDPOINT "/entity/MANUFACTURING/24.200.001/ProductionOrder"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getproductionorder
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Getproductionorder"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Getproductionorder"
        WITH METHOD "GET"
        WITH ENDPOINT "/entity/MANUFACTURING/24.200.001/ProductionOrder/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Putmoveentry
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Putmoveentry"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Putmoveentry"
        WITH METHOD "PUT"
        WITH ENDPOINT "/entity/MANUFACTURING/24.200.001/MoveEntry"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Liststockitems
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Liststockitems"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Liststockitems"
        WITH METHOD "GET"
        WITH ENDPOINT "/entity/Default/24.200.001/StockItem"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getstockitem
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Getstockitem"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Getstockitem"
        WITH METHOD "GET"
        WITH ENDPOINT "/entity/Default/24.200.001/StockItem/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Putinventoryadjustment
        WITH SOURCE_TOPIC "integrations/acumatica-cloud-erp/request/Putinventoryadjustment"
        WITH DESTINATION_TOPIC "integrations/acumatica-cloud-erp/response/Putinventoryadjustment"
        WITH METHOD "PUT"
        WITH ENDPOINT "/entity/Default/24.200.001/InventoryAdjustment"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Login` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/acumatica-cloud-erp/response/Login' &
mosquitto_pub -t 'integrations/acumatica-cloud-erp/request/Login' -m '{"access_token": "<access_token>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# Airtable
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/airtable

Client-mode REST API connector for a curated Airtable Web API v0 slice: create records, filterByFormula list, upsert by device id, and webhook create

Technical Preview

## Overview

A client-mode connector for a **curated IoT / low-code** slice of the [Airtable Web API](https://airtable.com/developers/web/api/introduction) under `https://api.airtable.com`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| | `GET /v0/meta/bases` | Bases visible to the token |
| POST \{table} records | `POST /v0/{baseId}/{tableIdOrName}` | Device publishes state into a table |
| GET \{table}?filterByFormula= | `GET /v0/{baseId}/{tableIdOrName}?filterByFormula=` | URL-encode the formula |
| PATCH \{table} upsert by device id | `PATCH /v0/{baseId}/{tableIdOrName}` | `performUpsert.fieldsToMergeOn` |
| (optional) webhooks | `POST /v0/bases/{baseId}/webhooks` | Client create; inbound ping is separate |

`BASE_ADDRESS` is `https://api.airtable.com` (no trailing slash; endpoints already include `/v0/...`). Topics use `devops/airtable/<object>/<verb>`. Pass `baseId` and `tableIdOrName` on each MQTT payload (prefer table IDs).

> [!NOTE]
>
> Upsert: set `performUpsert.fieldsToMergeOn` (for example `["Device Id"]`). Zero matches create; one match updates; multiple matches fail.

> [!NOTE]
>
> Webhooks: this package ships **client create** only. Airtable POSTs a lightweight ping to `notificationUrl`. Inbound receive would need a separate `ENABLE_SERVER` connector.

> [!NOTE]
>
> Prefer Hub secrets for tokens.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Airtable curated IoT / low-code slice
# Auth: Bearer {value.json.api_token} (PAT or OAuth)
# BASE_ADDRESS: https://api.airtable.com

DEFINE CONNECTOR AirtableRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.airtable.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listbases
        WITH SOURCE_TOPIC "devops/airtable/bases/list"
        WITH DESTINATION_TOPIC "devops/airtable/bases/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v0/meta/bases"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createrecords
        WITH SOURCE_TOPIC "devops/airtable/records/create"
        WITH DESTINATION_TOPIC "devops/airtable/records/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v0/{value.json.baseId}/{value.json.tableIdOrName}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Listrecords
        WITH SOURCE_TOPIC "devops/airtable/records/list"
        WITH DESTINATION_TOPIC "devops/airtable/records/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v0/{value.json.baseId}/{value.json.tableIdOrName}?filterByFormula={value.json.filterByFormula}&maxRecords={value.json.maxRecords}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Upsertrecords
        WITH SOURCE_TOPIC "devops/airtable/records/upsert"
        WITH DESTINATION_TOPIC "devops/airtable/records/upsert/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v0/{value.json.baseId}/{value.json.tableIdOrName}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Createwebhook
        WITH SOURCE_TOPIC "devops/airtable/webhooks/create"
        WITH DESTINATION_TOPIC "devops/airtable/webhooks/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v0/bases/{value.json.baseId}/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Listbases | GET | `/v0/meta/bases` | `devops/airtable/bases/list` | `devops/airtable/bases/list/response` |
| Createrecords | POST | `/v0/{baseId}/{tableIdOrName}` | `devops/airtable/records/create` | `devops/airtable/records/create/response` |
| Listrecords | GET | `/v0/{baseId}/{tableIdOrName}?filterByFormula=&maxRecords=` | `devops/airtable/records/list` | `devops/airtable/records/list/response` |
| Upsertrecords | PATCH | `/v0/{baseId}/{tableIdOrName}` | `devops/airtable/records/upsert` | `devops/airtable/records/upsert/response` |
| Createwebhook | POST | `/v0/bases/{baseId}/webhooks` | `devops/airtable/webhooks/create` | `devops/airtable/webhooks/create/response` |

## Auth

**Personal access token or OAuth 2.0 Bearer — default in the template:**

1. Create a PAT at [airtable.com/create/tokens](https://airtable.com/create/tokens) (or an OAuth app) with scopes `data.records:read`, `data.records:write`, plus `schema.bases:read` for ListBases and `webhook:manage` for CreateWebhook. Add the target base as a resource.
2. Pass `api_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.api_token}`
3. Store the token in Hub secrets / `GET SECRET "AIRTABLE_TOKEN"`. Never commit real credentials.
4. Pass `baseId` and `tableIdOrName` on each call (prefer table IDs so renames do not break paths).

## Example payloads

**List bases:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "api_token": "YOUR_PAT_OR_OAUTH_TOKEN" }
```

**Create records:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_PAT_OR_OAUTH_TOKEN",
  "baseId": "appXXXXXXXXXXXXXX",
  "tableIdOrName": "tblXXXXXXXXXXXXXX",
  "records": [
    {
      "fields": {
        "Device Id": "line-a-sensor-01",
        "Temperature": 72.5,
        "Status": "OK"
      }
    }
  ]
}
```

**List with filterByFormula (URL-encoded):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_PAT_OR_OAUTH_TOKEN",
  "baseId": "appXXXXXXXXXXXXXX",
  "tableIdOrName": "tblXXXXXXXXXXXXXX",
  "filterByFormula": "%7BDevice%20Id%7D%3D%27line-a-sensor-01%27",
  "maxRecords": "50"
}
```

**Upsert by device id:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_PAT_OR_OAUTH_TOKEN",
  "baseId": "appXXXXXXXXXXXXXX",
  "tableIdOrName": "tblXXXXXXXXXXXXXX",
  "performUpsert": { "fieldsToMergeOn": ["Device Id"] },
  "records": [
    {
      "fields": {
        "Device Id": "line-a-sensor-01",
        "Temperature": 73.1,
        "Status": "WARN"
      }
    }
  ]
}
```

**Create webhook:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_PAT_OR_OAUTH_TOKEN",
  "baseId": "appXXXXXXXXXXXXXX",
  "notificationUrl": "https://example.com/airtable-ping",
  "specification": {
    "options": {
      "filters": {
        "dataTypes": ["tableData"],
        "recordChangeScope": "tblXXXXXXXXXXXXXX"
      }
    }
  }
}
```

## Rate limits and notes

* Airtable enforces per-base rate limits; back off on HTTP 429.
* Prefer table IDs over names.
* `filterByFormula` must be URL-encoded; keep URLs under \~16k characters.
* Deployable `.lot` must not include `ADD METADATA` (Hub uses `hub-metadata.lot` separately).

## Sources

* [API introduction](https://airtable.com/developers/web/api/introduction)
* [Authentication](https://airtable.com/developers/web/api/authentication)
* [Create records](https://airtable.com/developers/web/api/create-records)
* [List records](https://airtable.com/developers/web/api/list-records)
* [Update multiple records (upsert)](https://airtable.com/developers/web/api/update-multiple-records)
* [Create a webhook](https://airtable.com/developers/web/api/create-a-webhook)
* [Webhooks overview](https://airtable.com/developers/web/api/webhooks-overview)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Amazon Bedrock Control
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/amazon-bedrock-control

Connect Coreflux LoT to the Amazon Bedrock control plane to list and inspect foundation models and list inference profiles with a Bedrock API key

Technical Preview

## Overview

Client-mode REST API connectors for Amazon Bedrock: triage alarms and summarize shift logs with the Converse API, create Titan embeddings with InvokeModel, count tokens, screen text with a guardrail, and list foundation models and inference profiles, all with a Bedrock API key.

This is one of the templates in the Amazon Bedrock REST API app (`amazon-bedrock`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Amazon Bedrock API key as Authorization: Bearer \{value.json.api\_key} (long-term ABSK..., short-term bedrock-api-key-...). Hub secret suggested AWS\_BEARER\_TOKEN\_BEDROCK + GET SECRET. Alternative: AWS SigV4 (service bedrock) computed outside the broker, documented in comments. Never commit keys.

Auth headers used by the template: `Authorization: Bearer {value.json.api_key}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Amazon Bedrock Control connector | no |
| `BaseUrl` | string | Amazon Bedrock Control base URL without trailing slash (e.g. [https://bedrock.eu-west-1.amazonaws.com](https://bedrock.eu-west-1.amazonaws.com)) | yes |

`BASE_ADDRESS` default: `https://bedrock.eu-west-1.amazonaws.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ListFoundationModels` | GET | `/foundation-models?byOutputModality={value.json.output_modality}&byProvider={value.json.provider}` | `ai/bedrock/foundation-model/list` | `ai/bedrock/foundation-model/list/response` | `api_key`, `output_modality`, `provider` |
| `GetFoundationModel` | GET | `/foundation-models/{value.json.model_id}` | `ai/bedrock/foundation-model/get` | `ai/bedrock/foundation-model/get/response` | `api_key`, `model_id` |
| `ListInferenceProfiles` | GET | `/inference-profiles?maxResults={value.json.max_results}&type={value.json.type}` | `ai/bedrock/inference-profile/list` | `ai/bedrock/inference-profile/list/response` | `api_key`, `max_results`, `type` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AMAZON_BEDROCK_CONTROL"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AmazonBedrockControl WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://bedrock.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListFoundationModels
        WITH SOURCE_TOPIC "ai/bedrock/foundation-model/list"
        WITH DESTINATION_TOPIC "ai/bedrock/foundation-model/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/foundation-models?byOutputModality={value.json.output_modality}&byProvider={value.json.provider}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT GetFoundationModel
        WITH SOURCE_TOPIC "ai/bedrock/foundation-model/get"
        WITH DESTINATION_TOPIC "ai/bedrock/foundation-model/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/foundation-models/{value.json.model_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ListInferenceProfiles
        WITH SOURCE_TOPIC "ai/bedrock/inference-profile/list"
        WITH DESTINATION_TOPIC "ai/bedrock/inference-profile/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/inference-profiles?maxResults={value.json.max_results}&type={value.json.type}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ListFoundationModels` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/bedrock/foundation-model/list/response' &
mosquitto_pub -t 'ai/bedrock/foundation-model/list' -m '{"api_key": "<api_key>", "output_modality": "<output_modality>", "provider": "<provider>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Amazon Bedrock Runtime
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/amazon-bedrock-runtime

Use the LoT Amazon Bedrock Runtime connector to call Converse and InvokeModel, count tokens and apply guardrails from MQTT with a Bedrock API key

Technical Preview

## Overview

Client-mode REST API connectors for Amazon Bedrock: triage alarms and summarize shift logs with the Converse API, create Titan embeddings with InvokeModel, count tokens, screen text with a guardrail, and list foundation models and inference profiles, all with a Bedrock API key.

This is one of the templates in the Amazon Bedrock REST API app (`amazon-bedrock`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Amazon Bedrock API key as Authorization: Bearer \{value.json.api\_key} (long-term ABSK..., short-term bedrock-api-key-...). Hub secret suggested AWS\_BEARER\_TOKEN\_BEDROCK + GET SECRET. Alternative: AWS SigV4 (service bedrock) computed outside the broker, documented in comments. Never commit keys.

Auth headers used by the template: `Authorization: Bearer {value.json.api_key}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Amazon Bedrock Runtime connector | no |
| `BaseUrl` | string | Amazon Bedrock Runtime base URL without trailing slash (e.g. [https://bedrock-runtime.eu-west-1.amazonaws.com](https://bedrock-runtime.eu-west-1.amazonaws.com)) | yes |

`BASE_ADDRESS` default: `https://bedrock-runtime.eu-west-1.amazonaws.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Converse` | POST | `/model/{value.json.model_id}/converse` | `ai/bedrock/converse/send` | `ai/bedrock/converse/send/response` | `api_key`, `body`, `model_id` |
| `InvokeModel` | POST | `/model/{value.json.model_id}/invoke` | `ai/bedrock/model/invoke` | `ai/bedrock/model/invoke/response` | `api_key`, `body`, `model_id` |
| `CountTokens` | POST | `/model/{value.json.model_id}/count-tokens` | `ai/bedrock/tokens/count` | `ai/bedrock/tokens/count/response` | `api_key`, `body`, `model_id` |
| `ApplyGuardrail` | POST | `/guardrail/{value.json.guardrail_id}/version/{value.json.guardrail_version}/apply` | `ai/bedrock/guardrail/apply` | `ai/bedrock/guardrail/apply/response` | `api_key`, `body`, `guardrail_id`, `guardrail_version` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AMAZON_BEDROCK_RUNTIME"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AmazonBedrockRuntime WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://bedrock-runtime.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Converse
        WITH SOURCE_TOPIC "ai/bedrock/converse/send"
        WITH DESTINATION_TOPIC "ai/bedrock/converse/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/model/{value.json.model_id}/converse"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT InvokeModel
        WITH SOURCE_TOPIC "ai/bedrock/model/invoke"
        WITH DESTINATION_TOPIC "ai/bedrock/model/invoke/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/model/{value.json.model_id}/invoke"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT CountTokens
        WITH SOURCE_TOPIC "ai/bedrock/tokens/count"
        WITH DESTINATION_TOPIC "ai/bedrock/tokens/count/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/model/{value.json.model_id}/count-tokens"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ApplyGuardrail
        WITH SOURCE_TOPIC "ai/bedrock/guardrail/apply"
        WITH DESTINATION_TOPIC "ai/bedrock/guardrail/apply/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/guardrail/{value.json.guardrail_id}/version/{value.json.guardrail_version}/apply"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `Converse` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/bedrock/converse/send/response' &
mosquitto_pub -t 'ai/bedrock/converse/send' -m '{"api_key": "<api_key>", "body": {}, "model_id": "<model_id>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Amazon CloudWatch
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/amazon-cloudwatch

LoT connector for Amazon CloudWatch: send PutMetricData, GetMetricData, CreateLogStream and PutLogEvents from MQTT using upstream SigV4 headers

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) and [CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST PutMetricData | `POST /` on `monitoring.{region}.amazonaws.com` | JSON + `X-Amz-Target: GraniteServiceVersion20100801.PutMetricData`; SigV4 service `monitoring`; expect **200** |
| GetMetricData | `POST /` (same host) | Catalog said GET; official JSON protocol is POST `GetMetricData`; preferred credential check → **200** |
| POST PutLogEvents | `POST /` on `logs.{region}.amazonaws.com` | `Content-Type: application/x-amz-json-1.1`; `X-Amz-Target: Logs_20140328.PutLogEvents`; SigV4 service `logs` |
| CreateLogStream | `POST /` (logs host) | Helper so PutLogEvents is usable |
| SNS alarm notification | inbound HTTPS | **ENABLE\_SERVER companion** (docs only — not in this client `.lot`) |

Default `BASE_ADDRESS` is `https://monitoring.eu-west-1.amazonaws.com`. Topics use `itsm/amazon-cloudwatch/<object>/<verb>`. Switch BASE to `https://logs.{region}.amazonaws.com` for Logs events.

> [!NOTE]
>
> Prefer Hub secrets for `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` used by an upstream SigV4 signer. Pass `Authorization`, `x-amz-date`, and `x-amz-content-sha256` on each MQTT payload — this is **not** Bearer auth.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Amazon CloudWatch (metrics + logs)
# Auth: SigV4 headers from MQTT payload (NOT Bearer)
# BASE_ADDRESS: https://monitoring.eu-west-1.amazonaws.com

DEFINE CONNECTOR AmazonCloudWatchRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://monitoring.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Putmetricdata
        WITH SOURCE_TOPIC "itsm/amazon-cloudwatch/metric/put"
        WITH DESTINATION_TOPIC "itsm/amazon-cloudwatch/metric/put/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Content-Encoding" "amz-1.0"
            ADD "X-Amz-Target" "GraniteServiceVersion20100801.PutMetricData"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Getmetricdata
        WITH SOURCE_TOPIC "itsm/amazon-cloudwatch/metric/get"
        WITH DESTINATION_TOPIC "itsm/amazon-cloudwatch/metric/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Content-Encoding" "amz-1.0"
            ADD "X-Amz-Target" "GraniteServiceVersion20100801.GetMetricData"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Putlogevents
        WITH SOURCE_TOPIC "itsm/amazon-cloudwatch/log/put"
        WITH DESTINATION_TOPIC "itsm/amazon-cloudwatch/log/put/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-amz-json-1.1"
            ADD "X-Amz-Target" "Logs_20140328.PutLogEvents"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Createlogstream
        WITH SOURCE_TOPIC "itsm/amazon-cloudwatch/log/create-stream"
        WITH DESTINATION_TOPIC "itsm/amazon-cloudwatch/log/create-stream/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-amz-json-1.1"
            ADD "X-Amz-Target" "Logs_20140328.CreateLogStream"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
```

## Authentication

| Mode | Header | Notes |
| - | - | - |
| AWS Signature Version 4 | `Authorization: {value.json.authorization}` (+ `x-amz-date`, `x-amz-content-sha256`) | Default in this template — **not** Bearer |

Sign with service name `monitoring` (metrics host) or `logs` (Logs host). Store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` (optional `AWS_SESSION_TOKEN`) in Hub secrets and resolve via an upstream signer + `GET SECRET` — never commit credentials.

## MQTT examples

**PutMetricData** (BASE = monitoring):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Namespace": "Coreflux/Plant",
  "MetricData": [
    {
      "MetricName": "vibration_rms",
      "Value": 12.4,
      "Unit": "None",
      "Dimensions": [{ "Name": "line", "Value": "a" }]
    }
  ]
}
```

Publish with SigV4 headers. Expect **HTTP 200**.

**GetMetricData** (credential check; BASE = monitoring):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "StartTime": "2026-10-04T16:00:00Z",
  "EndTime": "2026-10-04T17:00:00Z",
  "MetricDataQueries": [
    {
      "Id": "m1",
      "MetricStat": {
        "Metric": {
          "Namespace": "AWS/EC2",
          "MetricName": "CPUUtilization",
          "Dimensions": [{ "Name": "InstanceId", "Value": "i-0123456789abcdef0" }]
        },
        "Period": 300,
        "Stat": "Average"
      }
    }
  ]
}
```

Expect **HTTP 200**.

**PutLogEvents** (BASE = `logs.{region}.amazonaws.com`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "logGroupName": "coreflux/plant",
  "logStreamName": "line-a",
  "logEvents": [
    { "timestamp": 1728057600000, "message": "vibration_rms=12.4" }
  ]
}
```

Expect **HTTP 200** with `nextSequenceToken`. Create the stream first via `Createlogstream` if needed.

## ENABLE\_SERVER companion

CloudWatch Alarms → SNS → HTTPS subscription can POST notification JSON to an inbound endpoint. Package that as a separate `ENABLE_SERVER` connector — not included in the client `.lot`.

## Sources

* [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API\_PutMetricData.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricData.html)
* [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API\_GetMetricData.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricData.html)
* [https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/making-api-requests.html](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/making-api-requests.html)
* [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API\_PutLogEvents.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html)
* [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API\_CreateLogStream.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLogStream.html)
* [https://docs.aws.amazon.com/sns/latest/dg/sns-http-https-endpoint-as-subscriber.html](https://docs.aws.amazon.com/sns/latest/dg/sns-http-https-endpoint-as-subscriber.html)

## Related

* [REST API connectors overview](/latest/lot-language/routes/rest-api-routes)
* [Azure Monitor](/latest/lot-language/routes/rest-api-apps/azure-monitor)
* [Datadog](/latest/lot-language/routes/rest-api-apps/datadog)
* [AWS IoT Core](/latest/lot-language/routes/rest-api-apps/aws-iot-core)


# Amazon DynamoDB
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/amazon-dynamodb

LoT connector for Amazon DynamoDB: put, update, get and query device state items, batch writes and list tables from MQTT with SigV4-signed JSON

Technical Preview

## Overview

A client-mode connector for the [Amazon DynamoDB API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/) that keeps per-device state and history in a DynamoDB table straight from MQTT. DynamoDB uses the AWS JSON 1.0 protocol: every operation is `POST /` with `Content-Type: application/x-amz-json-1.0` and an `X-Amz-Target` header naming the operation.

| Connector event | X-Amz-Target | Notes |
| - | - | - |
| `PutItem` | `DynamoDB_20120810.PutItem` | Write or replace a device state item. [API\_PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html) |
| `UpdateItem` | `DynamoDB_20120810.UpdateItem` | Set `lastSeen` or other attributes with an `UpdateExpression`. [API\_UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) |
| `QueryByDevice` | `DynamoDB_20120810.Query` | Items for one partition key (for example `deviceId`), newest first. [API\_Query](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) |
| `GetItem` | `DynamoDB_20120810.GetItem` | Read one item by primary key. |
| `BatchWriteItem` | `DynamoDB_20120810.BatchWriteItem` | Up to 25 puts or deletes per call. |
| `ListTables` | `DynamoDB_20120810.ListTables` | Credential check. |
| `DescribeTable` / `CreateTable` | `…DescribeTable`, `…CreateTable` | Table status, key schema, and one-time setup. |

Default `BASE_ADDRESS` is `https://dynamodb.eu-west-1.amazonaws.com`; change the region to match your table. Topics use `data/amazon-dynamodb/<object>/<verb>`, and replies arrive on `<topic>/response`.

## Auth

DynamoDB requires [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv4.html) with service name `dynamodb`. It is not a Bearer token. The connector does not sign requests itself; an upstream signer (a Python action, edge service, or SDK) signs each request and publishes the signed headers with the body:

* `authorization`: the `AWS4-HMAC-SHA256 Credential=…, SignedHeaders=…, Signature=…` value
* `x_amz_date`: the `X-Amz-Date` timestamp used in the signature
* `x_amz_content_sha256`: hex SHA-256 of the body
* `body`: the DynamoDB request JSON. Only this field is sent to AWS.

Keep `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_REGION` in Hub secrets for the signer, and never commit keys. For temporary STS credentials, add an `x-amz-security-token` header to the events.

> [!WARNING]
>
> **The signature covers the exact body bytes.** Sign compact JSON (no spaces) and make sure the connector sends the same bytes. If they differ, AWS returns `400 InvalidSignatureException`. This has not been verified on the broker runtime yet.

The IAM policy needs `dynamodb:PutItem`, `UpdateItem`, `Query`, `GetItem`, `BatchWriteItem`, `ListTables` and `DescribeTable` on the table, plus `CreateTable` if the connector creates it.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AmazonDynamodbRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://dynamodb.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/x-amz-json-1.0"
        # Errors come back as HTTP 400 JSON {"__type":"...#ValidationException","message":"..."}
    ADD EVENT PutItem
        WITH SOURCE_TOPIC "data/amazon-dynamodb/item/put"
        WITH DESTINATION_TOPIC "data/amazon-dynamodb/item/put/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-amz-json-1.0"
            ADD "X-Amz-Target" "DynamoDB_20120810.PutItem"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateItem
        WITH SOURCE_TOPIC "data/amazon-dynamodb/item/update"
        WITH DESTINATION_TOPIC "data/amazon-dynamodb/item/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-amz-json-1.0"
            ADD "X-Amz-Target" "DynamoDB_20120810.UpdateItem"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{value.json.body}"
    ADD EVENT QueryByDevice
        WITH SOURCE_TOPIC "data/amazon-dynamodb/items/query"
        WITH DESTINATION_TOPIC "data/amazon-dynamodb/items/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-amz-json-1.0"
            ADD "X-Amz-Target" "DynamoDB_20120810.Query"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{value.json.body}"
```

The full template also includes `GetItem`, `BatchWriteItem`, `ListTables`, `DescribeTable` and `CreateTable`, which use the same headers with their own `X-Amz-Target`.

## Payload examples

DynamoDB values use attribute-value JSON: strings are `{"S": "…"}`, and numbers are `{"N": "…"}` written as strings.

**Write device state (topic `data/amazon-dynamodb/item/put`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "AWS4-HMAC-SHA256 Credential=AKIA…/20261004/eu-west-1/dynamodb/aws4_request, SignedHeaders=…, Signature=…",
  "x_amz_date": "20261004T220500Z",
  "x_amz_content_sha256": "<hex sha256 of body>",
  "body": {
    "TableName": "cf_device_state",
    "Item": {
      "deviceId": {"S": "press-01"},
      "ts": {"N": "1759615200"},
      "temp": {"N": "21.5"},
      "state": {"S": "RUN"}
    }
  }
}
```

**Update last-seen (topic `data/amazon-dynamodb/item/update`), body only:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "TableName": "cf_device_state",
  "Key": {"deviceId": {"S": "press-01"}, "ts": {"N": "1759615200"}},
  "UpdateExpression": "SET lastSeen = :t, #s = :s",
  "ExpressionAttributeNames": {"#s": "state"},
  "ExpressionAttributeValues": {":t": {"S": "2026-10-04T22:05:00Z"}, ":s": {"S": "IDLE"}},
  "ReturnValues": "ALL_NEW"
}
```

**Query a device, newest first (topic `data/amazon-dynamodb/items/query`), body only:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "TableName": "cf_device_state",
  "KeyConditionExpression": "deviceId = :d",
  "ExpressionAttributeValues": {":d": {"S": "press-01"}},
  "ScanIndexForward": false,
  "Limit": 10
}
```

> [!TIP]
>
> `state`, `name`, `status` and many other common words are DynamoDB reserved words. Alias them with `ExpressionAttributeNames` (`#s`) in update and query expressions.

## Errors and limits

* Errors are `HTTP 400` JSON with `__type` and `message`, for example `ValidationException`, `ResourceNotFoundException`, `ConditionalCheckFailedException`, or `ProvisionedThroughputExceededException` (back off and retry).
* Items are limited to 400 KB. `BatchWriteItem` accepts up to 25 requests (16 MB) and may return `UnprocessedItems` with `HTTP 200`; resend those.
* `Query` returns at most 1 MB per call; page with `LastEvaluatedKey` → `ExclusiveStartKey`.
* Scan, deletes, PartiQL, transactions and DynamoDB Streams (a separate `streams.dynamodb` endpoint) are not included.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [Amazon S3](/latest/lot-language/routes/rest-api-apps/amazon-s3)
* [Amazon CloudWatch](/latest/lot-language/routes/rest-api-apps/amazon-cloudwatch)


# Amazon S3
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/amazon-s3

Client-mode REST API connector for a curated Amazon S3 slice: PutObject, GetObject, HeadObject, ListBuckets, and PUT to a presigned URL

Technical Preview

## Overview

A client-mode connector for a **curated IIoT object-storage** slice of the [Amazon S3 REST API](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html) under path-style `https://s3.amazonaws.com`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| | `GET /` | ListBuckets for the signing identity |
| PUT object (snapshot, CSV rollup) | `PUT /{bucket}/{key}` | SigV4 headers required |
| GET object | `GET /{bucket}/{key}` | SigV4 headers required |
| (optional) HeadObject | `HEAD /{bucket}/{key}` | Metadata without body |
| PUT to presigned URL | `PUT {presigned_path}` | No Authorization; switch BASE to URL origin |
| S3 → SNS event | — | Docs-only; future `ENABLE_SERVER` |

`BASE_ADDRESS` defaults to `https://s3.amazonaws.com` (no trailing slash; path-style). Prefer regional `https://s3.{region}.amazonaws.com` when required. Topics use `storage/amazon-s3/<object>/<verb>`.

> [!NOTE]
>
> **Virtual-hosted style:** set `BASE_ADDRESS` to `https://{bucket}.s3.{region}.amazonaws.com` and use endpoints like `/{key}` (bucket is already in the host).

> [!NOTE]
>
> **Presigned PUT:** set `BASE_ADDRESS` to the presigned URL origin only, put path+query in `presigned_path`, and omit SigV4 headers — the query string carries the signature. Ideal for edge devices that must not hold AWS keys.

> [!NOTE]
>
> **S3 event notifications** (SNS / EventBridge / Lambda) are not inbound HTTP on this client connector. Receiving notification POSTs needs a separate `ENABLE_SERVER` REST\_API template (not packaged).

> [!NOTE]
>
> Prefer Hub secrets for AWS keys used by an upstream SigV4 signer.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Amazon S3 curated slice
# Auth: SigV4 via {value.json.authorization}, {value.json.x_amz_date},
#       {value.json.x_amz_content_sha256} — or PutPresigned (no Authorization)
# BASE_ADDRESS: https://s3.amazonaws.com (path-style)

DEFINE CONNECTOR AmazonS3RestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://s3.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/octet-stream"
    ADD EVENT Listbuckets
        WITH SOURCE_TOPIC "storage/amazon-s3/buckets/list"
        WITH DESTINATION_TOPIC "storage/amazon-s3/buckets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Putobject
        WITH SOURCE_TOPIC "storage/amazon-s3/object/put"
        WITH DESTINATION_TOPIC "storage/amazon-s3/object/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Getobject
        WITH SOURCE_TOPIC "storage/amazon-s3/object/get"
        WITH DESTINATION_TOPIC "storage/amazon-s3/object/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Headobject
        WITH SOURCE_TOPIC "storage/amazon-s3/object/head"
        WITH DESTINATION_TOPIC "storage/amazon-s3/object/head/response"
        WITH METHOD "HEAD"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Putpresigned
        WITH SOURCE_TOPIC "storage/amazon-s3/object/put-presigned"
        WITH DESTINATION_TOPIC "storage/amazon-s3/object/put-presigned/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "{value.json.presigned_path}"
        WITH HEADERS
            ADD "Content-Type" "{value.json.content_type}"
        WITH BODY "{payload}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `AmazonS3RestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://s3.amazonaws.com` (path-style default) |
| Topic prefix | `storage/amazon-s3/...` |
| Default Content-Type | `application/octet-stream` |
| Hub status | Technical preview (`WITH STATUS "beta"`) |

## Authentication

### AWS Signature Version 4

S3 does **not** use `Authorization: Bearer …`. Sign each request with [SigV4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) and pass:

| MQTT JSON field | HTTP header |
| - | - |
| `authorization` | `Authorization` (`AWS4-HMAC-SHA256 Credential=…`) |
| `x_amz_date` | `x-amz-date` |
| `x_amz_content_sha256` | `x-amz-content-sha256` |

Use Hub secrets for `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` in an upstream signing helper. Never commit real keys. STS sessions may also need `x-amz-security-token` (add that header in a customized fork if required).

### Presigned URLs (recommended for edge)

Generate a time-limited PUT or GET URL with the AWS CLI/SDK. For PutPresigned:

1. Point `BASE_ADDRESS` at the URL origin.
2. Put path + query into `presigned_path`.
3. Omit Authorization — do not re-sign on the broker.

## MQTT topics

| Event | Request topic | Response topic |
| - | - | - |
| ListBuckets | `storage/amazon-s3/buckets/list` | `…/response` |
| PutObject | `storage/amazon-s3/object/put` | `…/response` |
| GetObject | `storage/amazon-s3/object/get` | `…/response` |
| HeadObject | `storage/amazon-s3/object/head` | `…/response` |
| PutPresigned | `storage/amazon-s3/object/put-presigned` | `…/response` |

## Example payloads

**ListBuckets (after signing):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "AWS4-HMAC-SHA256 Credential=AKIA.../20261004/eu-west-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=...",
  "x_amz_date": "20261004T040000Z",
  "x_amz_content_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
```

**PutObject CSV rollup:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "bucket": "my-iiot-rollups",
  "key": "line-a/2026-10-04/rollup.csv",
  "content_type": "text/csv",
  "authorization": "AWS4-HMAC-SHA256 Credential=...",
  "x_amz_date": "20261004T040100Z",
  "x_amz_content_sha256": "<sha256 of body>",
  "payload": "ts,device,temp\n2026-10-04T04:01:00Z,sensor-01,72.5\n"
}
```

**PutPresigned:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "presigned_path": "/line-a/snapshot.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
  "content_type": "application/json",
  "payload": "{\"device\":\"sensor-01\",\"temp\":72.5}"
}
```

## References

* [S3 API PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)
* [S3 API GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)
* [S3 API HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)
* [S3 API ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html)
* [Upload with a presigned URL](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html)
* [Authenticating Requests (SigV4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)
* [Coreflux REST API Connectors](/latest/lot-language/routes/rest-api-routes)

## Package status


# Amazon SNS
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/amazon-sns

LoT connector for Amazon SNS: publish to topics or SMS, list and create topics, read attributes and subscribe endpoints from MQTT with SigV4 auth

Technical Preview

## Overview

A client-mode connector for a **curated messaging / notifications** slice of [Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/welcome.html):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST Publish (topic) | `POST /` on `sns.{region}.amazonaws.com` | Query `Action=Publish&Version=2010-03-31` + `TopicArn` + `Message`; SigV4 service `sns`; expect **200** XML `MessageId` |
| POST Publish SMS | `POST /` (same host) | Same Publish action with `PhoneNumber` (E.164) instead of `TopicArn` |
| ListTopics | `POST /` | Preferred credential check → **200** XML topic list |
| GetTopicAttributes | `POST /` | Topic property map |
| CreateTopic | `POST /` | Create / idempotent get by name |
| Subscribe | `POST /` | e.g. `Protocol=https` + `Endpoint`; pending until confirmed |
| Confirm / receive HTTPS subscription | inbound HTTPS | **ENABLE\_SERVER companion** (docs only — not in this client `.lot`); client `ConfirmSubscription` Query action optional in a fork |

Default `BASE_ADDRESS` is `https://sns.eu-west-1.amazonaws.com`. Topics use `messaging/amazon-sns/<object>/<verb>`. Official protocol is **Query** form-urlencoded (XML responses), not CloudWatch-style JSON `X-Amz-Target`.

> [!NOTE]
>
> Prefer Hub secrets for `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` used by an upstream SigV4 signer. Pass `Authorization`, `x-amz-date`, and `x-amz-content-sha256` on each MQTT payload — this is **not** Bearer auth.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Amazon SNS (Query API 2010-03-31)
# Auth: SigV4 headers from MQTT payload (NOT Bearer)
# BASE_ADDRESS: https://sns.eu-west-1.amazonaws.com

DEFINE CONNECTOR AmazonSnsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://sns.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/x-www-form-urlencoded"
    ADD EVENT Publish
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/publish"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Publishsms
        WITH SOURCE_TOPIC "messaging/amazon-sns/sms/publish"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/sms/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Listtopics
        WITH SOURCE_TOPIC "messaging/amazon-sns/topics/list"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topics/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Gettopicattributes
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/get-attributes"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/get-attributes/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Createtopic
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/create"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Subscribe
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/subscribe"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/subscribe/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
```

## Authentication

| Mode | Header | Notes |
| - | - | - |
| AWS Signature Version 4 | `Authorization: {value.json.authorization}` (+ `x-amz-date`, `x-amz-content-sha256`) | Default in this template — **not** Bearer |

Sign with service name `sns` and a region matching the host. Store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` (optional `AWS_SESSION_TOKEN`) in Hub secrets and resolve via an upstream signer + `GET SECRET` — never commit credentials.

## MQTT examples

**ListTopics** (a good first call; form body):

```
Action=ListTopics&Version=2010-03-31
```

Expect **HTTP 200**.

**Publish** to topic:

```
Action=Publish&Version=2010-03-31&TopicArn=arn%3Aaws%3Asns%3Aeu-west-1%3A123456789012%3Acoreflux-plant&Message=vibration_rms%3D12.4&Subject=Plant%20alarm
```

Expect **HTTP 200** with `MessageId`.

**Publish SMS:**

```
Action=Publish&Version=2010-03-31&PhoneNumber=%2B351912345678&Message=Plant%20alarm
```

**Subscribe** HTTPS:

```
Action=Subscribe&Version=2010-03-31&TopicArn=arn%3Aaws%3Asns%3Aeu-west-1%3A123456789012%3Acoreflux-plant&Protocol=https&Endpoint=https%3A%2F%2Fbroker.example.com%2Fsns%2Fplant&ReturnSubscriptionArn=true
```

Include SigV4 header fields (`authorization`, `x_amz_date`, `x_amz_content_sha256`) on the MQTT JSON envelope; put the form string in the HTTP body (`{payload}`).

## ENABLE\_SERVER companion

When SNS delivers **SubscriptionConfirmation** / **Notification** / **UnsubscribeConfirmation** to your HTTPS endpoint, handle them with a separate `ENABLE_SERVER` connector (not packaged here). Confirm with the client [ConfirmSubscription](https://docs.aws.amazon.com/sns/latest/api/API_ConfirmSubscription.html) Query action (`Token` + `TopicArn`) or by GETting the `SubscribeURL` from the confirmation payload.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Amazon CloudWatch](/latest/lot-language/routes/rest-api-apps/amazon-cloudwatch) (SigV4 pattern; SNS alarm companion)
* AWS docs: [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html), [ListTopics](https://docs.aws.amazon.com/sns/latest/api/API_ListTopics.html), [HTTPS subscribers](https://docs.aws.amazon.com/sns/latest/dg/sns-http-https-endpoint-as-subscriber.html)


# Anaplan
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/anaplan

Client-mode REST API connectors for Anaplan Integration API v2: auth token plus workspaces and models and file upload and import and export and process tasks

Technical Preview

## Overview

Client-mode REST API connectors for Anaplan Integration API v2: auth token plus workspaces and models and file upload and import and export and process tasks. `BASE_ADDRESS` defaults to `https://api.anaplan.com`. Topics use `analytics/anaplan/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `TokenAuthenticate` | `POST /token/authenticate` | `analytics/anaplan/auth/token/create` |
| `TokenRefresh` | `POST /token/refresh` | `analytics/anaplan/auth/token/refresh` |
| `TokenValidate` | `GET /token/validate` | `analytics/anaplan/auth/token/validate` |
| `WorkspacesList` | `GET /2/0/workspaces` | `analytics/anaplan/workspaces/list` |
| `ModelsList` | `GET /2/0/workspaces/{value.json.workspaceId}/models` | `analytics/anaplan/models/list` |
| `FilesList` | `GET /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/files` | `analytics/anaplan/files/list` |
| `FileUpload` | `PUT /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/files/{value.json.fileId}` | `analytics/anaplan/files/upload` |
| `ImportsList` | `GET /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/imports` | `analytics/anaplan/imports/list` |
| `ImportTaskStart` | `POST /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/imports/{value.json.importId}/tasks` | `analytics/anaplan/imports/tasks/start` |
| `ImportTaskGet` | `GET /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/imports/{value.json.importId}/tasks/{value.json.taskId}` | `analytics/anaplan/imports/tasks/get` |
| `ExportTaskStart` | `POST /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/exports/{value.json.exportId}/tasks` | `analytics/anaplan/exports/tasks/start` |
| `ExportTaskGet` | `GET /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/exports/{value.json.exportId}/tasks/{value.json.taskId}` | `analytics/anaplan/exports/tasks/get` |
| `ProcessTaskStart` | `POST /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/processes/{value.json.processId}/tasks` | `analytics/anaplan/processes/tasks/start` |
| `ProcessTaskGet` | `GET /2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/processes/{value.json.processId}/tasks/{value.json.taskId}` | `analytics/anaplan/processes/tasks/get` |

## Authentication

AnaplanAuthToken. AnaplanAuthRestApi ([https://auth.anaplan.com](https://auth.anaplan.com)) POST /token/authenticate with Authorization: \{value.json.authorization} ("Basic base64(user:password)" or the CACertificate header form) returns tokenInfo.tokenValue; refresh with /token/refresh before 30 minutes. AnaplanRestApi events send Authorization: AnaplanAuthToken \{value.json.auth\_token}.

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* Two connectors because authentication lives on auth.anaplan.com and the Integration API on api.anaplan.com.
* FileUpload sends \{value.json.body} as the whole file (single chunk, application/octet-stream). Larger files need the chunked PUT /chunks flow; not packaged.
* Tokens expire after 30 minutes; call TokenRefresh before expiry.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AnaplanAuthRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://auth.anaplan.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TokenAuthenticate
        WITH SOURCE_TOPIC "analytics/anaplan/auth/token/create"
        WITH DESTINATION_TOPIC "analytics/anaplan/auth/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/token/authenticate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT TokenRefresh
        WITH SOURCE_TOPIC "analytics/anaplan/auth/token/refresh"
        WITH DESTINATION_TOPIC "analytics/anaplan/auth/token/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/token/refresh"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
        WITH BODY ""
    ADD EVENT TokenValidate
        WITH SOURCE_TOPIC "analytics/anaplan/auth/token/validate"
        WITH DESTINATION_TOPIC "analytics/anaplan/auth/token/validate/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/token/validate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"

DEFINE CONNECTOR AnaplanRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.anaplan.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT WorkspacesList
        WITH SOURCE_TOPIC "analytics/anaplan/workspaces/list"
        WITH DESTINATION_TOPIC "analytics/anaplan/workspaces/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/0/workspaces"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
    ADD EVENT ModelsList
        WITH SOURCE_TOPIC "analytics/anaplan/models/list"
        WITH DESTINATION_TOPIC "analytics/anaplan/models/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
    ADD EVENT FilesList
        WITH SOURCE_TOPIC "analytics/anaplan/files/list"
        WITH DESTINATION_TOPIC "analytics/anaplan/files/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/files"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
    ADD EVENT FileUpload
        WITH SOURCE_TOPIC "analytics/anaplan/files/upload"
        WITH DESTINATION_TOPIC "analytics/anaplan/files/upload/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/files/{value.json.fileId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/octet-stream"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ImportsList
        WITH SOURCE_TOPIC "analytics/anaplan/imports/list"
        WITH DESTINATION_TOPIC "analytics/anaplan/imports/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/imports"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
    ADD EVENT ImportTaskStart
        WITH SOURCE_TOPIC "analytics/anaplan/imports/tasks/start"
        WITH DESTINATION_TOPIC "analytics/anaplan/imports/tasks/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/imports/{value.json.importId}/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ImportTaskGet
        WITH SOURCE_TOPIC "analytics/anaplan/imports/tasks/get"
        WITH DESTINATION_TOPIC "analytics/anaplan/imports/tasks/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/imports/{value.json.importId}/tasks/{value.json.taskId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
    ADD EVENT ExportTaskStart
        WITH SOURCE_TOPIC "analytics/anaplan/exports/tasks/start"
        WITH DESTINATION_TOPIC "analytics/anaplan/exports/tasks/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/exports/{value.json.exportId}/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ExportTaskGet
        WITH SOURCE_TOPIC "analytics/anaplan/exports/tasks/get"
        WITH DESTINATION_TOPIC "analytics/anaplan/exports/tasks/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/exports/{value.json.exportId}/tasks/{value.json.taskId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
    ADD EVENT ProcessTaskStart
        WITH SOURCE_TOPIC "analytics/anaplan/processes/tasks/start"
        WITH DESTINATION_TOPIC "analytics/anaplan/processes/tasks/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/processes/{value.json.processId}/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ProcessTaskGet
        WITH SOURCE_TOPIC "analytics/anaplan/processes/tasks/get"
        WITH DESTINATION_TOPIC "analytics/anaplan/processes/tasks/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/0/workspaces/{value.json.workspaceId}/models/{value.json.modelId}/processes/{value.json.processId}/tasks/{value.json.taskId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "AnaplanAuthToken {value.json.auth_token}"
```

## Sources

* [https://help.anaplan.com/upload-and-import-a-csv-75094951-6424-446c-af03-cf9852af1179](https://help.anaplan.com/upload-and-import-a-csv-75094951-6424-446c-af03-cf9852af1179)
* [https://help.anaplan.com/start-the-import-7e0dcedb-3628-44a1-8688-4a68eef85cdb](https://help.anaplan.com/start-the-import-7e0dcedb-3628-44a1-8688-4a68eef85cdb)
* [https://help.anaplan.com/monitor-the-import-tasks-107143d0-91b3-4158-b2ee-c30a9ba4ee5f](https://help.anaplan.com/monitor-the-import-tasks-107143d0-91b3-4158-b2ee-c30a9ba4ee5f)
* [https://www.postman.com/apiplan/official-anaplan-collection/documentation/2m6331d/official-anaplan-collection](https://www.postman.com/apiplan/official-anaplan-collection/documentation/2m6331d/official-anaplan-collection)


# Anthropic
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/anthropic

Client-mode REST API connector for Anthropic Claude Messages and Message Batches — MQTT into shift-log summarization and nightly batches

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [Anthropic Claude API](https://docs.anthropic.com/en/api/getting-started) focused on IIoT / edge ops text into Claude:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST messages | `POST /v1/messages` | Messages API — summarize shift log; extract fields with tools |
| POST messages/batches | `POST /v1/messages/batches` | Message Batches — nightly / async batch (up to 24h) |
| (supporting) GET models | `GET /v1/models` | List models (checks the token) |
| (supporting) GET model | `GET /v1/models/{model}` | Retrieve one model |

Default `BASE_ADDRESS` is `https://api.anthropic.com` (no trailing slash). Topics use `ai/anthropic/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** `x-api-key: &lt;Anthropic API key&gt;` **and** `anthropic-version: 2023-06-01` on every request. Prefer Hub secrets (`GET SECRET "ANTHROPIC_API_KEY"`) mapped into MQTT `api_token`. Never commit real `sk-ant-...` keys.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Anthropic
# Auth: x-api-key {value.json.api_token} + anthropic-version 2023-06-01
# BASE_ADDRESS: https://api.anthropic.com

DEFINE CONNECTOR AnthropicRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.anthropic.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostMessages
        WITH SOURCE_TOPIC "ai/anthropic/messages/post"
        WITH DESTINATION_TOPIC "ai/anthropic/messages/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "x-api-key" "{value.json.api_token}"
            ADD "anthropic-version" "2023-06-01"
        WITH BODY "{payload}"
    ADD EVENT PostMessagesBatches
        WITH SOURCE_TOPIC "ai/anthropic/messages/batches/post"
        WITH DESTINATION_TOPIC "ai/anthropic/messages/batches/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/messages/batches"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "x-api-key" "{value.json.api_token}"
            ADD "anthropic-version" "2023-06-01"
        WITH BODY "{payload}"
```

## Topics

| Event | Source topic | Destination topic |
| - | - | - |
| PostMessages | `ai/anthropic/messages/post` | `…/response` |
| PostMessagesBatches | `ai/anthropic/messages/batches/post` | `…/response` |
| GetModels | `ai/anthropic/models/list` | `…/response` |
| GetModel | `ai/anthropic/models/get` | `…/response` |

## Configuration

1. Set `BASE_ADDRESS` to `https://api.anthropic.com`.
2. Store an Anthropic API key in Hub secrets (`ANTHROPIC_API_KEY`); map into MQTT `api_token`.
3. Always send `anthropic-version: 2023-06-01` (already on every event in the template).
4. For shift-log summarization / tool use: publish to `ai/anthropic/messages/post` with a Messages body (`model`, `max_tokens`, `messages`, optional `tools`).
5. For nightly batches: publish to `ai/anthropic/messages/batches/post` with a `requests` array of `{custom_id, params}`.
6. Use `GetModels` as a cheap credential check before production workloads.

## References

* [Anthropic API overview](https://docs.anthropic.com/en/api/getting-started)
* [Messages](https://docs.anthropic.com/en/api/messages)
* [Creating Message Batches](https://docs.anthropic.com/en/api/creating-message-batches)
* [Models](https://docs.anthropic.com/en/api/models)


# Apache Superset
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/apache-superset

Connect Coreflux LoT to Apache Superset to run chart and SQL Lab queries, upload CSV data, refresh datasets, add annotations and issue guest tokens

Technical Preview

## Overview

A client-mode connector for the [Apache Superset REST API](https://superset.apache.org/docs/api). Use it to put BI results on MQTT and plant events into Superset: run a chart query or a SQL Lab statement and publish the rows to a display, upload a CSV rollup (shift totals, OEE per line) into a database, register and refresh datasets, warm the chart cache when new data lands, and mark downtime, changeover or alarm windows as annotations on time-series charts. It also reads alerts and reports with their run logs and issues guest tokens for dashboards embedded on an HMI or kiosk.

The connector `ApacheSupersetRestApi` in `ApacheSupersetRestApi.lot` has 38 events (26 GET, 9 POST, 3 PUT). 9 are writes: `DatasetCreate`, `DatasetRefresh`, `DatasetWarmUpCache`, `DatabaseCsvUpload`, `SqlLabExecute`, `AnnotationLayerCreate`, `AnnotationCreate`, `AnnotationUpdate`, `GuestTokenCreate`. There are no DELETE events.

Set `BASE_ADDRESS` to your Superset web root with no trailing slash, for example `https://superset.example.com` (use `http://` and `USE_SSL "false"` for a plain-HTTP install on a LAN). Every endpoint already starts with `/api/v1`, except `/health`. Topics use `analytics/apache-superset/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** publish `{"body":{"username":"...","password":"...","provider":"db","refresh":true}}` to `analytics/apache-superset/auth/login` (`provider` is `ldap` for LDAP users). The reply carries a JWT `access_token`, which expires after 15 minutes by default, and a `refresh_token` when `refresh` is true. Every event except `HealthGet` and `SecurityLogin` sends `Authorization: Bearer <access_token>`. To renew, publish `{"access_token":"<refresh_token>"}` to `analytics/apache-superset/auth/refresh`, or log in again. Use a dedicated Superset user with only the roles the broker needs. Keep `SUPERSET_USER` and `SUPERSET_PASSWORD` in broker secrets, read them with `GET SECRET`, never retain topics that carry a password or token, and restrict `analytics/apache-superset/auth/#` and `analytics/apache-superset/embedded/#` with ACLs. Deployments that only allow OAuth or SAML sign-in need a database or LDAP service user for the API.

> [!WARNING]
>
> **CSRF on writes.** Superset 6.x checks a CSRF token on API `POST` and `PUT` calls even when they carry a JWT, and the token only works together with a browser session cookie, which a broker connector does not keep. Without a change, every write except `ChartDataQuery` answers `400 The CSRF token is missing`. Reads, `SecurityLogin`, `SecurityRefresh` and `ChartDataQuery` work as is. To allow the packaged writes, add their views to `WTF_CSRF_EXEMPT_LIST` in `superset_config.py` and restart Superset. This exempts only those views; a signed-in browser could then be tricked into calling them, so keep the list to the writes you use.

```python theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
import os
from superset.config import WTF_CSRF_EXEMPT_LIST as _DEFAULT_EXEMPT
SECRET_KEY = os.environ["SUPERSET_SECRET_KEY"]
PREVENT_UNSAFE_DB_CONNECTIONS = False
FEATURE_FLAGS = {"ALERT_REPORTS": True, "EMBEDDED_SUPERSET": True}
# Coreflux ApacheSupersetRestApi route: API writes with a JWT and no browser session.
WTF_CSRF_EXEMPT_LIST = [*_DEFAULT_EXEMPT,
    "superset.datasets.api.post", "superset.datasets.api.refresh", "superset.datasets.api.warm_up_cache",
    "superset.databases.api.upload", "superset.sqllab.api.execute_sql_query",
    "superset.annotation_layers.api.post", "superset.annotation_layers.annotations.api.post",
    "superset.annotation_layers.annotations.api.put", "superset.security.api.guest_token"]
GUEST_TOKEN_JWT_SECRET = os.environ["SUPERSET_SECRET_KEY"] + "-guest"
```

## Events

| Event | Request | Source topic | Notes |
| - | - | - | - |
| HealthGet | `GET /health` | `analytics/apache-superset/health/get` | Smoke without login: answers OK when the web server is up. No Authorization header. |
| SecurityLogin | `POST /api/v1/security/login` | `analytics/apache-superset/auth/login` | Log in and get a JWT access\_token (and refresh\_token with refresh:true). No Authorization header. |
| SecurityRefresh | `POST /api/v1/security/refresh` | `analytics/apache-superset/auth/refresh` | New access\_token from a refresh token: send the refresh token as access\_token in the payload (Authorization: Bearer \<refresh\_token>). No body. |
| CsrfTokenGet | `GET /api/v1/security/csrf_token/` | `analytics/apache-superset/auth/csrf_token` | CSRF token, only needed when the server enforces CSRF on API writes (see the docs page). Not needed with the default JWT setup tested here. |
| MeGet | `GET /api/v1/me/` | `analytics/apache-superset/me/get` | Smoke: the user behind the token (id, username, first\_name, is\_active). |
| MeRolesGet | `GET /api/v1/me/roles/` | `analytics/apache-superset/me/roles` | Roles and permissions of the token user. |
| DashboardsList | `GET /api/v1/dashboard/?{value.json.query}` | `analytics/apache-superset/dashboards/list` | Dashboards. |
| DashboardGet | `GET /api/v1/dashboard/{value.json.dashboard_id}` | `analytics/apache-superset/dashboards/get` | One dashboard by id or slug (title, url, owners, json\_metadata). |
| DashboardChartsList | `GET /api/v1/dashboard/{value.json.dashboard_id}/charts` | `analytics/apache-superset/dashboards/charts` | Charts on a dashboard (ids, form\_data). |
| DashboardDatasetsList | `GET /api/v1/dashboard/{value.json.dashboard_id}/datasets` | `analytics/apache-superset/dashboards/datasets` | Datasets behind a dashboard. |
| ChartsList | `GET /api/v1/chart/?{value.json.query}` | `analytics/apache-superset/charts/list` | Charts. |
| ChartGet | `GET /api/v1/chart/{value.json.chart_id}` | `analytics/apache-superset/charts/get` | One chart (viz\_type, params, query\_context). |
| ChartDataGet | `GET /api/v1/chart/{value.json.chart_id}/data/?{value.json.query}` | `analytics/apache-superset/charts/data_get` | Result of a saved chart's query (catalog: chart result to MQTT). |
| ChartDataQuery | `POST /api/v1/chart/data` | `analytics/apache-superset/charts/data_query` | Run an ad hoc query context against a dataset and publish the rows (catalog event: POST chart/data). Read-only. |
| DatasetsList | `GET /api/v1/dataset/?{value.json.query}` | `analytics/apache-superset/datasets/list` | Datasets. |
| DatasetGet | `GET /api/v1/dataset/{value.json.dataset_id}` | `analytics/apache-superset/datasets/get` | One dataset (columns, metrics, database, table\_name). |
| DatasetCreate | `POST /api/v1/dataset/` | `analytics/apache-superset/datasets/create` | Write. Register a table or view as a dataset. |
| DatasetRefresh | `PUT /api/v1/dataset/{value.json.dataset_id}/refresh` | `analytics/apache-superset/datasets/refresh` | Write (re-reads column metadata from the source table). Catalog event 'POST dataset/(id)/refresh' (the API method is PUT). No body. |
| DatasetWarmUpCache | `PUT /api/v1/dataset/warm_up_cache` | `analytics/apache-superset/datasets/warm_up_cache` | Write (fills the chart cache). Warm the cache for every chart on a table after new data lands. |
| DatabasesList | `GET /api/v1/database/?{value.json.query}` | `analytics/apache-superset/databases/list` | Database connections (no passwords). |
| DatabaseGet | `GET /api/v1/database/{value.json.database_id}` | `analytics/apache-superset/databases/get` | One database connection (backend, allow\_dml, allow\_file\_upload). |
| DatabaseSchemasList | `GET /api/v1/database/{value.json.database_id}/schemas/?{value.json.query}` | `analytics/apache-superset/databases/schemas` | Schemas of a database. |
| DatabaseTablesList | `GET /api/v1/database/{value.json.database_id}/tables/?{value.json.query}` | `analytics/apache-superset/databases/tables` | Tables in a schema. |
| DatabaseCsvUpload | `POST /api/v1/database/{value.json.database_id}/upload/` | `analytics/apache-superset/databases/upload_csv` | Write (creates or appends a table). Upload a CSV rollup (shift totals, OEE per line) into a database that allows file upload. |
| SqlLabExecute | `POST /api/v1/sqllab/execute/` | `analytics/apache-superset/sqllab/execute` | Write only when the database allows DML. Run SQL and publish the rows. |
| SqlLabResultsGet | `GET /api/v1/sqllab/results/?{value.json.query}` | `analytics/apache-superset/sqllab/results` | Results of an async SQL Lab query. |
| QueriesList | `GET /api/v1/query/?{value.json.query}` | `analytics/apache-superset/queries/list` | SQL Lab query history (status, rows, error). |
| SavedQueriesList | `GET /api/v1/saved_query/?{value.json.query}` | `analytics/apache-superset/saved_queries/list` | Saved SQL Lab queries. |
| ReportsList | `GET /api/v1/report/?{value.json.query}` | `analytics/apache-superset/reports/list` | Alerts and reports (needs ALERT\_REPORTS feature flag). |
| ReportGet | `GET /api/v1/report/{value.json.report_id}` | `analytics/apache-superset/reports/get` | One alert or report (crontab, recipients, last\_state). |
| ReportLogsList | `GET /api/v1/report/{value.json.report_id}/log/?{value.json.query}` | `analytics/apache-superset/reports/logs` | Execution log of an alert or report (state, error\_message, end\_dttm). |
| AnnotationLayersList | `GET /api/v1/annotation_layer/?{value.json.query}` | `analytics/apache-superset/annotation_layers/list` | Annotation layers (overlays on time-series charts). |
| AnnotationLayerCreate | `POST /api/v1/annotation_layer/` | `analytics/apache-superset/annotation_layers/create` | Write. Create a layer for plant events. |
| AnnotationsList | `GET /api/v1/annotation_layer/{value.json.layer_id}/annotation/?{value.json.query}` | `analytics/apache-superset/annotations/list` | Annotations in a layer. |
| AnnotationCreate | `POST /api/v1/annotation_layer/{value.json.layer_id}/annotation/` | `analytics/apache-superset/annotations/create` | Write. Mark a downtime, changeover or alarm window on time-series charts. |
| AnnotationUpdate | `PUT /api/v1/annotation_layer/{value.json.layer_id}/annotation/{value.json.annotation_id}` | `analytics/apache-superset/annotations/update` | Write. Close an open window (set end\_dttm) or fix its text. body e.g. ("end\_dttm":"2026-10-05T08:12:00"). |
| LogRecentActivity | `GET /api/v1/log/recent_activity/?{value.json.query}` | `analytics/apache-superset/logs/recent_activity` | Recent views and edits of the token user. |
| GuestTokenCreate | `POST /api/v1/security/guest_token/` | `analytics/apache-superset/embedded/guest_token` | Write (issues a token). Guest token for an embedded dashboard on an HMI or kiosk (needs EMBEDDED\_SUPERSET and the can\_grant\_guest\_token permission). |

Payload fields: `access_token`; ids `dashboard_id` (id or slug), `chart_id`, `dataset_id`, `database_id`, `report_id`, `layer_id`, `annotation_id`; `query` (URL query string without `?`, or `""`; list endpoints take Rison in `q`, for example `q=(page_size:20)`); `body` (JSON); `multipart` (whole `multipart/form-data` body for `DatabaseCsvUpload`).

## Basic Syntax

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ApacheSupersetRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://superset.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SecurityLogin
        WITH SOURCE_TOPIC "analytics/apache-superset/auth/login"
        WITH DESTINATION_TOPIC "analytics/apache-superset/auth/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/security/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT MeGet
        WITH SOURCE_TOPIC "analytics/apache-superset/me/get"
        WITH DESTINATION_TOPIC "analytics/apache-superset/me/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/me/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ChartDataQuery
        WITH SOURCE_TOPIC "analytics/apache-superset/charts/data_query"
        WITH DESTINATION_TOPIC "analytics/apache-superset/charts/data_query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/chart/data"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DatabaseCsvUpload
        WITH SOURCE_TOPIC "analytics/apache-superset/databases/upload_csv"
        WITH DESTINATION_TOPIC "analytics/apache-superset/databases/upload_csv/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/database/{value.json.database_id}/upload/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "multipart/form-data; boundary=CorefluxSupersetBoundary"
        WITH BODY "{value.json.multipart}"
    ADD EVENT AnnotationCreate
        WITH SOURCE_TOPIC "analytics/apache-superset/annotations/create"
        WITH DESTINATION_TOPIC "analytics/apache-superset/annotations/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/annotation_layer/{value.json.layer_id}/annotation/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

### Keep a token for the other actions

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SupersetLogin
ON EVERY 10 MINUTES DO
    SET "user" WITH GET SECRET "SUPERSET_USER"
    SET "password" WITH GET SECRET "SUPERSET_PASSWORD"
    PUBLISH TOPIC "analytics/apache-superset/auth/login" WITH { "body": { "username": {user}, "password": {password}, "provider": "db", "refresh": false } }

DEFINE ACTION SupersetKeepToken
ON TOPIC "analytics/apache-superset/auth/login/response" DO
    SET "token" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "state/superset/access_token" WITH {token}
```

### Mark a downtime window on charts

Create a layer once with `AnnotationLayerCreate`, then add an annotation when a stop starts and close it with `AnnotationUpdate` when the line runs again. Times are local timestamps without a zone, for example `2026-10-05T08:00:00`.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SupersetMarkDowntime
ON TOPIC "plant/line2/downtime/start" DO
    SET "token" WITH GET TOPIC "state/superset/access_token" AS STRING
    SET "start" WITH GET JSON "start" IN PAYLOAD AS STRING
    PUBLISH TOPIC "analytics/apache-superset/annotations/create" WITH { "access_token": {token}, "layer_id": "3", "body": { "short_descr": "Line 2 stop", "start_dttm": {start}, "end_dttm": {start} } }
```

The reply on `analytics/apache-superset/annotations/create/response` carries the annotation `id`. Publish `{"access_token":"...","layer_id":"3","annotation_id":"<id>","body":{"end_dttm":"2026-10-05T08:12:00"}}` to `analytics/apache-superset/annotations/update` to close the window.

### Publish chart rows to a display

`ChartDataQuery` runs a query context against a dataset and returns the rows in `result[0].data`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token":"...","body":{"datasource":{"id":4,"type":"table"},"queries":[{"columns":["line"],"metrics":[{"expressionType":"SQL","sqlExpression":"SUM(units)","label":"units"}],"row_limit":100}],"result_format":"json","result_type":"full"}}
```

For a saved chart, publish `{"access_token":"...","chart_id":"12","query":"format=json&type=full"}` to `analytics/apache-superset/charts/data_get`. The chart needs a saved query context (charts saved from the Explore view in recent versions have one).

### Upload a CSV rollup

`DatabaseCsvUpload` sends `multipart` unchanged with `Content-Type: multipart/form-data; boundary=CorefluxSupersetBoundary`. Use CRLF line endings. The database needs **Allow file uploads to database** and the schema must be allowed for uploads. Superset 6.x registers the new table as a dataset itself.

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
--CorefluxSupersetBoundary
Content-Disposition: form-data; name="type"

csv
--CorefluxSupersetBoundary
Content-Disposition: form-data; name="table_name"

shift_rollup
--CorefluxSupersetBoundary
Content-Disposition: form-data; name="schema"

main
--CorefluxSupersetBoundary
Content-Disposition: form-data; name="already_exists"

append
--CorefluxSupersetBoundary
Content-Disposition: form-data; name="file"; filename="rollup.csv"
Content-Type: text/csv

line,shift,units,oee
Line 1,A,1200,0.81
--CorefluxSupersetBoundary--
```

### SQL Lab

`SqlLabExecute` runs SQL synchronously with `"runAsync":false` and returns the rows in `data`. Keep **Allow DML** off on the connection so the connector can only read: a mutating statement then fails with `This database does not allow for DDL/DML`. `SqlLabResultsGet` only applies to async queries with a results backend.

## Not packaged

* DELETE operations, on purpose.
* Alert and report create and update: those views share one wrapped handler with report deletes and plugin forms, so they cannot be CSRF-exempted on their own. Create alerts in the Superset UI; the connector reads them with `ReportsList`, `ReportGet` and `ReportLogsList`.
* Import and export ZIPs, screenshots and thumbnails, security, role and user administration, row-level security, themes, tags, explore form data and permalinks.


# Apprise API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/apprise-api

LoT connector for the Apprise API: send stateless or stateful notifications, check health, list supported services and save or inspect URL configs

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Apprise API](https://github.com/caronc/apprise-api) (Docker `caronc/apprise`), the lightweight REST wrapper around the [Apprise](https://github.com/caronc/apprise) notification library (100+ services):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST notify/\{key} | `POST /notify/{key}` | Stateful send through a saved Config ID (`title`, `body`, `type`) |
| POST notify | `POST /notify` | Stateless send with explicit `urls` list (+ `body`) |
| GET status | `GET /status` | Health → **200** OK / JSON (or **417** on config issues) |
| GET details | `GET /details` | Supported Apprise URL schemas (`Accept: application/json`) |
| POST add/\{key} | `POST /add/{key}` | Persist URLs/config under a key |
| GET json/urls/\{key} | `GET /json/urls/{key}` | Inspect saved URLs/tags (`privacy=1` redacts secrets) |

Default `BASE_ADDRESS` placeholder is `https://apprise.example.com`. Replace with your self-hosted origin via `APPRISE_BASE_URL` (common local Docker: `http://localhost:8000`). Topics use `messaging/apprise-api/<object>/<verb>`.

> [!NOTE]
>
> Auth is **deployment-dependent**: many lab containers expose endpoints with no credentials. When the server sets `APPRISE_AUTH_REQUIRED`, use HTTP Basic (`APPRISE_USER` / `APPRISE_PASSWORD`) or per-key Basic. Prefer Hub secrets.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Apprise API
# BASE_ADDRESS: set from APPRISE_BASE_URL (placeholder below)
# Optional Basic Auth when APPRISE_AUTH_REQUIRED

DEFINE CONNECTOR AppriseApiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://apprise.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getstatus
        WITH SOURCE_TOPIC "messaging/apprise-api/status/get"
        WITH DESTINATION_TOPIC "messaging/apprise-api/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/status"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getdetails
        WITH SOURCE_TOPIC "messaging/apprise-api/details/get"
        WITH DESTINATION_TOPIC "messaging/apprise-api/details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/details"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Notifystateless
        WITH SOURCE_TOPIC "messaging/apprise-api/notify/stateless"
        WITH DESTINATION_TOPIC "messaging/apprise-api/notify/stateless/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/notify"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Notifybykey
        WITH SOURCE_TOPIC "messaging/apprise-api/notify/by-key"
        WITH DESTINATION_TOPIC "messaging/apprise-api/notify/by-key/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/notify/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Addconfiguration
        WITH SOURCE_TOPIC "messaging/apprise-api/config/add"
        WITH DESTINATION_TOPIC "messaging/apprise-api/config/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/add/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Geturls
        WITH SOURCE_TOPIC "messaging/apprise-api/urls/get"
        WITH DESTINATION_TOPIC "messaging/apprise-api/urls/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/json/urls/{value.json.key}?privacy={value.json.privacy}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getstatus | GET | `/status` | `messaging/apprise-api/status/get` | `messaging/apprise-api/status/get/response` |
| Getdetails | GET | `/details` | `messaging/apprise-api/details/get` | `messaging/apprise-api/details/get/response` |
| Notifystateless | POST | `/notify` | `messaging/apprise-api/notify/stateless` | `messaging/apprise-api/notify/stateless/response` |
| Notifybykey | POST | `/notify/{key}` | `messaging/apprise-api/notify/by-key` | `messaging/apprise-api/notify/by-key/response` |
| Addconfiguration | POST | `/add/{key}` | `messaging/apprise-api/config/add` | `messaging/apprise-api/config/add/response` |
| Geturls | GET | `/json/urls/{key}` | `messaging/apprise-api/urls/get` | `messaging/apprise-api/urls/get/response` |

## Auth

| Mode | How |
| - | - |
| Open lab instance | No credentials; check with `GET /status` |
| Global Basic Auth | `APPRISE_USER` + `APPRISE_PASSWORD` (Hub `GET SECRET`) on the connector config |
| Per-key Basic | Credentials assigned to a Config ID; still use Basic header |
| Stateful key | Path `{key}` from MQTT `value.json.key` (env alias `APPRISE_KEY` / `APPRISE_CONFIG_ID`) |

Never put real passwords in the `.lot` file. Optional Basic:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH USERNAME "YOUR_APPRISE_USER"
WITH PASSWORD GET SECRET "APPRISE_PASSWORD"
```

## Example payloads

**Stateless notify** (urls in body):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "urls": ["json://localhost"],
  "title": "Zone A",
  "body": "RMS high",
  "type": "warning"
}
```

**Stateful notify** (saved key):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "key": "plant-alerts",
  "title": "Zone A trip",
  "body": "E-stop engaged",
  "type": "failure"
}
```

**Add configuration:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "key": "plant-alerts",
  "urls": ["tgram://BOT_TOKEN/CHAT_ID/"]
}
```

## BASE\_ADDRESS

Self-hosted only — there is no shared public Apprise API tenant for Coreflux alert:

| Env / setting | Example |
| - | - |
| `APPRISE_BASE_URL` → `BASE_ADDRESS` | `http://localhost:8000` |
| HTTPS reverse proxy | `https://apprise.your-plant.local` |
| Placeholder in package | `https://apprise.example.com` |

If you use plain HTTP, set `WITH USE_SSL "false"`.

## Server / inbound companion

This package is **client-mode first** (MQTT → HTTP to Apprise). Apprise API does not provide a general inbound webhook-to-MQTT surface for Coreflux; notification *destinations* are Apprise URLs (Slack, Telegram, email, …). If you need HTTP callbacks into the broker, use a separate `ENABLE_SERVER` companion connector (e.g. ntfy action buttons or your own webhook) — not included here.

## Deploy notes

* Deploy `AppriseApiRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/apprise-api](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/apprise-api)

## Sources

* [Apprise API](https://github.com/caronc/apprise-api)
* [OpenAPI / swagger.yaml](https://github.com/caronc/apprise-api/blob/master/swagger.yaml)
* [API Endpoints](https://appriseit.com/api/endpoints/)
* [Apprise library](https://github.com/caronc/apprise)
* Docker image `caronc/apprise`


# Aras Innovator Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/aras-innovator-api

Connect Coreflux LoT to Aras Innovator PLM to query parts, BOMs, documents, problem reports and ECNs over the OData REST API with OAuth tokens

Technical Preview

## Overview

Client-mode REST API connector for Aras Innovator PLM: query parts, read BOMs, where-used, CAD and document links, documents and files, problem reports, ECRs and ECNs, and turn an inspection or quality event into a problem report or a BOM line, through the Aras RESTful API (OData v4) with OAuth tokens.

This is one of the templates in the Aras Innovator REST API app (`aras-innovator`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 Bearer from the Aras OAuth server (\<alias>/oauthserver/connect/token). ArasInnovatorAuth GetToken: password grant, scope Innovator, client\_id (IOMApp by default), username, password = MD5 hex hash (SHA on FIPS servers), database; returns access\_token (3600 s default), token\_type Bearer. RefreshToken: refresh\_token grant for offline\_access logins (14+ PKCE, client InnovatorClient). ArasInnovatorApi events take payload field authorization = 'Bearer \<token>'. DATABASE / AUTHUSER / AUTHPASSWORD headers are unsupported since 12.0.

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Aras Innovator Api connector | no |
| `BaseUrl` | string | Aras Innovator Api base URL without trailing slash (e.g. https\://YOUR\_ARAS\_SERVER) | yes |

`BASE_ADDRESS` default: `https://YOUR_ARAS_SERVER`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `QueryParts` | GET | `/InnovatorServer/Server/odata/Part?$filter={value.json.filter}&$top={value.json.top}` | `mes/aras-innovator/parts/query` | `mes/aras-innovator/parts/query/response` | `authorization`, `filter`, `top` |
| `GetPart` | GET | `/InnovatorServer/Server/odata/Part('{value.json.id}')` | `mes/aras-innovator/part/get` | `mes/aras-innovator/part/get/response` | `authorization`, `id` |
| `GetPartBom` | GET | `/InnovatorServer/Server/odata/Part('{value.json.id}')/Part_BOM?$expand=related_id` | `mes/aras-innovator/part-bom/get` | `mes/aras-innovator/part-bom/get/response` | `authorization`, `id` |
| `GetPartWhereUsed` | GET | `/InnovatorServer/Server/odata/Part?$filter=[Part%20BOM]/related_id/item_number%20eq%20'{value.json.item_number}'&$select=id,item_number,name,state` | `mes/aras-innovator/part-where-used/get` | `mes/aras-innovator/part-where-used/get/response` | `authorization`, `item_number` |
| `GetPartCad` | GET | `/InnovatorServer/Server/odata/Part('{value.json.id}')/Part_CAD?$expand=related_id` | `mes/aras-innovator/part-cad/get` | `mes/aras-innovator/part-cad/get/response` | `authorization`, `id` |
| `GetPartDocuments` | GET | `/InnovatorServer/Server/odata/Part('{value.json.id}')/Part_Document?$expand=related_id` | `mes/aras-innovator/part-documents/get` | `mes/aras-innovator/part-documents/get/response` | `authorization`, `id` |
| `QueryDocuments` | GET | `/InnovatorServer/Server/odata/Document?$filter={value.json.filter}&$top={value.json.top}` | `mes/aras-innovator/documents/query` | `mes/aras-innovator/documents/query/response` | `authorization`, `filter`, `top` |
| `GetDocument` | GET | `/InnovatorServer/Server/odata/Document('{value.json.id}')` | `mes/aras-innovator/document/get` | `mes/aras-innovator/document/get/response` | `authorization`, `id` |
| `GetDocumentFiles` | GET | `/InnovatorServer/Server/odata/Document('{value.json.id}')/Document_File?$expand=related_id` | `mes/aras-innovator/document-files/get` | `mes/aras-innovator/document-files/get/response` | `authorization`, `id` |
| `GetFileInfo` | GET | `/InnovatorServer/Server/odata/File('{value.json.id}')` | `mes/aras-innovator/file/get` | `mes/aras-innovator/file/get/response` | `authorization`, `id` |
| `ListProblemReports` | GET | `/InnovatorServer/Server/odata/PR?$filter={value.json.filter}&$top={value.json.top}` | `mes/aras-innovator/problem-reports/list` | `mes/aras-innovator/problem-reports/list/response` | `authorization`, `filter`, `top` |
| `GetProblemReport` | GET | `/InnovatorServer/Server/odata/PR('{value.json.id}')?$expand=affected_item` | `mes/aras-innovator/problem-report/get` | `mes/aras-innovator/problem-report/get/response` | `authorization`, `id` |
| `CreateProblemReport` | POST | `/InnovatorServer/Server/odata/PR` | `mes/aras-innovator/problem-report/create` | `mes/aras-innovator/problem-report/create/response` | `authorization`, `request` |
| `ListEcrs` | GET | `/InnovatorServer/Server/odata/ECR?$filter={value.json.filter}&$top={value.json.top}` | `mes/aras-innovator/ecrs/list` | `mes/aras-innovator/ecrs/list/response` | `authorization`, `filter`, `top` |
| `ListEcns` | GET | `/InnovatorServer/Server/odata/ECN?$filter={value.json.filter}&$top={value.json.top}` | `mes/aras-innovator/ecns/list` | `mes/aras-innovator/ecns/list/response` | `authorization`, `filter`, `top` |
| `AddPartBomLine` | POST | `/InnovatorServer/Server/odata/Part_BOM` | `mes/aras-innovator/part-bom/create` | `mes/aras-innovator/part-bom/create/response` | `authorization`, `request` |
| `QueryItems` | GET | `/InnovatorServer/Server/odata/{value.json.itemtype}?$filter={value.json.filter}&$top={value.json.top}` | `mes/aras-innovator/items/query` | `mes/aras-innovator/items/query/response` | `authorization`, `filter`, `itemtype`, `top` |
| `QueryItemTypes` | GET | `/InnovatorServer/Server/odata/ItemType?$filter={value.json.filter}&$select=id,name,label` | `mes/aras-innovator/item-types/query` | `mes/aras-innovator/item-types/query/response` | `authorization`, `filter` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode ARAS_INNOVATOR"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ArasInnovatorApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ARAS_SERVER"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT QueryParts
        WITH SOURCE_TOPIC "mes/aras-innovator/parts/query"
        WITH DESTINATION_TOPIC "mes/aras-innovator/parts/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Part?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetPart
        WITH SOURCE_TOPIC "mes/aras-innovator/part/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/part/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Part('{value.json.id}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetPartBom
        WITH SOURCE_TOPIC "mes/aras-innovator/part-bom/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/part-bom/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Part('{value.json.id}')/Part_BOM?$expand=related_id"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetPartWhereUsed
        WITH SOURCE_TOPIC "mes/aras-innovator/part-where-used/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/part-where-used/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Part?$filter=[Part%20BOM]/related_id/item_number%20eq%20'{value.json.item_number}'&$select=id,item_number,name,state"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetPartCad
        WITH SOURCE_TOPIC "mes/aras-innovator/part-cad/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/part-cad/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Part('{value.json.id}')/Part_CAD?$expand=related_id"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetPartDocuments
        WITH SOURCE_TOPIC "mes/aras-innovator/part-documents/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/part-documents/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Part('{value.json.id}')/Part_Document?$expand=related_id"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT QueryDocuments
        WITH SOURCE_TOPIC "mes/aras-innovator/documents/query"
        WITH DESTINATION_TOPIC "mes/aras-innovator/documents/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Document?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDocument
        WITH SOURCE_TOPIC "mes/aras-innovator/document/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/document/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Document('{value.json.id}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDocumentFiles
        WITH SOURCE_TOPIC "mes/aras-innovator/document-files/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/document-files/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Document('{value.json.id}')/Document_File?$expand=related_id"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetFileInfo
        WITH SOURCE_TOPIC "mes/aras-innovator/file/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/file/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/File('{value.json.id}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListProblemReports
        WITH SOURCE_TOPIC "mes/aras-innovator/problem-reports/list"
        WITH DESTINATION_TOPIC "mes/aras-innovator/problem-reports/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/PR?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetProblemReport
        WITH SOURCE_TOPIC "mes/aras-innovator/problem-report/get"
        WITH DESTINATION_TOPIC "mes/aras-innovator/problem-report/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/PR('{value.json.id}')?$expand=affected_item"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateProblemReport
        WITH SOURCE_TOPIC "mes/aras-innovator/problem-report/create"
        WITH DESTINATION_TOPIC "mes/aras-innovator/problem-report/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/InnovatorServer/Server/odata/PR"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "Prefer" "return=representation"
        WITH BODY "{value.json.request}"
    ADD EVENT ListEcrs
        WITH SOURCE_TOPIC "mes/aras-innovator/ecrs/list"
        WITH DESTINATION_TOPIC "mes/aras-innovator/ecrs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/ECR?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListEcns
        WITH SOURCE_TOPIC "mes/aras-innovator/ecns/list"
        WITH DESTINATION_TOPIC "mes/aras-innovator/ecns/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/ECN?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT AddPartBomLine
        WITH SOURCE_TOPIC "mes/aras-innovator/part-bom/create"
        WITH DESTINATION_TOPIC "mes/aras-innovator/part-bom/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/InnovatorServer/Server/odata/Part_BOM"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "Prefer" "return=representation"
        WITH BODY "{value.json.request}"
    ADD EVENT QueryItems
        WITH SOURCE_TOPIC "mes/aras-innovator/items/query"
        WITH DESTINATION_TOPIC "mes/aras-innovator/items/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/{value.json.itemtype}?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT QueryItemTypes
        WITH SOURCE_TOPIC "mes/aras-innovator/item-types/query"
        WITH DESTINATION_TOPIC "mes/aras-innovator/item-types/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/InnovatorServer/Server/odata/ItemType?$filter={value.json.filter}&$select=id,name,label"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `QueryParts` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/aras-innovator/parts/query/response' &
mosquitto_pub -t 'mes/aras-innovator/parts/query' -m '{"authorization": "<authorization>", "filter": "<filter>", "top": "<top>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Asana
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/asana

Client-mode REST API connector for a curated Asana REST API v1.0 slice: create/update tasks, list project tasks, users/me check, workspaces, and webhook create

Technical Preview

## Overview

A client-mode connector for a **curated work-management** slice of the [Asana REST API](https://developers.asana.com/reference/rest-api-reference):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST tasks | `POST /tasks` | Create task from alarm / MQTT (body `{"data":{…}}`) |
| PUT tasks/\{gid} | `PUT /tasks/{task_gid}` | Update task fields / complete |
| GET projects/\{gid}/tasks | `GET /projects/{project_gid}/tasks` | List project tasks |
| GET users/me | `GET /users/{user_gid}` with `me` | Credential check → `data.gid` |
| GET workspaces | `GET /workspaces` | Workspace discovery |
| GET tasks/\{gid} | `GET /tasks/{task_gid}` | Single task read |
| POST webhooks | `POST /webhooks` | Register Asana → HTTPS target |

Default `BASE_ADDRESS` is `https://app.asana.com/api/1.0`. Topics use `devops/asana/<object>/<verb>`.

> [!NOTE]
>
> Auth is **Bearer** personal access token or OAuth 2.0 access token (`Authorization: Bearer …`). Prefer Hub secret `ASANA_ACCESS_TOKEN` (aliases `ASANA_PAT`, `ASANA_TOKEN`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Asana REST API v1.0
# Auth: Bearer {value.json.access_token} (PAT or OAuth)
# BASE_ADDRESS: https://app.asana.com/api/1.0

DEFINE CONNECTOR AsanaRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://app.asana.com/api/1.0"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuser
        WITH SOURCE_TOPIC "devops/asana/user/get"
        WITH DESTINATION_TOPIC "devops/asana/user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/users/{value.json.user_gid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getworkspaces
        WITH SOURCE_TOPIC "devops/asana/workspace/list"
        WITH DESTINATION_TOPIC "devops/asana/workspace/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/workspaces"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createtask
        WITH SOURCE_TOPIC "devops/asana/task/create"
        WITH DESTINATION_TOPIC "devops/asana/task/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Updatetask
        WITH SOURCE_TOPIC "devops/asana/task/update"
        WITH DESTINATION_TOPIC "devops/asana/task/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/tasks/{value.json.task_gid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Gettask
        WITH SOURCE_TOPIC "devops/asana/task/get"
        WITH DESTINATION_TOPIC "devops/asana/task/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tasks/{value.json.task_gid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Gettasksforproject
        WITH SOURCE_TOPIC "devops/asana/project/tasks"
        WITH DESTINATION_TOPIC "devops/asana/project/tasks/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/projects/{value.json.project_gid}/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createwebhook
        WITH SOURCE_TOPIC "devops/asana/webhook/create"
        WITH DESTINATION_TOPIC "devops/asana/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuser | GET | `/users/{user_gid}` | `devops/asana/user/get` | `devops/asana/user/get/response` |
| Getworkspaces | GET | `/workspaces` | `devops/asana/workspace/list` | `devops/asana/workspace/list/response` |
| Createtask | POST | `/tasks` | `devops/asana/task/create` | `devops/asana/task/create/response` |
| Updatetask | PUT | `/tasks/{task_gid}` | `devops/asana/task/update` | `devops/asana/task/update/response` |
| Gettask | GET | `/tasks/{task_gid}` | `devops/asana/task/get` | `devops/asana/task/get/response` |
| Gettasksforproject | GET | `/projects/{project_gid}/tasks` | `devops/asana/project/tasks` | `devops/asana/project/tasks/response` |
| Createwebhook | POST | `/webhooks` | `devops/asana/webhook/create` | `devops/asana/webhook/create/response` |

## Auth

1. Create a [personal access token](https://developers.asana.com/docs/personal-access-token) in Asana developer console, **or** obtain an OAuth 2.0 access token.
2. Set connector `BASE_ADDRESS` to `https://app.asana.com/api/1.0`.
3. Pass `access_token` on MQTT JSON payloads so the Bearer header resolves. For path params, also pass `user_gid` / `task_gid` / `project_gid`.
4. Store secrets in Hub / `GET SECRET "ASANA_ACCESS_TOKEN"` (aliases `ASANA_PAT`, `ASANA_TOKEN`). Never commit real credentials.
5. A successful check: `GET /users/me` → **HTTP 200** with `data.gid`. Invalid tokens → **HTTP 401**.

## Example payloads

**getUser:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ASANA_ACCESS_TOKEN",
  "user_gid": "me"
}
```

**createTask:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "data": {
    "name": "Coreflux alarm — Zone A",
    "notes": "RMS exceeded limit",
    "projects": ["YOUR_PROJECT_GID"]
  }
}
```

**updateTask:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "task_gid": "YOUR_TASK_GID",
  "data": {
    "completed": true
  }
}
```

**createWebhook:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "data": {
    "resource": "YOUR_PROJECT_GID",
    "target": "https://YOUR_PUBLIC_HTTPS_CALLBACK/asana-webhook"
  }
}
```

## Server / inbound companion

`POST /webhooks` is **client-mode** registration (MQTT → Asana). Asana then POSTs events to your `target` URL (handshake with `X-Hook-Secret`). Receiving those callbacks into MQTT requires a separate companion `ENABLE_SERVER` connector — not included in `AsanaRestApi.lot`.

## Deploy notes

* Deploy `AsanaRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/asana](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/asana)

## Sources

* [Asana REST API reference](https://developers.asana.com/reference/rest-api-reference)
* [Personal access token](https://developers.asana.com/docs/personal-access-token)
* [OAuth](https://developers.asana.com/docs/oauth)
* [Webhooks guide](https://developers.asana.com/docs/webhooks-guide)
* [Official OpenAPI](https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml)


# Auth0
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/auth0

Client-mode REST API connector for a curated Auth0 Management API v2 slice: list users and create a user

Technical Preview

# Auth0

Client-mode REST API connector for a curated Auth0 Management API v2 slice: list users and create a user.

* Hub category: **Identity**.
* Base: `https://tenant.us.auth0.com`

## Template reference

Generated from the shipped broker template `auth0` (`-connectorCode AUTH0`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Auth0 connector | no |
| `BaseUrl` | string | Auth0 base URL without trailing slash (e.g. [https://tenant.us.auth0.com](https://tenant.us.auth0.com)) | yes |

`BASE_ADDRESS` default: `https://tenant.us.auth0.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listusers` | GET | `/api/v2/users` | `identity/auth0/users/list` | `identity/auth0/users/list/response` | `api_token` |
| `Createuser` | POST | `/api/v2/users` | `identity/auth0/users/create` | `identity/auth0/users/create/response` | `api_token`, `body` |
| `Getuser` | GET | `/api/v2/users/{value.json.user_id}` | `identity/auth0/users/get` | `identity/auth0/users/get/response` | `api_token`, `user_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AUTH0"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Auth0RestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://tenant.us.auth0.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listusers
        WITH SOURCE_TOPIC "identity/auth0/users/list"
        WITH DESTINATION_TOPIC "identity/auth0/users/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/users"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createuser
        WITH SOURCE_TOPIC "identity/auth0/users/create"
        WITH DESTINATION_TOPIC "identity/auth0/users/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/users"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getuser
        WITH SOURCE_TOPIC "identity/auth0/users/get"
        WITH DESTINATION_TOPIC "identity/auth0/users/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/users/{value.json.user_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listusers` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'identity/auth0/users/list/response' &
mosquitto_pub -t 'identity/auth0/users/list' -m '{"api_token": "<api_token>"}'
```


# Autodesk Platform Services Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/autodesk-platform-services-api

LoT connector for Autodesk Platform Services: browse hubs, projects and item versions, read model derivatives, add webhooks and query Fusion BOMs

Technical Preview

## Overview

Client-mode REST API connector for Autodesk Platform Services (APS): browse Data Management hubs, projects, folders, items and versions to show the latest design or drawing revision as a work instruction, read Model Derivative manifests and properties, subscribe webhooks to new versions, and query Fusion component properties and BOMs through the Manufacturing Data Model GraphQL API, with OAuth 2.0 tokens.

This is one of the templates in the Autodesk Platform Services (Data Management, Manufacturing Data Model, Fusion) REST API app (`autodesk-platform-services`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 (APS Authentication v2, POST /authentication/v2/token). Client authentication: Authorization: Basic base64(client\_id:client\_secret) from payload field authorization. GetToken = client\_credentials (2-legged, scopes URL-encoded space-separated, e.g. data:read%20data:create); ExchangeCode = authorization\_code (3-legged, after one browser sign-in to /authentication/v2/authorize); RefreshToken = refresh\_token (rotates the refresh token). API events take authorization = 'Bearer \<access\_token>'. Data Management / Model Derivative / Webhooks accept 2-legged (BIM 360 Docs / ACC after the account admin adds the app as an integration) or 3-legged; Fusion Team / BIM 360 Team / A360 data and all Manufacturing Data Model calls require 3-legged.

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Autodesk Platform Services Api connector | no |
| `BaseUrl` | string | Autodesk Platform Services Api base URL without trailing slash (e.g. [https://developer.api.autodesk.com](https://developer.api.autodesk.com)) | yes |

`BASE_ADDRESS` default: `https://developer.api.autodesk.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ListHubs` | GET | `/project/v1/hubs` | `mes/autodesk-platform-services/hubs/list` | `mes/autodesk-platform-services/hubs/list/response` | `authorization` |
| `ListProjects` | GET | `/project/v1/hubs/{value.json.hub_id}/projects` | `mes/autodesk-platform-services/projects/list` | `mes/autodesk-platform-services/projects/list/response` | `authorization`, `hub_id` |
| `GetProject` | GET | `/project/v1/hubs/{value.json.hub_id}/projects/{value.json.project_id}` | `mes/autodesk-platform-services/project/get` | `mes/autodesk-platform-services/project/get/response` | `authorization`, `hub_id`, `project_id` |
| `ListTopFolders` | GET | `/project/v1/hubs/{value.json.hub_id}/projects/{value.json.project_id}/topFolders` | `mes/autodesk-platform-services/top-folders/list` | `mes/autodesk-platform-services/top-folders/list/response` | `authorization`, `hub_id`, `project_id` |
| `ListFolderContents` | GET | `/data/v1/projects/{value.json.project_id}/folders/{value.json.folder_id}/contents` | `mes/autodesk-platform-services/folder-contents/list` | `mes/autodesk-platform-services/folder-contents/list/response` | `authorization`, `folder_id`, `project_id` |
| `SearchFolder` | GET | `/data/v1/projects/{value.json.project_id}/folders/{value.json.folder_id}/search?{value.json.filter}` | `mes/autodesk-platform-services/folder/search` | `mes/autodesk-platform-services/folder/search/response` | `authorization`, `filter`, `folder_id`, `project_id` |
| `GetItem` | GET | `/data/v1/projects/{value.json.project_id}/items/{value.json.item_id}` | `mes/autodesk-platform-services/item/get` | `mes/autodesk-platform-services/item/get/response` | `authorization`, `item_id`, `project_id` |
| `GetItemTip` | GET | `/data/v1/projects/{value.json.project_id}/items/{value.json.item_id}/tip` | `mes/autodesk-platform-services/item-tip/get` | `mes/autodesk-platform-services/item-tip/get/response` | `authorization`, `item_id`, `project_id` |
| `ListItemVersions` | GET | `/data/v1/projects/{value.json.project_id}/items/{value.json.item_id}/versions` | `mes/autodesk-platform-services/item-versions/list` | `mes/autodesk-platform-services/item-versions/list/response` | `authorization`, `item_id`, `project_id` |
| `GetVersion` | GET | `/data/v1/projects/{value.json.project_id}/versions/{value.json.version_id}` | `mes/autodesk-platform-services/version/get` | `mes/autodesk-platform-services/version/get/response` | `authorization`, `project_id`, `version_id` |
| `ListVersionDownloads` | GET | `/data/v1/projects/{value.json.project_id}/versions/{value.json.version_id}/downloads` | `mes/autodesk-platform-services/version-downloads/list` | `mes/autodesk-platform-services/version-downloads/list/response` | `authorization`, `project_id`, `version_id` |
| `GetManifest` | GET | `/modelderivative/v2/designdata/{value.json.urn}/manifest` | `mes/autodesk-platform-services/manifest/get` | `mes/autodesk-platform-services/manifest/get/response` | `authorization`, `region`, `urn` |
| `ListModelViews` | GET | `/modelderivative/v2/designdata/{value.json.urn}/metadata` | `mes/autodesk-platform-services/model-views/list` | `mes/autodesk-platform-services/model-views/list/response` | `authorization`, `region`, `urn` |
| `GetModelProperties` | GET | `/modelderivative/v2/designdata/{value.json.urn}/metadata/{value.json.guid}/properties` | `mes/autodesk-platform-services/model-properties/get` | `mes/autodesk-platform-services/model-properties/get/response` | `authorization`, `guid`, `region`, `urn` |
| `CreateWebhook` | POST | `/webhooks/v1/systems/{value.json.system}/events/{value.json.event}/hooks?region={value.json.region}` | `mes/autodesk-platform-services/webhook/create` | `mes/autodesk-platform-services/webhook/create/response` | `authorization`, `event`, `region`, `request`, `system` |
| `ListWebhooks` | GET | `/webhooks/v1/hooks?region={value.json.region}` | `mes/autodesk-platform-services/webhooks/list` | `mes/autodesk-platform-services/webhooks/list/response` | `authorization`, `region` |
| `ListAppWebhooks` | GET | `/webhooks/v1/app/hooks?region={value.json.region}` | `mes/autodesk-platform-services/app-webhooks/list` | `mes/autodesk-platform-services/app-webhooks/list/response` | `authorization`, `region` |
| `ListEventWebhooks` | GET | `/webhooks/v1/systems/{value.json.system}/events/{value.json.event}/hooks?region={value.json.region}` | `mes/autodesk-platform-services/event-webhooks/list` | `mes/autodesk-platform-services/event-webhooks/list/response` | `authorization`, `event`, `region`, `system` |
| `GetWebhook` | GET | `/webhooks/v1/systems/{value.json.system}/events/{value.json.event}/hooks/{value.json.hook_id}?region={value.json.region}` | `mes/autodesk-platform-services/webhook/get` | `mes/autodesk-platform-services/webhook/get/response` | `authorization`, `event`, `hook_id`, `region`, `system` |
| `MdmQuery` | POST | `/mfg/v3/graphql/public` | `mes/autodesk-platform-services/mdm/query` | `mes/autodesk-platform-services/mdm/query/response` | `authorization`, `request` |
| `MdmMutation` | POST | `/mfg/v3/graphql/public` | `mes/autodesk-platform-services/mdm/mutate` | `mes/autodesk-platform-services/mdm/mutate/response` | `authorization`, `request` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AUTODESK_PLATFORM_SERVICES"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AutodeskPlatformServicesApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://developer.api.autodesk.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListHubs
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/hubs/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/hubs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/project/v1/hubs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListProjects
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/projects/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/projects/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/project/v1/hubs/{value.json.hub_id}/projects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetProject
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/project/get"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/project/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/project/v1/hubs/{value.json.hub_id}/projects/{value.json.project_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListTopFolders
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/top-folders/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/top-folders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/project/v1/hubs/{value.json.hub_id}/projects/{value.json.project_id}/topFolders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListFolderContents
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/folder-contents/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/folder-contents/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/projects/{value.json.project_id}/folders/{value.json.folder_id}/contents"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT SearchFolder
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/folder/search"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/folder/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/projects/{value.json.project_id}/folders/{value.json.folder_id}/search?{value.json.filter}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetItem
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/item/get"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/item/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/projects/{value.json.project_id}/items/{value.json.item_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetItemTip
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/item-tip/get"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/item-tip/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/projects/{value.json.project_id}/items/{value.json.item_id}/tip"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListItemVersions
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/item-versions/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/item-versions/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/projects/{value.json.project_id}/items/{value.json.item_id}/versions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetVersion
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/version/get"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/version/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/projects/{value.json.project_id}/versions/{value.json.version_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListVersionDownloads
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/version-downloads/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/version-downloads/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/projects/{value.json.project_id}/versions/{value.json.version_id}/downloads"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetManifest
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/manifest/get"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/manifest/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/modelderivative/v2/designdata/{value.json.urn}/manifest"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "region" "{value.json.region}"
    ADD EVENT ListModelViews
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/model-views/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/model-views/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/modelderivative/v2/designdata/{value.json.urn}/metadata"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "region" "{value.json.region}"
    ADD EVENT GetModelProperties
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/model-properties/get"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/model-properties/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/modelderivative/v2/designdata/{value.json.urn}/metadata/{value.json.guid}/properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "region" "{value.json.region}"
    ADD EVENT CreateWebhook
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/webhook/create"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webhooks/v1/systems/{value.json.system}/events/{value.json.event}/hooks?region={value.json.region}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT ListWebhooks
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/webhooks/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/webhooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webhooks/v1/hooks?region={value.json.region}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListAppWebhooks
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/app-webhooks/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/app-webhooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webhooks/v1/app/hooks?region={value.json.region}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListEventWebhooks
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/event-webhooks/list"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/event-webhooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webhooks/v1/systems/{value.json.system}/events/{value.json.event}/hooks?region={value.json.region}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetWebhook
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/webhook/get"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/webhook/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webhooks/v1/systems/{value.json.system}/events/{value.json.event}/hooks/{value.json.hook_id}?region={value.json.region}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT MdmQuery
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/mdm/query"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/mdm/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mfg/v3/graphql/public"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT MdmMutation
        WITH SOURCE_TOPIC "mes/autodesk-platform-services/mdm/mutate"
        WITH DESTINATION_TOPIC "mes/autodesk-platform-services/mdm/mutate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mfg/v3/graphql/public"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ListHubs` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/autodesk-platform-services/hubs/list/response' &
mosquitto_pub -t 'mes/autodesk-platform-services/hubs/list' -m '{"authorization": "<authorization>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# AVEVA CONNECT data services
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/aveva-connect-data-services

LoT connector for AVEVA CONNECT data services: ingest OMF types, containers and data, list SDS streams and read or write stream data from MQTT

Technical Preview

## Overview

A client-mode connector for a **curated** slice of [AVEVA CONNECT data services](https://docs.aveva.com/bundle/connect-data-services-developer/page/developer-guide/sequential-data-store-dev/sds-quick-start.html) (formerly AVEVA Data Hub / OSIsoft Cloud Services) under your regional host `https://{region}.datahub.connect.aveva.com/api/v1/Tenants/{tenant}/Namespaces/{ns}`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| | `GET /Streams` | List SDS streams in the namespace |
| POST omf (type) | `POST /omf` + `MessageType: type` | OMF type → SDS type |
| POST omf (container) | `POST /omf` + `MessageType: container` | OMF container → SDS stream |
| POST omf (data) | `POST /omf` + `MessageType: data` | High-throughput async ingest (expects **202**) |
| GET Streams/\{id}/Data | `GET /Streams/{streamId}/Data?startIndex=` | Also `endIndex` / `count` |
| PUT Streams/\{id}/Data | `PUT /Streams/{streamId}/Data` | Update/upsert SDS values |

`BASE_ADDRESS` includes tenant and namespace (no trailing slash; endpoints start with `/`). Topics use `historian/aveva-connect-data-services/<object>/<verb>`. Default stub region is `uswe` (US West).

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Tenant + OAuth required.** There is no public CONNECT sandbox. Replace `YOUR_TENANT` / `YOUR_NAMESPACE`, pick your region, and supply an OAuth 2.0 **client credentials** access token. Prefer Hub secrets.

> [!NOTE]
>
> **OMF connection.** For `POST /omf`, map the client-credentials client to an **OMF connection** that targets the namespace (CONNECT portal: Data Management → Connections). Otherwise OMF ingress is unauthorized or not routed.

> [!NOTE]
>
> Prefer Hub secrets for tokens / client secrets.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — AVEVA CONNECT data services
# Auth: OAuth 2.0 client credentials → Bearer {value.json.api_token}
# BASE_ADDRESS: https://uswe.datahub.connect.aveva.com/api/v1/Tenants/YOUR_TENANT/Namespaces/YOUR_NAMESPACE

DEFINE CONNECTOR AvevaConnectDataServicesRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://uswe.datahub.connect.aveva.com/api/v1/Tenants/YOUR_TENANT/Namespaces/YOUR_NAMESPACE"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListStreams
        WITH SOURCE_TOPIC "historian/aveva-connect-data-services/streams/list"
        WITH DESTINATION_TOPIC "historian/aveva-connect-data-services/streams/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Streams"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT PostOmfType
        WITH SOURCE_TOPIC "historian/aveva-connect-data-services/omf/type"
        WITH DESTINATION_TOPIC "historian/aveva-connect-data-services/omf/type/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/omf"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
            ADD "MessageType" "type"
            ADD "MessageFormat" "json"
            ADD "OmfVersion" "1.2"
        WITH BODY "{payload}"
    ADD EVENT PostOmfContainer
        WITH SOURCE_TOPIC "historian/aveva-connect-data-services/omf/container"
        WITH DESTINATION_TOPIC "historian/aveva-connect-data-services/omf/container/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/omf"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
            ADD "MessageType" "container"
            ADD "MessageFormat" "json"
            ADD "OmfVersion" "1.2"
        WITH BODY "{payload}"
    ADD EVENT PostOmfData
        WITH SOURCE_TOPIC "historian/aveva-connect-data-services/omf/data"
        WITH DESTINATION_TOPIC "historian/aveva-connect-data-services/omf/data/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/omf"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
            ADD "MessageType" "data"
            ADD "MessageFormat" "json"
            ADD "OmfVersion" "1.2"
        WITH BODY "{payload}"
    ADD EVENT GetStreamData
        WITH SOURCE_TOPIC "historian/aveva-connect-data-services/streams/data/get"
        WITH DESTINATION_TOPIC "historian/aveva-connect-data-services/streams/data/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Streams/{value.json.streamId}/Data?startIndex={value.json.startIndex}&endIndex={value.json.endIndex}&count={value.json.count}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT PutStreamData
        WITH SOURCE_TOPIC "historian/aveva-connect-data-services/streams/data/put"
        WITH DESTINATION_TOPIC "historian/aveva-connect-data-services/streams/data/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/Streams/{value.json.streamId}/Data"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| ListStreams | GET | `/Streams` | `historian/aveva-connect-data-services/streams/list` | `.../response` |
| PostOmfType | POST | `/omf` (`MessageType: type`) | `.../omf/type` | `.../response` |
| PostOmfContainer | POST | `/omf` (`MessageType: container`) | `.../omf/container` | `.../response` |
| PostOmfData | POST | `/omf` (`MessageType: data`) | `.../omf/data` | `.../response` |
| GetStreamData | GET | `/Streams/{streamId}/Data?startIndex=&endIndex=&count=` | `.../streams/data/get` | `.../response` |
| PutStreamData | PUT | `/Streams/{streamId}/Data` | `.../streams/data/put` | `.../response` |

## Auth

1. Create a **Client-Credentials** client in CONNECT (Security → Clients) with roles that can read/write SDS streams (and OMF if ingesting).
2. For OMF, create an **OMF connection** and map that client to the target namespace(s).
3. Exchange credentials at the regional token endpoint, e.g.\
   `POST https://uswe.datahub.connect.aveva.com/identity/connect/token`\
   with `grant_type=client_credentials`, `client_id`, `client_secret`.
4. Discovery: `https://uswe.datahub.connect.aveva.com/identity/.well-known/openid-configuration`.
5. Pass the access token on each MQTT payload as `api_token` → header `Authorization: Bearer {value.json.api_token}`.
6. Prefer Hub secrets. Never commit `client_secret` or access tokens.

## Example payloads

**List streams:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_ACCESS_TOKEN"
}
```

**OMF data message (body is OMF JSON; MessageType is set by the event headers):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "containerid": "SimpleStream",
    "values": [
      {
        "Time": "2026-10-04T10:00:00Z",
        "Measurement": 42.5
      }
    ]
  }
]
```

Publish that array as the MQTT payload (and include `api_token` in a wrapper only if your upstream strips non-body keys before `{payload}` — otherwise publish the OMF body alone and pass the token via a Hub secret injection pattern your broker supports). Practical pattern: put `api_token` alongside path fields when the connector uses `{value.json.*}` for path/query, and keep `{payload}` as the full MQTT JSON for PUT/POST when the API accepts extra fields being ignored — for OMF, prefer a clean OMF array body.

**Get stream data:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_ACCESS_TOKEN",
  "streamId": "SimpleStream",
  "startIndex": "2026-10-04T00:00:00Z",
  "endIndex": "2026-10-04T23:59:59Z",
  "count": "1000"
}
```

**Put stream data:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "Time": "2026-10-04T10:00:00Z",
    "State": 0,
    "Measurement": 123.45
  }
]
```

Use `streamId` in the MQTT JSON for the path placeholder; shape the body as an SDS value array.

## Configuration checklist

1. Set `BASE_ADDRESS` region + tenant + namespace.
2. Store OAuth client id/secret (or a short-lived access token) in Hub secrets.
3. Map the client to an OMF connection before using `PostOmf*`.
4. Deploy the `.lot` with `-addConnector` (no `ADD METADATA` in the deployable file).
5. Smoke: publish to `historian/aveva-connect-data-services/streams/list` → expect HTTP 200 on the response topic.

## Sources

* [OMF Ingress](https://docs.aveva.com/bundle/connect-data-services-developer/page/api-reference/data-ingress/omf-ingress/omf-ingress-omf.html)
* [SDS Quick Start](https://docs.aveva.com/bundle/connect-data-services-developer/page/developer-guide/sequential-data-store-dev/sds-quick-start.html)
* [SDS Streams API](https://docs.aveva.com/bundle/connect-data-services-developer/page/api-reference/sequential-data-store/sds-streams.html)
* [CONNECT developer docs (GitHub)](https://github.com/aveva/CONNECT-data-services-developer-docs)
* [OMF samples](https://github.com/AVEVA/AVEVA-Samples-OMF)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [AVEVA PI Web API](/latest/lot-language/routes/rest-api-apps/aveva-pi-web-api) (on-prem sister historian package)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Aveva Mes Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/aveva-mes-api

Connect Coreflux LoT to AVEVA MES Web API V3 to read job queues, work orders and OEE and post production counts, downtime and job state changes

Technical Preview

## Overview

Client-mode REST API connector for AVEVA MES (formerly Wonderware MES): read the job queue, work orders, OEE and utilization, and post production counts, consumption, downtime events and job state changes from MQTT through the MES Web API V3.

This is one of the templates in the AVEVA MES (formerly Wonderware MES) REST API app (`aveva-mes`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

MES security mode OS User or OS Group + AVEVA Identity Manager. Register a service client with RegisterAIMServiceClient.ps1 (InstallFiles/CD-MES/AIMRegistration), POST https\://\<AIM host>/identitymanager/connect/token grant\_type=client\_credentials (form) -> access\_token (24 h default), then Authorization: Bearer \<token> from the MQTT payload field authorization. Service-to-service calls run as the MES Default Background User (system attribute 199).

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Aveva Mes Api connector | no |
| `BaseUrl` | string | Aveva Mes Api base URL without trailing slash (e.g. https\://YOUR\_MES\_SERVER) | yes |

`BASE_ADDRESS` default: `https://YOUR_MES_SERVER`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetOpenApiSpec` | GET | `/mesmw/swagger/docs/v3` | `mes/aveva-mes/openapi/get` | `mes/aveva-mes/openapi/get/response` | `authorization` |
| `ListEntities` | GET | `/mesmw/api/v3/Entity?{value.json.query}` | `mes/aveva-mes/entity/list` | `mes/aveva-mes/entity/list/response` | `authorization`, `query` |
| `GetEntity` | GET | `/mesmw/api/v3/Entity/key?entId={value.json.ent_id}` | `mes/aveva-mes/entity/get` | `mes/aveva-mes/entity/get/response` | `authorization`, `ent_id` |
| `FindEntityId` | GET | `/mesmw/api/v3/Entity/name?entName={value.json.ent_name}&siteName={value.json.site_name}` | `mes/aveva-mes/entity-id/get` | `mes/aveva-mes/entity-id/get/response` | `authorization`, `ent_name`, `site_name` |
| `ListLines` | GET | `/mesmw/api/v3/line` | `mes/aveva-mes/line/list` | `mes/aveva-mes/line/list/response` | `authorization` |
| `ListLineEntities` | GET | `/mesmw/api/v3/LineEntity?{value.json.query}` | `mes/aveva-mes/line-entity/list` | `mes/aveva-mes/line-entity/list/response` | `authorization`, `query` |
| `GetJobQueue` | GET | `/mesmw/api/v3/JobQueue?{value.json.query}` | `mes/aveva-mes/job-queue/get` | `mes/aveva-mes/job-queue/get/response` | `authorization`, `query` |
| `ListWorkOrders` | GET | `/mesmw/api/v3/WO/filter?{value.json.query}` | `mes/aveva-mes/work-order/list` | `mes/aveva-mes/work-order/list/response` | `authorization`, `query` |
| `GetWorkOrder` | GET | `/mesmw/api/v3/WO/key?woId={value.json.wo_id}` | `mes/aveva-mes/work-order/get` | `mes/aveva-mes/work-order/get/response` | `authorization`, `wo_id` |
| `ListWorkOrderJobs` | GET | `/mesmw/api/v3/Jobs?woId={value.json.wo_id}` | `mes/aveva-mes/work-order-jobs/list` | `mes/aveva-mes/work-order-jobs/list/response` | `authorization`, `wo_id` |
| `GetJob` | GET | `/mesmw/api/v3/Jobs/key?woId={value.json.wo_id}&operId={value.json.oper_id}&seqNo={value.json.seq_no}` | `mes/aveva-mes/job/get` | `mes/aveva-mes/job/get/response` | `authorization`, `oper_id`, `seq_no`, `wo_id` |
| `GetJobExec` | GET | `/mesmw/api/v3/JobExec/key?{value.json.query}` | `mes/aveva-mes/job-exec/get` | `mes/aveva-mes/job-exec/get/response` | `authorization`, `query` |
| `GetOeeExec` | GET | `/mesmw/api/v3/OeeExec/key?entId={value.json.ent_id}` | `mes/aveva-mes/oee-exec/get` | `mes/aveva-mes/oee-exec/get/response` | `authorization`, `ent_id` |
| `GetEntityCountsAndDuration` | GET | `/mesmw/api/v3/countsAndDuration/entity?{value.json.query}` | `mes/aveva-mes/counts-duration-entity/get` | `mes/aveva-mes/counts-duration-entity/get/response` | `authorization`, `query` |
| `GetLineCountsAndDuration` | GET | `/mesmw/api/v3/countsAndDuration/line?{value.json.query}` | `mes/aveva-mes/counts-duration-line/get` | `mes/aveva-mes/counts-duration-line/get/response` | `authorization`, `query` |
| `ListUtilStates` | GET | `/mesmw/api/v3/UtilState` | `mes/aveva-mes/util-state/list` | `mes/aveva-mes/util-state/list/response` | `authorization` |
| `ListUtilReasons` | GET | `/mesmw/api/v3/utilreason/flat` | `mes/aveva-mes/util-reason/list` | `mes/aveva-mes/util-reason/list/response` | `authorization` |
| `GetAllowableReasons` | GET | `/mesmw/api/v3/Util/AllowableReasons?entID={value.json.ent_id}` | `mes/aveva-mes/allowable-reason/list` | `mes/aveva-mes/allowable-reason/list/response` | `authorization`, `ent_id` |
| `ListProduction` | GET | `/mesmw/api/v3/Production/filter?{value.json.query}` | `mes/aveva-mes/production/list` | `mes/aveva-mes/production/list/response` | `authorization`, `query` |
| `ListConsumption` | GET | `/mesmw/api/v3/Consumption/filter?{value.json.query}` | `mes/aveva-mes/consumption/list` | `mes/aveva-mes/consumption/list/response` | `authorization`, `query` |
| `ListItems` | GET | `/mesmw/api/v3/Item/filter?{value.json.query}` | `mes/aveva-mes/item/list` | `mes/aveva-mes/item/list/response` | `authorization`, `query` |
| `ListInventory` | GET | `/mesmw/api/v3/ItemInventory/filter?{value.json.query}` | `mes/aveva-mes/inventory/list` | `mes/aveva-mes/inventory/list/response` | `authorization`, `query` |
| `ListLots` | GET | `/mesmw/api/v3/Lot/filter?{value.json.query}` | `mes/aveva-mes/lot/list` | `mes/aveva-mes/lot/list/response` | `authorization`, `query` |
| `ListSamples` | GET | `/mesmw/api/v3/Sample/filter?{value.json.query}` | `mes/aveva-mes/sample/list` | `mes/aveva-mes/sample/list/response` | `authorization`, `query` |
| `AddProductionByJob` | POST | `/mesmw/api/v3/Production/ByJob` | `mes/aveva-mes/production/post` | `mes/aveva-mes/production/post/response` | `authorization`, `body` |
| `AddProductionPostExec` | POST | `/mesmw/api/v3/Production/PostExec` | `mes/aveva-mes/production-post-exec/post` | `mes/aveva-mes/production-post-exec/post/response` | `authorization`, `body` |
| `AddConsumptionByJob` | POST | `/mesmw/api/v3/Consumption/ByJob` | `mes/aveva-mes/consumption/post` | `mes/aveva-mes/consumption/post/response` | `authorization`, `body` |
| `AddUtilizationEvent` | POST | `/mesmw/api/v3/UtilHistory/AddEvent` | `mes/aveva-mes/util-event/post` | `mes/aveva-mes/util-event/post/response` | `authorization`, `body` |
| `AddCurrentUtilizationEvent` | POST | `/mesmw/api/v3/UtilHistory` | `mes/aveva-mes/util-history/post` | `mes/aveva-mes/util-history/post/response` | `authorization`, `body` |
| `StartJob` | PUT | `/mesmw/api/v3/Jobs/Start` | `mes/aveva-mes/job/start` | `mes/aveva-mes/job/start/response` | `authorization`, `body` |
| `PauseJob` | PUT | `/mesmw/api/v3/Jobs/Pause` | `mes/aveva-mes/job/pause` | `mes/aveva-mes/job/pause/response` | `authorization`, `body` |
| `EndJob` | PUT | `/mesmw/api/v3/Jobs/End` | `mes/aveva-mes/job/end` | `mes/aveva-mes/job/end/response` | `authorization`, `body` |
| `ChangeJobStates` | PUT | `/mesmw/api/v3/Jobs/ChangeJobStates` | `mes/aveva-mes/job-states/put` | `mes/aveva-mes/job-states/put/response` | `authorization`, `body` |
| `ReleaseWorkOrder` | PUT | `/mesmw/api/v3/WO/Release` | `mes/aveva-mes/work-order/release` | `mes/aveva-mes/work-order/release/response` | `authorization`, `body` |
| `RecordSampleData` | PUT | `/mesmw/api/v3/Sample/RecordData` | `mes/aveva-mes/sample-data/put` | `mes/aveva-mes/sample-data/put/response` | `authorization`, `body` |
| `MiddlewareAccessXml` | POST | `/mesmw/api/v3/MiddlewareAccess/xml` | `mes/aveva-mes/middleware-xml/post` | `mes/aveva-mes/middleware-xml/post/response` | `authorization`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AVEVA_MES"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AvevaMesApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_MES_SERVER"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetOpenApiSpec
        WITH SOURCE_TOPIC "mes/aveva-mes/openapi/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/openapi/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/swagger/docs/v3"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListEntities
        WITH SOURCE_TOPIC "mes/aveva-mes/entity/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/entity/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Entity?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetEntity
        WITH SOURCE_TOPIC "mes/aveva-mes/entity/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/entity/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Entity/key?entId={value.json.ent_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT FindEntityId
        WITH SOURCE_TOPIC "mes/aveva-mes/entity-id/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/entity-id/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Entity/name?entName={value.json.ent_name}&siteName={value.json.site_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListLines
        WITH SOURCE_TOPIC "mes/aveva-mes/line/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/line/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/line"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListLineEntities
        WITH SOURCE_TOPIC "mes/aveva-mes/line-entity/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/line-entity/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/LineEntity?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetJobQueue
        WITH SOURCE_TOPIC "mes/aveva-mes/job-queue/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/job-queue/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/JobQueue?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListWorkOrders
        WITH SOURCE_TOPIC "mes/aveva-mes/work-order/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/work-order/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/WO/filter?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetWorkOrder
        WITH SOURCE_TOPIC "mes/aveva-mes/work-order/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/work-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/WO/key?woId={value.json.wo_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListWorkOrderJobs
        WITH SOURCE_TOPIC "mes/aveva-mes/work-order-jobs/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/work-order-jobs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Jobs?woId={value.json.wo_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetJob
        WITH SOURCE_TOPIC "mes/aveva-mes/job/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/job/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Jobs/key?woId={value.json.wo_id}&operId={value.json.oper_id}&seqNo={value.json.seq_no}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetJobExec
        WITH SOURCE_TOPIC "mes/aveva-mes/job-exec/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/job-exec/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/JobExec/key?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetOeeExec
        WITH SOURCE_TOPIC "mes/aveva-mes/oee-exec/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/oee-exec/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/OeeExec/key?entId={value.json.ent_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetEntityCountsAndDuration
        WITH SOURCE_TOPIC "mes/aveva-mes/counts-duration-entity/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/counts-duration-entity/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/countsAndDuration/entity?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetLineCountsAndDuration
        WITH SOURCE_TOPIC "mes/aveva-mes/counts-duration-line/get"
        WITH DESTINATION_TOPIC "mes/aveva-mes/counts-duration-line/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/countsAndDuration/line?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListUtilStates
        WITH SOURCE_TOPIC "mes/aveva-mes/util-state/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/util-state/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/UtilState"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListUtilReasons
        WITH SOURCE_TOPIC "mes/aveva-mes/util-reason/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/util-reason/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/utilreason/flat"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetAllowableReasons
        WITH SOURCE_TOPIC "mes/aveva-mes/allowable-reason/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/allowable-reason/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Util/AllowableReasons?entID={value.json.ent_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListProduction
        WITH SOURCE_TOPIC "mes/aveva-mes/production/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/production/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Production/filter?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListConsumption
        WITH SOURCE_TOPIC "mes/aveva-mes/consumption/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/consumption/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Consumption/filter?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListItems
        WITH SOURCE_TOPIC "mes/aveva-mes/item/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/item/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Item/filter?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListInventory
        WITH SOURCE_TOPIC "mes/aveva-mes/inventory/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/inventory/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/ItemInventory/filter?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListLots
        WITH SOURCE_TOPIC "mes/aveva-mes/lot/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/lot/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Lot/filter?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListSamples
        WITH SOURCE_TOPIC "mes/aveva-mes/sample/list"
        WITH DESTINATION_TOPIC "mes/aveva-mes/sample/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mesmw/api/v3/Sample/filter?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT AddProductionByJob
        WITH SOURCE_TOPIC "mes/aveva-mes/production/post"
        WITH DESTINATION_TOPIC "mes/aveva-mes/production/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mesmw/api/v3/Production/ByJob"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT AddProductionPostExec
        WITH SOURCE_TOPIC "mes/aveva-mes/production-post-exec/post"
        WITH DESTINATION_TOPIC "mes/aveva-mes/production-post-exec/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mesmw/api/v3/Production/PostExec"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT AddConsumptionByJob
        WITH SOURCE_TOPIC "mes/aveva-mes/consumption/post"
        WITH DESTINATION_TOPIC "mes/aveva-mes/consumption/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mesmw/api/v3/Consumption/ByJob"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT AddUtilizationEvent
        WITH SOURCE_TOPIC "mes/aveva-mes/util-event/post"
        WITH DESTINATION_TOPIC "mes/aveva-mes/util-event/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mesmw/api/v3/UtilHistory/AddEvent"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT AddCurrentUtilizationEvent
        WITH SOURCE_TOPIC "mes/aveva-mes/util-history/post"
        WITH DESTINATION_TOPIC "mes/aveva-mes/util-history/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mesmw/api/v3/UtilHistory"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT StartJob
        WITH SOURCE_TOPIC "mes/aveva-mes/job/start"
        WITH DESTINATION_TOPIC "mes/aveva-mes/job/start/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/mesmw/api/v3/Jobs/Start"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT PauseJob
        WITH SOURCE_TOPIC "mes/aveva-mes/job/pause"
        WITH DESTINATION_TOPIC "mes/aveva-mes/job/pause/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/mesmw/api/v3/Jobs/Pause"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT EndJob
        WITH SOURCE_TOPIC "mes/aveva-mes/job/end"
        WITH DESTINATION_TOPIC "mes/aveva-mes/job/end/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/mesmw/api/v3/Jobs/End"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ChangeJobStates
        WITH SOURCE_TOPIC "mes/aveva-mes/job-states/put"
        WITH DESTINATION_TOPIC "mes/aveva-mes/job-states/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/mesmw/api/v3/Jobs/ChangeJobStates"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ReleaseWorkOrder
        WITH SOURCE_TOPIC "mes/aveva-mes/work-order/release"
        WITH DESTINATION_TOPIC "mes/aveva-mes/work-order/release/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/mesmw/api/v3/WO/Release"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT RecordSampleData
        WITH SOURCE_TOPIC "mes/aveva-mes/sample-data/put"
        WITH DESTINATION_TOPIC "mes/aveva-mes/sample-data/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/mesmw/api/v3/Sample/RecordData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT MiddlewareAccessXml
        WITH SOURCE_TOPIC "mes/aveva-mes/middleware-xml/post"
        WITH DESTINATION_TOPIC "mes/aveva-mes/middleware-xml/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mesmw/api/v3/MiddlewareAccess/xml"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetOpenApiSpec` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/aveva-mes/openapi/get/response' &
mosquitto_pub -t 'mes/aveva-mes/openapi/get' -m '{"authorization": "<authorization>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# AVEVA PI Web API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/aveva-pi-web-api

Client-mode REST API connector for AVEVA PI Web API (PI System / FactoryTalk Historian): stream value/recorded, streamset recorded, ad-hoc bulk write, and batch

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [AVEVA PI Web API](https://docs.aveva.com/bundle/pi-web-api/page/topics/getting-started.html) (PI System / FactoryTalk Historian) under your customer host `https://{host}/piwebapi`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| | `GET /system/status` | Uptime / system state |
| GET streams/\{webId}/value | `GET /streams/{webId}/value` | Current or time-specified value |
| (supporting) stream recorded | `GET /streams/{webId}/recorded` | `startTime` / `endTime` / `maxCount` |
| GET streamsets/\{webId}/recorded | `GET /streamsets/{webId}/recorded` | Catalog: `?startTime=` |
| POST streamsets/recorded | `POST /streamsets/recorded` | Ad-hoc bulk write MQTT → PI points |
| POST batch | `POST /batch` | Multi-request dictionary |

`BASE_ADDRESS` is `https://YOUR_PI_HOST/piwebapi` (no trailing slash; endpoints start with `/`). Topics use `historian/aveva-pi-web-api/<object>/<verb>`. Pass stream / element **WebIds** on each MQTT payload.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Customer-hosted.** There is no public PI Web API sandbox. Replace `YOUR_PI_HOST` and supply Basic, Kerberos, or Bearer (OIDC) credentials configured on your instance. Prefer Hub secrets.

> [!NOTE]
>
> **Channels (WebSocket)** for live value change streams are out of scope. This package is **client REST only**. Use host Swagger at `https://{host}/piwebapi/help` for the full controller surface.

> [!NOTE]
>
> Prefer Hub secrets for tokens / passwords.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — AVEVA PI Web API
# Auth: Bearer {value.json.api_token} (or Basic via USERNAME/PASSWORD secrets)
# BASE_ADDRESS: https://YOUR_PI_HOST/piwebapi

DEFINE CONNECTOR AvevaPiWebApiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_PI_HOST/piwebapi"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetSystemStatus
        WITH SOURCE_TOPIC "historian/aveva-pi-web-api/system/status"
        WITH DESTINATION_TOPIC "historian/aveva-pi-web-api/system/status/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT GetStreamValue
        WITH SOURCE_TOPIC "historian/aveva-pi-web-api/streams/value"
        WITH DESTINATION_TOPIC "historian/aveva-pi-web-api/streams/value/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/streams/{value.json.webId}/value"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT GetStreamRecorded
        WITH SOURCE_TOPIC "historian/aveva-pi-web-api/streams/recorded"
        WITH DESTINATION_TOPIC "historian/aveva-pi-web-api/streams/recorded/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/streams/{value.json.webId}/recorded?startTime={value.json.startTime}&endTime={value.json.endTime}&maxCount={value.json.maxCount}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT GetStreamSetRecorded
        WITH SOURCE_TOPIC "historian/aveva-pi-web-api/streamsets/recorded"
        WITH DESTINATION_TOPIC "historian/aveva-pi-web-api/streamsets/recorded/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/streamsets/{value.json.webId}/recorded?startTime={value.json.startTime}&endTime={value.json.endTime}&maxCount={value.json.maxCount}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT PostStreamSetsRecorded
        WITH SOURCE_TOPIC "historian/aveva-pi-web-api/streamsets/write"
        WITH DESTINATION_TOPIC "historian/aveva-pi-web-api/streamsets/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/streamsets/recorded"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT PostBatch
        WITH SOURCE_TOPIC "historian/aveva-pi-web-api/batch/execute"
        WITH DESTINATION_TOPIC "historian/aveva-pi-web-api/batch/execute/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/batch"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| GetSystemStatus | GET | `/system/status` | `historian/aveva-pi-web-api/system/status` | `.../response` |
| GetStreamValue | GET | `/streams/{webId}/value` | `historian/aveva-pi-web-api/streams/value` | `.../response` |
| GetStreamRecorded | GET | `/streams/{webId}/recorded?startTime=&endTime=&maxCount=` | `historian/aveva-pi-web-api/streams/recorded` | `.../response` |
| GetStreamSetRecorded | GET | `/streamsets/{webId}/recorded?startTime=&endTime=&maxCount=` | `historian/aveva-pi-web-api/streamsets/recorded` | `.../response` |
| PostStreamSetsRecorded | POST | `/streamsets/recorded` | `historian/aveva-pi-web-api/streamsets/write` | `.../response` |
| PostBatch | POST | `/batch` | `historian/aveva-pi-web-api/batch/execute` | `.../response` |

## Auth

**Bearer (OIDC) — default in the template:**

1. Obtain an access token from your PI Web API OpenID Connect / identity provider configuration.
2. Pass `api_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.api_token}`
3. Store the token in Hub secrets / `GET SECRET "PI_WEB_API_TOKEN"`. Never commit real credentials.

**Basic (optional):**

1. Uncomment `WITH USERNAME` / `WITH PASSWORD GET SECRET "PI_WEB_API_PASSWORD"` on `REST_API_CONFIG`, **or** send `Authorization: Basic <base64(user:pass)>` by adjusting the header scheme and payload field.
2. Map the identity to a PI / AF identity with read/write rights for the target points.

Kerberos is supported by PI Web API deployments but is not expressed in this MQTT client template.

## Example payloads

**System status:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "api_token": "YOUR_OIDC_OR_BEARER_TOKEN" }
```

**Stream value:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OIDC_OR_BEARER_TOKEN",
  "webId": "YOUR_POINT_OR_ATTRIBUTE_WEBID"
}
```

**Stream set recorded:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OIDC_OR_BEARER_TOKEN",
  "webId": "YOUR_ELEMENT_WEBID",
  "startTime": "*-1h",
  "endTime": "*",
  "maxCount": "1000"
}
```

**Ad-hoc write (`PostStreamSetsRecorded`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OIDC_OR_BEARER_TOKEN",
  "Items": [
    {
      "WebId": "YOUR_POINT_WEBID",
      "Items": [
        { "Timestamp": "*", "Value": 42.5 }
      ]
    }
  ]
}
```

The HTTP body is the full MQTT `{payload}` (include only fields PI Web API expects).

## Deploy notes

* Deployable file: `AvevaPiWebApiRestApi.lot` — **no** `ADD METADATA`.
* Hub catalog sidecar: `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Replace `YOUR_PI_HOST` before use. TLS: keep `USE_SSL "true"` for HTTPS hosts.
* Obtain WebIds via Points / Attributes / Elements search on your host (or batch step 1) before stream calls.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app catalog](/latest/lot-language/routes/rest-api-apps)
* [AVEVA PI Web API getting started](https://docs.aveva.com/bundle/pi-web-api/page/topics/getting-started.html)
* [Stream controller](https://docs.aveva.com/bundle/pi-web-api-reference/page/help/controllers/stream.html)
* [StreamSet controller](https://docs.aveva.com/bundle/pi-web-api-reference/page/help/controllers/streamset.html)
* [Batch controller](https://docs.aveva.com/bundle/pi-web-api-reference/page/help/controllers/batch.html)


# AWS IoT Core
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/aws-iot-core

Client-mode REST API connector for a curated AWS IoT Core slice: HTTPS Publish, Device Shadow GET/POST, CreateJob (OTA), and ListThings

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) covering registry, Jobs/OTA, classic Device Shadow, and HTTPS data-plane publish (no MQTT bridge):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET ListThings | `GET /things` | Control-plane credential check |
| POST CreateJob (OTA) | `PUT /jobs/{jobId}` | AWS uses **PUT** (catalog named it POST CreateJob) |
| GET things/\{name}/shadow | `GET /things/{thingName}/shadow` | Classic Device Shadow |
| POST things/\{name}/shadow | `POST /things/{thingName}/shadow` | Classic Device Shadow update |
| POST topics/\{topic} | `POST /topics/{topic}?qos=0\|1` | Data-plane HTTPS publish — switch BASE to ATS endpoint |

Default `BASE_ADDRESS` is control-plane `https://iot.eu-west-1.amazonaws.com` (no trailing slash; substitute `{region}`). Topics use `cloud-iot/aws-iot-core/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Data-plane Publish:** set `BASE_ADDRESS` to your ATS endpoint from `aws iot describe-endpoint --endpoint-type iot:Data-ATS` (for example `https://xxxxxx-ats.iot.eu-west-1.amazonaws.com`). SigV4 service name on the data plane is `iotdevicegateway` (port 443). X.509 on `:8443` is AWS-supported but outside this LoT template.

> [!NOTE]
>
> **Control-plane SigV4 service name** is `iot`. Pass `Authorization`, `x-amz-date`, and `x-amz-content-sha256` from an upstream signer via MQTT JSON placeholders. Prefer Hub secrets for AWS keys — never commit them into the `.lot`.

> [!NOTE]
>
> Prefer Hub secrets for AWS keys used by an upstream SigV4 signer.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — AWS IoT Core curated slice
# Auth: SigV4 via {value.json.authorization}, {value.json.x_amz_date},
#       {value.json.x_amz_content_sha256}
# BASE_ADDRESS: https://iot.eu-west-1.amazonaws.com (control plane)

DEFINE CONNECTOR AwsIotCoreRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://iot.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListThings
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/things/list"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/things/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/things?maxResults={value.json.max_results}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT CreateJob
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/jobs/create"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/jobs/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/jobs/{value.json.job_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT GetThingShadow
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/shadow/get"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/shadow/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/things/{value.json.thing_name}/shadow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT UpdateThingShadow
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/shadow/update"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/shadow/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/things/{value.json.thing_name}/shadow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT PublishTopic
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/topics/publish"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/topics/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/topics/{value.json.topic}?qos={value.json.qos}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `AwsIotCoreRestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://iot.eu-west-1.amazonaws.com` (control plane; change region as needed) |
| Topic prefix | `cloud-iot/aws-iot-core/...` |
| Default Content-Type | `application/json` |
| Auth | SigV4 headers from MQTT placeholders |
| Status | Technical preview — needs AWS keys (+ data endpoint for Publish) |

## MQTT topics

| Event | Source | Response |
| - | - | - |
| ListThings | `cloud-iot/aws-iot-core/things/list` | `.../things/list/response` |
| CreateJob | `cloud-iot/aws-iot-core/jobs/create` | `.../jobs/create/response` |
| GetThingShadow | `cloud-iot/aws-iot-core/shadow/get` | `.../shadow/get/response` |
| UpdateThingShadow | `cloud-iot/aws-iot-core/shadow/update` | `.../shadow/update/response` |
| PublishTopic | `cloud-iot/aws-iot-core/topics/publish` | `.../topics/publish/response` |

## Auth details

1. Sign each request with AWS Signature Version 4 using the correct **service name** (`iot` on control plane; `iotdevicegateway` on data-plane Publish).
2. Map signed values into MQTT JSON: `authorization`, `x_amz_date`, `x_amz_content_sha256` (and optional STS session token).
3. Store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` as Hub secrets for the upstream signer — never in the deployable `.lot`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Amazon S3](/latest/lot-language/routes/rest-api-apps/amazon-s3) (same SigV4 placeholder pattern)
* [AWS IoT ListThings](https://docs.aws.amazon.com/iot/latest/apireference/API_ListThings.html)
* [AWS IoT CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)
* [Device Shadow REST API](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-rest-api.html)
* [HTTPS publish](https://docs.aws.amazon.com/iot/latest/developerguide/http.html)


# AWS IoT SiteWise
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/aws-iot-sitewise

Client-mode REST API connector for a curated AWS IoT SiteWise slice: BatchPutAssetPropertyValue, GetAssetPropertyValueHistory, CreateAsset, and ListAssets

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [AWS IoT SiteWise](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) covering property ingest from UNS topics, property history queries, and asset create from Sparkplug birth:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST properties batch put | `POST /properties` | Data-plane BatchPutAssetPropertyValue |
| GET property history | `GET /properties/history` | Data-plane GetAssetPropertyValueHistory |
| POST assets create (Sparkplug birth) | `POST /assets` | Control-plane CreateAsset — switch BASE to `api.iotsitewise` |
| GET ListAssets (checks the token) | `GET /assets` | Control-plane ListAssets — switch BASE to `api.iotsitewise` |

Default `BASE_ADDRESS` is data-plane `https://data.iotsitewise.eu-west-1.amazonaws.com` (no trailing slash; substitute `{region}`). Topics use `cloud-iot/aws-iot-sitewise/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Control-plane ops:** set `BASE_ADDRESS` to `https://api.iotsitewise.{region}.amazonaws.com` for CreateAsset and ListAssets. SigV4 service name on both planes is `iotsitewise`.

> [!NOTE]
>
> **Data-plane SigV4:** Pass `Authorization`, `x-amz-date`, and `x-amz-content-sha256` from an upstream signer via MQTT JSON placeholders. Prefer Hub secrets for AWS keys — never commit them into the `.lot`.

> [!NOTE]
>
> Prefer Hub secrets for AWS keys used by an upstream SigV4 signer.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — AWS IoT SiteWise curated slice
# Auth: SigV4 via {value.json.authorization}, {value.json.x_amz_date},
#       {value.json.x_amz_content_sha256}
# BASE_ADDRESS: https://data.iotsitewise.eu-west-1.amazonaws.com (data plane)

DEFINE CONNECTOR AwsIotSitewiseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://data.iotsitewise.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT BatchPutAssetPropertyValue
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-sitewise/properties/batch-put"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-sitewise/properties/batch-put/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT GetAssetPropertyValueHistory
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-sitewise/properties/history"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-sitewise/properties/history/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/properties/history?propertyAlias={value.json.property_alias}&startDate={value.json.start_date}&endDate={value.json.end_date}&maxResults={value.json.max_results}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT CreateAsset
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-sitewise/assets/create"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-sitewise/assets/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/assets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT ListAssets
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-sitewise/assets/list"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-sitewise/assets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/assets?filter={value.json.filter}&maxResults={value.json.max_results}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `AwsIotSitewiseRestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://data.iotsitewise.eu-west-1.amazonaws.com` (data plane; change region as needed) |
| Topic prefix | `cloud-iot/aws-iot-sitewise/...` |
| Default Content-Type | `application/json` |
| Auth | SigV4 headers from MQTT placeholders (service `iotsitewise`) |
| Status | Technical preview — needs AWS keys + region |

## MQTT topics

| Event | Source | Response |
| - | - | - |
| BatchPutAssetPropertyValue | `cloud-iot/aws-iot-sitewise/properties/batch-put` | `.../properties/batch-put/response` |
| GetAssetPropertyValueHistory | `cloud-iot/aws-iot-sitewise/properties/history` | `.../properties/history/response` |
| CreateAsset | `cloud-iot/aws-iot-sitewise/assets/create` | `.../assets/create/response` |
| ListAssets | `cloud-iot/aws-iot-sitewise/assets/list` | `.../assets/list/response` |

## Auth details

1. Sign each request with AWS Signature Version 4 using service name **`iotsitewise`** (both planes).
2. Map signed values into MQTT JSON: `authorization`, `x_amz_date`, `x_amz_content_sha256` (and optional STS session token).
3. Store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` as Hub secrets for the upstream signer — never in the deployable `.lot`.
4. Use data-plane BASE for BatchPut / history; switch to control-plane BASE (`api.iotsitewise.{region}.amazonaws.com`) for CreateAsset / ListAssets.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [AWS IoT Core](/latest/lot-language/routes/rest-api-apps/aws-iot-core) (same SigV4 placeholder pattern)
* [Amazon S3](/latest/lot-language/routes/rest-api-apps/amazon-s3) (same SigV4 placeholder pattern)
* [BatchPutAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_BatchPutAssetPropertyValue.html)
* [GetAssetPropertyValueHistory](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValueHistory.html)
* [CreateAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_CreateAsset.html)
* [ListAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssets.html)
* [SiteWise endpoints](https://docs.aws.amazon.com/general/latest/gr/iot-sitewise.html)


# Azure Blob Storage and Data Lake Gen2
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-blob-storage-and-data-lake-gen2

Client-mode REST API connector for a curated Azure Blob slice: Put Blob, Append Block, Get Blob, List Blobs, and PUT/GET via SAS URL

Technical Preview

## Overview

A client-mode connector for a **curated IIoT object-storage** slice of the [Azure Blob service REST API](https://learn.microsoft.com/en-us/rest/api/storageservices/blob-service-rest-api) under `https://{account}.blob.core.windows.net`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| | `GET /{container}?restype=container&comp=list` | List Blobs |
| PUT blob | `PUT /{container}/{blob}` | `x-ms-blob-type: BlockBlob` |
| (optional) Create Append Blob | `PUT /{container}/{blob}` | `x-ms-blob-type: AppendBlob`, empty body |
| PUT append block (continuous log) | `PUT /{container}/{blob}?comp=appendblock` | Existing AppendBlob only |
| GET blob | `GET /{container}/{blob}` | Download body |
| (optional) HEAD properties | `HEAD /{container}/{blob}` | Metadata without body |
| PUT / GET via SAS | `PUT/GET {sas_path}` | No Authorization; switch BASE to URL origin |
| Event Grid blob webhook | — | Docs-only; future `ENABLE_SERVER` |

`BASE_ADDRESS` defaults to the placeholder `https://ACCOUNT.blob.core.windows.net` (no trailing slash). Replace `ACCOUNT` with your storage account. Topics use `storage/azure-blob-storage-and-data-lake-gen2/<object>/<verb>`.

> [!NOTE]
>
> **Data Lake Gen2:** hierarchical namespace filesystem REST uses `https://{account}.dfs.core.windows.net`. Keep primary events on the Blob endpoint; swap BASE only when calling DFS path APIs.

> [!NOTE]
>
> **SAS PUT/GET:** set `BASE_ADDRESS` to the SAS URL origin only, put path+query in `sas_path`, and omit Shared Key / Bearer — the query string carries `sv` / `sig`. Ideal for edge devices that must not hold account keys.

> [!NOTE]
>
> **Event Grid** blob created/deleted subscriptions are not inbound HTTP on this client connector. Receiving Event Grid validation and event POSTs needs a separate `ENABLE_SERVER` REST\_API template (not packaged).

> [!NOTE]
>
> Prefer Hub secrets for account keys or Entra client credentials used by an upstream signer.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Azure Blob curated slice
# Auth: SharedKey or Bearer via {value.json.authorization},
#       {value.json.x_ms_date}, {value.json.x_ms_version}
#       — or PutViaSas / GetViaSas (no Authorization)
# BASE_ADDRESS: https://ACCOUNT.blob.core.windows.net

DEFINE CONNECTOR AzureBlobStorageAndDataLakeGen2RestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://ACCOUNT.blob.core.windows.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/octet-stream"
    ADD EVENT Listblobs
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blobs/list"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blobs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.container}?restype=container&comp=list"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "{value.json.x_ms_version}"
    ADD EVENT Putblob
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/put"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.container}/{value.json.blob}"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "x-ms-blob-type" "BlockBlob"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "{value.json.x_ms_version}"
        WITH BODY "{payload}"
    ADD EVENT Createappendblob
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/create-append"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/create-append/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.container}/{value.json.blob}"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/octet-stream"
            ADD "Content-Length" "0"
            ADD "x-ms-blob-type" "AppendBlob"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "{value.json.x_ms_version}"
    ADD EVENT Appendblock
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/append-block"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/append-block/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.container}/{value.json.blob}?comp=appendblock"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "{value.json.x_ms_version}"
        WITH BODY "{payload}"
    ADD EVENT Getblob
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/get"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.container}/{value.json.blob}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "{value.json.x_ms_version}"
    ADD EVENT Getblobproperties
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/head"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/head/response"
        WITH METHOD "HEAD"
        WITH ENDPOINT "/{value.json.container}/{value.json.blob}"
        WITH HEADERS
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "{value.json.x_ms_version}"
    ADD EVENT Putviasas
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/put-via-sas"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/put-via-sas/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "{value.json.sas_path}"
        WITH HEADERS
            ADD "Content-Type" "{value.json.content_type}"
            ADD "x-ms-blob-type" "BlockBlob"
            ADD "x-ms-version" "{value.json.x_ms_version}"
        WITH BODY "{payload}"
    ADD EVENT Getviasas
        WITH SOURCE_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/get-via-sas"
        WITH DESTINATION_TOPIC "storage/azure-blob-storage-and-data-lake-gen2/blob/get-via-sas/response"
        WITH METHOD "GET"
        WITH ENDPOINT "{value.json.sas_path}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "x-ms-version" "{value.json.x_ms_version}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `AzureBlobStorageAndDataLakeGen2RestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://ACCOUNT.blob.core.windows.net` (replace ACCOUNT) |
| Topic prefix | `storage/azure-blob-storage-and-data-lake-gen2/...` |
| Default Content-Type | `application/octet-stream` |
| API version header | `x-ms-version: 2023-11-03` (payload-driven) |
| Hub status | Technical preview (`WITH STATUS "beta"`) |

## Authentication

### Shared Key / Entra Bearer

Blob does **not** use a simple static Bearer for Shared Key. Sign each request or obtain an Entra token and pass:

| MQTT JSON field | HTTP header |
| - | - |
| `authorization` | `Authorization` (`SharedKey account:…` or `Bearer …`) |
| `x_ms_date` | `x-ms-date` (RFC 1123 UTC) |
| `x_ms_version` | `x-ms-version` (e.g. `2023-11-03`) |

Use Hub secrets for account keys / Entra client credentials in an upstream signing helper. Never commit real keys.

### SAS URLs (recommended for edge)

Generate a time-limited service or user-delegation SAS with Azure CLI/SDK/portal. For PutViaSas / GetViaSas:

1. Point `BASE_ADDRESS` at the URL origin.
2. Put path + query into `sas_path`.
3. Omit Authorization — do not re-sign on the broker.

## MQTT topics

| Event | Request topic | Response topic |
| - | - | - |
| ListBlobs | `storage/azure-blob-storage-and-data-lake-gen2/blobs/list` | `…/response` |
| PutBlob | `storage/azure-blob-storage-and-data-lake-gen2/blob/put` | `…/response` |
| CreateAppendBlob | `storage/azure-blob-storage-and-data-lake-gen2/blob/create-append` | `…/response` |
| AppendBlock | `storage/azure-blob-storage-and-data-lake-gen2/blob/append-block` | `…/response` |
| GetBlob | `storage/azure-blob-storage-and-data-lake-gen2/blob/get` | `…/response` |
| GetBlobProperties | `storage/azure-blob-storage-and-data-lake-gen2/blob/head` | `…/response` |
| PutViaSas | `storage/azure-blob-storage-and-data-lake-gen2/blob/put-via-sas` | `…/response` |
| GetViaSas | `storage/azure-blob-storage-and-data-lake-gen2/blob/get-via-sas` | `…/response` |

## Example payloads

**ListBlobs (after signing):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "container": "iiot-rollups",
  "authorization": "SharedKey myaccount:…",
  "x_ms_date": "Sun, 04 Oct 2026 04:00:00 GMT",
  "x_ms_version": "2023-11-03"
}
```

**PutBlob CSV rollup:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "container": "iiot-rollups",
  "blob": "line-a/2026-10-04/rollup.csv",
  "content_type": "text/csv",
  "authorization": "SharedKey myaccount:…",
  "x_ms_date": "Sun, 04 Oct 2026 04:01:00 GMT",
  "x_ms_version": "2023-11-03",
  "payload": "ts,device,temp\n2026-10-04T04:01:00Z,sensor-01,72.5\n"
}
```

**PutViaSas:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "sas_path": "/iiot-rollups/line-a/snapshot.json?sv=2023-11-03&ss=b&srt=o&sp=cw&se=2026-10-04T12:00:00Z&sig=…",
  "content_type": "application/json",
  "x_ms_version": "2023-11-03",
  "payload": "{\"device\":\"sensor-01\",\"temp\":72.5}"
}
```

## References

* [Put Blob](https://learn.microsoft.com/en-us/rest/api/storageservices/put-blob)
* [Append Block](https://learn.microsoft.com/en-us/rest/api/storageservices/append-block)
* [Get Blob](https://learn.microsoft.com/en-us/rest/api/storageservices/get-blob)
* [List Blobs](https://learn.microsoft.com/en-us/rest/api/storageservices/list-blobs)
* [Authorize with Shared Key](https://learn.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key)
* [Delegate access with SAS](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature)
* [Azure Data Lake Storage Gen2](https://learn.microsoft.com/en-us/azure/storage/blobs/data-lake-storage-introduction)
* [Event Grid blob events](https://learn.microsoft.com/en-us/azure/event-grid/event-schema-blob-storage)
* [Coreflux REST API Connectors](/latest/lot-language/routes/rest-api-routes)

## Package status


# Azure Cosmos DB
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-cosmos-db

LoT connector for Azure Cosmos DB for NoSQL: create, upsert, read, replace, list and SQL query documents from MQTT using Entra ID tokens

Technical Preview

## Overview

Client-mode REST API connector for the Azure Cosmos DB for NoSQL data plane: create and upsert and read and replace documents and SQL queries with Entra ID tokens. `BASE_ADDRESS` defaults to `https://YOUR_ACCOUNT.documents.azure.com`. Topics use `data/azure-cosmos-db/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `DocumentCreate` | `POST /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/create` |
| `DocumentUpsert` | `POST /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/upsert` |
| `DocumentGet` | `GET /dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}` | `data/azure-cosmos-db/documents/get` |
| `DocumentReplace` | `PUT /dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}` | `data/azure-cosmos-db/documents/replace` |
| `DocumentQuery` | `POST /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/query` |
| `DocumentsList` | `GET /dbs/{value.json.db}/colls/{value.json.coll}/docs` | `data/azure-cosmos-db/documents/list` |

## Authentication

Microsoft Entra ID (Cosmos DB RBAC): Authorization: \{value.json.authorization} = URL-encoded "type=aad\&ver=1.0\&sig=\<Entra access token>" (scope [https://YOUR\_ACCOUNT.documents.azure.com/.default](https://YOUR_ACCOUNT.documents.azure.com/.default); role Cosmos DB Built-in Data Contributor). A resource token (type=resource) also works. Master-key auth needs a per-request HMAC over verb, resource and date, which the REST\_API connector cannot compute, so it is not supported. x-ms-date (RFC 1123, UTC, within 15 minutes) is passed per payload.

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* partition\_key is a JSON array string, e.g. \["line-1"].
* Entra RBAC covers data-plane operations only; databases and containers are created through ARM / portal.
* DocumentQuery sends \{value.json.body} = \{"query":"SELECT ...","parameters":\[...]} as application/query+json.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AzureCosmosDbRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ACCOUNT.documents.azure.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT DocumentCreate
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/create"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentUpsert
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/upsert"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
            ADD "x-ms-documentdb-is-upsert" "True"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentGet
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/get"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
    ADD EVENT DocumentReplace
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/replace"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/replace/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-partitionkey" "{value.json.partition_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentQuery
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/query"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/query+json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-documentdb-isquery" "True"
            ADD "x-ms-documentdb-query-enablecrosspartition" "True"
            ADD "x-ms-max-item-count" "{value.json.max_items}"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentsList
        WITH SOURCE_TOPIC "data/azure-cosmos-db/documents/list"
        WITH DESTINATION_TOPIC "data/azure-cosmos-db/documents/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/dbs/{value.json.db}/colls/{value.json.coll}/docs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-ms-date" "{value.json.x_ms_date}"
            ADD "x-ms-version" "2018-12-31"
            ADD "x-ms-max-item-count" "{value.json.max_items}"
```

## Sources

* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources](https://learn.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/create-a-document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/create-a-document)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-document)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/replace-a-document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/replace-a-document)
* [https://learn.microsoft.com/en-us/rest/api/cosmos-db/querying-cosmosdb-resources-using-the-rest-api](https://learn.microsoft.com/en-us/rest/api/cosmos-db/querying-cosmosdb-resources-using-the-rest-api)
* [https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-setup-rbac](https://learn.microsoft.com/en-us/azure/cosmos-db/how-to-setup-rbac)


# Azure Data Explorer and Fabric Eventhouse
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-data-explorer-and-fabric-eventhouse

Client-mode REST API connector for Azure Data Explorer (Kusto) and Fabric Eventhouse — KQL query, management commands, and streaming JSON ingest from MQTT

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [Kusto REST API](https://learn.microsoft.com/en-us/kusto/api/rest/?view=azure-data-explorer) used by **Azure Data Explorer** and **Microsoft Fabric Eventhouse**:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST query (KQL) | `POST /v1/rest/query` | Body `{"db","csl"}` — also `POST /v2/rest/query` |
| (supporting) GET query | `GET /v1/rest/query?db=&csl=` | Query-string form |
| POST mgmt | `POST /v1/rest/mgmt` | Management commands (`.show …`) |
| POST ingest JSON | `POST /v1/rest/ingest/{db}/{table}?streamFormat=JSON&mappingName=` | **Streaming** ingest on the **engine** Cluster URI |

Default `BASE_ADDRESS` is `https://YOUR_CLUSTER.YOUR_REGION.kusto.windows.net` (no trailing slash). For Fabric, use the Eventhouse **Query URI**. Topics use `data/azure-data-explorer/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** `Authorization: Bearer &lt;entra_access_token&gt;`. Prefer Hub secrets (`GET SECRET "ADX_ACCESS_TOKEN"` or `"KUSTO_ACCESS_TOKEN"`). Token resource is typically `https://api.kusto.windows.net` or the cluster URI.

> [!NOTE]
>
> **Streaming vs queued ingest:** `/v1/rest/ingest/...` streaming ingest uses the **engine** host (same as query). The portal Data ingestion URI (`ingest-*`) is for queued/bulk pipelines and is not the `BASE_ADDRESS` for this template.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Azure Data Explorer / Fabric Eventhouse
# Auth: Authorization: Bearer {value.json.access_token}
# BASE_ADDRESS: https://YOUR_CLUSTER.YOUR_REGION.kusto.windows.net

DEFINE CONNECTOR AzureDataExplorerRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CLUSTER.YOUR_REGION.kusto.windows.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostQuery
        WITH SOURCE_TOPIC "data/azure-data-explorer/query"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rest/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT PostMgmt
        WITH SOURCE_TOPIC "data/azure-data-explorer/mgmt"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/mgmt/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rest/mgmt"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT PostIngestJson
        WITH SOURCE_TOPIC "data/azure-data-explorer/ingest"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/ingest/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rest/ingest/{value.json.database}/{value.json.table}?streamFormat=JSON&mappingName={value.json.mapping_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
```

## Auth and placeholders

| Placeholder | Meaning |
| - | - |
| `{value.json.access_token}` | Entra ID access token → `Authorization: Bearer …` |
| `{value.json.database}` / `{value.json.table}` | Ingest path segments |
| `{value.json.mapping_name}` | Pre-created ingestion mapping (required for JSON) |
| `{value.json.db}` / `{value.json.csl}` | GET query query-string params |
| `{value.json.client_request_id}` | Optional `x-ms-client-request-id` |
| `{payload}` | JSON body for query/mgmt, or raw JSON record(s) for ingest |

## Template reference

Generated from the shipped broker template `azure-data-explorer-and-fabric-eventhouse` (`-connectorCode AZURE_DATA_EXPLORER_AND_FABRIC_EVENTHOUSE`). It lists every event the template defines.

### Auth

Authorization: Bearer \{value.json.access\_token} (Microsoft Entra ID OAuth 2.0). Prefer GET SECRET ADX\_ACCESS\_TOKEN or KUSTO\_ACCESS\_TOKEN. Token resource typically [https://api.kusto.windows.net](https://api.kusto.windows.net) or the cluster URI. Never commit real credentials.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Azure Data Explorer and Fabric Eventhouse connector | no |
| `BaseUrl` | string | Azure Data Explorer and Fabric Eventhouse base URL without trailing slash (e.g. [https://YOUR\_CLUSTER.YOUR\_REGION.kusto.windows.net](https://YOUR_CLUSTER.YOUR_REGION.kusto.windows.net)) | yes |

`BASE_ADDRESS` default: `https://YOUR_CLUSTER.YOUR_REGION.kusto.windows.net`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `PostQuery` | POST | `/v1/rest/query` | `data/azure-data-explorer/query` | `data/azure-data-explorer/query/response` | `access_token`, `body`, `client_request_id` |
| `PostQueryV2` | POST | `/v2/rest/query` | `data/azure-data-explorer/query-v2` | `data/azure-data-explorer/query-v2/response` | `access_token`, `body`, `client_request_id` |
| `GetQuery` | GET | `/v1/rest/query?db={value.json.db}&csl={value.json.csl}` | `data/azure-data-explorer/query-get` | `data/azure-data-explorer/query-get/response` | `access_token`, `csl`, `db` |
| `PostMgmt` | POST | `/v1/rest/mgmt` | `data/azure-data-explorer/mgmt` | `data/azure-data-explorer/mgmt/response` | `access_token`, `body`, `client_request_id` |
| `PostIngestJson` | POST | `/v1/rest/ingest/{value.json.database}/{value.json.table}?streamFormat=JSON&mappingName={value.json.mapping_name}` | `data/azure-data-explorer/ingest` | `data/azure-data-explorer/ingest/response` | `access_token`, `body`, `client_request_id`, `database`, `mapping_name`, `table` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AZURE_DATA_EXPLORER_AND_FABRIC_EVENTHOUSE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AzureDataExplorerRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CLUSTER.YOUR_REGION.kusto.windows.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostQuery
        WITH SOURCE_TOPIC "data/azure-data-explorer/query"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rest/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-ms-app" "Coreflux"
            ADD "x-ms-client-request-id" "{value.json.client_request_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT PostQueryV2
        WITH SOURCE_TOPIC "data/azure-data-explorer/query-v2"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/query-v2/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/rest/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-ms-app" "Coreflux"
            ADD "x-ms-client-request-id" "{value.json.client_request_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetQuery
        WITH SOURCE_TOPIC "data/azure-data-explorer/query-get"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/query-get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/rest/query?db={value.json.db}&csl={value.json.csl}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-ms-app" "Coreflux"
    ADD EVENT PostMgmt
        WITH SOURCE_TOPIC "data/azure-data-explorer/mgmt"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/mgmt/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rest/mgmt"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-ms-app" "Coreflux"
            ADD "x-ms-client-request-id" "{value.json.client_request_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT PostIngestJson
        WITH SOURCE_TOPIC "data/azure-data-explorer/ingest"
        WITH DESTINATION_TOPIC "data/azure-data-explorer/ingest/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rest/ingest/{value.json.database}/{value.json.table}?streamFormat=JSON&mappingName={value.json.mapping_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-ms-app" "Coreflux"
            ADD "x-ms-client-request-id" "{value.json.client_request_id}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `PostQuery` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'data/azure-data-explorer/query/response' &
mosquitto_pub -t 'data/azure-data-explorer/query' -m '{"access_token": "<access_token>", "body": {}, "client_request_id": "<client_request_id>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Kusto REST API overview](https://learn.microsoft.com/en-us/kusto/api/rest/?view=azure-data-explorer)
* [Query / management request](https://learn.microsoft.com/en-us/kusto/api/rest/request)
* [Streaming ingestion](https://learn.microsoft.com/en-us/kusto/api/rest/streaming-ingest)
* [Authentication](https://learn.microsoft.com/en-us/kusto/api/rest/authentication)
* [Fabric Kusto REST](https://learn.microsoft.com/en-us/kusto/api/rest/?view=microsoft-fabric)


# Azure DevOps
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-devops

Connect Coreflux LoT to Azure DevOps to create and update work items from plant alarms, run WIQL queries, start pipelines and builds and add service hooks

Technical Preview

## Overview

A client-mode connector for the [Azure DevOps Services REST API 7.1](https://learn.microsoft.com/en-us/rest/api/azure/devops/?view=azure-devops-rest-7.1) that connects the plant floor to the engineering backlog and to edge CI/CD. A typical flow creates a Bug or Issue when the broker sees a recurring alarm, adds the readings as a comment, closes the item when the machine recovers, and finds open items with WIQL. On the delivery side it starts a YAML pipeline run or queues a build (for example an edge firmware build or a gateway configuration deployment), polls the run, reads its timeline, logs and artifacts, and cancels or tags builds. Service hook subscriptions send work item, build and pipeline events back to a Coreflux server connector.

One connector carries 43 events (32 GET, 8 POST, 2 PATCH, 1 PUT; 9 writes, no DELETE). Topics use `devops/azure-devops/<object>/<verb>`; each response is published on `<source topic>/response`. `WiqlQuery` and `WorkItemsBatchGet` are read-only POSTs.

## Setup

1. Create an **organization-scoped** personal access token (User settings > Personal access tokens) with only the scopes you need: **Work Items (Read & write)**, **Build (Read & execute)**, **Project and Team (Read)**, and for service hook subscriptions the scopes of the events you subscribe to. Global PATs stop working on December 1, 2026. For unattended use, prefer a Microsoft Entra service principal or managed identity added to the organization as a user.
2. Build the header value once and keep it in a broker secret (for example `AZURE_DEVOPS_AUTHORIZATION`). Inject it in a LoT action with `GET SECRET`. Never retain topics that carry it.
3. Read the project once with `WorkItemTypesList`, `FieldsList` and `ClassificationNodesList` to get the work item types, field reference names and area paths you will write.

## Authentication

Every event sends the payload field `authorization` unchanged as the `Authorization` header:

| Credential | `authorization` value |
| - | - |
| Personal access token | `Basic ` + base64 of `:` + PAT (empty user name) |
| Microsoft Entra ID (service principal, managed identity, user) | `Bearer ` + access token for the Azure DevOps resource `499b84ac-1321-427f-aa17-267ca6975798` (URI `https://app.vssps.visualstudio.com`), scope `.../.default` |

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Basic OnlvdXItcGF0LWhlcmU=", "organization": "contoso", "project": "Plant%20Ops"}
```

Every event also sends `X-TFS-FedAuthRedirect: Suppress`. Without it, a missing, bad or expired credential gets a `302` redirect to the sign-in page (`203` HTML if the client follows it) instead of a `401` JSON error.

> [!WARNING]
>
> On an organization with **public** projects, Azure DevOps treats a bad credential as anonymous: public reads still answer `200` and only private data or writes answer `401`. If reads must come from a real identity, call `ConnectionData` first and check that `authenticatedUser` is not `Anonymous`.

## Organization, project and api-version

The base address is `https://dev.azure.com`; each endpoint starts with `/{organization}`, and project-scoped events continue with `/{project}`. Put both in the payload (URL-encode project names with spaces, for example `Plant%20Ops`). Every endpoint pins its `api-version`: `7.1` (the latest GA version), `7.1-preview.4` for work item comments and `7.1-preview.1` for `ConnectionData`. Preview resources answer `400` to plain `7.1`.

Azure DevOps Server (on-premises) is not covered by this template. It uses `https://<server>/<collection>/` and older API versions.

## Query parameters and bodies

Optional query parameters go in `query`, URL-encoded and **starting with `&`**. The connector appends `query` directly after the pinned `api-version`, for example `&statusFilter=inProgress&$top=20`. Leave `query` empty for defaults. Do not send a lone `&`: an empty parameter makes some endpoints fail (`build/builds` answers `400`, `build/definitions` answers `500`). `WorkItemsList` and `PipelineRunArtifactGet` need their query (`&ids=...`, `&artifactName=...`).

Writes send `body`. Work item create and update take a **JSON Patch** array and are sent as `application/json-patch+json`; everything else is `application/json`.

## Examples

Create a Bug when an alarm repeats (`devops/azure-devops/work-items/create`, `type` = `Bug`; use `&validateOnly=true` in `query` for a dry run):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<secret>", "organization": "contoso", "project": "Plant%20Ops", "type": "Bug", "query": "", "body": [{"op": "add", "path": "/fields/System.Title", "value": "Press 7 over-temperature"}, {"op": "add", "path": "/fields/System.AreaPath", "value": "Plant Ops\\Line 2"}, {"op": "add", "path": "/fields/Microsoft.VSTS.TCM.ReproSteps", "value": "94.2 C at 14:02, limit 85 C"}, {"op": "add", "path": "/fields/System.Tags", "value": "coreflux; line-2"}]}
```

The response holds the new work item `id` and `rev`. Keep the id to update it later.

Close it when the press recovers, with a link to the trend panel (`devops/azure-devops/work-items/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<secret>", "organization": "contoso", "project": "Plant%20Ops", "id": "4711", "query": "", "body": [{"op": "add", "path": "/fields/System.State", "value": "Done"}, {"op": "add", "path": "/fields/System.History", "value": "Back to 71 C at 15:10"}, {"op": "add", "path": "/relations/-", "value": {"rel": "Hyperlink", "url": "https://broker.example.com/panels/press7"}}]}
```

Find open items raised by the broker (`devops/azure-devops/wiql/query`, then `devops/azure-devops/work-items/batch-get` with the returned ids):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<secret>", "organization": "contoso", "project": "Plant%20Ops", "query": "&$top=50", "body": {"query": "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.Tags] CONTAINS 'coreflux' AND [System.State] <> 'Done' ORDER BY [System.ChangedDate] DESC"}}
```

Start an edge deployment pipeline (`devops/azure-devops/pipelines/runs/run`), then poll `devops/azure-devops/pipelines/runs/get` with the returned run id:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<secret>", "organization": "contoso", "project": "Plant%20Ops", "pipeline": "12", "query": "", "body": {"resources": {"repositories": {"self": {"refName": "refs/heads/main"}}}, "templateParameters": {"line": "2", "target": "edge-gw-07"}}}
```

List running builds (`devops/azure-devops/builds/list`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<secret>", "organization": "contoso", "project": "Plant%20Ops", "query": "&statusFilter=inProgress&$top=20"}
```

Send failed builds to a Coreflux server connector (`devops/azure-devops/hooks/subscriptions/create`; organization-level, the project goes in `publisherInputs.projectId`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<secret>", "organization": "contoso", "body": {"publisherId": "tfs", "eventType": "build.complete", "resourceVersion": "1.0", "consumerId": "webHooks", "consumerActionId": "httpRequest", "publisherInputs": {"projectId": "<project guid>", "buildStatus": "failed"}, "consumerInputs": {"url": "https://broker.example.com/azure-devops/events", "httpHeaders": "X-Coreflux-Key:<shared secret>", "resourceDetailsToSend": "minimal"}}}
```

> [!WARNING]
>
> Service hooks post to a public **HTTPS** URL; they cannot target localhost or private address ranges. The receiving side is a separate `ENABLE_SERVER` REST\_API connector, which is not part of this template. Protect it with `basicAuthCredentials` or a shared header in `httpHeaders` (header values are visible to anyone who can read the subscription). Other useful events: `workitem.created`, `workitem.updated` (publisher `tfs`) and `ms.vss-pipelines.run-state-changed-event` (publisher `pipelines`). List them with `HookEventTypesList`. Check deliveries with `HookNotificationsList`.

## Events

| Event | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - |
| `ConnectionData` | `GET` | `/{organization}/_apis/connectionData?api-version=7.1-preview.1` | `devops/azure-devops/connection-data/get` | | Smoke: who the token is (authenticatedUser id / displayName) and the organization instance id. Location service, not in the published specs; needs a -preview api-version (7.1 alone answers 400). Public organizations answer it anonymously. |
| `ProjectsList` | `GET` | `/{organization}/_apis/projects?api-version=7.1{query}` | `devops/azure-devops/projects/list` | | Projects the token can see. query e.g. \&stateFilter=wellFormed&\$top=100 (or empty; page with continuationToken). |
| `ProjectGet` | `GET` | `/{organization}/_apis/projects/{project}?api-version=7.1{query}` | `devops/azure-devops/projects/get` | | One project by name or id. query e.g. \&includeCapabilities=true (process template, source control) or empty. |
| `TeamsList` | `GET` | `/{organization}/_apis/projects/{project}/teams?api-version=7.1{query}` | `devops/azure-devops/teams/list` | | Teams in the project (area-path owners for routing work items). query e.g. &\$top=100 (or empty). |
| `WorkItemCreate` | `POST` | `/{organization}/{project}/_apis/wit/workitems/${type}?api-version=7.1{query}` | `devops/azure-devops/work-items/create` | Yes | Catalog 'POST wit/workitems/$Bug'. Create a Bug / Issue / Task from an alarm with a JSON Patch document (Content-Type application/json-patch+json). type: Bug, Task, Issue, User%20Story, ... (URL-encoded, the $ is in the template). body: \[\{"op":"add","path":"/fields/System.Title","value":"Press 7 over-temperature"},\{"op":"add","path":"/fields/System.AreaPath","value":"Plant\Line 2"},\{"op":"add","path":"/fields/Microsoft.VSTS.TCM.ReproSteps","value":"94.2 C at 14:02"},\{"op":"add","path":"/fields/System.Tags","value":"coreflux; line-2"}]. query e.g. \&validateOnly=true for a dry run, \&suppressNotifications=true, &\$expand=fields (or empty). |
| `WorkItemGet` | `GET` | `/{organization}/{project}/_apis/wit/workitems/{id}?api-version=7.1{query}` | `devops/azure-devops/work-items/get` | | One work item. query e.g. \&fields=System.State,System.AssignedTo or &$expand=relations (or empty; fields and $expand cannot be combined). |
| `WorkItemsList` | `GET` | `/{organization}/{project}/_apis/wit/workitems?api-version=7.1{query}` | `devops/azure-devops/work-items/list` | | Up to 200 work items by id. query (required): \&ids=101,102,103 plus e.g. \&fields=System.Title,System.State\&errorPolicy=omit. |
| `WorkItemsBatchGet` | `POST` | `/{organization}/{project}/_apis/wit/workitemsbatch?api-version=7.1` | `devops/azure-devops/work-items/batch-get` | | Read-only POST: up to 200 work items by id with chosen fields (use after WiqlQuery). body: \{"ids":\[101,102],"fields":\["System.Id","System.Title","System.State"],"errorPolicy":"omit"}. |
| `WorkItemUpdate` | `PATCH` | `/{organization}/{project}/_apis/wit/workitems/{id}?api-version=7.1{query}` | `devops/azure-devops/work-items/update` | Yes | Update fields, state, assignee, links with a JSON Patch document (application/json-patch+json). body: \[\{"op":"test","path":"/rev","value":3},\{"op":"add","path":"/fields/System.State","value":"Done"},\{"op":"add","path":"/fields/System.History","value":"Press 7 back to 71 C"},\{"op":"add","path":"/relations/-","value":\{"rel":"Hyperlink","url":"[https://broker.example.com/panels/press7](https://broker.example.com/panels/press7)"}}]. query e.g. \&suppressNotifications=true (or empty). |
| `WorkItemUpdatesList` | `GET` | `/{organization}/{project}/_apis/wit/workItems/{id}/updates?api-version=7.1{query}` | `devops/azure-devops/work-items/updates/list` | | Change history of a work item (who changed which field). query e.g. &$top=50&$skip=0 (or empty). |
| `WiqlQuery` | `POST` | `/{organization}/{project}/_apis/wit/wiql?api-version=7.1{query}` | `devops/azure-devops/wiql/query` | | Read-only POST: run a WIQL query, returns work item ids (then WorkItemsBatchGet). Team segment omitted (optional in the spec). body: \{"query":"SELECT \[System.Id] FROM WorkItems WHERE \[System.TeamProject] = @project AND \[System.Tags] CONTAINS 'coreflux' AND \[System.State] \<> 'Done' ORDER BY \[System.ChangedDate] DESC"}. query e.g. &\$top=50 (or empty). |
| `WiqlQueryById` | `GET` | `/{organization}/{project}/_apis/wit/wiql/{wiql_id}?api-version=7.1{query}` | `devops/azure-devops/wiql/run-saved` | | Run a saved query by its id (wiql\_id, from QueriesList). query e.g. &\$top=50 (or empty). |
| `WorkItemCommentAdd` | `POST` | `/{organization}/{project}/_apis/wit/workItems/{id}/comments?api-version=7.1-preview.4` | `devops/azure-devops/work-items/comments/add` | Yes | Add a discussion comment (preview resource: api-version 7.1-preview\.4; plain 7.1 answers 400). body: \{"text":"Bearing replaced, line restarted at 15:10"}. |
| `WorkItemCommentsList` | `GET` | `/{organization}/{project}/_apis/wit/workItems/{id}/comments?api-version=7.1-preview.4{query}` | `devops/azure-devops/work-items/comments/list` | | Comments on a work item (api-version 7.1-preview\.4). query e.g. &\$top=20\&order=desc (or \&ids=1,2 for specific comments; or empty). |
| `WorkItemTypesList` | `GET` | `/{organization}/{project}/_apis/wit/workitemtypes?api-version=7.1` | `devops/azure-devops/work-item-types/list` | | Work item types of the project's process (Bug, Task, Issue, ...) and their fields. |
| `WorkItemTypeStatesList` | `GET` | `/{organization}/{project}/_apis/wit/workitemtypes/{type}/states?api-version=7.1` | `devops/azure-devops/work-item-types/states/list` | | Valid states of one work item type (type e.g. Bug), to map machine states to work item states. |
| `FieldsList` | `GET` | `/{organization}/{project}/_apis/wit/fields?api-version=7.1{query}` | `devops/azure-devops/fields/list` | | Field reference names (System.Title, Microsoft.VSTS.Common.Priority, Custom.\*) for JSON Patch paths. query e.g. &\$expand=extensionFields (or empty). |
| `ClassificationNodesList` | `GET` | `/{organization}/{project}/_apis/wit/classificationnodes?api-version=7.1{query}` | `devops/azure-devops/classification-nodes/list` | | Area and iteration paths (e.g. Plant\Line 2) to connector work items per line or cell. query e.g. &\$depth=2. |
| `TagsList` | `GET` | `/{organization}/{project}/_apis/wit/tags?api-version=7.1` | `devops/azure-devops/tags/list` | | Work item tags defined in the project. |
| `QueriesList` | `GET` | `/{organization}/{project}/_apis/wit/queries?api-version=7.1{query}` | `devops/azure-devops/queries/list` | | Saved queries and folders (ids for WiqlQueryById). query e.g. &$depth=1&$expand=wiql (or empty). |
| `PipelinesList` | `GET` | `/{organization}/{project}/_apis/pipelines?api-version=7.1{query}` | `devops/azure-devops/pipelines/list` | | Pipelines in the project. query e.g. &\$top=50\&orderBy=name%20asc (or empty). |
| `PipelineGet` | `GET` | `/{organization}/{project}/_apis/pipelines/{pipeline}?api-version=7.1{query}` | `devops/azure-devops/pipelines/get` | | One pipeline (pipeline = id). query e.g. \&pipelineVersion=4 (or empty). |
| `PipelineRun` | `POST` | `/{organization}/{project}/_apis/pipelines/{pipeline}/runs?api-version=7.1{query}` | `devops/azure-devops/pipelines/runs/run` | Yes | Catalog 'POST pipelines/\{id}/runs'. Start a pipeline run, e.g. edge firmware build or deployment to a line gateway. body: \{"resources":\{"repositories":\{"self":\{"refName":"refs/heads/main"}}},"templateParameters":\{"line":"2","target":"edge-gw-07"},"variables":\{"TRIGGERED\_BY":\{"value":"coreflux","isSecret":false}}}; add "previewRun":true to only expand the YAML. query e.g. \&pipelineVersion=4 (or empty). |
| `PipelineRunsList` | `GET` | `/{organization}/{project}/_apis/pipelines/{pipeline}/runs?api-version=7.1` | `devops/azure-devops/pipelines/runs/list` | | Latest runs of a pipeline (up to 10000, newest first; no query parameters). |
| `PipelineRunGet` | `GET` | `/{organization}/{project}/_apis/pipelines/{pipeline}/runs/{run}?api-version=7.1` | `devops/azure-devops/pipelines/runs/get` | | One run: state (inProgress, completed) and result (succeeded, failed, canceled). Poll after PipelineRun. |
| `PipelineRunLogsList` | `GET` | `/{organization}/{project}/_apis/pipelines/{pipeline}/runs/{run}/logs?api-version=7.1{query}` | `devops/azure-devops/pipelines/runs/logs/list` | | Logs of a run. query e.g. &\$expand=signedContent (time-limited download URLs) or empty. |
| `PipelineRunArtifactGet` | `GET` | `/{organization}/{project}/_apis/pipelines/{pipeline}/runs/{run}/artifacts?api-version=7.1{query}` | `devops/azure-devops/pipelines/runs/artifacts/get` | | One published artifact of a run, e.g. a firmware image. query (required): \&artifactName=firmware&\$expand=signedContent. |
| `BuildsList` | `GET` | `/{organization}/{project}/_apis/build/builds?api-version=7.1{query}` | `devops/azure-devops/builds/list` | | Catalog 'GET build/builds?statusFilter='. Builds and pipeline runs. query e.g. \&statusFilter=inProgress or \&resultFilter=failed\&minTime=2026-10-05T06:00:00Z\&definitions=12&\$top=20\&queryOrder=finishTimeDescending. |
| `BuildQueue` | `POST` | `/{organization}/{project}/_apis/build/builds?api-version=7.1{query}` | `devops/azure-devops/builds/queue` | Yes | Queue a build of a definition (classic or YAML). body: \{"definition":\{"id":12},"sourceBranch":"refs/heads/main","templateParameters":\{"line":"2"},"parameters":"\{"system.debug":"false"}","tags":\["coreflux"]}. query e.g. \&ignoreWarnings=true (or empty). |
| `BuildGet` | `GET` | `/{organization}/{project}/_apis/build/builds/{build}?api-version=7.1{query}` | `devops/azure-devops/builds/get` | | One build: status, result, sourceVersion, timings. query e.g. \&propertyFilters=... (or empty). |
| `BuildUpdate` | `PATCH` | `/{organization}/{project}/_apis/build/builds/{build}?api-version=7.1{query}` | `devops/azure-devops/builds/update` | Yes | Cancel a running build: body \{"status":"cancelling"}. query: \&retry=true (with body \{}) re-runs the failed jobs of a finished build; or empty. (Keep-forever is a retention lease in 7.1, not a Build field; not packaged.) |
| `BuildTagsAdd` | `POST` | `/{organization}/{project}/_apis/build/builds/{build}/tags?api-version=7.1` | `devops/azure-devops/builds/tags/add` | Yes | Tag a build, e.g. with the line or gateway it was deployed to. body: \["line-2","deployed-edge-gw-07"]. |
| `BuildTimelineGet` | `GET` | `/{organization}/{project}/_apis/build/builds/{build}/timeline?api-version=7.1{query}` | `devops/azure-devops/builds/timeline/get` | | Stages, jobs and tasks of a build with state, result and error counts (timelineId omitted = the build's own timeline). query e.g. \&changeId=5 for incremental polling (or empty). |
| `BuildLogsList` | `GET` | `/{organization}/{project}/_apis/build/builds/{build}/logs?api-version=7.1` | `devops/azure-devops/builds/logs/list` | | Log ids and line counts of a build. |
| `BuildWorkItemsList` | `GET` | `/{organization}/{project}/_apis/build/builds/{build}/workitems?api-version=7.1{query}` | `devops/azure-devops/builds/work-items/list` | | Work items linked to a build (what a firmware release fixes). query e.g. &\$top=50 (or empty). |
| `BuildDefinitionsList` | `GET` | `/{organization}/{project}/_apis/build/definitions?api-version=7.1{query}` | `devops/azure-devops/builds/definitions/list` | | Build definitions (ids for BuildQueue / BuildsList). query e.g. \&name=edge-firmware\*\&includeLatestBuilds=true&\$top=50 (or empty). |
| `HookPublishersList` | `GET` | `/{organization}/_apis/hooks/publishers?api-version=7.1` | `devops/azure-devops/hooks/publishers/list` | | Event publishers (tfs = work items, builds, code; pipelines = YAML pipeline runs, stages, approvals). |
| `HookEventTypesList` | `GET` | `/{organization}/_apis/hooks/publishers/{publisher}/eventtypes?api-version=7.1` | `devops/azure-devops/hooks/event-types/list` | | Event types of one publisher (publisher e.g. tfs: workitem.created, workitem.updated, build.complete; pipelines: ms.vss-pipelines.run-state-changed-event) with their filter inputs. |
| `HookSubscriptionsList` | `GET` | `/{organization}/_apis/hooks/subscriptions?api-version=7.1{query}` | `devops/azure-devops/hooks/subscriptions/list` | | Service hook subscriptions. query e.g. \&consumerId=webHooks\&eventType=build.complete (or empty). |
| `HookSubscriptionCreate` | `POST` | `/{organization}/_apis/hooks/subscriptions?api-version=7.1` | `devops/azure-devops/hooks/subscriptions/create` | Yes | Send Azure DevOps events to a Coreflux server connector (Web Hooks consumer). body: \{"publisherId":"tfs","eventType":"build.complete","resourceVersion":"1.0","consumerId":"webHooks","consumerActionId":"httpRequest","publisherInputs":\{"projectId":"\<project guid>","buildStatus":"failed"},"consumerInputs":\{"url":"[https://broker.example.com/azure-devops/events","httpHeaders":"X-Coreflux-Key:\&lt;shared](https://broker.example.com/azure-devops/events","httpHeaders":"X-Coreflux-Key:\&lt;shared) secret>","resourceDetailsToSend":"minimal"}}. |
| `HookSubscriptionGet` | `GET` | `/{organization}/_apis/hooks/subscriptions/{subscription}?api-version=7.1` | `devops/azure-devops/hooks/subscriptions/get` | | One subscription (status enabled / onProbation / disabledBySystem ...). |
| `HookSubscriptionReplace` | `PUT` | `/{organization}/_apis/hooks/subscriptions/{subscription}?api-version=7.1` | `devops/azure-devops/hooks/subscriptions/replace` | Yes | Replace a subscription, e.g. re-enable it after the broker was offline (send the full subscription from HookSubscriptionGet with "status":"enabled"). |
| `HookNotificationsList` | `GET` | `/{organization}/_apis/hooks/subscriptions/{subscription}/notifications?api-version=7.1{query}` | `devops/azure-devops/hooks/notifications/list` | | Recent deliveries of a subscription with result and HTTP response (debug the broker endpoint). query e.g. \&maxResults=20\&result=failed (or empty). |

## Limits

Azure DevOps meters load in throughput units (TSTUs): 200 TSTUs per identity in any sliding five-minute window, and the same per pipeline. Above that, requests are delayed or rejected with `429`. Honor `Retry-After` and watch the `X-RateLimit-*` response headers. Batch reads with `WorkItemsBatchGet` (up to 200 ids) instead of one `WorkItemGet` per item, and poll run state at a sensible interval.

## Not packaged

* All DELETE endpoints (work items, comments, builds, subscriptions) on purpose. Close work items by state instead.
* Releases (classic release pipelines). They live on a different host (`vsrm.dev.azure.com`) and need a second connector.
* Work item attachment upload (binary), Git repositories and pull requests, test plans, artifacts feeds, wikis, approvals and checks, agent pools and service connections.
* Build retention (keep forever is a retention lease in 7.1, not a build field).
* The incoming service hook direction: a separate `ENABLE_SERVER` connector.
* Azure DevOps Server (on-premises) collections.


# Azure Digital Twins
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-digital-twins

LoT connectors for Azure Digital Twins: patch and upsert twins and relationships, query the twin graph, send telemetry and get Entra ID tokens

Technical Preview

## Overview

Two client-mode connectors for [Azure Digital Twins](https://learn.microsoft.com/en-us/azure/digital-twins/overview):

* **AzureDigitalTwins** calls your instance's data plane (`https://<instance>.api.<region>.digitaltwins.azure.net`, api-version `2023-10-31`). Use it to keep a twin graph in step with the plant: patch twin properties from UNS telemetry, create or replace twins and relationships, query the graph, and publish telemetry on a twin so ADT event routes forward it to Event Grid, Event Hubs or Service Bus.
* **AzureDigitalTwinsEntraToken** calls Microsoft Entra ID (`login.microsoftonline.com`) with the client-credentials flow and returns an access token for the `https://digitaltwins.azure.net` audience.

| Event | Request | Notes |
| - | - | - |
| UpdateTwin | `PATCH /digitaltwins/{twin_id}` | JSON Patch array, `Content-Type: application/json-patch+json`; returns `204` |
| GetTwin | `GET /digitaltwins/{twin_id}` | Twin with `$dtId`, `$etag`, `$metadata` and properties |
| UpsertTwin | `PUT /digitaltwins/{twin_id}` | Create or replace; body needs `$metadata.$model` |
| QueryTwins | `POST /query` | ADT query language; `{"query": "..."}` or `{"continuationToken": "..."}` |
| SendTelemetry | `POST /digitaltwins/{twin_id}/telemetry` | `Message-Id` header required (unique per message); returns `204` |
| ListRelationships | `GET /digitaltwins/{twin_id}/relationships` | Outgoing relationships |
| UpsertRelationship | `PUT /digitaltwins/{twin_id}/relationships/{relationship_id}` | Body: `$targetId`, `$relationshipName` |
| ListModels | `GET /models` | DTDL models in the instance |
| GetModel | `GET /models/{model_id}?includeModelDefinition=true` | DTDL definition of one model |
| ListEventRoutes | `GET /eventroutes` | Where twin changes and telemetry are forwarded |
| GetAccessToken | `POST /{tenant_id}/oauth2/v2.0/token` | Client credentials, scope `https://digitaltwins.azure.net/.default` |

Topics use `cloud-iot/azure-digital-twins/<object>/<verb>`; replies land on `<topic>/response`. Before deploying, replace `YOUR_INSTANCE.api.YOUR_REGION` in the `AzureDigitalTwins` connector with your instance host name, shown as **Host name** on the instance overview in the Azure portal or by `az dt show`, for example `plant-porto.api.weu.digitaltwins.azure.net`.

> [!WARNING]
>
> Never commit a client secret or access token. Store the tenant id, client id and client secret as broker secrets and map them into payloads with `GET SECRET`.

## Authentication

Every data-plane event sends a **Microsoft Entra ID access token** as `Authorization: Bearer <token>`. The token must be issued for the Azure Digital Twins audience `https://digitaltwins.azure.net`.

1. Register an app in Microsoft Entra ID (or use a managed identity if the broker runs on Azure) and create a client secret.
2. On the Azure Digital Twins instance, assign that identity **Azure Digital Twins Data Owner** for read and write, or **Azure Digital Twins Data Reader** for read only. Owning the Azure subscription is not enough; the data-plane role is required.
3. Publish `tenant_id`, `client_id` and `client_secret` to `cloud-iot/azure-digital-twins/token/get`. The reply carries `access_token` and `expires_in` (about one hour). The client secret must be URL-encoded because it goes into a form body.
4. Pass `access_token` on every data-plane payload. Refresh it before it expires; the helper actions below do this every 45 minutes.

A missing or expired token returns `401`. A valid token without the data-plane role returns `403`.

## Basic Syntax

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AzureDigitalTwins WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.api.YOUR_REGION.digitaltwins.azure.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT UpdateTwin
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/twin/update"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/twin/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/digitaltwins/{value.json.twin_id}?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json-patch+json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTwin
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/twin/get"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/twin/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/digitaltwins/{value.json.twin_id}?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UpsertTwin
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/twin/upsert"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/twin/upsert/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/digitaltwins/{value.json.twin_id}?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT QueryTwins
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/query/run"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/query/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/query?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT SendTelemetry
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/telemetry/send"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/telemetry/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/digitaltwins/{value.json.twin_id}/telemetry?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Message-Id" "{value.json.message_id}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListRelationships
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/relationship/list"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/relationship/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/digitaltwins/{value.json.twin_id}/relationships?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UpsertRelationship
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/relationship/upsert"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/relationship/upsert/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/digitaltwins/{value.json.twin_id}/relationships/{value.json.relationship_id}?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListModels
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/model/list"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/model/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/models?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetModel
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/model/get"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/model/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/models/{value.json.model_id}?includeModelDefinition=true&api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListEventRoutes
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/event-route/list"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/event-route/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/eventroutes?api-version=2023-10-31"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"

DEFINE CONNECTOR AzureDigitalTwinsEntraToken WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://login.microsoftonline.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/x-www-form-urlencoded"
    ADD EVENT GetAccessToken
        WITH SOURCE_TOPIC "cloud-iot/azure-digital-twins/token/get"
        WITH DESTINATION_TOPIC "cloud-iot/azure-digital-twins/token/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.tenant_id}/oauth2/v2.0/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "grant_type=client_credentials&client_id={value.json.client_id}&client_secret={value.json.client_secret}&scope=https%3A%2F%2Fdigitaltwins.azure.net%2F.default"
```

## MQTT examples

Request bodies go under `body`, so control fields like `access_token`, `twin_id` and `message_id` are not sent to Azure.

**Patch a twin from telemetry**: publish to `cloud-iot/azure-digital-twins/twin/update`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Entra access token>",
  "twin_id": "press-01",
  "body": [
    {"op": "add", "path": "/Temperature", "value": 71.4},
    {"op": "add", "path": "/State", "value": "Running"}
  ]
}
```

A successful patch returns `204` with an empty body. `replace` fails with `400` if the property has never been set on the twin, so use `add` for the first write. Every property must exist in the twin's DTDL model.

**Create or replace a twin**: publish to `cloud-iot/azure-digital-twins/twin/upsert`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Entra access token>",
  "twin_id": "press-01",
  "body": {"$metadata": {"$model": "dtmi:coreflux:Machine;1"}, "Temperature": 0, "State": "Idle"}
}
```

**Link it to its line**: publish to `cloud-iot/azure-digital-twins/relationship/upsert`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Entra access token>",
  "twin_id": "press-01",
  "relationship_id": "press-01-isPartOf-line-1",
  "body": {"$targetId": "line-1", "$relationshipName": "isPartOf"}
}
```

**Query the graph**: publish to `cloud-iot/azure-digital-twins/query/run`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Entra access token>",
  "body": {"query": "SELECT T FROM DIGITALTWINS T WHERE IS_OF_MODEL(T, 'dtmi:coreflux:Machine;1') AND T.Temperature > 80"}
}
```

The reply has `value` (the matching twins) and `continuationToken`. Send `{"continuationToken": "..."}` as the body to get the next page.

**Send telemetry on a twin**: publish to `cloud-iot/azure-digital-twins/telemetry/send`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Entra access token>",
  "twin_id": "press-01",
  "message_id": "press-01-2026-10-05T03:15:00Z",
  "body": {"Vibration": 9.2}
}
```

Telemetry is not stored on the twin. ADT forwards it to whatever event routes you configured (check them on `cloud-iot/azure-digital-twins/event-route/list`). `message_id` must be unique per message; ADT uses it to drop duplicates.

**Read**: publish `{"access_token": "<token>", "twin_id": "press-01"}` to `cloud-iot/azure-digital-twins/twin/get` or `.../relationship/list`, `{"access_token": "<token>"}` to `.../model/list` or `.../event-route/list`, and `{"access_token": "<token>", "model_id": "dtmi%3Acoreflux%3AMachine%3B1"}` to `.../model/get`. URL-encode the model id because it contains `:` and `;`.

## Helper actions

Keep the Entra credentials in broker secrets, refresh the token on a timer and keep it in broker-internal state, so machines only publish their raw values:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AzureDigitalTwinsRefreshToken
ON EVERY 45 MINUTES DO
    SET "tenant" WITH GET SECRET "ADT_TENANT_ID"
    SET "client" WITH GET SECRET "ADT_CLIENT_ID"
    SET "secret" WITH GET SECRET "ADT_CLIENT_SECRET"
    PUBLISH TOPIC "cloud-iot/azure-digital-twins/token/get" WITH { "tenant_id": {tenant}, "client_id": {client}, "client_secret": {secret} }

DEFINE ACTION AzureDigitalTwinsKeepToken
ON TOPIC "cloud-iot/azure-digital-twins/token/get/response" DO
    SET "token" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "state/azure-digital-twins/token" WITH {token}

DEFINE ACTION AzureDigitalTwinsSyncTemperature
ON TOPIC "plant/porto/line1/+/temperature" DO
    SET "machine" WITH TOPIC POSITION 4
    SET "temp" WITH PAYLOAD AS DOUBLE
    SET "token" WITH GET TOPIC "state/azure-digital-twins/token" AS STRING
    PUBLISH TOPIC "cloud-iot/azure-digital-twins/twin/update" WITH { "access_token": {token}, "twin_id": {machine}, "body": [ { "op": "add", "path": "/Temperature", "value": {temp} } ] }
```

Here the fourth topic segment (`press-01` in `plant/porto/line1/press-01/temperature`) is the twin id. Name twins after your UNS asset ids so this mapping stays trivial. Store a client secret that is already URL-encoded, or encode it before publishing. Restrict who can read `cloud-iot/azure-digital-twins/#` with a rule: these payloads carry tokens and secrets.

## Notes

* Errors come back on the response topic: `401` for a missing, expired or wrong-audience token, `403` without the Data Owner or Data Reader role, `404` (`DigitalTwinNotFound`, `RelationshipNotFound`, `ModelNotFound`), `400` for a bad JSON Patch, a property that is not in the DTDL model or an invalid query, `412` for a failed `If-Match` / `If-None-Match` precondition, `429` when throttled.
* ADT throttles requests per instance and per twin (see [Azure Digital Twins service limits](https://learn.microsoft.com/en-us/azure/digital-twins/reference-service-limits)). Batch high-rate telemetry or use `ON CHANGE` instead of patching on every sample.
* `PATCH` and `PUT` here send no `If-Match` / `If-None-Match` header, so they overwrite unconditionally. Add the header to the event if you need optimistic concurrency.
* Model upload and decommission, deletes, import and delete jobs, event connector writes, component telemetry and component patches, and the ARM control plane (creating instances) are not part of this template.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Azure IoT Hub](/latest/lot-language/routes/rest-api-apps/azure-iot-hub)
* [Azure Data Explorer and Fabric Eventhouse](/latest/lot-language/routes/rest-api-apps/azure-data-explorer-and-fabric-eventhouse)


# Azure Event Hubs
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-event-hubs

LoT connector for Azure Event Hubs: send single, partition-keyed, partition-targeted or batched events over HTTPS with SAS or Entra ID auth

Technical Preview

## Overview

A client-mode connector that forwards broker data into [Azure Event Hubs](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-about) over the runtime REST send API. Use it to stream plant telemetry into Azure analytics (Stream Analytics, Fabric Real-Time Intelligence, Data Explorer, Databricks) without running an AMQP or Kafka client.

| Event | Request | Notes |
| - | - | - |
| SendEvent | `POST /{hub}/messages` | One event; `application/atom+xml;type=entry;charset=utf-8` |
| SendEventWithPartitionKey | `POST /{hub}/messages` + `BrokerProperties` | Same key lands on the same partition (ordered per device) |
| SendPartitionEvent | `POST /{hub}/partitions/{id}/messages` | Explicit partition |
| SendBatch | `POST /{hub}/messages` | JSON array of `{"Body", "UserProperties"}`; `application/vnd.microsoft.servicebus.json` |

Every request uses `api-version=2014-01` and returns **201 Created** with an empty body. Default `BASE_ADDRESS` is `https://YOUR_NAMESPACE.servicebus.windows.net` (no trailing slash). Topics use `data/azure-event-hubs/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** pass the full `Authorization` value as `{value.json.authorization}`, either `SharedAccessSignature sr=…&sig=…&se=…&skn=…` from a policy with the **Send** claim, or `Bearer {entra_token}` (scope `https://eventhubs.azure.net/.default`, role **Azure Event Hubs Data Sender**). Prefer Hub secrets; never commit keys into the `.lot`.

> [!NOTE]
>
> **Send only.** Event Hubs has no REST receive API; consumers use AMQP or Kafka. The management plane (creating namespaces and hubs) goes through Azure Resource Manager and is not packaged. A **Fabric Eventstream** custom endpoint exposes an Event Hubs-compatible namespace and SAS key, so the same template applies. This template has not yet been verified against a live namespace.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AzureEventHubsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_NAMESPACE.servicebus.windows.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: SAS or Entra Bearer via {value.json.authorization} (see header comments). Never commit real keys.
    ADD EVENT SendEvent
        WITH SOURCE_TOPIC "data/azure-event-hubs/messages/post"
        WITH DESTINATION_TOPIC "data/azure-event-hubs/messages/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.hub}/messages?timeout=60&api-version=2014-01"
        WITH HEADERS
            ADD "Content-Type" "application/atom+xml;type=entry;charset=utf-8"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT SendEventWithPartitionKey
        WITH SOURCE_TOPIC "data/azure-event-hubs/messages/keyed/post"
        WITH DESTINATION_TOPIC "data/azure-event-hubs/messages/keyed/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.hub}/messages?timeout=60&api-version=2014-01"
        WITH HEADERS
            ADD "Content-Type" "application/atom+xml;type=entry;charset=utf-8"
            ADD "Authorization" "{value.json.authorization}"
            ADD "BrokerProperties" "{value.json.broker_properties}"
        WITH BODY "{value.json.body}"
    ADD EVENT SendPartitionEvent
        WITH SOURCE_TOPIC "data/azure-event-hubs/partitions/messages/post"
        WITH DESTINATION_TOPIC "data/azure-event-hubs/partitions/messages/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.hub}/partitions/{value.json.partition_id}/messages?timeout=60&api-version=2014-01"
        WITH HEADERS
            ADD "Content-Type" "application/atom+xml;type=entry;charset=utf-8"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT SendBatch
        WITH SOURCE_TOPIC "data/azure-event-hubs/messages/batch/post"
        WITH DESTINATION_TOPIC "data/azure-event-hubs/messages/batch/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.hub}/messages?timeout=60&api-version=2014-01"
        WITH HEADERS
            ADD "Content-Type" "application/vnd.microsoft.servicebus.json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
```

## MQTT examples

**SendEvent** (`data/azure-event-hubs/messages/post`), expect **201 Created** with an empty body:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "hub": "press-telemetry",
  "authorization": "SharedAccessSignature sr=https%3A%2F%2FYOUR_NAMESPACE.servicebus.windows.net%2Fpress-telemetry&sig=...&se=1767225600&skn=coreflux-send",
  "body": {
    "DeviceId": "press-01",
    "Temperature": 37.0,
    "ts": "2026-10-05T00:21:00Z"
  }
}
```

**SendEventWithPartitionKey** (`data/azure-event-hubs/messages/keyed/post`), expect **201 Created** with an empty body:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "hub": "press-telemetry",
  "authorization": "SharedAccessSignature sr=...&sig=...&se=...&skn=coreflux-send",
  "broker_properties": "{\"PartitionKey\":\"press-01\"}",
  "body": {
    "DeviceId": "press-01",
    "rpm": 1450
  }
}
```

**SendPartitionEvent** (`data/azure-event-hubs/partitions/messages/post`), expect **201 Created** with an empty body:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "hub": "press-telemetry",
  "partition_id": "0",
  "authorization": "SharedAccessSignature sr=...&sig=...&se=...&skn=coreflux-send",
  "body": {
    "DeviceId": "press-02",
    "state": "RUN"
  }
}
```

**SendBatch** (`data/azure-event-hubs/messages/batch/post`), expect **201 Created** with an empty body:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "hub": "press-telemetry",
  "authorization": "Bearer <entra_access_token>",
  "body": [
    {
      "Body": "{\"DeviceId\":\"press-01\",\"t\":37.1}",
      "UserProperties": {
        "line": "A"
      }
    },
    {
      "Body": "{\"DeviceId\":\"press-02\",\"t\":36.8}"
    }
  ]
}
```

`body` becomes the HTTP body, so control fields (`hub`, `authorization`, `partition_id`, `broker_properties`) are never sent to Azure.

## Generating a SAS token

The signature is `HMAC-SHA256(key, url_encode(resource_uri) + "\n" + expiry)`, base64-encoded and URL-encoded. With Azure CLI you can read the policy key:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
az eventhubs eventhub authorization-rule keys list -g YOUR_RG --namespace-name YOUR_NAMESPACE --eventhub-name press-telemetry -n coreflux-send
```

Then build the token with the snippet from [Generate SAS token](https://learn.microsoft.com/en-us/rest/api/eventhub/generate-sas-token). Keep expiry short and rotate through Hub secrets.

## Notes

* Replace `YOUR_NAMESPACE` in `BASE_ADDRESS` before deploy.
* Max event or batch size is 1 MB (Standard and above); 256 KB on Basic.
* `UserProperties` in headers are ignored for batches; put them inside each batch item.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Send event](https://learn.microsoft.com/en-us/rest/api/eventhub/send-event)
* [Send batch events](https://learn.microsoft.com/en-us/rest/api/eventhub/send-batch-events)
* [Send partition event](https://learn.microsoft.com/en-us/rest/api/eventhub/send-partition-event)
* [Authenticate with SAS](https://learn.microsoft.com/en-us/azure/event-hubs/authenticate-shared-access-signature)


# Azure IoT Hub
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-iot-hub

Client-mode REST API connector for a curated Azure IoT Hub slice: registry GetDevice, device-to-cloud SendDeviceEvent, twin GET/PATCH, and InvokeDeviceMethod

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [Azure IoT Hub](https://learn.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-overview) covering registry, device-to-cloud events, device twin, and direct methods:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| Registry get | `GET /devices/{deviceId}?api-version=…` | Service SAS or Entra |
| POST devices/\{id}/messages/events | `POST /devices/{deviceId}/messages/events?api-version=…` | DeviceConnect SAS; HTTP 204 |
| GET twins/\{id} | `GET /twins/{deviceId}?api-version=…` | Read twin |
| PATCH twins/\{id} | `PATCH /twins/{deviceId}?api-version=…` | Service desired/tags (catalog named reported) |
| POST twins/\{id}/methods | `POST /twins/{deviceId}/methods?api-version=…` | Direct method / command to device |

Default `BASE_ADDRESS` is `https://YOUR_HUB.azure-devices.net` (no trailing slash). Topics use `cloud-iot/azure-iot-hub/<object>/<verb>`. Default `api-version` is **`2021-04-12`**.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** pass `Authorization` as `{value.json.authorization}` — either `SharedAccessSignature sr=…&sig=…&se=…&skn=…` or `Bearer {entra_token}` for **service** APIs. Prefer Hub secrets — never commit real keys into the `.lot`.

> [!NOTE]
>
> **Device SendDeviceEvent** requires a **DeviceConnect** SAS scoped to the device. Microsoft Entra ID is **not** supported for IoT Hub device APIs.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Azure IoT Hub curated slice
# Auth: Authorization → {value.json.authorization}
#   SharedAccessSignature …  OR  Bearer {entra_token} (service)
# BASE_ADDRESS: https://YOUR_HUB.azure-devices.net

DEFINE CONNECTOR AzureIotHubRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_HUB.azure-devices.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/devices/get"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/devices/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/devices/{value.json.device_id}?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT SendDeviceEvent
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/messages/events/post"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/messages/events/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/devices/{value.json.device_id}/messages/events?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT GetTwin
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/twins/get"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/twins/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/twins/{value.json.device_id}?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT UpdateTwin
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/twins/update"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/twins/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/twins/{value.json.device_id}?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "If-Match" "{value.json.if_match}"
        WITH BODY "{payload}"
    ADD EVENT InvokeDeviceMethod
        WITH SOURCE_TOPIC "cloud-iot/azure-iot-hub/twins/methods/post"
        WITH DESTINATION_TOPIC "cloud-iot/azure-iot-hub/twins/methods/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/twins/{value.json.device_id}/methods?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
```

## MQTT examples

**GetDevice** (`cloud-iot/azure-iot-hub/devices/get`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net&sig=...&se=...&skn=registryRead"
}
```

**SendDeviceEvent** (`cloud-iot/azure-iot-hub/messages/events/post`) — device SAS; expect **204**:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net%2Fdevices%2Fline-a-gw&sig=...&se=...&skn=device",
  "payload": "{\"temp\":72.5}"
}
```

**UpdateTwin** (`cloud-iot/azure-iot-hub/twins/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net&sig=...&se=...&skn=service",
  "if_match": "*",
  "payload": "{\"properties\":{\"desired\":{\"pump\":true}}}"
}
```

**InvokeDeviceMethod** (`cloud-iot/azure-iot-hub/twins/methods/post`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "device_id": "line-a-gw",
  "api_version": "2021-04-12",
  "authorization": "SharedAccessSignature sr=YOUR_HUB.azure-devices.net&sig=...&se=...&skn=service",
  "payload": "{\"methodName\":\"reboot\",\"responseTimeoutInSeconds\":30,\"payload\":{}}"
}
```

## Notes

* Replace `YOUR_HUB` in `BASE_ADDRESS` before deploy.
* `api-version=2021-04-12` is required on every request (pass `api_version` in MQTT JSON).
* Service twin PATCH updates **desired** properties and **tags**. Catalog wording said “reported”; reported properties are typically updated by the device.
* Event Grid inbound webhooks are not packaged (future server connector).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Microsoft IoT Hub REST](https://learn.microsoft.com/en-us/rest/api/iothub/)
* [Control access with SAS](https://learn.microsoft.com/en-us/azure/iot-hub/authenticate-authorize-sas)
* [Control access with Entra ID](https://learn.microsoft.com/en-us/azure/iot-hub/authenticate-authorize-azure-ad)


# Azure Monitor
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-monitor

LoT connector for Azure Monitor: send logs to a DCR stream, post custom metrics and run Log Analytics KQL queries from MQTT with Entra tokens

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of [Azure Monitor](https://learn.microsoft.com/en-us/azure/azure-monitor/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST logs to DCR stream | `POST /dataCollectionRules/{dcr}/streams/{stream}?api-version=2023-01-01` | Logs Ingestion on DCE/DCR host; scope `https://monitor.azure.com/.default`; expect **204** |
| POST custom metric | `POST /{resourceId}/metrics` | Host `https://{region}.monitoring.azure.com`; scope `https://monitoring.azure.com/.default`; expect **200** |
| POST KQL query | `POST /v1/workspaces/{workspaceId}/query` | Host `https://api.loganalytics.azure.com`; scope `https://api.loganalytics.io/.default`; credential check → **200** |
| GET KQL query | `GET /v1/workspaces/{workspaceId}/query` | Same query API via query string |
| Action Group / alert webhook | inbound HTTP | **ENABLE\_SERVER companion** (docs only — not in this client `.lot`) |

Default `BASE_ADDRESS` is `https://YOUR_DCE.ingest.monitor.azure.com`. Topics use `itsm/azure-monitor/<object>/<verb>`. Switch BASE per surface (Logs / Metrics / Query) the same way other multi-host connectors do.

> [!NOTE]
>
> Replace `YOUR_DCE` with your Data Collection Endpoint hostname (or use the DCR `logsIngestion` endpoint). Prefer Hub secrets for Entra client credentials and workspace / DCR / resource identifiers.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Azure Monitor (Logs + Metrics + KQL)
# Auth: Authorization: Bearer {value.json.access_token}
# BASE_ADDRESS: https://YOUR_DCE.ingest.monitor.azure.com

DEFINE CONNECTOR AzureMonitorRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DCE.ingest.monitor.azure.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Uploadlogs
        WITH SOURCE_TOPIC "itsm/azure-monitor/log/ingest"
        WITH DESTINATION_TOPIC "itsm/azure-monitor/log/ingest/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dataCollectionRules/{value.json.dcr_immutable_id}/streams/{value.json.stream_name}?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-ms-client-request-id" "{value.json.client_request_id}"
        WITH BODY "{payload}"
    ADD EVENT Createcustommetric
        WITH SOURCE_TOPIC "itsm/azure-monitor/metric/custom"
        WITH DESTINATION_TOPIC "itsm/azure-monitor/metric/custom/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.resource_id}/metrics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Executequery
        WITH SOURCE_TOPIC "itsm/azure-monitor/query/execute"
        WITH DESTINATION_TOPIC "itsm/azure-monitor/query/execute/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/workspaces/{value.json.workspace_id}/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Executequeryget
        WITH SOURCE_TOPIC "itsm/azure-monitor/query/get"
        WITH DESTINATION_TOPIC "itsm/azure-monitor/query/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/workspaces/{value.json.workspace_id}/query?query={value.json.query}&timespan={value.json.timespan}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Authentication

| Mode | Header | Notes |
| - | - | - |
| Entra OAuth 2.0 client credentials | `Authorization: Bearer {value.json.access_token}` | Default in this template |

Acquire tokens from `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token`. Scopes: `https://monitor.azure.com/.default` (logs), `https://monitoring.azure.com/.default` (custom metrics), `https://api.loganalytics.io/.default` (query). Store tenant / client / secret in Hub secrets (`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`) and resolve via `GET SECRET` — never commit credentials.

## MQTT examples

**Logs ingest** (JSON array; BASE = DCE):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "Time": "2026-10-04T17:00:00Z",
    "Computer": "line-a",
    "AdditionalContext": "vibration_rms=12.4"
  }
]
```

Publish with `access_token`, `dcr_immutable_id`, `stream_name`, and `api_version` (`2023-01-01`). Expect **HTTP 204**.

**Custom metric** (BASE = `{region}.monitoring.azure.com`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "time": "2026-10-04T17:00:00Z",
  "data": {
    "baseData": {
      "metric": "vibration_rms",
      "namespace": "Coreflux/Plant",
      "series": [{"min": 12.4, "max": 12.4, "sum": 12.4, "count": 1}]
    }
  }
}
```

Expect **HTTP 200**.

**KQL query** (BASE = `api.loganalytics.azure.com`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "AzureActivity | summarize count() by Category",
  "timespan": "PT12H"
}
```

Expect **HTTP 200**.

## Action Group webhook companion

Azure Monitor Action Groups can deliver Common Alert Schema (or older schemas) to a webhook URL. Package a separate `ENABLE_SERVER true` REST\_API connector to receive those POSTs on an MQTT-bound path. That inbound surface is **not** included in `AzureMonitorRestApi.lot`.

## Sources

* [Logs Ingestion API](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/logs-ingestion-api-overview)
* [Custom metrics REST](https://learn.microsoft.com/en-us/azure/azure-monitor/metrics/metrics-store-custom-rest-api)
* [Metrics - Custom - Create](https://learn.microsoft.com/en-us/rest/api/monitor/metrics-custom/create)
* [Logs query API](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/overview)
* [API access and authentication](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/access-api)
* [Action groups](https://learn.microsoft.com/en-us/azure/azure-monitor/alerts/action-groups)

## Package

Broker template folder: `src/CorefluxCentral/Routes/Templates/RestApiConnectors/azure-monitor/`

Deployable file: `AzureMonitorRestApi.lot` (no `ADD METADATA`). Hub icon/status: `hub-metadata.lot`.


# Azure OpenAI and Azure AI Foundry
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-openai-and-azure-ai-foundry

Client-mode REST API connector for Azure OpenAI / Foundry chat completions and embeddings — MQTT into Azure-hosted LLM alarm classification

Technical Preview

## Overview

A client-mode connector for a **curated** slice of [Azure OpenAI](https://learn.microsoft.com/en-us/azure/foundry/openai/reference) / [Azure AI Foundry](https://learn.microsoft.com/en-us/rest/api/microsoft-foundry/azureopenai/chat) focused on IIoT / edge alarm text into Azure-hosted LLMs (OpenAI-compatible bodies, deployment-based paths):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST chat/completions | `POST /openai/deployments/{deployment}/chat/completions?api-version=…` | Chat Completions — same body template as OpenAI |
| POST embeddings | `POST /openai/deployments/{deployment}/embeddings?api-version=…` | Create embeddings on an embeddings deployment |
| (supporting) GET models | `GET /openai/models?api-version=…` | List models (checks the token) |
| (supporting) GET model | `GET /openai/models/{model}?api-version=…` | Retrieve one model |

Default `BASE_ADDRESS` placeholder is `https://YOUR_RESOURCE.openai.azure.com` (no trailing slash) — replace with your real resource host. Default `api-version` in docs/examples: **`2024-10-21`**. Topics use `ai/azure-openai/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** `api-key: &lt;Azure OpenAI resource key&gt;` on every request (template default). Prefer Hub secrets (`GET SECRET "AZURE_OPENAI_API_KEY"` or `AZURE_OPENAI_KEY`) mapped into MQTT `api_token`. **Entra ID alternative:** `Authorization: Bearer &lt;token&gt;` with scope `https://cognitiveservices.azure.com/.default`. Never commit real keys.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Azure OpenAI / Foundry
# Auth: api-key {value.json.api_token}
# BASE_ADDRESS: https://YOUR_RESOURCE.openai.azure.com

DEFINE CONNECTOR AzureOpenaiAndAzureAiFoundryRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_RESOURCE.openai.azure.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostChatCompletions
        WITH SOURCE_TOPIC "ai/azure-openai/chat/completions/post"
        WITH DESTINATION_TOPIC "ai/azure-openai/chat/completions/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openai/deployments/{value.json.deployment}/chat/completions?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "api-key" "{value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT PostEmbeddings
        WITH SOURCE_TOPIC "ai/azure-openai/embeddings/post"
        WITH DESTINATION_TOPIC "ai/azure-openai/embeddings/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openai/deployments/{value.json.deployment}/embeddings?api-version={value.json.api_version}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "api-key" "{value.json.api_token}"
        WITH BODY "{payload}"
```

## Topics

| Event | Source topic | Destination topic |
| - | - | - |
| PostChatCompletions | `ai/azure-openai/chat/completions/post` | `…/response` |
| PostEmbeddings | `ai/azure-openai/embeddings/post` | `…/response` |
| GetModels | `ai/azure-openai/models/list` | `…/response` |
| GetModel | `ai/azure-openai/models/get` | `…/response` |

## Configuration

1. Set `BASE_ADDRESS` to `https://{your-resource}.openai.azure.com` (no trailing slash).
2. Store the Azure OpenAI API key in Hub secrets (`AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_KEY`); map into MQTT `api_token`.
3. Pass `deployment` (deployment name) and `api_version` (e.g. `2024-10-21`) on inference MQTT JSON.
4. For alarm classification: publish to `ai/azure-openai/chat/completions/post` with an OpenAI-compatible messages body (optional `response_format`).
5. For semantic search / similarity: publish to `ai/azure-openai/embeddings/post` with a tiny `input` string against an embeddings deployment.
6. Use `GetModels` as a cheap credential check before production workloads.

## References

* [Azure OpenAI REST reference](https://learn.microsoft.com/en-us/azure/foundry/openai/reference)
* [Models — List (2024-10-21)](https://learn.microsoft.com/en-us/rest/api/azureopenai/models/list?view=rest-azureopenai-2024-10-21)
* [Foundry — Chat Completions](https://learn.microsoft.com/en-us/rest/api/microsoft-foundry/azureopenai/chat)
* [Foundry — Embeddings](https://learn.microsoft.com/en-us/rest/api/microsoft-foundry/azureopenai/embeddings)
* Sibling: [OpenAI](/latest/lot-language/routes/rest-api-apps/openai)


# Azure Service Bus
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/azure-service-bus

LoT connector for Azure Service Bus: send to queues and topics, peek-lock or receive-and-delete messages, and complete or unlock them from MQTT

Technical Preview

## Overview

Client-mode REST API connector for the Azure Service Bus runtime REST API: send to queues and topics plus peek-lock and receive-and-delete and complete and unlock. `BASE_ADDRESS` defaults to `https://YOUR_NAMESPACE.servicebus.windows.net`. Topics use `cloud/azure-service-bus/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `QueueSend` | `POST /{value.json.queue}/messages?timeout=60` | `cloud/azure-service-bus/queues/send` |
| `TopicSend` | `POST /{value.json.topic}/messages?timeout=60` | `cloud/azure-service-bus/topics/send` |
| `QueuePeekLock` | `POST /{value.json.queue}/messages/head?timeout={value.json.timeout}` | `cloud/azure-service-bus/queues/peek-lock` |
| `QueueReceiveAndDelete` | `DELETE /{value.json.queue}/messages/head?timeout={value.json.timeout}` | `cloud/azure-service-bus/queues/receive` |
| `SubscriptionPeekLock` | `POST /{value.json.topic}/subscriptions/{value.json.subscription}/messages/head?timeout={value.json.timeout}` | `cloud/azure-service-bus/subscriptions/peek-lock` |
| `SubscriptionReceiveAndDelete` | `DELETE /{value.json.topic}/subscriptions/{value.json.subscription}/messages/head?timeout={value.json.timeout}` | `cloud/azure-service-bus/subscriptions/receive` |
| `MessageComplete` | `DELETE /{value.json.entity_path}/messages/{value.json.messageId}/{value.json.lockToken}` | `cloud/azure-service-bus/messages/complete` |
| `MessageUnlock` | `PUT /{value.json.entity_path}/messages/{value.json.messageId}/{value.json.lockToken}` | `cloud/azure-service-bus/messages/unlock` |

## Authentication

Authorization: \{value.json.authorization} carries either "SharedAccessSignature sr=...\&sig=...\&se=...\&skn=..." (SAS from a policy with Send / Listen) or "Bearer \<Entra token>" (scope [https://servicebus.azure.net/.default](https://servicebus.azure.net/.default); roles Azure Service Bus Data Sender / Receiver). The connector cannot sign; generate the SAS or token upstream (LoT action with GET SECRET or an external helper).

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* Topic names here use cloud/azure-service-bus/... (not messaging/...).
* BrokerProperties is a JSON string header, e.g. \{"MessageId":"m-1","SessionId":"line-1","TimeToLive":3600}; pass "\{}" when unused.
* Peek-lock returns the lock token in the BrokerProperties response header; MessageComplete and MessageUnlock need messageId and lockToken from it.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AzureServiceBusRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_NAMESPACE.servicebus.windows.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '90'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT QueueSend
        WITH SOURCE_TOPIC "cloud/azure-service-bus/queues/send"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/queues/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.queue}/messages?timeout=60"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "BrokerProperties" "{value.json.broker_properties}"
        WITH BODY "{value.json.body}"
    ADD EVENT TopicSend
        WITH SOURCE_TOPIC "cloud/azure-service-bus/topics/send"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/topics/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.topic}/messages?timeout=60"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "BrokerProperties" "{value.json.broker_properties}"
        WITH BODY "{value.json.body}"
    ADD EVENT QueuePeekLock
        WITH SOURCE_TOPIC "cloud/azure-service-bus/queues/peek-lock"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/queues/peek-lock/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.queue}/messages/head?timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT QueueReceiveAndDelete
        WITH SOURCE_TOPIC "cloud/azure-service-bus/queues/receive"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/queues/receive/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/{value.json.queue}/messages/head?timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT SubscriptionPeekLock
        WITH SOURCE_TOPIC "cloud/azure-service-bus/subscriptions/peek-lock"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/subscriptions/peek-lock/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.topic}/subscriptions/{value.json.subscription}/messages/head?timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT SubscriptionReceiveAndDelete
        WITH SOURCE_TOPIC "cloud/azure-service-bus/subscriptions/receive"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/subscriptions/receive/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/{value.json.topic}/subscriptions/{value.json.subscription}/messages/head?timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT MessageComplete
        WITH SOURCE_TOPIC "cloud/azure-service-bus/messages/complete"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/messages/complete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/{value.json.entity_path}/messages/{value.json.messageId}/{value.json.lockToken}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT MessageUnlock
        WITH SOURCE_TOPIC "cloud/azure-service-bus/messages/unlock"
        WITH DESTINATION_TOPIC "cloud/azure-service-bus/messages/unlock/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.entity_path}/messages/{value.json.messageId}/{value.json.lockToken}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
```

## Sources

* [https://learn.microsoft.com/en-us/rest/api/servicebus/send-message-to-queue](https://learn.microsoft.com/en-us/rest/api/servicebus/send-message-to-queue)
* [https://learn.microsoft.com/en-us/rest/api/servicebus/peek-lock-message-non-destructive-read](https://learn.microsoft.com/en-us/rest/api/servicebus/peek-lock-message-non-destructive-read)
* [https://learn.microsoft.com/en-us/rest/api/servicebus/receive-and-delete-message-destructive-read](https://learn.microsoft.com/en-us/rest/api/servicebus/receive-and-delete-message-destructive-read)
* [https://learn.microsoft.com/en-us/rest/api/servicebus/delete-message](https://learn.microsoft.com/en-us/rest/api/servicebus/delete-message)
* [https://learn.microsoft.com/en-us/rest/api/servicebus/unlock-message](https://learn.microsoft.com/en-us/rest/api/servicebus/unlock-message)
* [https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-sas](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-sas)


# REST API Apps
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/index

Catalog of client-mode REST API LoT templates for IIoT workloads and enterprise systems

Technical Preview

> [!WARNING]
>
> Every REST API app in this catalog is in technical preview.

## Overview

These templates are client-mode `TYPE REST_API` connectors: an MQTT request topic triggers an HTTP call, and the response is published on a matching topic. Start with [REST API Connectors](/latest/lot-language/routes/rest-api-routes) for config, auth, and placeholders. This catalog is the app layer on top of that connector.

Every app ships with the broker. The connector signs outbound requests itself through `CLIENT_AUTH`, and reads credentials from broker secrets (`GET SECRET`). Create the secrets a template needs before you deploy it: a connector whose `CLIENT_AUTH` secret is empty does not start. The Hub lists these secrets (`requiredSecrets`) and asks for them before deploying.

## Catalog

Apps are grouped by Hub category. An app with several connectors has one app code per connector, each with its own page.

* **Auth** is the `CLIENT_AUTH` mode the template uses. *None* means the API is public or takes its key in the request.
* **Minimum tier** follows the number of actions the connector registers: up to 24 runs on Community, up to 100 needs Growth, more needs Enterprise.

### Analytics

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Amazon DynamoDB](/latest/lot-language/routes/rest-api-apps/amazon-dynamodb) | `AMAZON_DYNAMODB` | AWS SigV4 | Community |
| [Anaplan](/latest/lot-language/routes/rest-api-apps/anaplan) | `ANAPLAN` | Login token | Community |
| [Apache Superset](/latest/lot-language/routes/rest-api-apps/apache-superset) | `APACHE_SUPERSET` | Login token | Growth |
| [Azure Cosmos DB](/latest/lot-language/routes/rest-api-apps/azure-cosmos-db) | `AZURE_COSMOS_DB` | API key | Community |
| [Azure Data Explorer (Kusto) and Fabric Eventhouse](/latest/lot-language/routes/rest-api-apps/azure-data-explorer-and-fabric-eventhouse) | `AZURE_DATA_EXPLORER_AND_FABRIC_EVENTHOUSE` | Bearer | Community |
| [Azure Event Hubs (REST send)](/latest/lot-language/routes/rest-api-apps/azure-event-hubs) | `AZURE_EVENT_HUBS` | API key | Community |
| [ClickHouse (OSS and Cloud)](/latest/lot-language/routes/rest-api-apps/clickhouse) | `CLICKHOUSE` | Basic | Community |
| [Databricks](/latest/lot-language/routes/rest-api-apps/databricks) | `DATABRICKS` | Bearer | Community |
| [Domo](/latest/lot-language/routes/rest-api-apps/domo) | `DOMO` | OAuth 2.0 client credentials | Growth |
| [Elasticsearch and Elastic Cloud](/latest/lot-language/routes/rest-api-apps/elasticsearch-and-elastic-cloud) | `ELASTICSEARCH_AND_ELASTIC_CLOUD` | API key | Community |
| [Firebase Realtime Database and Cloud Firestore](/latest/lot-language/routes/rest-api-apps/firebase-realtime-database-and-cloud-firestore) | [`CLOUD_FIRESTORE`](/latest/lot-language/routes/rest-api-apps/cloud-firestore) [`FIREBASE_REALTIME_DATABASE`](/latest/lot-language/routes/rest-api-apps/firebase-realtime-database) | Bearer | Community |
| [Google BigQuery](/latest/lot-language/routes/rest-api-apps/google-bigquery) | `GOOGLE_BIGQUERY` | Bearer | Community |
| [Google Cloud Pub/Sub](/latest/lot-language/routes/rest-api-apps/google-cloud-pub-sub) | `GOOGLE_CLOUD_PUB_SUB` | Bearer | Community |
| [Grafana Loki](/latest/lot-language/routes/rest-api-apps/grafana-loki) | `GRAFANA_LOKI` | None | Community |
| [InfluxDB (v2, v3 Core/Enterprise, Cloud)](/latest/lot-language/routes/rest-api-apps/influxdb) | `INFLUXDB` | API key | Community |
| [Looker](/latest/lot-language/routes/rest-api-apps/looker) | `LOOKER` | OAuth 2.0 client credentials | Growth |
| [Metabase](/latest/lot-language/routes/rest-api-apps/metabase) | `METABASE` | API key | Community |
| [Microsoft Power BI](/latest/lot-language/routes/rest-api-apps/microsoft-power-bi) | `MICROSOFT_POWER_BI` | Bearer | Community |
| [Qlik Cloud](/latest/lot-language/routes/rest-api-apps/qlik-cloud) | `QLIK_CLOUD` | Bearer | Growth |
| [QuestDB](/latest/lot-language/routes/rest-api-apps/questdb) | `QUESTDB` | API key | Community |
| [Snowflake SQL API](/latest/lot-language/routes/rest-api-apps/snowflake-sql-api) | `SNOWFLAKE_SQL_API` | Bearer | Community |
| [Supabase (PostgREST, Realtime, Storage)](/latest/lot-language/routes/rest-api-apps/supabase) | `SUPABASE` | Bearer | Community |
| [Tableau (Server and Cloud)](/latest/lot-language/routes/rest-api-apps/tableau) | `TABLEAU` | Login token | Community |
| [TDengine](/latest/lot-language/routes/rest-api-apps/tdengine) | `TDENGINE` | Basic | Community |

### CRM

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Dynamics 365](/latest/lot-language/routes/rest-api-apps/dynamics365) | `DYNAMICS365` | Bearer | Community |
| [Freshdesk and Freshservice](/latest/lot-language/routes/rest-api-apps/freshdesk-and-freshservice) | `FRESHDESK_AND_FRESHSERVICE` | Bearer | Community |
| [Help Scout](/latest/lot-language/routes/rest-api-apps/help-scout) | `HELP_SCOUT` | OAuth 2.0 client credentials | Growth |
| [HubSpot](/latest/lot-language/routes/rest-api-apps/hubspot) | `HUBSPOT` | Bearer | Community |
| [Intercom](/latest/lot-language/routes/rest-api-apps/intercom) | `INTERCOM` | Bearer | Growth |
| [Pipedrive](/latest/lot-language/routes/rest-api-apps/pipedrive) | `PIPEDRIVE` | API key | Community |
| [Salesforce](/latest/lot-language/routes/rest-api-apps/salesforce) | `SALESFORCE` | Bearer | Community |
| [SugarCRM](/latest/lot-language/routes/rest-api-apps/sugarcrm) | `SUGARCRM` | Login token | Community |
| [Zendesk Support](/latest/lot-language/routes/rest-api-apps/zendesk-support) | `ZENDESK_SUPPORT` | Bearer | Community |
| [Zoho CRM](/latest/lot-language/routes/rest-api-apps/zoho-crm) | `ZOHO_CRM` | Bearer | Community |

### Cloud IoT

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [AWS IoT Core](/latest/lot-language/routes/rest-api-apps/aws-iot-core) | `AWS_IOT_CORE` | AWS SigV4 | Community |
| [AWS IoT SiteWise](/latest/lot-language/routes/rest-api-apps/aws-iot-sitewise) | `AWS_IOT_SITEWISE` | AWS SigV4 | Community |
| [Azure Digital Twins](/latest/lot-language/routes/rest-api-apps/azure-digital-twins) | `AZURE_DIGITAL_TWINS` | OAuth 2.0 client credentials | Community |
| [Azure IoT Hub](/latest/lot-language/routes/rest-api-apps/azure-iot-hub) | `AZURE_IOT_HUB` | API key | Community |
| [balena](/latest/lot-language/routes/rest-api-apps/balena) | `BALENA` | Bearer | Community |
| [Blynk](/latest/lot-language/routes/rest-api-apps/blynk-device-api) | [`BLYNK_DEVICE_API`](/latest/lot-language/routes/rest-api-apps/blynk-device-api) [`BLYNK_PLATFORM_API`](/latest/lot-language/routes/rest-api-apps/blynk-platform-api) | API key, OAuth 2.0 client credentials | Community / Growth |
| [ChirpStack v4](/latest/lot-language/routes/rest-api-apps/chirpstack-v4) | `CHIRPSTACK_V4` | API key | Community |
| [Cumulocity](/latest/lot-language/routes/rest-api-apps/cumulocity) | `CUMULOCITY` | API key | Community |
| [Datacake](/latest/lot-language/routes/rest-api-apps/datacake) | `DATACAKE` | API key | Community |
| [Eclipse Ditto (digital twins)](/latest/lot-language/routes/rest-api-apps/eclipse-ditto) | `ECLIPSE_DITTO` | API key | Growth |
| [Eclipse hawkBit (OTA)](/latest/lot-language/routes/rest-api-apps/eclipse-hawkbit) | `ECLIPSE_HAWKBIT` | API key | Growth |
| [Golioth](/latest/lot-language/routes/rest-api-apps/golioth) | `GOLIOTH` | API key | Growth |
| [Home Assistant](/latest/lot-language/routes/rest-api-apps/home-assistant) | `HOME_ASSISTANT` | API key | Community |
| [Losant](/latest/lot-language/routes/rest-api-apps/losant) | `LOSANT` | Bearer | Community |
| [Memfault](/latest/lot-language/routes/rest-api-apps/memfault) | `MEMFAULT` | Bearer | Growth |
| [Mender](/latest/lot-language/routes/rest-api-apps/mender) | `MENDER` | Bearer | Community |
| [Particle](/latest/lot-language/routes/rest-api-apps/particle) | `PARTICLE` | Bearer | Growth |
| [Siemens Insights Hub (formerly MindSphere)](/latest/lot-language/routes/rest-api-apps/siemens-insights-hub) | `SIEMENS_INSIGHTS_HUB` | API key | Community |
| [Soracom](/latest/lot-language/routes/rest-api-apps/soracom) | `SORACOM` | Login token | Growth |
| [Teltonika RMS](/latest/lot-language/routes/rest-api-apps/teltonika-rms) | `TELTONIKA_RMS` | API key | Growth |
| [The Things Stack (TTN and TTI)](/latest/lot-language/routes/rest-api-apps/the-things-stack) | `THE_THINGS_STACK` | API key | Community |
| [ThingsBoard (CE, PE, Cloud)](/latest/lot-language/routes/rest-api-apps/thingsboard) | `THINGSBOARD` | API key | Community |
| [Ubidots](/latest/lot-language/routes/rest-api-apps/ubidots) | `UBIDOTS` | API key | Community |

### Cloud storage

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Amazon S3](/latest/lot-language/routes/rest-api-apps/amazon-s3) | `AMAZON_S3` | AWS SigV4 | Community |
| [Azure Blob Storage and Data Lake Gen2](/latest/lot-language/routes/rest-api-apps/azure-blob-storage-and-data-lake-gen2) | `AZURE_BLOB_STORAGE_AND_DATA_LAKE_GEN2` | API key | Community |
| [Box](/latest/lot-language/routes/rest-api-apps/box) | [`BOX`](/latest/lot-language/routes/rest-api-apps/box) [`BOX_UPLOAD`](/latest/lot-language/routes/rest-api-apps/box-upload) | OAuth 2.0 client credentials | Community / Growth |
| [Dropbox](/latest/lot-language/routes/rest-api-apps/dropbox) | [`DROPBOX`](/latest/lot-language/routes/rest-api-apps/dropbox) [`DROPBOX_CONTENT`](/latest/lot-language/routes/rest-api-apps/dropbox-content) [`DROPBOX_NOTIFY`](/latest/lot-language/routes/rest-api-apps/dropbox-notify) | OAuth 2.0 refresh token | Community / Growth |
| [Google Cloud Storage](/latest/lot-language/routes/rest-api-apps/google-cloud-storage) | `GOOGLE_CLOUD_STORAGE` | Bearer | Community |
| [Google Drive](/latest/lot-language/routes/rest-api-apps/google-drive) | `GOOGLE_DRIVE` | Bearer | Community |
| [Google Sheets](/latest/lot-language/routes/rest-api-apps/google-sheets) | `GOOGLE_SHEETS` | Bearer | Community |
| [MinIO](/latest/lot-language/routes/rest-api-apps/minio) | `MINIO` | API key | Community |
| [Nextcloud](/latest/lot-language/routes/rest-api-apps/nextcloud) | `NEXTCLOUD` | Basic | Growth |
| [SharePoint and OneDrive (Microsoft Graph)](/latest/lot-language/routes/rest-api-apps/sharepoint-and-onedrive) | `SHAREPOINT_AND_ONEDRIVE` | Bearer | Community |

### ERP

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Acumatica Cloud ERP](/latest/lot-language/routes/rest-api-apps/acumatica-cloud-erp) | `ACUMATICA_CLOUD_ERP` | OAuth 2.0 refresh token | Community |
| [Coupa](/latest/lot-language/routes/rest-api-apps/coupa) | `COUPA` | OAuth 2.0 client credentials | Community |
| [Dynamics 365 Business Central](/latest/lot-language/routes/rest-api-apps/dynamics365-bc) | `DYNAMICS365_BC` | Bearer | Community |
| [Microsoft Dynamics 365 Finance and Supply Chain](/latest/lot-language/routes/rest-api-apps/dynamics365-fscm) | `DYNAMICS365_FSCM` | Bearer | Community |
| [Epicor Kinetic](/latest/lot-language/routes/rest-api-apps/epicor-kinetic) | `EPICOR_KINETIC` | Bearer | Community |
| [IFS Cloud](/latest/lot-language/routes/rest-api-apps/ifs-cloud) | `IFS_CLOUD` | Bearer | Community |
| [Infor CloudSuite via ION API Gateway](/latest/lot-language/routes/rest-api-apps/infor-cloudsuite-via-ion-api-gateway) | `INFOR_CLOUDSUITE_VIA_ION_API_GATEWAY` | Bearer | Community |
| [Oracle NetSuite (SuiteTalk REST)](/latest/lot-language/routes/rest-api-apps/netsuite) | `NETSUITE` | Bearer | Community |
| [Odoo](/latest/lot-language/routes/rest-api-apps/odoo) | `ODOO` | Bearer | Community |
| [Oracle E-Business Suite (Integrated SOA Gateway)](/latest/lot-language/routes/rest-api-apps/oracle-e-business-suite) | `ORACLE_E_BUSINESS_SUITE` | Basic | Community |
| [Oracle Fusion Cloud ERP and SCM](/latest/lot-language/routes/rest-api-apps/oracle-fusion-erp) | `ORACLE_FUSION_ERP` | Bearer | Community |
| [Oracle JD Edwards EnterpriseOne](/latest/lot-language/routes/rest-api-apps/oracle-jd-edwards) | `ORACLE_JD_EDWARDS` | API key | Community |
| [QAD Adaptive ERP](/latest/lot-language/routes/rest-api-apps/qad-adaptive-erp) | `QAD_ADAPTIVE_ERP` | Basic | Growth |
| [SAP Ariba](/latest/lot-language/routes/rest-api-apps/sap-ariba-open-api) | `SAP_ARIBA` | OAuth 2.0 client credentials | Community |
| [SAP Business One Service Layer](/latest/lot-language/routes/rest-api-apps/sap-b1) | `SAP_B1` | Basic | Community |
| [SAP S/4HANA Cloud](/latest/lot-language/routes/rest-api-apps/sap-s4hana-cloud) | `SAP_S4HANA_CLOUD` | Bearer | Community |
| [SAP S/4HANA on-premise and ECC (SAP Gateway)](/latest/lot-language/routes/rest-api-apps/sap-s4hana-onprem) | `SAP_S4HANA_ONPREM` | Bearer | Community |

### Energy

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [E-REDES and REN open data (Portugal)](/latest/lot-language/routes/rest-api-apps/eredes-open-data) | [`EREDES_OPEN_DATA`](/latest/lot-language/routes/rest-api-apps/eredes-open-data) [`REN_DATA_HUB`](/latest/lot-language/routes/rest-api-apps/ren-data-hub) | None | Community |
| [Electricity Maps](/latest/lot-language/routes/rest-api-apps/electricity-maps) | `ELECTRICITY_MAPS` | API key | Growth |
| [Enphase](/latest/lot-language/routes/rest-api-apps/enphase) | `ENPHASE` | Bearer | Community |
| [Enphase Enlighten API v4](/latest/lot-language/routes/rest-api-apps/enphase-enlighten-api-v4) | `ENPHASE_ENLIGHTEN_API_V4` | API key | Growth |
| [ENTSO-E Transparency Platform](/latest/lot-language/routes/rest-api-apps/entso-e-transparency-platform) | `ENTSO_E_TRANSPARENCY_PLATFORM` | API key | Community |
| [Fronius Solar API (local)](/latest/lot-language/routes/rest-api-apps/fronius-solar-api) | `FRONIUS_SOLAR_API` | None | Community |
| [OCPI 2.2.1 (EV charging roaming)](/latest/lot-language/routes/rest-api-apps/ocpi-2-2-1) | `OCPI_2_2_1` | API key | Community |
| [OpenADR 3.0 (demand response)](/latest/lot-language/routes/rest-api-apps/openadr-3-0) | `OPENADR_3_0` | OAuth 2.0 client credentials | Growth |
| [OpenEI](/latest/lot-language/routes/rest-api-apps/openei) | `OPENEI` | API key | Community |
| [Project Haystack](/latest/lot-language/routes/rest-api-apps/project-haystack) | `PROJECT_HAYSTACK` | API key | Community |
| [Shelly (Gen2+ local RPC and Shelly Cloud)](/latest/lot-language/routes/rest-api-apps/shelly-gen2-rpc) | [`SHELLY_GEN2_RPC`](/latest/lot-language/routes/rest-api-apps/shelly-gen2-rpc) [`SHELLY_CLOUD_CONTROL`](/latest/lot-language/routes/rest-api-apps/shelly-cloud-control) | API key | Community / Growth |
| [SolarEdge](/latest/lot-language/routes/rest-api-apps/solaredge) | `SOLAREDGE` | API key | Community |
| [SolarEdge Monitoring API](/latest/lot-language/routes/rest-api-apps/solaredge-monitoring-api) | `SOLAREDGE_MONITORING_API` | API key | Community |
| [Victron VRM API](/latest/lot-language/routes/rest-api-apps/victron-vrm-api) | `VICTRON_VRM_API` | API key | Community |
| [WattTime](/latest/lot-language/routes/rest-api-apps/watttime) | `WATTTIME` | Login token | Community |

### Field service

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Dynamics 365 Field Service and Connected Field Service](/latest/lot-language/routes/rest-api-apps/dynamics-365-field-service-and-connected-field-service) | `DYNAMICS_365_FIELD_SERVICE_AND_CONNECTED_FIELD_SERVICE` | Bearer | Community |
| [Fracttal One](/latest/lot-language/routes/rest-api-apps/fracttal-one-api) | `FRACTTAL_ONE` | OAuth 2.0 client credentials | Community |
| [HxGN EAM (Hexagon, formerly Infor EAM)](/latest/lot-language/routes/rest-api-apps/hxgn-eam) | `HXGN_EAM` | API key | Community |
| [IBM Maximo Manage (Maximo Application Suite)](/latest/lot-language/routes/rest-api-apps/ibm-maximo-manage) | `IBM_MAXIMO_MANAGE` | API key | Community |
| [Limble CMMS](/latest/lot-language/routes/rest-api-apps/limble-cmms) | `LIMBLE_CMMS` | Basic | Growth |
| [MaintainX](/latest/lot-language/routes/rest-api-apps/maintainx) | `MAINTAINX` | Bearer | Community |
| [SAP Field Service Management](/latest/lot-language/routes/rest-api-apps/sap-field-service-management) | `SAP_FIELD_SERVICE_MANAGEMENT` | OAuth 2.0 client credentials | Community |
| [ServiceMax (PTC)](/latest/lot-language/routes/rest-api-apps/servicemax) | `SERVICEMAX` | OAuth 2.0 client credentials | Community |
| [ServiceTitan](/latest/lot-language/routes/rest-api-apps/service-titan-api) | `SERVICETITAN` | OAuth 2.0 client credentials | Growth |
| [UpKeep](/latest/lot-language/routes/rest-api-apps/upkeep) | `UPKEEP` | API key | Community |

### Finance

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [DocuSign eSignature](/latest/lot-language/routes/rest-api-apps/docu-sign-esignature) | [`DOCU_SIGN_OAUTH`](/latest/lot-language/routes/rest-api-apps/docu-sign-oauth) [`DOCU_SIGN_ESIGNATURE`](/latest/lot-language/routes/rest-api-apps/docu-sign-esignature) | OAuth 2.0 JWT bearer | Community / Growth |
| [QuickBooks Online](/latest/lot-language/routes/rest-api-apps/quickbooks-online) | `QUICKBOOKS_ONLINE` | OAuth 2.0 refresh token | Community |
| [Xero](/latest/lot-language/routes/rest-api-apps/xero) | `XERO` | OAuth 2.0 client credentials | Community |

### Fleet

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [DHL API Developer Portal](/latest/lot-language/routes/rest-api-apps/dhl-api) | [`DHL_API`](/latest/lot-language/routes/rest-api-apps/dhl-api) [`DHL_LOCATION_FINDER`](/latest/lot-language/routes/rest-api-apps/dhl-location-finder) [`MY_DHL_EXPRESS`](/latest/lot-language/routes/rest-api-apps/my-dhl-express) [`DHL_PARCEL_DE`](/latest/lot-language/routes/rest-api-apps/dhl-parcel-de) | API key, Basic, OAuth 2.0 password | Community |
| [EasyPost](/latest/lot-language/routes/rest-api-apps/easypost) | `EASYPOST` | Basic | Growth |
| [FedEx Developer Portal](/latest/lot-language/routes/rest-api-apps/fed-ex-auth) | [`FED_EX_AUTH`](/latest/lot-language/routes/rest-api-apps/fed-ex-auth) [`FED_EX_API`](/latest/lot-language/routes/rest-api-apps/fed-ex-api) [`FED_EX_DOCS`](/latest/lot-language/routes/rest-api-apps/fed-ex-docs) | Bearer | Community / Growth |
| [Geotab (MyGeotab API)](/latest/lot-language/routes/rest-api-apps/geotab) | `GEOTAB` | None | Community |
| [Samsara](/latest/lot-language/routes/rest-api-apps/samsara) | `SAMSARA` | Bearer | Community |
| [Traccar (open-source GPS server)](/latest/lot-language/routes/rest-api-apps/traccar) | `TRACCAR` | Bearer | Community |
| [Trackunit](/latest/lot-language/routes/rest-api-apps/trackunit-iris) | `TRACKUNIT` | OAuth 2.0 client credentials | Growth |
| [UPS Developer Portal](/latest/lot-language/routes/rest-api-apps/ups-api) | `UPS_DEVELOPER_PORTAL` | OAuth 2.0 client credentials | Growth |
| [Webfleet (Bridgestone)](/latest/lot-language/routes/rest-api-apps/webfleet) | `WEBFLEET` | Basic | Growth |

### HR

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [SAP SuccessFactors](/latest/lot-language/routes/rest-api-apps/sap-successfactors) | `SAP_SUCCESSFACTORS` | OAuth 2.0 SAML bearer | Growth |
| [Workday](/latest/lot-language/routes/rest-api-apps/workday) | `WORKDAY` | Bearer | Community |

### Identity

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Auth0](/latest/lot-language/routes/rest-api-apps/auth0) | `AUTH0` | Bearer | Community |
| [Okta](/latest/lot-language/routes/rest-api-apps/okta) | `OKTA` | API key | Community |

### LLMs

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Amazon Bedrock](/latest/lot-language/routes/rest-api-apps/amazon-bedrock-runtime) | [`AMAZON_BEDROCK_RUNTIME`](/latest/lot-language/routes/rest-api-apps/amazon-bedrock-runtime) [`AMAZON_BEDROCK_CONTROL`](/latest/lot-language/routes/rest-api-apps/amazon-bedrock-control) | AWS SigV4 | Community |
| [Anthropic](/latest/lot-language/routes/rest-api-apps/anthropic) | `ANTHROPIC` | API key | Community |
| [Azure OpenAI and Azure AI Foundry](/latest/lot-language/routes/rest-api-apps/azure-openai-and-azure-ai-foundry) | `AZURE_OPENAI_AND_AZURE_AI_FOUNDRY` | API key | Community |
| [Google Gemini API and Vertex AI](/latest/lot-language/routes/rest-api-apps/gemini-api) | [`GEMINI_API`](/latest/lot-language/routes/rest-api-apps/gemini-api) [`VERTEX_AI`](/latest/lot-language/routes/rest-api-apps/vertex-ai) | API key, OAuth 2.0 JWT bearer | Community |
| [Hugging Face Inference Providers and Endpoints](/latest/lot-language/routes/rest-api-apps/hugging-face-inference-providers) | [`HUGGING_FACE_INFERENCE_PROVIDERS`](/latest/lot-language/routes/rest-api-apps/hugging-face-inference-providers) [`HUGGING_FACE_INFERENCE_ENDPOINTS`](/latest/lot-language/routes/rest-api-apps/hugging-face-inference-endpoints) [`HUGGING_FACE_DEDICATED_ENDPOINT`](/latest/lot-language/routes/rest-api-apps/hugging-face-dedicated-endpoint) [`HUGGING_FACE_HUB`](/latest/lot-language/routes/rest-api-apps/hugging-face-hub) | Bearer | Community |
| [Mistral AI](/latest/lot-language/routes/rest-api-apps/mistral-ai) | `MISTRAL_AI` | Bearer | Community |
| [Ollama (local models)](/latest/lot-language/routes/rest-api-apps/ollama) | `OLLAMA` | None | Community |
| [OpenAI](/latest/lot-language/routes/rest-api-apps/openai) | `OPENAI` | Bearer | Community |

### Manufacturing

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Aras Innovator](/latest/lot-language/routes/rest-api-apps/aras-innovator-api) | `ARAS_INNOVATOR` | OAuth 2.0 refresh token | Community |
| [Autodesk Platform Services (Data Management, Manufacturing Data Model, Fusion)](/latest/lot-language/routes/rest-api-apps/autodesk-platform-services-api) | `AUTODESK_PLATFORM_SERVICES` | OAuth 2.0 client credentials | Community |
| [AVEVA MES (formerly Wonderware MES)](/latest/lot-language/routes/rest-api-apps/aveva-mes-api) | `AVEVA_MES` | OAuth 2.0 client credentials | Growth |
| [BarTender (Seagull Scientific) label printing](/latest/lot-language/routes/rest-api-apps/bar-tender-actions) | [`BAR_TENDER_ACTIONS`](/latest/lot-language/routes/rest-api-apps/bar-tender-actions) [`BAR_TENDER_CLOUD`](/latest/lot-language/routes/rest-api-apps/bar-tender-cloud) [`BAR_TENDER_PRINT_PORTAL`](/latest/lot-language/routes/rest-api-apps/bar-tender-print-portal) | Bearer | Community |
| [Critical Manufacturing MES](/latest/lot-language/routes/rest-api-apps/critical-manufacturing-mes) | `CRITICAL_MANUFACTURING_MES` | OAuth 2.0 client credentials | Growth |
| [DELMIA Apriso (Dassault Systèmes)](/latest/lot-language/routes/rest-api-apps/delmia-apriso) | `DELMIA_APRISO` | OAuth 2.0 password | Community |
| [MachineMetrics](/latest/lot-language/routes/rest-api-apps/machinemetrics) | `MACHINEMETRICS` | Bearer | Community |
| [PTC Windchill (Windchill REST Services)](/latest/lot-language/routes/rest-api-apps/ptc-windchill) | `PTC_WINDCHILL` | API key | Community |
| [QAD Redzone](/latest/lot-language/routes/rest-api-apps/qad-redzone) | `QAD_REDZONE` | OAuth 2.0 client credentials | Community |
| [Rockwell Plex Smart Manufacturing Platform](/latest/lot-language/routes/rest-api-apps/rockwell-plex-smart-manufacturing-platform) | `ROCKWELL_PLEX_SMART_MANUFACTURING_PLATFORM` | API key | Community |
| [SAP Digital Manufacturing](/latest/lot-language/routes/rest-api-apps/sap-digital-manufacturing) | `SAP_DIGITAL_MANUFACTURING` | Bearer | Community |
| [Sepasoft MES for Ignition](/latest/lot-language/routes/rest-api-apps/sepasoft-mes-for-ignition) | `SEPASOFT_MES_FOR_IGNITION` | API key | Community |
| [Siemens Industrial Edge Management](/latest/lot-language/routes/rest-api-apps/siemens-industrial-edge-management) | `SIEMENS_INDUSTRIAL_EDGE_MANAGEMENT` | Login token | Community |
| [Siemens Opcenter Execution](/latest/lot-language/routes/rest-api-apps/siemens-opcenter-execution) | `SIEMENS_OPCENTER_EXECUTION` | API key | Community |
| [Siemens Teamcenter](/latest/lot-language/routes/rest-api-apps/siemens-teamcenter) | `SIEMENS_TEAMCENTER` | None | Community |
| [Sight Machine](/latest/lot-language/routes/rest-api-apps/sight-machine) | `SIGHT_MACHINE` | API key | Community |
| [Tulip](/latest/lot-language/routes/rest-api-apps/tulip) | `TULIP` | Basic | Community |
| [Veeva Vault (QMS, QualityDocs)](/latest/lot-language/routes/rest-api-apps/veeva-vault-api) | `VEEVA_VAULT` | Bearer | Community |

### Maps

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Google Maps Platform](/latest/lot-language/routes/rest-api-apps/google-maps-web-services) | [`GOOGLE_MAPS_WEB_SERVICES`](/latest/lot-language/routes/rest-api-apps/google-maps-web-services) [`GOOGLE_GEOLOCATION`](/latest/lot-language/routes/rest-api-apps/google-geolocation) [`GOOGLE_ROUTES`](/latest/lot-language/routes/rest-api-apps/google-routes) [`GOOGLE_ROADS`](/latest/lot-language/routes/rest-api-apps/google-roads) [`GOOGLE_PLACES`](/latest/lot-language/routes/rest-api-apps/google-places) [`GOOGLE_ADDRESS_VALIDATION`](/latest/lot-language/routes/rest-api-apps/google-address-validation) [`GOOGLE_WEATHER`](/latest/lot-language/routes/rest-api-apps/google-weather) [`GOOGLE_AIR_QUALITY`](/latest/lot-language/routes/rest-api-apps/google-air-quality) | API key | Community |
| [HERE Geocoding](/latest/lot-language/routes/rest-api-apps/here-geocoding) | `HERE_GEOCODING` | API key | Community |
| [HERE Platform](/latest/lot-language/routes/rest-api-apps/here-geocode) | [`HERE_GEOCODE`](/latest/lot-language/routes/rest-api-apps/here-geocode) [`HERE_REVERSE_GEOCODE`](/latest/lot-language/routes/rest-api-apps/here-reverse-geocode) [`HERE_MULTI_REVERSE_GEOCODE`](/latest/lot-language/routes/rest-api-apps/here-multi-reverse-geocode) [`HERE_DISCOVER`](/latest/lot-language/routes/rest-api-apps/here-discover) [`HERE_BROWSE`](/latest/lot-language/routes/rest-api-apps/here-browse) [`HERE_LOOKUP`](/latest/lot-language/routes/rest-api-apps/here-lookup) [`HERE_ROUTING`](/latest/lot-language/routes/rest-api-apps/here-routing) [`HERE_ISOLINE`](/latest/lot-language/routes/rest-api-apps/here-isoline) [`HERE_MATRIX`](/latest/lot-language/routes/rest-api-apps/here-matrix) [`HERE_TRAFFIC`](/latest/lot-language/routes/rest-api-apps/here-traffic) [`HERE_WAYPOINTS_SEQUENCE`](/latest/lot-language/routes/rest-api-apps/here-waypoints-sequence) [`HERE_ROUTE_MATCHING`](/latest/lot-language/routes/rest-api-apps/here-route-matching) [`HERE_TOUR_PLANNING`](/latest/lot-language/routes/rest-api-apps/here-tour-planning) | API key | Community |
| [Mapbox](/latest/lot-language/routes/rest-api-apps/mapbox) | `MAPBOX` | API key | Community |
| [OpenStreetMap: Nominatim and OSRM (self-hostable)](/latest/lot-language/routes/rest-api-apps/osm-nominatim) | [`OSM_NOMINATIM`](/latest/lot-language/routes/rest-api-apps/osm-nominatim) [`OSM_OSRM`](/latest/lot-language/routes/rest-api-apps/osm-osrm) | None | Community |

### Messaging

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Amazon SNS](/latest/lot-language/routes/rest-api-apps/amazon-sns) | `AMAZON_SNS` | AWS SigV4 | Community |
| [Apprise API](/latest/lot-language/routes/rest-api-apps/apprise-api) | `APPRISE_API` | None | Community |
| [Azure Service Bus](/latest/lot-language/routes/rest-api-apps/azure-service-bus) | `AZURE_SERVICE_BUS` | API key | Community |
| [Discord](/latest/lot-language/routes/rest-api-apps/discord) | `DISCORD` | API key | Community |
| [Firebase Cloud Messaging (HTTP v1)](/latest/lot-language/routes/rest-api-apps/firebase-cloud-messaging) | `FIREBASE_CLOUD_MESSAGING` | Bearer | Community |
| [Mailgun](/latest/lot-language/routes/rest-api-apps/mailgun) | `MAILGUN` | Basic | Growth |
| [Mattermost](/latest/lot-language/routes/rest-api-apps/mattermost) | `MATTERMOST` | Bearer | Community |
| [Microsoft Teams (Graph and Workflows webhooks)](/latest/lot-language/routes/rest-api-apps/microsoft-teams) | `MICROSOFT_TEAMS` | Bearer | Community |
| [ntfy](/latest/lot-language/routes/rest-api-apps/ntfy) | `NTFY` | Bearer | Community |
| [Pushover](/latest/lot-language/routes/rest-api-apps/pushover) | `PUSHOVER` | API key | Community |
| [SendGrid](/latest/lot-language/routes/rest-api-apps/sendgrid) | `SENDGRID` | Bearer | Community |
| [Slack Web API](/latest/lot-language/routes/rest-api-apps/slack) | `SLACK` | Bearer | Community |
| [Telegram Bot API](/latest/lot-language/routes/rest-api-apps/telegram-bot-api) | `TELEGRAM_BOT_API` | None | Community |
| [Twilio (SMS, Voice, Verify, WhatsApp)](/latest/lot-language/routes/rest-api-apps/twilio) | `TWILIO` | Basic | Community |
| [WhatsApp Business Platform (Meta Cloud API)](/latest/lot-language/routes/rest-api-apps/whatsapp-business-platform) | `WHATSAPP_BUSINESS_PLATFORM` | Bearer | Community |

### Monitoring

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Amazon CloudWatch](/latest/lot-language/routes/rest-api-apps/amazon-cloudwatch) | `AMAZON_CLOUDWATCH` | AWS SigV4 | Community |
| [Azure Monitor](/latest/lot-language/routes/rest-api-apps/azure-monitor) | `AZURE_MONITOR` | Bearer | Community |
| [BMC Helix ITSM](/latest/lot-language/routes/rest-api-apps/bmc-helix-itsm) | `BMC_HELIX_ITSM` | Login token | Growth |
| [Datadog](/latest/lot-language/routes/rest-api-apps/datadog) | `DATADOG` | API key | Community |
| [Dynatrace](/latest/lot-language/routes/rest-api-apps/dynatrace) | `DYNATRACE` | API key | Community |
| [Grafana (OSS, Enterprise, Cloud)](/latest/lot-language/routes/rest-api-apps/grafana) | `GRAFANA` | Bearer | Community |
| [Jira Service Management](/latest/lot-language/routes/rest-api-apps/jira-service-management) | `JIRA_SERVICE_MANAGEMENT` | Bearer | Community |
| [New Relic](/latest/lot-language/routes/rest-api-apps/new-relic) | `NEW_RELIC` | API key | Community |
| [Opsgenie](/latest/lot-language/routes/rest-api-apps/opsgenie) | `OPSGENIE` | API key | Community |
| [PagerDuty](/latest/lot-language/routes/rest-api-apps/pagerduty) | `PAGERDUTY` | API key | Community |
| [Prometheus, Alertmanager and Pushgateway](/latest/lot-language/routes/rest-api-apps/prometheus-alertmanager-and-pushgateway) | `PROMETHEUS_ALERTMANAGER_AND_PUSHGATEWAY` | None | Community |
| [Sentry](/latest/lot-language/routes/rest-api-apps/sentry) | `SENTRY` | Bearer | Community |
| [ServiceNow](/latest/lot-language/routes/rest-api-apps/servicenow) | `SERVICENOW` | Bearer | Community |
| [Splunk Enterprise and Cloud](/latest/lot-language/routes/rest-api-apps/splunk-enterprise-and-cloud) | `SPLUNK_ENTERPRISE_AND_CLOUD` | API key | Community |
| [Zabbix](/latest/lot-language/routes/rest-api-apps/zabbix) | `ZABBIX` | Bearer | Community |

### Payments

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Shopify](/latest/lot-language/routes/rest-api-apps/shopify) | `SHOPIFY` | API key | Community |
| [Stripe](/latest/lot-language/routes/rest-api-apps/stripe) | `STRIPE` | Bearer | Community |

### Public data

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Open-Meteo](/latest/lot-language/routes/rest-api-apps/open-meteo) | `OPEN_METEO` | None | Community |
| [OpenAQ](/latest/lot-language/routes/rest-api-apps/openaq) | `OPENAQ` | API key | Community |
| [OpenWeatherMap](/latest/lot-language/routes/rest-api-apps/openweathermap) | `OPENWEATHERMAP` | API key | Community |
| [PurpleAir](/latest/lot-language/routes/rest-api-apps/purpleair) | `PURPLEAIR` | API key | Community |

### SCADA

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [AVEVA CONNECT data services (formerly AVEVA Data Hub / OSIsoft Cloud Services)](/latest/lot-language/routes/rest-api-apps/aveva-connect-data-services) | `AVEVA_CONNECT_DATA_SERVICES` | Bearer | Community |
| [AVEVA PI Web API (PI System, FactoryTalk Historian)](/latest/lot-language/routes/rest-api-apps/aveva-pi-web-api) | `AVEVA_PI_WEB_API` | Bearer | Community |
| [Canary Historian](/latest/lot-language/routes/rest-api-apps/canary-read) | [`CANARY_READ`](/latest/lot-language/routes/rest-api-apps/canary-read) [`CANARY_WRITE`](/latest/lot-language/routes/rest-api-apps/canary-write) | None | Community |
| [Clarify (Searis)](/latest/lot-language/routes/rest-api-apps/clarify) | `CLARIFY` | OAuth 2.0 client credentials | Community |
| [GE Vernova Proficy Historian](/latest/lot-language/routes/rest-api-apps/ge-vernova-proficy-historian) | `GE_VERNOVA_PROFICY_HISTORIAN` | OAuth 2.0 client credentials | Community |
| [HighByte Intelligence Hub](/latest/lot-language/routes/rest-api-apps/high-byte-data) | [`HIGH_BYTE_DATA`](/latest/lot-language/routes/rest-api-apps/high-byte-data) [`HIGH_BYTE_CONFIG`](/latest/lot-language/routes/rest-api-apps/high-byte-config) | Bearer | Community |
| [Ignition (Inductive Automation)](/latest/lot-language/routes/rest-api-apps/ignition) | `IGNITION` | API key | Community |
| [Kepware (PTC KEPServerEX, ThingWorx Kepware Server, Kepware+)](/latest/lot-language/routes/rest-api-apps/kepware-config) | [`KEPWARE_CONFIG`](/latest/lot-language/routes/rest-api-apps/kepware-config) [`KEPWARE_IOT_GATEWAY`](/latest/lot-language/routes/rest-api-apps/kepware-iot-gateway) | API key | Community |
| [Litmus Edge](/latest/lot-language/routes/rest-api-apps/litmus-edge) | `LITMUS_EDGE` | OAuth 2.0 client credentials | Community |
| [N3uron](/latest/lot-language/routes/rest-api-apps/n3uron) | `N3URON` | API key | Community |
| [Node-RED (Admin API, HTTP In nodes) and FlowFuse](/latest/lot-language/routes/rest-api-apps/node-red-admin) | [`NODE_RED_ADMIN`](/latest/lot-language/routes/rest-api-apps/node-red-admin) [`NODE_RED_HTTP_IN`](/latest/lot-language/routes/rest-api-apps/node-red-http-in) [`FLOW_FUSE_API`](/latest/lot-language/routes/rest-api-apps/flow-fuse-api) | Bearer | Community |
| [Rhize (ISA-95 manufacturing data hub)](/latest/lot-language/routes/rest-api-apps/rhize-api) | `RHIZE` | OAuth 2.0 client credentials | Community |
| [Seeq](/latest/lot-language/routes/rest-api-apps/seeq) | `SEEQ` | Login token | Community |
| [Siemens WinCC Unified (GraphQL server)](/latest/lot-language/routes/rest-api-apps/siemens-wincc-unified) | `SIEMENS_WINCC_UNIFIED` | Bearer | Community |

### Testing

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [HTTPBin](/latest/lot-language/routes/rest-api-apps/httpbin) | `HTTPBIN` | Bearer | Community |
| [JSONPlaceholder](/latest/lot-language/routes/rest-api-apps/jsonplaceholder) | `JSONPLACEHOLDER` | Bearer | Community |
| [Postman Echo](/latest/lot-language/routes/rest-api-apps/postman-echo) | `POSTMAN_ECHO` | Bearer | Community |

### Work and DevOps

| App | App code | Auth (`CLIENT_AUTH`) | Minimum tier |
| - | - | - | - |
| [Airtable](/latest/lot-language/routes/rest-api-apps/airtable) | `AIRTABLE` | Bearer | Community |
| [Asana](/latest/lot-language/routes/rest-api-apps/asana) | `ASANA` | Bearer | Community |
| [Azure DevOps](/latest/lot-language/routes/rest-api-apps/azure-devops) | `AZURE_DEVOPS` | API key | Growth |
| [Docker Hub](/latest/lot-language/routes/rest-api-apps/docker-hub) | `DOCKER_HUB` | Bearer | Community |
| [Excel Online](/latest/lot-language/routes/rest-api-apps/excel-online) | `EXCEL_ONLINE` | Bearer | Community |
| [GitHub REST](/latest/lot-language/routes/rest-api-apps/github) | `GITHUB` | Bearer | Community |
| [GitLab](/latest/lot-language/routes/rest-api-apps/gitlab) | `GITLAB` | API key | Community |
| [Jira Cloud (Software)](/latest/lot-language/routes/rest-api-apps/jira-cloud) | `JIRA_CLOUD` | Bearer | Community |
| [monday.com](/latest/lot-language/routes/rest-api-apps/monday-com) | `MONDAY_COM` | API key | Community |
| [Notion](/latest/lot-language/routes/rest-api-apps/notion) | `NOTION` | Bearer | Community |
| [Smartsheet](/latest/lot-language/routes/rest-api-apps/smartsheet) | `SMARTSHEET` | Bearer | Growth |
| [Trello](/latest/lot-language/routes/rest-api-apps/trello) | `TRELLO` | API key | Growth |

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)

## Discover connectors

The broker ships every REST API app in this catalog as a connector template. List them all with `-listTemplates`, and get one template with `-connectorCode` (`-routeCode` remains a supported alias). Publish both commands to `$SYS/Coreflux/Command`:

| Command | What it returns |
| - | - |
| `-listTemplates` (`--list-templates`) | JSON object keyed by template type, one card per built-in connector template and per REST API connector template. |
| `-connectorCode <type\|APP_CODE>` (`--connector-code`; alias `-routeCode`) | The JSON card for one template. `<type>` is a connector type such as `REST_API`, or a REST API app code such as `AIRTABLE`, `SAP_S4HANA_CLOUD` or `GEMINI_API`. |

An app with one connector is keyed by its folder name, upper-cased with every non-alphanumeric run turned into `_` (`sap-s4hana-cloud` becomes `SAP_S4HANA_CLOUD`). An app with several connectors keys each one by its connector name without the `RestApi` suffix (`GeminiApiRestApi` becomes `GEMINI_API`). The [catalog](/latest/lot-language/routes/rest-api-apps#catalog) lists every app code.

Each card has this shape (from `RouteHandler.BuildTemplatePayload`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "type": "AIRTABLE",
  "baseType": "REST_API",
  "connector": true,
  "template": "DEFINE CONNECTOR #RouteName,string,...# WITH TYPE REST_API ...",
  "metadata": {
    "name": "Airtable",
    "image": "<base64 PNG>",
    "status": "beta",
    "category": "...",
    "description": "...",
    "doclink": "https://docs.coreflux.org/.../rest-api-apps/airtable",
    "license": "community",
    "minimumTier": "Community",
    "actionSlots": 5,
    "availableOnThisBroker": true,
    "requiredSecrets": ["AIRTABLE_API_TOKEN"]
  }
}
```

* `status` is `beta` for every app today: the broker accepts no other value. The docs call this technical preview.
* `license` is `community` when a Community broker can deploy the template, otherwise `licensed`. `minimumTier` is `Community`, `Growth` or `Enterprise`, `actionSlots` is the number of actions the connector registers, and `availableOnThisBroker` says whether the current license can deploy it.
* `requiredSecrets` lists the broker secrets the template reads (`GET SECRET` or `{secret.NAME}`). Create them before you deploy.
* `connector` is `true` and `baseType` is `REST_API` for every vendor connector. For built-in connector templates `connector` is `false` and `baseType` equals `type`.
* An app code is not a connector type: deploy the `template` with `WITH TYPE REST_API`, not `WITH TYPE AIRTABLE`.
* `template` is the deployable connector code only. The `ADD METADATA` block is split off into `metadata`, because `-addConnector` rejects it.
* `#Name,type,description,regex,required#` markers are Hub placeholders (for example `#RouteName#` and `#BaseUrl#`). Replace them with real values before you deploy with `-addConnector`.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-listTemplates"
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AIRTABLE"
```


# REST API Connectors
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

Connect to external REST APIs or expose HTTP endpoints from your broker with client/server modes

## REST API Overview

The `REST_API` connector enables HTTP communication in both directions:

* **Client Mode** - Make HTTP requests to external APIs triggered by MQTT messages
* **Server Mode** - Expose HTTP endpoints that accept data and publish it to MQTT topics

> [!TIP]
>
> REST API connectors are ideal for integrating with web services, webhooks, cloud APIs, and creating HTTP-to-MQTT bridges.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR APIConnector WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
    ADD EVENT GetData
        WITH SOURCE_TOPIC "api/requests/data"
        WITH DESTINATION_TOPIC "api/responses/data"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/data"
```

***

## How REST API Connectors Work

A REST API connector bridges the HTTP and MQTT worlds. It contains **events** that define what happens when data flows through—either from MQTT to HTTP (client mode) or from HTTP to MQTT (server mode).

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph ClientMode
        A[MQTT Message] -->|triggers| B[HTTP Request]
        B -->|response| C[MQTT Topic]
    end
    subgraph ServerMode
        D[HTTP Request] -->|triggers| E[MQTT Topic]
    end
```

| Component | Purpose |
| - | - |
| `REST_API_CONFIG` | Connection settings—base URL, authentication, SSL, timeouts |
| `EVENT` | Defines a single HTTP operation with its trigger, method, and routing |
| `SOURCE_TOPIC` | MQTT topic that triggers the HTTP request (client mode) |
| `DESTINATION_TOPIC` | MQTT topic where results are published |
| `ENDPOINT` | The HTTP path to call (can include placeholders) |

***

## REST API Configuration

### REST\_API\_CONFIG Parameters

> **Client Settings**
>
> **BASE\_ADDRESS** `string` *required*
>
> Base URL for HTTP requests (e.g., `https://api.example.com`).
>
> **ENABLE\_CLIENT** `boolean`
>
> Enable HTTP client functionality. Default: false.
>
> **REQUEST\_TIMEOUT** `integer`
>
> Request timeout in seconds. Default: 30.
>
> **DEFAULT\_CONTENT\_TYPE** `string`
>
> Default content type. Default: application/json.

> **Server Settings**
>
> **ENABLE\_SERVER** `boolean`
>
> Enable HTTP server functionality. Default: false.
>
> **SERVER\_PORT** `integer`
>
> HTTP server port. Default: 8080.

> **Authentication**
>
> **USERNAME** `string`
>
> Basic authentication username.
>
> **PASSWORD** `string`
>
> Basic authentication password.

> **SSL/Security**
>
> **USE\_SSL** `boolean`
>
> Enable SSL/TLS. Default: false.
>
> **IGNORE\_CERT\_ERRORS** `boolean`
>
> Ignore certificate validation errors. Default: false.

> **CORS**
>
> **ENABLE\_CORS** `boolean`
>
> Enable CORS headers. Default: false.
>
> **CORS\_ORIGINS** `string`
>
> Allowed CORS origins. Default: \* (all).

***

## Client Mode

Use client mode when your broker needs to **call external APIs**. An MQTT message triggers the HTTP request, and the response is published back to MQTT.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    A["MQTT: weather/request<br/>{city: 'London'}"] -->|triggers| B[REST API Connector]
    B -->|GET /weather?q=London| C[External API]
    C -->|JSON response| B
    B -->|publishes| D["MQTT: weather/response<br/>{temp: 15, ...}"]
```

### Event Configuration

> **Trigger & Routing**
>
> **SOURCE\_TOPIC** `string`
>
> MQTT topic that triggers the HTTP request.
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic to publish HTTP response.

> **HTTP Request**
>
> **METHOD** `string`
>
> HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`.
>
> **ENDPOINT** `string`
>
> API endpoint path (supports placeholders).
>
> **BODY** `string`
>
> Request body for POST/PUT (supports placeholders).

### Placeholder Support

Use placeholders in endpoints and bodies to insert dynamic values from the MQTT message:

| Placeholder | Description |
| - | - |
| `{payload}` | Full MQTT payload as-is |
| `{value.json}` | Parsed JSON payload |
| `{value.json.field}` | Specific field from JSON payload |
| `{source_topic}` | Original MQTT topic |
| `{timestamp}` | Message timestamp |

A placeholder in `ENDPOINT` stays on the connector's `BASE_ADDRESS`. A value that points at another host, such as `/evil.example/x` or `https://evil.example/x`, is refused, and the reply topic gets a `RequestRejected` error. An `ENDPOINT` you write as a full URL still uses that URL.

### Client Examples

**GET Request**

Fetch data from an external API when an MQTT message arrives:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WeatherAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.openweathermap.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
    ADD EVENT GetWeather
        WITH SOURCE_TOPIC "weather/request"
        WITH DESTINATION_TOPIC "weather/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/weather?q={value.json.city}&appid={value.json.apikey}"
```

When a message like `{"city": "London", "apikey": "abc123"}` arrives at `weather/request`, the connector calls the API and publishes the weather data to `weather/response`.

**POST Request**

Send data to an external API:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR NotificationAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.notification-service.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
    ADD EVENT SendNotification
        WITH SOURCE_TOPIC "notifications/send"
        WITH DESTINATION_TOPIC "notifications/result"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/notify"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{payload}"
```

The entire MQTT payload is forwarded as the HTTP request body using `{payload}`.

**With Authentication**

Use basic authentication for protected APIs:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AuthenticatedAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://secure-api.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USERNAME "api_user"
        WITH PASSWORD "api_secret"
        WITH USE_SSL "true"
    ADD EVENT SecureRequest
        WITH SOURCE_TOPIC "secure/request"
        WITH DESTINATION_TOPIC "secure/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/protected/data"
```

The username and password are sent as HTTP Basic Authentication headers automatically.

***

## Server Mode

Use server mode when external systems need to **send data to your broker via HTTP**. The broker exposes an HTTP endpoint that accepts requests and publishes the data to MQTT topics.

> [!TIP]
>
> **Common use case:** Your web application, mobile app, or third-party service needs to push data into the MQTT broker without implementing an MQTT client.

### Why Use Server Mode?

| Scenario | How Server Mode Helps |
| - | - |
| Web dashboards | Submit commands or data via simple HTTP POST |
| Mobile apps | Send sensor data without MQTT libraries |
| Webhooks | Receive callbacks from services like GitHub, Stripe, Slack |
| Legacy systems | Integrate systems that only support HTTP |
| Firewalled environments | Accept data through standard HTTP ports |

### Server Event Configuration

> **Endpoint & Method**
>
> **ENDPOINT** `string`
>
> The HTTP path to expose (e.g., `/api/sensors`).
>
> **METHOD** `string`
>
> HTTP method to accept: `GET`, `POST`, `PUT`, `DELETE`.

> **MQTT Routing**
>
> **DESTINATION\_TOPIC** `string`
>
> MQTT topic where incoming HTTP data is published.

### Server Examples

**Accept Sensor Data**

Expose an endpoint for devices to submit readings via HTTP:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorHTTPBridge WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH ENABLE_CORS "true"
    ADD EVENT ReceiveSensorData
        WITH ENDPOINT "/api/sensors"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "sensors/from/http"
```

**Usage:** Send sensor data with a simple HTTP POST:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -X POST http://broker-ip:8080/api/sensors \
  -H "Content-Type: application/json" \
  -d '{"sensor_id": "temp-01", "value": 25.5}'
```

The data is published to `sensors/from/http` and available to all MQTT subscribers.

**Multiple Endpoints**

Expose different endpoints for different data types:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MultiEndpointAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH ENABLE_CORS "true"
    
    ADD EVENT ReceiveTemperature
        WITH ENDPOINT "/api/temperature"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "sensors/temperature/http"
    
    ADD EVENT ReceivePressure
        WITH ENDPOINT "/api/pressure"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "sensors/pressure/http"
    
    ADD EVENT ReceiveCommands
        WITH ENDPOINT "/api/commands"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "commands/from/http"
```

Each endpoint connectors to a different MQTT topic for organized data handling.

**Webhook Receiver**

Accept webhooks from external services:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9000'
    
    ADD EVENT GitHubWebhook
        WITH ENDPOINT "/webhooks/github"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "webhooks/github/events"
    
    ADD EVENT StripeWebhook
        WITH ENDPOINT "/webhooks/stripe"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "webhooks/stripe/events"
```

Configure GitHub or Stripe to send webhooks to `http://your-broker:9000/webhooks/github`. Events appear on the corresponding MQTT topics.

**CORS for Web Apps**

Enable cross-origin requests for browser-based applications:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WebAppAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '3000'
        WITH ENABLE_CORS "true"
        WITH CORS_ORIGINS "https://app.example.com, https://admin.example.com"
    ADD EVENT SubmitData
        WITH ENDPOINT "/api/submit"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "webapp/submissions"
```

Only requests from the specified origins are allowed. Use `"*"` for development (not recommended for production).

***

## Combined Client and Server

A single connector can operate in both modes—accepting HTTP requests AND calling external APIs:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BidirectionalHTTP WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://external-api.com"
        WITH ENABLE_CLIENT "true"
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH USE_SSL "true"
        WITH ENABLE_CORS "true"
    
    // Server: Accept HTTP, publish to MQTT
    ADD EVENT ReceiveFromHTTP
        WITH ENDPOINT "/api/receive"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "http/incoming"
    
    // Client: MQTT triggers external HTTP call
    ADD EVENT CallExternalAPI
        WITH SOURCE_TOPIC "http/outgoing"
        WITH DESTINATION_TOPIC "http/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data"
```

***

## Complete Examples

**IoT Dashboard API**

Full API for a web dashboard to read sensor data and send commands:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DashboardAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH ENABLE_CORS "true"
        WITH DEFAULT_CONTENT_TYPE "application/json"
    
    ADD EVENT PostSensorData
        WITH ENDPOINT "/api/sensors"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "dashboard/sensors/incoming"
    
    ADD EVENT PostCommand
        WITH ENDPOINT "/api/commands"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "commands/from/dashboard"
    
    ADD EVENT PostAlert
        WITH ENDPOINT "/api/alerts"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "alerts/from/dashboard"
```

**Third-Party Integration**

Integrate with an external CRM or ERP system:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CRMIntegration WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.crm-system.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
    
    ADD EVENT CreateRecord
        WITH SOURCE_TOPIC "crm/create"
        WITH DESTINATION_TOPIC "crm/created"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/records"
        WITH HEADERS
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.data}"
    
    ADD EVENT UpdateRecord
        WITH SOURCE_TOPIC "crm/update"
        WITH DESTINATION_TOPIC "crm/updated"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/records/{value.json.id}"
        WITH BODY "{value.json.data}"
    
    ADD EVENT DeleteRecord
        WITH SOURCE_TOPIC "crm/delete"
        WITH DESTINATION_TOPIC "crm/deleted"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/v2/records/{value.json.id}"
```

***

## Troubleshooting

> **Connection Timeout**
>
> * Verify BASE\_ADDRESS is correct
> * Check firewall allows outbound connections
> * Increase REQUEST\_TIMEOUT if API is slow
> * Verify network connectivity

> **SSL/TLS Errors**
>
> * Ensure USE\_SSL matches the API requirements
> * For self-signed certificates, set IGNORE\_CERT\_ERRORS (not recommended for production)
> * Verify certificate chain is complete

> **Authentication Failed**
>
> * Verify USERNAME and PASSWORD are correct
> * Check Authorization header format
> * Ensure API key is valid and not expired

> **CORS Errors**
>
> * Enable CORS on the server: `WITH ENABLE_CORS "true"`
> * Configure specific allowed origins
> * Check browser console for specific CORS error messages

> **No Response Published**
>
> * Verify DESTINATION\_TOPIC is configured
> * Check MQTT broker connectivity
> * Monitor broker logs for errors

***

## Best Practices

> **Use HTTPS in Production**
>
> Always use SSL/TLS for external API connections:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH USE_SSL "true"
> ```

> **Set Appropriate Timeouts**
>
> Configure timeouts based on expected API response times:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH REQUEST_TIMEOUT '30'
> ```

> **Handle Errors Gracefully**
>
> Subscribe to response topics to monitor API call results and handle failures in your Actions.

> **Secure Server Endpoints**
>
> When exposing HTTP server endpoints:
>
> * Use authentication where needed
> * Limit CORS origins to specific domains
> * Consider rate limiting at the network level

> **Use Environment-Specific Base URLs**
>
> Configure different base URLs for development and production environments.

***

## REST API app templates

Ready-made client connectors (public test APIs, weather, Slack, GitHub, and planned enterprise systems such as SAP HANA and Salesforce) are listed in the [REST API Apps](/latest/lot-language/routes/rest-api-apps) catalog. Each app page shows the LoT connector definition, the event table, and how auth is passed.

> [!NOTE]
>
> That catalog does not include competitor brokers (HiveMQ, EMQX, ThingWorx) or OEM device connectors.

## Discover templates and REST API apps: -listTemplates and -connectorCode

The broker ships every REST API app on this catalog as a template, keyed by its **app code**. Two broker commands, published to `$SYS/Coreflux/Command`, expose them (defined in `Commands/Commands.cs`):

| Command | What it returns |
| - | - |
| `-listTemplates` (`--list-templates`) | JSON object keyed by template type, one card per built-in connector template and per REST API app. |
| `-connectorCode <type\|APP_CODE>` (`--connector-code`; alias `-routeCode`) | The JSON card for one template. The argument is a connector type such as `REST_API`, or a REST API app code such as `AIRTABLE`, `SAP_S4HANA_CLOUD` or `GEMINI_API`. |

An app with one connector is keyed by its folder name, upper-cased with every non-alphanumeric run turned into `_` (`sap-s4hana-cloud` becomes `SAP_S4HANA_CLOUD`). An app with several connectors keys each one by its connector name without the `RestApi` suffix (`GeminiApiRestApi` becomes `GEMINI_API`). The [catalog](/latest/lot-language/routes/rest-api-apps#catalog) lists every app code.

Each card has this shape (from `RouteHandler.BuildTemplatePayload`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "type": "AIRTABLE",
  "baseType": "REST_API",
  "connector": true,
  "template": "DEFINE CONNECTOR #RouteName,string,...# WITH TYPE REST_API ...",
  "metadata": {
    "name": "Airtable",
    "image": "<base64 PNG>",
    "status": "beta",
    "category": "...",
    "description": "...",
    "doclink": "https://docs.coreflux.org/.../rest-api-apps/airtable",
    "license": "community",
    "minimumTier": "Community",
    "actionSlots": 5,
    "availableOnThisBroker": true,
    "requiredSecrets": ["AIRTABLE_API_TOKEN"]
  }
}
```

* `status` is `beta` for every app today: the broker accepts no other value. The docs call this technical preview.
* `license` is `community` when a Community broker can deploy the template, otherwise `licensed`. `minimumTier` is `Community`, `Growth` or `Enterprise`, `actionSlots` is the number of actions the connector registers, and `availableOnThisBroker` says whether the current license can deploy it.
* `requiredSecrets` lists the broker secrets the template reads (`GET SECRET` or `{secret.NAME}`). Create them before you deploy.
* `connector` is `true` and `baseType` is `REST_API` for every REST API app. For built-in connector templates `connector` is `false` and `baseType` equals `type`. The field keeps the name `connector` for compatibility; it marks a REST API app.
* An app code is not a connector type: deploy the `template` with `WITH TYPE REST_API`, not `WITH TYPE AIRTABLE`.
* `template` is the deployable connector code only. The `ADD METADATA` block is split off into `metadata`, because `-addConnector` rejects it.
* `#Name,type,description,regex,required#` markers are Hub placeholders (for example `#RouteName#` and `#BaseUrl#`). Replace them with real values before you deploy with `-addConnector` (`-addRoute` remains a supported alias).

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-listTemplates"
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode AIRTABLE"
```

## Next Steps

> **[Streaming Connectors](./streaming/kafka)**
>
> Stream MQTT messages through Kafka.

> **[Connector Examples](./examples)**
>
> See complete connector configuration examples.


# Store and Forward Configuration
Source: https://docs.coreflux.org/latest/lot-language/routes/store-and-forward

How LoT connectors buffer MQTT messages when a destination is slow, cap the buffer with ADD CONNECTOR_CONFIG, and choose backpressure or drop

## Store and forward in LoT connectors

Store and forward means holding messages while the next hop is slow or unavailable, then passing them on when it catches up. In Coreflux, every LoT connector sits behind a shared, **bounded, in-memory queue** between the broker and the connector's handlers. `ADD CONNECTOR_CONFIG` decides what each connector does when that queue is full: wait (backpressure) or drop the newest message. `ADD ROUTE_CONFIG` remains a supported alias of the same block.

> [!TIP]
>
> **Like a ticket window with a limited line.** People already in line are always served, in order. When the line is full you can wait for a spot, wait a short time then turn the newest arrival away, or turn them away immediately.

### The principles, and how LoT handles them

| Principle | In LoT connectors |
| - | - |
| **Buffer while the destination is slow** | Matching messages wait in a shared in-memory queue that one consumer drains in order. |
| **Bounded queues** | The shared queue holds `COREFLUX_ROUTE_CHANNEL_CAPACITY` messages (default `100000`). `OVERLOAD_CAPACITY` puts a private cap on one connector. |
| **Backpressure or drop** | `lossless` makes the publisher wait. `balanced` waits up to `OVERLOAD_TIMEOUT`, then drops. `realtime` drops at once. Only the **arriving** message is ever dropped. |
| **Ordering** | First in, first out. An accepted message is never evicted or reordered, so a sequence such as Sparkplug birth then data stays consistent. |
| **Delivery guarantee** | At most once into the connector. `lossless` means "never dropped by this queue", not "delivered to the destination". |
| **Survives a restart** | No. The queue lives in memory. Anything still queued when the broker stops is lost. |

### What it does not do

> [!WARNING]
>
> This is not a complete store-and-forward system. The connector queue:
>
> * **does not write to disk**, so queued messages don't survive a broker restart or crash,
> * **does not replay** messages after a destination comes back. Once a connector has taken a message from the queue, retrying a failed write is up to that connector type, and many simply log the failure,
> * **does not acknowledge end to end**: a publisher's QoS 1/2 acknowledgement means the broker accepted the message, not that the destination stored it.

### Filling the gaps

* **Upstream, use MQTT itself.** Publish with QoS 1 or 2 from clients with persistent sessions (`cleanSession=false`, or a session expiry in MQTT 5), so the broker keeps their messages while they are offline. The broker's [durability](/latest/mqtt-broker/durability) settings decide what survives a broker restart.
* **Store first, forward later.** Write each message to a database connector (or a model with `STORE IN`), then forward from that table on a schedule. The table is the durable buffer and can be replayed.
* **Let the destination buffer.** Kafka, and a remote MQTT broker with persistent sessions, keep their own durable queues once a message reaches them.
* **Watch for drops.** The broker logs when a connector starts dropping. Treat that as an alert.

### When to use it

* Leave the default (`balanced`) on most connectors.
* Use `lossless` when a path must not lose messages (audit, compliance) and you accept that the publisher may wait.
* Use `realtime` when high-rate telemetry must never stall the client that published it.
* Set `OVERLOAD_CAPACITY` to cap one noisy connector so it cannot crowd out others.

`ADD CONNECTOR_CONFIG` is the only LoT block that works on **every** connector type. Place it next to that type's own config (`SQL_CONFIG`, `SOURCE_CONFIG`, `MODBUS_CONFIG`, and so on). Order among `ADD` blocks does not matter.

***

Let's look at how to set it, starting with the three common contracts.

## Quick Start

**Never drop a message**

Use `lossless` on a forwarding path that must keep every message. The publisher waits until this connector has room — it never drops.

```lot wrap focus={3-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CloudBridge WITH TYPE MQTT_BRIDGE
    ADD CONNECTOR_CONFIG
        WITH OVERLOAD_POLICY "lossless"
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "broker.example.com"
        WITH BROKER_PORT '8883'
        WITH USE_TLS "true"
    ADD MAPPING auditForward
        WITH SOURCE_TOPIC "audit/#"
        WITH DESTINATION_TOPIC "cloud/audit/#"
        WITH DIRECTION "out"
```

**Never stall the publisher**

Use `realtime` on high-rate telemetry. If the connector is full, the arriving message is dropped immediately and the publishing client is not delayed.

```lot wrap focus={3-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDB WITH TYPE POSTGRESQL
    ADD CONNECTOR_CONFIG
        WITH OVERLOAD_POLICY "realtime"
    ADD SQL_CONFIG
        WITH SERVER GET ENV "PG_HOST"
        WITH DATABASE "factory"
        WITH USERNAME GET ENV "PG_USER"
        WITH PASSWORD GET SECRET "PG_PASSWORD"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO readings (ts, value) VALUES (NOW(), '{value.json}')"
```

**Cap a noisy connector**

Cap how many of **this connector's** messages may be in flight. Extra messages from this connector drop even while other connectors still have room.

```lot wrap focus={3-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR NoisySensors WITH TYPE MQTT_BRIDGE
    ADD CONNECTOR_CONFIG
        WITH OVERLOAD_CAPACITY 5000
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "telemetry.example.com"
        WITH BROKER_PORT '1883'
    ADD MAPPING sensorsOut
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "remote/sensors/#"
        WITH DIRECTION "out"
```

***

## Settings

All three settings are optional. An absent `ADD CONNECTOR_CONFIG` block inherits the broker default entirely.

```lot wrap focus={3-6} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CloudBridge WITH TYPE MQTT_BRIDGE
    ADD CONNECTOR_CONFIG
        WITH OVERLOAD_POLICY "balanced"
        WITH OVERLOAD_TIMEOUT 200
        WITH OVERLOAD_CAPACITY 20000
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "broker.example.com"
        WITH BROKER_PORT '8883'
        WITH USE_TLS "true"
    ADD MAPPING sensorSync
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "cloud/sensors/#"
        WITH DIRECTION "out"
```

| Setting | Required | Default | Description |
| - | - | - | - |
| `OVERLOAD_POLICY` | No | `balanced` | `lossless` waits until there is room and never drops. `balanced` waits up to `OVERLOAD_TIMEOUT`, then drops the **arriving** message. `realtime` never waits — it drops immediately when the connector is full. |
| `OVERLOAD_TIMEOUT` | No | `50` (ms) | Wait budget for `balanced` only. Ignored for `lossless` (waits indefinitely) and `realtime` (never waits). Must be zero or greater. |
| `OVERLOAD_CAPACITY` | No | unbounded | Maximum number of **this connector's** messages allowed in flight at once. Once reached, further messages from this connector drop even if other connectors still have room. Must be greater than zero. |

A message already accepted for a connector is never evicted. Only the arriving message can be dropped. That keeps sequences such as Sparkplug birth then data self-consistent under load.

> [!WARNING]
>
> Do not set `OVERLOAD_CAPACITY` together with `OVERLOAD_POLICY "lossless"`. A capacity cap drops overflow; `lossless` never drops. The broker logs an error naming the connector, **ignores the capacity**, and runs the connector as lossless. The same conflict applies if the connector inherits `lossless` from the broker default and then declares a capacity.

***

## Defaults

Each setting resolves on its own:

1. **No `ADD CONNECTOR_CONFIG` block** — the connector inherits the broker default for policy, timeout, and capacity.
2. **A block is present but a setting is omitted** — that setting does not copy the broker's timeout or capacity. `OVERLOAD_POLICY` inherits the broker default. `OVERLOAD_TIMEOUT` and `OVERLOAD_CAPACITY` use that policy's own default (`50` ms for `balanced`, unbounded capacity).
3. **An invalid value** (unknown policy name, negative timeout, non-positive capacity) does not stop the connector loading. The broker logs an error and uses that field's default.

Broker-wide defaults are environment variables, read once at process start. Change them and **restart** the broker. A connector's own `ADD CONNECTOR_CONFIG` always overrides these for that connector.

| Variable | Default | Effect |
| - | - | - |
| `COREFLUX_ROUTE_OVERLOAD_POLICY` | `balanced` | Default for `OVERLOAD_POLICY` (`lossless`, `balanced`, or `realtime`). An unrecognized value logs an error and falls back to `balanced`. |
| `COREFLUX_ROUTE_CHANNEL_FULL_TIMEOUT_MS` | `50` | Default wait budget in milliseconds for `balanced`. Ignored when the resolved policy is `lossless` or `realtime`. A negative value logs an error and falls back to `50`. |
| `COREFLUX_ROUTE_CHANNEL_CAPACITY` | `100000` | Shared ceiling on how many connector updates the broker will hold at once. Below the ceiling, matching messages are accepted. At the ceiling, the arriving message's wait-or-drop policy applies. Values below `1024` are raised to `1024`. Unset, non-numeric, zero, or negative values fall back to `100000`. |

`OVERLOAD_CAPACITY` on a connector is a **private** budget for that connector. The shared ceiling is separate: one connector can hit its own cap and start dropping while other connectors still have room.

See [Broker Configuration](/latest/mqtt-broker/configuration#performance-and-back-pressure) for how these sit alongside other broker limits.

***

## What happens under load

When a connector is waiting, that wait can delay **the publishing client's own publish** — only that client, and only up to the wait budget. Other connected clients are not stalled by this connector.

The broker logs two different saturation conditions (each at most once every five seconds):

* The shared connector queue is full — every connector waiting behind it is affected.
* A single connector is over the `OVERLOAD_CAPACITY` it declared for itself — the shared queue may still have room.

> [!WARNING]
>
> If two connectors could match the same topic (for example one exact mapping and another `sensors/#`), the broker applies the **stricter** wait-or-drop choice among those candidates. A `lossless` connector on an overlapping pattern can make a `realtime` connector wait, even if only the `realtime` connector would have handled the message. The broker never drops a message because a more lenient connector asked to drop it. If mixed policies on overlapping wildcards wait or drop more than you expect, check the patterns first — that behavior is by design.

***

## Troubleshooting

> **A connector drops messages even though the broker looks idle**
>
> That connector's own `OVERLOAD_CAPACITY` is exhausted. Look for the broker warning that a connector is over its in-flight budget, not the warning that the shared queue is full.

> **Publishers on a lossless connector stall under load**
>
> Working as designed — `lossless` waits until there is room. Switch to `balanced` with a timeout if you would rather drop than stall, or cap a noisy connector with `OVERLOAD_CAPACITY` so it drops its own overflow instead.

> **OVERLOAD\_CAPACITY seems to have no effect**
>
> It is declared alongside `OVERLOAD_POLICY "lossless"` (or the broker default is `lossless`). Check the broker log for the lossless/capacity conflict — capacity is ignored, not applied.

> **A connector with no wildcard still waits longer than its own policy**
>
> Another connector's overlapping wildcard pattern resolved a stricter policy for that topic. See the overlapping-pattern warning above.

> **The connector drops immediately and never waits**
>
> The resolved policy is `realtime`. That is expected — `realtime` drops without waiting.

***

## Best practices

* Start with the default `balanced` policy. Change a connector only when you have a reason (must not lose, must not stall, or must not crowd others).
* Use `lossless` sparingly. It protects delivery at the cost of delaying the publisher that caused the backlog.
* Put `OVERLOAD_CAPACITY` on the noisy connector, not on the critical one — the critical connector can stay unbounded while the noisy connector drops its own overflow.
* Prefer exact topic mappings when two connectors would otherwise share a broad `+` / `#` pattern with different policies.
* Invalid settings never fail the connector silently: read the broker log after deploy if behavior does not match the block you wrote.

***

## Next Steps

> **[Connectors Overview](./overview)**
>
> Define connectors, mappings, and status topics.

> **[Broker Configuration](/latest/mqtt-broker/configuration#performance-and-back-pressure)**
>
> Set broker-wide queue defaults and other limits.


# gRPC Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/streaming/grpc

Call an external gRPC service from the Coreflux broker with TYPE GRPC — unary, streaming, and per-device bidirectional sessions

## Call a gRPC Service from MQTT

A gRPC connector opens a channel from the broker to an external gRPC service and maps MQTT topics onto that service's calls. Publish bytes on a source topic and the connector sends them; replies are published back onto a destination topic.

> [!WARNING]
>
> This page is the **gRPC client connector** (`DEFINE CONNECTOR … WITH TYPE GRPC`). The broker connects *out* to a gRPC service. You do not call it from an Action — there is no `CALL GRPC`.
>
> To let an AI client operate **this** broker, use the [MCP Server](/latest/mqtt-broker/mcp-server). The hosted [documentation MCP](/ai/mcp) searches docs.coreflux.org and does not open a gRPC channel.

> [!TIP]
>
> **Like a phone line to another building.** The connector keeps one line open to the service (the channel). Each conversation on that line is a call: MQTT bytes go in, and the reply bytes come back on another topic.

> [!NOTE]
>
> gRPC connectors are **beta**. Coreflux HUB lists the gRPC template with the other streaming connectors when the broker exposes it. The fields on that template are the same `GRPC_CONFIG` parameters as the LoT on this page.

### When to use it

* A service you already run speaks gRPC, and MQTT messages should invoke it without a separate gateway.
* Each device needs its own long-lived stream. With the default session scope, one IMEI (or any other id in the source topic) gets its own bidirectional call.
* The exchange is one request and one reply, a server stream, a client stream, or a bidirectional stream.

Use a [REST API connector](../rest-api-routes) for HTTP. Use the [Kafka connector](./kafka) for an event log. Encode and decode protobuf with [LoT models](/latest/lot-language/models/protobuf) — this connector forwards raw bytes and does not read a `.proto` file.

***

Define the channel once, then map the MQTT topics that feed it.

## Quick Start

**Unary call**

One MQTT message opens one call and publishes the single reply:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EchoGrpc WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS "grpc.example.com"
        WITH PORT '50051'
        WITH USE_TLS "false"
        WITH SERVICE "echo.Echo"
        WITH METHOD "Unary"
        WITH RPC_TYPE "UNARY"
    ADD EVENT CallEcho
        WITH SOURCE_TOPIC "grpc/echo/in"
        WITH DESTINATION_TOPIC "grpc/echo/out"
```

A payload on `grpc/echo/in` is the request. The response bytes are published to `grpc/echo/out`.

**Server stream**

One request, then every message the server sends until it finishes:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TickStream WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '50051'
        WITH USE_TLS "false"
        WITH SERVICE "echo.Echo"
        WITH METHOD "ServerStream"
        WITH RPC_TYPE "SERVER_STREAM"
    ADD EVENT Tick
        WITH SOURCE_TOPIC "grpc/ticks/request"
        WITH DESTINATION_TOPIC "grpc/ticks/data"
```

Each server message is published to `grpc/ticks/data` as it arrives.

**One call per device**

A bidirectional call per device topic. The id in the topic — an IMEI, a serial number, a session id — is the call key:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DeviceBidi WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '443'
        WITH USE_TLS "true"
        WITH SERVICE "echo.Echo"
        WITH METHOD "Bidi"
        WITH RPC_TYPE "BIDI"
        WITH SESSION_SCOPE "TOPIC"
        WITH DEADLINE '300'
        WITH IDLE_TIMEOUT '15'
    ADD EVENT Converse
        WITH SOURCE_TOPIC "devices/+/uplink"
        WITH DESTINATION_TOPIC "devices/{topic.2}/downlink"
```

`devices/490154203237518/uplink` keeps its own call. A second IMEI does not wait on that call or close it. Replies for the first device are published to `devices/490154203237518/downlink`. `{topic.N}` is 1-based, so the device id is segment 2.

> [!NOTE]
>
> `USE_TLS "false"` is for a service that speaks plaintext HTTP/2. The default is TLS on port `443`. Use `127.0.0.1` only when that service listens on the broker host. Set `ADDRESS` with [`GET ENV`](/latest/mqtt-broker/secrets-and-env) and credentials with `GET SECRET`.

***

## How a Call Is Chosen

One connector is one channel and one RPC method (`SERVICE` + `METHOD`). HTTP/2 carries many calls on that channel. Add another connector when you need a second method.

| LoT | What it sets |
| - | - |
| `ADDRESS`, `PORT`, `USE_TLS` | Channel to the service |
| `SERVICE`, `METHOD` | Which RPC to call |
| `RPC_TYPE` | Unary, server stream, client stream, or bidirectional |
| `SOURCE_TOPIC` | MQTT topic that supplies request bytes |
| `DESTINATION_TOPIC` | MQTT topic that receives response bytes |
| `SESSION_SCOPE` | Whether streaming calls are per topic or shared by the event |
| `CLIENT_AUTH`, `METADATA` | Initial metadata on the call, including `authorization` |

There is no session-key setting. Put application ids inside the payload. The connector correlates calls with the MQTT topic match.

`ADD CONNECTOR_CONFIG` still controls wait-or-drop when this connector falls behind incoming MQTT (`ADD ROUTE_CONFIG` remains a supported alias). See [Store and Forward Configuration](../store-and-forward).

***

## GRPC\_CONFIG

| Parameter | Required | Default | Description |
| - | - | - | - |
| `ADDRESS` | Yes | — | Host name or IP of the gRPC service. A `dns:///`, `https://`, or `http://` prefix is removed. A `:port` suffix overrides `PORT` (do not append `:port` to a bracketed IPv6 address — set `PORT` instead). |
| `PORT` | No | `443` | Channel port, unless `ADDRESS` already includes a port. |
| `USE_TLS` | No | `true` | `true` uses TLS. `false` uses plaintext HTTP/2. The scheme in `ADDRESS` does not override this. |
| `SERVICE` | Yes | — | Fully qualified service name (`package.Service`). |
| `METHOD` | Yes | — | RPC method name. |
| `RPC_TYPE` | No | `UNARY` | `UNARY`, `SERVER_STREAM`, `CLIENT_STREAM`, or `BIDI`. |
| `DEADLINE` | No | `30` | Call deadline in seconds, counted from when the call opens. Values below `1` are treated as 1 second. The deadline is not extended by later messages on the same call. |
| `IDLE_TIMEOUT` | No | `5` | Seconds of silence before the connector half-closes a client stream or bidirectional call. `0` disables that idle close. |
| `SESSION_SCOPE` | No | `TOPIC` | `TOPIC`: one streaming call per source topic. `EVENT`: one bidirectional call shared by every match of that event. |
| `METADATA` | No | — | Extra initial metadata. A JSON object, or `key=value,key2=value2`. Keys must not start with `grpc-`. |
| `CLIENT_AUTH` | No | `NONE` | Outbound authentication. See [Authentication](#authentication). |

The parser also accepts `SERVERSTREAM`, `CLIENTSTREAM`, `BIDIRECTIONAL`, and `DUPLEX` for `RPC_TYPE`, and `SOURCE`, `SOURCE_TOPIC`, `SHARED`, and `ROUTE` for `SESSION_SCOPE`. Use the spellings in the table.

### Event parameters

| Parameter | Required | Description |
| - | - | - |
| `SOURCE_TOPIC` | Yes | MQTT topic (wildcards allowed) whose payload is the request bytes. |
| `DESTINATION_TOPIC` | Yes | MQTT topic for response bytes. `{topic.N}` expands from the source topic that triggered the call (1-based). |

Several `ADD EVENT` blocks share the same channel and the same method. Each event keeps its own calls.

Response publishes use QoS 0 and are not retained.

***

## RPC Types

| `RPC_TYPE` | MQTT to the service | Service to MQTT | How the client side ends |
| - | - | - | - |
| `UNARY` | One message, one call | One response | The call completes |
| `SERVER_STREAM` | One message, one call | Each response is published until the server finishes | The server finishes the call |
| `CLIENT_STREAM` | Many messages on the same call | One response after the client half-closes | Empty payload, or `IDLE_TIMEOUT` |
| `BIDI` | Many messages on the same call, while replies arrive | Each response is published as it arrives | Empty payload, or `IDLE_TIMEOUT` |

An empty MQTT payload is a real empty request for `UNARY` and `SERVER_STREAM`. For `CLIENT_STREAM` and `BIDI` it is the half-close (no more client messages). The connector then waits up to 30 seconds for the remaining server bytes so the last response can still be published.

`PAYLOAD AS BYTES` in an Action does not publish an empty payload. Send the zero-length message from an MQTT client (MQTT Explorer or any MQTT client) on that source topic.

Raise `DEADLINE` above the longest call you expect. The default of 30 seconds ends a bidirectional session that runs longer than that, even when messages are still flowing. Raise `IDLE_TIMEOUT` when silence between messages is normal, or set it to `0` so only an empty payload half-closes the call.

### Client stream

Publish request bytes to `grpc/upload/in`. Publish an empty payload, or wait for `IDLE_TIMEOUT`, to half-close. The single response is published to `grpc/upload/out`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR UploadGrpc WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '50051'
        WITH USE_TLS "false"
        WITH SERVICE "echo.Echo"
        WITH METHOD "ClientStream"
        WITH RPC_TYPE "CLIENT_STREAM"
        WITH IDLE_TIMEOUT '10'
    ADD EVENT Upload
        WITH SOURCE_TOPIC "grpc/upload/in"
        WITH DESTINATION_TOPIC "grpc/upload/out"
```

### One shared call (`SESSION_SCOPE EVENT`)

`SESSION_SCOPE "EVENT"` keeps a single bidirectional call for every topic that matches the event. A new IMEI does not open its own call. Replies are published with `{topic.N}` taken from the **latest** source topic, not from the topic that opened the call.

```lot wrap focus={11} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SharedBidi WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '443'
        WITH USE_TLS "true"
        WITH SERVICE "echo.Echo"
        WITH METHOD "Bidi"
        WITH RPC_TYPE "BIDI"
        WITH DEADLINE '300'
        WITH IDLE_TIMEOUT '30'
        WITH SESSION_SCOPE "EVENT"
    ADD EVENT Converse
        WITH SOURCE_TOPIC "devices/+/uplink"
        WITH DESTINATION_TOPIC "devices/{topic.2}/downlink"
```

Leave the default `TOPIC` when each device must stay isolated. Use `EVENT` only when the service expects one shared stream.

> [!WARNING]
>
> After a bidirectional call has already ended, further payloads on that session are dropped until you publish an empty payload. The next non-empty payload then opens a fresh call. A service that ends the turn inside the protobuf, without an empty MQTT message, leaves that topic dropped until the empty payload arrives. The connector logs a warning with the topic and the number of bytes it dropped. That end-of-stream condition (`InvalidArgument` or `Aborted`) does not by itself mark the connector unhealthy.

***

## Authentication

`CLIENT_AUTH` attaches credentials as initial metadata on each call. Access tokens are not published on MQTT topics. If the service returns unauthenticated, the connector invalidates the cached token, drops the streaming call, and retries that payload once so the new token is on the new call.

| `CLIENT_AUTH` | What you set | How it is sent |
| - | - | - |
| `NONE` | — | No credential metadata. Default. |
| `API_KEY` | `API_KEY`. Optional `AUTH_HEADER` (default `X-API-Key`). | That metadata key |
| `BEARER` | `BEARER_TOKEN` | `authorization: Bearer …` |
| `OAUTH2_CLIENT_CREDENTIALS` | `CLIENT_ID`, `CLIENT_SECRET`, and `TOKEN_URL` or `ISSUER`. Optional `SCOPE`, `TOKEN_AUTH`. | `authorization: Bearer …` with a cached access token |
| `OAUTH2_REFRESH_TOKEN` | `REFRESH_TOKEN`, plus the same token endpoint fields | `authorization: Bearer …` |
| `OAUTH2_JWT_BEARER` | `SERVICE_ACCOUNT` (service-account JSON with `client_email` and `private_key`). Optional `TOKEN_URL` and `SCOPE`. | `authorization: Bearer …` |
| `GOOGLE_METADATA` | Optional `METADATA_URL` and `SCOPE` | `authorization: Bearer …` from the instance metadata server |

`TOKEN_AUTH` chooses how the client authenticates to the token endpoint: `CLIENT_SECRET_BASIC` (default), `CLIENT_SECRET_POST`, or `PRIVATE_KEY_JWT` (`CLIENT_ID` plus `CLIENT_ASSERTION_KEY` as PEM or JWK). `ISSUER` is the OIDC issuer; the connector discovers the token endpoint when `TOKEN_URL` is omitted. `BEARER_TOKEN` and `API_KEY` also accept the setting name `AUTH_SECRET`.

For `OAUTH2_JWT_BEARER`, set `TOKEN_URL` when the service-account JSON has no `token_uri`. For `GOOGLE_METADATA`, the default metadata address is `http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token`. Set `METADATA_URL` to point elsewhere. When `SCOPE` is set and that URL has no query string, the connector adds the scope as a `scopes` query parameter.

**API key**

Send a static key in initial metadata:

```lot wrap focus={9-11} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ApiKeyGrpc WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '443'
        WITH USE_TLS "true"
        WITH SERVICE "echo.Echo"
        WITH METHOD "Unary"
        WITH RPC_TYPE "UNARY"
        WITH CLIENT_AUTH "API_KEY"
        WITH API_KEY GET SECRET "GRPC_API_KEY"
        WITH AUTH_HEADER "X-API-Key"
    ADD EVENT CallEcho
        WITH SOURCE_TOPIC "grpc/echo/in"
        WITH DESTINATION_TOPIC "grpc/echo/out"
```

**OAuth client**

Fetch an access token with client credentials. Store the secret with [`-setSecret`](/latest/mqtt-broker/secrets-and-env), not in the connector text:

```lot wrap focus={10-14} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OAuthGrpc WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '443'
        WITH USE_TLS "true"
        WITH SERVICE "acme.Device"
        WITH METHOD "Bidi"
        WITH RPC_TYPE "BIDI"
        WITH DEADLINE '300'
        WITH CLIENT_AUTH "OAUTH2_CLIENT_CREDENTIALS"
        WITH TOKEN_URL GET ENV "GRPC_TOKEN_URL"
        WITH CLIENT_ID GET ENV "GRPC_CLIENT_ID"
        WITH CLIENT_SECRET GET SECRET "GRPC_CLIENT_SECRET"
        WITH SCOPE "devices.stream"
    ADD EVENT Stream
        WITH SOURCE_TOPIC "devices/+/uplink"
        WITH DESTINATION_TOPIC "devices/{topic.2}/downlink"
```

**Service account**

Sign in with a service-account JSON key:

```lot wrap focus={10-13} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR JwtGrpc WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '443'
        WITH USE_TLS "true"
        WITH SERVICE "acme.Device"
        WITH METHOD "Bidi"
        WITH RPC_TYPE "BIDI"
        WITH DEADLINE '300'
        WITH CLIENT_AUTH "OAUTH2_JWT_BEARER"
        WITH TOKEN_URL GET ENV "GRPC_TOKEN_URL"
        WITH SERVICE_ACCOUNT GET SECRET "GRPC_SERVICE_ACCOUNT"
        WITH SCOPE "devices.stream"
    ADD EVENT Stream
        WITH SOURCE_TOPIC "devices/+/uplink"
        WITH DESTINATION_TOPIC "devices/{topic.2}/downlink"
```

Extra metadata is merged with the auth entry. Prefer a JSON object when a value contains a comma:

```lot wrap focus={9-11} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MetaGrpc WITH TYPE GRPC
    ADD GRPC_CONFIG
        WITH ADDRESS GET ENV "GRPC_HOST"
        WITH PORT '443'
        WITH USE_TLS "true"
        WITH SERVICE "echo.Echo"
        WITH METHOD "Unary"
        WITH RPC_TYPE "UNARY"
        WITH CLIENT_AUTH "BEARER"
        WITH BEARER_TOKEN GET SECRET "GRPC_BEARER"
        WITH METADATA "{\"x-tenant\":\"plant-a\"}"
    ADD EVENT CallEcho
        WITH SOURCE_TOPIC "grpc/echo/in"
        WITH DESTINATION_TOPIC "grpc/echo/out"
```

The connector fetches the access token when it starts. A token or channel failure leaves the connector disconnected. Startup waits up to 10 seconds for the channel. If the route has not started, the broker retries in the background, from 2 seconds up to 60 seconds, until the route starts or you remove it. Removing the connector drops the cached token.

There is no setting for a client certificate or a private CA file. TLS uses the trust store on the broker host.

***

## Payloads

The connector sends and publishes the MQTT payload as raw bytes. It does not encode JSON and it does not compile protobuf. A binary publish stays binary. If the topic cache has no raw bytes, the connector sends the payload text as UTF-8, which corrupts protobuf and audio.

Publish protobuf with `PUBLISH MODEL`, or forward an existing blob with `PAYLOAD AS BYTES`. Decode replies with `GET PROTO` on the destination topic.

The model describes the request. The Action writes binary protobuf to the topic the connector is listening on:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL EchoRequest WITH FORMAT PROTOBUF COLLAPSED
    ADD STRING "text" PROTO_TAG 1
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SendEcho
ON TOPIC "commands/echo" DO
    PUBLISH MODEL EchoRequest TO "grpc/echo/in" WITH
        text = (GET JSON "text" IN PAYLOAD AS STRING)
```

`EchoGrpc` from the Quick Start then forwards those bytes and publishes the service's reply on `grpc/echo/out`. Read fields from that reply with `GET PROTO` and a response model. See [Protobuf models](/latest/lot-language/models/protobuf).

***

## Check the Round Trip

**1. Deploy the connector**

Deploy the LoT, then confirm the connector reaches the service. Health is retained on `$SYS/Coreflux/Routes/EchoGrpc/status`. See [Connector status](../overview#connector-status-monitoring).

**2. Subscribe to the reply**

In MQTT Explorer, subscribe to the destination topic (`grpc/echo/out`, or `devices/+/downlink` for the per-device example).

**3. Publish a request**

Publish a payload to the source topic. For a unary echo, the reply is one message. For a bidirectional device topic, further publishes on that same topic reuse the call until an empty payload or the idle timeout.

**4. Half-close a stream**

For `CLIENT_STREAM` or `BIDI`, publish a zero-length payload on that source topic. The last server bytes are published, and the next non-empty payload opens a new call.

***

## Best Practices

* Keep `SESSION_SCOPE "TOPIC"` (the default) so each device topic, such as one IMEI, has its own call.
* Set `DEADLINE` to the full length of a streaming call, not the gap between messages.
* Store keys with `GET SECRET`. Do not publish tokens on MQTT topics.
* Put correlation ids in the payload. The connector will not add a session id for you.
* Tell operators that an empty payload half-closes `CLIENT_STREAM` and `BIDI`.
* Do not send metadata keys that start with `grpc-`.

***

## Limitations

> [!WARNING]
>
> * **Raw bytes only.** The connector does not load a `.proto` or a protobuf codec. Encode before publish and decode after the reply.
> * **One method per connector.** `SERVICE`, `METHOD`, and `RPC_TYPE` are connector-wide.
> * **Deadline is fixed when the call opens.** A 30-second deadline stops a longer bidirectional call.
> * **Finished bidirectional calls drop new bytes** until an empty payload half-closes that session.
> * **`SESSION_SCOPE "EVENT"` shares one call.** Replies follow the latest source topic.
> * **No client certificate or private CA field.** TLS uses the broker host trust store.
> * **Replies are QoS 0 and not retained.**
> * **Empty binary publishes from LoT do not half-close.** `PAYLOAD AS BYTES` does not publish an empty payload. Publish the zero-length message from an MQTT client.

### Troubleshooting

> **The connector will not start**
>
> * `GRPC_CONFIG` needs `ADDRESS`, `SERVICE`, and `METHOD`. Each event needs `SOURCE_TOPIC` and `DESTINATION_TOPIC`.
> * The channel must connect within 10 seconds. Use a host and port the broker host can reach, and match `USE_TLS` to the service (plaintext often uses port `50051`; TLS often uses `443`).
> * If the route fails to start, the broker retries in the background, from 2 seconds up to 60 seconds, until the route starts or you remove it.
> * OAuth modes fetch a token at startup. Check `TOKEN_URL` or `ISSUER`, and the secret names.

> **Unauthenticated replies**
>
> The connector retries once after refreshing the token and opening a new streaming call. If that retry fails, check `CLIENT_AUTH`, the token endpoint, and that the secret resolves. Tokens are not written to MQTT topics.

> **Binary payloads look corrupted**
>
> Publish raw bytes (`PUBLISH MODEL` or `PAYLOAD AS BYTES`). A text payload is sent as UTF-8.

> **Metadata is rejected**
>
> Remove any key that starts with `grpc-`. Use a JSON object for `METADATA` when a value contains a comma.

> **The stream never finishes**
>
> Nothing published an empty payload, and `IDLE_TIMEOUT` is high or `0`. Publish a zero-length payload on the source topic, or lower `IDLE_TIMEOUT`.

> **MQTT publishes continue but replies stop**
>
> The previous bidirectional call already ended. Payloads on that topic are dropped until an empty payload. Publish the empty payload, then send the next request. Check connector logs for the dropped-byte warning.

> **Replies land on the wrong device topic**
>
> `SESSION_SCOPE "EVENT"` expands `{topic.N}` from the latest source topic. Use `TOPIC` when each IMEI needs its own call and its own reply topic.

***

## Next Steps

> **[Protobuf Models](/latest/lot-language/models/protobuf)**
>
> Encode request bytes with `PUBLISH MODEL` and read replies with `GET PROTO`.

> **[Kafka Connector](./kafka)**
>
> Stream MQTT to an event log when the other side is Kafka, not a gRPC method.


# Kafka Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/streaming/kafka

Stream data both ways between your Coreflux broker and Apache Kafka clusters, including Confluent Cloud, AWS MSK, Aiven, and self-managed brokers

## Kafka Overview

The `KAFKA` connector connects your Coreflux broker to an Apache Kafka cluster and moves messages in both directions. A single connector can **produce** (MQTT → Kafka) and **consume** (Kafka → MQTT) at the same time, so device telemetry can flow into your data pipeline while commands and setpoints flow back to the field.

> [!TIP]
>
> **Like a conveyor belt between two warehouses.** Your MQTT broker handles fast-moving device traffic; Kafka is the long-term, replayable record. The Kafka connector is the belt that carries boxes (messages) between them in whichever direction you point it.

### When to use it

* Feed real-time MQTT telemetry into a Kafka-based analytics or data pipeline.
* Bring Kafka events (commands, setpoints, alarms) back into the broker for field devices.
* Bridge edge MQTT traffic to a managed cloud platform like Confluent Cloud or AWS MSK.

A gRPC service uses the [gRPC connector](./grpc) (`TYPE GRPC`).

### Key capabilities

| Capability | What it means for you |
| - | - |
| **Bidirectional** | Produce and consume in one connector — no separate definitions needed |
| **Secure** | Supports `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, and `SASL_SSL` |
| **Reliable delivery** | On consume, the offset is committed only after the broker has dispatched the message (at-least-once) |
| **Message keys** | Connector records to partitions by topic segment or JSON field for ordered, per-device streams |
| **Tunable throughput** | Configurable batching, compression, and acknowledgement levels |
| **Cloud & self-hosted** | Confluent Cloud, AWS MSK, Aiven, Redpanda, and self-managed clusters |

***

Let's look at how a Kafka connector is defined, starting with the three common directions.

## Quick Start

**Produce (MQTT → Kafka)**

Send every sensor reading from the broker into a Kafka topic, keyed by device:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorProducer WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-sensors"
        WITH SECURITY_PROTOCOL "PLAINTEXT"
    ADD EVENT SensorsToKafka
        WITH SOURCE_TOPIC "factory/sensors/+"
        WITH DESTINATION_TOPIC "factory.sensors.raw"
        WITH DIRECTION "out"
        WITH QUERY "{topic.3}"
```

A message on `factory/sensors/pump-01` becomes a Kafka record on `factory.sensors.raw` with key `pump-01`.

**Consume (Kafka → MQTT)**

Forward Kafka commands into the MQTT broker:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CommandConsumer WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-commands"
        WITH SECURITY_PROTOCOL "PLAINTEXT"
        WITH AUTO_OFFSET_RESET "Latest"
    ADD EVENT CommandsFromKafka
        WITH SOURCE_TOPIC "factory.commands"
        WITH DESTINATION_TOPIC "factory/commands/in"
        WITH DIRECTION "in"
```

A Kafka record on `factory.commands` is published to the MQTT topic `factory/commands/in`.

**Bidirectional**

One connector handling both directions — telemetry out, commands in:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-plant"
        WITH SECURITY_PROTOCOL "PLAINTEXT"
        WITH AUTO_OFFSET_RESET "Earliest"
    ADD EVENT SensorsToKafka
        WITH SOURCE_TOPIC "plant/sensors/+"
        WITH DESTINATION_TOPIC "plant.sensors.raw"
        WITH DIRECTION "out"
    ADD EVENT CommandsFromKafka
        WITH SOURCE_TOPIC "plant.commands"
        WITH DESTINATION_TOPIC "plant/commands/in"
        WITH DIRECTION "in"
```

> [!WARNING]
>
> The Quick Start examples use `PLAINTEXT` for clarity. For any cluster reachable over a network — especially cloud services — use `SASL_SSL` and load credentials from environment variables and secrets. See [Security & Authentication](#security--authentication).

***

## How Kafka Compares to MQTT

Kafka and MQTT solve different problems. Coreflux bridges the two so each does what it's best at: MQTT for fast device traffic, Kafka for durable, replayable streams.

| Feature | Kafka | MQTT |
| - | - | - |
| **Delivery model** | Pull (consumer fetches) | Push (broker delivers) |
| **Retention** | Configurable (hours to forever) | Typically none |
| **Ordering** | Per-partition | Per-topic |
| **Fan-out / load balancing** | Built-in consumer groups | Shared subscriptions |
| **Throughput** | Millions of messages/sec | Thousands of messages/sec |
| **Typical use** | Data pipelines, analytics, replay | IoT telemetry, device control |

A few Kafka terms appear throughout this page:

| Term | Description |
| - | - |
| **Bootstrap servers** | The initial broker addresses the connector contacts to discover the rest of the cluster |
| **Topic** | A named, partitioned log of records |
| **Partition** | An ordered sub-stream within a topic — the unit of ordering and parallelism |
| **Consumer group** | A set of consumers that divide a topic's partitions between them |
| **Offset** | A record's position within a partition. An `"in"` event commits it only after the broker has dispatched the message |

***

## Supported Kafka Services

The Kafka connector works with any Kafka-compatible cluster, cloud-managed or self-hosted.

**Cloud-managed**

| Service | Security Protocol | Notes |
| - | - | - |
| **Confluent Cloud** | `SASL_SSL` | `PLAIN` or `SCRAM` mechanism |
| **Amazon MSK** | `SASL_SSL` | IAM or SCRAM auth |
| **Aiven for Kafka** | `SASL_SSL` | SCRAM-SHA-512 typical |
| **Azure Event Hubs (Kafka API)** | `SASL_SSL` | `PLAIN` with connection string as password |
| **Redpanda Cloud** | `SASL_SSL` | Kafka-compatible |

**Self-managed**

| Cluster | Notes |
| - | - |
| **Apache Kafka** (2.0+) | All security protocols supported |
| **Confluent Platform** | Same configuration as Apache Kafka |
| **Redpanda** | Drop-in Kafka-compatible cluster |
| **KRaft mode** | Kafka without ZooKeeper — fully supported |

***

## Connection Configuration

Every Kafka connector starts with a `KAFKA_CONFIG` block describing the cluster, security, and throughput settings. Only `BROKER_ADDRESS` is required, but production connectors should always set a `GROUP_ID` and use a secure protocol.

```lot wrap focus={3-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-plant"
    ADD EVENT SensorsToKafka
        WITH SOURCE_TOPIC "plant/sensors/+"
        WITH DESTINATION_TOPIC "plant.sensors.raw"
        WITH DIRECTION "out"
```

### Connection & Security

> **Cluster Connection**
>
> **BROKER\_ADDRESS** `string` *required*
>
> Bootstrap servers, e.g. `localhost:9092` or `host1:9092,host2:9092`. List two or three brokers in production so the connector survives an individual broker restart.
>
> **GROUP\_ID** `string`
>
> Consumer group name. **Always set this in production.** If omitted, a random group is generated on every startup, causing the consumer to replay all retained messages from scratch after each restart.
>
> **AUTO\_OFFSET\_RESET** `string` (default: Earliest)
>
> Where to start reading when no committed offset exists: `Earliest` (from the beginning) or `Latest` (new messages only).
>
> **ENABLE\_AUTO\_COMMIT** `boolean` (default: false)
>
> Leave `false` so an `"in"` event commits the offset only after the broker has dispatched the message (at-least-once). Set `true` to also enable periodic background commits.

> **Security**
>
> **SECURITY\_PROTOCOL** `string` (default: PLAINTEXT)
>
> `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, or `SASL_SSL`.
>
> **SASL\_MECHANISM** `string`
>
> Required with SASL: `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`.
>
> **SASL\_USERNAME** `string`
>
> SASL username. Supports `GET ENV`.
>
> **SASL\_PASSWORD** `string`
>
> SASL password. Use `GET SECRET` to keep it out of your LoT definition.
>
> **SSL\_CA\_LOCATION** `string`
>
> Path to the CA certificate (for `SSL` or `SASL_SSL`).
>
> **SSL\_CERTIFICATE\_LOCATION** `string`
>
> Path to the client certificate (mutual TLS).
>
> **SSL\_KEY\_LOCATION** `string`
>
> Path to the client key (required with a client certificate).
>
> **SSL\_KEYSTORE\_PASSWORD** `string`
>
> Key or keystore password.

> **Throughput & Tuning**
>
> **ACKS** `string` (default: all)
>
> Producer durability: `0` (no acknowledgement), `1` (leader only), or `all` (all in-sync replicas).
>
> **LINGER\_MS** `integer` (default: 5)
>
> How long the producer waits to fill a batch before sending. Higher values mean fewer, larger requests (better throughput) at the cost of a little added latency.
>
> **BATCH\_SIZE** `integer`
>
> Maximum producer batch size in bytes. Default is 1 MB.
>
> **COMPRESSION\_TYPE** `string` (default: none)
>
> Producer compression: `none`, `gzip`, `snappy`, `lz4`, or `zstd`. Most effective on larger batches — pair with `LINGER_MS`.
>
> **FETCH\_MAX\_BYTES** `integer`
>
> Maximum bytes returned per consumer fetch. Default is 50 MB.
>
> **QUEUED\_MAX\_MESSAGES\_KB** `integer` (default: 65536)
>
> Maximum KB pre-fetched per partition into the consumer buffer (64 MB by default). Lower it to cap memory use on high-volume topics.
>
> **FLUSH\_TIMEOUT\_MS** `integer` (default: 5000)
>
> How long the connector waits for in-flight produced messages to drain when stopping.

***

## Security & Authentication

Choose the security protocol that matches your broker's listener. For anything beyond a local development cluster, use `SASL_SSL`.

| `SECURITY_PROTOCOL` | TLS | SASL | Typical use |
| - | - | - | - |
| `PLAINTEXT` | No | No | Local development |
| `SSL` | Yes | No | TLS-only clusters |
| `SASL_PLAINTEXT` | No | Yes | Internal test environments |
| `SASL_SSL` | Yes | Yes | Confluent Cloud, MSK, Aiven, production |

**PLAINTEXT (development)**

No encryption or authentication — local clusters only:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS "localhost:9092"
        WITH GROUP_ID "coreflux-dev"
        WITH SECURITY_PROTOCOL "PLAINTEXT"
    ADD EVENT SensorsToKafka
        WITH SOURCE_TOPIC "dev/sensors/+"
        WITH DESTINATION_TOPIC "dev.sensors"
        WITH DIRECTION "out"
```

**SSL (TLS only)**

Encrypted transport without SASL credentials:

```lot wrap focus={5-6} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TlsKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS "kafka.example.com:9093"
        WITH GROUP_ID "coreflux-tls"
        WITH SECURITY_PROTOCOL "SSL"
        WITH SSL_CA_LOCATION "/etc/ssl/certs/kafka-ca.pem"
    ADD EVENT SensorsToKafka
        WITH SOURCE_TOPIC "plant/sensors/+"
        WITH DESTINATION_TOPIC "plant.sensors"
        WITH DIRECTION "out"
```

**SASL\_SSL (production)**

Encrypted transport with SCRAM authentication — the recommended production setup:

```lot wrap focus={5-10} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecureKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-prod"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "SCRAM-SHA-512"
        WITH SASL_USERNAME GET ENV "KAFKA_USER"
        WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
        WITH SSL_CA_LOCATION "/etc/ssl/certs/ca.pem"
    ADD EVENT SensorsToKafka
        WITH SOURCE_TOPIC "plant/sensors/+"
        WITH DESTINATION_TOPIC "plant.sensors"
        WITH DIRECTION "out"
```

> [!NOTE]
>
> Store credentials with `GET SECRET` and non-sensitive values like hostnames with `GET ENV`. See [Environment Variables and Secrets](/latest/mqtt-broker/secrets-and-env) for setup across Windows, Linux, Docker, and Kubernetes.

***

## Events and Direction

Each `ADD EVENT` block maps one MQTT topic to one Kafka topic and sets the direction of flow. Think of the **broker** as the source side and **Kafka** as the destination side.

| `DIRECTION` | `SOURCE_TOPIC` | `DESTINATION_TOPIC` | Data flow |
| - | - | - | - |
| `"out"` | Broker MQTT topic (wildcards OK) | Kafka topic to produce to | MQTT → Kafka |
| `"in"` | Kafka topic to subscribe to | Broker MQTT topic to publish to | Kafka → MQTT |

### Event Parameters

> **Required**
>
> **SOURCE\_TOPIC** `string` *required*
>
> Broker MQTT topic when `DIRECTION` is `"out"`; Kafka topic to subscribe to when `DIRECTION` is `"in"`.
>
> **DESTINATION\_TOPIC** `string` *required*
>
> Kafka topic when `DIRECTION` is `"out"`; broker MQTT publish topic when `DIRECTION` is `"in"`.
>
> **DIRECTION** `string` *required*
>
> `"out"` (MQTT → Kafka) or `"in"` (Kafka → MQTT).

> **Optional**
>
> **QUERY** `string`
>
> The Kafka record **key** for partitioning (produce events only). See [Message Keys and Partitioning](#message-keys-and-partitioning).

> [!NOTE]
>
> `WITH EVERY` is not supported on a Kafka event. Adding a route that includes it is rejected. A route saved earlier still loads: `EVERY` is ignored, a warning is written to the log, and the event runs from its `SOURCE_TOPIC`. To produce on a schedule, use a LoT action with [`ON EVERY`](/latest/lot-language/actions/events#time-based-triggers) that publishes to the event's `SOURCE_TOPIC`.

***

## Message Keys and Partitioning

Kafka sends records with the same key to the same partition, which preserves **order per key**. On produce events, set the key with `WITH QUERY`.

* **With a key** (`WITH QUERY`): same key → same partition → ordering preserved per key (for example, all readings from one device stay in order).
* **Without a key**: records spread across all partitions for higher throughput, with no per-key ordering guarantee.
* **Consume events** join the consumer group and have partitions assigned automatically — set a stable `GROUP_ID` so offsets survive restarts.

### Key Placeholders

The `WITH QUERY` value is resolved before each record is sent. Supported placeholders:

| Placeholder | Description | Example result |
| - | - | - |
| `{topic.N}` | Nth segment (1-based) of the source topic | `pump-01` from `plant/sensors/pump-01/reading` |
| `{topic}` | Full source topic string | `plant/sensors/pump-01/reading` |
| `{payload}` | Message payload as a string | `42.5` |
| `{payload.json}` | Full payload parsed as JSON | — |
| `{payload.json.field}` | A JSON field from the payload | `pump-01` from `{"device_id":"pump-01","value":42}` |
| `{timestamp}` | ISO 8601 timestamp | `2026-06-12T10:30:45.123Z` |
| `{env.NAME}` | Environment variable value | value of `NAME` |
| `{secret.NAME}` | Secret value | value of `NAME` |

### Key from a topic segment

Use a wildcard position from the source topic as the key — here the device ID in the third segment:

```lot wrap focus={10} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorsByDevice WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-sensors"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "SCRAM-SHA-512"
        WITH SASL_USERNAME GET ENV "KAFKA_USER"
        WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
    ADD EVENT SensorsByDevice
        WITH SOURCE_TOPIC "plant/sensors/+/reading"
        WITH DESTINATION_TOPIC "plant.sensors.raw"
        WITH DIRECTION "out"
        WITH QUERY "{topic.3}"
```

A message on `plant/sensors/pump-01/reading` gets the key `pump-01`.

### Key from a JSON field

When the identifier lives inside the payload, pull it from a JSON field instead:

```lot wrap focus={13} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorsByPayloadId WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-sensors"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "SCRAM-SHA-512"
        WITH SASL_USERNAME GET ENV "KAFKA_USER"
        WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
    ADD EVENT SensorsByPayloadId
        WITH SOURCE_TOPIC "plant/sensors/+/reading"
        WITH DESTINATION_TOPIC "plant.sensors.raw"
        WITH DIRECTION "out"
        WITH QUERY "{payload.json.device_id}"
```

For a payload of `{"device_id":"pump-01","value":42}`, the record key becomes `pump-01`.

***

## Complete Examples

**Production (SASL\_SSL)**

Full production connector with TLS, SCRAM authentication, telemetry out, and alarms in:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-production"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "SCRAM-SHA-512"
        WITH SASL_USERNAME GET ENV "KAFKA_USER"
        WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
        WITH SSL_CA_LOCATION "/etc/ssl/certs/ca.pem"
        WITH ACKS "all"
        WITH AUTO_OFFSET_RESET "Earliest"
    ADD EVENT TelemetryOut
        WITH SOURCE_TOPIC "production/+/telemetry"
        WITH DESTINATION_TOPIC "production.telemetry"
        WITH DIRECTION "out"
        WITH QUERY "{topic.2}"
    ADD EVENT AlarmsIn
        WITH SOURCE_TOPIC "production.alarms"
        WITH DESTINATION_TOPIC "production/alarms/incoming"
        WITH DIRECTION "in"
```

**High-throughput telemetry**

Optimized for sustained high-rate telemetry with batching and compression:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TelemetryKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-telemetry"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "SCRAM-SHA-512"
        WITH SASL_USERNAME GET ENV "KAFKA_USER"
        WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
        WITH ACKS "1"
        WITH LINGER_MS "50"
        WITH COMPRESSION_TYPE "lz4"
        WITH FLUSH_TIMEOUT_MS "10000"
    ADD EVENT DeviceTelemetry
        WITH SOURCE_TOPIC "devices/+/telemetry"
        WITH DESTINATION_TOPIC "iot.telemetry"
        WITH DIRECTION "out"
        WITH QUERY "{topic.2}"
```

`ACKS "1"` avoids waiting for every replica on non-critical telemetry, `LINGER_MS "50"` batches bursts into fewer requests, and `lz4` compression cuts bandwidth with negligible CPU cost.

**Multiple topic mappings**

Connector different asset types to different Kafka topics, keyed by a JSON field:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AssetKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "KAFKA_BOOTSTRAP"
        WITH GROUP_ID "coreflux-assets"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "SCRAM-SHA-512"
        WITH SASL_USERNAME GET ENV "KAFKA_USER"
        WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
    ADD EVENT PumpsOut
        WITH SOURCE_TOPIC "assets/pumps/+/data"
        WITH DESTINATION_TOPIC "assets.pumps"
        WITH DIRECTION "out"
        WITH QUERY "{payload.json.asset_id}"
    ADD EVENT MotorsOut
        WITH SOURCE_TOPIC "assets/motors/+/data"
        WITH DESTINATION_TOPIC "assets.motors"
        WITH DIRECTION "out"
        WITH QUERY "{payload.json.asset_id}"
    ADD EVENT SetpointsIn
        WITH SOURCE_TOPIC "assets.setpoints"
        WITH DESTINATION_TOPIC "assets/setpoints/incoming"
        WITH DIRECTION "in"
```

**Confluent Cloud**

Connect to Confluent Cloud using SASL/PLAIN with an API key and secret:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ConfluentCloud WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS GET ENV "CONFLUENT_BOOTSTRAP"
        WITH GROUP_ID "coreflux-cloud"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "PLAIN"
        WITH SASL_USERNAME GET ENV "CONFLUENT_API_KEY"
        WITH SASL_PASSWORD GET SECRET "CONFLUENT_API_SECRET"
        WITH ACKS "all"
        WITH AUTO_OFFSET_RESET "Latest"
    ADD EVENT TelemetryToCloud
        WITH SOURCE_TOPIC "factory/+/telemetry"
        WITH DESTINATION_TOPIC "factory.telemetry"
        WITH DIRECTION "out"
        WITH QUERY "{topic.2}"
```

`CONFLUENT_BOOTSTRAP` is the `pkc-xxxx.region.confluent.cloud:9092` address from your cluster settings; the API key and secret come from the Confluent Cloud credentials page.

**High availability**

List multiple bootstrap brokers so the connector survives a single broker restart:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HaKafka WITH TYPE KAFKA
    ADD KAFKA_CONFIG
        WITH BROKER_ADDRESS "kafka-1:9092,kafka-2:9092,kafka-3:9092"
        WITH GROUP_ID "coreflux-ha"
        WITH SECURITY_PROTOCOL "SASL_SSL"
        WITH SASL_MECHANISM "SCRAM-SHA-512"
        WITH SASL_USERNAME GET ENV "KAFKA_USER"
        WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
        WITH ACKS "all"
    ADD EVENT TelemetryOut
        WITH SOURCE_TOPIC "factory/sensors/+"
        WITH DESTINATION_TOPIC "factory.sensors"
        WITH DIRECTION "out"
```

***

## Performance Tuning

A few settings control the trade-off between throughput, latency, durability, and memory. Tune them to match each stream.

### Durability vs. throughput (produce)

`ACKS` decides how many replicas must confirm each record before it counts as sent:

| `ACKS` | Behavior | Use for |
| - | - | - |
| `all` | Wait for all in-sync replicas (most durable, lower throughput) | Mission-critical data |
| `1` | Wait for the partition leader only | High-rate telemetry |
| `0` | Don't wait at all | Fire-and-forget metrics where loss is acceptable |

### Batching and compression (produce)

Under burst load, many produces are in flight at once and Kafka groups them into shared batches. These settings shape that behavior:

| Setting | Effect |
| - | - |
| `LINGER_MS "0"` | Send immediately — lowest latency, smallest batches |
| `LINGER_MS "50"` | Wait up to 50 ms to fill a batch — fewer, larger requests |
| `COMPRESSION_TYPE "lz4"` | Compress batches — lower bandwidth at negligible CPU cost |
| `BATCH_SIZE "2097152"` | Allow 2 MB batches — more messages per request |

### Consume throughput

Each consumed message commits its offset only after the broker has dispatched the message. That is at-least-once delivery, and it adds a short round-trip per message. For very high-rate consume topics, use one Kafka connector per logical stream rather than stacking many consume events on a single connector.

### Memory use (consume)

The connector pre-fetches messages into a buffer while it processes. On high-volume topics with many partitions this buffer can grow large. Cap it with `QUEUED_MAX_MESSAGES_KB` (for example `"4096"` for 4 MB per partition) and bound fetch responses with `FETCH_MAX_BYTES`.

### Watch for consume backpressure

When a consume connector publishes into the broker, a busy MQTT subsystem (many subscribers, large payloads) can slow the consumer down. If you pair a high-rate consume topic with many subscribers, monitor consumer group lag to catch this early.

***

## Best Practices

> **Always set a stable GROUP\_ID**
>
> A fixed group ID lets offsets survive restarts. Without one, a new random group is created on every startup and the consumer replays the entire topic.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH GROUP_ID "coreflux-plant-v1"
> ```

> **Use GET SECRET for credentials**
>
> Never hardcode passwords in a connector definition.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH SASL_PASSWORD GET SECRET "KAFKA_PASSWORD"
> ```

> **Use SASL\_SSL in production**
>
> Reserve `PLAINTEXT` for local development; encrypt and authenticate everything else.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH SECURITY_PROTOCOL "SASL_SSL"
> WITH SASL_MECHANISM "SCRAM-SHA-512"
> ```

> **Set AUTO\_OFFSET\_RESET deliberately**
>
> Choose where a brand-new consumer starts reading.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH AUTO_OFFSET_RESET "Earliest"   // replay history
> WITH AUTO_OFFSET_RESET "Latest"     // new messages only
> ```

> **Key messages for per-device ordering**
>
> Use a message key so all records from one device land on the same partition, in order.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH QUERY "{topic.2}"
> ```

> **List multiple bootstrap brokers**
>
> A single broker address is a single point of failure; list several for resilience.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH BROKER_ADDRESS "kafka-1:9092,kafka-2:9092,kafka-3:9092"
> ```

> **Monitor consumer group lag**
>
> Use your Kafka management UI (such as Confluent Control Center or Redpanda Console) or `kafka-consumer-groups --describe --group <GROUP_ID>` to watch for growing lag, which signals publish backpressure.

***

## Troubleshooting

> **Quick connection check**
>
> Verify a connector's connection at any time by publishing the following to `$SYS/Coreflux/Command` from any MQTT client:
>
> ```
> -checkConnectorConnection PlantKafka
> ```
>
> The connector validates the cluster connection and, when consume events are present, the consumer group join — catching configuration problems early.

> **The route does not start**
>
> A Kafka route that fails to start is retried in the background. The wait begins at 2 seconds and increases up to 60 seconds, until the route starts or you remove it.

> **Cannot connect to the cluster**
>
> * Confirm the bootstrap address and port are correct.
> * Make sure `SECURITY_PROTOCOL` matches the broker's listener.
> * Check that the port (default `9092`) isn't blocked by a firewall.
> * Verify network reachability to the broker host.

> **Connects, but no messages flow**
>
> The bootstrap connection can succeed while the cluster's advertised addresses point somewhere unreachable. This is common when Kafka runs in Docker. Make sure the broker advertises an address the Coreflux host can actually reach:
>
> | Where Coreflux runs | `BROKER_ADDRESS` |
> | - | - |
> | On the host | `localhost:9092` |
> | Same Docker network as Kafka | `kafka:9092` |

> **Authentication or SASL errors**
>
> * Confirm `SECURITY_PROTOCOL` matches the listener (e.g. `SASL_SSL`, not `SASL_PLAINTEXT`).
> * Make sure `SASL_MECHANISM` matches what the broker requires.
> * Check that credentials are correct and the env/secret names resolve.

> **Consumer receives nothing / replays every restart**
>
> * Set `AUTO_OFFSET_RESET "Earliest"` if messages were produced before the consumer first started.
> * Set a stable `GROUP_ID` so offsets are remembered across restarts.
> * Give each connector its own `GROUP_ID` unless you intentionally want them to share partitions.
> * An `"in"` event commits the offset only after the broker has dispatched the message. A crash before that dispatch leaves the record to be read again.

> **Performance problems**
>
> | Symptom | Likely cause | Fix |
> | - | - | - |
> | Produce slower than expected | `ACKS "all"` on a high-rate stream | Use `ACKS "1"` for telemetry |
> | High bandwidth usage | No compression | Add `COMPRESSION_TYPE "lz4"` and `LINGER_MS "50"` |
> | High memory on consume connectors | Large prefetch buffer | Set `QUEUED_MAX_MESSAGES_KB "4096"` |
> | Growing consumer lag | MQTT publish backpressure | Reduce subscriber load on the destination topics |
> | Messages lost on shutdown | Flush timeout too short | Raise `FLUSH_TIMEOUT_MS` |

***

## Next Steps

> **[System Connectors](../system-routes)**
>
> Configure MQTT bridges and Sparkplug roles.

> **[Data Storage Connectors](../data-storage/overview)**
>
> Persist MQTT data in databases for analytics.


# System Connectors
Source: https://docs.coreflux.org/latest/lot-language/routes/system-routes

Configure MQTT bridges and Sparkplug roles with Coreflux System Connectors

## Build the broker topology around your data

System Connectors define how your Coreflux broker participates in a wider MQTT system. Use them to bridge selected topics to another broker, or make Coreflux consume and produce Sparkplug B traffic.

> [!TIP]
>
> **Think of System Connectors as the roads around the broker.** Bridges connect MQTT brokers, and Sparkplug connectors define how industrial MQTT traffic enters and leaves the system.

> [!NOTE]
>
> For **high-availability Coreflux clustering** (multi-node broker failover), see [High-Availability Clustering](/latest/mqtt-broker/clustering) (beta). That feature is broker configuration, not a System Connector.

### When to use System Connectors

Use this category when you need to:

* synchronize topics with another MQTT broker;
* decode Sparkplug B payloads into readable JSON;
* publish as a Sparkplug edge node; or
* make Coreflux the Sparkplug Primary Host Application.

## Choose a System Connector

> **[MQTT Bridge](./system/mqtt-bridge)**
>
> Synchronize selected MQTT topics with another broker.

> **[Sparkplug B](./system/sparkplug-b)**
>
> Decode Sparkplug traffic or publish Coreflux metrics as an edge node.

> **[Sparkplug Host](./system/sparkplug-host)**
>
> Make Coreflux the Primary Host for a Sparkplug namespace.

***

Choose the connector by the role Coreflux needs to play.

## Compare System Connectors

| Connector | Coreflux role | Connects to | Best for |
| - | - | - | - |
| `MQTT_BRIDGE` | MQTT bridge | Another MQTT broker | Topic synchronization and edge-to-cloud links |
| `SPARKPLUG_B` | Decoder and/or edge node | A Sparkplug MQTT namespace | Translating Sparkplug to JSON or publishing Sparkplug telemetry |
| `SPARKPLUG_HOST` | Primary Host Application | Sparkplug edge nodes | Namespace authority, commands, and automatic rebirth requests |

> [!WARNING]
>
> A `SPARKPLUG_HOST` connector and a `SPARKPLUG_B` connector in `DECODE` or `BOTH` mode cannot run together on the same broker. Both consume the complete `spBv1.0/#` namespace. You can combine one Host connector with separate `ENCODE`-only connectors.

***

## Next Steps

> **[Choose a Sparkplug role](./system/sparkplug-b)**
>
> Compare decode, edge-node, and Primary Host responsibilities.

> **[High-Availability Clustering](/latest/mqtt-broker/clustering)**
>
> Run multiple Coreflux brokers as a fault-tolerant cluster (beta).


# MQTT Bridge Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/system/mqtt-bridge

Connect two MQTT brokers for edge-to-cloud synchronization, multi-site connectivity, and backup systems

## MQTT Bridge Overview

The `MQTT_BRIDGE` connector connects your Coreflux broker to another MQTT broker and keeps selected topics in sync between them. Use it for edge-to-cloud synchronization, linking multiple sites, or mirroring data to a backup broker.

> [!TIP]
>
> **Like call forwarding for messages.** You decide which topics get forwarded and in which direction, and the bridge relays every matching message between the two brokers automatically.

### When to use it

* Push local sensor data from an edge device up to a cloud broker.
* Pull commands or configuration from a central broker down to remote sites.
* Keep two brokers continuously in sync for redundancy.

***

Let's look at how to define a bridge, starting with the most common scenarios.

## Quick Start

**Edge to cloud (out)**

Forward local sensor data up to a cloud broker over TLS:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EdgeToCloud WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloud-provider.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "EdgeDevice001"
        WITH USERNAME "edge_user"
        WITH PASSWORD "secure_password"
        WITH USE_TLS "true"
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH DESTINATION_TOPIC "edge-001/sensors/+/data"
        WITH DIRECTION "out"
```

**Cloud to edge (in)**

Pull commands from a cloud broker down to the local broker:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CloudCommands WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloud-provider.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "EdgeDevice001-Commands"
        WITH USE_TLS "true"
    ADD MAPPING commands
        WITH SOURCE_TOPIC "local/commands/#"
        WITH DESTINATION_TOPIC "edge-001/commands/#"
        WITH DIRECTION "in"
```

**Bidirectional (both)**

Keep two brokers fully in sync in both directions:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FullSync WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "partner-broker.example.com"
        WITH BROKER_PORT '1883'
        WITH CLIENT_ID "SyncClient"
    ADD MAPPING bidirectionalSync
        WITH SOURCE_TOPIC "shared/data/#"
        WITH DESTINATION_TOPIC "partner/data/#"
        WITH DIRECTION "both"
```

***

## Connection Configuration

A bridge has two endpoints: a `SOURCE_CONFIG` (usually your local broker) and a `DESTINATION_CONFIG` (the remote broker). Use `WITH BROKER SELF` for the local Coreflux broker, or provide explicit connection details for a remote one.

> **Broker Settings**
>
> **BROKER\_ADDRESS** `string` *required*
>
> IP address or hostname of the broker. Use `SELF` for the local broker.
>
> **BROKER\_PORT** `integer` *required*
>
> MQTT port (typically 1883 for unencrypted, 8883 for TLS).
>
> **CLIENT\_ID** `string`
>
> Client identifier for the bridge connection. Optional. When unset, the broker generates one that is unique per host, connector and endpoint (`cf-<host>-<connector>-src` or `cf-<host>-<connector>-dst`). Set it when the remote broker expects a specific client ID, and keep it distinct for each connector.

> **Authentication**
>
> **USERNAME** `string`
>
> Authentication username.
>
> **PASSWORD** `string`
>
> Authentication password.

> **TLS/Security**
>
> **USE\_TLS** `boolean`
>
> Enable TLS encryption. Default: false.
>
> **ALLOW\_UNTRUSTED\_CERTS** `boolean`
>
> Allow untrusted certificates. Default: false.
>
> **SERVER\_CA\_CERT\_PATH** `string`
>
> Path to CA certificate file.
>
> **CLIENT\_CERT\_PATH** `string`
>
> Path to client certificate for mTLS.
>
> **CLIENT\_CERT\_PASS** `string`
>
> Client certificate password.

> **Connection Handling**
>
> **RECONNECTION\_RETRIES** `integer`
>
> Number of reconnection attempts. Default: 5.

***

## Mapping Configuration

Each `ADD MAPPING` block defines which topics are bridged and in which direction.

> **Topic Mapping**
>
> **SOURCE\_TOPIC** `string` *required*
>
> Topic pattern to subscribe to on the source broker. Supports wildcards.
>
> **DESTINATION\_TOPIC** `string` *required*
>
> Topic to publish to on the destination broker.
>
> **DIRECTION** `string` *required*
>
> Data flow direction: `out` (source→dest), `in` (dest→source), or `both`.

***

## Secure mTLS Bridge

For production links between sites, encrypt both endpoints and authenticate with mutual TLS:

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SecureBridge WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER_ADDRESS "192.168.1.10"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "SecureSource"
        WITH USE_TLS "true"
        WITH SERVER_CA_CERT_PATH "/certs/ca.pem"
        WITH CLIENT_CERT_PATH "/certs/client.pem"
        WITH CLIENT_CERT_PASS "cert_password"
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "secure.cloud.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "SecureDest"
        WITH USE_TLS "true"
        WITH ALLOW_UNTRUSTED_CERTS "false"
    ADD MAPPING secureMapping
        WITH SOURCE_TOPIC "secure/+/data"
        WITH DESTINATION_TOPIC "cloud/+/data"
        WITH DIRECTION "out"
```

***

## Best Practices

> **Use TLS for External Connections**
>
> Always enable TLS when connecting to external brokers:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH USE_TLS "true"
> ```

> **Unique Client IDs**
>
> If you set CLIENT\_ID, keep it unique per bridge connection to avoid conflicts. Two connections with the same client ID on one remote broker disconnect each other. Leave it unset to use the generated default.
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH CLIENT_ID "EdgeDevice001-SensorBridge"
> ```

> **Test with Local Broker First**
>
> Use `WITH BROKER SELF` during development:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> ADD SOURCE_CONFIG
>     WITH BROKER SELF
> ```

> **Secure Credentials**
>
> Store passwords securely and use app-specific passwords where available.

> **Handle Reconnection**
>
> Configure appropriate retry settings:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> WITH RECONNECTION_RETRIES '10'
> ```

***

## Troubleshooting

> **Bridge Connection Timeout**
>
> * Verify IP address and port are correct
> * Check firewall allows outbound connections on the configured port
> * Ensure remote broker is running and accessible
> * Try increasing `RECONNECTION_RETRIES`

> **TLS/Certificate Errors**
>
> * Verify certificate paths are correct
> * Ensure certificates are valid and not expired
> * Check certificate chain is complete
> * For testing, use `ALLOW_UNTRUSTED_CERTS "true"` (not recommended for production)

> **Messages Not Bridging**
>
> * Verify SOURCE\_TOPIC and DESTINATION\_TOPIC are correct
> * Check DIRECTION setting matches your expected data flow
> * If you set CLIENT\_ID, ensure it is unique across all connections
> * Check broker logs for subscription errors

***

## Next Steps

> **[System Connectors](../system-routes)**
>
> Compare bridging and Sparkplug roles.

> **[Sparkplug B](./sparkplug-b)**
>
> Publish and consume structured industrial MQTT data.


# Sparkplug B Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/system/sparkplug-b

Decode Sparkplug B traffic to JSON or publish Coreflux MQTT topics as a Sparkplug edge node

## Give industrial MQTT data a shared structure

The `SPARKPLUG_B` connector connects Coreflux to a Sparkplug B namespace. It can decode binary Sparkplug payloads into readable JSON, publish local MQTT topics as a Sparkplug edge node, or run both directions in one connector.

> [!TIP]
>
> **Sparkplug is a shared vocabulary for industrial MQTT.** MQTT carries the messages; Sparkplug defines how devices announce themselves, report values, and signal whether they are online.

### When to use it

Use this connector when you need to:

* consume `spBv1.0/#` traffic in LoT Actions, dashboards, or storage Connectors;
* publish Coreflux topics as `NBIRTH`, `NDATA`, and `NDEATH`;
* group edge-node metrics into Sparkplug devices;
* accept `NCMD` or `DCMD` writes for selected metrics; or
* gate edge-node publishing on an external Primary Host.

Use the separate [Sparkplug Host Connector](./sparkplug-host) when Coreflux must be the Primary Host Application. For a **custom** plant `.proto` (not Sparkplug), use [Protobuf Models](/latest/lot-language/models/protobuf) instead of this connector.

***

Start by choosing the direction in which Coreflux participates.

## Quick Start

**Decode to JSON**

Decode every Sparkplug B publisher on the local broker into readable MQTT topics:

```lot wrap focus={3} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantDecoder WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "DECODE"
```

This mode listens to all `spBv1.0/#` traffic. You do not need a Group ID or Edge Node ID.

**Publish as an edge node**

Publish a local temperature topic as a Sparkplug edge-node metric:

```lot wrap focus={3-5,6-8} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Line1Edge WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "ENCODE"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "Line1"
    ADD METRIC "Temperature"
        WITH DATA_TYPE "Float"
        WITH SOURCE_TOPIC "factory/line1/temperature"
```

Coreflux publishes a birth certificate when the connector connects and sends data when the source topic changes.

**Decode and publish**

Decode the namespace while publishing Coreflux metrics as a gateway edge node:

```lot wrap focus={3-5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantGateway WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "BOTH"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "CorefluxGateway"
    ADD METRIC "Uptime"
        WITH DATA_TYPE "Int64"
        WITH SOURCE_TOPIC "gateway/uptime"
```

The decode and encode paths operate independently inside the same connector.

***

## Choose the Coreflux role

| Mode | Coreflux role | Inbound behavior | Outbound behavior |
| - | - | - | - |
| `DECODE` | Translator and consumer | Decodes all `spBv1.0/#` traffic | None |
| `ENCODE` | Sparkplug edge node | Handles commands for writable metrics | Publishes birth, data, and death messages |
| `BOTH` | Translator and edge node | Decodes the namespace and handles commands | Publishes Coreflux metrics |

`MODE` is the canonical setting. `DIRECTION` remains accepted as a deprecated alias with the same values.

> [!WARNING]
>
> Only one namespace consumer can run per broker. Deploy either one `SPARKPLUG_B` connector in `DECODE` or `BOTH` mode, or one `SPARKPLUG_HOST` connector. Multiple `ENCODE`-only connectors are allowed.

## Configure the Sparkplug connection

The `SPARKPLUG_CONFIG` block controls the connector mode, edge-node identity, target MQTT broker, and optional Primary Host gating.

| Setting | Required | Default | Description |
| - | - | - | - |
| `MODE` | No | `DECODE` | `DECODE`, `ENCODE`, or `BOTH` |
| `GROUP_ID` | For `ENCODE`/`BOTH` | — | Group identity Coreflux publishes on the Sparkplug wire |
| `EDGE_NODE_ID` | For `ENCODE`/`BOTH` | — | Unique edge-node identity within the group |
| `PRIMARY_HOST_ID` | No | — | External Primary Host whose retained `STATE` gates edge publishing |
| `SERVER` | No | `localhost` | MQTT broker used by the encode path |
| `PORT` | No | `1883` | Target MQTT broker port |
| `USERNAME` | No | — | Target broker username |
| `PASSWORD` | No | — | Target broker password; use `GET SECRET` |
| `USE_TLS` | No | `false` | Enables TLS for the target broker connection |

> [!NOTE]
>
> `GROUP_ID` and `EDGE_NODE_ID` do not filter decoded traffic. The decode path always consumes the complete `spBv1.0/#` namespace.

## Declare edge-node metrics

In `ENCODE` or `BOTH` mode, add node-level metrics directly to the connector and device-level metrics inside `ADD DEVICE`.

| Setting | Required | Description |
| - | - | - |
| `DATA_TYPE` | Yes | Sparkplug datatype for the metric |
| `SOURCE_TOPIC` | Yes | Local MQTT topic whose value Coreflux publishes |
| `WRITE_TOPIC` or `DESTINATION_TOPIC` | For command write-back | Local topic that receives an inbound command value |
| `WRITABLE` | No | Set to `"true"` to accept `NCMD` or `DCMD` writes |

This complete connector publishes a node metric and a writable device metric to a remote broker:

```lot wrap focus={10-15} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Line1Edge WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "ENCODE"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "Line1"
        WITH SERVER GET ENV "SPARKPLUG_BROKER"
        WITH PORT 8883
        WITH USERNAME GET ENV "SPARKPLUG_USER"
        WITH PASSWORD GET SECRET "SPARKPLUG_PASSWORD"
        WITH USE_TLS true
    ADD METRIC "Uptime"
        WITH DATA_TYPE "Int64"
        WITH SOURCE_TOPIC "factory/line1/uptime"
    ADD DEVICE "Press01"
        ADD METRIC "Setpoint"
            WITH DATA_TYPE "Float"
            WITH SOURCE_TOPIC "factory/line1/press01/setpoint"
            WITH WRITE_TOPIC "factory/line1/press01/setpoint/write"
            WITH WRITABLE "true"
```

Supported scalar and array datatypes include signed and unsigned integers, `Float`, `Double`, `Boolean`, `String`, `Text`, `UUID`, `DateTime`, and `Bytes`. `DataSet` and `Template` values can be decoded but not encoded.

## Understand the message lifecycle

When the encode path connects, Coreflux:

1. publishes `NBIRTH`, including `bdSeq` and `Node Control/Rebirth`;
2. publishes one `DBIRTH` for each declared device;
3. publishes `NDATA` or `DDATA` when a source topic changes;
4. republishes births after a `Node Control/Rebirth` command; and
5. publishes death messages on a graceful stop or delivers `NDEATH` through the MQTT Will after a crash.

Writable node and device metrics accept inbound `NCMD` and `DCMD` values. Coreflux republishes each accepted value to its local write topic.

### Gate publishing on a Primary Host

Set `PRIMARY_HOST_ID` when an external Primary Host must be online before the edge node publishes:

```lot wrap focus={6} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GatedEdge WITH TYPE SPARKPLUG_B
    ADD SPARKPLUG_CONFIG
        WITH MODE "ENCODE"
        WITH GROUP_ID "Factory"
        WITH EDGE_NODE_ID "Line1"
        WITH PRIMARY_HOST_ID "PlantHost"
    ADD METRIC "Temperature"
        WITH DATA_TYPE "Float"
        WITH SOURCE_TOPIC "factory/line1/temperature"
```

The connector watches the retained `spBv1.0/STATE/PlantHost` topic. It defers births and suppresses data until the host reports `online:true`, then publishes fresh births and resumes data.

> [!WARNING]
>
> Primary Host gating does not buffer values. Data produced while the host is offline is dropped, and multi-server Primary Host failover is not supported.

***

## Consume decoded topics

The decode path converts the fixed Sparkplug wire namespace into a JSON topic tree:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
spBv1.0/<group>/<verb>/<node>/<device>
  → sparkplug/decoded/<group>/<node>/<device>/<metric>

spBv1.0/<group>/<verb>/<node>
  → sparkplug/decoded/<group>/<node>/<metric>
```

Each decoded metric contains its canonical name, value, datatype, timestamp, and quality:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "name": "Inputs/Temperature",
  "value": 24.6,
  "type": "Double",
  "timestamp": 1717160400123,
  "quality": "GOOD"
}
```

If a DATA metric omits its datatype, Coreflux uses the one from NBIRTH or DBIRTH.

The connector also publishes:

| Topic suffix | Retained | Purpose |
| - | - | - |
| `/<metric>` | No | Latest decoded metric event |
| `/$status` | Yes | Node or device online state from BIRTH and DEATH |
| `/$error` | No | Decode or alias-resolution error |

Metric names containing `/` create deeper topic levels. The `name` field in the JSON payload remains authoritative.

## Verify the connector

**1. Check connector health**

Publish the connection check command to `$SYS/Coreflux/Command`:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-checkConnectorConnection PlantDecoder
```

Confirm `$SYS/Coreflux/Routes/PlantDecoder/status` reports the connector as connected or active.

**2. Observe Sparkplug traffic**

Use any MQTT client to confirm messages arrive under `spBv1.0/#`.

**3. Subscribe to decoded output**

Subscribe to `sparkplug/decoded/#`. After a BIRTH message, named metric topics and retained `$status` topics appear.

## Troubleshooting

> **No decoded topics appear**
>
> Confirm the connector is active and that a Sparkplug B publisher is sending valid protobuf payloads under `spBv1.0/#`. Decoded output appears under `sparkplug/decoded/#`.

> **Metrics appear with unresolved aliases**
>
> Alias-only DATA arrived before its matching BIRTH. Wait for or request a rebirth and monitor `$error` for `alias_map_unavailable`.

> **The edge node remains silent**
>
> If `PRIMARY_HOST_ID` is configured, confirm the matching host publishes retained `{"online":true}` state on the same target broker configured by `SERVER` and `PORT`.

> **Commands do not reach local topics**
>
> Confirm the metric has `WRITABLE "true"` and a `WRITE_TOPIC` or `DESTINATION_TOPIC`. Read-only metrics reject inbound commands.

## Best Practices

* Give every edge node a unique `GROUP_ID` and `EDGE_NODE_ID` pair.
* Build automations on `sparkplug/decoded/#`, not on opaque protobuf topics.
* Use retained `$status` topics for availability checks.
* Load broker credentials with `GET ENV` and `GET SECRET`.
* Monitor `$error` and connector status for repeated alias or decode failures.

***

## Next Steps

> **[Configure Sparkplug Host](./sparkplug-host)**
>
> Make Coreflux the Primary Host and issue commands to edge nodes.

> **[Store decoded data](../data-storage/overview)**
>
> Persist readable Sparkplug metrics in a database.


# Sparkplug Host Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/system/sparkplug-host

Make Coreflux the Sparkplug B Primary Host Application for namespace state, commands, decoding, and rebirth control

## Make Coreflux the namespace authority

The `SPARKPLUG_HOST` connector makes Coreflux the Sparkplug B Primary Host Application. It publishes authoritative host state, decodes the complete Sparkplug namespace, issues commands to edge nodes, and requests rebirth when it detects missing aliases or sequence gaps.

> [!TIP]
>
> **The Primary Host is the control room for a Sparkplug namespace.** Edge nodes report their catalogues and values; the host watches their health and sends commands back.

### When to use it

Use this connector when Coreflux must:

* publish retained `STATE` as the namespace's Primary Host;
* consume and decode all edge-node traffic;
* issue `NCMD` and `DCMD` commands from LoT;
* detect sequence gaps and request a fresh BIRTH; or
* prevent two hosts from asserting the same Host ID.

Use [Sparkplug B Connector](./sparkplug-b) instead when Coreflux only needs to decode traffic or publish as an edge node.

***

Start with the broker where the Sparkplug edge nodes publish.

## Quick Start

**Local broker**

Make Coreflux the Primary Host for edge nodes connected to its local broker:

```lot wrap focus={3-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantHost WITH TYPE SPARKPLUG_HOST
    ADD SPARKPLUG_HOST_CONFIG
        WITH SERVER "localhost"
        WITH HOST_ID "CorefluxHost"
```

Coreflux publishes retained state at `spBv1.0/STATE/CorefluxHost` and decodes the local namespace.

**Remote plant broker**

Connect the Host connector to the broker already used by plant edge nodes:

```lot wrap focus={3-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantHost WITH TYPE SPARKPLUG_HOST
    ADD SPARKPLUG_HOST_CONFIG
        WITH SERVER "plant-broker.local"
        WITH PORT 8883
        WITH HOST_ID "CorefluxHost"
        WITH HOST_ID_CONFLICT "REFUSE"
        WITH USE_TLS true
        WITH USERNAME GET ENV "SPARKPLUG_USER"
        WITH PASSWORD GET SECRET "SPARKPLUG_PASSWORD"
```

Decoded metrics are republished on the local Coreflux broker under `sparkplug/decoded/#`.

**Declared command**

Add an explicit command target that works even before Coreflux sees the edge node's BIRTH:

```lot wrap focus={6-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantHost WITH TYPE SPARKPLUG_HOST
    ADD SPARKPLUG_HOST_CONFIG
        WITH SERVER "plant-broker.local"
        WITH HOST_ID "CorefluxHost"
        WITH HOST_ID_CONFLICT "REFUSE"
    ADD METRIC "Setpoint"
        WITH DATA_TYPE "Float"
        WITH TARGET "Factory/Line1/Press01"
        WITH COMMAND_TOPIC "commands/line1/press01/setpoint"
```

Publishing a value to the command topic sends a typed `DCMD` to `Press01`.

***

## Understand the Host role

A Host connector connects two MQTT contexts:

| Context | Purpose |
| - | - |
| Target broker (`SERVER`/`PORT`) | Carries `spBv1.0/#`, retained host `STATE`, and outbound commands |
| Local Coreflux broker | Receives `sparkplug/decoded/#` JSON and local command triggers |

The target and local brokers can be the same broker. If they differ, configure `SERVER` to the broker used by the Sparkplug edge nodes.

> [!WARNING]
>
> A `SPARKPLUG_HOST` connector consumes the complete Sparkplug namespace. Do not run it alongside a `SPARKPLUG_B` connector in `DECODE` or `BOTH` mode on the same broker. You can run separate `SPARKPLUG_B` connectors in `ENCODE` mode.

## Configure the Primary Host

| Setting | Required | Default | Description |
| - | - | - | - |
| `HOST_ID` | Yes | — | Identity published in `spBv1.0/STATE/<HOST_ID>` |
| `HOST_ID_CONFLICT` | No | `REFUSE` | `REFUSE` backs off when another host appears to own the ID; `WARN` proceeds and logs |
| `SERVER` | No | `localhost` | Target broker where edge nodes publish |
| `PORT` | No | `1883` | Target broker port |
| `USE_TLS` | No | `false` | Enables TLS for the target broker |
| `USERNAME` | No | — | Target broker username |
| `PASSWORD` | No | — | Target broker password; use `GET SECRET` |

There is no `MODE` setting: `SPARKPLUG_HOST` defines the role.

### Prevent Host ID conflicts

With the default `HOST_ID_CONFLICT "REFUSE"`, Coreflux watches the configured state topic before asserting the role. If it sees a foreign `online:true` state for the same Host ID, it disconnects and stands down for that session.

Use `WARN` only when you know that the other state is stale and Coreflux should proceed.

## Follow the STATE lifecycle

The Host connector publishes retained state with QoS 1:

1. Before connecting, it registers an MQTT Will with `online:false`.
2. After connecting, it publishes `online:true` using the same session timestamp.
3. On graceful stop, it publishes `online:false`.
4. After a crash, the target broker delivers the registered Will.
5. After reconnecting, it publishes a new offline-to-online session state.

The payload follows this shape:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "online": true,
  "timestamp": 1717160400123
}
```

Edge nodes configured with the matching `PRIMARY_HOST_ID` use this state to decide when to publish.

***

## Issue commands to edge nodes

The Host connector supports two command methods.

### Use the convention topic tree

Publish a value on the local broker without declaring command metrics:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sparkplug/command/<group>/<node>/<metric>
sparkplug/command/<group>/<node>/<device>/<metric>
```

The node form sends `NCMD`; the device form sends `DCMD`. Coreflux uses the datatype learned from the target's BIRTH catalogue.

This Action forwards a UI value to a node-level setpoint:

```lot wrap focus={3} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SetLine1Setpoint
ON TOPIC "ui/line1/setpoint" DO
    PUBLISH TOPIC "sparkplug/command/Factory/Line1/Setpoint" WITH PAYLOAD
```

### Declare a command overlay

Use `ADD METRIC` when you need a friendly trigger topic, an explicit datatype, or commands before the first BIRTH:

| Setting | Required | Description |
| - | - | - |
| `DATA_TYPE` | Yes | Sparkplug datatype used to encode the command |
| `TARGET` | Yes | `<group>/<node>` for `NCMD` or `<group>/<node>/<device>` for `DCMD` |
| `COMMAND_TOPIC` | Yes | Local MQTT topic that triggers the command |

The declared datatype takes precedence over a learned catalogue. If neither source provides a datatype, Coreflux drops the command instead of guessing.

## Decode and repair the namespace

The Host connector feeds the same readable topic tree as a `SPARKPLUG_B` decode connector:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
spBv1.0/<group>/<verb>/<node>[/<device>]
  → sparkplug/decoded/<group>/<node>[/<device>]/<metric>
```

It also monitors sequence integrity. When alias-only DATA arrives before BIRTH or a node's `seq` skips a value, Coreflux rate-limits and sends a node-level `Node Control/Rebirth` request.

| Output | Purpose |
| - | - |
| `sparkplug/decoded/.../<metric>` | Decoded metric JSON |
| `sparkplug/decoded/.../$status` | Retained node or device availability |
| `sparkplug/decoded/.../$error` | Decode and alias-resolution failures |

***

## Verify the Host connector

**1. Check connector health**

Publish the following command to `$SYS/Coreflux/Command`:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-checkConnectorConnection PlantHost
```

Confirm `$SYS/Coreflux/Routes/PlantHost/status` reports the target connection as active.

**2. Confirm Host state**

Use any MQTT client connected to the target broker and subscribe to `spBv1.0/STATE/CorefluxHost`. Confirm the retained payload reports `online:true`.

**3. Confirm decoded output**

Subscribe to `sparkplug/decoded/#` on the local Coreflux broker, then connect or rebirth an edge node.

**4. Test a command**

Publish a correctly typed value to a convention or declared command topic and confirm the edge node receives `NCMD` or `DCMD`.

## Troubleshooting

> **Host STATE is not published**
>
> Confirm `SERVER`, `PORT`, credentials, and TLS settings point to the broker used by the edge nodes. Check connector status for a `HOST_ID_CONFLICT` refusal.

> **No decoded data appears**
>
> Confirm edge nodes publish valid Sparkplug B traffic to the target broker and that no `SPARKPLUG_B` decode consumer conflicts with this Host connector.

> **Commands are dropped**
>
> Use the correct convention topic or declared `COMMAND_TOPIC`. If the edge node has not published BIRTH, declare the command with an explicit `DATA_TYPE`.

> **Repeated rebirth requests occur**
>
> Persistent alias or sequence gaps usually indicate an unstable edge node. Monitor decoded `$error` topics and the connector status.

## Limitations

> [!WARNING]
>
> * The connector connects to one target `SERVER` and `PORT`; multi-server Primary Host failover is not supported.
> * The connector does not provide durable store-and-forward replay.
> * `DataSet` and `Template` metrics decode to JSON but cannot be sent as commands.

## Best Practices

* Keep `HOST_ID_CONFLICT` set to `REFUSE` unless you intentionally take ownership.
* Match every edge node's `PRIMARY_HOST_ID` to the Host connector's `HOST_ID`.
* Point `SERVER` at the broker where the edge nodes actually publish.
* Prefer declared command overlays for production automations.
* Load credentials with `GET ENV` and `GET SECRET`.

***

## Next Steps

> **[Configure Sparkplug B](./sparkplug-b)**
>
> Decode traffic or publish Coreflux metrics as an edge node.

> **[Create LoT Actions](../../actions/overview)**
>
> Automate decoded metrics and Sparkplug command topics.


# High-Availability Clustering
Source: https://docs.coreflux.org/latest/mqtt-broker/clustering

Run Coreflux MQTT Broker nodes as a fault-tolerant cluster with automatic failover, majority-stored QoS 1/2 messages and delivery from any node

> [!WARNING]
>
> **High-availability clustering is in beta.** It has been tested by repeatedly killing, restarting, and isolating nodes under load, but not yet in production deployments, at production message rates, or across rolling upgrades. Its behavior and configuration options can change in a later release. Test it with your own workload before you rely on it in production, and include your broker version when you report an issue.

## Keep messaging available when a node fails

A single broker is a single point of failure. High-availability clustering (beta) runs several Coreflux MQTT Broker nodes as one system. Clients connect to any node, and a message published on one node reaches subscribers on every node. If a node stops, the others keep serving clients and take over its work. A QoS 1 or 2 message is acknowledged to the publisher only once it is stored on a majority of the nodes responsible for it, so losing a minority of the cluster does not lose messages the broker has already accepted.

> [!TIP]
>
> **Like a team that keeps shared minutes.** One member chairs the meeting, and every decision is written into the minutes of most members before it counts. If the chair leaves, the others pick a new one and carry on from the same minutes.

### When to use clustering

Use clustering when you need:

* MQTT service that continues when one broker stops, crashes, or is restarted for maintenance;
* QoS 1/2 messages that survive the loss of a node after the broker has acknowledged them; or
* one MQTT endpoint served by several broker nodes, on fixed machines or as Kubernetes pods.

Run **3** or **5** nodes. A cluster keeps working as long as a majority of its nodes are up: 2 of 3, or 3 of 5. Clustering requires a license that grants the cluster feature; with clustering enabled and no such license, the broker logs a warning and runs standalone.

> [!NOTE]
>
> Clustering is **broker configuration**, not a LoT Connector. To exchange topics with another, separate MQTT broker (including non-Coreflux brokers), use an [MQTT Bridge](/latest/lot-language/routes/system/mqtt-bridge) instead.

***

Setting up a cluster takes the same steps on every node: a service user for traffic between nodes, a `Cluster` section in the broker configuration, and durability turned on. Then load your LoT on any node, and the cluster replicates it to the others. See [LoT in a cluster](#lot-in-a-cluster).

## Quick Start

**1. Create the cluster service user on every node**

Nodes exchange messages with each other over MQTT, using a dedicated MQTT user. Create the same user, with the same password, on every node, for example with the [`-addUser` broker command](/latest/mqtt-broker/commands#user-management):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addUser cluster a-strong-password
```

Only this user may send cluster traffic between nodes.

**2. Configure the cluster on every node**

Add a `Cluster` section to the broker configuration of each node, or set the matching `COREFLUX_CLUSTER_*` environment variables (environment variables override the file). Keep everything identical except `NodeName`, and turn [durability](/latest/mqtt-broker/durability) on as well (see [Durability and clustering](#durability-and-clustering)).

**Seeds (typical production)**

List the peers' addresses when automatic discovery is not available, which is the case in most cloud networks and across subnets:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Cluster": {
    "Enabled": true,
    "ClusterId": "factory-floor",
    "NodeName": "broker-a",
    "Discovery": "seeds",
    "Seeds": ["broker-a:9200", "broker-b:9200", "broker-c:9200"],
    "SharedSecret": "a-long-random-secret",
    "DataPlaneUsername": "cluster"
  },
  "Durability": {
    "Enabled": true
  }
}
```

**Kubernetes**

Discover the pods through a headless Service. Use the StatefulSet pod name as `NodeName`, so each node keeps its identity when its pod is rescheduled:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Cluster": {
    "Enabled": true,
    "ClusterId": "k8s-brokers",
    "NodeName": "coreflux-broker-0",
    "Discovery": "kubernetes",
    "KubernetesServiceDns": "coreflux-broker-headless.default.svc.cluster.local",
    "KubernetesPeerPort": 9200,
    "SharedSecret": "a-long-random-secret",
    "DataPlaneUsername": "cluster"
  },
  "Durability": {
    "Enabled": true
  }
}
```

**Multicast (same LAN)**

Let nodes on one local network find each other automatically:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Cluster": {
    "Enabled": true,
    "ClusterId": "lab-cluster",
    "NodeName": "broker-1",
    "Discovery": "multicast",
    "SharedSecret": "a-long-random-secret",
    "DataPlaneUsername": "cluster"
  },
  "Durability": {
    "Enabled": true
  }
}
```

**Environment variables (Docker)**

The same seeds setup for a container, without editing the configuration file:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
environment:
  COREFLUX_CLUSTER_ENABLED: "true"
  COREFLUX_CLUSTER_ID: "factory-floor"
  COREFLUX_CLUSTER_NODE_NAME: "broker-a"
  COREFLUX_CLUSTER_DISCOVERY: "seeds"
  COREFLUX_CLUSTER_SEEDS: "broker-a:9200,broker-b:9200,broker-c:9200"
  COREFLUX_CLUSTER_SHARED_SECRET: "a-long-random-secret"
  COREFLUX_CLUSTER_DATAPLANE_USERNAME: "cluster"
  COREFLUX_DURABILITY_ENABLED: "true"
```

**3. Start the nodes**

Start all nodes. On a first start, the nodes wait up to `BootstrapGraceSeconds` (30 s by default) to make sure no cluster is running yet, then form a new one and elect a leader. Later restarts rejoin the existing cluster at once.

**4. Verify the cluster**

Call `GET /cluster` on the [operations port](/latest/mqtt-broker/operational-endpoints#cluster-status) of any node (`9100` by default):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl http://broker-a:9100/cluster
```

> [!TIP]
>
> Every node names the same `leadership.leader`, `membersTotal` equals your number of nodes on every node, and on the leader `membersAlive` equals `membersTotal`.

***

## How a cluster works

### One leader, automatic membership

The nodes elect one **leader**. The leader admits new nodes, removes dead ones, and decides which node is responsible for which part of the message traffic. Every node, leader or not, serves MQTT clients in the same way.

* **Elections are automatic.** When the leader is lost, the remaining nodes elect a new one within a few election timeouts, typically under a second. That includes a leader that is silent: frozen, or cut off so its cluster port no longer answers.
* **Nodes keep their identity.** A node is recognised by its `NodeName`, not by its IP address. A node that restarts on a new address, or on another node's old address, is recognised and its old address is dropped at once.
* **Restarts rejoin.** Each node remembers its cluster membership on disk and rejoins its peers after a restart, including when every node restarts at the same time.
* **Dead nodes are removed.** A node that stays unreachable for `MemberRemovalGraceSeconds` (5 minutes by default) is removed from the membership, so it no longer counts when the cluster checks for a majority. With `kubernetes` discovery, a pod that the headless Service no longer lists, and whose cluster port fails a TCP probe, is removed after `MemberAbsentFromDiscoverySeconds` (2 minutes, 120 seconds, by default). A new pod is found within seconds. A node is added back when it returns.
* **LoT changes go through the leader.** Send them to any node: a follower passes them to the leader. Other commands, such as user management, run on the node that receives them. See [LoT in a cluster](#lot-in-a-cluster).
* **No accidental second cluster.** A node that starts with no cluster state first asks its peers whether they already belong to a cluster, and joins that cluster instead of starting a new one.

### Partitions spread the work

QoS 1/2 traffic is split into **partitions** (32 by default). A publisher's messages always belong to the same partition, chosen from its client id. Each partition has one **owner**, the node that accepts its writes, and copies on other nodes (3 copies by default, owner included). The leader spreads the owners evenly across the nodes. When a node fails, its partitions move to nodes that already hold their copies, so no accepted message is left behind.

### QoS 1 and 2 are acknowledged once they are safe

When a client publishes at QoS 1 or 2, the broker stores the message on a majority of its partition's copies (2 of 3) before it sends the PUBACK (QoS 1) or PUBREC (QoS 2). A client connected to a node that does not own its partition is served the same way: that node passes the message to the owner and acknowledges it when the owner confirms.

If a majority cannot be reached in time (`ReplicationTimeoutMs`, 5 s by default), the broker **rejects** the publish instead of acknowledging a message it cannot keep safe, and does not deliver it:

| Reason code (MQTT 5) | Meaning | What the client should do |
| - | - | - |
| `0x97` Quota exceeded | Not enough nodes available for this partition right now (failover in progress, this side of a network split has no majority, or replication is still starting on the receiving node) | Retry after a short delay, on the same or another node |
| `0x80` Unspecified error | The node could not write the message to its disk | Retry; check the node's disk |

While replication is still starting, that `0x97` refusal uses the reason text "Cluster starting" and lasts at most 30 seconds. Retry; the node accepts the publish once replication is running.

> [!WARNING]
>
> **Use MQTT 5 for QoS 1/2 publishers.** MQTT 3.1.1 has no way to report a rejected publish: a 3.1.1 client receives a normal acknowledgement for a message the cluster did not accept. MQTT 5 clients see the reason code and can retry.

### Subscribers on any node receive every message

A message published on one node is delivered to matching subscribers on every node:

* **QoS 1/2** messages are queued on disk for each other node and re-sent until that node confirms delivery. A node that is down receives its messages when it returns, including messages for its offline persistent sessions.
* **QoS 0** messages are sent to the other nodes once, without storage. A node that is down misses them, as with any QoS 0 message.

### Failover

When a node fails, its partitions move to surviving nodes that already hold their copies. The new owner first catches up from the other copies, then re-delivers the messages of the last `ReplicationReplaySeconds` (5 minutes by default) for those partitions, so subscribers do not miss messages the failed node had accepted but not yet passed on. Subscribers can therefore receive some messages twice after a failover. With `ReplicationDedupDelivered` on (the default), a node drops a replay copy of a quorum-durable message it has already delivered. Set it to `false` to deliver every copy.

During a failover, publishes to the affected partitions are rejected with `0x97` until the new owner is ready. A new leader is elected within a few election timeouts, typically under a second, including when the lost node is silent. Expect about 15 seconds after a node failure before that owner is ready, and up to about 25 seconds when the failed node was the leader. Publishes to partitions owned by the surviving nodes continue meanwhile. Clients that retry on `0x97` lose nothing.

### Sessions follow the client

With [durability](/latest/mqtt-broker/durability) enabled, a client with a persistent session that reconnects to another node gets its subscriptions back. Messages already queued for it while it was offline stay on the node it was connected to, and are delivered only if it reconnects to that node. See [Limitations](#limitations).

***

## Durability and clustering

Clustering and [MQTT state durability](/latest/mqtt-broker/durability) protect different parts of a message's path, and a production cluster needs both:

* **Clustering** protects the message after the publisher's acknowledgement: it is stored on a majority of nodes and survives the loss of one of them.
* **Durability** protects the subscriber side on each node: persistent sessions, their subscriptions, the messages queued for them, and retained messages survive a restart of that node.

| What is lost when … | Clustering only | Clustering + durability |
| - | - | - |
| a node with persistent subscribers restarts | the messages queued for them, and the messages published while the node was down | nothing |
| a node that owns partitions fails | nothing | nothing |
| a client reconnects to another node | its subscriptions | the messages queued for it on the old node (delivered only if it reconnects there) |
| a node restarts (retained messages) | the node's retained messages | nothing |

> [!TIP]
>
> Enable durability on **every** node of a cluster. Clients without persistent sessions (MQTT 3.1.1 clean session, MQTT 5 session expiry 0) are not affected either way.

***

## LoT in a cluster

The cluster runs LoT as **one logical broker**. A client can connect to any node and sees the same definitions, the same shared state, and the same results. A broker that isn't clustered behaves as before.

### The three rules

1. **Same definitions everywhere.** Every node runs the same version of every action, model, connector, rule, Python script, and panel. Changes go through the leader and are replicated to every node.
2. **One place per piece of work.** A message runs LoT on the node it **entered**. A client event runs on the node that holds the connection. Timers, startup, and device connections run on one **owner** node that the cluster picks.
3. **A message from a peer never triggers LoT.** It still reaches that node's subscribers and caches, but the action that reacts to it runs once, where the message came in.

### Where LoT runs

| Trigger | Examples | Runs on |
| - | - | - |
| A message | `ON TOPIC`, `ON CHANGE`, a model's trigger fields | The node the message entered. The output reaches subscribers on every node |
| A client event | `ON CONNECT`, `ON DISCONNECT`, `ON SUBSCRIBE` | The node holding the connection |
| A timer | `ON EVERY`, `ON EVERY WEEKDAY AT` | The action's owner |
| Startup | `ON START` | The action's owner, once per cluster session. See [ON START and KEEP](#on-start-and-keep) |
| Called code | `CALL ACTION`, `CALL PYTHON` | Wherever the caller runs. Python module state stays on that node |
| Access rules | `DEFINE RULE` | Every node |
| Shared state | `KEEP TOPIC` | Where the action runs. The value reaches every node |

### Where connectors run

| Class | Connector types | Runs on |
| - | - | - |
| **Client of a service** | PostgreSQL, MySQL, MariaDB, SQL Server, MongoDB, OpenSearch, CrateDB, Snowflake, REST client, email, LLM, MCP, barcode | Every node. Events run where the message entered; a scheduled event (`WITH EVERY`) has one owner |
| **Exclusive connection** | Modbus TCP and serial, Siemens S7, OPC UA client, EtherNet/IP, ADS, Allen-Bradley, FINS, BACnet, Sparkplug host and edge node, MQTT bridge to a remote broker, video input, audio input, `FILE_STORAGE`, `MQTT_TO_REST`, streaming gRPC | **Only its owner.** Other nodes hold the definition and report it as **standby** |
| **Server** | `MODBUS_SERVER`, `OPCUA_SERVER`, `VIDEO_OUTPUT`, `REST_API` in server mode | Every node, on `0.0.0.0:<port>`. See [Server connectors](#server-connectors) |
| **Group consumer** | `KAFKA` | Every node, in one consumer group. An `"in"` Kafka connector must set `GROUP_ID`, or every node reads every message |
| **Local transform** | MQTT bridge from `SELF` to `SELF`, Sparkplug decode | Every node |

A `MODBUS_SERVER` on a serial port is an exclusive connection: only its owner opens the port.

A `TRIGGER` or `STORE IN` on a node that doesn't own the connector is sent to the owner and runs there. A `FETCH` needs the answer where it was asked, so on another node it fails with a message that names the owner. Use an event that writes to a `DESTINATION_TOPIC` instead.

### Pin a connector

To keep an exclusive connector on the node that is cabled to the device, set `CLUSTER_NODE` in `CONNECTOR_CONFIG` (`ROUTE_CONFIG` remains a supported alias) to that node's `NodeName`:

```lot wrap focus={7-8} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Press1 WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH CONNECTION_TYPE "TCP"
        WITH IP "192.168.1.100"
        WITH PORT 502
        WITH SLAVE_ID 1
    ADD CONNECTOR_CONFIG
        WITH CLUSTER_NODE "coreflux-node2"
    ADD MAPPING Poll
        WITH EVERY 1 SECONDS
        WITH SOURCE_TOPIC "press1/read"
        ADD TAG Temperature
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "INT16"
```

While the pinned node is down, the connector runs nowhere. Leave `CLUSTER_NODE` out to let the cluster place and balance it.

### Change definitions

Send LoT commands (`-addAction`, `-removeConnector`, `-loadProject`, MCP tools, the HUB) to **any** node. A follower passes the command to the leader, which validates and commits it. The follower answers once its own node has applied the change.

* A command that fails changes nothing on any node. A project load is applied as one change.
* Changes are refused, with the reason, while a majority of nodes can't be reached, or while a live node runs a version without replicated LoT. **Upgrade every node before you change LoT.** `lot.mixedMode` in [`GET /cluster`](/latest/mqtt-broker/operational-endpoints#cluster-status) shows when this is the case.
* Users and credentials are **not** replicated. Create them on every node: the node that receives a command checks your permission locally.

**First start.** Until the first change is committed, each node runs its own LoT. Once the leader has been stable for a few seconds, or on the first LoT command, the leader's definitions become the cluster's. A node whose files differ drops what the cluster doesn't have and saves each definition it removes or replaces under `lot-backup/<timestamp>/<kind>/<name>.lot`.

**A node that was away** catches up when it returns: it applies what it missed, removes what the cluster removed, and backs up the files it drops.

### Owners and failover

Each timer, `ON START` action, exclusive connector, and scheduled event has **one owner and one standby node**. Every node agrees on the map, and the cluster spreads the work over the live nodes.

| Event | What happens |
| - | - |
| A node stops or is cut off | After 6 s of silence, its work moves to the standby nodes. Nothing else moves |
| A node comes back | It takes **new** work, not work that is already running elsewhere |
| An owner loses contact with a majority | Within 4 s it stops its timers and closes its device connections itself, before another node takes them over, so a device never sees two clients |
| The leader fails | The new leader continues from the committed map |

Plan on about **10 seconds** without a timer or device connection when its owner fails. After a takeover:

* A timer starts a new cycle, and runs missed during the takeover aren't made up.
* `DATE_TIME` timers use the node's local time, so **set the same time zone on every node**.
* Python module globals, LLM conversations, and the OT publish-on-change state start fresh on the new owner.
* The node that loses a connector doesn't clear its tag topics.

### ON START and KEEP

`ON START` runs **once per cluster session**, on the action's owner, and again when the action is redeployed with different code.

* A session starts when the cluster forms from nothing and lasts while any of its members is alive. Restarting one node, or all but one, runs nothing. Restarting every node starts a new session.
* An `ON START` action runs at most once per session and code version, even if its node fails before it runs.
* While a definition fails to apply on a node, `ON START` actions wait on that node.

`KEEP TOPIC` values are sent to every node's cache, without reaching subscribers or triggering LoT there.

* Values are **eventually consistent**: when two nodes keep the same topic at about the same time, the later write wins. A normal publish to the topic replaces a kept value.
* A node that was down gets the values when it returns, and a node keeps its values across a restart. Each value can be up to 1 MB, with up to 100,000 kept topics per node.

### Server connectors

A server connector (Modbus server, OPC UA server, REST API server, video output) runs on **every node**, so a load balancer or Kubernetes Service can send a client to any of them. Every node serves the current value of every tag.

* **OPC UA behind one name.** Set `WITH ADVERTISED_HOST "opcua.example.com"` in `OPCUA_SERVER_CONFIG` (a host name or address, no scheme, port, or path). To present one identity, put the same PKCS#12 certificate with its private key in `<PKI_DIR>/own/private` on each node, or import it with `-connectorCertificates import`. In a container, set `PKI_DIR` to a writable folder.
* **Failed listeners are reported.** `GET /cluster` lists every connector listener under `routeListeners` with its state, also on retained `$SYS/Coreflux/Cluster/RouteListeners` and as `coreflux_route_listener_up` on `/metrics`. A failed bind isn't retried.
* **Open every port.** The Service or load balancer must list every server connector port, including ones you add later. `MODBUS_SERVER` defaults to port 502, which a non-root container can't bind: map it to an unprivileged port.

### What is guaranteed

* **A LoT run is at most once per message.** If a node fails after a message is accepted but before LoT runs, that run is lost. Failover replay delivers the message again but doesn't run LoT again.
* **LoT output isn't quorum-durable.** It's forwarded to the other nodes over the reliable link.
* **`ON CHANGE` compares against the last value this node saw.** There is no cluster-wide order per topic.
* **QoS 1 redelivery runs an `ON TOPIC` action twice**, as on a single broker.
* **Definitions match on every node** once a change is applied. Until then, `lot` in `GET /cluster` shows which node is behind and why.

***

## Configuration reference

Set these options in the `Cluster` section of the broker configuration, or with the listed environment variables (environment variables win). Use the same values on every node, except `NodeName`, `AdvertisedHost`, and `BindIP`.

### Identity and discovery

| Config field | Env var | Default | Description |
| - | - | - | - |
| `Enabled` | `COREFLUX_CLUSTER_ENABLED` | `false` | Turns clustering on. The license must also grant the cluster feature |
| `ClusterId` | `COREFLUX_CLUSTER_ID` | `coreflux-cluster` | Name of the cluster. Required |
| `NodeName` | `COREFLUX_CLUSTER_NODE_NAME` | host name | This node's identity in the cluster. Must be unique and must not change; in Kubernetes, use the StatefulSet pod name |
| `Discovery` | `COREFLUX_CLUSTER_DISCOVERY` | `multicast` | How nodes find each other: `seeds`, `kubernetes`, or `multicast` |
| `Seeds` | `COREFLUX_CLUSTER_SEEDS` | — | Peer addresses as `host:port`, separated by `,`, `;`, or spaces. Required with `seeds` |
| `KubernetesServiceDns` | `COREFLUX_CLUSTER_K8S_SERVICE_DNS` | — | DNS name of the headless Service. Required with `kubernetes` |
| `KubernetesPeerPort` | `COREFLUX_CLUSTER_K8S_PEER_PORT` | `Port` | Cluster port of the pods found through that Service |
| `MulticastGroup` | `COREFLUX_CLUSTER_MULTICAST_GROUP` | `239.63.114.71` | Multicast group for `multicast` discovery |
| `MulticastPort` | `COREFLUX_CLUSTER_MULTICAST_PORT` | `9201` | UDP port for `multicast` discovery |
| `SharedSecret` | `COREFLUX_CLUSTER_SHARED_SECRET` | — | Signs all traffic between nodes so it cannot be forged; with `multicast`, also keeps foreign nodes out. **Set it in production**; the broker logs a warning when it is missing |

### Network

| Config field | Env var | Default | Description |
| - | - | - | - |
| `BindIP` | `COREFLUX_CLUSTER_BIND_IP` | `0.0.0.0` | Local address of the cluster port |
| `Port` | `COREFLUX_CLUSTER_PORT` | `9200` | Cluster TCP port (leader election and membership) |
| `AdvertisedHost` | `COREFLUX_CLUSTER_ADVERTISED_HOST` | `NodeName` | Address the other nodes use to reach this node. Set it when the node's own address is not reachable from its peers (containers, NAT) |
| `AdvertisedPort` | `COREFLUX_CLUSTER_ADVERTISED_PORT` | `Port` | Port the other nodes use to reach this node |
| `DataPlaneUsername` | `COREFLUX_CLUSTER_DATAPLANE_USERNAME` | — | The cluster service user. It must exist, with a password, on every node. Without it, nodes do not exchange messages or LoT changes. If it is set but missing from a node's users, clustering does not start on that node |
| `DataPlaneMqttPort` | `COREFLUX_CLUSTER_DATAPLANE_MQTT_PORT` | broker MQTT port | MQTT port nodes use to reach each other |
| `DataPlaneEnabled` | `COREFLUX_CLUSTER_DATAPLANE_ENABLED` | `true` | Forwards QoS 0 messages between nodes. When `false`, QoS 0 messages stay on the node they were published on |
| `Topology` | `COREFLUX_CLUSTER_TOPOLOGY` | `mesh` | How QoS 0 messages travel: `mesh` (every node to every node, recommended) or `ring` (to two neighbours only; complete only for up to 3 nodes) |
| `UseTls` | `COREFLUX_CLUSTER_TLS` | `false` | Uses TLS for the QoS 0 links between nodes. It does not encrypt the cluster port or the QoS 1/2 links (see [Ports and network](#ports-and-network)) |
| `DataDir` | `COREFLUX_CLUSTER_DATA_DIR` | `cluster` folder in the broker data path | Where the node keeps its cluster state and partition copies. Must be on persistent storage |
| `PublishInternalRoutes` | `COREFLUX_CLUSTER_PUBLISH_INTERNAL_ROUTES` | `false` | Troubleshooting aid: publishes the connectors the cluster generates between nodes, password redacted, on `$SYS/Coreflux/Cluster/DataPlane/Routes/{name}` |

### Replication

| Config field | Env var | Default | Description |
| - | - | - | - |
| `ReplicationEnabled` | `COREFLUX_CLUSTER_REPLICATION_ENABLED` | `true` | Stores QoS 1/2 messages on several nodes, delivers them reliably to other nodes, and lets sessions follow clients. When `false`, QoS 1/2 messages travel between nodes like QoS 0, and a follower can't pass LoT changes or connector calls to other nodes |
| `QuorumGateEnabled` | `COREFLUX_CLUSTER_QUORUM_GATE` | `true` | Waits for a majority before acknowledging QoS 1/2 publishes. When `false`, publishes are acknowledged once the receiving node has them, and are no longer protected against that node's loss |
| `ReplicationFactor` | `COREFLUX_CLUSTER_REPLICATION_FACTOR` | `0` (= 3) | Copies of each partition, owner included (0–7), limited by the number of nodes up. `1` gives no protection across nodes |
| `PartitionCount` | `COREFLUX_CLUSTER_PARTITION_COUNT` | `32` | Number of partitions (1–4096). Choose it once: changing it on a running cluster reassigns every client |
| `ReplicationTimeoutMs` | `COREFLUX_CLUSTER_REPLICATION_TIMEOUT_MS` | `5000` | How long a publish may wait for a majority before it is rejected (100–60000) |
| `ReplicationWindow` | `COREFLUX_CLUSTER_REPLICATION_WINDOW` | `1024` | QoS 1/2 publishes that may wait for a majority at the same time on a node (1–65536). Beyond it, publishes are rejected at once with `0x97` |
| `ReplicationReplaySeconds` | `COREFLUX_CLUSTER_REPLICATION_REPLAY_SECONDS` | `300` | Messages re-delivered after a failover, in seconds (0 = none, up to 86400). Longer means more duplicates, shorter means more risk of a gap |
| `ReplicationForwardQueueEntries` | `COREFLUX_CLUSTER_REPLICATION_FORWARD_QUEUE_ENTRIES` | `8192` | QoS 1/2 messages kept for a node that is down (64–1000000). Beyond it, the oldest are dropped for that node |
| `ReplicationCompactEveryRecords` | `COREFLUX_CLUSTER_REPLICATION_COMPACT_EVERY` | `50000` | Compacts a partition's stored messages after this many records, to bound disk use (1000–10000000) |
| `ReplicationDedupDelivered` | `COREFLUX_CLUSTER_REPLICATION_DEDUP_DELIVERED` | `true` | The node remembers which quorum-durable messages it delivered and drops failover-replay copies of them. `false` delivers every copy |
| `ReplicationTrace` | `COREFLUX_CLUSTER_REPLICATION_TRACE` | `false` | Records each QoS 1 or 2 message on the node under `replication/trace`. Read it with [`GET /cluster/trace`](/latest/mqtt-broker/operational-endpoints#replication-trace) on the ops port (`9100`). About 50 MB per hour per node at 100 messages per second |
| `ReplicationTraceMaxMegabytes` | `COREFLUX_CLUSTER_REPLICATION_TRACE_MAX_MB` | `512` | Cap on those trace files, in megabytes (8–8192). The oldest files are deleted first |

### Membership and startup

| Config field | Env var | Default | Description |
| - | - | - | - |
| `BootstrapGraceSeconds` | `COREFLUX_CLUSTER_BOOTSTRAP_GRACE_SECONDS` | `30` | How long a node with no cluster state waits to be added to a running cluster before it may start a new one (1–3600). Also how long a node retries resolving its `AdvertisedHost` and looking for peers that moved |
| `BootstrapPeerCheck` | `COREFLUX_CLUSTER_BOOTSTRAP_PEER_CHECK` | `true` | Before starting a new cluster, asks each peer's operations endpoint whether it already belongs to one. A peer that doesn't answer counts as one that might, so the node keeps waiting. Turn off only if the operations ports cannot be reached between nodes |
| `PeerOpsPort` | `COREFLUX_CLUSTER_PEER_OPS_PORT` | `0` (= this node's) | Operations port of the peers, for that check |
| `MemberRemovalGraceSeconds` | `COREFLUX_CLUSTER_MEMBER_REMOVAL_GRACE_SECONDS` | `300` | The leader removes a node that stays unreachable for this long from the membership, so it no longer counts toward the majority (0–86400). It is added back once discovery lists it and it answers. A member that Kubernetes discovery has stopped listing is removed with `MemberAbsentFromDiscoverySeconds` instead. `0` turns off removal of an unreachable node |
| `MemberAbsentFromDiscoverySeconds` | `COREFLUX_CLUSTER_MEMBER_ABSENT_FROM_DISCOVERY_SECONDS` | `120` | With Kubernetes discovery, the leader removes a member that DNS has stopped listing and that fails a TCP probe, after this many seconds (10–86400) |
| `MemberAddResignSeconds` | `COREFLUX_CLUSTER_MEMBER_ADD_RESIGN_SECONDS` | `60` | The leader resigns if it has tried this long to add a member that discovery lists and that answers a TCP probe, without the member joining (0 = never; 15–3600). The next leader tries again |
| `ElectionTimeoutLowerMs` | `COREFLUX_CLUSTER_ELECTION_LOWER_MS` | `150` | Lower bound of the randomised election timeout. Lower values detect a lost leader sooner |
| `ElectionTimeoutUpperMs` | `COREFLUX_CLUSTER_ELECTION_UPPER_MS` | `300` | Upper bound; must be greater than the lower bound |
| `ElectionRpcTimeoutMs` | `COREFLUX_CLUSTER_ELECTION_RPC_TIMEOUT_MS` | `0` (= 2/3 of the lower election timeout, 100 ms) | How long a node waits for a vote, pre-vote, or heartbeat reply, and to connect. Must be shorter than `ElectionTimeoutLowerMs`; otherwise clustering does not start |
| `HeartbeatThreshold` | `COREFLUX_CLUSTER_HEARTBEAT_THRESHOLD` | `0.25` | The leader sends a heartbeat every election timeout multiplied by this value (0.05–0.5) |
| `RaftTransport` | `COREFLUX_CLUSTER_RAFT_TRANSPORT` | `Deadline` | `Deadline` gives votes, pre-votes, and heartbeats their own reply deadline. `Tcp` is the fallback |

The broker checks these values at start. If one is invalid, clustering does not start, the log names the problem, and `GET /cluster` reports `enabled: false`.

***

## Ports and network

| Port | Protocol | Purpose | Open between |
| - | - | - | - |
| `9200` (`Port`) | TCP | Leader election and membership | All nodes |
| Broker MQTT port (`1883` by default) | TCP | Messages between nodes, as the cluster service user | All nodes |
| `9100` (operations port) | TCP | Bootstrap check and monitoring | All nodes, and your monitoring system |
| `9201` (`MulticastPort`) | UDP | Discovery, `multicast` mode only | All nodes |

> [!WARNING]
>
> **Keep the cluster port on a private network.** Traffic on port `9200` is neither encrypted nor authenticated. `SharedSecret` signs the messages exchanged between nodes, but not this port. Allow it only between cluster nodes.

***

## Delivery guarantees

| QoS | With clustering |
| - | - |
| **0** | Delivered to subscribers on every node that is up. Lost for a node that is down, or if the publishing node fails, as with any QoS 0 message |
| **1** | Acknowledged only once stored on a majority of its partition's copies; otherwise rejected (`0x97`/`0x80`) and not delivered. Delivered to subscribers on every node, including nodes that are down when it is published (when they return). At least once: after a failover, some messages can arrive twice |
| **2** | The same as QoS 1. Between a client and its node the QoS 2 exchange works as usual, but across a node failure delivery is **at least once**, not exactly once |

Design consumers to tolerate duplicates, for example with a message id or sequence number in the payload. For new designs, QoS 1 gives the same guarantee as QoS 2 in a cluster, with one round trip less.

***

## Operations

### Starting, restarting, and scaling

* **First start:** expect about `BootstrapGraceSeconds` (30 s) before the cluster forms. Until then, `GET /cluster` reports `enabled: false` or no leader.
* **Restarts:** a node rejoins with its previous identity and data. Restart one node at a time, and wait for `GET /cluster` to show it back before restarting the next.
* **Adding a node:** start it with the same cluster settings and a new `NodeName`, and add it to `Seeds` on the other nodes if you use seeds. The leader admits it and moves some partitions to it.
* **Removing a node:** stop it. After `MemberRemovalGraceSeconds` it leaves the membership and its partitions stay on the remaining nodes. In Kubernetes, a pod the headless Service no longer lists leaves after about 2 minutes (`MemberAbsentFromDiscoverySeconds`, 120 seconds by default), once its cluster port fails a TCP probe.
* **Upgrades:** all nodes of a cluster must run the same broker version. To upgrade a cluster from 2.14 or earlier, stop all nodes and upgrade them together. LoT changes are refused until every node runs a version that replicates LoT.

### Monitoring

| Signal | What it shows |
| - | - |
| [`GET /cluster`](/latest/mqtt-broker/operational-endpoints#cluster-status) | The node's full cluster view: leader, members, partition ownership, replication and forwarding counters |
| [`GET /cluster/trace`](/latest/mqtt-broker/operational-endpoints#replication-trace) | Each QoS 1 or 2 message on the node, when `ReplicationTrace` is on |
| [`GET /info`](/latest/mqtt-broker/operational-endpoints#cluster-and-mcp-summaries) | A short `cluster` summary: role, leader, member count |
| [Prometheus `/metrics`](/latest/mqtt-broker/operational-endpoints#when-durability-or-clustering-is-active) | `coreflux_cluster_*`, `coreflux_partition*`, and `coreflux_replication_*` series |
| Retained `$SYS` topics | `$SYS/Coreflux/Cluster/Role`, `IsLeader`, `Leader`, `Term`, `Members`, and `Status` (a JSON summary), refreshed every 7 seconds |

Watch these values; on a healthy cluster they stay at the healthy value:

| Value | Healthy | When it is not |
| - | - | - |
| Leader (`leadership.leader` in `/cluster`) | the same node on every node | Elections in progress, or a node cut off from the others |
| `membersTotal` | your number of nodes, on every node | A larger value means a node's old address is still listed; it is removed within seconds when the node answers at its new address |
| `membersAlive` on the leader | equal to `membersTotal` | A node is down or unreachable (followers report other nodes as `unknown`; trust the leader's view) |
| Rejected publishes (`coreflux_replication_quorum_failures_total`) | not increasing | Clients are getting `0x97`: a failover is in progress, or there is no majority |
| Messages waiting for other nodes (`coreflux_replication_forward_backlog`) | close to `0` | A node is down or slow; the queue empties when it catches up |
| Messages dropped for a node that was down too long (`coreflux_replication_forward_dropped_total`) | `0` | Subscribers on that node missed messages; increase `ReplicationForwardQueueEntries` or bring nodes back sooner |

Use MQTT Explorer or any MQTT client to subscribe to `$SYS/Coreflux/Cluster/#`.

***

## Best practices

> **Do**
>
> * Run 3 or 5 nodes, and spread them across failure domains (hosts, racks, zones).
> * Set `SharedSecret`, and keep the cluster port on a private network.
> * Enable durability on every node.
> * Use MQTT 5 for QoS 1/2 publishers, and retry on `0x97`.
> * Make consumers tolerate duplicates.
> * Give each node a stable `NodeName` and persistent storage for `DataDir` and the durability data.
> * Deploy LoT through any one node and let the cluster place it; pin an exclusive Connector to a node with `CLUSTER_NODE` only when the device is cabled to that node (see [LoT in a cluster](#lot-in-a-cluster)).
> * Create the same users on every node, and use the same time zone and synchronised clocks.

> **Don't**
>
> * Don't run 2 nodes: losing either one stops QoS 1/2 publishing, because 1 of 2 is not a majority.
> * Don't set `ReplicationFactor` to `1` when you need messages to survive a node failure.
> * Don't change `PartitionCount` on a running cluster.
> * Don't restart several nodes at once on a 3-node cluster: QoS 1/2 publishing pauses until a majority is back.

***

## Limitations

> [!WARNING]
>
> **Offline queues stay on their node.** A persistent session's subscriptions follow a client to another node (with durability), but messages already queued for it stay on the node it was connected to, and are delivered only if it reconnects there.

> [!WARNING]
>
> **Users and credentials are kept per node.** Create the same users on every node. LoT definitions, including Rules, are replicated; users are not.

> [!WARNING]
>
> **Retained messages are kept per node.** Each node keeps its own copy of retained messages. A node added later does not receive retained messages published before it joined, and a node that was down misses retained QoS 0 messages published meanwhile.

> [!WARNING]
>
> **At least once, not exactly once.** After a failover, subscribers can receive some messages twice, at QoS 1 and QoS 2.

> [!WARNING]
>
> **MQTT 3.1.1 publishers cannot see rejected publishes.** When the cluster cannot reach a majority, a 3.1.1 client still receives a normal acknowledgement for a message that was not accepted. Use MQTT 5 for QoS 1/2 publishers.

> [!WARNING]
>
> **One publishing connection is limited by the time to reach a majority.** Each QoS 1/2 message waits for its majority before the broker reads the same connection's next message. Total throughput grows with the number of publishing connections. A single connection that publishes at high rate is limited to roughly one message per round trip between nodes.

> [!WARNING]
>
> **Shared subscriptions are per node.** A shared subscription group includes only the clients connected to the same node; each node delivers a message to one member of its own group. See [shared subscriptions](/latest/mqtt-broker/configuration#shared-subscriptions).

> [!WARNING]
>
> **Agents are not replicated.** An agent (`DEFINE AGENT`) exists only on the node where you defined it. It is not copied to the other nodes, does not move when a node fails, and a `-removeAgent` on one node does not remove it from the others. Define an agent on every node that should run it. The LLM Connector an agent uses is an ordinary Connector and is replicated.

> [!WARNING]
>
> **Agents inside a Thing.** Currently:
>
> * The leader deploys a Thing (`-addThing`). Its definition and its connectors, models, actions, rules, and panels replicate to every node.
> * A `DEFINE AGENT` inside the Thing is not replicated. It currently runs only on the node that was leader when the Thing was deployed, which is not necessarily the node that received the command.
> * The agent's conversation memory stays on that node and is never replicated.
> * The agent does not move on failover. If its node is down, the agent is unavailable until that node returns.
> * On the other nodes the Thing still lists the agent, but the agent is not running there, so Thing health on those nodes may show it as not ok. Its status topics are visible on every node.

***

## Next Steps

> **[MQTT State Durability](/latest/mqtt-broker/durability)**
>
> Keep sessions, queued messages, and retained messages across restarts on every node.

> **[Operational Endpoints](/latest/mqtt-broker/operational-endpoints)**
>
> Monitor each node with /cluster, /info, and Prometheus metrics.


# Broker Commands
Source: https://docs.coreflux.org/latest/mqtt-broker/commands

Publish commands to the Coreflux MQTT broker at runtime and parse the JSON replies

## Control the Broker Over MQTT

Instead of editing files and restarting, you publish a command string to a system topic and the broker applies the change immediately: users, LoT entities, Connectors, projects, secrets, and more.

> [!TIP]
>
> **Like a remote control for the broker.** You send a message to a reserved topic; the broker answers on a matching output topic. No SSH and no restart.

### When to use broker commands

* Deploy or remove Actions, Models, Connectors, and Rules without downtime
* Run an Action on demand, or inspect what is loaded
* Manage users, groups, environment variables, and secrets
* Load LoT notebook projects and check their status
* Drive the same verbs from [Coreflux HUB Command Console](/hub/system/command-console) or any MQTT client
* Mint, list, and revoke [MCP Server](/latest/mqtt-broker/mcp-server) bearer tokens

On a [cluster](/latest/mqtt-broker/clustering) (beta), send a command that adds, changes, removes, or loads LoT (actions, models, connectors, rules, Python scripts, panels, Things, projects) to **any** node, once. A follower passes it to the leader, which commits it on a majority of the nodes, and every node applies it. The node that receives the command checks your permission. Other commands, such as users, agents, licenses, and certificates, run only on the node you are connected to. See [LoT in a cluster](/latest/mqtt-broker/clustering#lot-in-a-cluster).

***

Subscribe first, then publish. Replies are always JSON on a single output topic.

## Quick Start

**Deploy an Action**

Subscribe to `$SYS/Coreflux/Command/Output`, then publish the command. Use QoS 1 on both the command and the output subscription.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION Heartbeat ON EVERY 10 SECONDS DO PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

The broker replies with a JSON envelope. `success` is `true` when the Action was registered:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "AddAction",
  "message": "Action 'Heartbeat' added successfully.",
  "entityType": "Action",
  "entityName": "Heartbeat",
  "data": {}
}
```

**List Connectors**

List commands put the structured result in `data`. `message` stays a short human summary. This example sends `-listConnectors`. The reply's `command` field stays `ListRoutes`, and `-listRoutes` remains a supported alias.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-listConnectors -requestId connectors-1
```

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "ListRoutes",
  "requestId": "connectors-1",
  "message": "Listed 1 connector(s).",
  "data": [
    {
      "name": "CloudBridge",
      "type": "MQTT_BRIDGE",
      "connection": "Connected",
      "health": "Green"
    }
  ]
}
```

**Correlate replies**

Every client shares `$SYS/Coreflux/Command/Output`. Pass `-requestId` so you can match the reply to the request you sent.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-listProjects -requestId demo-1
```

Read `requestId` on the envelope root. Omit the flag when you only have one command in flight.

## How Commands Work

| Role | Topic | Notes |
| - | - | - |
| **Publish commands** | `$SYS/Coreflux/Command` | UTF-8 plain string payload (not a JSON wrapper) |
| **Subscribe for replies** | `$SYS/Coreflux/Command/Output` | Always this topic — independent of flags in the command |

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-commandName <arguments...> [-requestId <correlation-id>]
```

| Flag | Required | Purpose |
| - | - | - |
| `-requestId` | No | Client correlation id; echoed as `requestId` in the JSON reply. Alias: `--request-id` |

Authorization uses the **MQTT session username** of the publishing client. Do not send `-requestUser` in the payload.

> [!WARNING]
>
> Replies always go to `$SYS/Coreflux/Command/Output`. Do not subscribe to `$SYS/Coreflux/CommandResponse`. Custom reply routing (`-bt`) and `$SYS/Coreflux/Cloud/Command` are not supported.

## Response Envelope

Every reply on `$SYS/Coreflux/Command/Output` is one JSON object. List and query payloads live in `data`. `data` is **always present**: `{}` when there is nothing structured to return, or `[]` for an empty list.

| Field | Type | Description |
| - | - | - |
| `success` | boolean | Whether the command itself succeeded |
| `command` | string | Command name (`AddRoute`, `ListProjects`, …). Unknown verbs keep the raw `-verb` form |
| `message` | string | Human-readable summary |
| `entityType` | string? | Entity kind for deploy, remove, and run commands |
| `entityName` | string? | Entity name when applicable |
| `requestId` | string? | Echo of `-requestId` when you sent one |
| `data` | object or array | Structured result. Always present |
| `errors` | object\[]? | Present when `success` is `false` |
| `warnings` | string\[]? | Non-fatal warnings (for example a project load that skipped one entity) |

### How to parse a reply

1. Parse the payload as JSON (always a single object).
2. Read `success`, `command`, and optional `requestId` from the root.
3. Read structured results from `data`.
4. Read human text from `message` and failures from `errors[]`.

### Error objects

| Field | Description |
| - | - |
| `message` | Error text for that entry |
| `line` / `column` | 1-based source location for LoT parse errors |
| `sourceLines` | Map of line number to source text |
| `suggestions` | Parser hints when available |

Parse failure example:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": false,
  "command": "AddAction",
  "message": "Unexpected token 'WITH' at line 4",
  "entityType": "Action",
  "entityName": "BadAction",
  "data": {},
  "errors": [
    {
      "message": "Unexpected token 'WITH' at line 4",
      "line": 4,
      "column": 12,
      "sourceLines": { "4": "DO PUBLISH TOPIC \"x\"" }
    }
  ]
}
```

### Global failures

**Permission denied** (command accepted at MQTT, then blocked by RBAC):

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": false,
  "command": "AddRoute",
  "message": "Permission denied: You are not allowed to execute -addRoute.",
  "data": {},
  "errors": [
    { "message": "Permission denied: You are not allowed to execute -addRoute." }
  ]
}
```

The reply currently names the Route form of the command, even when the client sent `-addConnector`.

**Unknown command:**

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": false,
  "command": "-notARealCommand",
  "message": "Unknown command: -notARealCommand",
  "data": {},
  "errors": [{ "message": "Unknown command: -notARealCommand" }]
}
```

If the session lacks `CommandCall`, the publish to `$SYS/Coreflux/Command` can be rejected before any Output message. Handle both MQTT-level denial and JSON `success: false`. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac).

***

## Command Index

Most verbs also accept a dashed alias (`-addConnector` / `--add-connector`). The table lists the MQTT form you publish. Each Connector command also has a Route spelling (`-addConnector` and `-addRoute` run the same command), kept as an alias. See [Connector command spellings](#connector-command-spellings).

| Area | Commands |
| - | - |
| **Users** | `-addUser`, `-removeUser`, `-changeUserPassword`, `-changeUserSettings`, `-addUserToGroup`, `-removeUserFromGroup`, `-listUserGroups` |
| **Rules** | `-addRule`, `-removeRule`, `-removeAllProjectRules`, `-restoreRules` |
| **Models** | `-addModel`, `-removeModel`, `-removeAllModels` |
| **Actions** | `-addAction`, `-removeAction`, `-runAction`, `-removeAllActions`, `-actionTrace`, `-disableAction`, `-enableAction` |
| **Connectors** | `-addConnector` (`-addRoute`), `-removeConnector` (`-removeRoute`), `-removeAllConnectors` (`-removeAllRoutes`), `-listConnectors` (`-listRoutes`), `-connectorCode` (`-routeCode`), `-checkConnectorConnection` (`-checkRouteConnection`), `-connectorCertificates` (`-routeCertificates`), `-disableConnector` (`-disableRoute`), `-enableConnector` (`-enableRoute`), `-listTemplates`, `-connectionStatus`, `-discoverAIProviders` |
| **Agents** | `-addAgent`, `-removeAgent`, `-listAgents`, `-disableAgent`, `-enableAgent` |
| **Things** | `-addThing` (`--dryRun`), `-removeThing`, `-listThings` |
| **Diagnostics** | `-lotDiagnostic`, `-getPendingStatus` |
| **Python** | `-addPython`, `-removePython`, `-installPythonPackage`, `-listPythonPackages`, `-removeAllPythonScripts` |
| **Panels** | `-addPanel` (`-addVisu`), `-removePanel`, `-listPanels`, `-panelCode`, `-updateVisuState`, `-addVisuFile`, `-refreshVisu`, `-addTheme`, `-removeTheme`, `-removeAllThemes`, `-listThemes` |
| **Projects** | `-addProject`, `-removeProject`, `-loadProject`, `-unloadProject`, `-listProjects`, `-listEntities`, `-getProject`, `-duplicateProject`, `-projectCheckout`, `-projectPull`, `-projectPush`, `-projectStatus`, `-projectManifest` |
| **Env & secrets** | `-setEnv`, `-removeEnv`, `-listEnv`, `-setSecret`, `-removeSecret`, `-listSecrets` |
| **MCP tokens** | `-createMcpToken`, `-listMcpTokens`, `-revokeMcpToken` |
| **License** | `-activateLicense`, `-loadLicense`, `-refreshLicense`, `-enroll` |
| **Audit** | `-auditStatus`, `-auditQuery`, `-auditFilter`, `-decryptAudit`, `-auditExport` |
| **Certificates** | `-brokerCertificates` (admin only) |
| **System** | `-addTraceLog`, `-listTraceLogs`, `-removeTraceLog`, `-removeAllTraceLogs`, `-updateData`, `-h` |

`-updateData` refreshes broker `$SYS` statistics and **does not** publish a reply on `$SYS/Coreflux/Command/Output`.

***

## User Management

Create a user, then assign groups for `USER IN GROUP` in LoT Rules. Group commands require user-management permission on the **authenticated MQTT session**. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac).

These commands manage the local user store. An [OIDC access token](/latest/mqtt-broker/oidc-authentication) is not a local user: there is no command to create one, and `-listUsers` does not show token sessions.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addUser operator SecurePass123!
-removeUser operator
-changeUserPassword operator NewSecurePass456!
-changeUserSettings alice AllowedUserManagement true
-addUserToGroup alice operators
-removeUserFromGroup alice operators
-listUserGroups alice
```

`-listUserGroups` returns `{ username, groups, count }` in `data`.

Permission flags for `-changeUserSettings` include `AllowedUserManagement`, `AllowedSystemConfiguration`, and `AllowedLogManagement`.

***

## Rules

Rules define access control. See [Rules Overview](/latest/lot-language/rules/overview), [Rules Syntax](/latest/lot-language/rules/syntax), and [RBAC](/latest/lot-language/rules/rbac). **Lower priority number wins**. `-addRule` accepts priorities from `100` to `1 000 000` only; custom ACL rules require Growth or Enterprise.

> [!NOTE]
>
> Rules are LoT code and can also be deployed from a [LoT Notebook](/latest/quick-start/vscode) by running the cell that contains the definition.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addRule DEFINE RULE RestrictSensorPublish WITH PRIORITY 100 FOR Publish TO TOPIC "sensors/#"
    IF USER IN GROUP "operators" THEN
        ALLOW
    ELSE
        DENY
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removeRule RestrictSensorPublish
```

> [!NOTE]
>
> Locked built-in system rules cannot be removed. Seed catch-alls (`AllowPublishTopic` / `AllowSubscribeTopic` / `AllowConnect`) may be removed to switch that operation toward default-deny — except Connect, where removing `AllowConnect` without a replacement leaves CONNECT ungated. See [RBAC](/latest/lot-language/rules/rbac#seed-catch-alls).

`-restoreRules` puts `AllowPublishTopic`, `AllowSubscribeTopic`, and `AllowConnect` back to their shipped ALLOW definitions. Missing seeds are re-added; overrides of those names are reset; locked built-ins and your other custom rules are left alone. Requires `root` or `AllowedSystemConfiguration`. No arguments.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-restoreRules
```

`-removeAllProjectRules` removes permission rules **owned by the active project**. Built-in rules and operator-authored custom rules stay in place.

***

## Models

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addModel DEFINE MODEL TemperatureSensor
    WITH TOPIC "sensors/+/temperature"
    ADD FIELD temperature WITH TYPE Float
    ADD FIELD unit WITH TYPE String
    ADD FIELD timestamp WITH TYPE DateTime
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removeModel TemperatureSensor
-removeAllModels
```

> [!WARNING]
>
> `-removeAllModels` removes every Model on the broker.

***

## Actions

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION Heartbeat
    ON EVERY 10 SECONDS DO
        PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION EchoMessage
    ON TOPIC "input/data" DO
        PUBLISH TOPIC "output/echo" WITH PAYLOAD
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removeAction Heartbeat
-removeAllActions
```

### Run an Action on demand

`-runAction` runs an Action immediately, regardless of its trigger.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-runAction Heartbeat
```

Success means the command **dispatched** the Action. For this form, a failure inside the Action body is not in the command reply — watch `$SYS/Coreflux/Actions/<name>/Trace` (if tracing is on) or `$SYS/Coreflux/Actions/<name>/Error`. `data.traceId` identifies this execution.

**Callable Actions** (those that declare `INPUT`) accept a JSON object of parameters:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-runAction SetZoneSetpoint {"zone":"f2-north","target":21.5}
```

The broker rejects a payload on a non-callable Action, invalid JSON, or a non-object JSON value.

**Topic-triggered Actions** (`ON TOPIC` / `ON CHANGE`) accept trigger context instead of `INPUT` bindings when the JSON object contains a `topic` key. The Action runs **synchronously**; `data` includes `status`, `published`, `durationMs`, `error`, and `traceId`. You do not need to arm `-actionTrace` for this form.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-runAction TemperatureMonitor {"topic":"sensors/zone1/temperature","payload":{"value":72}}
```

| `data.status` | Meaning |
| - | - |
| `success` | Finished; `published` lists messages it emitted |
| `error` | The Action threw; `error` has the message. Envelope `success` stays `true` — the *command* worked |
| `no_trace_captured` | Ran, but no trace was produced |

The `topic` value must match the Action's trigger pattern (including wildcards). This `topic` form does not apply to callables — their JSON object is always `INPUT` bindings, even if it contains a `topic` key.

See [Callable ACTIONs](/latest/lot-language/actions/callable-actions) for `INPUT` / `CALL ACTION`.

### Action tracing

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-actionTrace Heartbeat
-actionTrace all
-actionTrace status
-actionTrace off
-actionTrace remove Heartbeat
```

Traces publish to `$SYS/Coreflux/Actions/<name>/Trace`. Arming auto-expires; `data.expiresUtc` tells you when. A `{ "topic": … }` `-runAction` arms tracing for that one call and disarms afterward, unless a live `-actionTrace` session was already on.

***

## Agents

Agents are their own LoT entity. `-addConnector` refuses a `DEFINE AGENT` block, and `-listConnectors` does not include agents. See [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addAgent DEFINE AGENT Planner
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    ADD TOOL "read_lot"
-removeAgent Planner
-listAgents
```

`-addAgent` on a name that already exists updates that agent and keeps its conversations. `-removeAgent` cancels running tasks and forgets session memory. `-removeConnector` refuses to remove a `TYPE LLM` connector an agent still uses.

`-addAgent` requires `AgentManagementCreation`. `-removeAgent` requires `AgentManagementRemove`. `root`, `admin`, and `AllowedSystemConfiguration` pass those gates, as they do for connectors.

***

## Connectors

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addConnector DEFINE CONNECTOR CloudBridge WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloudprovider.com"
        WITH BROKER_PORT '8883'
        WITH USE_TLS true
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "factory1/sensors/#"
        WITH DIRECTION "out"
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removeConnector CloudBridge
-removeAllConnectors
-listConnectors
-connectorCode POSTGRESQL
-listTemplates
-checkConnectorConnection CloudBridge
-connectionStatus
```

### Connector command spellings

Each Route command has a Connector spelling. The Route names (`-addRoute`, `-listRoutes`, and the rest) stay as aliases. Both forms run the same command, and the reply's `command` field keeps the Route name (`AddRoute`, `ListRoutes`, …), so scripts that check it keep working.

| Route spelling | Connector spelling | Reply `command` |
| - | - | - |
| `-addRoute` / `--add-route` | `-addConnector` / `--add-connector` | `AddRoute` |
| `-removeRoute` / `--remove-route` | `-removeConnector` / `--remove-connector` | `RemoveRoute` |
| `-removeAllRoutes` / `--remove-all-routes` | `-removeAllConnectors` / `--remove-all-connectors` | `RemoveAllRoutes` |
| `-listRoutes` / `--list-routes` | `-listConnectors` / `--list-connectors` | `ListRoutes` |
| `-routeCode` / `--route-code` | `-connectorCode` / `--connector-code` | `GetRouteTemplate` |
| `-checkRouteConnection` / `--check-route-connection` | `-checkConnectorConnection` / `--check-connector-connection` | `CheckRouteConnection` |
| `-routeCertificates` / `--route-certificates` | `-connectorCertificates` / `--connector-certificates` | `RouteCertificates` |

`-addConnector` takes the same body as `-addRoute`, written with either `DEFINE CONNECTOR` or `DEFINE ROUTE`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addConnector DEFINE CONNECTOR CloudBridge WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloudprovider.com"
        WITH BROKER_PORT '8883'
        WITH USE_TLS true
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "sensors/#"
        WITH DESTINATION_TOPIC "factory1/sensors/#"
        WITH DIRECTION "out"
```

When you start the broker with a Connectors file on the command line, use `--lot-connectors <path>`. `-lotrt` and `--lot-routes` remain supported aliases.

`-listConnectors` places entries in `data` (`name`, `type`, `connection`, `health`). Unmonitored connectors report `"Unknown"` for connection and health.

`-checkConnectorConnection` tests the named Connector. Details such as `routeType` and `connectionTime` are in `data`. What “connected” means depends on the Connector type — see the Connector page (for example [OPC UA Client](/latest/lot-language/routes/industrial/opcua-client) or [Modbus TCP Server](/latest/lot-language/routes/industrial/modbus-tcp-server)).

`-connectorCode` returns template LoT for that Connector type, or for a [REST API app](/latest/lot-language/routes/rest-api-routes#rest-api-app-templates) by its app code, in `data`. `-listTemplates` lists available templates.

`-connectorCertificates` manages PKI for Connectors that support certificate stores (OPC UA client and server). The argument is `cert64:` plus base64 of a minified JSON request (`stores`, `list`, `inspect`, `trust`, `delete`, `export`, `import`). Operation details are in `data`. See [OPC UA Client — Certificate Management](/latest/lot-language/routes/industrial/opcua-client#certificate-management).

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-connectorCertificates cert64:<base64-of-json-request>
```

`-discoverAIProviders` probes configured LLM providers for reachability and models. API keys and host URLs come from secrets and environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OLLAMA_HOST`). An optional JSON object can override those values for the probe. Results are also published retained on `$SYS/Coreflux/AI/Providers`.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-discoverAIProviders
```

***

## Disable and Enable

These commands switch an action, connector, or agent off or on without deleting it. Each one redeploys the stored definition with a `DISABLE true` line added right after the `DEFINE` line, or removed, through the normal add path. An entity already in the requested state is left alone and the command still succeeds.

| Command | Entity | MCP tool |
| - | - | - |
| `-disableAction <name>` / `-enableAction <name>` | Action | `disable_action` / `enable_action` |
| `-disableConnector <name>` / `-enableConnector <name>` (aliases `-disableRoute` / `-enableRoute`) | Connector | `disable_route` / `enable_route` |
| `-disableAgent <name>` / `-enableAgent <name>` | Agent | `disable_agent` / `enable_agent` |

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-disableConnector PlantHistorian
-enableConnector PlantHistorian
```

They need the same permission as adding that entity (`ActionManagementCreation`, `ConnectorManagementCreation`, `AgentManagementCreation`). `RouteManagementCreation` remains a supported alias of `ConnectorManagementCreation`. With a live project, the change is written back to its notebook cell. A connector, action, or agent that belongs to a Thing is refused: change the Thing instead. `-disableConnector` refuses a `TYPE LLM` connector that agents still use.

What a disabled entity does: [Actions](/latest/lot-language/actions/syntax#disable-an-action), [Connectors](/latest/lot-language/routes/overview#disable-a-connector), [Agents](/latest/lot-language/agents/syntax#disable-an-agent).

***

## Things

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addThing --dryRun DEFINE THING TEMPLATE TankLevel …
-addThing DEFINE THING TEMPLATE TankLevel … DEFINE THING TankFarm …
-listThings
-removeThing TankFarm
```

| Command | What it does | Permission |
| - | - | - |
| `-addThing [--dryRun] <DEFINE THING …>` | Deploys every Thing in the payload as one unit. `--dryRun` returns the plan and each child's expanded code, and changes nothing. `data` holds `things`, `affectedRoots`, and the per-root `plan` | `ThingManagementCreation` |
| `-removeThing <name>` | Removes a root and its children in reverse order, or an unused template. A template still in use is refused | `ThingManagementRemove` |
| `-listThings` | Lists every Thing in `data`: `name`, `kind`, `template`, `uses`, `usedBy`, `childCount`, `project` | `CommandCall` |

The children a Thing creates are read-only: `-addAction`, `-removeConnector`, and the other per-entity commands refuse them and name the owning Thing. `-removeAllActions`, `-removeAllModels`, and `-removeAllConnectors` skip them. See [LoT THING](/latest/lot-language/things/overview).

***

## Diagnostics

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-lotDiagnostic true
-lotDiagnostic false
-getPendingStatus
```

`-lotDiagnostic` turns global LoT diagnostic tracing on or off. The only argument is `true` or `false`. Anything else returns `Invalid diagnostic value`.

***

## Environment Variables and Secrets

See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for storage, substitution in LoT, and security notes.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-setEnv DB_HOST=postgres.example.com
-removeEnv OLD_CONFIG
-listEnv
-setSecret DB_PASSWORD=my_secure_password
-removeSecret OLD_API_KEY
-listSecrets
```

> [!WARNING]
>
> **Quote values that contain `//`, a space, or `#`.** The command is cleaned before it runs. Outside double quotes, `//`, `/*` and `-- ` start a comment and cut off the rest of the line, and a space ends the value. Wrap the value in double quotes: `-setEnv API_URL="https://api.example.com/v1"`. The quotes are removed before the value is stored. The same rule applies to `-setSecret`.

`-listEnv` returns name/value pairs in `data`. `-listSecrets` returns **names only** — secret values never appear in command output.

***

## Python Integration

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addPython Calculator
# Script Name: Calculator

def add(a, b):
    return a + b
```

> [!NOTE]
>
> Python scripts must start with `# Script Name: YourScriptName`. That name is what you pass to `CALL PYTHON` from a LoT Action.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removePython Calculator
-installPythonPackage numpy
-listPythonPackages
-removeAllPythonScripts
```

***

## Panels and Themes

Deploy dashboards written as `DEFINE PANEL`. `-addPanel` and `-addVisu` are the same command. See [Defining Panels](/latest/lot-language/panels/defining-panels).

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addPanel DEFINE PANEL LineOverview
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line Overview"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "Temperature" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        BIND VALUE TO TOPIC "sensor/temperature"
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removePanel LineOverview
-listPanels
-panelCode LineOverview
-updateVisuState LineOverview PUBLISHED
-refreshVisu
```

`-updateVisuState` takes `DRAFT`, `PUBLISHED`, or `ARCHIVED`.

`-addVisuFile lot64:<base64>` deploys every `DEFINE PANEL` block from a `.lot` file encoded as base64.

Theme commands: `-addTheme` (full `DEFINE THEME` body), `-removeTheme`, `-listThemes`, `-removeAllThemes`.

`-listPanels` and `-listThemes` also publish catalog data on `$SYS/Coreflux/VoT/Panels/` and `$SYS/Coreflux/VoT/Themes/`.

***

## Projects

A project is a folder of `.lotnb` files under the broker data path. See [Project organization](/latest/lot-language/usage-patterns/project-organization).

> [!NOTE]
>
> `-loadProject` and `-unloadProject` remove only entities the broker attributes to that project. Actions, Models, Connectors, Python scripts, and panels you added with `-addAction` (and similar) while no project was active stay running.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-listProjects
-addProject "https://git.example.com/factory-iot.git" main
-addProject zip64:<base64>
-loadProject factory-iot
-unloadProject
-removeProject factory-iot
-listEntities
-getProject factory-iot
-duplicateProject factory-iot factory-iot-copy
-projectCheckout factory-iot main
-projectPull factory-iot
-projectPush factory-iot
-projectStatus factory-iot
-projectManifest factory-iot
```

Names may contain spaces or hyphens (`-loadProject Traceability System` or `-loadProject "Traceability System"`). `/` is not allowed.

Quote a git URL so the address stays one argument. The branch name is the next argument: `-addProject "https://git.example.com/factory-iot.git" main`.

`-listProjects` returns `name`, `active`, git metadata, and related fields in `data`.

`-loadProject` returns `{ project, entities, counts }` in `data`. `counts.actions` lists **user-defined** Actions only (not Connector-internal event Actions). Built-in permission rules are omitted. Per-entity failures appear in `warnings[]`; `success` can still be `true` when the load finished with partial errors.

The last loaded project is remembered across restarts unless you pass `--project` at startup. See [Startup Options](/latest/mqtt-broker/startup-options#loading-a-project-at-startup).

`-unloadProject` tears down owned runtime entities and returns the broker to standalone mode. The folder stays on disk. `-removeProject` also deletes the folder.

`-getProject` exports a zip (base64) on `$SYS/Coreflux/Projects/<name>/download`.

`-projectManifest` returns hashes of stored files and declared entities so clients can compare a working copy without downloading the zip. The same JSON is published retained on `$SYS/Coreflux/Projects/{name}/manifest`.

***

## MCP Tokens

Bearer tokens for the [MCP Server](/latest/mqtt-broker/mcp-server). These verbs are operator-only (`McpTokenManagement`) and are **not** advertised as MCP tools.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-createMcpToken operator cursor-local
-listMcpTokens
-listMcpTokens operator
-revokeMcpToken cursor-local
```

`-createMcpToken <username> <token-name> [ttlDays]` returns the plaintext **once** in `data.token`. The username must already exist; tool calls run as that user. Token names cannot contain whitespace. `-listMcpTokens` returns metadata in `data.tokens` — never the secret.

MQTT replies always land on `$SYS/Coreflux/Command/Output`. That topic's default audience is wider than `McpTokenManagement`. Prefer the broker console or the [HUB MCP tab](/hub/system/configuration#mcp) when you need the plaintext off that lane.

***

## License

Licenses are signed tokens. Register at [portal.coreflux.org](https://portal.coreflux.org) for a license — including a **30-day Growth-type** trial — and manage your fleet of brokers there. Full operator guide: [Licensing and Enrollment](/latest/mqtt-broker/licensing).

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-activateLicense CFLX-XXXX-XXXX-XXXX
-loadLicense /path/to/license.jws
-loadLicense eyJhbGciOiJFUzI1NiIsInR5cCI6IkNGTFhMSUMi.….<payload>.<signature>
-refreshLicense
-enroll et_…
```

| Command | What it does |
| - | - |
| `-activateLicense <code>` | Exchanges a `CFLX-…` activation code for a lease and applies the plan immediately. Requires `SystemConfiguration`. No restart. |
| `-loadLicense <jws-or-path>` | Verifies a signed license — compact JWS text, or a path on the broker host — and stages `config/license.jws`. |
| `-refreshLicense` | Forces one online lease refresh instead of waiting for the 24-hour timer. Refused when the broker holds no lease. |
| `-enroll <et_…>` | Stages a single-use enrollment token. The token is never echoed in the reply; the exchange runs in the background. |

`-loadLicense` treats the argument as the license itself when it has the shape of a compact JWS, and as a filesystem path otherwise. That is how Coreflux HUB installs an offline license without writing a file on the broker host.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "LoadLicense",
  "message": "Signed license verified and stored at <config>/license.jws",
  "data": {}
}
```

***

## Broker Certificates

`-brokerCertificates` manages the broker's TLS server certificate, its Root CA, and the mTLS client trust store (`ClientCertificateSourcePath`). It is what [HUB Certificates](/hub/system/certificates) uses. It needs administrator rights (`AllowedSystemConfiguration`), and it is not exposed to the MCP server or to agents, because requests carry certificate bytes and passphrases. Changes are audit-logged.

The argument is `cert64:` plus base64 of a JSON request with an `op` and an optional `requestId` that is echoed back.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-brokerCertificates cert64:<base64-of-json-request>
```

| `op` | Fields | Result |
| - | - | - |
| `overview` | — | Trust store settings, server certificate, Root CA, TLS port |
| `list` | — | Path status, threshold, and every file in the storage path and `revoked/` |
| `import` | `fileName`, `dataB64`, `password` (PKCS#12) | Stores and trusts the file. Private keys in PKCS#12 or combined PEM uploads are discarded. 10 MB limit |
| `revoke` | `fileName` | Moves the file to `revoked/`. New connections that present it are rejected immediately |
| `export` | `fileName`, `revoked` (optional) | `fileName` and `dataB64` of a certificate file. Files with private keys and symbolic links are refused |
| `setSettings` | `storagePath`, `resetPath`, `expiryThresholdDays`, `clientCertificationValidation`, `checkCertificateChainValidation` (all optional) | Saves the settings and returns the overview. `clientCertificationValidation` fully applies after a restart |
| `replaceServer` | `fileName`, `dataB64`, `keyB64` (optional), `password` (optional) | Replaces the server certificate with a timestamped `.bak-` copy of the old files. Hot-swapped when TLS is already running, otherwise a restart is needed |
| `replaceRootCa` | `fileName`, `dataB64` | Replaces the Root CA with a timestamped `.bak-` copy and applies it to chain validation |
| `exportServer` / `exportRootCa` | — | The public certificate as PEM |

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "op": "revoke", "requestId": "r1", "fileName": "plc-line-a.pem" }
```

The reply's `message` is JSON: `requestId`, `op`, `success`, a human `message`, and `data`. Mutating ops also republish [`$SYS/Coreflux/Certificates/Summary`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary).

## Audit

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-auditStatus
-auditQuery 2026-08-26
-auditQuery 2026-08-26 -auditFilter operationName=UserLogin
-decryptAudit 2026-08-26
```

`-auditQuery` takes a date (`YYYY-MM-DD`). Add `-auditFilter field=value` in the same payload to narrow results. `-decryptAudit` decrypts that day's log; pair with `-auditExport <path>` to write JSON to a file. Decryption requires the audit key configured on the broker (`COREFLUX_AUDIT_KEY`).

***

## Trace Logging

Capture broker log lines and republish matches to an MQTT topic.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addTraceLog level=Information,lifetime=3600,messageContains=sensor,topic=logs/sensors
-listTraceLogs
-removeTraceLog logs/sensors
-removeAllTraceLogs
```

| Parameter | Description |
| - | - |
| `level` | `Debug`, `Information`, `Warning`, `Error`, `Fatal` |
| `lifetime` | Seconds until the trace point expires |
| `messageContains` | Only logs whose message contains this substring |
| `topic` | MQTT topic where matching logs are published |

***

## Command Authorization

Not every user can run every command. Management gates such as `CommandCall` and per-entity creation flags are defined in LoT Rules. See [Rules overview](/latest/lot-language/rules/overview) and [RBAC](/latest/lot-language/rules/rbac).

> [!WARNING]
>
> Configure access control before any untrusted client can publish to `$SYS/Coreflux/Command`.

***

## Next Steps

> **[System (\$SYS) Topics](/latest/mqtt-broker/sys-topics)**
>
> Subscribe to command output, entity code, and broker telemetry.

> **[Command Console](/hub/system/command-console)**
>
> Run the same commands from Coreflux HUB without a separate MQTT client.


# Broker Configuration
Source: https://docs.coreflux.org/latest/mqtt-broker/configuration

Complete guide to configuring the Coreflux MQTT Broker - ports, security, TLS, and deployment options

Configure your Coreflux MQTT Broker to match your deployment requirements. This guide covers network settings, security options, TLS certificates, and deployment-specific configurations.

> [!NOTE]
>
> Most configuration changes require a broker restart to take effect. Plan those updates during a maintenance window. Updated bytes in the TLS certificate files are the exception: the broker re-reads them on a timer and uses them for new handshakes. See [TLS Server Certificate](#tls-server-certificate).

> [!NOTE]
>
> To keep retained messages, persistent sessions, and queued QoS 1/2 across restarts, configure the separate [`Durability`](/latest/mqtt-broker/durability) section (or `COREFLUX_DURABILITY_*` environment variables).

> [!NOTE]
>
> To expose the broker as an MCP server for AI clients, configure the separate [`Mcp`](/latest/mqtt-broker/mcp-server) section (or `COREFLUX_MCP_*` environment variables). `TYPE MCP_SERVER` was removed — this is not a LoT connector.

> [!NOTE]
>
> To accept an OIDC access token as the MQTT CONNECT password, configure the [`Oidc`](/latest/mqtt-broker/oidc-authentication) object in this file. There is no `COREFLUX_OIDC_*` variable. Enabling it forces `AnonymousLogin` off.

***

## Configuration Overview

The broker configuration is stored as a JSON object. The structure below shows every supported property (the file is encrypted on disk; this is an illustrative representation):

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Name": "Coreflux DataHub",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "AnonymousLogin": false,
  "CleanSession": false,
  "SessionExpiryInterval": 0,
  "SharedSubscriptions": false,
  "MaxPendingMessagesPerClient": 20000,
  "FullDebugLog": false,
  "CloudLogging": false,
  "ResendRetainTopics": false,
  "ClientCertificationValidation": false,
  "CheckCertificateChainValidation": false,
  "CheckCertificateRevokationList": false,
  "ServerCertificatePath": "",
  "ServerCertificateKeyPath": "",
  "ServerCertificatePassword": "",
  "ServerCertificateReloadIntervalSeconds": 3600,
  "RootCACertificatePath": "",
  "ClientCertificateSourcePath": "",
  "ClientCertificateRevocationListPath": "",
  "ProjectPath": "",
  "UsersFile": "",
  "EnvsPath": "",
  "SecretsPath": ""
}
```

### First-Run Defaults

When no config file exists, the broker creates one with these values:

| Property | Default |
| - | - |
| `Name` | `"Coreflux DataHub"` |
| `Port` | `1883` |
| `TlsPort` | `8883` |
| `WebsocketPort` | `5000` |
| `WebsocketPortTls` | `443` |
| Bind IPs (MQTT / TLS / WebSocket) | `"0.0.0.0"` (all interfaces) |
| `AnonymousLogin` | `true` |
| `FullDebugLog` | `false` |
| `ClientCertificationValidation` | `false` |
| `MaxPendingMessagesPerClient` | `20000` |
| `CleanSession` | `false` |
| `SessionExpiryInterval` | `0` |
| `SharedSubscriptions` | `false` |

> [!WARNING]
>
> On a brand-new install the broker creates the config with `AnonymousLogin: true`. Set it to `false` and configure user credentials before exposing the broker to any untrusted network.

***

## Network Settings

### Ports

The broker listens on multiple ports for different connection types:

**Port** `integer` (default: 1883)

Standard MQTT port for unencrypted connections. This is the default port used by most MQTT clients.

**TlsPort** `integer` (default: 8883)

MQTT port for TLS-encrypted connections. Requires valid server certificate configuration.

**WebsocketPort** `integer` (default: 5000)

Port for MQTT over WebSocket connections. Used by browser-based clients and applications that cannot use raw TCP.

**WebsocketPortTls** `integer` (default: 443)

Port for MQTT over WebSocket with TLS. The default is `443` on the broker host. A port below 1024 needs permission to bind it on the broker host. Linux APT and DNF packages grant that permission. See [Ports below 1024](/latest/mqtt-broker/startup-options#ports-below-1024).

> [!WARNING]
>
> All ports must be between 1 and 65535. Ensure chosen ports are not already in use by other services.

### IP Bindings

Control which network interfaces the broker listens on:

**BindIPForMQTT** `string`

IP address to bind for standard MQTT connections. Use `0.0.0.0` to listen on all interfaces, or a specific IP to restrict access.

**BindIPForMQTTwithTls** `string`

IP address to bind for TLS-encrypted MQTT connections.

**BindIpForWebSockets** `string`

IP address to bind for WebSocket connections.

**BindIpForWebSocketsTls** `string`

IP address to bind for WebSocket connections with TLS.

#### Example: Restrict to Local Network

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "BindIPForMQTT": "192.168.1.100",
  "BindIPForMQTTwithTls": "192.168.1.100",
  "BindIpForWebSockets": "192.168.1.100",
  "BindIpForWebSocketsTls": "192.168.1.100"
}
```

#### Example: Listen on All Interfaces

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0"
}
```

***

## Security Settings

### Authentication

**AnonymousLogin** `boolean` (default: true (first run))

When `true`, clients may connect **without** a valid username/password, and unknown usernames are treated as anonymous. When `false`, only registered users in the users store can connect.

The class default is `false`, but on a brand-new install the broker writes the first-run config with `AnonymousLogin: true`. Enforced at runtime in `ValidateConnectionAsync`, which rejects unauthenticated connects when `false` and the user is not found.

> [!WARNING]
>
> Never leave `AnonymousLogin` enabled in production environments. Always require authentication for broker access.

When [`Oidc.Enabled`](/latest/mqtt-broker/oidc-authentication) is true, the broker forces `AnonymousLogin` off at startup. Passwords that are access tokens are checked with the identity provider. Any other password is still checked against the user store.

### TLS Server Certificate

Configure TLS encryption for secure client connections:

**ServerCertificatePath** `string`

Path to the server certificate file (PEM or PFX format). Required to enable the TLS listeners — MQTTS and WSS endpoints are only started when a server certificate is loaded successfully. If set but the file is missing, a warning is logged and the broker may still start without TLS.

The broker re-reads this file (and `ServerCertificateKeyPath`, when set) on the interval below. A renewed certificate is used for **new** MQTTS and WSS handshakes. Clients that are already connected stay on the certificate they negotiated.

**ServerCertificateKeyPath** `string`

Path to the **private key** file when the certificate and key are in separate PEM files. Leave empty if the key is embedded in the certificate file. File contents are re-read on the same interval as the certificate.

**ServerCertificatePassword** `string`

Password for an encrypted private key or PFX bundle. If `ServerCertificatePath` is set but this is empty, a warning is logged at startup. `$SYS/Coreflux/Config` shows it as `********`. Publishing that mask back to `$SYS/Coreflux/Config/New` keeps the stored password.

You need a password only when the PEM key is encrypted. cert-manager writes an unencrypted `tls.key` by default, so leave this empty for that key. A password set beside an unencrypted key does not block loading.

**ServerCertificateReloadIntervalSeconds** `integer (seconds)` (default: 3600)

How often the broker checks `ServerCertificatePath` and `ServerCertificateKeyPath` for new file contents. Default `3600` (one hour). Set `0` to disable reloading.

When the contents change, the next MQTTS or WSS handshake uses the new certificate. Existing sessions stay connected. The broker compares file contents, so a timestamp change with the same bytes does not swap the certificate. A detected change is read again after one second so a file that is still being written is not loaded. If the new files fail to load, the previous certificate stays in use.

The first check runs one full interval after startup. Changing this value, the certificate **paths**, listener ports, or mTLS mode still requires a broker restart.

Allowed values are `0` or a positive number of seconds, up to `4294966` (about 49.7 days).

> [!NOTE]
>
> Keep the reload interval shorter than your certificate renewal margin. With the default of one hour, a renewed file can wait up to an hour before new handshakes pick it up. cert-manager renews at `renewBefore`, which for a typical 90-day certificate is days ahead of expiry, so the default sits inside that margin. Use a shorter interval (for example `60` to `300`) for short-lived certificates. Each check is two file reads and a hash.

> [!WARNING]
>
> Do not mount the certificate with `subPath`. A `subPath` mount captures the file at mount time and never updates when the Secret changes, so the broker never sees a renewal. Mount the Secret as a directory and point `ServerCertificatePath` at a file inside it.

**RootCACertificatePath** `string`

Path to the root CA certificate for certificate chain validation.

#### Example: TLS Configuration

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "your-certificate-password",
  "ServerCertificateReloadIntervalSeconds": 3600,
  "RootCACertificatePath": "/certs/ca.crt"
}
```

### Mutual TLS (mTLS)

For environments requiring client certificate authentication:

**ClientCertificateSourcePath** `string`

Folder of trusted client certificates (the mTLS trust store). The broker loads every `.pem`, `.crt`, `.cer`, `.der`, and unprotected `.p12`/`.pfx` file in it (not recursive). Certificates in its `revoked/` sub-folder are rejected. Empty means the default trust store under the broker data directory: `$COREFLUX_DATA_PATH/certs`, else `$CONFIG_PATH/certs`. That is `/etc/project/certs` in the Docker and Kubernetes images and `/var/lib/coreflux/certs` for apt/dnf packages; with neither variable set it is `/var/lib/coreflux/certs` on Linux and macOS, and `C:\ProgramData\Coreflux\certs` on Windows.

The broker creates the folder at startup if it is missing. If it can't (read-only, or not owned by the broker user), the broker starts with an empty trust store and the HUB shows the path as **Unavailable**. In containers, keep the default so certificates live on the `/etc/project` volume; a custom path must be on a writable, persisted volume owned by UID/GID `10001`.

When you set it from the HUB or with `-brokerCertificates`, the path must be absolute, outside system folders and the server certificate's folder, and, on Linux and macOS, under an allowed root (`/var/lib`, `/opt`, `/srv`, `/data`, `/mnt`, `/media`, `/home`, `/Users`, temp folders, or the `COREFLUX_DATA_PATH` / `CONFIG_PATH` folders). Extend the roots with `COREFLUX_CERT_STORAGE_ROOTS`. Symbolic links are resolved before the check.

A subfolder of `CONFIG_PATH` is allowed even under a system folder, so `/etc/project/certs` works in Docker. Use a `certs` subfolder on the project volume. The `CONFIG_PATH` folder itself is refused, and so is anything under `/etc` when `CONFIG_PATH` is `/etc`. Uploads through the HUB or `import` accept certificates only (`.crt`, `.pem`, `.cer`, `.der`, `.p12`, `.pfx`); private keys and CSRs are refused. See [HUB Certificates](/hub/system/certificates#trust-store-settings).

**CertificateExpiryThresholdDays** `integer (days)` (default: 30)

Days before expiry at which a client certificate, the server certificate, or the Root CA is reported as expiring on `$SYS/Coreflux/Certificates/Summary`. 1 to 365.

**ClientCertificationValidation** `boolean` (default: false)

Enable client certificate validation. When `true`, TLS connections **require** a client certificate (`ClientCertificateMode.RequireCertificate`). When `false`, client certificates are optional (`AllowCertificate`).

**ClientCertificateRevocationListPath** `string`

Path to the Certificate Revocation List (CRL) file for checking revoked certificates. When it is a folder, certificates in it are also treated as revoked, alongside the trust store's `revoked/` sub-folder.

**CheckCertificateRevokationList** `boolean` (default: false)

Enable CRL checking for client certificates.

**CheckCertificateChainValidation** `boolean` (default: false)

Enable full certificate chain validation for client certificates against `RootCACertificatePath`. When `false`, only the trusted list is checked. Changing it from the HUB takes effect immediately.

> [!TIP]
>
> In HUB 2.12, **System Config → Certificates** shows and edits these settings, replaces the server certificate and Root CA without a restart, and uploads or revokes client certificates. See [Certificates](/hub/system/certificates).

#### Example: mTLS Configuration

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "your-password",
  "ClientCertificateSourcePath": "/certs/trusted-clients/",
  "ClientCertificationValidation": true,
  "CheckCertificateChainValidation": true,
  "CheckCertificateRevokationList": true,
  "ClientCertificateRevocationListPath": "/certs/crl.pem"
}
```

> [!TIP]
>
> mTLS is recommended for high-security environments where you need to verify client identity at the transport layer, in addition to username/password authentication.

***

## Sessions and MQTT Behavior

**CleanSession** `boolean` (default: false)

**Broker policy** (not the client CONNECT flag).

* `false` — allow persistent sessions; honour each client's Clean Session / Clean Start flag.
* `true` — **require** clean sessions only; reject clients that connect with a persistent session (returns `NotAuthorized`).

Wired in via `ValidateConnectionAsync` (reject policy) and `WithPersistentSessions(!CleanSession)` at startup.

> [!NOTE]
>
> **Naming note:** `CleanSession = true` on the broker means "force clean sessions from clients", not "enable clean session".

> [!WARNING]
>
> **Clean Session enforcement** — per the MQTT 5.0 spec, a broker with `CleanSession = true` rejects any client connecting with `CleanSession = false` (persistent session). Make sure your clients connect with a clean session when this policy is enabled.

**SessionExpiryInterval** `integer (seconds)` (default: 0)

**MQTT 5 only** — maximum session lifetime cap, in seconds. Defines how long the broker holds a session after a client disconnects. (Previously hardcoded to 10 minutes; now configurable.)

* `0` — no cap; the client's CONNECT value is used as-is.
* `> 0` — reject persistent connects where the client requests **more** than this many seconds.
* `4294967295` (`uint.MaxValue`) — allow "never expire" client requests.

Applied in `MqttService.ApplyConfiguredSessionExpiry` during connection validation.

**MQTT 3.1.1:** ignored — persistence is controlled by `CleanSession` + `WithPersistentSessions` only.

**Important:** Coreflux has **no** server-builder API for session expiry. Clients that need MQTT 5 persistence must set `SessionExpiryInterval > 0` in their CONNECT packet.

### Shared subscriptions

**SharedSubscriptions** `boolean` (default: false)

Enables MQTT 5 shared subscriptions (`$share/{group}/{filter}`). Each message that matches the filter is delivered to **exactly one** member of that group — round-robin, preferring members that are connected. A client subscribed to the same filter without `$share` still receives every matching message.

Use this when a pool of workers should share the load on one topic. `$share/workers/jobs/#` and `$share/other/jobs/#` are separate groups, because the group is the full share filter.

* `false` (default) — a `$share/...` SUBSCRIBE is refused with reason code `0x9E` (Shared Subscriptions Not Supported). CONNACK reports Shared Subscription Available = `0`.
* `true` — share filters are accepted. CONNACK reports Shared Subscription Available = `1`. A malformed share filter (empty group name, `+` or `#` in the group name, or a missing filter) is refused with `0x8F` (Topic Filter Invalid).

`COREFLUX_MQTT_SHARED_SUBSCRIPTIONS` overrides this field: `1` or `true` enables shared subscriptions, `0` or `false` disables them. Restart the broker after changing the field or the variable.

In a cluster, in this version, each shared group is local to the broker host the members are connected to.

> [!NOTE]
>
> MQTT 3.1.1 clients can use the same `$share/` prefix once shared subscriptions are enabled. See [Shared subscriptions](/latest/mqtt-broker/protocol#shared-subscriptions).

**ResendRetainTopics** `boolean` (default: false)

When `true`, the broker maintains a buffer of retained messages and re-publishes them in specific situations: on new subscriptions (copies retained messages into an internal buffer) and via periodic `LogRetainedObjects` publishing. Useful when clients need retained messages re-delivered after reconnect or subscription changes.

***

## Performance and Back-Pressure

**MaxPendingMessagesPerClient** `integer` (default: 20000)

Maximum number of **pending outbound messages** queued per connected client before Coreflux drops messages (especially QoS 0). Protects broker memory when a client is slow to read.

Wired in via `WithMaxPendingMessagesPerClient` at startup.

> [!WARNING]
>
> `MaxPendingMessagesPerClient` must be between `1` and `100000`. A value outside this range prevents the broker from starting.

Per-connector wait-or-drop when a LoT connector cannot keep up is configured in LoT with `ADD CONNECTOR_CONFIG` (`ADD ROUTE_CONFIG` remains a supported alias). These environment variables set the broker-wide defaults (a restart is required to change them):

| Variable | Default | Effect |
| - | - | - |
| `COREFLUX_ROUTE_OVERLOAD_POLICY` | `balanced` | Default for `OVERLOAD_POLICY`: `lossless` (wait forever, never drop), `balanced` (wait up to the timeout, then drop the arriving message), or `realtime` (drop immediately). |
| `COREFLUX_ROUTE_CHANNEL_FULL_TIMEOUT_MS` | `50` | Default wait budget in milliseconds for `balanced`. |
| `COREFLUX_ROUTE_CHANNEL_CAPACITY` | `100000` | Shared ceiling on how many connector updates the broker holds at once. Values below `1024` are raised to `1024`. |

See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward) for the LoT block, per-connector overrides, and what happens under load.

***

## Deployment and Data Paths

These paths control where the broker stores its state. `ProjectPath` is the "base" that the other three resolve against.

**ProjectPath** `string (directory path)`

Overrides the broker **data root** (`CFBasePath`) so all state (`bin`, `log`, `stats`, config, projects, users, envs, secrets) lives under this path instead of the default install directory. Typical for Kubernetes volumes or custom install layouts. If not set, the broker uses its install directory.

**Precedence:** `COREFLUX_DATA_PATH` (if set) wins over this field. `CONFIG_PATH` sets the initial data directory (used by Docker images) but a non-empty `ProjectPath` can still replace it unless `COREFLUX_DATA_PATH` is set. The `-p` / `--path` flag is applied late — prefer env vars.

**UsersFile** `string (file path)`

Path to the file holding the broker's user accounts (the username/password credentials used when `AnonymousLogin` is `false`). When set and valid, users load from this **plaintext JSON** array instead of the encrypted user store, and runtime user changes are written back to this file.

**EnvsPath** `string (directory path)`

Directory containing the `.env` file for environment variables the broker (and LOT logic) can reference at runtime — used to externalize deployment-specific values instead of hardcoding them in config. Resolves to `{EnvsPath}/.env`. Falls back to `CFBasePath` when empty. See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for usage.

**SecretsPath** `string (directory path)`

Directory containing `secrets.json` — the secrets store for sensitive values (tokens, keys, credentials) kept separate from the main config so they aren't sitting in plain config JSON. Used by connectors and LOT `GET SECRET`. Resolves to `{SecretsPath}/secrets.json`. Falls back to `CFBasePath` when empty. See [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env) for usage.

***

## Logging

**FullDebugLog** `boolean` (default: false)

Enable detailed debug logging: connection validation details, every publish/subscription intercept, TCP health noise, etc. Useful for troubleshooting but may impact performance in production.

> [!WARNING]
>
> Only enable `FullDebugLog` for troubleshooting. Debug logging generates significant log volume and may impact broker performance.

**CloudLogging** `boolean` (default: false)

When `true`, switches logging to **stdout-only structured JSON** (no rolling file sink). Intended for Docker/Kubernetes where log aggregators scrape container output. The `COREFLUX_CLOUD_LOGGING=true` environment variable also enables cloud logging.

***

## Additional Settings

**Name** `string` (default: Coreflux DataHub)

A human-readable name for this DataHub / broker instance. Used for identification in logs and UI; does not affect MQTT protocol behaviour.

***

## Applying Configuration

### Via MQTT Topic

Publish a configuration JSON to the system topic using any MQTT client (such as MQTT Explorer). A partial object is merged into the live configuration: only the fields you include change, and every field you omit stays as it is, including bind addresses.

| Field | Value |
| - | - |
| **Topic** | `$SYS/Coreflux/Config/New` |
| **Auth** | Requires a user with system configuration permission |

**Payload:** Full or partial configuration JSON object

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"Name":"ProductionBroker","Port":1883,"TlsPort":8883,"AnonymousLogin":false}
```

> [!NOTE]
>
> The runtime handler currently persists only a subset of fields (`AnonymousLogin`, bind IPs, ports, `FullDebugLog`). A restart is required for listener, session, and certificate **path** changes to take effect. The **contents** of the files at `ServerCertificatePath` and `ServerCertificateKeyPath` are picked up on `ServerCertificateReloadIntervalSeconds` and do not require a restart.

### Configuration Validation

The broker validates configuration on load. The following checks are **fatal** — an invalid value prevents the broker from starting:

| Check | Requirement |
| - | - |
| Port values | Must be between 1 and 65535 |
| IP addresses | Must be valid IPv4 addresses |
| `MaxPendingMessagesPerClient` | Must be between 1 and 100000 |

Certificate-related issues are **non-fatal**: they log a warning at startup and the broker continues without TLS rather than refusing to start.

| Condition | Behaviour |
| - | - |
| `ServerCertificatePath` set but file missing | Warning logged; TLS listeners not started |
| `ServerCertificatePath` set but `ServerCertificatePassword` empty | Warning logged |
| `ClientCertificateSourcePath` (or default trust store) missing | Folder created at startup; if that fails, an error is logged and the trust store starts empty |

### Related Environment Variables

These process environment variables override or complement the JSON file. Restart the broker after changing them. Details and examples: [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env).

| Variable | Effect |
| - | - |
| `COREFLUX_DATA_PATH` | Data directory, used as-is; takes precedence over `CONFIG_PATH` and `ProjectPath` |
| `CONFIG_PATH` | Data directory if `COREFLUX_DATA_PATH` is unset (Docker images set `/etc/project`) |
| `COREFLUX_MQTT_SHARED_SUBSCRIPTIONS` | Overrides `SharedSubscriptions`. `1` or `true` enables shared subscriptions; `0` or `false` disables them. See [Shared subscriptions](#shared-subscriptions). |
| `COREFLUX_CLOUD_LOGGING` | Enables stdout JSON logging (same intent as `CloudLogging`) |
| `COREFLUX_LOG_LEVEL` | Log verbosity (`Verbose` … `Fatal`) |
| `COREFLUX_SECRET_KEY` | Base64 32-byte key for encrypted secrets |
| `COREFLUX_AUDIT_KEY` | Base64 32-byte key for audit log encryption |
| `COREFLUX_OPS_ENABLED` | Enable ops HTTP on `COREFLUX_OPS_PORT` (default `9100`) — `/health`, `/ready`, `/info`, `/license`, `/metrics`. See [Operational endpoints](/latest/mqtt-broker/operational-endpoints). |
| `COREFLUX_OPS_PORT` | Ops listener port |
| `COREFLUX_OPS_BIND_IP` | Ops bind address |
| `COREFLUX_ACTIVATION_CODE` | Online license activation (`CFLX-…`). See [Licensing and Enrollment](/latest/mqtt-broker/licensing) |
| `COREFLUX_ROUTE_OVERLOAD_POLICY` | Broker-wide default for connector `OVERLOAD_POLICY`. See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward). |
| `COREFLUX_ROUTE_CHANNEL_FULL_TIMEOUT_MS` | Broker-wide default wait budget (ms) for `balanced` connectors |
| `COREFLUX_ROUTE_CHANNEL_CAPACITY` | Shared ceiling on queued connector updates (default `100000`) |
| `COREFLUX_DURABILITY_*` | See [MQTT State Durability](/latest/mqtt-broker/durability) |
| `COREFLUX_CLUSTER_*` | See [Clustering](/latest/mqtt-broker/clustering) |
| `COREFLUX_DISABLE_PYTHON` | Skip in-process Python when `true` |

***

## Docker Configuration

When running Coreflux in Docker, configure the broker using environment variables or mounted configuration files.

### Using Environment Variables

**Docker Run**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d \
  --name coreflux_broker \
  -p 1883:1883 \
  -p 5000:5000 \
  -p 9100:9100 \
  -v project-volume:/etc/project \
  -v /path/to/certs:/certs \
  coreflux/coreflux-mqtt-broker:latest
```

**Docker Compose**

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
version: '3.8'
services:
  coreflux:
    image: coreflux/coreflux-mqtt-broker:latest
    container_name: coreflux
    ports:
      - "1883:1883"
      - "8883:8883"
      - "5000:5000"
      - "443:443"
    volumes:
      - ./config:/config
      - ./certs:/certs
    restart: unless-stopped
```

### Mounting Configuration

Mount your configuration file to the container:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run -d \
  -v /path/to/config.json:/app/config.json \
  -p 1883:1883 \
  coreflux/coreflux-mqtt-broker:latest
```

### TLS with Docker

When using TLS in Docker, ensure certificate paths in the configuration match the mounted paths inside the container:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
version: '3.8'
services:
  coreflux:
    image: coreflux/coreflux-mqtt-broker:latest
    ports:
      - "1883:1883"
      - "8883:8883"
    volumes:
      - ./certs/server.crt:/certs/server.crt:ro
      - ./certs/server.key:/certs/server.key:ro
      - ./certs/ca.crt:/certs/ca.crt:ro
```

Configuration JSON should reference the container paths:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "RootCACertificatePath": "/certs/ca.crt"
}
```

***

## Configuration Examples

### Development Environment

Minimal configuration for local development:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Name": "DevBroker",
  "Port": 1883,
  "AnonymousLogin": true,
  "FullDebugLog": true,
  "BindIPForMQTT": "127.0.0.1"
}
```

### Production Environment

Secure configuration for production deployment:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Name": "ProductionBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "AnonymousLogin": false,
  "FullDebugLog": false,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "secure-password",
  "RootCACertificatePath": "/certs/ca.crt"
}
```

### High-Security Environment

Configuration with mTLS for maximum security:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Name": "SecureBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "AnonymousLogin": false,
  "FullDebugLog": false,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "ServerCertificatePath": "/certs/server.crt",
  "ServerCertificateKeyPath": "/certs/server.key",
  "ServerCertificatePassword": "secure-password",
  "RootCACertificatePath": "/certs/ca.crt",
  "ClientCertificateSourcePath": "/certs/trusted-clients/",
  "ClientCertificationValidation": true,
  "CheckCertificateChainValidation": true,
  "CheckCertificateRevokationList": true,
  "ClientCertificateRevocationListPath": "/certs/crl.pem"
}
```

***

## Next Steps

> **[Broker Commands](/latest/mqtt-broker/commands)**
>
> Learn how to manage the broker via MQTT commands.

> **[\$SYS Topics](/latest/mqtt-broker/sys-topics)**
>
> Monitor broker status through system topics.


# MQTT State Durability
Source: https://docs.coreflux.org/latest/mqtt-broker/durability

Persist retained messages, sessions, and queued QoS 1/2 across broker restarts with the durability write-ahead log

## Keep MQTT state across restarts

By default, retained messages, persistent sessions, and queued QoS 1/2 traffic live in memory. A broker restart clears them. **Durability** writes that state to a local write-ahead log (WAL) so after a restart, clients can reconnect and pick up where they left off — their subscriptions, retained values, and any messages that were still waiting to be delivered.

> [!TIP]
>
> **Like a notebook next to a whiteboard.** The whiteboard is fast working memory; the notebook is what you still have after the room goes dark. Durability is the notebook for MQTT state that must survive a restart.

### When to enable durability

Enable durability when you need:

* retained values to survive a broker restart;
* persistent sessions and their subscriptions restored after reboot; or
* queued QoS 1/2 messages re-offered to clients that reconnect with a persistent session.

Leave it off on constrained edge devices (slow flash, tight write budgets) or when restart persistence is not required.

> [!NOTE]
>
> Durability is a **broker-level** setting. It works on a standalone broker and on every cluster node. In a [high-availability cluster](/latest/mqtt-broker/clustering) (beta), enable it on every node: it keeps each node's sessions and queued messages across restarts, and it lets subscriptions follow a client that reconnects to another node.

***

Configure the `Durability` section (or `COREFLUX_DURABILITY_*` environment variables), restart the broker, and verify retained or session state after a controlled restart.

## Quick Start

Add a `Durability` block to the broker configuration, or set environment variables (env vars override the file). Restart the broker for changes to take effect.

**Enable (typical)**

Opt in with the default flush policy (group commit every 50 ms):

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Durability": {
    "Enabled": true,
    "FsyncPolicy": "interval",
    "FsyncIntervalMs": 50,
    "Codec": "json"
  }
}
```

**Strongest fsync**

Flush every append when you need the smallest power-loss window on a single node:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Durability": {
    "Enabled": true,
    "FsyncPolicy": "always",
    "Codec": "json"
  }
}
```

**Environment variables**

Tune without editing the config file (useful in containers):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
export COREFLUX_DURABILITY_ENABLED=true
export COREFLUX_DURABILITY_FSYNC=interval
export COREFLUX_DURABILITY_FSYNC_INTERVAL_MS=50
export COREFLUX_DURABILITY_CODEC=json
# optional: export COREFLUX_DURABILITY_DATA_DIR=/var/lib/coreflux/mqttwal
```

***

## What is persisted

| State | Survives restart? | Notes |
| - | - | - |
| **Retained messages** | Yes | Reloaded on boot on that node |
| **Persistent sessions + subscriptions** | Yes | A client that reconnects with a persistent session gets its subscriptions back |
| **Queued QoS 1/2 (unacked)** | Yes | Re-offered on session restore (**at-least-once** — a message acked at crash time may be redelivered) |

QoS 0 traffic is not made durable by this layer — MQTT treats it as best-effort.

***

## Configuration reference

| Config field | Env var | Default | Description |
| - | - | - | - |
| `Enabled` | `COREFLUX_DURABILITY_ENABLED` | `false` | Master switch — opt in for restart durability |
| `FsyncPolicy` | `COREFLUX_DURABILITY_FSYNC` | `interval` | `interval` (group commit) or `always` (flush every append) |
| `FsyncIntervalMs` | `COREFLUX_DURABILITY_FSYNC_INTERVAL_MS` | `50` | Flush interval in ms when policy is `interval` |
| `Codec` | `COREFLUX_DURABILITY_CODEC` | `json` | Log encoding: `json` (readable) or `binary` (compact) |
| `DataDir` | `COREFLUX_DURABILITY_DATA_DIR` | `{data path}/mqttwal` | Root directory for durable MQTT state |
| `MaxSegmentBytes` | — | `8388608` (8 MiB) | Segment size that triggers rotation |
| `CheckpointEveryAppends` | — | `4096` | Appends between checkpoints that truncate older segments |

Accept `1` / `true` (case-insensitive) for `COREFLUX_DURABILITY_ENABLED`.

### Fsync policy

| Policy | Behavior | Trade-off |
| - | - | - |
| `interval` (default) | Appends buffer and flush together on a timer | Bounded loss window on **power failure** only; process crashes still keep what the OS already had |
| `always` | Flush to disk on every append | Strongest single-node guarantee; every message waits for the disk, so it suits low message rates (and is costly on eMMC/SD edge devices) |

### Codec

* **`json` (default)** — human-readable records; easier to inspect during debugging.
* **`binary`** — compact encoding; smaller on disk and typically faster to encode/decode on busy brokers. Existing JSON segments still recover; new records append in binary. Switching back from binary to `json` for inspection of already-written binary segments is not supported — stay on `json` if you need text tooling on the log.

In a cluster, the same codec setting also applies to the replication logs used for quorum durability.

***

## Performance

Durability is built so that you only pay for the state you choose to protect.

| Clients | What durability does for them | Performance impact |
| - | - | - |
| **Without a persistent session** (MQTT 3.1.1 clean session, MQTT 5 session expiry 0) | Nothing to keep: the broker records nothing for them | None measurable |
| **With a persistent session** | Records each QoS 1/2 message queued for them, and its acknowledgement, so nothing is lost if the broker restarts | Grows with the rate of messages delivered to persistent sessions |

In our tests with the default flush policy (one broker, QoS 1), average round-trip latency was unchanged, and fan-out to 20 persistent subscribers kept about two-thirds of the delivery rate it reached with durability off. `FsyncPolicy: always` waits for the disk on every write and is meant for low message rates.

> [!TIP]
>
> Give persistent sessions only to the clients that must receive messages sent while they were offline. Traffic that reaches no persistent session costs nothing extra, even with durability on.

***

## Durability and clustering

Durability and clustering (beta) protect different parts of a message's path, and a cluster needs both:

| Concern | What protects you |
| - | - |
| **A node restarts** | Durability on that node: its persistent sessions, their queued QoS 1/2 messages, and its retained messages are restored |
| **A node fails after acknowledging a QoS ≥ 1 publish** | Cluster [quorum replication](/latest/mqtt-broker/clustering#delivery-guarantees): the message is already stored on a majority of nodes |
| **Messages published while a node is down** | Clustering queues them for that node, and durability restores the sessions they are delivered to when it returns |
| **A client reconnects to another node** | Session takeover: requires durability so the client's subscriptions follow it |

Without durability, a cluster node that restarts comes back with no sessions. Messages that the other nodes kept for its persistent subscribers then have no session to go to, and are lost. See [Durability and clustering](/latest/mqtt-broker/clustering#durability-and-clustering) on the clustering page.

> [!WARNING]
>
> **Offline queues stay on the node that hosted them.** Subscriptions follow a client that reconnects to another node (with durability enabled), but QoS 1/2 messages already queued for it are delivered only if it reconnects to the node that queued them. See [clustering limitations](/latest/mqtt-broker/clustering#limitations).

***

## Observability

Prometheus `/metrics` exposes durability and WAL series, including:

| Metric family | What it shows |
| - | - |
| `coreflux_durability_enabled` | Whether durability is on |
| `coreflux_wal_*` | Appends, bytes written, fsyncs, last fsync latency |
| `coreflux_durable_*` | Counts for retained messages, sessions, in-flight messages, and in-flight drops |

Use these alongside your usual broker health checks after enabling durability or changing fsync policy.

***

## Limitations

> [!WARNING]
>
> **Durability is opt-in.** The default is `Enabled: false`. Without it, retained messages, sessions, and queued QoS 1/2 are lost on restart, and cluster session failover cannot restore subscriptions on another node.

> [!WARNING]
>
> **Persistent sessions add disk work.** Every QoS 1/2 message delivered to a persistent session is written to the log when it is queued and again when it is acknowledged. Plan disk throughput for your persistent-session message rate, and use `FsyncPolicy: always` only for low message rates. See [Performance](#performance).

> [!WARNING]
>
> **At-least-once after crash.** A QoS 1/2 message acknowledged at the exact moment of failure may be redelivered after restore. Design consumers to tolerate duplicates.

> [!WARNING]
>
> **Retained messages are kept per node.** Durability restores each node's own retained messages after a restart; it does not create a cluster-wide retained store. See [clustering limitations](/latest/mqtt-broker/clustering#limitations).

***

## Next Steps

> **[High-Availability Clustering](/latest/mqtt-broker/clustering)**
>
> Run multiple brokers with quorum replication and session failover on top of durability.

> **[Broker Configuration](/latest/mqtt-broker/configuration)**
>
> Ports, TLS, listeners, and other broker settings.


# Licensing and Enrollment
Source: https://docs.coreflux.org/latest/mqtt-broker/licensing

Activate a Coreflux broker with an online code or a signed license, enroll it in an organization, and inspect tier limits

## Unlock the plan you bought

A Coreflux broker always starts. With no license it runs as **Community**. A signed license — obtained online with an activation code, or installed offline as a file — is what raises the plan, artifact budget, and premium features.

> [!TIP]
>
> **Like a signed ticket versus a door code.** An activation code is the door code: the broker exchanges it once for a signed ticket (the license) and keeps that ticket. An offline file *is* the ticket, already signed for the broker host. Either way, the broker checks the ticket itself — losing internet does not lock you out.

### When to use this

* **Start a 30-day Growth trial** — register at [portal.coreflux.org](https://portal.coreflux.org), then activate the license on your broker
* **Manage your fleet** of brokers in the same portal
* **Activate a running broker** with a `CFLX-…` code, without restarting
* **Install a signed license** on an air-gapped host using the hardware fingerprint
* **Enroll** the broker into a Coreflux organization so federated logins can bind to that org
* **Check usage and limits** from `$SYS/Coreflux/License` or the ops [`GET /license`](/latest/mqtt-broker/operational-endpoints#license-status) endpoint

Licensing and enrollment are **separate**. A license sets the plan. Enrollment binds the broker to an organization. You can license a broker without enrolling it.

***

The sections below cover the two license paths, the MQTT commands, environment variables, and how to watch status.

## Quick Start

**Activate online**

Paste an activation code on a running broker. Limits apply immediately — no restart.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-activateLicense CFLX-XXXX-XXXX-XXXX
```

Get the code by registering at [portal.coreflux.org](https://portal.coreflux.org) (including a 30-day Growth-type license). The broker exchanges the code with the licensing authority, verifies the signed lease, and republishes `$SYS/Coreflux/License`. The code is used once and is not written to disk; the signed lease is what survives a restart.

On a broker you cannot reach over MQTT, set `COREFLUX_ACTIVATION_CODE` in the **process** environment and start (or restart) the broker instead.

**Install a signed file**

For air-gapped hosts, print the broker host's fingerprint, send it to Coreflux, and install the signed file you get back:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
./CorefluxMQTTBroker --show-fingerprint
./CorefluxMQTTBroker --load-license /path/to/license.jws
```

`--load-license` verifies the file and stages it under the data directory as `config/license.jws` before MQTT starts. On a running broker, publish `-loadLicense` with either a path **on the broker host** or the compact JWS text itself (the usual path from Coreflux HUB).

**Enroll in an organization**

Enrollment binds this broker to a Coreflux organization. It does not change the plan. Stage a one-shot token (`et_…`, typically valid for about 10 minutes):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-enroll et_…
```

The broker exchanges the token in the background and never echoes it in the command reply. Until enrollment succeeds the broker still starts: local users work; federated logins that need an org binding are refused.

## Plans

Three plans. With no license and no activation code, the broker is **Community**. The broker does **not** start a trial on its own.

### 30-day Growth trial

To try Growth features, **register at [portal.coreflux.org](https://portal.coreflux.org)**. That issues a **30-day Growth-type license**. Activate it on your broker the same way as any other license (`-activateLicense` / `COREFLUX_ACTIVATION_CODE`, or a signed file). When the 30 days end, the broker reverts to Community like any other expired license.

Use the same portal to **manage your fleet of brokers**. This page does not walk through portal screens — open the portal and follow the flow there.

The same account is how [Coreflux HUB](/hub/account-and-fleet) lists that fleet and connects with an access token. The broker accepts the token only after enrollment has set its organization and [OIDC bearer authentication](/latest/mqtt-broker/oidc-authentication) is enabled. License activation and that MQTT check are separate: a valid license does not by itself turn token login on.

> [!NOTE]
>
> A **Cloud Trial** on [Installation](/latest/quick-start/installation) is a hosted broker and HUB Coreflux runs for you. A Growth trial from the portal is a **license** you apply to a broker you install (Docker, package, or binary).

A 30-day trial uses the **Growth** column. Paid plans keep the same limits until the license expires.

| Feature | Community | Growth | Enterprise |
| - | - | - | - |
| Artifact budget | 24 | 100 | 1 000 |
| Connectors | 3 | 5 | Unlimited |
| MQTT Bridge | No | Yes | Yes |
| MCP | No | Yes | Yes |
| LLM / Agent | No | Yes | Yes |
| Video input / output | No | Yes | Yes |
| RBAC / topic access control | No | Yes | Yes |
| Cluster | No | No | Yes |
| Max connections (display) | 10 000 | 10 000 | 10 000 |

Custom ACL rules (`-addRule`) require Growth or Enterprise. Shipped default rules always apply. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac).

A `TYPE LLM` connector counts toward the connector cap. A `DEFINE AGENT` needs the same Growth or Enterprise license and does not take a connector slot. License usage reports agents separately from connectors. See [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

### Artifact budget

Models, Actions, and Panels each cost **1**. Python scripts cost **2**. When the budget is full, new definitions are refused with a message that names the limit.

When a license expires (past expiry plus any offline grace), the broker reverts to **Community**. Existing artifacts keep running; new artifacts, advanced connectors, and new RBAC rules are blocked.

***

## How the broker picks a license

On boot the broker uses the **first** source that succeeds:

1. **Inline signed token** — process env `COREFLUX_LICENSE_TOKEN` (a compact JWS)
2. **License file path** — process env `COREFLUX_LICENSE_FILE` (for a read-only mount)
3. **Working file** — `config/license.jws` in the [data directory](/latest/mqtt-broker/secrets-and-env#config-root)
4. **Online activation** — process env `COREFLUX_ACTIVATION_CODE`
5. **Community** — nothing of the above

A verified token is staged to `config/license.jws` so later restarts can load it without the network. An online lease then refreshes about once a day.

> [!WARNING]
>
> Licensing reads the **process** environment at boot (`Docker environment:`, systemd `Environment=`, Kubernetes `env:`). It does **not** read the LoT `.env` file you manage with `-setEnv` / `GET ENV`. Put `COREFLUX_ACTIVATION_CODE` in the process environment, not only in the data-directory `.env`.

***

## Commands

Publish to `$SYS/Coreflux/Command` and subscribe to `$SYS/Coreflux/Command/Output`. The same verbs work from [Coreflux HUB Command Console](/hub/system/command-console) and the System Config **License** tab. See [Broker Commands](/latest/mqtt-broker/commands#license).

| Command | Alias | Permission | What it does |
| - | - | - | - |
| `-activateLicense <code>` | `--activate-license` | `SystemConfiguration` | Exchanges a `CFLX-…` code for a lease and applies it immediately. No restart. |
| `-loadLicense <jws-or-path>` | `--load-license` | `CommandCall` | Verifies a signed license (compact JWS text, or a path on the broker host) and stages `config/license.jws`. |
| `-refreshLicense` | `--refresh-license` | `CommandCall` | Forces one online lease refresh. Refused when the broker holds no lease. |
| `-enroll <et_…>` | `--enroll` | `CommandCall` | Stages a single-use enrollment token. The exchange runs in the background. |

### Activate

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-activateLicense CFLX-XXXX-XXXX-XXXX -requestId license-1
```

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "ActivateLicense",
  "requestId": "license-1",
  "message": "Activated: Growth (lic_…), hard seat, expires 2027-04-09. Limits applied now — no restart needed.",
  "data": {}
}
```

On refusal the broker `message` names the remedy (unknown code, no free seat, authority unreachable). The activation code is redacted from broker logs and the audit trail.

### Load a signed license

A compact JWS is treated as the license itself. Anything else is treated as a path on the **broker** filesystem:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-loadLicense /path/to/license.jws
-loadLicense eyJhbGciOiJFUzI1NiIsInR5cCI6IkNGTFhMSUMi.….<payload>.<signature>
```

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "LoadLicense",
  "message": "Signed license verified and stored at <config>/license.jws",
  "data": {}
}
```

HUB and other remote clients send the JWS text because they cannot write a file on the broker host. Strip wrapping whitespace before you send it — a compact JWS contains none, but files often arrive with a trailing newline.

> [!NOTE]
>
> Brokers that predate JWS-text `-loadLicense` treat the token as a path and reply `License file not found: eyJ…`. Update the broker, or install on the host with `--load-license /path/to/license.jws`.

### Refresh an online lease

The online lease refreshes on a 24-hour timer. Use `-refreshLicense` when a plan change or revocation should apply now:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-refreshLicense
```

Refused when this broker holds no online lease — activate first, or install an offline file instead.

### Enroll

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-enroll et_…
```

The reply confirms the token was staged; it never contains the token. Treat enrollment as done when `$SYS/Coreflux/License` shows `Enrollment.Enrolled` as `true` or `Enrollment.BoundOrg` set to the organization id — Coreflux HUB shows **Enrolled** in that case. `Enrollment.Pending` going false is not enough. While enrollment is still pending, `Enrollment.Reason` names the remaining problem.

#### When the platform can't be reached

If egress to `brokers.coreflux.org` is blocked, the broker keeps serving. Licensing and local users are unaffected. Only federated logins wait for `BoundOrg`. Each platform call times out after 15 seconds, so startup isn't delayed.

A lease enrollment with no answer retries at the next licence refresh (daily, or now with `-refreshLicense`). An `et_…` token with no answer is kept and retried with backoff (5 seconds, doubling up to every 5 minutes) while the token is valid. A new token, or pressing **Enroll** in Coreflux HUB, is tried at once.

`Enrollment.Reason` says the platform couldn't be reached, and the broker logs one warning instead of an error per attempt.

#### When the credential is revoked

If the broker's Fleet row is deleted, the broker is disconnected, or the organization is deleted, the broker logs *Platform no longer recognises this credential* and keeps serving.

If it holds an online lease, it renames the file to `credential.json.revoked` and enrolls again with the lease within seconds. The portal only accepts that for a broker waiting in Fleet, so a disconnected broker doesn't rejoin on its own.

Without a lease, replace or remove the credential and supply a new `et_…` token.

***

## Startup flags

These flags are processed at process start (see [Startup Options](/latest/mqtt-broker/startup-options)):

| Option | Long form | Description |
| - | - | - |
| `-showFingerprint` | `--show-fingerprint` | Print the broker host's hardware fingerprint and exit. Send that value to Coreflux to be issued an offline license. Does not start MQTT. |
| `-loadLicense` | `--load-license` | Stage a signed license file as `config/license.jws` before MQTT starts. |
| `-enroll` | `--enroll` | Stage a single-use `et_…` token for the startup exchange. Also accepted on `$SYS/Coreflux/Command` while running. |

***

## Environment variables

Set these on the **broker process**. Restart after changing them unless you use `-activateLicense` / `-enroll` on a live broker instead.

| Variable | Role |
| - | - |
| `COREFLUX_ACTIVATION_CODE` | Online activation (`CFLX-…`). Also turns **enrollment** on. |
| `COREFLUX_LICENSE_TOKEN` | Inline signed JWS. Wins over a file on disk. |
| `COREFLUX_LICENSE_FILE` | Path to a signed `.jws` file (read-only mounts). |
| `COREFLUX_FLEET_METRICS` | `off`, `false`, or `0` stops an enrolled broker sending [fleet performance metrics](#fleet-performance-metrics). Unset leaves them on. This wins over the Portal switch. |
| `DO_NOT_TRACK` | `1` turns off fleet performance metrics and the anonymous install census. |

A broker onboarded from Coreflux HUB needs none of these. Enrollment also turns on at boot when `config/enrollment/credential.json` exists (from `-enroll`) or `config/license.jws` holds an online lease for this instance (from `-activateLicense`). A successful `-activateLicense` turns it on immediately, without a restart.

There is no `COREFLUX_ENROLLMENT_TOKEN` environment variable. Deliver the token with `--enroll` / `-enroll`, or write it to `{data directory}/config/enrollment-token`.

Allow outbound HTTPS to `https://license.coreflux.org` for activation and refresh, and to `https://brokers.coreflux.org` for enrollment.

***

## Fleet performance metrics

An enrolled broker sends a host description, one metrics point per minute, and up to 25 grouped error reports on the same enrollment heartbeat (every 300 seconds by default). No extra connection is opened. A broker that is not enrolled sends nothing. The Coreflux Portal charts the metrics on that broker's page.

The host description includes the process start time, operating system and version, architecture, .NET version, container and orchestrator, core count, cgroup CPU quota and memory limit, and cluster role and size. It does not include a hostname, IP address, user name, or file path.

Each minute includes CPU (average and peak), working set and managed heap, garbage-collection pause share and thread-pool queue peak, connected clients, connects and disconnects, messages and bytes in and out (with per-second peaks), refused CONNECTs, ACL denials, rate-limit refusals, route and cluster drops, and route, action, model, and Python errors. It also includes the session count, the retained-message count, the ten routes with the most errors.

Error signatures are scrubbed before they leave the broker. Numbers become `#`. GUIDs and hex ids become `<id>`. Anything in single or double quotes becomes `'…'`. The text is cut at 200 characters. Topics and payloads are never sent. Each signature is named by the route, action, model, or script that failed.

Errors are grouped by kind, not by source, so 100 connectors with the same fault send one report. Each report lists the sources that hit it (up to 50, busiest first) with a count, and adds:

* A category (`comms`, `config`, `auth`, `resource`, `script`, `internal`, or `device`), a severity, whether the broker retries on its own, and a short hint when the broker recognizes the error.
* The exception type and the first broker code frame. For an action, the LoT line that failed.
* For a connector, its type and name. Never its address.

Transient connector errors, such as timeouts and dropped sockets, fold into one **Connection unstable** report per connector type, with the number of reconnects. It is a warning while reads still succeed, and becomes an error once a source has gone more than two report intervals without a good read. The whole error block stays under about 24 KB.

The heartbeat also reports why the previous broker process stopped: `graceful`, `signal` (for example a Kubernetes rollout or Ctrl-C), `unhandled` (with the exception type), or `unknown` (killed, out of memory, or power loss), with its start time and uptime. This needs a persistent data directory. On a container without one it stays empty.

While the platform is unreachable, the broker keeps up to 60 unsent minutes and sends them when the platform answers again. Older minutes are dropped.

Fleet performance metrics are on by default. The Coreflux Portal has a per-broker switch. The broker learns that choice from the heartbeat response, within one interval. These settings on the broker always win over the Portal:

1. `COREFLUX_FLEET_METRICS=off` (or `false` or `0`).
2. `DO_NOT_TRACK=1`.
3. `"Enrollment": { "Metrics": { "Enabled": false } }` in the broker configuration.

`COREFLUX_TELEMETRY` affects only the anonymous install census. It does not change fleet performance metrics. The counters behind these metrics are also exposed on the local [`/metrics`](/latest/mqtt-broker/operational-endpoints#metrics) endpoint, whether fleet metrics are on or off.

***

## Watch license status

The broker publishes the full status **retained** on:

```
$SYS/Coreflux/License
```

The same status is served on **`GET /license`** on the [operational endpoints](/latest/mqtt-broker/operational-endpoints#license-status) listener (default port `9100`). HTTP property names are camelCase; the samples below match the retained topic. Ops HTTP is unauthenticated — do not expose that port to the public internet.

Community brokers still publish the topic, so you can read `Tier`, `EffectiveLimits`, `CurrentUsage`, `Fingerprint`, and `Enrollment`.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "LicensedTo": "N/A",
  "ExpiresUtc": null,
  "IsActive": false,
  "Tier": "Community",
  "Fingerprint": "…",
  "FingerprintSource": "machine-id",
  "EffectiveLimits": {
    "MaxArtifacts": 24,
    "MaxRoutes": 3,
    "MaxConnections": 10000
  },
  "CurrentUsage": {
    "ArtifactCount": 4,
    "Routes": 1
  },
  "Enrollment": { "Pending": false, "Reason": null, "Enrolled": false, "BoundOrg": null }
}
```

An activated Growth license looks like:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "LicensedTo": "Acme Corp",
  "ExpiresUtc": "2027-04-09T00:00:00Z",
  "IsActive": true,
  "Tier": "Growth",
  "Plan": "growth",
  "Activation": {
    "Mode": "online",
    "BindingOk": true,
    "Online": {
      "IsLease": true,
      "SeatMode": "hard",
      "LeaseExpiresUtc": "2026-09-28T00:00:00Z"
    }
  },
  "Enrollment": { "Pending": false, "Reason": null, "Enrolled": false, "BoundOrg": null }
}
```

Those two samples are licensed (or not) without an organization binding. A finished enrollment on a current broker looks like this:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "Pending": false, "Reason": null, "Enrolled": true, "BoundOrg": "your-org-id" }
```

JSON field names still say `Routes` for connectors (`MaxRoutes`, `CurrentUsage.Routes`). `isTrial` may appear in lowercase. Older brokers omit `Enrolled` and `BoundOrg` and publish only `{ Pending, Reason }`.

### Fields operators use

| Field | Meaning |
| - | - |
| `Tier`, `IsActive`, `Plan`, `LicensedTo` | Plan in force |
| `ExpiresUtc`, `SecondsToExpiry` | Hard expiry of the license |
| `Fingerprint`, `FingerprintSource` | Value to send Coreflux for an offline license |
| `Activation.Mode` | `online` (lease) or `offline` (signed file) |
| `Activation.BindingOk` / `BindingReason` / `TamperDetected` | Whether the broker actually honoured the license |
| `Activation.Online.LeaseExpiresUtc` / `LastValidatedUtc` / `SeatMode` | Online lease freshness (`hard` = seat pool enforced, `soft` = Enterprise cluster honor-system) |
| `EffectiveLimits`, `CurrentUsage`, `Features` | Quotas and gates |
| `Enrollment.Pending` / `Enrollment.Reason` | A problem was recorded, and the broker's sentence for it. `Pending: false` only means no problem was recorded |
| `Enrollment.Enrolled` | `true` only while this broker is bound to an organization or heartbeating with its enrollment credential. A credential file on disk alone doesn't count. This is the signal to treat enrollment as done |
| `Enrollment.BoundOrg` | Organization id when the broker has one. With `Enrolled`, this is what Coreflux HUB uses for **Enrolled** |

> [!WARNING]
>
> `Enrollment.Pending: false` does **not** mean the broker is enrolled. The broker sets `Pending` when it recorded a problem. A broker that never attempted enrollment reports the same `Pending: false` as one that finished. Treat a missing `Reason` as “no problem reported,” not as proof of an org binding. Treat enrollment as done when `Enrolled` is `true` or `BoundOrg` names the organization (Coreflux HUB shows **Enrolled**). A payload that only has `{ Pending, Reason }` does not report enrollment; HUB shows **Enrollment not reported**.

### Enrollment reasons

When `Enrollment.Pending` is `true`, `Reason` is a full sentence. Typical causes:

| Cause | What to do |
| - | - |
| No credential supplied | Set `COREFLUX_ACTIVATION_CODE`, or paste an `et_…` token in the HUB License tab / `-enroll` |
| Authority unreachable | Allow egress to `https://license.coreflux.org`; the broker retries on its own |
| Platform unreachable | Allow egress to `https://brokers.coreflux.org`; the broker keeps serving and retries |
| Seat pool full | Wait for a killed instance's lease to expire, or manage the fleet at [portal.coreflux.org](https://portal.coreflux.org) |
| Licence unclaimed | The license is not bound to an organization yet. Manage the fleet at [portal.coreflux.org](https://portal.coreflux.org) — retrying the broker will not help |
| Instance mismatch | Expected: a lease cannot move between hosts |

***

## Offline fingerprint

Send Coreflux the value from `--show-fingerprint`, or the `Fingerprint` field on the status payload. That value is what the offline license is bound to.

A container that cannot read a stable machine id gets a fingerprint that can change when the container is recreated, which drops the broker back to Community. Request an offline license for that container only when that is acceptable.

***

## Persist the data volume

The license, install identity, and enrollment credential live under `{data directory}/config/`. Official images use `CONFIG_PATH=/etc/project`.

| Path (under the data directory) | Why it must persist |
| - | - |
| `config/license.jws` | Active license or online lease |
| `config/instance-id` | Install identity — one volume is one seat. Restarts reclaim the same seat instead of spending a new one |
| `config/enrollment-token` | Drop-file for a one-shot `et_…` token (`--enroll` writes here; the broker deletes it after a successful exchange when the path is writable) |
| `config/enrollment/` | Persisted org credential after a successful enroll |

> [!WARNING]
>
> Never copy `config/instance-id` between hosts, and never bake `config/` into an image after first boot. Every broker launched from that image then claims the **same** seat. Build images before first boot, or delete `config/instance-id` and `config/enrollment/` before snapshotting.

Online-activated brokers with `COREFLUX_ACTIVATION_CODE` and an **empty** volume mint a new install identity and consume a new seat. Restoring the old volume is cheaper than re-activating. If the volume is gone, manage the fleet at [portal.coreflux.org](https://portal.coreflux.org) before activating on a new volume.

Enrolled brokers need `config/enrollment/` on the same volume. An enrollment token is single-use: if the credential is on an emptyDir and the pod restarts, the next exchange fails and will not self-heal.

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
volumeMounts:
  - name: broker-data
    mountPath: /etc/project
volumes:
  - name: broker-data
    persistentVolumeClaim:
      claimName: coreflux-data
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d --name coreflux_broker \
  -p 1883:1883 -p 5000:5000 -p 9100:9100 \
  -e COREFLUX_ACTIVATION_CODE=CFLX-XXXX-XXXX-XXXX \
  -v project-volume:/etc/project \
  coreflux/coreflux-mqtt-broker:latest
```

***

## Error messages

| Situation | Typical message |
| - | - |
| Artifact budget full | `Artifact budget exceeded. Max N artifact(s) allowed on this tier.` |
| Connector limit reached | `Tier limit exceeded: Maximum allowed routes are N.` |
| Advanced connector, wrong tier | `Route type 'X' requires a Growth or Enterprise license.` |
| RBAC rule, wrong tier | `RBAC / Topic Access Control rules require a Growth or Enterprise license.` |
| Bad signed file | `Signed license failed verification (bad signature, wrong product, or not yet valid).` |
| Not a JWS and not a file | `Not a signed license file (expected a compact JWS).` |

***

## Best practices

> **Prefer an activation code when the broker can reach the network**
>
> Online activation refreshes the lease, picks up plan changes, and releases the seat on a graceful shutdown. Get a code (including a 30-day Growth-type license) at [portal.coreflux.org](https://portal.coreflux.org). Keep `COREFLUX_ACTIVATION_CODE` in the process environment (or activate once with `-activateLicense` and persist `config/license.jws`).

> **Use a signed file only when the host is air-gapped**
>
> Offline licenses are hardware-bound. Collect `--show-fingerprint` from the real host — not from a laptop you will not deploy.

> **Keep config/ on the same volume across upgrades**
>
> Replacing the image while keeping `/etc/project` (or `/var/lib/coreflux`) preserves the license, the seat, and enrollment.

> **Do not publish the ops port**
>
> `GET /license` on the [ops listener](/latest/mqtt-broker/operational-endpoints#license-status) is unauthenticated. Bind ops to localhost or a private network. The same status is on `$SYS/Coreflux/License` for MQTT clients that already authenticate.

> [!WARNING]
>
> Losing connectivity never bricks a licensed broker. The signed license is checked locally. An online lease keeps running until its expiry plus grace; if refresh later sees a revocation, the broker reverts to Community.

***

## Next Steps

> **[License tab in Coreflux HUB](/hub/system/configuration#license)**
>
> Activate with a code or signed file, refresh a lease, and enroll from System Config.

> **[Broker Commands](/latest/mqtt-broker/commands#license)**
>
> Publish `-activateLicense`, `-loadLicense`, `-refreshLicense`, and `-enroll` over MQTT.


# MCP Server
Source: https://docs.coreflux.org/latest/mqtt-broker/mcp-server

Expose the Coreflux broker as an MCP server so AI clients can run broker commands and LoT actions over Streamable HTTP

## Let AI Clients Operate the Broker

The Coreflux broker can listen as an **MCP (Model Context Protocol) server**. An AI client — Cursor, Claude Desktop, or any MCP-capable assistant — connects over HTTP, presents a broker-issued token, and calls tools that map to broker commands and your LoT (Language of Things) Actions. You stay in the editor; the assistant deploys Actions, lists connectors, and inspects topics **as a named broker user**, with that user's RBAC.

This is a **broker configuration feature** (`Mcp.Enabled`), not a LoT connector. There is no `DEFINE CONNECTOR` for it, and `DEFINE ROUTE` is only the alias of that keyword. `TYPE MCP_SERVER` was removed.

> [!TIP]
>
> **Like giving an assistant a badge for the control room.** The badge (a bearer token) is minted for a specific operator. Every tool call is checked against that operator's permissions — not against a shared admin back door.

### When to use this

* You want Cursor or Claude Desktop to **deploy LoT, inspect topics, and run broker commands** against a live broker
* You need a **least-privilege identity** for the assistant (not `root`) so RBAC still applies
* You are **migrating off** a saved `TYPE MCP_SERVER` connector or an old `/sse` client URL

### Three different MCP surfaces

Coreflux uses MCP in three places. They are not interchangeable:

| Surface | Direction | What it is | Docs |
| - | - | - | - |
| **MCP Server** | AI client → this broker | The broker's built-in MCP server. Config (`Mcp.Enabled`), Streamable HTTP at `/mcp`, bearer token. | This page |
| **Documentation MCP** | AI client → docs.coreflux.org | Hosted docs search for assistants. Does **not** control a broker. | [Documentation MCP](/ai/mcp) |
| **MCP connector** | Broker → an external MCP server | LoT `DEFINE CONNECTOR … WITH TYPE MCP` and `CALL MCP` from Actions. | [MCP Connectors](/latest/lot-language/routes/mcp-routes) |

The Coreflux HUB AI assistant does **not** talk to this MCP server. HUB is a control plane for enabling it and minting tokens — not an MCP client of the broker.

***

Enable the listener, mint a token for a real broker user, point the client at `/mcp`, then verify with `/health` and `$SYS/Coreflux/MCP/Info`.

## Quick Start

The listener starts only when `Mcp.Enabled` is on **and the broker has restarted**. Default bind is loopback on the broker host: `127.0.0.1:6278` at path `/mcp`. In a container, that's the container's own loopback. See [Docker and Kubernetes](#docker-and-kubernetes).

**Broker config**

Add an `Mcp` block to the broker configuration, then restart:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Mcp": {
    "Enabled": true,
    "Port": 6278,
    "BindIP": "127.0.0.1",
    "Endpoint": "/mcp"
  }
}
```

Mint a token for an existing broker user. The plaintext is returned **once** in `data.token`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-createMcpToken operator cursor-local
```

Point the AI client at `http://127.0.0.1:6278/mcp` with `Authorization: Bearer <token>`.

**Environment variables**

Override the file without editing JSON (useful in containers). Restart the broker after setting them:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
export COREFLUX_MCP_ENABLED=true
export COREFLUX_MCP_PORT=6278
export COREFLUX_MCP_BIND_IP=127.0.0.1
export COREFLUX_MCP_ENDPOINT=/mcp
```

Then mint a token the same way (`-createMcpToken <username> <token-name>`) and put it in the client's MCP config.

**Coreflux HUB**

In **System → System Configuration**, open the **MCP** tab. Turn **Enabled** on, save, and **restart the broker**. Status stays **Pending restart** until the new `Mcp` block is live.

Click **Create token**, pick a broker user, give the token a name with no spaces, and copy the value immediately. The dialog offers Cursor, Claude Code, and Claude Desktop snippets with `"type": "http"` and the bearer header already filled in.

Older brokers with no `Mcp` key in `$SYS/Coreflux/Config` do not have this tab's editor — update the broker first. See [System Configuration](/hub/system/configuration#mcp).

> [!TIP]
>
> Probe the unauthenticated health path on the MCP port (this is **not** the ops `/health` on port 9100):
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> curl http://127.0.0.1:6278/health
> ```
>
> A healthy listener returns `status: "healthy"` and a `tools_count`. Then subscribe in MQTT Explorer to `$SYS/Coreflux/MCP/Info` — the retained payload includes `http_endpoint` and `status`.

***

## Endpoints

The MCP listener is a **separate HTTP port** from MQTT and from the [operational endpoints](/latest/mqtt-broker/operational-endpoints) (`/health`, `/ready`, `/info`, `/metrics` on port `9100`).

| Path | Auth | Purpose |
| - | - | - |
| `{Endpoint}` (default `/mcp`) | Bearer token | Streamable HTTP JSON-RPC. Every MCP tool call. |
| `/health` | None | Liveness probe. Returns `status`, `server`, `version`, `tools_count`. |
| `/info` | Bearer token | Compact server name, version, transport, path, and advertised tool names. |

Default URL on the broker host:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
http://127.0.0.1:6278/mcp
```

The server is **HTTP-only**:

* Transport is **stateless Streamable HTTP**. There is no stdio transport.
* `/sse` and `/message` are **rejected**. There is no SSE compatibility mode.
* Native TLS for this listener is **not** in this release. Bind loopback, or terminate TLS in front of a non-loopback bind.

Authenticated requests send:

```http wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Authorization: Bearer <token>
```

Anonymous MQTT login is **not** inherited. A client with no token gets `401` on `/mcp` and `/info`. The listener still stays up if you enabled it with zero tokens — every request is refused until you mint one.

> [!WARNING]
>
> A bind outside loopback (`0.0.0.0` or a LAN address) sends bearer tokens in the clear. Put TLS in front (a reverse proxy) before exposing the MCP port beyond the broker host.

***

## Docker and Kubernetes

The MCP server has its own HTTP listener. It isn't a path on the MQTT port (`1883`) or the WebSocket port (`5000`). A client URL such as `https://broker.example.com/mcp` reaches it only when the proxy in front of that host sends `/mcp` to port `6278`. A proxy that sends every path to port `5000` delivers the request to the WebSocket listener instead.

Publishing port `6278` isn't enough on its own. Inside a container, `127.0.0.1` is the container's own loopback, so a Docker port mapping or a Kubernetes Service can't reach a listener bound there. The administrator who deploys the broker sets all of these:

| Step | Setting | Why |
| - | - | - |
| Enable | `Mcp.Enabled` or `COREFLUX_MCP_ENABLED=true` | The listener is off by default. Restart the broker after the change. |
| Bind | `Mcp.BindIP` or `COREFLUX_MCP_BIND_IP` set to `0.0.0.0` | The default `127.0.0.1` can't be reached from a published port or from the pod network. |
| Publish | A Docker port mapping, or a container port and Service port `6278` | The broker image and the sample Compose file don't publish `6278`. |
| Route | A proxy or Ingress path `/mcp` to port `6278` | Send only this path to the MCP port. Keep `/` on the WebSocket port. |
| Allow | A firewall or NetworkPolicy rule for `6278`, from the proxy only | A policy that allows only `1883` and `5000` drops MCP traffic. |
| TLS | Terminate TLS on the proxy | The listener speaks plain HTTP, and bearer tokens must not cross the network in the clear. |
| Token | `-createMcpToken`, then `Authorization: Bearer <token>` on the client | `/mcp` doesn't accept anonymous MQTT login. |

If you changed `Port` or `Endpoint`, use those values instead of `6278` and `/mcp`.

**Docker Compose**

Add the MCP port and the two variables to the broker service:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
services:
  broker:
    image: coreflux/coreflux-mqtt-broker:latest
    ports:
      - "1883:1883"
      - "5000:5000"
      - "9100:9100"
      - "127.0.0.1:6278:6278"   # MCP, reached only through the TLS proxy
    environment:
      - COREFLUX_MCP_ENABLED=true
      - COREFLUX_MCP_BIND_IP=0.0.0.0
```

The `127.0.0.1:` prefix keeps the port off the host's public interfaces, so only a proxy on the same host reaches it. A proxy in the same Compose network can use `broker:6278` and needs no published port.

**Kubernetes**

Name the MCP port on the broker container and the Service, then add an Ingress path for `/mcp` next to the WebSocket path:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Broker container
ports:
  - name: mcp
    containerPort: 6278
env:
  - name: COREFLUX_MCP_ENABLED
    value: "true"
  - name: COREFLUX_MCP_BIND_IP
    value: "0.0.0.0"

# Service
ports:
  - name: mcp
    port: 6278
    targetPort: mcp

# Ingress rule on the public host, next to the "/" path to port 5000
paths:
  - path: /mcp
    pathType: Prefix
    backend:
      service:
        name: coreflux-broker
        port:
          number: 6278
```

Let the Ingress terminate TLS. If a NetworkPolicy guards the broker, allow TCP `6278` from the ingress controller's namespace.

`/health` and `/info` are on the same listener. Route them to `6278` too if operators should reach them through the public host. `/info` needs a token. The AI client needs only `/mcp`.

### Check the route

From outside the cluster or host, call `/mcp` without a token:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -i https://broker.example.com/mcp
```

The MCP listener answers `401` with `WWW-Authenticate: Bearer` and asks for a token from `-createMcpToken`. Any other answer, such as a `404` with an empty body, means the request reached a different listener, usually the WebSocket port. Then point the client at the same URL with its bearer token.

***

## Configuration reference

Environment variables override the JSON block. Changes apply on **restart**.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Mcp": {
    "Enabled": true,
    "Port": 6278,
    "BindIP": "127.0.0.1",
    "Endpoint": "/mcp",
    "EnableAllTools": true,
    "EnabledTools": [],
    "TokenLifetimeDays": 0
  }
}
```

| Setting | Required | Default | Description |
| - | - | - | - |
| `Enabled` | Yes, to start | `false` | Master switch. Applied at startup. |
| `Port` | No | `6278` | Listening port for Streamable HTTP. |
| `BindIP` | No | `127.0.0.1` | Bind address. Non-loopback needs TLS in front. |
| `Endpoint` | No | `/mcp` | Streamable HTTP path. Must be an absolute path. `/sse` and `/message` are rejected. |
| `ServerName` | No | `CorefluxBroker` | MCP protocol server name (HUB: **Advanced**). |
| `ServerVersion` | No | Broker version | Sent to the client during discovery. |
| `EnableAllTools` | No | `true` | When `true`, advertise the full MCP surface (registry tools, handwritten tools, capability tools, and `action_*`). When `false`, only names in `EnabledTools`. |
| `EnabledTools` | When `EnableAllTools` is `false` | `[]` | Allow-list of **advertised MCP names** (`add_route`, `get_route_template`). Command tokens such as `-addConnector` and `-addRoute` are also accepted. An empty list advertises nothing. |
| `TokenLifetimeDays` | No | `0` | Default lifetime for newly minted tokens, in days. `0` means no expiry. Per-token `ttlDays` on `-createMcpToken` overrides this. |

### Environment variables

| Variable | Config key |
| - | - |
| `COREFLUX_MCP_ENABLED` | `Enabled` (`1` or `true`) |
| `COREFLUX_MCP_PORT` | `Port` |
| `COREFLUX_MCP_BIND_IP` | `BindIP` |
| `COREFLUX_MCP_ENDPOINT` | `Endpoint` |
| `COREFLUX_MCP_ENABLE_ALL_TOOLS` | `EnableAllTools` |
| `COREFLUX_MCP_ENABLED_TOOLS` | `EnabledTools` (comma- or semicolon-separated) |
| `COREFLUX_MCP_TOKEN_LIFETIME_DAYS` | `TokenLifetimeDays` |

HUB **Advanced** also exposes `ServerName` and `ServerVersion`. Restrict the tool list from HUB with **Expose all tools** off and the allow-list picker — write advertised names (`get_route_template`), not internal command tokens (`route_code`). Add `action_*` names with **Custom tool**.

***

## Bearer tokens

Every MCP HTTP request except `GET /health` requires a broker-issued bearer token. Tool calls run as **the broker user the token was minted for** and are checked against that user's RBAC.

These three commands are operator-only. They are **not** advertised as MCP tools.

| Command | Permission | What it does |
| - | - | - |
| `-createMcpToken <username> <token-name> [ttlDays]` | `McpTokenManagement` | Mint a token. Plaintext returned **once** in `data.token`. |
| `-listMcpTokens [username]` | `McpTokenManagement` | Metadata only: `id`, `name`, `userName`, `created`, `expires`, `lastUsed`, `state`. Never the secret or its hash. |
| `-revokeMcpToken <token-id\|token-name>` | `McpTokenManagement` | Immediate refuse for clients using that token. |

The username must already exist. Removing a broker user also deletes that user's tokens. Token names must not contain whitespace (the command parser splits on spaces).

The locked built-in `AllowMcpTokenManagement` admits `root`, `AllowedUserManagement`, and `AllowedSystemConfiguration` — the same flags as other user-management gates. You cannot override that gate with a custom rule; set permission flags instead. See [Operation scopes](/latest/lot-language/rules/syntax#operation-scopes).

### Create a token

Publish to `$SYS/Coreflux/Command` (or run it from [Command Console](/hub/system/command-console) / the broker console):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-createMcpToken operator cursor-local
```

Optional third argument is lifetime in days (`0` = no expiry), overriding `Mcp.TokenLifetimeDays`.

Success envelope (secret redacted here):

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "CreateMcpToken",
  "entityType": "McpToken",
  "entityName": "cursor-local",
  "data": {
    "token": "cfx_mcp_…",
    "id": "…",
    "name": "cursor-local",
    "userName": "operator",
    "expires": "never"
  }
}
```

Store `data.token` immediately. `-listMcpTokens` will never show it again.

> [!WARNING]
>
> MQTT command replies always go to `$SYS/Coreflux/Command/Output`. The default `AllowSubscribeCommandOutput` audience is **wider** than `McpTokenManagement`, so a user who cannot mint tokens may still read a mint reply. To keep the plaintext off that topic, mint from the broker console or from the HUB MCP tab (HUB keeps the value in the create dialog only). If a token may have been observed, `-revokeMcpToken` and mint again.

Mint for a **least-privilege** account. Do not mint for `root` unless the client should have full operator access.

***

## Point a client at the broker

Put the same JSON shape in the file your client actually reads. `"type": "http"` is optional in Cursor (it infers HTTP from `url`) but **required** in Claude Code and Claude Desktop — without it they skip the entry with no error.

**Cursor**

Project file: `.cursor/mcp.json` (filename is `mcp.json`, not `.mcp.json`). Global fallback: `~/.cursor/mcp.json`.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux-broker": {
      "type": "http",
      "url": "http://127.0.0.1:6278/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

**Claude Code**

Project file: `.mcp.json` at the **repository root** (not under `.claude/`).

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux-broker": {
      "type": "http",
      "url": "http://127.0.0.1:6278/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

**Claude Desktop**

OS app config (`claude_desktop_config.json`), not a file in the repo. `"type": "http"` is required.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux-broker": {
      "type": "http",
      "url": "http://127.0.0.1:6278/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

Do not commit a minted token. After changing the file, start a new Claude Code session. In Cursor, if the server shows resources but **0 tools**, remove the entry, save, and add it back (or quit Cursor) — an empty `tools/list` result can stay cached in memory; reloading the server is not enough.

When the broker binds `0.0.0.0`, `$SYS/Coreflux/MCP/Info` still prints that bind in `http_endpoint`. HUB substitutes the host it is connected to when offering snippets; a loopback bind is copied as written.

***

## What the tools do

A connected client calls `tools/list` on `/mcp`. The exact set is whatever this broker advertises (`/health` `tools_count` and `$SYS/Coreflux/MCP/Tools`). It is not a second copy of `$SYS/Coreflux/Command`.

Typical surface when `EnableAllTools` is `true`:

| Kind | Examples | Notes |
| - | - | - |
| Broker command wrappers | `add_action`, `list_routes`, `load_project` | Most management verbs. Each call runs as the token's user. |
| Things | `add_thing`, `remove_thing`, `list_things` | Wrap `-addThing`, `-removeThing`, and `-listThings`. `add_thing` takes one or more `DEFINE THING` blocks; a leading `--dryRun` returns the plan and changes nothing. |
| Disable and enable | `disable_action`, `enable_action`, `disable_route`, `enable_route`, `disable_agent`, `enable_agent` | Switch an entity off or on without deleting it. See [Disable and enable](/latest/mqtt-broker/commands#disable-and-enable). |
| Discovery helpers | `get_broker_info`, `get_available_commands`, `list_action_tools` | Handwritten; not MQTT command names. |
| Keep-list names | `get_route_template`, `list_route_templates`, `get_panel_code` | Use these in `EnabledTools`, not `route_code` / `list_templates` / `panel_code`. |
| Capability tools | `explore_topics`, `diagnose`, `provision_data_source`, `deploy_lot` | An allow-list must name them **exactly**. `explore` does not enable `explore_topics`. |
| LoT Actions | `action_{name}` | Registered when the MCP server **starts**. Restart the broker after deploying new Actions if they should appear as tools. |

Token, license, and password commands are **never** advertised (`-createMcpToken`, `-listMcpTokens`, `-revokeMcpToken`, `-changeUserPassword`, `-activateLicense`, `-loadLicense`, `-refreshLicense`, `-enroll`).

User-management tools (`add_user`, `remove_user`, `change_user_settings`, `add_user_to_group`, `remove_user_from_group`) **are** on the default surface. `add_user` takes a password in its arguments — chat transcripts will see it. Mint the token for a user without user-management permission, or turn `EnableAllTools` off and omit those names.

List-shaped tools default to a concise page of 50 items (`items`, `total`, `next_cursor`). Pass `response_format=detailed` for full objects.

> **Capability tools**
>
> | Tool | Purpose |
> | - | - |
> | `explore_topics` | Paginated MQTT topic listing with JSON schema inference. Does not wait for live publishes. |
> | `diagnose` | Connection status, Action errors, and pending status. Takes **no** arguments. |
> | `provision_data_source` | Add an OT or database connector from LoT (`route_type`, `name`; optional `definition`). |
> | `deploy_lot` | Deploy `DEFINE ACTION` / `MODEL` / `CONNECTOR` (or `ROUTE`) / `AGENT` / `RULE` / `THING` blocks in one call. Agent blocks go through `-addAgent`, and consecutive `DEFINE THING` blocks are sent as one `-addThing`. On first failure it rolls back entities **this call** created or overwrote. |
>
> `lot_diagnostic` is a **process-wide** tracing toggle (`true` / `false`), not a per-entity report. Use `diagnose` for health and Action error topics for compile failures.

> **Resources and prompts**
>
> Clients can call `resources/list` and `resources/read`. There is no `resources/subscribe` (the server is stateless). Unknown URIs return JSON-RPC `-32602` (Invalid params).
>
> | URI | Contents |
> | - | - |
> | `coreflux://topics` | First concise page of the topic tree |
> | `coreflux://topics/{topic}` | One topic snapshot (`/` in the topic is URI-escaped as `%2F`) |
> | `coreflux://lot/{kind}` | LoT inventory (`actions`, `models`, `routes`, `agents`, `rules`, `things`) |
> | `coreflux://lot/{kind}/{name}` | One entity definition |
> | `coreflux://skills` | Agent skill catalogue |
> | `coreflux://skills/{name}` | Full skill body |
>
> To install the public skill set straight into a coding agent instead, see [Agent Skills](/ai/agent-skills).
>
> Reads require `CommandCall` on the token's user. Topic URIs are filtered again by that user's subscribe rules (`Subscribe` / `SubscribeSys`).
>
> `prompts/list` advertises `lot_authoring` (optional `entity_type`: `action`, `model`, `route`, `rule`).

***

## System topics

When the MCP host starts or stops, it republishes two **retained** topics. Neither payload includes token values, hashes, or the usernames tokens map to.

### `$SYS/Coreflux/MCP/Info`

The live payload lists every advertised tool name. The sample below is abbreviated.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "server_name": "CorefluxBroker",
  "server_version": "2.22.0",
  "transport_type": "http",
  "http_endpoint": "http://127.0.0.1:6278/mcp",
  "http_port": 6278,
  "bind_ip": "127.0.0.1",
  "total_tools": 2,
  "tools": ["add_action", "list_routes"],
  "tokens_active": 1,
  "auth": "bearer",
  "status": "running",
  "connection_info": "Connect via Streamable HTTP at http://127.0.0.1:6278/mcp with an Authorization: Bearer header.",
  "timestamp": "2026-09-21T10:00:00.000Z"
}
```

`status` is `running` or `stopped`. A clean shutdown republishes `stopped` so a stale retain does not claim the server is up.

### `$SYS/Coreflux/MCP/Tools`

An array of `{ "name": "…" }` objects — currently advertised MCP names only, not the full possible catalogue. When `EnableAllTools` is false and `EnabledTools` is empty, this topic is an empty list.

> [!NOTE]
>
> These topics are `$SYS`. Subscribe with an identity that is allowed to read system topics (MQTT Explorer as an admin user). HUB maps `status: "running"` to **Listening**. If Info is missing after a saved, applied `Mcp.Enabled: true`, HUB still treats the server as Listening rather than as another pending restart.

The ops HTTP `/info` on port **9100** (separate from MCP `/info` on **6278**) includes a compact `mcp` object when the feature is enabled (`enabled`, `endpoint`, `bind`, `port`, `toolsCount`, `tokensActive`, `auth`) — still no token secrets. See [Operational endpoints](/latest/mqtt-broker/operational-endpoints#cluster-and-mcp-summaries).

***

## Moving off `TYPE MCP_SERVER` and SSE

A saved project that still carries `DEFINE CONNECTOR … WITH TYPE MCP_SERVER` or `DEFINE ROUTE … WITH TYPE MCP_SERVER` **fails to load** with a message that the type was removed. The MCP *client* connector (`TYPE MCP`, `ADD MCP_CONFIG`, `CALL MCP`) is unchanged.

**Action:**

1. Remove the `TYPE MCP_SERVER` definition from the project.
2. Enable `Mcp.Enabled` (or `COREFLUX_MCP_ENABLED=1`) and restart the broker.
3. Mint a token: `-createMcpToken <username> <token-name>`.
4. Point the client at `http://127.0.0.1:6278/mcp` (or your bind, port, and endpoint) with `Authorization: Bearer <token>`.

| Before (broken) | After |
| - | - |
| URL `http://127.0.0.1:6278/sse` | URL `http://127.0.0.1:6278/mcp` |
| Separate `/message` URL | Same `/mcp` path for every JSON-RPC POST |
| `WITH TRANSPORT_TYPE "sse"` on `TYPE MCP_SERVER` | `Mcp.Enabled`; transport is HTTP-only |
| `WITH SSE_ENDPOINT` / `WITH MESSAGE_ENDPOINT` | `Mcp.Endpoint` (default `/mcp`) |

There is no compatibility mode. Every existing `/sse` client configuration stops working.

***

## Best practices

> **Least-privilege tokens**
>
> Mint a dedicated broker user for the assistant. Leave user-management and `AllowedSystemConfiguration` off unless the client must administer the broker. Prefer `EnableAllTools: false` plus an allow-list of the tools that job needs.

> **Loopback first**
>
> Keep `BindIP` at `127.0.0.1` when the AI client runs on the same host as the broker. Only bind a LAN address when a remote client must connect, and terminate TLS in front. In a container, bind `0.0.0.0` and reach the port only through the TLS proxy. See [Docker and Kubernetes](#docker-and-kubernetes).

> **Treat mint replies as secrets**
>
> Prefer the HUB create-token dialog or the broker console over MQTT when other administrators share `$SYS/Coreflux/Command/Output`. Revoke and re-mint if a token may have leaked into a chat log.

> **Do not confuse health ports**
>
> MCP `/health` is on the MCP port (default `6278`). Orchestrator probes for the broker process still use ops `/health` on port `9100`. See [Operational endpoints](/latest/mqtt-broker/operational-endpoints).

> [!WARNING]
>
> The MCP server does not speak OAuth 2.0 / OIDC. Identity is the minted bearer token only. An [OIDC access token](/latest/mqtt-broker/oidc-authentication) used as an MQTT password is a different credential and is not accepted on `/mcp`. Don't publish the MCP port directly on the internet. Reach it only through a proxy that terminates TLS.

***

## Next Steps

> **[MCP Connectors](/latest/lot-language/routes/mcp-routes)**
>
> Connect the broker as a client to external MCP servers and call their tools from LoT Actions.

> **[System Configuration](/hub/system/configuration#mcp)**
>
> Enable the listener and mint tokens from the Coreflux HUB MCP tab.


# OIDC and Bearer Authentication
Source: https://docs.coreflux.org/latest/mqtt-broker/oidc-authentication

Let MQTT clients connect with an OIDC access token as the password, and authorize them with the same LoT rules as local users

MQTT clients can sign in with an access token from an OIDC identity provider instead of a password stored on the broker. The broker checks the token, then applies the same LoT (Language of Things) rules it uses for a local user.

> [!TIP]
>
> **Like a badge that expires.** The client shows a badge (the access token) at the door. The broker checks the badge with the issuer, lets the person in as the identity printed on it, and asks them to leave when the badge expires.

## When to use token authentication

Use it when people and services already have identities outside the broker:

* **Coreflux accounts** — Operators sign in to [Coreflux HUB](/hub/account-and-fleet) with their organization account and connect to a broker in the fleet. The HUB presents that account's access token. The broker accepts it only after [enrollment](/latest/mqtt-broker/licensing) has bound the broker to the same organization.
* **A provider you run** — Point `Issuers` at an identity provider that publishes a discovery document over HTTPS and signs access tokens with RS256.

Leave it off when every client uses a username and password in the broker's user store. It is **off by default**.

Local users keep working. A CONNECT whose password is not a token is still checked against the user store.

***

Token checks run at MQTT CONNECT. Enabling them is a broker configuration change, and the broker reads that configuration at startup.

## Quick Start

**Coreflux organization**

A broker enrolled in a Coreflux organization accepts account tokens for that organization. Enrollment fills `BoundOrg`; until that succeeds, token logins are refused and local users still connect.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "AnonymousLogin": false,
  "Oidc": {
    "Enabled": true,
    "Issuers": ["https://accounts.example.com"],
    "ClientIdAllowlist": ["hub-desktop"],
    "RequiredScope": "coreflux-broker/connect"
  }
}
```

Replace `Issuers` with the issuer URL of the account tokens you accept. List every `client_id` exactly — `hub-desktop` is the id the broker's account-token contract uses for the desktop HUB. There is no wildcard. With enrollment turned on and `BoundOrg` still empty, the broker starts and refuses token logins until enrollment writes the organization id. With enrollment off, set `BoundOrg` yourself or the broker will not start. Restart after editing the file.

**Your own identity provider**

When the issuer serves only this broker's users, declare it in `DedicatedIssuers`. `BoundOrg` can stay empty, and group names on the token are used as written.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "AnonymousLogin": false,
  "Oidc": {
    "Enabled": true,
    "Issuers": ["https://idp.example.com"],
    "DedicatedIssuers": ["https://idp.example.com"],
    "ClientIdAllowlist": ["plant-mqtt"],
    "RequiredScope": "",
    "RequiredClaimsVersion": ""
  }
}
```

The token must still be an **access** token (`token_use` = `access`), signed with RS256, and its `client_id` claim must be in the allowlist. Empty `RequiredScope` and `RequiredClaimsVersion` skip those checks. Group names are read from `coreflux:groups` as a space-separated string. On a dedicated issuer, a name with no organization prefix is kept as-is. Restart the broker after editing the file.

> [!NOTE]
>
> There is no `COREFLUX_OIDC_*` environment variable on the broker. These fields live in the broker configuration file (the same JSON as [ports and TLS](/latest/mqtt-broker/configuration)). `BoundOrg` is the exception: a successful [enrollment](/latest/mqtt-broker/licensing#quick-start) writes the organization id into it.

## What the client sends

On CONNECT, put the access token in the **password**. An optional `Bearer ` prefix is accepted. The broker does not read the CONNECT username as the identity — the identity is the token's subject claim (`sub` unless you change `UsernameClaim`).

| CONNECT field | What to send |
| - | - |
| Password | The access token, or `Bearer ` followed by the token |
| Username | Any value your client requires. It is not the broker username |

A password that is not shaped like a token (three non-empty segments separated by `.`) stays on the local user-store path.

The Coreflux HUB does this when you **Connect** on a fleet row. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).

Use MQTT over TLS (`mqtts://` or `wss://`) whenever the token leaves the broker host. OIDC does not encrypt the MQTT connection. A plaintext listener carries the access token in the CONNECT password. Mutual TLS is a separate check — it does not replace the token, and the token does not replace it. See [TLS Server Certificate](/latest/mqtt-broker/configuration#tls-server-certificate).

## How the broker decides

When `Oidc.Enabled` is true and the password looks like a token:

1. The broker loads the issuer's discovery document over HTTPS and checks the RS256 signature, the issuer, and the expiry.
2. It requires `token_use` = `access`. An ID token is refused.
3. It requires the `client_id` claim to be in `ClientIdAllowlist`.
4. If `RequiredScope` is set, that exact scope must appear in the token's space-separated `scope` list. Coreflux account tokens from the HUB request `coreflux-broker/connect`.
5. If `RequiredClaimsVersion` is set (default `1`), the `coreflux:claims_version` claim must match it.
6. If `BoundOrg` is set, that organization id must appear in the space-separated `coreflux:orgs` claim. An empty `BoundOrg` refuses the token unless the issuer is listed in `DedicatedIssuers`.
7. Groups and roles are read from `coreflux:groups` and `coreflux:role`. On a bound broker they must be prefixed with the organization id (`org_…:engineers`). The broker strips that prefix and authorizes the plain name.

A discovery or key outage **refuses** the connection. It does not fall through to anonymous access.

### Identity and rules

The session is not written to the local user store. HUB User Management and `-listUsers` still show local accounts only.

| What a rule sees | Source |
| - | - |
| `USER IS "…"` | `UsernameClaim`, default `sub` |
| `USER IN GROUP "engineers"` | De-qualified name from `coreflux:groups` for `BoundOrg` |
| `USER HAS AllowedSystemConfiguration` | True only when `AdminRoles` or `AdminGroups` matches |

The display name (`preferred_username` by default) is written to login logs. Rules never match it. A rule written against an email address does not match a subject id.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE EngineersPublish WITH PRIORITY 200 FOR Publish TO TOPIC "plant/status/#"
    IF USER IN GROUP "engineers" THEN
        ALLOW
    ELSE
        DENY
```

Custom rules like this one require a Growth or Enterprise license. On Community, set `AdminRoles` or `AdminGroups` instead: a matching token receives `AllowedSystemConfiguration`, `AllowedUserManagement`, and `AllowedLogManagement`, which the shipped rules already allow. Both lists are empty by default, so a Coreflux account is **not** an administrator until you name the role or group. Use the plain name (`owner`), not `org_…:owner`.

Group and role changes apply on the next token. The live session keeps the groups it connected with until it is disconnected.

See [RBAC with LoT Rules](/latest/lot-language/rules/rbac#federated-accounts).

### Token lifetime

`DisconnectOnExpiry` is on by default. When the access token expires, the broker waits `ExpiryGraceSeconds` (default 30) and then disconnects the client. On MQTT 5 the disconnect reason is `NotAuthorized`. The client connects again with a fresh token. That window is how a revoked account loses MQTT access: there is no separate revocation list.

Signature checks allow `ClockSkewSeconds` of clock difference (default 60).

## Configuration reference

All fields sit under `Oidc` in the broker configuration file. Restart the broker after a change. Turning `Enabled` on forces `AnonymousLogin` off, even if the file still says `true`.

| Field | Default | Required when enabled | Purpose |
| - | - | - | - |
| `Enabled` | `false` | — | Turn token authentication on |
| `Issuers` | empty | Exactly one HTTPS issuer URL | Discovery and signature keys. More than one issuer refuses to start |
| `DedicatedIssuers` | empty | No | Issuers that serve a single organization. Only these may run with an empty `BoundOrg` |
| `ClientIdAllowlist` | empty | Yes, at least one id | Exact `client_id` values. Empty refuses to start |
| `RequiredScope` | empty | No | Exact scope string. Empty skips the check |
| `RequiredClaimsVersion` | `1` | No | Expected `coreflux:claims_version`. Empty skips the check |
| `BoundOrg` | empty | Yes for a shared issuer | Organization id that must appear in `coreflux:orgs`. Enrollment sets this |
| `OrgsClaim` | `coreflux:orgs` | No | Claim holding organization ids |
| `GroupsClaim` | `coreflux:groups` | No | Claim holding `orgId:group` names |
| `RoleClaim` | `coreflux:role` | No | Claim holding `orgId:role` names. Used only for `AdminRoles` |
| `ClaimsVersionClaim` | `coreflux:claims_version` | No | Claim holding the contract version |
| `UsernameClaim` | `sub` | No | Session identity for `USER IS` |
| `DisplayNameClaim` | `preferred_username` | No | Label in logs. Empty disables it. Never used for authorization |
| `AdminRoles` | empty | No | Plain role names that receive the three admin permission flags |
| `AdminGroups` | empty | No | Plain group names that receive the same flags. Compared case-insensitively |
| `GroupsSeparator` | space | No | Separator for the list claims |
| `ClockSkewSeconds` | `60` | No | Allowed clock difference for expiry |
| `DisconnectOnExpiry` | `true` | No | Disconnect when the access token expires |
| `ExpiryGraceSeconds` | `30` | No | Extra seconds after expiry before disconnect |

> [!WARNING]
>
> An enabled configuration with no issuer, more than one issuer, an empty `ClientIdAllowlist`, or a shared issuer and an empty `BoundOrg` **refuses to start**. The exception is enrollment: if enrollment is on and `BoundOrg` is not known yet, the broker starts, serves local users, and refuses token logins until enrollment writes the organization id. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

## Failure modes

| What you see | Cause |
| - | - |
| Broker will not start, log says the allowlist is empty or `BoundOrg` is not set | Fix `Oidc` or finish enrollment. A shared issuer with no organization binding is rejected on purpose |
| MQTT 5 `BadUserNameOrPassword` | The password looked like a token and validation failed: bad signature, expired, wrong issuer, ID token, `client_id` not allowed, scope missing, claims version mismatch, organization mismatch, or a group entry naming an organization the token does not list |
| MQTT 5 `ServerUnavailable` | The broker could not fetch the issuer's discovery document or signing keys. The connection is denied |
| MQTT 5 `NotAuthorized` after a successful token check | A `FOR Connect` rule denied the session, or the broker required a clean session the client did not request |
| Disconnect with `NotAuthorized` after the token lifetime | `DisconnectOnExpiry` dropped the client. Reconnect with a new access token |
| `USER IS` never matches the person's email | The identity is `sub`. Match a group, or set `UsernameClaim` only if that claim is stable and unique |
| A local password is rejected as a bad token | The password contained two dots and three non-empty segments, so it took the token path |

Login attempts are published on [`$SYS/Coreflux/Comms/Logins`](/latest/mqtt-broker/sys-topics#syscorefluxcommslogins). For a token login, `Username` is the subject and `DisplayName` is the display-name claim. The password is not included.

## How this fits with the portal

[portal.coreflux.org](https://portal.coreflux.org) is where an organization gets a license and registers brokers. Enrollment tells **this** broker which organization it belongs to (`BoundOrg`). The HUB fleet view lists those brokers for people signed in with an account in that organization. **Connect** on a fleet row sends that account's access token to the broker. LoT rules then see the groups on the token.

A license plan and an organization binding are different steps. The plan is [activation](/latest/mqtt-broker/licensing). The binding is enrollment. Token login needs the binding when the issuer is shared.

***

## Best practices

> **Prefer groups over subject ids**
>
> Subject ids are opaque. Write `USER IN GROUP` rules for the names your identity provider puts on the token, and keep `UsernameClaim` on `sub`.

> **Put tokens on TLS listeners**
>
> The access token is the CONNECT password. Expose `8883` and `443` on the broker host, and keep `1883` off untrusted networks.

> **Keep the client allowlist short**
>
> Every id in `ClientIdAllowlist` can present a token this broker will try to accept. Add a service client only for the job that needs MQTT.

> **Do not confuse this with MCP tokens**
>
> [MCP Server](/latest/mqtt-broker/mcp-server) bearer tokens are minted by the broker for HTTP `/mcp`. They are not OIDC access tokens, and an OIDC token is not an MCP token.

> [!WARNING]
>
> The broker accepts RS256 access tokens only, and it requires the `token_use` claim to equal `access`. There is no setting to allow another algorithm or to skip that claim. An identity provider that omits `token_use` or `client_id` cannot authenticate MQTT clients until its tokens include them.

## Next Steps

> **[Account, fleet, and Cloud mode](/hub/account-and-fleet)**
>
> Sign in to the HUB with a Coreflux account and connect to brokers in the organization.

> **[RBAC with LoT Rules](/latest/lot-language/rules/rbac#federated-accounts)**
>
> Authorize token sessions with groups and permission flags.


# Operational Endpoints
Source: https://docs.coreflux.org/latest/mqtt-broker/operational-endpoints

Probe liveness, readiness, license status, and Prometheus metrics on the broker's dedicated HTTP port

## Check the broker without opening MQTT

Orchestrators and monitoring systems need a plain HTTP answer: is the process up, is it accepting clients, and what is it doing. The Coreflux MQTT Broker serves that on a **dedicated ops port** (default `9100`), separate from MQTT and from the WebSocket data plane.

> [!TIP]
>
> **Like a side door for the building inspector.** Devices still use the front door (MQTT). Kubernetes and Prometheus use the side door, a small HTTP port that only answers health and status questions.

Use these endpoints when you need to:

* tell a container orchestrator when to restart the process, and when to send it traffic;
* scrape broker gauges and counters into Prometheus;
* read version, ports, and license status from the broker host without an MQTT login.

The listener is **unauthenticated**. Keep port `9100` on a private network. See [Security](#security).

***

These paths answer only on the ops port. The same path on the WebSocket / HTTP port (default `5000`) returns **404**.

## Endpoints

| Method | Path | Success | What you get |
| - | - | - | - |
| `GET` | `/health`, `/healthz` | `200` | Liveness. Always healthy while the process is serving. |
| `GET` | `/ready`, `/readyz` | `200` or `503` | Readiness. `503` until startup has finished **and** MQTT is accepting connections. |
| `GET` | `/info` | `200` | Build, runtime, ports, and short summaries. No secrets. |
| `GET` | `/license` | `200` | License tier, limits, usage, fingerprint, activation, and enrollment. |
| `GET` | `/metrics` | `200` | Prometheus text. |
| `GET` | `/cluster` | `200` | High-availability summary. Clustering off is still `200`. |
| `GET` | `/cluster/trace` | `200` | Replication trace of QoS 1 and 2 messages on the broker host. |
| `GET` | `/loglevel` | `200` | Current minimum log level. |
| `POST` | `/loglevel` | `200` or `400` | Change the minimum log level until the next restart. |

All JSON responses use camelCase property names.

## Liveness

`GET /health` (alias `/healthz`) means the process is up and answering HTTP. It does **not** mean MQTT is accepting clients. Use `/ready` for that.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "status": "healthy",
  "version": "2.14.0",
  "timestamp": "2026-09-28T10:00:00Z"
}
```

| Field | Meaning |
| - | - |
| `status` | Always `healthy` on this path. |
| `version` | Broker version string. |
| `timestamp` | UTC time of the response (`yyyy-MM-ddTHH:mm:ssZ`). |

## Readiness

`GET /ready` (alias `/readyz`) returns `200` only when **both** are true:

1. The broker application has finished starting.
2. The MQTT server is accepting connections.

Until then the status is **503**.

Ready:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "status": "ready",
  "timestamp": "2026-09-28T10:00:00Z"
}
```

Not ready:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "status": "not_ready",
  "reason": "MQTT server is not accepting connections yet",
  "timestamp": "2026-09-28T10:00:00Z"
}
```

| `reason` | When |
| - | - |
| `application is still starting` | The process is up, but startup has not finished. |
| `MQTT server is not accepting connections yet` | Startup finished, and the MQTT listener is not up yet. |

Point a Kubernetes **liveness** probe at `/health` and a **readiness** probe at `/ready`. A liveness probe on `/ready` restarts the broker during a normal startup.

## Runtime info

`GET /info` is a single JSON document: name, version, uptime, operating system, Python sandbox, cluster and MCP summaries, telemetry status, listener ports, and the CPU, memory, and GC view the process actually has. It does not include passwords, tokens, license files, or the cluster shared secret.

A standalone broker (clustering and MCP off, census not yet pinged) has this shape. `runtimeResources` below is trimmed to the CPU and GC fields operators compare first; the live document also includes process memory, the thread pool, container signals, and cgroup data.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "name": "Coreflux DataHub",
  "version": "2.14.0",
  "uptimeSeconds": 1234.5,
  "timestamp": "2026-09-28T10:00:00Z",
  "os": {
    "type": "Linux",
    "version": "Debian GNU/Linux 13",
    "architecture": "X64",
    "framework": ".NET 10.0"
  },
  "python": {
    "available": true,
    "mode": "coreflux-runner",
    "version": "3.12.0",
    "backend": "linux-native",
    "isolationLevel": "OsNamespaces"
  },
  "cluster": { "enabled": false },
  "mcp": { "enabled": false },
  "telemetry": {
    "enabled": true,
    "reason": null,
    "lastPingAt": null,
    "lastStatus": null
  },
  "ports": {
    "mqtt": 1883,
    "mqttTls": 8883,
    "websocket": 5000,
    "websocketTls": 443,
    "ops": 9100
  },
  "runtimeResources": {
    "runtime": {
      "processorCount": 2,
      "is64BitProcess": true,
      "enableWriteXorExecute": true
    },
    "gc": {
      "isServerGc": true,
      "configuration": { "ServerGC": true }
    }
  }
}
```

`name` is the broker configuration name (`Coreflux MQTT Broker` if that name is unset). `ports` reflects the listeners in effect, including `ops`. `uptimeSeconds` is `0` when the process start time cannot be read.

### Python sandbox

| `available` | `mode` | `backend` | `isolationLevel` | Meaning |
| - | - | - | - | - |
| `false` | `null` | `null` | `null` | Python execution is unavailable. |
| `true` | `coreflux-runner` | Reported by the runner, or `unknown` | Reported by the runner, or `unknown` | Scripts run in the sandboxed runner. `unknown` means the runner has not answered yet. |
| `true` | `in-process` | `python.net` | `none` | Legacy in-process Python, with no sandbox boundary. |

### Cluster and MCP summaries

`cluster` is `{ "enabled": false }` when high-availability clustering is off. When it is on, the summary is `enabled`, `clusterId`, `node`, `role` (lowercase), `isLeader`, `leader`, and `members` (the member count). While a configured cluster fails to start, it is `enabled: false` with `configured: true` and a `startFailure` block. Full status is [`GET /cluster`](#cluster-status).

`mcp` is `{ "enabled": false }` when the [MCP Server](/latest/mqtt-broker/mcp-server) is off. When it is on, the summary is:

| Field | Meaning |
| - | - |
| `enabled` | `true` |
| `endpoint` | Full URL, such as `http://127.0.0.1:6278/mcp` |
| `bind` | Bind address |
| `port` | MCP listen port |
| `toolsCount` | Tools currently advertised |
| `tokensActive` | How many tokens exist — never the token values or the usernames they map to |
| `auth` | `bearer` |

That object is not the MCP listener. MCP `/health` and MCP `/info` stay on the MCP port (default `6278`).

### Telemetry summary

`telemetry` is the anonymous install-census status. It does not include an install id, hostname, or license.

| Field | Meaning |
| - | - |
| `enabled` | `true` when the daily census is allowed to run. |
| `reason` | Why it is off: `starting` before the check finishes, `COREFLUX_TELEMETRY`, `DO_NOT_TRACK`, or `Telemetry.Enabled`. `null` when it is on. |
| `lastPingAt` | UTC time of the last attempt, or `null` before the first one. |
| `lastStatus` | HTTP status from the platform, or `timeout` / `error`. `null` before the first attempt. |

Set `COREFLUX_TELEMETRY` to `off`, `false`, or `0` to turn the census off. `COREFLUX_TELEMETRY` affects only the census. `DO_NOT_TRACK=1` turns off the census and also turns off [fleet performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics). `Telemetry.Enabled: false` in the broker configuration turns the census off too. The environment is checked first.

### Runtime resources

`runtimeResources` is the live view of CPU, memory, garbage collection, the thread pool, and (on Linux) cgroup limits. The fields operators compare most often:

| Field | Meaning |
| - | - |
| `gc.configuration.ServerGC` | Server GC as **requested**. A `DOTNET_gcServer` or `COMPlus_gcServer` value wins; otherwise this is the mode baked in at publish. |
| `gc.isServerGc` | The mode **actually in effect**. |
| `runtime.processorCount` | Processors the runtime can see. |
| `runtime.enableWriteXorExecute` | Effective write-xor-execute mode for generated code. `false` on `linux-arm` / ARMv7 publishes, `true` on other targets, unless `DOTNET_EnableWriteXorExecute` or `COMPlus_EnableWriteXorExecute` overrides it. |
| `cgroup` | Linux cgroup files the process could read (CPU quota, memory max, cpuset). Empty off Linux. Keys look like `cpu.max (/sys/fs/cgroup/cpu.max)`. |

`ServerGC` and `isServerGc` disagree when the runtime silently drops to workstation GC. That happens when only one processor is visible: a one-CPU container, a cgroup quota of one core, or a Kubernetes `limits.cpu` of `1` or less (`500m` is one processor). Give the broker at least two CPUs to keep Server GC, and confirm with `processorCount` and `cgroup`.

The same object also includes process memory (`process`), thread-pool counts (`threadPool`), container signals (`container`), and `dotNetEnv` — only `DOTNET_GC*`, `DOTNET_ThreadPool*`, `COMPlus_*`, `DOTNET_EnableWriteXorExecute`, and `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT`. Broker passwords and tokens are not in this document.

## License status

`GET /license` returns the license status: tier, limits, usage, fingerprint, activation, and enrollment. A broker with no license still answers, with `tier` `Community`.

HTTP property names are **camelCase**. The retained MQTT topic `$SYS/Coreflux/License` carries the same status with PascalCase names (`Tier`, `EffectiveLimits`), except `isTrial`, which is lowercase on both. Field meanings are on [Licensing and Enrollment](/latest/mqtt-broker/licensing#watch-license-status).

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "licensedTo": "N/A",
  "expiresUtc": null,
  "secondsToExpiry": null,
  "isActive": false,
  "tier": "Community",
  "isTrial": false,
  "fingerprint": "…",
  "fingerprintSource": "machine-id",
  "activation": {
    "mode": "offline",
    "bindingOk": true,
    "tamperDetected": false
  },
  "enrollment": {
    "pending": false,
    "reason": null,
    "enrolled": false,
    "boundOrg": null
  },
  "effectiveLimits": {
    "maxArtifacts": 24,
    "maxRoutes": 3,
    "maxConnections": 10000
  },
  "currentUsage": {
    "artifactCount": 4,
    "routes": 1
  }
}
```

`effectiveLimits` also includes `maxModels`, `maxRules`, `maxActions`, `maxVisus`, and `maxCertInTls`. `currentUsage` also includes `actions` (regular actions, route events, Python scripts), `models`, `rules`, and `panels`. Connector counts still use the name `routes`.

If the status cannot be read, the response is **500**:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "error": "failed to read license status",
  "detail": "…"
}
```

> [!WARNING]
>
> `GET /license` is unauthenticated. It exposes the hardware fingerprint, plan, and enrollment state. Do not publish port `9100` on the public internet. Bind it to `127.0.0.1` when only local probes need it. MQTT clients that already authenticate can read the same status on `$SYS/Coreflux/License`.

## Metrics

`GET /metrics` returns Prometheus text exposition format, version 0.0.4 (`text/plain; version=0.0.4; charset=utf-8`).

A scrape still succeeds if the live client list cannot be read. In that case `coreflux_clients_connected`, `coreflux_sessions_total`, and `coreflux_retained_messages_total` are `0`.

| Metric | Type | Meaning |
| - | - | - |
| `coreflux_up` | gauge | `1` while the process is running. |
| `coreflux_ready` | gauge | `1` when the broker is ready to accept MQTT traffic (same rule as `/ready`). |
| `coreflux_uptime_seconds` | gauge | Process uptime, in seconds. |
| `coreflux_clients_connected` | gauge | MQTT clients connected right now. |
| `coreflux_sessions_total` | gauge | Active MQTT sessions. |
| `coreflux_retained_messages_total` | gauge | Retained messages held. |
| `coreflux_messages_published_total` | counter | Application messages clients published to the broker since process start. |
| `coreflux_messages_delivered_total` | counter | Application messages the broker delivered to clients since process start. |
| `coreflux_subscriptions_total` | counter | `$SYS` topic subscriptions since the daily stats reset. Data-topic subscriptions are not counted. |
| `coreflux_bytes_sent_total` | counter | Bytes sent since process start. |
| `coreflux_bytes_received_total` | counter | Bytes received since process start. |
| `coreflux_cpu_usage_ratio` | gauge | Process CPU over the last second, as a fraction of one (0–1). When a cgroup CPU quota is set, the fraction is of that quota; otherwise it is of all cores. `NaN` for the first second after start. |
| `coreflux_auth_failures_total` | counter | CONNECTs the broker refused, for any reason (bad credentials, a reserved client id, connect rules, or session expiry). |
| `coreflux_acl_denied_total` | counter | Publishes and subscriptions refused by the ACL. The `op` label is `publish` or `subscribe`. |
| `coreflux_rate_limited_total` | counter | Publishes refused by the per-client rate limit. |
| `coreflux_route_dropped_total` | counter | Messages shed by a saturated route channel. |
| `coreflux_errors_total` | counter | Failures in routes, LoT actions, LoT models, and Python scripts. The `component` label is `route`, `action`, `model`, or `python`. |
| `coreflux_process_memory_bytes` | gauge | Process working set, in bytes. |
| `coreflux_gc_heap_bytes` | gauge | Managed heap size, in bytes. |

> [!NOTE]
>
> Counters other than `coreflux_subscriptions_total` count from process start and return to zero only when the broker restarts, so Prometheus `rate()` and `increase()` work across midnight. In earlier releases, `coreflux_messages_published_total`, `coreflux_bytes_sent_total`, and `coreflux_bytes_received_total` followed the daily stats file (`FluxCapacitorStats_*.json`) and dropped to zero at UTC midnight. That daily file still keeps its per-day totals. `coreflux_subscriptions_total` still counts `$SYS` subscriptions since the daily stats reset.
>
> The same counters feed an enrolled broker's [fleet performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics). They keep updating whether or not fleet metrics are turned on.

### When durability or clustering is active

Each family below always includes an `*_enabled` gauge (`0` or `1`). The rest of the family is emitted only while that feature is active.

| Family | When you see more than the enabled gauge | Where to read the feature |
| - | - | - |
| `coreflux_durability_enabled`, `coreflux_wal_*`, `coreflux_durable_*` | [MQTT state durability](/latest/mqtt-broker/durability) is active (WAL appends, fsyncs, durable retained messages, sessions, and queued QoS 1/2). | Durability |
| `coreflux_cluster_*`, `coreflux_partitions_*`, `coreflux_partition_*`, `coreflux_replication_*` | [High-availability clustering](/latest/mqtt-broker/clustering) is on. Includes leadership, member counts, Raft progress, partition ownership, quorum replication, rejected publishes, delivery to other nodes, and failover. | Clustering |

## Cluster status

`GET /cluster` is the [high-availability clustering](/latest/mqtt-broker/clustering) (beta) view of one node. It never includes the cluster shared secret. Ask the leader for the authoritative view of the other nodes: only the leader checks whether members are alive, so a follower reports other nodes as `unknown`.

The answer has one of three shapes.

**Clustering off**

Clustering is disabled, not granted by the license, its configuration is invalid (the log names the problem), or the node is still starting:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "enabled": false,
  "message": "Clustering is not enabled on this node.",
  "timestamp": "2026-10-04T10:00:00Z"
}
```

**Start failing**

Clustering is configured but could not start, for example because `AdvertisedHost` does not resolve, the cluster port is in use, or the data directory is not writable. Until it starts, the node serves its clients but is not part of the cluster. It retries after 5 s, then with doubling delays up to one minute; a rising `attempts` means the cause persists:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "enabled": false,
  "configured": true,
  "message": "Clustering is configured but failed to start; this node is not part of the cluster. Retrying.",
  "startFailure": {
    "error": "Cluster: could not resolve the advertised host 'broker-a' within 30s; set Cluster.AdvertisedHost to an address peers can reach.",
    "attempts": 3,
    "firstFailedAt": "2026-10-04T10:00:00Z",
    "lastFailedAt": "2026-10-04T10:01:10Z",
    "nextAttemptAt": "2026-10-04T10:01:50Z"
  },
  "timestamp": "2026-10-04T10:01:20Z"
}
```

**Running**

A healthy member of a 3-node cluster (trimmed):

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "enabled": true,
  "identity": { "clusterId": "factory-floor", "node": "broker-a", "endpoint": "10.0.0.11:9200" },
  "leadership": { "role": "leader", "isLeader": true, "leader": "broker-a" },
  "raft": { "term": 7, "commitIndex": 25, "lastAppliedIndex": 25, "hasState": true, "standby": false, "standbyRecoveries": 0, "logReset": null, "quorumSize": 2 },
  "members": [
    { "name": "broker-a", "endpoint": "10.0.0.11:9200", "isSelf": true, "isLeader": true, "status": "alive" },
    { "name": "broker-b", "endpoint": "10.0.0.12:9200", "isSelf": false, "isLeader": false, "status": "alive" },
    { "name": "broker-c", "endpoint": "10.0.0.13:9200", "isSelf": false, "isLeader": false, "status": "alive" }
  ],
  "membersTotal": 3,
  "membersAlive": 3,
  "partitions": { "enabled": true, "mapVersion": 14, "partitionCount": 32, "replicationFactor": 3, "underReplicated": 0 },
  "replication": { "enabled": true, "quorumGateEnabled": true, "connectedPeers": 2, "quorumFailures": 0, "lastQuorumMicros": 2446 },
  "timestamp": "2026-10-04T10:05:00Z"
}
```

When clustering is running, the document has these blocks:

| Block | What it shows | What to look for |
| - | - | - |
| `identity` | `clusterId`, this `node`, and the `endpoint` the other nodes use to reach it | `endpoint` matches how the other nodes list this node in `members` |
| `leadership` | `role` (`leader`, `follower`, or `candidate` while no leader is known), `isLeader`, and the `leader`'s name | Every node names the same leader |
| `raft` | Election `term`, the `commitIndex` and `lastAppliedIndex` of the cluster's own bookkeeping (never MQTT messages), `quorumSize`, `hasState` (this node belongs to a cluster), `standby` and `standbyRecoveries`, and `logReset` | `term` rising quickly means repeated elections. `logReset` is set when the node found its cluster log unreadable at start, moved it aside, and rejoined from the leader |
| `discovery`, `topology` | Discovery mode and the QoS 0 topology | — |
| `members`, `membersTotal`, `membersAlive` | Each member's `name`, `endpoint`, `isSelf`, `isLeader`, and `status` | `membersTotal` equals your number of nodes; on the leader, `membersAlive` equals `membersTotal` |
| `dataPlane` | Names of the links that carry QoS 0 messages to the other nodes | One per other node with the `mesh` topology |
| `partitions` | `mapVersion`, `partitionCount`, `replicationFactor`, `underReplicated`, the number of partitions each node owns, this node's partitions, and the full map (`owner`, `replicas`, and `epoch` per partition). `enabled: false` until the cluster has formed | Owners spread evenly across nodes; the map version rises after each node failure or return |
| `replication` | `quorumGateEnabled`, `connectedPeers`, and counters since `startedUtc`: accepted and forwarded publishes, rejected publishes (`quorumFailures`), the last time to reach a majority (`lastQuorumMicros`), and the `wal`, `forwarding`, `sessions`, `failover`, `consistency`, and `transport` blocks. `partitionProgress` lists, for each partition this node holds, the last stored sequence and epoch | `connectedPeers` equals the number of other nodes; `forwarding.backlog` near `0`; `forwarding.dropped` stays `0`. The same `partitionProgress` values on every copy of a partition mean the copies agree |
| `lot` | The committed LoT version and the version this node has applied, each node's state and why it is behind, `mixedMode` while a live node can't take part in LoT changes, and who owns each timer, `ON START` action, and exclusive connector | Every node has applied the committed version; `mixedMode` is `false` |
| `routeListeners` | Each server connector's listener on this node (Modbus server, OPC UA server, REST API server, video output) and its state, with the reason when a bind failed | Every listener is up on every node |

The counters restart at `0` when the node restarts. The short form on [`/info`](#runtime-info) is enough for a dashboard tile. See [Clustering](/latest/mqtt-broker/clustering#monitoring) for the values to watch.

## Replication trace

`GET /cluster/trace` reads the trace of QoS 1 and 2 messages on the broker host. Turn it on with `ReplicationTrace` in the cluster configuration (see [Replication](/latest/mqtt-broker/clustering#replication)). While that setting is off, the trace does not record messages.

The node writes the trace to `replication/trace`. At about 100 messages per second, expect about 50 MB per hour on each node. `ReplicationTraceMaxMegabytes` (default `512`, from 8 to 8192) caps the files, and the oldest are deleted first.

The path is on the ops port (default `9100`) and is unauthenticated, like the other paths on that port. Keep the port on a private network.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -s http://127.0.0.1:9100/cluster/trace
```

## Log level

`GET /loglevel` and `POST /loglevel` change the broker's minimum log level without a restart. The new level lasts until the process exits. The next start uses `COREFLUX_LOG_LEVEL` again (default `Information`).

Read the current level:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -s http://127.0.0.1:9100/loglevel
```

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "level": "Information" }
```

Set it with a query string or a JSON body. If both are sent, the query string wins. Names are case-insensitive; the response uses the canonical name.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -s -X POST 'http://127.0.0.1:9100/loglevel?level=Debug'
```

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -s -X POST http://127.0.0.1:9100/loglevel \
  -H 'Content-Type: application/json' \
  -d '{"level":"Debug"}'
```

Success is `{ "level": "Debug" }`. An unknown or missing level is **400**:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "error": "invalid or missing level",
  "allowed": ["Verbose", "Debug", "Information", "Warning", "Error", "Fatal"]
}
```

> [!WARNING]
>
> `POST /loglevel` is unauthenticated. Anyone who can reach the ops port can raise verbosity for the whole process. Keep the port on a private network.

## Configuration

The ops listener is on by default. Environment variables override the broker configuration. Restart the broker after changing them.

| Broker configuration | Environment variable | Default | Effect |
| - | - | - | - |
| `OpsEnabled` | `COREFLUX_OPS_ENABLED` | `true` | Turn the whole ops listener on or off. |
| `OpsPort` | `COREFLUX_OPS_PORT` | `9100` | TCP port. Must be from `1` to `65535`. |
| `OpsBindIP` | `COREFLUX_OPS_BIND_IP` | `0.0.0.0` | Bind address on the broker host. `127.0.0.1` keeps probes on the broker host only. |

When `COREFLUX_OPS_ENABLED` is set, the listener is on only for `1` or `true` (any letter case). `false`, `0`, and any other value turn it off. When the variable is unset, `OpsEnabled` is used.

An invalid `COREFLUX_OPS_PORT` (not an integer, or outside `1`–`65535`) is ignored, and `OpsPort` is used instead. A non-empty `COREFLUX_OPS_BIND_IP` replaces `OpsBindIP`.

When the listener is disabled, nothing is bound to the ops port and these paths are not served.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
export COREFLUX_OPS_ENABLED=true
export COREFLUX_OPS_PORT=9100
export COREFLUX_OPS_BIND_IP=127.0.0.1
```

The same names are listed under [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env#operational-http-health-ready-info-license-metrics).

## Security

These endpoints are unauthenticated on purpose, so orchestrator probes and in-cluster scrapers do not need a password.

* Do not expose port `9100` to the public internet.
* On a single broker host, bind `127.0.0.1` (or publish the Docker port on `127.0.0.1` only).
* In Kubernetes, leave the port on the pod network and scrape it with a Service. Do not put it on a public LoadBalancer.
* Treat `/license` and `POST /loglevel` as sensitive even though `/health` is not.

`/info` is intentionally free of secrets: no MQTT passwords, no MCP token values, no license file, no cluster shared secret.

## Kubernetes

The published broker image has no shell, so use HTTP probes rather than a command inside the container.

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ports:
  - name: mqtt
    containerPort: 1883
  - name: ops
    containerPort: 9100
livenessProbe:
  httpGet:
    path: /health
    port: 9100
  initialDelaySeconds: 5
  periodSeconds: 15
readinessProbe:
  httpGet:
    path: /ready
    port: 9100
  initialDelaySeconds: 5
  periodSeconds: 10
```

A longer startup example is on [Startup Options](/latest/mqtt-broker/startup-options).

Prometheus Operator scrape (the Service must expose a port named `ops`):

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: coreflux-broker
spec:
  selector:
    matchLabels:
      app: coreflux-broker
  endpoints:
    - port: ops
      path: /metrics
      interval: 30s
```

## Try it on the broker host

With the default port published on the broker host:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -s http://127.0.0.1:9100/health
curl -s http://127.0.0.1:9100/ready
curl -s http://127.0.0.1:9100/info
curl -s http://127.0.0.1:9100/license
curl -s http://127.0.0.1:9100/metrics
```

Confirm the ops paths are not served on the WebSocket / HTTP port (expect `404`):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5000/health
```

## Next Steps

> **[System topics](/latest/mqtt-broker/sys-topics)**
>
> Read the same license status, and the rest of the broker, over MQTT.

> **[Licensing and Enrollment](/latest/mqtt-broker/licensing)**
>
> Interpret tier, limits, fingerprint, activation, and enrollment.


# MQTT Broker
Source: https://docs.coreflux.org/latest/mqtt-broker/overview

Introduction to the Coreflux MQTT Broker - the core component of your IoT platform.

## Why Use the Coreflux MQTT Broker?

Your IoT devices need to communicate with each other and with your applications. Without a central hub, you'd need to manage complex point-to-point connections between every device—impossible to scale and maintain.

> [!TIP]
>
> **Think of the broker as a smart post office.** Devices "mail" messages to topics (like addresses), and the broker delivers them to everyone who "subscribed" to that address. No device needs to know who else is listening.

The Coreflux MQTT Broker solves this by providing:

* **Reliable message delivery** between any number of devices
* **Built-in data processing** with LoT (Language of Things)
* **Security and access control** without external services
* **Edge computing** that reduces cloud dependency

***

## How Does an MQTT Broker Work?

An MQTT broker sits at the center of all communication. Instead of devices talking directly to each other, they all talk to the broker—and the broker handles delivery.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart TB
    subgraph Publishers
        A[Temperature Sensor]
        B[Pressure Sensor]
        C[Motion Detector]
    end
    subgraph Broker
        D[Coreflux MQTT Broker]
    end
    subgraph Subscribers
        E[Dashboard App]
        F[Alert System]
        G[Database Logger]
    end
    A -->|"PUBLISH sensors/temp"| D
    B -->|"PUBLISH sensors/pressure"| D
    C -->|"PUBLISH sensors/motion"| D
    D -->|"DELIVER"| E
    D -->|"DELIVER"| F
    D -->|"DELIVER"| G
```

### The Publish-Subscribe Pattern

MQTT uses a **publish-subscribe** (pub/sub) model:

1. **Publishers** send messages to **topics** (like `sensors/temperature`)
2. **Subscribers** register interest in topics they care about
3. The **broker** receives all messages and delivers them to matching subscribers

This decouples senders from receivers—a sensor doesn't need to know (or care) who's listening to its data.

### What the Broker Handles

| Function | What It Does |
| - | - |
| **Message Routing** | Receives messages from publishers, matches topics, delivers to subscribers |
| **Connection Management** | Maintains client connections, handles reconnects, manages session state |
| **Quality of Service** | Ensures delivery guarantees (at-most-once, at-least-once, exactly-once) |
| **Message Retention** | Optionally stores the last message on a topic for new subscribers |
| **Security** | Authenticates clients and enforces access permissions |

***

## The Coreflux Advantage

Standard MQTT brokers connector messages—that's it. The Coreflux MQTT Broker goes further with **built-in intelligence** using the LoT (Language of Things) runtime:

### Beyond Message Routing

* **[LoT Actions](/latest/lot-language/actions/overview)** — React to messages automatically. When a temperature exceeds a threshold, trigger an alert without external code.

* **[LoT Models](/latest/lot-language/models/overview)** — Transform and structure data in real-time. Convert raw sensor values into formatted JSON with timestamps and metadata.

* **[LoT Connectors](/latest/lot-language/routes/overview)** — Connect to external systems. Bridge to other brokers, store data in databases, call REST APIs—all configured in LoT.

* **[LoT Rules](/latest/lot-language/rules/overview)** — Control access with fine-grained permissions. Define who can publish, subscribe, or manage the broker.

### Processing at the Edge

Instead of sending all data to the cloud for processing, the Coreflux broker processes data **where it's generated**:

* **Lower latency** — Local actions execute in milliseconds, no round-trip to the cloud
* **Reduced bandwidth** — Only filtered or aggregated data leaves the edge
* **Offline resilience** — Critical logic keeps running even if the internet drops
* **Stronger privacy** — Sensitive data stays on-premises by default

***

## Key Benefits

> **Efficient Communication**
>
> MQTT's lightweight protocol is designed for constrained devices and limited bandwidth. The Coreflux broker optimizes message delivery for challenging network conditions—perfect for industrial environments, remote sites, or battery-powered devices.
>
> **Coreflux enhancement:** Built-in message compression and intelligent batching reduce bandwidth by up to 70% compared to raw MQTT.

> **Security and Access Control**
>
> IoT security is non-negotiable. The Coreflux broker includes TLS encryption, certificate-based authentication, and username/password auth out of the box.
>
> **Coreflux enhancement:** LoT Rules provide fine-grained access control—define exactly who can publish, subscribe, or manage each topic pattern.

> **Intelligent Data Processing**
>
> Raw sensor data is rarely useful as-is. It needs filtering, transformation, and enrichment before applications can use it.
>
> **Coreflux enhancement:** LoT Models and Actions process data in real-time at the edge. No external ETL pipelines or stream processors required.

> **System Integration**
>
> IoT systems don't exist in isolation. They connect to databases, APIs, dashboards, and other brokers.
>
> **Coreflux enhancement:** LoT Connectors provide native integration with SQL databases, REST APIs, industrial protocols (Modbus, OPC-UA, S7), and other MQTT brokers.

***

## Coreflux MQTT Broker as a Platform

The Coreflux MQTT Broker is more than a message router — it is a complete IoT platform running at the edge:

| Layer | What You Get |
| - | - |
| **MQTT Messaging** | Reliable pub/sub communication with QoS guarantees, session management, and retained messages |
| **Security** | TLS encryption, client authentication, and fine-grained topic-level access control via LoT Rules |
| **LoT Runtime** | Built-in automation, data transformation, external integrations, and access policies — no external code required |
| **Administration** | Configuration, licensing, logging, metrics, the MCP Server, and maintenance through MQTT-native management topics and the [ops HTTP listener](/latest/mqtt-broker/operational-endpoints) |

***

## Next Steps

> **[MQTT Protocol](/latest/mqtt-broker/protocol)**
>
> Learn the fundamentals of MQTT messaging.

> **[Installation Guide](/latest/quick-start/installation)**
>
> Install and configure your Coreflux broker.


# MQTT Protocol
Source: https://docs.coreflux.org/latest/mqtt-broker/protocol

Understanding the MQTT protocol - the foundation of IoT communication.

## The Language of IoT

MQTT (Message Queuing Telemetry Transport) is a lightweight, publish-subscribe messaging protocol designed for constrained devices and low-bandwidth, high-latency networks. It has become the de facto standard for IoT communication.

Before diving into Coreflux features like LoT Actions and Models, you need to understand how MQTT works. Every Coreflux capability builds on these fundamentals—topics, subscriptions, QoS, and message patterns.

> [!TIP]
>
> **Think of MQTT like a radio station.** Publishers broadcast on a frequency (topic), and anyone who tunes in (subscribes) hears the message. The broker is the transmission tower that makes it all work.

> [!NOTE]
>
> MQTT is designed to be simple, lightweight, and easy to implement. A minimal MQTT control message can be as small as 2 bytes, making it ideal for resource-constrained devices.

***

## The Publish-Subscribe Pattern

Unlike traditional request-response protocols (like HTTP), MQTT uses a publish-subscribe (pub/sub) pattern. This decouples the sender (publisher) from the receiver (subscriber), allowing for more flexible and scalable architectures.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    subgraph Publishers
        A[Temperature Sensor]
        B[Humidity Sensor]
    end
    subgraph Broker
        C[Coreflux MQTT Broker]
    end
    subgraph Subscribers
        D[Mobile App]
        E[Dashboard]
        F[Database]
    end
    A -->|"PUBLISH<br/>sensors/temp"| C
    B -->|"PUBLISH<br/>sensors/humidity"| C
    C -->|"DELIVER"| D
    C -->|"DELIVER"| E
    C -->|"DELIVER"| F
```

### How It Works

**1. Publisher sends message**

A client publishes a message to a specific topic on the broker.

**2. Broker receives message**

The broker receives the message and checks which clients are subscribed to that topic.

**3. Broker delivers message**

The broker forwards the message to all subscribers of that topic.

***

## Topics

Topics are the routing mechanism in MQTT. They are UTF-8 strings that the broker uses to filter messages for each connected client.

### Topic Structure

Topics are hierarchical, using forward slashes (`/`) as level separators. This hierarchy is powerful for organizing data—especially in industrial settings using patterns like the Unified Namespace (UNS).

```
building/floor1/room101/temperature
building/floor1/room101/humidity
building/floor2/room201/temperature
```

### Topic Tree Example

A well-designed topic tree organizes your entire system logically:

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
    A[enterprise] --> B[site] --> C[area] --> D[line] --> E[cell] --> F[device] --> G[measurement]
```

Here's how this maps to real topics:

```
enterprise/
├── factory-munich/
│   ├── production/
│   │   ├── line-1/
│   │   │   ├── cnc-machine-01/
│   │   │   │   ├── temperature
│   │   │   │   ├── vibration
│   │   │   │   └── status
│   │   │   └── robot-arm-02/
│   │   │       ├── position
│   │   │       └── status
│   │   └── line-2/
│   │       └── ...
│   └── quality/
│       └── ...
└── factory-berlin/
    └── ...
```

> [!TIP]
>
> Design your topic hierarchy carefully. A well-structured topic tree—often called a Unified Namespace (UNS)—makes it easier to subscribe to related data, manage access control, and scale your system.

### Topic Best Practices

| Practice | Example | Description |
| - | - | - |
| Use hierarchical structure | `factory/line1/machine1/status` | Organize topics logically |
| Be specific | `sensors/temp/celsius` | Avoid overly generic topics |
| Use lowercase | `home/living-room/light` | Consistent naming convention |
| Avoid leading slashes | `home/kitchen` not `/home/kitchen` | Leading slash creates empty level |

***

## Wildcards

MQTT supports two wildcard characters for subscribing to multiple topics at once.

**Single-Level (+)**

The `+` wildcard matches **exactly one** topic level.

**Subscription:** `building/floor1/+/temperature`

> [!TIP]
>
> **Matches:** `building/floor1/room101/temperature`, `building/floor1/room102/temperature`, `building/floor1/lobby/temperature`

> [!WARNING]
>
> **Does NOT match:** `building/floor2/room201/temperature` (different floor), `building/floor1/room101/humidity` (different measurement), `building/floor1/west/room101/temperature` (extra level)

**Multi-Level (#)**

The `#` wildcard matches **any number of levels** and must be at the end.

**Subscription:** `building/floor1/#`

> [!TIP]
>
> **Matches:** `building/floor1/room101/temperature`, `building/floor1/room101/humidity`, `building/floor1/room102/status`, `building/floor1/lobby/motion/detected`

> [!WARNING]
>
> **Does NOT match:** `building/floor2/room201/temperature` (different floor), `building/basement/storage/humidity` (different path)

> [!WARNING]
>
> Use wildcards carefully. Subscribing to `#` alone would receive ALL messages on the broker, which could overwhelm your client and create security risks.

***

## Quality of Service (QoS)

MQTT defines three levels of Quality of Service for message delivery. Choose based on your reliability requirements and network conditions.

### QoS 0 — At Most Once

**Fire and forget.** The message is sent once with no acknowledgment.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sequenceDiagram
    participant P as Publisher
    participant B as Broker
    participant S as Subscriber
    P->>B: PUBLISH
    B->>S: PUBLISH
```

| Aspect | Detail |
| - | - |
| **Delivery** | At most once (may be lost) |
| **Acknowledgment** | None |
| **Performance** | Fastest |
| **Use when** | Frequent sensor readings where occasional loss is acceptable |

> [!NOTE]
>
> **Best for:** High-frequency telemetry data like temperature readings every second. Missing one reading doesn't matter when the next arrives immediately.

### QoS 1 — At Least Once

**Acknowledged delivery.** The sender stores the message until the broker confirms receipt.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sequenceDiagram
    participant P as Publisher
    participant B as Broker
    participant S as Subscriber
    P->>B: PUBLISH
    B->>S: PUBLISH
    B->>P: PUBACK
```

| Aspect | Detail |
| - | - |
| **Delivery** | At least once (may duplicate) |
| **Acknowledgment** | PUBACK from broker |
| **Performance** | Moderate |
| **Use when** | Important data where your application can handle duplicates |

> [!NOTE]
>
> **Best for:** Event logs, alerts, or status updates. If the same alert arrives twice, your system should deduplicate it.

### QoS 2 — Exactly Once

**Assured delivery.** A four-way handshake ensures the message arrives exactly once.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sequenceDiagram
    participant P as Publisher
    participant B as Broker
    P->>B: PUBLISH
    B->>P: PUBREC
    P->>B: PUBREL
    B->>P: PUBCOMP
```

| Aspect | Detail |
| - | - |
| **Delivery** | Exactly once (guaranteed, no duplicates) |
| **Acknowledgment** | PUBREC → PUBREL → PUBCOMP handshake |
| **Performance** | Slowest |
| **Use when** | Critical data where duplicates cause problems |

> [!NOTE]
>
> **Best for:** Financial transactions, billing events, or commands where duplicate execution would be harmful (e.g., "dispense medication").

***

## Retained Messages

When a message is published with the retain flag set, the broker stores the last message for that topic. Any new subscriber immediately receives this retained message upon subscribing.

> [!TIP]
>
> Retained messages are useful for status topics. A new client connecting can immediately know the current state without waiting for the next update.

**Example use cases:**

* Device status (online/offline)
* Current configuration values
* Last known sensor readings

***

## Last Will and Testament (LWT)

The Last Will and Testament feature allows a client to specify a message that the broker should publish if the client disconnects unexpectedly. This is essential for detecting device failures.

### How LWT Works

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sequenceDiagram
    participant D as Device
    participant B as Broker
    participant M as Monitoring System
    
    D->>B: CONNECT with LWT
    Note right of B: LWT stored:<br/>"devices/sensor-01/status" = "offline"
    
    D->>B: PUBLISH status = "online"
    B->>M: status = "online"
    
    Note over D: Device crashes or<br/>loses network
    
    B->>M: LWT triggered:<br/>status = "offline"
```

**1. Client connects with LWT**

When connecting, the client specifies its LWT message, topic, QoS, and retain flag.

**2. Connection maintained**

The broker holds the LWT message as long as the client stays connected.

**3. Unexpected disconnect**

If the client disconnects without sending a proper DISCONNECT packet (crash, network loss), the broker publishes the LWT message.

### LWT Configuration Example

A typical pattern for device status monitoring:

| Setting | Value | Purpose |
| - | - | - |
| **LWT Topic** | `devices/sensor-01/status` | Where to publish if device disconnects |
| **LWT Message** | `offline` | What to publish |
| **LWT Retain** | `true` | Keep message for new subscribers |
| **LWT QoS** | `1` | Ensure delivery to monitoring systems |

When the device connects, it publishes `online` to the same topic (retained). If it crashes, the broker publishes `offline`. Monitoring systems always know the current state.

***

## Clean Sessions

MQTT supports two session types:

| Session Type | Clean Session Flag | Behavior |
| - | - | - |
| **Clean Session** | `true` | No state is stored between connections. Subscriptions are discarded on disconnect. |
| **Persistent Session** | `false` | Broker stores subscriptions and queued messages (QoS 1/2) for the client. |

> [!NOTE]
>
> Persistent sessions are useful for mobile devices or intermittent connections where you don't want to miss messages during brief disconnections.

***

## Shared subscriptions

A normal subscription delivers every matching message to every subscriber. A shared subscription splits that work: several clients join one group, and each matching message goes to exactly one member of the group.

> [!TIP]
>
> **Like one ticket window with several clerks.** The next customer (message) is served by one clerk. Anyone watching the queue from outside the window (a normal subscription) still sees every customer.

Subscribe with an MQTT 5 share filter:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
$share/{group}/{filter}
```

`$share/workers/jobs/#` puts the client in the group `workers` for `jobs/#`. `$share/other/jobs/#` is a different group. The broker hands each matching message to one connected member, round-robin. A client subscribed to `jobs/#` without `$share` still receives every message.

Shared subscriptions are off until you turn them on. Set `SharedSubscriptions` to `true`, or set `COREFLUX_MQTT_SHARED_SUBSCRIPTIONS` to `1` or `true`. See [Broker Configuration](/latest/mqtt-broker/configuration#shared-subscriptions).

| Broker setting | What clients see |
| - | - |
| `SharedSubscriptions` `false` (default) | `$share/...` SUBSCRIBE is refused with `0x9E` (Shared Subscriptions Not Supported). CONNACK reports Shared Subscription Available = `0`. |
| `SharedSubscriptions` `true` | CONNACK reports Shared Subscription Available = `1`. A malformed share filter (empty group name, `+` or `#` in the group name, or a missing filter) is refused with `0x8F` (Topic Filter Invalid). |

> [!NOTE]
>
> In this version, a shared group in a cluster includes only the clients connected to that broker host. Clients on another host form their own group. MQTT 3.1.1 clients can use the `$share/` prefix once the feature is enabled.

***

## Keep Alive

The keep-alive mechanism ensures the connection remains active and detects dead connections quickly.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sequenceDiagram
    participant C as Client
    participant B as Broker
    
    C->>B: CONNECT (keep-alive: 60s)
    
    Note over C,B: Normal data exchange
    C->>B: PUBLISH
    B->>C: PUBACK
    
    Note over C,B: No data to send...<br/>approaching keep-alive timeout
    
    C->>B: PINGREQ
    B->>C: PINGRESP
    
    Note over C,B: Connection confirmed alive
    
    C->>B: PINGREQ
    Note over B: No PINGRESP for 1.5x keep-alive
    Note over B: Connection declared dead,<br/>LWT published
```

### How It Works

| Step | Description |
| - | - |
| **1. Connect** | Client specifies a keep-alive interval (in seconds) when connecting |
| **2. Activity** | Client must send a control packet within each keep-alive period |
| **3. Ping** | If no data is being sent, the client sends PINGREQ |
| **4. Response** | The broker responds with PINGRESP |
| **5. Timeout** | If no communication occurs within 1.5x the keep-alive period, the connection is considered dead |

> [!TIP]
>
> Choose keep-alive values based on your network. Shorter intervals (15-30s) detect failures faster but use more bandwidth. Longer intervals (60-120s) are better for mobile networks with variable latency.

***

## Authentication

Clients present a username and password at CONNECT, or connect anonymously when the broker allows it. For organization accounts, the password is an access token and the broker checks it with the identity provider. That path is [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication). It is separate from TLS: TLS protects the connection, and the token says who the client is.

***

## Next Steps

> **[Broker Commands](/latest/mqtt-broker/commands)**
>
> Learn how to control the Coreflux broker via MQTT commands.

> **[\$SYS Topics](/latest/mqtt-broker/sys-topics)**
>
> Explore system topics for monitoring and control.


# Environment Variables & Secrets
Source: https://docs.coreflux.org/latest/mqtt-broker/secrets-and-env

Manage configuration, credentials, and sensitive data securely with environment variables and encrypted secrets

## Stop Hardcoding Credentials

Every IoT deployment needs connection strings, API keys, and passwords -- but embedding them directly in your LoT code or connector definitions creates security risks and makes your configuration impossible to reuse across environments. The Coreflux Broker solves this with built-in environment variable and secrets management.

* **Environment variables** store non-sensitive configuration (hostnames, ports, URLs) in a plain-text `.env` file
* **Secrets** store sensitive credentials (passwords, API keys, tokens) encrypted at rest with **AES-256-GCM**

Both are accessible from LoT Actions, Models, Connectors, and broker CLI commands using a unified syntax -- no external tools or services required.

> [!TIP]
>
> **Think of it like a vault and a notebook.** Environment variables are the notebook -- quick to read, easy to update, visible if someone opens the file. Secrets are the vault -- locked with a key, encrypted on disk, only decrypted when the broker needs them at runtime.

> [!NOTE]
>
> Environment variables and secrets management is available from **Coreflux Broker v1.9.3** and above.

## When to Use Each

| Scenario | Use | Why |
| - | - | - |
| Database host, port, name | **Environment variable** | Non-sensitive, changes per environment |
| API base URLs | **Environment variable** | Configuration that varies between dev/staging/prod |
| Feature flags | **Environment variable** | Simple on/off toggles |
| Database passwords | **Secret** | Must not be readable on disk |
| API keys and tokens | **Secret** | Sensitive credentials |
| TLS passphrases | **Secret** | Security-critical values |

***

## Config Root

The broker picks its **data directory** (config root) in this order — **first match wins**:

1. `COREFLUX_DATA_PATH` (used as-is)
2. `CONFIG_PATH` (used as-is; this is what official Docker images set)
3. `-p` / `--path` (used as-is, applied later in startup — prefer the env vars)
4. Default: `{install directory}/Coreflux`

When an env var is set, **`/Coreflux` is not appended**. With `CONFIG_PATH=/etc/project`, files live at `/etc/project/.env`, not `/etc/project/Coreflux/.env`. The `/Coreflux` suffix is only added in the default case (no env var and no `-p`).

| Install | Typical data directory |
| - | - |
| Docker / Compose | `/etc/project` (`CONFIG_PATH` in the image; mount your volume here) |
| Linux APT/DNF | `/var/lib/coreflux` (`COREFLUX_DATA_PATH` in `coreflux-broker.service`) |
| Windows / portable binary | `{folder with the executable}/Coreflux` unless you set `COREFLUX_DATA_PATH` |

### File Layout

Environment and secrets files live in the data directory:

```
{data directory}/
  .env                # Plain-text environment variables (key=value)
  secrets.json        # AES-256-GCM encrypted secrets
  secret.key          # Optional: encryption key (base64, 32 bytes)
  config/             # Signed license, install identity, enrollment (persist this)
  bin/                # Internal broker data (managed automatically), including the LoT stores below
  log/                # Log files
  stats/              # Statistics
```

The LoT you deploy is saved in `bin/` as plain-text files, one per kind: `actions.lot`, `models.lot`, `routes.lot` and `rules.lot`, plus `Python.Scripts` for Python scripts and `project-entity-ownership.json`, which records which project loaded each entity. Back up `bin/` with the rest of the data directory. Do not edit these files while the broker runs; change LoT with the broker commands or a project.

> [!NOTE]
>
> Earlier versions named these files `Saul.Ricardo` (actions), `Marco.Paulo` (models), `Roberto.Leal` (connectors), `Ze.Cabra` (rules) and `Ze.Cabra.project-rules.json` (project ownership). On the first start after an upgrade the broker copies each one to its new name and leaves the old file in place, so your LoT carries over and you can still go back to the earlier version. See [Update Coreflux](/latest/updating-coreflux).

***

## Broker process environment variables

These names are read by the **broker process** (Docker `environment:`, systemd `Environment=`, Kubernetes `env:`). They are not the same as values you store in `.env` for `GET ENV` — though a name set in the process environment is still visible to `GET ENV` through the fallback chain.

Restart the broker after changing them.

### Data path and logging

| Variable | Default | Description |
| - | - | - |
| `COREFLUX_DATA_PATH` | `{install}/Coreflux` | Data directory, used as-is. Wins over `CONFIG_PATH` and over the `ProjectPath` config field. |
| `COREFLUX_CERT_STORAGE_ROOTS` | — | Extra folders (separated by `:` on Linux and macOS) under which the client certificate storage path may be set from the HUB or `-brokerCertificates`. See [Certificates](/hub/system/certificates#trust-store-settings). |
| `CONFIG_PATH` | — | Same role as `COREFLUX_DATA_PATH` if that variable is unset. Official images set this to `/etc/project`. A non-empty `ProjectPath` in broker JSON can still override it unless `COREFLUX_DATA_PATH` is set. |
| `COREFLUX_CLOUD_LOGGING` | auto in containers | `true` / `1` forces stdout JSON logs. Also on when the process runs in a container. |
| `COREFLUX_LOG_LEVEL` | `Information` | Serilog level (`Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal`). |

### Secrets and audit

| Variable | Default | Description |
| - | - | - |
| `COREFLUX_SECRET_KEY` | derived key | Base64-encoded 32-byte key for `secrets.json`. Preferred in Docker/Kubernetes. |
| `COREFLUX_AUDIT_KEY` | derived key | Base64-encoded 32-byte key for encrypted audit logs (or use `audit.key` in the data directory). |

### Operational HTTP (`/health`, `/ready`, `/info`, `/license`, `/metrics`)

| Variable | Default | Description |
| - | - | - |
| `COREFLUX_OPS_ENABLED` | `true` | Set `false` / `0` to disable the ops listener. |
| `COREFLUX_OPS_PORT` | `9100` | Ops TCP port. Do not publish this port to the public internet. |
| `COREFLUX_OPS_BIND_IP` | `0.0.0.0` | Ops bind address. Use `127.0.0.1` to keep probes on localhost. |

Env vars override the matching fields in broker JSON (`OpsEnabled`, `OpsPort`, `OpsBindIP`).

Paths, response shapes, Kubernetes probes, and the Prometheus scrape are on [Operational endpoints](/latest/mqtt-broker/operational-endpoints). `GET /license` returns the license status also published on the retained `$SYS/Coreflux/License` topic (tier, limits, usage, fingerprint, activation, enrollment). It is unauthenticated — keep the ops port on a private network. Field meanings: [Licensing and Enrollment](/latest/mqtt-broker/licensing#watch-license-status).

### Licensing and enrollment

These names are read from the **process** environment at boot. They are not the LoT `.env` file you manage with `-setEnv`.

| Variable | Description |
| - | - |
| `COREFLUX_ACTIVATION_CODE` | Online activation code (`CFLX-…`). Get a 30-day Growth-type license at [portal.coreflux.org](https://portal.coreflux.org). Also enables organization enrollment. |
| `COREFLUX_LICENSE_TOKEN` | Inline signed license (compact JWS). |
| `COREFLUX_LICENSE_FILE` | Path to a signed license file. |

There is no enrollment-token environment variable — use `--enroll` / `-enroll` or `{data directory}/config/enrollment-token`. Full guide: [Licensing and Enrollment](/latest/mqtt-broker/licensing).

### MQTT

| Variable | Default | Description |
| - | - | - |
| `COREFLUX_MQTT_SHARED_SUBSCRIPTIONS` | unset | Overrides `SharedSubscriptions` (default `false`). `1` or `true` enables MQTT 5 shared subscriptions; `0` or `false` disables them. See [Broker Configuration](/latest/mqtt-broker/configuration#shared-subscriptions). |

OIDC bearer authentication is **not** configured with a process environment variable. The `Oidc` object lives in the broker configuration file. Enrollment writes `Oidc.BoundOrg` after the broker joins an organization. See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).

### Connectors, durability, clustering, Python

| Variable | Description |
| - | - |
| `COREFLUX_ROUTE_OVERLOAD_POLICY` | Broker-wide default `lossless`, `balanced`, or `realtime`. See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward). |
| `COREFLUX_ROUTE_CHANNEL_FULL_TIMEOUT_MS` | Wait budget (ms) for `balanced` (default `50`). |
| `COREFLUX_ROUTE_CHANNEL_CAPACITY` | Shared queue ceiling (default `100000`). |
| `COREFLUX_DURABILITY_*` | Restart persistence for retained messages and sessions. See [MQTT State Durability](/latest/mqtt-broker/durability). |
| `COREFLUX_MCP_*` | MCP Server listen address, tool allow-list, and token lifetime. See [MCP Server](/latest/mqtt-broker/mcp-server). |
| `COREFLUX_CLUSTER_*` | High-availability clustering. See [Clustering](/latest/mqtt-broker/clustering). |
| `COREFLUX_DISABLE_PYTHON` | `true` skips in-process Python (`CALL PYTHON`). |

***

## Environment Variables

### Storage

Environment variables are stored in plain text in `{data directory}/.env` using standard key=value format:

```env wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
MQTT_BRIDGE_HOST=remote-broker.company.com
```

### Resolution Order

When the broker resolves an environment variable (via `GET ENV`, connector config, or CLI), it checks multiple sources in this order:

| Priority | Source | Description |
| - | - | - |
| 1 | `.env` file (managed) | Set via `-setEnv` or `KEEP ENV`. Persisted to disk. |
| 2 | Process environment | Docker `environment:`, Kubernetes `env:`, or shell exports. |
| 3 | User environment | OS user-level environment variables (non-Docker). |
| 4 | Machine environment | OS machine-level environment variables (non-Docker). |

If not found in any source, an empty string is returned.

> [!NOTE]
>
> This fallback chain means Docker `environment:` variables work even without a `.env` file -- the broker picks them up from the process environment automatically.

***

## Secrets

### How Secrets Work

Secrets are encrypted at rest using **AES-256-GCM** and stored in `{data directory}/secrets.json`. Each secret entry contains the initialization vector, the encrypted value with authentication tag, and a creation timestamp:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "DB_PASSWORD": {
    "IV": "base64...",
    "Value": "base64(ciphertext):base64(tag)",
    "Created": "2026-02-08T12:00:00Z"
  }
}
```

Secret values are only decrypted at runtime when accessed via `GET SECRET` or connector configuration. They are never logged or displayed -- even the `-listSecrets` command only shows secret names, never values.

### Encryption Key

The broker resolves the encryption key in this order:

| Priority | Source | Notes |
| - | - | - |
| 1 | `COREFLUX_SECRET_KEY` env var | Best for Docker/Kubernetes. Base64-encoded, 32 bytes. |
| 2 | `{data directory}/secret.key` file | Good for mounted volumes. Base64-encoded, 32 bytes. |
| 3 | Derived from machine GUID | Auto-generated fallback. Machine-specific -- secrets become unreadable if moved to a different machine. |

#### Generating a Key

Use OpenSSL to generate a cryptographically secure 32-byte key:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
openssl rand -base64 32
# Example output: K7x2mN8pQ1rT5uW3yB6dF9hJ0kL4nP7sV2xZ8cG1eA=
```

> [!WARNING]
>
> If you use the derived key fallback (no explicit key), your secrets are tied to the specific machine. Moving the `secrets.json` file to another machine or container will make the secrets unreadable. Always use an explicit key for portable deployments.

***

## Using in LoT

Environment variables and secrets can be read, written, and deleted from within LoT Actions, Models, and connector configurations.

### Reading Values

Use `GET ENV` to read an environment variable and `GET SECRET` to read an encrypted secret (decrypted at runtime):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Read configuration from environment
SET "myHost" WITH (GET ENV "DB_HOST")
SET "myPort" WITH (GET ENV "DB_PORT")

-- Read credentials from encrypted secrets
SET "dbPass" WITH (GET SECRET "DB_PASSWORD")
SET "apiKey" WITH (GET SECRET "API_KEY")
```

### Persisting Values

Use `KEEP ENV` to save a new environment variable to the `.env` file, and `KEEP SECRET` to encrypt and store a new secret:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Save an environment variable (persisted to .env)
KEEP ENV "LAST_RUN" WITH TIMESTAMP "UTC"

-- Save an encrypted secret (persisted to secrets.json)
KEEP SECRET "API_KEY" WITH "sk-abc123"
```

### Deleting Values

Use `DELETE ENV` and `DELETE SECRET` to remove values:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Remove an environment variable
DELETE ENV "OLD_CONFIG"

-- Remove a secret
DELETE SECRET "OLD_API_KEY"
```

### Complete Example

This action reads database configuration from environment variables and credentials from secrets on broker startup, then reports the status:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ConnectToDatabase
ON START DO
    -- Read connection settings from environment
    SET "host" WITH (GET ENV "DB_HOST")
    SET "port" WITH (GET ENV "DB_PORT")
    SET "dbName" WITH (GET ENV "DB_NAME")

    -- Read credentials from encrypted secrets
    SET "user" WITH (GET SECRET "DB_USER")
    SET "pass" WITH (GET SECRET "DB_PASSWORD")

    IF {host} == EMPTY THEN
        PUBLISH TOPIC "system/errors" WITH "DB_HOST not configured"
    ELSE
        PUBLISH TOPIC "system/status" WITH "Database configured: " + {host} + ":" + {port}

    -- Track when we last initialized
    KEEP ENV "LAST_DB_INIT" WITH TIMESTAMP "UTC"
```

***

## Using in Connectors

Environment variables and secrets can be referenced directly in connector definitions, keeping connection details out of your LoT code.

### Standard Syntax

Use `GET ENV` and `GET SECRET` in connector configuration blocks to inject values at runtime:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MyDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER GET ENV "DB_HOST"
        WITH PORT 5432
        WITH DATABASE GET ENV "DB_NAME"
        WITH USERNAME GET ENV "DB_USER"
        WITH PASSWORD GET SECRET "DB_PASSWORD"
```

### Legacy Prefix Syntax

The `ENV:` and `SECRET:` prefix syntax is also supported for backward compatibility in connector `ADD CONFIG` sections:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH SERVER ENV:DB_HOST
WITH PASSWORD SECRET:DB_PASSWORD
```

### Event Query Placeholders

In connector event queries (e.g. `WITH QUERY`), use curly-brace placeholders that are resolved at execution time:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD EVENT StoreReading
    WITH SOURCE_TOPIC "sensors/#"
    WITH QUERY "INSERT INTO readings (host, value) VALUES ('{env.DB_HOST}', '{payload}')"
```

| Placeholder | Resolves To |
| - | - |
| `{env.NAME}` | Environment variable value |
| `{secret.NAME}` | Decrypted secret value |

***

## CLI Commands

Manage environment variables and secrets at runtime by publishing commands to `$SYS/Coreflux/Command` using any MQTT client (such as MQTT Explorer).

### Environment Variable Commands

| Command | Description |
| - | - |
| `-setEnv NAME=value` | Set an environment variable (persisted to `.env` file) |
| `-removeEnv NAME` | Remove an environment variable |
| `-listEnv` | List all managed environment variables |

Publish these messages to `$SYS/Coreflux/Command` to manage environment variables:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Set an environment variable
-setEnv DB_HOST=postgres.example.com

# List all environment variables
-listEnv

# Remove an environment variable
-removeEnv OLD_CONFIG
```

> [!WARNING]
>
> **Quote values that contain `//`, a space, or `#`.** The command is cleaned before it runs. Outside double quotes, `//`, `/*` and `-- ` start a comment and cut off the rest of the line, and a space ends the value. Wrap the value in double quotes: `-setEnv API_URL="https://api.example.com/v1"`. The quotes are removed before the value is stored. The same rule applies to `-setSecret`.

### Secret Commands

| Command | Description |
| - | - |
| `-setSecret NAME=value` | Set a secret (encrypted and persisted to `secrets.json`) |
| `-removeSecret NAME` | Remove a secret |
| `-listSecrets` | List secret names (values are never shown) |

Publish these messages to `$SYS/Coreflux/Command` to manage secrets:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Set a secret
-setSecret DB_PASSWORD=my_secure_password

# List secret names
-listSecrets

# Remove a secret
-removeSecret OLD_API_KEY
```

> [!NOTE]
>
> Subscribe to `$SYS/Coreflux/Command/Output` to receive confirmation responses from commands.

***

## Deployment

Set up environment variables and secrets across different deployment targets.

**Windows**

On Windows, the data directory defaults to the broker's executable folder + `\Coreflux` unless `COREFLUX_DATA_PATH` is set (used as-is).

**1. Locate the data directory**

If the broker is at `C:\Coreflux\CorefluxMQTTBroker.exe`, the default data directory is `C:\Coreflux\Coreflux\`.

To pin a custom path, set a machine environment variable (no extra `\Coreflux` is appended):

```powershell wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[Environment]::SetEnvironmentVariable("COREFLUX_DATA_PATH", "C:\CorefluxData", "Machine")
```

Files then live directly under `C:\CorefluxData\`.

**2. Create the .env File**

Create a `.env` file in the data directory:

```powershell wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
@"
DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
"@ | Out-File -FilePath "C:\CorefluxData\.env" -Encoding UTF8
```

**3. Generate an Encryption Key**

Generate and save a `secret.key` file for encrypting secrets:

```powershell wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
openssl rand -base64 32 > "C:\CorefluxData\secret.key"
```

**4. Set Secrets After Start**

Start the broker, then set secrets using any MQTT client (such as MQTT Explorer). Publish to `$SYS/Coreflux/Command`:

```
-setSecret DB_PASSWORD=my_secure_password
```

> [!TIP]
>
> Subscribe to `$SYS/Coreflux/Command/Output` to confirm the secret was stored.

**Linux**

APT/DNF installs already set `COREFLUX_DATA_PATH=/var/lib/coreflux` on `coreflux-broker.service`. Put `.env` and `secret.key` there.

**1. Create the .env file**

Write your environment variables and restrict permissions:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo tee /var/lib/coreflux/.env << 'EOF'
DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
EOF
sudo chown coreflux:coreflux /var/lib/coreflux/.env
sudo chmod 600 /var/lib/coreflux/.env
```

**2. Generate an encryption key**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
openssl rand -base64 32 | sudo tee /var/lib/coreflux/secret.key >/dev/null
sudo chown coreflux:coreflux /var/lib/coreflux/secret.key
sudo chmod 600 /var/lib/coreflux/secret.key
```

**3. Restart the service**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo systemctl restart coreflux-broker
```

**4. Set Secrets After Start**

Using any MQTT client, publish to `$SYS/Coreflux/Command`:

```
-setSecret DB_PASSWORD=my_secure_password
```

> [!TIP]
>
> Verify with `-listSecrets` -- the secret name should appear in the output.

**Docker Compose**

### Option 1: Mount a Config Volume (Recommended)

Pre-create the config files on the host and mount them into the container.

**1. Prepare the host directory:**

Create the config directory, generate an encryption key, and write your environment variables:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mkdir -p ./coreflux-data

# Generate encryption key
openssl rand -base64 32 > ./coreflux-data/secret.key

# Create .env file
cat > ./coreflux-data/.env << 'EOF'
DB_HOST=postgres.example.com
DB_PORT=5432
API_BASE_URL=https://api.example.com
EOF
```

**2. Docker Compose file:**

Mount the host directory at `/etc/project` (the image's `CONFIG_PATH`):

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
services:
  coreflux-broker:
    image: coreflux/coreflux-mqtt-broker:latest
    container_name: coreflux-broker
    ports:
      - "1883:1883"
      - "8883:8883"
      - "5000:5000"
      - "9100:9100"
    volumes:
      - ./coreflux-data:/etc/project
    restart: unless-stopped
```

The broker resolves:

* `CONFIG_PATH=/etc/project` (baked into the image) — data directory is `/etc/project`
* `.env` from `/etc/project/.env` (your `./coreflux-data/.env`)
* `secret.key` from `/etc/project/secret.key`
* All broker state persists in the mounted directory

**3. Set secrets after the broker starts:**

Using any MQTT client, publish to `$SYS/Coreflux/Command`:

```
-setSecret DB_PASSWORD=my_secure_password
```

### Option 2: Pass Env Vars via Docker (No .env File)

If you prefer not to manage a `.env` file, pass variables directly through Docker's `environment:`. The resolution fallback to process environment picks them up:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
services:
  coreflux-broker:
    image: coreflux/coreflux-mqtt-broker:latest
    ports:
      - "1883:1883"
      - "9100:9100"
    environment:
      - DB_HOST=postgres.example.com
      - DB_PORT=5432
      - API_BASE_URL=https://api.example.com
      - COREFLUX_SECRET_KEY=K7x2mN8pQ1rT5uW3yB6dF9hJ0kL4nP7sV2xZ8cG1eA=
    volumes:
      - coreflux-data:/etc/project

volumes:
  coreflux-data:
```

Variables set this way:

* Are available to LoT via `GET ENV "DB_HOST"`
* Are available to connectors via `GET ENV "DB_HOST"` and legacy `ENV:DB_HOST`
* Are **not** persisted to `.env` (they exist only in the process environment)
* Will be lost if the container restarts without the same `environment:` block

> [!NOTE]
>
> Secrets still need a volume for `secrets.json` persistence, even when passing the encryption key via `COREFLUX_SECRET_KEY`.

**Kubernetes**

Use Kubernetes ConfigMaps for environment variables and Kubernetes Secrets for the encryption key.

**1. ConfigMap for environment variables:**

Store non-sensitive configuration in a ConfigMap:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: coreflux-env
data:
  DB_HOST: "postgres.cluster.local"
  DB_PORT: "5432"
  API_BASE_URL: "https://api.example.com"
```

**2. Kubernetes Secret for the encryption key:**

Store the encryption key in a Kubernetes Secret (base64-encoded):

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apiVersion: v1
kind: Secret
metadata:
  name: coreflux-secrets
type: Opaque
data:
  COREFLUX_SECRET_KEY: SzdsMm1OOHBRMXJUNXVXM3lCNmRGOWhKMGtMNG5QN3NWMnhaOGNHMWVBPQ==
```

**3. Deployment:**

Inject the ConfigMap as environment variables via `envFrom`, and the encryption key from the Kubernetes Secret:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: coreflux-broker
spec:
  replicas: 1
  selector:
    matchLabels:
      app: coreflux-broker
  template:
    metadata:
      labels:
        app: coreflux-broker
    spec:
      containers:
        - name: broker
          image: coreflux/coreflux-mqtt-broker:latest
          ports:
            - containerPort: 1883
            - containerPort: 5000
            - containerPort: 9100
          env:
            - name: CONFIG_PATH
              value: "/etc/project"
            - name: COREFLUX_SECRET_KEY
              valueFrom:
                secretKeyRef:
                  name: coreflux-secrets
                  key: COREFLUX_SECRET_KEY
          envFrom:
            - configMapRef:
                name: coreflux-env
          volumeMounts:
            - name: data
              mountPath: /etc/project
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: coreflux-pvc
```

**4. PersistentVolumeClaim:**

Provide persistent storage for broker data, secrets, and configuration:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: coreflux-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
```

Apply all resources:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
kubectl apply -f coreflux-configmap.yaml
kubectl apply -f coreflux-secret.yaml
kubectl apply -f coreflux-pvc.yaml
kubectl apply -f coreflux-deployment.yaml
```

ConfigMap values are injected as process environment variables via `envFrom`, so `GET ENV` picks them up through the fallback chain. The `COREFLUX_SECRET_KEY` from the Kubernetes Secret enables portable secret encryption.

***

## Best Practices

> **Use explicit encryption keys in production**
>
> Never rely on the derived key fallback for production deployments. Always provide a `COREFLUX_SECRET_KEY` environment variable or a `secret.key` file. The derived key is machine-specific -- if you migrate, scale, or recreate a container, your secrets become unreadable.

> **Restrict file permissions**
>
> On Linux, restrict access to sensitive files to the broker's service user only:
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> chmod 600 /var/lib/coreflux/.env
> chmod 600 /var/lib/coreflux/secret.key
> chmod 600 /var/lib/coreflux/secrets.json
> ```

> **Prefer GET ENV over hardcoded values**
>
> Even for values that seem static (like a database port), use `GET ENV` so you can change configuration without redeploying LoT code. This makes your Actions and Connectors portable across dev, staging, and production.

> **Use mounted volumes for Docker**
>
> Always mount a persistent volume at the data directory (`/etc/project` in Docker, `/var/lib/coreflux` on Linux packages). Without a volume, `.env`, `secrets.json`, and broker state are lost when the container is recreated.

> **Never commit secrets to version control**
>
> Keep `secret.key`, `secrets.json`, and `.env` files out of Git. Add them to `.gitignore` and use your deployment pipeline to inject them at runtime.

***

## Resolution Reference

### Where Each Syntax Reads From

| Syntax | Where It Works | Resolved By |
| - | - | - |
| `GET ENV "NAME"` | Actions, Models, Connector configs | `.env` file, then process env fallback |
| `GET SECRET "NAME"` | Actions, Models, Connector configs | Decrypts from `secrets.json` |
| `ENV:NAME` | Connector `ADD CONFIG` sections only | Same as `GET ENV` |
| `SECRET:NAME` | Connector `ADD CONFIG` sections only | Same as `GET SECRET` |
| `{env.NAME}` | Event queries (`WITH QUERY`) | Replaced at event execution time |
| `{secret.NAME}` | Event queries (`WITH QUERY`) | Replaced at event execution time |

### Encryption Key Resolution Order

| Priority | Source | Notes |
| - | - | - |
| 1 | `COREFLUX_SECRET_KEY` env var | Best for Docker/Kubernetes. Base64-encoded, 32 bytes. |
| 2 | `{data directory}/secret.key` file | Good for mounted volumes. Base64-encoded, 32 bytes. |
| 3 | Derived from machine GUID | Auto-generated fallback. Machine-specific -- secrets won't decrypt on a different machine. |

### GetEnv Resolution Order

| Priority | Source | Notes |
| - | - | - |
| 1 | `.env` file (managed) | Set via `-setEnv` or `KEEP ENV`. Persisted to disk. |
| 2 | Process environment | Docker `environment:`, Kubernetes `env:`, or shell exports. |
| 3 | User environment | OS user-level env vars (non-Docker). |
| 4 | Machine environment | OS machine-level env vars (non-Docker). |

***

## Next Steps

> **[Broker Commands](/latest/mqtt-broker/commands)**
>
> Full reference for all broker CLI commands including env and secret management.

> **[Operations Reference](/latest/lot-language/actions/operations)**
>
> See GET ENV and GET SECRET in the complete LoT operations reference.


# Startup Options & Deployment
Source: https://docs.coreflux.org/latest/mqtt-broker/startup-options

Start the broker with CLI flags, projects, and packages — Docker, Linux systemd, and Windows services

## Configure the broker before it starts

Pass configuration at process start so containers, packages, and CI pipelines come up the same way every time. Typical jobs:

* Point the data directory at a persistent volume
* Import broker or user JSON on first boot
* Load a LoT notebook project from git or disk
* Stage a signed license or enrollment token before MQTT accepts connections

> [!TIP]
>
> **Think of startup options as a recipe card.** You tell the broker where its data lives and which project to load; it applies that recipe and then stays up as a service or container.

For install commands (Docker, APT, DNF, Windows), start with [Installation](/latest/quick-start/installation). For `COREFLUX_*` variables, secrets, and `.env` files, see [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env).

***

## Command-line options

### Configuration

| Option | Long form | Description |
| - | - | - |
| `-c` | `--config` | Path to broker configuration JSON. Applied only when no broker config exists yet, unless you also pass `--config-force`. |
| `-cf` | `--config-force` | Overwrite existing broker configuration with `--config`. |
| `-u` | `--users` | Path to users JSON. Applied only when no users file exists yet, unless you also pass `--users-force`. |
| `-uf` | `--users-force` | Overwrite existing users with `--users`. |
| `-p` | `--path` | Data directory (same role as `COREFLUX_DATA_PATH`). Prefer the environment variable so the path is set **before** `--config` is applied. |

> [!NOTE]
>
> Set `COREFLUX_DATA_PATH` or `CONFIG_PATH` in the process environment, then start the binary. `-p` / `--path` is applied late in startup, so `--config` can write into the default data directory instead of the path you intended.

### Projects and licenses

Load LoT (Language of Things) from a **project** (git URL, local folder, or a project already stored on this broker). That is the supported way to ship Actions, Models, Connectors, and Rules at boot.

| Option | Long form | Description |
| - | - | - |
| | `--project` | Load a project at startup (git URL, local path, or existing project name). |
| | `--branch` | Git branch or tag to check out with `--project`. |
| `-loadLicense` | `--load-license` | Stage a signed license file (compact JWS) as `config/license.jws` before MQTT starts. |
| `-showFingerprint` | `--show-fingerprint` | Print the broker host's hardware fingerprint and exit. Send it to Coreflux to be issued an offline license. Does not start MQTT. |
| `-enroll` | `--enroll` | Stage a single-use enrollment token (`et_…`) for organization binding. Also accepted on `$SYS/Coreflux/Command` while the broker is running. |

A project loaded with `--project` (or `-loadProject` at runtime) is remembered across restarts. On the next start, if you do **not** pass `--project`, the broker re-activates that project. `-unloadProject` clears it. `--project` always wins over the remembered project.

To activate a license at start, set `COREFLUX_ACTIVATION_CODE` in the process environment or pass `--load-license`. Register at [portal.coreflux.org](https://portal.coreflux.org) for a 30-day Growth-type license. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

### Other options

| Option | Long form | Description |
| - | - | - |
| `-I` | `--install` | Register a Windows service or a Linux systemd unit for a **portable** (zip/tarball) binary. Skip this when you installed from APT/DNF — the package already ships `coreflux-broker.service`. |
| `-h` | `--help` | Display help. |

***

## Basic usage

### Starting with configuration files

**Linux**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Start with broker configuration
./CorefluxMQTTBroker --config /path/to/broker-config.json

# Start with users configuration
./CorefluxMQTTBroker --users /path/to/users.json

# Start with both
./CorefluxMQTTBroker \
    --config /path/to/broker-config.json \
    --users /path/to/users.json
```

**Windows**

```powershell wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Start with broker configuration
.\CorefluxMQTTBroker.exe --config C:\config\broker-config.json

# Start with users configuration
.\CorefluxMQTTBroker.exe --users C:\config\users.json

# Start with both
.\CorefluxMQTTBroker.exe `
    --config C:\config\broker-config.json `
    --users C:\config\users.json
```

### Force overwrite existing configuration

By default, if configuration already exists in the data directory, startup JSON is ignored. Use force flags to overwrite:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Force overwrite broker config
./CorefluxMQTTBroker --config /path/to/broker-config.json --config-force

# Force overwrite users config
./CorefluxMQTTBroker --users /path/to/users.json --users-force

# Force overwrite both (short form)
./CorefluxMQTTBroker -c /path/to/broker-config.json -cf -u /path/to/users.json -uf
```

> [!WARNING]
>
> Force flags overwrite existing configurations. Back up your current configuration before using them.

### Loading a project at startup

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# From git URL
./CorefluxMQTTBroker --project https://github.com/org/my-iot-project.git --branch production

# From local path
./CorefluxMQTTBroker --project /path/to/my-project

# By project name (already stored on this broker)
./CorefluxMQTTBroker --project my-iot-project
```

> [!TIP]
>
> Package Actions, Models, Connectors, and Rules in a LoT notebook project and load it with `--project`. That is the supported bootstrap path for LoT at startup.

***

## Configuration files

### Broker configuration (JSON)

The broker configuration file defines MQTT service settings:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Name": "MyCorefluxBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "AnonymousLogin": false,
  "FullDebugLog": false,
  "ServerCertificatePath": "/path/to/certificate.pfx",
  "ServerCertificatePassword": "your-certificate-password",
  "ResendRetainTopics": false
}
```

> [!NOTE]
>
> For every supported field (ports, TLS/mTLS, sessions, performance, data paths, ops, durability), see [Broker Configuration](/latest/mqtt-broker/configuration).

### Users configuration (JSON)

The users configuration file defines MQTT users and their permissions:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "UserName": "root",
    "Password": "your-secure-password",
    "AllowedBaseTopic": "#",
    "AllowedSystemConfiguration": true,
    "AllowedUserManagement": true,
    "AllowedLogManagement": true
  },
  {
    "UserName": "device-user",
    "Password": "device-password",
    "AllowedBaseTopic": "devices/",
    "AllowedSystemConfiguration": false,
    "AllowedUserManagement": false,
    "AllowedLogManagement": false
  }
]
```

| Property | Type | Description |
| - | - | - |
| `UserName` | string | MQTT username |
| `Password` | string | MQTT password |
| `AllowedBaseTopic` | string | Topic access restriction (`#` for all topics) |
| `AllowedSystemConfiguration` | bool | Allow system configuration changes |
| `AllowedUserManagement` | bool | Allow user management operations |
| `AllowedLogManagement` | bool | Allow log management operations |

***

## Container deployment

Official images use `CONFIG_PATH=/etc/project`. Persist that directory so configuration, secrets, and projects survive image updates. The published image is `coreflux/coreflux-mqtt-broker`.

**Docker**

Same pattern as [Installation](/latest/quick-start/installation): named volume at `/etc/project`, MQTT on `1883`, WebSocket on `5000`, ops on `9100`.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d --name coreflux_broker \
  -p 1883:1883 -p 5000:5000 -p 9100:9100 \
  -v project-volume:/etc/project \
  coreflux/coreflux-mqtt-broker:latest \
  --project https://github.com/org/my-iot-project.git --branch main
```

Import JSON on first boot by mounting files and passing `--config` / `--users` (add `--config-force` / `--users-force` only when you intend to replace existing state):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d --name coreflux_broker \
  -p 1883:1883 -p 5000:5000 -p 9100:9100 \
  -v project-volume:/etc/project \
  -v /host/config:/config:ro \
  coreflux/coreflux-mqtt-broker:latest \
  --config /config/broker-config.json \
  --users /config/users.json
```

Probe liveness with `curl http://localhost:9100/health`. The image has no shell, so do not use `exec` healthchecks.

**Docker Compose**

Use the Compose file from [Installation](/latest/quick-start/installation). To load a project, add `command` on the broker service:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
services:
  broker:
    image: coreflux/coreflux-mqtt-broker:latest
    ports:
      - "1883:1883"
      - "5000:5000"
      - "9100:9100"
    volumes:
      - broker-data:/etc/project
    command:
      - "--project"
      - "https://github.com/org/my-iot-project.git"
      - "--branch"
      - "main"
    restart: unless-stopped

volumes:
  broker-data:
```

The image already sets `CONFIG_PATH=/etc/project`. Override `COREFLUX_DATA_PATH` only if you change the mount path.

**Kubernetes**

Mount a PVC at `/etc/project`. Use HTTP probes on port `9100` (the image has no shell). Paths and a Prometheus scrape are on [Operational endpoints](/latest/mqtt-broker/operational-endpoints#kubernetes).

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: coreflux-broker
spec:
  replicas: 1
  selector:
    matchLabels:
      app: coreflux-broker
  template:
    metadata:
      labels:
        app: coreflux-broker
    spec:
      containers:
        - name: broker
          image: coreflux/coreflux-mqtt-broker:latest
          args:
            - "--project"
            - "https://github.com/org/my-iot-project.git"
            - "--branch"
            - "production"
          ports:
            - containerPort: 1883
              name: mqtt
            - containerPort: 5000
              name: websocket
            - containerPort: 9100
              name: ops
          env:
            - name: CONFIG_PATH
              value: "/etc/project"
          volumeMounts:
            - name: data
              mountPath: /etc/project
          livenessProbe:
            httpGet:
              path: /health
              port: 9100
            initialDelaySeconds: 5
            periodSeconds: 15
          readinessProbe:
            httpGet:
              path: /ready
              port: 9100
            initialDelaySeconds: 5
            periodSeconds: 10
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: coreflux-data
```

***

## Service installation

Prefer the install method from [Installation](/latest/quick-start/installation). Use `--install` only for portable binaries.

**Linux packages**

APT and DNF packages already register **`coreflux-broker.service`**, install under `/opt/coreflux-broker`, and set `COREFLUX_DATA_PATH=/var/lib/coreflux`.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo systemctl status coreflux-broker
sudo systemctl restart coreflux-broker
sudo journalctl -u coreflux-broker -f
```

To add startup flags (for example `--project`), override the unit:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo systemctl edit coreflux-broker
```

```ini wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[Service]
ExecStart=
ExecStart=/opt/coreflux-broker/CorefluxMQTTBroker --project https://github.com/org/my-iot-project.git --branch main
```

Then `sudo systemctl daemon-reload && sudo systemctl restart coreflux-broker`.

### Ports below 1024

The service runs as the unprivileged user `coreflux`. The unit grants `CAP_NET_BIND_SERVICE`, so the broker can bind ports below 1024. A package upgrade replaces the unit file. Drop-in files under `/etc/systemd/system/coreflux-broker.service.d/` are kept.

An older package does not grant that capability. Add it in a drop-in:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo systemctl edit coreflux-broker
```

```ini wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[Service]
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
```

Then reload and restart:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo systemctl daemon-reload
sudo systemctl restart coreflux-broker
```

A container, or a broker you start without the APT or DNF package, needs that capability on the process, or a port of 1024 or above.

**Windows**

[Installation](/latest/quick-start/installation) registers the service with `sc create`. For a portable zip, you can instead run as Administrator:

```powershell wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
.\CorefluxMQTTBroker.exe --install
net start CorefluxMQTTBroker
Get-Service CorefluxMQTTBroker
```

To apply JSON once before the service owns the process, run the broker in the foreground with `--config` / `--users`, stop it, then install or start the service.

**Portable Linux**

For a tarball (not APT/DNF), run as root:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo ./CorefluxMQTTBroker --install
```

That writes a systemd unit. For production, still prefer the Linux package from the [Downloads page](https://portal.coreflux.org/downloads) so upgrades and `COREFLUX_DATA_PATH` stay consistent.

***

## Best practices

> **Set the data path in the environment**
>
> Use `COREFLUX_DATA_PATH` or `CONFIG_PATH` so `--config` and `--users` land in the same directory the broker uses at runtime. Docker images already set `CONFIG_PATH=/etc/project`.

> **Use force flags only when you mean to reset**
>
> `-cf` and `-uf` overwrite existing configuration. Back up first.

> **Ship LoT as a project**
>
> Load Actions, Models, Connectors, and Rules with `--project`, not with ad-hoc `.lot` file flags at process start.

> **Persist the data volume**
>
> Always mount a volume at `/etc/project` in Docker and Kubernetes. Without it, configuration, secrets, projects, the signed license (`config/license.jws`), and enrollment credentials disappear when the container is recreated. See [Licensing and Enrollment](/latest/mqtt-broker/licensing#persist-the-data-volume).

***

## Troubleshooting

> **Configuration not applied**
>
> 1. Confirm `COREFLUX_DATA_PATH` / `CONFIG_PATH` matches the volume you mounted.
> 2. If files already exist in that directory, add `--config-force` / `--users-force` only if you intend to replace them.
> 3. Check logs for validation errors.

> **Port already in use**
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> sudo lsof -i :1883
> ```
>
> On Windows: `netstat -ano | findstr :1883`
>
> Stop the other listener or change the broker port in configuration.

> **Broker exits at start with code 78 (a LoT state file cannot be used)**
>
> Before it loads anything, the broker checks its LoT files in `{data directory}/bin/` (`actions.lot`, `models.lot`, `routes.lot`, `rules.lot`, `project-entity-ownership.json`, `Python.Scripts`). It exits with code `78` when it can't write to `bin/`, can't open one of these files for reading and writing, or can't copy a file with an earlier name to its new name. It prints each file with the reason. It does not start empty, because a broker without its rules or actions would allow and run different things than you configured.
>
> 1. Read the message in the console or the log. It names every file the broker cannot use.
> 2. Give the user the broker runs as read and write access to those files. The container image runs as user `10001`, so on a mounted volume run `chown -R 10001 <volume path>`.
> 3. If the broker should start without a file, move that file aside and start again.

> **Permission denied on Linux**
>
> The package service user is `coreflux`, with state under `/var/lib/coreflux`. The service user needs read access to certificates and write access to the data directory.
>
> If the broker cannot bind a port below 1024, the process is missing `CAP_NET_BIND_SERVICE`. Current APT and DNF units grant it. On an older package, add the drop-in under [Ports below 1024](#ports-below-1024). A container or a manual run needs that capability, or a port of 1024 or above.

***

## Next Steps

> **[Broker Configuration](/latest/mqtt-broker/configuration)**
>
> Ports, TLS, sessions, ops, and every JSON field.

> **[Licensing and Enrollment](/latest/mqtt-broker/licensing)**
>
> Activation codes, signed licenses, enrollment, and `GET /license`.


# System ($SYS) Topics
Source: https://docs.coreflux.org/latest/mqtt-broker/sys-topics

Monitor the broker, read configuration, and control Coreflux over MQTT system topics

## See the Broker From MQTT

You do not need a separate monitoring stack to know what the broker is doing. Subscribe to `$SYS` topics and you get version, license, connected clients, LoT source, connector health, and project state as MQTT messages — the same way you already consume sensor data.

> [!TIP]
>
> **Think of `$SYS` as the broker's dashboard in topic form.** Subscribe like any other MQTT topic and watch live status, without opening a separate UI.

### When to use this

| Goal | Start here |
| - | - |
| Confirm the broker is up and which build is running | `$SYS/Coreflux/Version` |
| See the license tier and usage | `$SYS/Coreflux/License` (same status as ops [`GET /license`](/latest/mqtt-broker/operational-endpoints#license-status)) |
| Send management commands | `$SYS/Coreflux/Command` and `Command/Output` |
| Inspect or back up LoT source | `$SYS/Coreflux/Actions/#`, `Models/#`, `Routes/#`, `Rules/#`, `Visus/#` |
| Watch connector health | `$SYS/Coreflux/Routes/+/status` |
| See which project is loaded | `$SYS/Coreflux/Projects/active` |
| Confirm the MCP Server is listening | `$SYS/Coreflux/MCP/Info` |

> [!WARNING]
>
> Topics that start with `$` are not included when you subscribe to `#` at the root. Subscribe to `$SYS/#` (or a more specific `$SYS/…` filter) explicitly.

***

The tables below are the map; later sections explain payloads and who may publish or subscribe.

## Topic Hierarchy

```
$SYS/
├── Coreflux/
│   ├── Command                    # Publish commands
│   ├── Command/Output             # JSON command replies
│   ├── Config                     # Live configuration (includes Python status)
│   ├── Config/New                 # Publish a config update
│   ├── Config/New/Result          # Result of a config update
│   ├── Config/Users               # User list (passwords masked)
│   ├── Version                    # Broker version
│   ├── License                    # License and usage
│   ├── Resources/                 # Memory totals
│   ├── Comms/
│   │   ├── Sessions               # MQTT sessions
│   │   ├── Clients                # Connected clients
│   │   ├── Logins                 # Login events
│   │   └── PacketTrace/…          # Optional packet traces
│   ├── Actions/<name>             # Action LoT
│   ├── Models/<name>              # Model LoT
│   ├── Connectors/<name>              # Connector LoT
│   ├── Rules/<name>               # Rule LoT
│   ├── Visus/<name>               # Panel LoT
│   ├── Things/<name>              # Thing source, tree, status
│   ├── Projects/                  # Project list, active, manifest, download
│   ├── Entities/ownership         # Project vs ad-hoc origin
│   ├── MCP/Info                   # MCP Server status
│   ├── MCP/Tools                  # Advertised MCP tool names
│   ├── Cluster/                   # Role, leader, members (when clustering)
│   ├── Python/Scripts             # Registered Python scripts
│   ├── AI/Providers               # Discovered LLM providers
│   └── Certificates/Summary       # Certificate expiry counts (retained)
└── <OS>/                          # e.g. Linux-x64, Windows-x64
    ├── Python/Info
    └── Comms/TCP|UDP/…
```

### Read-only (broker → client)

| Topic | Content |
| - | - |
| `$SYS/Coreflux/Version` | Version JSON (**retained**) |
| `$SYS/Coreflux/License` | License, tier, limits, current usage (**retained**) |
| `$SYS/Coreflux/Config` | Live configuration JSON, including Python backend status |
| `$SYS/Coreflux/Config/Users` | Users with passwords masked; includes `Groups` |
| `$SYS/Coreflux/Config/New/Result` | Outcome of the last publish to `Config/New` |
| `$SYS/Coreflux/Comms/Sessions` | Active sessions |
| `$SYS/Coreflux/Comms/Clients` | Connected clients |
| `$SYS/Coreflux/Comms/Logins` | Login event lines |
| `$SYS/Coreflux/Actions/{name}` | Action LoT (**retained**) |
| `$SYS/Coreflux/Models/{name}` | Model LoT (**retained**) |
| `$SYS/Coreflux/Routes/{name}` | Connector LoT (**retained**) |
| `$SYS/Coreflux/Routes/{name}/status` | Connector health JSON |
| `$SYS/Coreflux/Rules/{name}` | Rule LoT |
| `$SYS/Coreflux/Visus/{name}` | Panel source (**retained**) |
| `$SYS/Coreflux/Projects/list` | Stored projects (**retained**) |
| `$SYS/Coreflux/Projects/active` | Loaded project (**retained**) |
| `$SYS/Coreflux/Entities/ownership` | Running entities → project origin (**retained**) |
| `$SYS/Coreflux/MCP/Info` | MCP Server status and endpoint (**retained**) |
| `$SYS/Coreflux/MCP/Tools` | Currently advertised MCP tool names (**retained**) |

### Writable (client → broker)

| Topic | Purpose |
| - | - |
| `$SYS/Coreflux/Command` | Run [broker commands](/latest/mqtt-broker/commands) |
| `$SYS/Coreflux/Config/New` | Apply a configuration JSON (restart still required for most fields) |
| `$SYS/Coreflux/Actions/{name}/Run` | Run a callable Action (panels use this) |
| `$SYS/Coreflux/Actions/{name}/Invoke` | Same as `/Run` (legacy alias) |
| `$SYS/Coreflux/Routes/{name}/Events/{event}/Trigger` | Fire a named connector event from a panel |

***

## Command Topics

Send a command and read the reply over MQTT. Subscribe to the output topic **before** you publish, or you can miss a fast reply.

**1. Subscribe to output**

Using any MQTT client (such as MQTT Explorer), subscribe to `$SYS/Coreflux/Command/Output`.

**2. Publish the command**

Publish the command string to `$SYS/Coreflux/Command`. Add `-requestId <id>` when several commands may be in flight.

**3. Read the JSON envelope**

Every reply is one JSON object on `Command/Output`. Match `requestId` when you sent one.

### `$SYS/Coreflux/Command`

**Direction:** Client → Broker

| Field | Value |
| - | - |
| **Topic** | `$SYS/Coreflux/Command` |
| **Payload** | `-addAction DEFINE ACTION Heartbeat ON EVERY 10 SECONDS DO PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"` |
| **Auth** | Session allowed for `CommandCall` (`root` or the matching RBAC permission flags) |

### `$SYS/Coreflux/Command/Output`

**Direction:** Broker → Client

Replies always use this JSON envelope. Structured list/query results are in `data`. `data` is always present (`{}` when there is nothing to return, or `[]` for an empty list).

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "AddAction",
  "message": "Action 'Heartbeat' added successfully.",
  "entityType": "Action",
  "entityName": "Heartbeat",
  "data": {}
}
```

| Field | Description |
| - | - |
| `success` | Whether the command succeeded |
| `command` | Internal command name (for example `AddAction`) |
| `message` | Human-readable summary |
| `requestId` | Echo of `-requestId` when you sent one |
| `data` | Structured payload for list/query commands |
| `errors` | Present when `success` is `false` |

The broker does **not** publish to `$SYS/Coreflux/CommandResponse`. The full command list is on [Broker Commands](/latest/mqtt-broker/commands).

***

## LoT Entity Topics

Each running Action, Model, Connector, Rule, and panel publishes its LoT (or panel source) on a topic named after that entity. Subscribe to retrieve what is actually deployed — useful for backup, debugging, and Coreflux HUB.

When you remove an entity, the broker publishes an **empty retained** payload on that topic (MQTT tombstone) so subscribers do not keep a stale definition.

### `$SYS/Coreflux/Actions/{ActionName}`

**Payload:** the complete Action definition (**retained**).

Subscribe with MQTT Explorer or any MQTT client:

| Field | Value |
| - | - |
| **Topic** | `$SYS/Coreflux/Actions/Heartbeat` |

**Payload received:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

Related Action topics:

| Topic | Content |
| - | - |
| `$SYS/Coreflux/Actions/{name}/Description` | Optional description (**retained**) |
| `$SYS/Coreflux/Actions/{name}/Error` | Last Action error (**retained** when set) |
| `$SYS/Coreflux/Actions/{name}/Trace` | Execution traces when tracing is enabled (not retained; expire after a few minutes) |
| `$SYS/Coreflux/Actions/{name}/Run` | **Publish** here to run a callable Action |
| `$SYS/Coreflux/Actions/{name}/Invoke` | Same as `/Run` |

### `$SYS/Coreflux/Models/{ModelName}`

Model LoT (**retained**).

### `$SYS/Coreflux/Routes/{connector_name}`

Connector LoT (**retained**). Extra subtopics appear depending on the connector type:

| Topic | Content |
| - | - |
| `$SYS/Coreflux/Routes/{name}/status` | Health and counters. See [Connector Status Monitoring](/latest/lot-language/routes/overview#connector-status-monitoring) |
| `$SYS/Coreflux/Routes/{name}/Certificates` | Certificate-store summary for cert-managed connectors (**retained**) |
| `$SYS/Coreflux/Routes/{name}/Tools` | MCP tool summary for MCP connectors |
| `$SYS/Coreflux/Routes/{name}/Tools/{tool}` | One MCP tool (schema and capability stats) |
| `$SYS/Coreflux/Routes/{name}/Tools/{tool}/Capability` | Call statistics for one MCP tool, updated after every call (**retained**). See [Capability Payload](/latest/lot-language/routes/mcp-routes#capability-payload) |
| `$SYS/Coreflux/Routes/{name}/Events/{event}/Trigger` | **Publish** to fire that connector event |

### `$SYS/Coreflux/Agents/{agent}`

Agent source (**retained**). Agents are not listed under `$SYS/Coreflux/Routes/`. See [Agent topics](/latest/lot-language/agents/syntax#agent-topics).

| Topic | Content |
| - | - |
| `$SYS/Coreflux/Agents/{agent}/card` | Discovery card, schema version 1 (**retained**) |
| `$SYS/Coreflux/Agents/{agent}/status` | `online`, `offline`, or `error` (**retained**) |
| `$SYS/Coreflux/Agents/{agent}/task/{id}/request` | **Publish** work. Needs a `PublishSys` rule |
| `$SYS/Coreflux/Agents/{agent}/task/{id}/response` | Final answer |
| `$SYS/Coreflux/Agents/{agent}/task/{id}/stream` | Event stream, schema version 1 |
| `$SYS/Coreflux/Agents/{agent}/task/{id}/status` | Task status |
| `$SYS/Coreflux/Agents/{agent}/task/{id}/cancel` | **Publish** to cancel that task |

The broker does not publish `$SYS/Coreflux/Agents/{agent}/Capabilities` or `…/Metrics`.

### `$SYS/Coreflux/Things/{name}`

Every Thing is published **retained**. An empty payload means the Thing was removed. See [LoT THING](/latest/lot-language/things/overview).

| Topic | Payload |
| - | - |
| `$SYS/Coreflux/Things/{name}` | The source as typed, for roots and templates |
| `$SYS/Coreflux/Things/{name}/tree` | JSON: `kind`, `template`, `uses`, `usedBy`, `params`, `project`, and for a root the `instance` tree (each instance's `chain`, `template`, `path`, resolved `params`, `children`, and nested `instances`) |
| `$SYS/Coreflux/Things/{name}/status` | Roots only: `state` (`ok`, `degraded`, or `error`), child counts, the `worst` children, and `updated`. Built from connector health, agent status, and action errors |

Children keep their own topics (`$SYS/Coreflux/Routes/…`, `$SYS/Coreflux/Agents/…`). `$SYS/Coreflux/Entities/ownership` marks each child with `thing: { root, chain, clause }` and lists each Thing as `thing:<name>`.

### `$SYS/Coreflux/Rules/{RuleName}`

Rule LoT source.

### `$SYS/Coreflux/Visus/{PanelName}`

Panel source text (**retained**).

#### Subscribe to all entities

| Entity type | Topic pattern |
| - | - |
| All Actions | `$SYS/Coreflux/Actions/#` |
| All Models | `$SYS/Coreflux/Models/#` |
| All Connectors | `$SYS/Coreflux/Routes/#` |
| All agents | `$SYS/Coreflux/Agents/#` |
| All Things | `$SYS/Coreflux/Things/#` |
| All Rules | `$SYS/Coreflux/Rules/#` |
| All panels | `$SYS/Coreflux/Visus/#` |

***

## Broker Information

### `$SYS/Coreflux/Version`

Broker version and build (**retained**).

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "version": {
    "major": 2,
    "minor": 14,
    "patch": 0,
    "branch": "release",
    "os": "Linux-x64",
    "stage": "stable",
    "timestamp": "2026-08-26T10:00:00Z",
    "notes": ""
  }
}
```

The `os` field is the same prefix used under `$SYS/{OS}/…`.

### `$SYS/Coreflux/License`

License status, tier, feature flags, limits, current usage, activation mode, fingerprint, and organization enrollment (**retained**). The same status is served on ops [`GET /license`](/latest/mqtt-broker/operational-endpoints#license-status) (default port `9100`; HTTP names are camelCase). Brokers with no license still publish this topic so you can see `Tier` (`Community`), `EffectiveLimits`, and `CurrentUsage`.

There is no built-in trial: with no license the payload shows **Community**. A trial is a **30-day Growth-type license** from [portal.coreflux.org](https://portal.coreflux.org) that you activate on the broker. Use the same portal to manage your fleet. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "LicensedTo": "N/A",
  "ExpiresUtc": null,
  "IsActive": false,
  "Tier": "Community",
  "Fingerprint": "…",
  "FingerprintSource": "machine-id",
  "Activation": {
    "Mode": "offline",
    "BindingOk": true
  },
  "Enrollment": { "Pending": false, "Reason": null },
  "EffectiveLimits": {
    "MaxArtifacts": 24,
    "MaxRoutes": 3,
    "MaxConnections": 10000
  },
  "CurrentUsage": {
    "ArtifactCount": 3,
    "Actions": { "Regular": 2, "RouteEvents": 0, "PythonScripts": 0 },
    "Models": 0,
    "Rules": 12,
    "Routes": 1,
    "Panels": 0
  }
}
```

JSON still uses `Routes` for connectors. `Enrollment.Pending: false` means no problem was recorded — not proof that the broker is bound to an organization.

### `$SYS/Coreflux/Resources`

| Topic | Description |
| - | - |
| `$SYS/Coreflux/Resources/MemoryInfoTotal` | Total available memory (bytes) |
| `$SYS/Coreflux/Resources/MemoryInfoUsage` | Current memory usage (bytes) |

***

## Configuration Topics

### `$SYS/Coreflux/Config`

The live broker configuration as JSON. The broker adds a `Python` object so you can see whether scripts run locally or on the runner sidecar without also subscribing to `$SYS/{OS}/Python/Info`.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Name": "Coreflux DataHub",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "BindIPForMQTT": "0.0.0.0",
  "AnonymousLogin": false,
  "Python": {
    "Available": true,
    "UsingEmbeddedRuntime": false,
    "UsingRunner": false,
    "Version": "3.11.2",
    "Backend": "python.net",
    "IsolationLevel": "none"
  }
}
```

`ServerCertificatePassword` is masked as `********`. Publishing the masked value back to `$SYS/Coreflux/Config/New` keeps the stored password.

> [!NOTE]
>
> To change configuration, publish JSON to `$SYS/Coreflux/Config/New`. Most fields still need a restart. See [Broker Configuration](/latest/mqtt-broker/configuration).

### `$SYS/Coreflux/Config/New` and `…/Result`

Publish a **partial** configuration object to `$SYS/Coreflux/Config/New`. The broker merges that object into the live configuration and keeps every omitted field, including bind addresses. It then writes `$SYS/Coreflux/Config/New/Result` with success or validation failure text. See [Applying Configuration](/latest/mqtt-broker/configuration#via-mqtt-topic).

### `$SYS/Coreflux/Certificates/Summary`

Retained certificate health for the broker's TLS identity and mTLS trust store. The broker publishes it after every `-brokerCertificates` change and at most every 5 minutes otherwise. The HUB status bar reads it. It carries no host paths.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "pathOk": true,
  "pathError": null,
  "thresholdDays": 30,
  "total": 4,
  "valid": 1,
  "expiring": 2,
  "expired": 1,
  "notYetValid": 0,
  "unreadable": 0,
  "server": { "commonName": "broker.example.com", "notAfter": "2027-11-19T00:00:00Z", "status": "valid", "daysUntilExpiry": 399 },
  "rootCa": { "commonName": "Example Root CA", "notAfter": "2029-10-19T00:00:00Z", "status": "valid", "daysUntilExpiry": 1099 },
  "alerts": { "expiring": 2, "expired": 1, "total": 3 },
  "level": "expired",
  "updatedAt": "2026-10-15T11:48:00Z"
}
```

`total` through `unreadable` count client certificates in the storage path (revoked ones excluded). `alerts` adds the server certificate and Root CA. `level` is `expired`, `expiring`, or `ok`. When the storage path is unavailable, `pathOk` is `false` and the counts are `0`.

### `$SYS/Coreflux/Config/Users`

Configured users with passwords masked. `Groups` is the list used by `USER IN GROUP` in Rules.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "UserName": "root",
    "Password": "********",
    "AllowedBaseTopic": "",
    "AllowedSystemConfiguration": true,
    "AllowedUserManagement": false,
    "AllowedLogManagement": false,
    "Groups": []
  }
]
```

| Field | Description |
| - | - |
| `AllowedBaseTopic` | Optional topic prefix restriction |
| `AllowedSystemConfiguration` | Can change broker configuration and most management gates |
| `AllowedUserManagement` | Can manage users |
| `AllowedLogManagement` | Can manage log traces |
| `Groups` | Group names for [RBAC](/latest/lot-language/rules/rbac) |

***

## MCP Server

When the [MCP Server](/latest/mqtt-broker/mcp-server) is enabled, the broker republishes two retained topics. Neither payload includes token values or the usernames tokens map to.

### `$SYS/Coreflux/MCP/Info`

Status of the Streamable HTTP listener (`status` is `running` or `stopped`). Subscribe in MQTT Explorer to read `http_endpoint`, `bind_ip`, `http_port`, `tokens_active`, and the currently advertised `tools` list.

### `$SYS/Coreflux/MCP/Tools`

An array of `{ "name": "…" }` objects for tools the **running** server currently advertises. When `EnableAllTools` is false and `EnabledTools` is empty, this list is empty.

***

## Connection Monitoring

### `$SYS/Coreflux/Comms/Sessions`

Active MQTT sessions.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "CreatedTimestamp": "2026-08-26T09:01:36.5008146Z",
    "DisconnectedTimestamp": null,
    "ExpiryInterval": 0,
    "Id": "mqtt-explorer-274f0040",
    "Items": {},
    "PendingApplicationMessagesCount": 0
  }
]
```

### `$SYS/Coreflux/Comms/Clients`

Connected clients, including bytes and packet counts.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "BytesReceived": 173,
    "BytesSent": 3943557,
    "ConnectedTimestamp": "2026-08-26T09:01:36.5008189Z",
    "Endpoint": "172.17.0.1:52256",
    "Id": "mqtt-explorer-274f0040",
    "ProtocolVersion": 4,
    "ReceivedApplicationMessagesCount": 16070,
    "SentApplicationMessagesCount": 0,
    "Session": {
      "Id": "mqtt-explorer-274f0040",
      "PendingApplicationMessagesCount": 0
    }
  }
]
```

| Field | Description |
| - | - |
| `BytesReceived` / `BytesSent` | Totals for this connection |
| `Endpoint` | Client IP and port |
| `Id` | MQTT client ID |
| `ProtocolVersion` | `3` = MQTT 3.1, `4` = 3.1.1, `5` = 5.0 |

### `$SYS/Coreflux/Comms/Logins`

One JSON object per login attempt. The password is not included.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "ClientId": "lotvstudio-a6kjtbkwp",
  "Endpoint": "172.17.0.1:53454",
  "Username": "root",
  "DisplayName": "",
  "CleanSession": true,
  "ReasonCode": "Success"
}
```

For an [OIDC access token](/latest/mqtt-broker/oidc-authentication), `Username` is the token subject and `DisplayName` is the token's display name (empty when the token has none). A local login leaves `DisplayName` empty and puts the broker username in `Username`.

Lifecycle Actions (`ON CONNECT` / `ON DISCONNECT`) are a better place for automation; this topic is for observability. See [Action triggers](/latest/lot-language/actions/events).

### `$SYS/Coreflux/Comms/PacketTrace/{clientId}/In` and `/Out`

Optional raw packet traces started with `-mqttPacketTrace`. Use only while debugging a specific client.

***

## Project Topics

Retained so Coreflux HUB and other clients get the last project state on subscribe, without sending `-listProjects` first. See [Project Commands](/latest/mqtt-broker/commands#project-commands).

| Topic | Content |
| - | - |
| `$SYS/Coreflux/Projects/list` | Stored projects and which one is active (**retained**) |
| `$SYS/Coreflux/Projects/active` | Currently loaded project (**retained**; empty in standalone mode) |
| `$SYS/Coreflux/Projects/{name}/status` | Git status for that project (**retained**) |
| `$SYS/Coreflux/Projects/{name}/manifest` | SHA-256 of stored file bytes, plus entities declared in `.lotnb` cells (**retained**). Same JSON as `-projectManifest`. Cleared on `-removeProject` |
| `$SYS/Coreflux/Entities/ownership` | Map of `type:name` → `{ project, file, cell }` for project-owned entities (**retained**). A Thing's child also carries `thing: { root, chain, clause }`. Absence of a key means the entity is ad-hoc |

Export payloads on `$SYS/Coreflux/Projects/{name}/download` are **not** retained (one-shot zip transfer).

> [!NOTE]
>
> Under default rules, `$SYS/Coreflux/Projects/#` is allowed for the same users who may use `-listProjects` (`AllowedUserManagement`, `AllowedSystemConfiguration`, `root`, `admin`) — not every MQTT user.

## Platform Topics

These topics are prefixed with the operating system identifier (for example `Linux-x64`, `Windows-x64`). Read `os` from `$SYS/Coreflux/Version`.

### `$SYS/{OS}/Python/Info`

Python availability and version on that host.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Available": true,
  "Version": "3.11.2 (main, Apr 28 2025, 14:11:48) [GCC 12.2.0]",
  "Scripts": []
}
```

Individual scripts also appear at `$SYS/{OS}/Python/Scripts/{scriptName}`.

### TCP and UDP listeners

| Topic | Content |
| - | - |
| `$SYS/{OS}/Comms/TCP/Listeners` | Addresses and ports the process is listening on |
| `$SYS/{OS}/Comms/TCP/ActiveConnections` | Established TCP connections |
| `$SYS/{OS}/Comms/UDP/Listeners` | UDP listeners |
| `$SYS/{OS}/Comms/UDP/ActiveConnections` | Active UDP associations |

Example TCP listeners payload:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {"Address": "0.0.0.0", "Port": "1883"},
  {"Address": "0.0.0.0", "Port": "80"}
]
```

***

## Access Control

`$SYS` uses the `SubscribeSys` and `PublishSys` rule scopes. **Locked built-in rules** already decide who may subscribe to `$SYS/#`, publish commands, and update config. A custom `SubscribeSys` rule on `$SYS/#` does not override those gates.

| Who | Typical access |
| - | - |
| `root`, `admin`, `AllowedSystemConfiguration` | Subscribe to `$SYS/#` |
| `CommandCall` gates | Publish to `$SYS/Coreflux/Command` and subscribe to `Command/Output` |
| Same roles as `-listProjects` | `$SYS/Coreflux/Projects/#` |
| Any connected client | Publish to `$SYS/Coreflux/Actions/+/Run` and `/Invoke` (panels call Actions this way) |

See [Rules syntax](/latest/lot-language/rules/syntax#system-topics-sys) and [RBAC](/latest/lot-language/rules/rbac) for flags and locked rules.

> [!WARNING]
>
> Publish access to `$SYS/Coreflux/Command` lets a client run administrative commands. Keep that topic on management users only. `/Run` and `/Invoke` are allowed more widely so dashboards can call Actions — restrict those Actions themselves if they are sensitive.

***

## Next Steps

> **[Broker Configuration](/latest/mqtt-broker/configuration)**
>
> Change ports, TLS, and other broker settings

> **[Broker Commands](/latest/mqtt-broker/commands)**
>
> Full command list published to `$SYS/Coreflux/Command`


# Best Practices & Patterns
Source: https://docs.coreflux.org/latest/quick-start/best-practices

Overview and table of contents for best practices—topic design, reusable logic, alarms, integrations, production architecture, and notebooks.

## After Hello World, What's Next?

Once you've followed [Getting Started](/latest/quick-start/getting-started) and have Coreflux, VS Code, and your first Action running, the question becomes *how to grow*: naming topics, handling JSON, scaling Actions, wiring integrations, and shipping systems that stay maintainable. Experienced teams reuse the same patterns across factories, buildings, energy sites, and fleets—only the topics and payloads change.

> [!TIP]
>
> **Like learning chords before writing songs.** Your first Action proves the broker runs your logic; patterns teach you how dozens of Actions, Models, and Connectors fit together without turning into spaghetti.

## How Are Best Practices & Patterns Organized

Chapters below live under **Best Practices and Usage Patterns** in the sidebar. Pick one based on what you're building — each page focus on a set of tips for a given topic. Start with **Naming conventions** and finish with **Anti-patterns** when reviewing code.

> **[Naming conventions](/latest/lot-language/usage-patterns/naming-conventions)**
>
> PascalCase entities, snake\_case variables, and topic naming basics.

> **[Designing your data layer (the foundation)](/latest/lot-language/usage-patterns/data-layer)**
>
> Topic trees (UNS), scalar vs JSON payloads, Models, and inheritance — how data is shaped and addressed.

> **[Working with JSON](/latest/lot-language/usage-patterns/working-with-json)**
>
> GET JSON in Actions, nested payloads, and publishing structured output through Models.

> **[Writing reusable logic (the building blocks)](/latest/lot-language/usage-patterns/reusable-logic)**
>
> Callable actions, wildcards, counting over time, and Python — techniques for the Action you are writing now; logic that scales and stays maintainable.

> **[Alarms and monitoring](/latest/lot-language/usage-patterns/alarms-and-monitoring)**
>
> Threshold crossings and device or connector offline detection; optional email connectors alongside alarms.

> **[Connecting to the outside world (integrations)](/latest/lot-language/usage-patterns/integrations)**
>
> REST server and client, live KPIs from a database, and ENV / Secrets — Connectors that bridge to non-MQTT systems.

> **[Production architecture](/latest/lot-language/usage-patterns/production-architecture)**
>
> End-to-end device-to-database ingestion and edge–cloud bridges — synthesis patterns that build on everything before.

> **[Project organization](/latest/lot-language/usage-patterns/project-organization)**
>
> Keeping notebooks clean and readable — single-file vs multi-file layouts and shared discipline at every stage.

> **[Anti-patterns](/latest/lot-language/usage-patterns/anti-patterns)**
>
> Common LoT mistakes and what to do instead.

***

## Next Steps

> **[Introduction to LoT](/latest/lot-language/introduction)**
>
> Building blocks and how Actions, Models, Connectors, and Rules fit together.

> **[Model Inheritance](/latest/lot-language/models/model-inheritance)**
>
> Deep dive on `FROM` and base models.

New to the language? **[Introduction to LoT](/latest/lot-language/introduction)** links Actions, Models, Connectors, and Rules from one page.


# Build Your First Dashboard
Source: https://docs.coreflux.org/latest/quick-start/building-dashboards

From a topic in the Data Viewer to a live, shareable panel — in about ten minutes.

![The finished Line 3 Shift Lead panel with a temperature gauge, a live temperature trend chart, a pump toggle, and a Start Line button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/tutorial/line3-hero.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d5ee7920b953f0b16f80cb363f64b85f)

Where you're heading: the finished panel — a temperature gauge, a live trend chart, a pump toggle, and a start button

By the end of this guide you'll have a live monitoring panel with a gauge, a live trend chart, a control, and an action wired to it — open and shareable on a second screen. Everything runs on data you generate yourself, so you can follow along even on a fresh broker.

> [!TIP]
>
> **Like assembling a control room one instrument at a time.** You'll bolt on one widget per step, watch it come alive immediately, and ship the finished console at the end.

**1. Generate some live data**

So your widgets have something to show, deploy a small **LoT Action** that publishes a changing temperature and machine status every few seconds. Open the **LoT Editor** in the HUB, paste this, and deploy:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SimulateSensorData
ON EVERY 3 SECONDS DO
    IF GET TOPIC "sim/counter" == EMPTY THEN
        KEEP TOPIC "sim/counter" WITH 0
    SET "n" WITH (GET TOPIC "sim/counter" AS INT)
    SET "n" WITH ({n} + 10)
    IF {n} > 140 THEN
        SET "n" WITH 0
    KEEP TOPIC "sim/counter" WITH {n}
    PUBLISH TOPIC "sensor/temperature" WITH {n}
    IF {n} > 100 THEN
        PUBLISH TOPIC "machine/status" WITH "stopped"
    ELSE
        PUBLISH TOPIC "machine/status" WITH "running"
```

This ramps `sensor/temperature` from 0 to 140 and flips `machine/status` between `running` and `stopped` — enough to move a gauge past its threshold and draw a live trend line.

> [!TIP]
>
> **Prefer to drive it by hand?** Skip the Action and instead publish manually in the [Data Viewer](/hub/mqtt/data-viewer): send `sensor/temperature` a number like `82`, and `machine/status` the text `running` or `stopped`.

**2. Find your signal**

Open the **Data Viewer** and confirm `sensor/temperature` is updating with a numeric payload. Note the payload shape: a plain number binds directly; a JSON object would need `JSON_PATH` later.

![Coreflux HUB Data Viewer showing the publish panel on the left and the topic tree with the sensor and machine topics](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/manager/data-viewer-publish.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=8fa37e11d51ba68bf4f031d1d3f6cbd0)

The Data Viewer's PUBLISH panel and topic tree — confirm your signal is live before binding to it

**3. Create a panel**

Open **Dashboards**, click **Create new panel**, and start from this skeleton. The Dashboard Manager opens the panel definition next to its live result:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Line3ShiftLead
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line 3 — Shift Lead"
WITH LAYOUT "grid" COLUMNS 2
```

**4. Add a gauge**

Add a **gauge** bound to `sensor/temperature`, with a range, a unit, and a warning threshold. The panel so far — the new gauge component is highlighted:

```lot wrap focus={7-11} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Line3ShiftLead
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line 3 — Shift Lead"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 150
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
        ADD THRESHOLD AT 100 WITH COLOR "warning"
```

Save — the needle starts moving immediately. That's the live binding at work.

![A radial temperature gauge with a 0 to 150 range reading a live value of 82 degrees](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/tutorial/line3-gauge.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=f3e61a06dfe5baf98f8c6899127a0043)

The gauge bound to the live temperature signal (warning threshold configured at 100 °C)

**5. Ask the AI to add a chart**

The gauge shows *now*; a chart shows *the last few minutes*. Open the **AI Assistant** and ask:

> "Add a live chart to my Line 3 panel that trends `sensor/temperature` over time."

Review what it added in the Dashboard Manager — the panel now reads:

```lot wrap focus={13-16} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Line3ShiftLead
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line 3 — Shift Lead"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 150
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
        ADD THRESHOLD AT 100 WITH COLOR "warning"

    ADD COMPONENT "TempTrend" WITH TYPE "realtime-chart"
        SET LABEL "Temperature Trend"
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
```

The `realtime-chart` accumulates every published value into a trend — with the simulator from step 1 running, the line starts drawing itself within seconds.

**6. Add a pump switch**

Add a **toggle** that tracks the live pump state — it flips the moment the bound topic changes. Publish `true` or `false` to `zone1/pump/state` in the Data Viewer to see it move:

```lot wrap focus={18-20} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Line3ShiftLead
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line 3 — Shift Lead"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 150
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
        ADD THRESHOLD AT 100 WITH COLOR "warning"

    ADD COMPONENT "TempTrend" WITH TYPE "realtime-chart"
        SET LABEL "Temperature Trend"
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"

    ADD COMPONENT "PumpToggle" WITH TYPE "toggle"
        SET LABEL "Pump"
        BIND STATE TO TOPIC "zone1/pump/state"
```

**7. Wire an action**

Events and actions are what make a panel *do* things, not just show them. Add a **button** that publishes a start command when clicked:

```lot wrap focus={22-25} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Line3ShiftLead
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line 3 — Shift Lead"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 150
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
        ADD THRESHOLD AT 100 WITH COLOR "warning"

    ADD COMPONENT "TempTrend" WITH TYPE "realtime-chart"
        SET LABEL "Temperature Trend"
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"

    ADD COMPONENT "PumpToggle" WITH TYPE "toggle"
        SET LABEL "Pump"
        BIND STATE TO TOPIC "zone1/pump/state"

    ADD COMPONENT "StartButton" WITH TYPE "button"
        SET LABEL "Start Line"
        ON CLICK DO
            PUBLISH TOPIC "line3/commands/start" WITH 1
```

Watch it work: subscribe to `line3/commands/start` in the [Data Viewer](/hub/mqtt/data-viewer), click the button, and the `1` arrives instantly.

The full set of events (clicks, changes, thresholds) and actions (publish, navigate, invoke, trigger) is in [Actions & Events](/latest/lot-language/panels/actions-events).

Save, and the console is complete — verify the labels and ranges; operators will rely on this screen.

![The finished Line 3 Shift Lead panel showing a temperature gauge, a live temperature trend chart, a pump toggle, and a Start Line button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/tutorial/line3-hero.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d5ee7920b953f0b16f80cb363f64b85f)

The final result: gauge, live trend chart, pump toggle, and start button — all live

**8. Put it on a second screen**

In the Dashboard Manager, hover the panel row and click **Broadcast in new tab**. Copy the URL into any browser — a wall TV, a tablet, a kiosk. Same live data, no HUB access required.

## The complete panel

Everything from the steps above in one copy-paste definition:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Line3ShiftLead
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Line 3 — Shift Lead"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 150
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
        ADD THRESHOLD AT 100 WITH COLOR "warning"

    ADD COMPONENT "TempTrend" WITH TYPE "realtime-chart"
        SET LABEL "Temperature Trend"
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"

    ADD COMPONENT "PumpToggle" WITH TYPE "toggle"
        SET LABEL "Pump"
        BIND STATE TO TOPIC "zone1/pump/state"

    ADD COMPONENT "StartButton" WITH TYPE "button"
        SET LABEL "Start Line"
        ON CLICK DO
            PUBLISH TOPIC "line3/commands/start" WITH 1
```

## Where to go next

> **[Component reference](/hub/dashboards/components/display)**
>
> Every widget, property, and bind target.

> **[Common patterns](/hub/dashboards/patterns)**
>
> Ready-to-adapt recipes: KPI walls, control panels, and model-backed dashboards.


# Creating Agents in Coreflux
Source: https://docs.coreflux.org/latest/quick-start/creating-agents

Add AI to Coreflux in minutes — talk to live data and put intelligence inside LoT automations, bringing AI to your solutions.

## Turn Your Broker Into a Teammate — and Your Automations Into Thinkers

Your devices, integrations, and databases already run on Coreflux — whether you monitor a factory, a solar site, a building portfolio, or a mobile fleet. **AI agents** live in LoT on that same broker: no separate AI platform, no copy-paste into another chat app.

**Talk with live data and automate with judgment.** Teams ask in plain language and get answers from what the broker sees *right now*. Your **Actions** already react to MQTT and timers; with agents they can also **reason** on a schedule or when an event fires — a status digest, a plain-language take on an alarm, a handover brief — all through `CALL AGENT` in LoT.

| What you gain | Example (any vertical) |
| - | - |
| **Ask the system, don't only chart it** | *"Which zones are offline?"* · *"What's output at site B?"* · *"Any inverters under target?"* |
| **Smarter automations, not more scripts** | A timer or topic wakes an agent; LoT publishes the result — no babysitting a workflow |
| **Reports while you sleep** | Hourly or daily digest on MQTT for supervisors, facility managers, or NOC staff |
| **Specialists, not one overloaded chatbot** | A guide for people, a reporter on a schedule, an analyst when alarms fire — each with its own job |

You define two things: a **`TYPE LLM` connector** (the model, the key, the price) and a **`DEFINE AGENT`** that uses it. The agent can do nothing until `ADD TOOL` grants a tool. Full options — grants, delegation, topics — are in [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

> [!TIP]
>
> **Like a supervisor on the floor and an analyst on the line.** People get answers when they ask; your automations get judgment when something changes — all on the broker you already run.

***

## Ready-to-Use Use Cases (Copy & Deploy)

> [!NOTE]
>
> The full `DEFINE AGENT` reference lives in the **LoT AGENT** section: [Agents Overview](/latest/lot-language/agents/overview), [Agent Syntax](/latest/lot-language/agents/syntax), and [Agent Examples](/latest/lot-language/agents/examples).

Each tab is a full recipe: an LLM connector, an agent, and an Action where the work is scheduled or triggered. Adapt names to your vertical — examples in the table.

| Use case | Who benefits | How it runs |
| - | - | - |
| **Talk with your data** | Operators, support, NOC | Ask on `agents/site/<session>/ask`, read `agents/site/<session>/response` |
| **Automatic report** | Supervisors, managers | Scheduled summary on `reports/operations/hourly` |
| **Alert triage** | On-call, maintenance | Each alert gets a short AI explanation |
| **Shift handover** | Shift leads, crews | Plain-language brief before the next rotation |

Some examples of use-cases for your industry:

| Vertical | Typical data topics | Automatic report might cover |
| - | - | - |
| **Manufacturing** | `production/`, `lines/`, `quality/` | Throughput, downtime, batch issues |
| **Solar & energy** | `solar/`, `inverters/`, `grid/` | Generation, underperformance, curtailment |
| **Smart buildings** | `buildings/`, `hvac/`, `occupancy/` | Comfort, energy, fault patterns |
| **Fleet & logistics** | `fleet/`, `vehicles/`, `connectors/` | Utilisation, delays, asset health |

### Before you start

* A **running broker** — [Installation](/latest/quick-start/installation) and [Getting Started](/latest/quick-start/getting-started) if you are new
* A **Growth or Enterprise** license. Community refuses `-addAgent`. See [Licensing](/latest/mqtt-broker/licensing#plans)
* A **model provider** — OpenAI, Anthropic, an OpenAI-compatible gateway, or **local Ollama** on the broker host. Every recipe below uses **OpenAI**. Swap `PROVIDER`, `MODEL`, and the secret name for another provider (see [Picking a provider](/latest/lot-language/routes/ai-routes#picking-a-provider))
* A **broker user** named in `DEFAULT_USER`. Each recipe uses `operator`. Create that user first (`-addUser operator …`). Tasks started by an Action run as this user, and the user must be allowed to do what the grants allow

Store an [OpenAI API key](https://platform.openai.com/api-keys) once:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP SECRET "OPENAI_API_KEY" WITH "sk-..."
```

Deploy the connector with `-addConnector` and the agent with `-addAgent` (LoT Editor, a LoT Notebook, or `$SYS/Coreflux/Command`). The agent does not show up under Connectors.

> [!NOTE]
>
> The **[HUB AI Assistant](/hub/ai-assistant)** (Coreflux icon in the dock) is a separate helper. It can run inside the HUB, or as a broker agent the wizard installs. This guide is about **your** agents — the ones you write in LoT.

**Talk with your data**

**Outcome:** Anyone who can publish to the interaction topic can ask a question. The agent reads live MQTT under `telemetry/#` and can list what is loaded.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiteModel WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"

DEFINE AGENT SiteGuide
    USES LLM CONNECTOR SiteModel
    WITH DESCRIPTION "Answers questions about this site from live MQTT"
    WITH DEFAULT_USER "operator"
    WITH SYSTEM_PROMPT "You are a site operations guide. Use your tools to answer from live MQTT data. Be concise."
    WITH INTERACTION_TOPIC "agents/site"
    ADD TOOL "read_mqtt"
        WITH TOPICS "telemetry/#"
    ADD TOOL "read_lot"
```

**1. Deploy and confirm**

Add **SiteModel** as a connector and **SiteGuide** as an agent. `-listAgents` should show `SiteGuide` as `online`. Read `$SYS/Coreflux/Agents/SiteGuide/status` if it stays in `error` — usually the connector has not started, or `operator` does not exist.

**2. Ask a real question**

In MQTT Explorer or HUB [Data Viewer](/hub/mqtt/data-viewer), publish to `agents/site/s1/ask` and subscribe to `agents/site/s1/response`. `s1` is the session. A later question on `s1` continues that conversation for the same user.

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Which sensors have been updated in the last few minutes?
```

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
What is the latest data on telemetry/zone1/status?
```

Rename `telemetry/` in the grant to `production/`, `solar/`, `buildings/`, or your own tree. A wildcard read shortens payloads over 1,024 characters. Reading the exact topic returns the whole payload.

**3. Read the answer on response**

`agents/site/s1/response` carries the agent's answer. Tool calls for that session appear on `$SYS/Coreflux/Agents/SiteGuide/task/s1/stream` when your user may subscribe to `$SYS`.

> [!TIP]
>
> You just **talked with your data**. No extra AI server — the agent runs where your MQTT already lives.

**Automatic report**

**Outcome:** **LoT automation with AI** — on a schedule, an Action calls the agent and publishes an **operations summary** to MQTT. No chat window.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiteModel WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"

DEFINE AGENT OperationsReporter
    USES LLM CONNECTOR SiteModel
    WITH DESCRIPTION "Writes the hourly operations summary"
    WITH DEFAULT_USER "operator"
    WITH SYSTEM_PROMPT "You write operations reports from live MQTT. Use your tools on telemetry/ topics. Bullet points: current status, anomalies, items needing follow-up. Plain language for managers."
    WITH MEMORY "none"
    ADD TOOL "read_mqtt"
        WITH TOPICS "telemetry/#"

DEFINE ACTION HourlyOperationsReport
ON EVERY 1 HOUR DO
    CALL AGENT "OperationsReporter.execute"
        WITH (task = "Hourly operations report: summarise key signals from telemetry/ topics, flag anything off-norm or stale, note follow-ups before the next review period.")
        RETURN AS {report}
    PUBLISH TOPIC "reports/operations/hourly" WITH {report}
```

**1. Deploy the connector, the agent, and the Action**

There is no interaction topic. Only the schedule triggers this agent. A successful `CALL AGENT` returns the answer text in `{report}`.

**2. Subscribe to the report**

Subscribe to `reports/operations/hourly` in MQTT Explorer, a dashboard, or the HUB Data Viewer.

**3. See the first report**

Publish sample payloads under your data tree (`telemetry/`, `solar/site1/power`, `buildings/tower/hvac`, and so on), then wait for the next run — or temporarily use `ON EVERY 30 SECONDS` and change it back when done.

> [!TIP]
>
> **Scheduled insight on autopilot** — the report speaks your operation's language, not broker diagnostics.

**Alert triage**

**Outcome:** When something hits your alerts topic, the broker adds a **plain-language triage note** — what it might mean and what to check first.

Works for any alert source: equipment faults, threshold breaches, connectivity, security events.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiteModel WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"

DEFINE AGENT AlertAnalyst
    USES LLM CONNECTOR SiteModel
    WITH DESCRIPTION "Explains one alert in three sentences"
    WITH DEFAULT_USER "operator"
    WITH SYSTEM_PROMPT "You triage operational alerts from MQTT. In 3 short sentences: what happened, likely cause, recommended first check. Be direct."
    WITH MEMORY "none"
    ADD TOOL "read_mqtt"
        WITH TOPICS "alerts/#"

DEFINE ACTION TriageAlert
ON TOPIC "alerts/#" DO
    CALL AGENT "AlertAnalyst.execute"
        WITH (task = "Alert on topic " + TOPIC + ": " + PAYLOAD, session_id = TOPIC)
        RETURN AS {triage}
    PUBLISH TOPIC "agents/site/alerts/analysis" WITH {triage}
```

**1. Wire your alerts**

Ensure your existing logic still publishes under `alerts/` — for example `alerts/inverter/fault`, `alerts/building/leak`, or `alerts/line2/quality`.

**2. Deploy triage**

Add **AlertAnalyst** and **TriageAlert**. Subscribe to `agents/site/alerts/analysis`.

**3. Trigger once**

Publish a test alert to `alerts/test/manual` with any message. Read the analysis on the triage topic. `session_id` is the alert topic, so a repeat of the same topic continues that conversation. Drop `session_id` when every alert must stand alone — `MEMORY "none"` already does that.

> [!TIP]
>
> On-call gets **context with the alarm**, not only a raw payload.

**Shift handover**

**Outcome:** Before each rotation, a **handover brief** lands on MQTT — what changed, what looks odd, what the incoming team should watch. Common in manufacturing, utilities, and 24/7 operations centers.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiteModel WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"

DEFINE AGENT HandoverBrief
    USES LLM CONNECTOR SiteModel
    WITH DESCRIPTION "Writes the shift handover"
    WITH DEFAULT_USER "operator"
    WITH SYSTEM_PROMPT "You write handover notes for operations teams. Bullet points: status, anomalies, open items. Max 8 bullets."
    WITH MEMORY "none"
    ADD TOOL "read_mqtt"
        WITH TOPICS "telemetry/#, alerts/#"

DEFINE ACTION ShiftHandover
ON EVERY 8 HOURS DO
    CALL AGENT "HandoverBrief.execute"
        WITH (task = "Prepare handover for the next shift: current operational status, active alarms, and anything unusual in the last 8 hours.")
        RETURN AS {brief}
    PUBLISH TOPIC "agents/site/shift/handover" WITH {brief}
```

**1. Deploy**

Add **HandoverBrief** and **ShiftHandover**. Subscribe to `agents/site/shift/handover`.

**2. Test faster**

Temporarily use `ON EVERY 2 MINUTES`, read one brief, then restore `ON EVERY 8 HOURS` for production.

> [!TIP]
>
> **Crew change becomes a story**, not a scramble through dashboards.

> [!TIP]
>
> **Starter pack:** **SiteGuide** + **HourlyOperationsReport** + **AlertAnalyst** — ask your deployment, get scheduled insight, enrich every alarm. They can share one `SiteModel` connector. Rename topic grants to `production/`, `solar/`, or `buildings/` when you copy the prompts.

***

## When You're Ready to Grow

You already have the building blocks: **chat** (`{INTERACTION_TOPIC}/<session>/ask`), **schedules** (`ON EVERY`), and **event-driven** (`ON TOPIC`) automations with `CALL AGENT`. Next is a writing grant (`ADD TOOL "write_mqtt"` with `WITH LEVEL "write"`), peers the agent may call (`WITH AGENTS`), and [MCP Connectors](/latest/lot-language/routes/mcp-routes) called from Actions.

For several agents on one broker, see [Multi-agent deployments](/latest/lot-language/agents/syntax#delegation-with-agents).

If you still have a `TYPE AGENT` connector from an earlier release, rewrite it before you upgrade. The broker skips those connectors at load. See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).

***

## Stay Safe While You Experiment

> **Try read-only first**
>
> Grant only `read_mqtt` and `read_lot` until you trust the prompt. For one question, publish JSON `{ "text": "…", "mode": "insight" }` on the ask topic. Insight mode refuses every writing tool, including in agents this one calls. A default of insight mode on the agent itself is not available yet.

> **Keep API keys off the clipboard in LoT files**
>
> Always use `GET SECRET "OPENAI_API_KEY"` on the `TYPE LLM` connector — never paste keys into definitions that get saved or shared.

> **Match the agent to the audience**
>
> An interaction topic is for people. Timed Actions are for machines. Leave `INTERACTION_TOPIC` off agents that should only run in the background.

> **Say who the agent is**
>
> `DEFAULT_USER` is required. Pick a user that can do the job, and grant `ADD TOOL` only the topics that job needs. A writing tool also needs `WITH LEVEL "write"`.

***

## What to Explore Next

> **[AI Connectors and Agents](/latest/lot-language/routes/ai-routes)**
>
> Providers, tool grants, delegation, topics, and the move off TYPE AGENT.

> **[Using AI with Coreflux](/latest/quick-start/using-ai)**
>
> Use MCP in your editor to write LoT faster — separate from agents running on the broker.


# Getting Started
Source: https://docs.coreflux.org/latest/quick-start/getting-started

Go from zero to your first working LoT Action in under 15 minutes.

![Coreflux HUB overview screen with a 'Start here' arrow pointing to the first navigation icon in the bottom toolbar](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/overview/hub-overview-start.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=bab525c05994ccb1c98530f1b50f40e1)

Coreflux HUB overview — start here

## Why This Guide?

This is the fastest way to validate your Coreflux setup: in under 15 minutes you'll have a live LoT (Language of Things) Action running inside your broker—proof that your installation works and logic executes at the edge. New to Coreflux? Start with the [Overview](../index).

> [!TIP]
>
> **Like installing an app on your router instead of your phone.** LoT Actions run directly inside the broker -- your logic executes at the edge without an external script or server.

## Prerequisites

Before you begin, ensure you have:

* **A running Coreflux Broker** — See the [Installation Guide](/latest/quick-start/installation) if you haven't set one up yet
* **VS Code** with the LoT Notebooks extension *or* access to the [Coreflux HUB](/hub/overview) in your browser — see the [VS Code Setup Guide](/latest/quick-start/vscode) for the extension
* **Basic MQTT knowledge** — Understanding of topics, publish/subscribe patterns

***

Ready? Here's what you'll build and deploy.

## Your First LoT Action in 15 Minutes

> **Concept Refresher**: You are about to write an action that lives and runs **inside** the broker, not on your laptop.

Let's create a **simulated temperature sensor** that publishes a temperature reading every 5 seconds. You'll see data on a topic as soon as you deploy—no external input required. This keeps the whole guide in a single "temperature monitoring" flow.

### Understanding the Action

LoT Actions have three parts:

1. **Definition** — `DEFINE ACTION <name>`
2. **Trigger** — When to run (`ON EVERY <time>`, `ON TOPIC "<topic>"`, or `ON CHANGE "<topic>"` for value-change-only)
3. **Logic** — What to do (publish data, conditional logic, etc.)

Here's what we're building:

```lot Temperature Simulator wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureSimulator
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "sensors/zone1/temperature" WITH "{\"temperature\": 72}"
```

| Line | What it does |
| - | - |
| `DEFINE ACTION TemperatureSimulator` | Creates an action named "TemperatureSimulator" |
| `ON EVERY 5 SECONDS DO` | Sets a time-based trigger (runs every 5 seconds) |
| `PUBLISH TOPIC ... WITH "{\"temperature\": 72}"` | Publishes a JSON payload with temperature in Fahrenheit (72°F) |

> [!NOTE]
>
> Quotes inside strings must be escaped with backslashes (e.g. `"{\"temperature\": 72}"`).

For a complete reference on triggers, operations, and advanced patterns, see the [Actions documentation](/latest/lot-language/actions/overview).

### Deploy the Action

**Coreflux HUB**

If you have the Coreflux HUB running—via Docker Compose or the standalone desktop app for Windows or Linux—you can deploy actions directly from the HUB. See [Installation](/latest/quick-start/installation) and the [Coreflux HUB Overview](/hub/overview).

**1. Open the HUB**

In your browser, open `http://localhost:3000` for Docker Compose. Click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`). For the standalone desktop app, run the executable and create a connection to your broker.

**2. Go to LoT Editor**

Select **LoT Editor** in the HUB dock. In the **WORKSPACE** section of the sidebar, click **＋ New** to create a project, then add a **`+ Code`** cell to its notebook. See [LoT Editor](/hub/lot-editor) for the full editor reference.

**3. Paste the Action Code**

Paste the following code into the cell (no `-addAction` prefix needed—the HUB handles registration):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureSimulator
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "sensors/zone1/temperature" WITH "{\"temperature\": 72}"
```

**4. Run the cell**

Click the cell's **run** button (or press `Shift`+`Enter`) to deploy it. The cell's badge changes to **`SYNCED`** and the Action appears under **Broker → Entities → Actions** — it is now running on the broker.

**VS Code Extension**

> [!TIP]
>
> The VS Code extension provides syntax highlighting, auto-completion, and real-time validation for LoT actions. See the [LoT Notebooks Setup Guide](/latest/quick-start/vscode) for full installation and configuration details.

**1. Ensure you have the LoT Notebooks extension installed**

Open the extension panel, search for 'LoT Notebooks', and install.

**2. Create a new LoT Notebook file**

Click on File > New File..., give it it to a descriptive name (e.g., temperature-monitor).

![Animated walkthrough of creating a new .lotnb file in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lotnb-create-new.gif?s=6f76d28d7999e12459a044e460d414bc)

Creating a new LoT Notebook file in VS Code

**3. Connect to Your Broker**

Enter your broker credentials (host, port, username, password) and click Connect.

![Animated walkthrough of entering broker credentials and connecting in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-broker-connect.gif?s=faf63084741fb786ec1807145f691a89)

Connecting to your Coreflux broker from VS Code

> **Default Broker Credentials**
>
> If you haven't changed your broker credentials, use these defaults:
>
> | Setting | Value |
> | - | - |
> | Host | `localhost` or your server IP |
> | Port | `1883` (unencrypted) / `8883` (TLS) |
> | Username | `root` |
> | Password | `coreflux` (change immediately!) |

**4. Create a New Action**

Create a new code block and add your code.

![Animated walkthrough of creating a new code block](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-basic-action.gif?s=f0a99e24fb50a62f34539d706812f912)

Creating a new LoT code cell in the notebook

**5. Paste the Action Code**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureSimulator
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "sensors/zone1/temperature" WITH "{\"temperature\": 72}"
```

**6. Deploy**

Click the **Run Button** on that specific cell to publish the action to your broker.

![Animated walkthrough of clicking the Run button to deploy the action to the broker](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-deploy-basic-action.gif?s=d7edcd18dc774cad66ff4969543e29ae)

Running the LoT action from the notebook cell

**MQTT Client**

If you're using any external MQTT client, publish to the system command topic:

**1. Connect**

Connect to your broker with your credentials.

**2. Publish the Action**

Publish the following to `$SYS/Coreflux/Command`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION TemperatureSimulator
ON EVERY 5 SECONDS DO
    PUBLISH TOPIC "sensors/zone1/temperature" WITH "{\"temperature\": 72}"
```

**3. Check the Response**

Subscribe to `$SYS/Coreflux/Command/Output`. A successful deploy looks like:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "command": "AddAction",
  "message": "Action 'TemperatureSimulator' added successfully.",
  "entityType": "Action",
  "entityName": "TemperatureSimulator",
  "data": {}
}
```

> [!NOTE]
>
> Note the `-addAction` prefix — this tells Coreflux to register the action definition that follows.

### Verify It's Running

**Coreflux HUB**

If you deployed via the HUB, verify using the built-in Data Viewer. In the top navigation, select **MQTT**, then **Data Viewer**. In the Topic Tree, navigate to **sensors** → **zone1** → **temperature**. You should see `{"temperature": 72}` arriving every 5 seconds in the payload viewer.

![Coreflux HUB Data Viewer with the topic tree and live payload for a sensor temperature topic](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/mqtt-explorer-topic.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=25ff42296df2fa4236ffe15b6cbdeaed)

Data Viewer showing live temperature messages on sensors/zone1/temperature

**VS Code Extension**

The LoT extension automatically shows debug values for MQTT topics, so you can verify in two ways:

**1. Check the Actions list**

If the action appears in your Actions list under the Coreflux Entities tab, it should be running.

**2. Check live values in the extension**

After deploying, the extension automatically subscribes to the action's topics and displays live MQTT messages. You should see temperature readings (e.g. `{"temperature": 72}`) on `sensors/zone1/temperature` arriving every 5 seconds.

![Coreflux Entities panel in VS Code showing TemperatureSimulator under the Actions list](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-verify-basic-action.gif?s=39e19beef3d939f9f6c9a2d5ceeb7d7b)

TemperatureSimulator action listed in the Coreflux Entities panel

**MQTT Client**

Subscribe to `sensors/zone1/temperature`. You should see temperature readings arriving every 5 seconds:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"temperature": 72}
```

**Congratulations!** Your first LoT Action is live.

## Example Real Scenario: Temperature Alarm

Now let's create a **reactive action** that transforms sensor data and checks thresholds. This demonstrates data transformation and conditional logic—common patterns in industrial monitoring.

> [!NOTE]
>
> This action runs **only when a message arrives** on `sensors/+/temperature`. After you deploy it, you will see no output until something publishes to that topic—for example, the Temperature Simulator from the previous section (if both are running), or a manual publish from the HUB Data Viewer or any MQTT client.

Here's what the action does each time a new temperature reading arrives:

1. **Trigger** — The action fires whenever a message is published to any topic matching `sensors/+/temperature` (e.g. `sensors/zone1/temperature`).
2. **Extract** — It reads the `temperature` value (in Fahrenheit) from the incoming JSON payload.
3. **Convert** — It transforms Fahrenheit to Celsius using the standard formula: `(F − 32) × 5 / 9`.
4. **Decide** — If the Celsius value exceeds 35 °C, it publishes an alert to `alerts/high_temp`. Otherwise, it publishes the normalized Celsius reading to `sensors/normalized`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureAlarm
ON TOPIC "sensors/+/temperature" DO
    SET "temp_f" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    SET "temp_c" WITH (({temp_f} - 32) * 5 / 9)
    IF {temp_c} > 35 THEN
        PUBLISH TOPIC "alerts/high_temp" WITH ("Alert: " + {temp_c} + "°C exceeds threshold")
    ELSE
        PUBLISH TOPIC "sensors/normalized" WITH {temp_c}
```

> [!NOTE]
>
> The `{}` denotes variable substitution, and expressions must be wrapped in parentheses. The `+` in the topic pattern is a single-level MQTT wildcard -- it matches any value in that position (e.g. `sensors/zone1/temperature`, `sensors/zone2/temperature`).

### Deploy and Test

Deploy this action using the same method as above (Coreflux HUB, VS Code extension, or MQTT client). Once deployed, use the steps below to verify reactive logic.

### How to Test the Logic

The action subscribes to any topic matching `sensors/+/temperature` (e.g. `sensors/zone1/temperature`). It expects a JSON payload with a `temperature` key (Fahrenheit). It then converts to Celsius and either publishes an alert (if > 35°C) or the normalized value.

| Role | Topic | Description |
| - | - | - |
| **Input** | `sensors/zone1/temperature` | Publish test payloads here (must match `sensors/+/temperature`) |
| **Output (normal)** | `sensors/normalized` | Receives the Celsius value when temperature is at or below 35°C |
| **Output (alert)** | `alerts/high_temp` | Receives the alert message when temperature exceeds 35°C (e.g. 95°F) |

**Sample payloads (copy-paste):**

* **Below threshold** — publish to `sensors/zone1/temperature`:
  ```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
  {"temperature": 77}
  ```
  Expect: a message on `sensors/normalized` with the Celsius value (about 25).
* **Above threshold** — publish to `sensors/zone1/temperature`:
  ```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
  {"temperature": 95}
  ```
  Expect: a message on `alerts/high_temp` with text like "Alert: 35°C exceeds threshold".

**Coreflux HUB**

**1. Deploy the Temperature Alarm action**

In **LoT** → **LoT Editor** → **Actions**, create a new action or open an existing one, paste the Temperature Alarm code, and save. Confirm it appears in the Actions list.

**2. Open the Data Viewer**

Select **MQTT** → **Data Viewer**. In the Topic Tree, watch `sensors/normalized` and `alerts/high_temp` (add them to your tracked view if needed).

![Coreflux HUB Data Viewer with the Publish panel on the left, Topic Tree in the center, and a tracked topic with live values on the right](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/mqtt-explorer-overview.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=e9fdfa778a5c182a4c8a3404a3707f30)

Coreflux HUB Data Viewer — Publish panel, Topic Tree, and live topic details

**3. Send test data**

In the **Publish** panel, set the topic to `sensors/zone1/temperature` and paste one of the sample JSON payloads above. Click publish. If the Temperature Simulator is still running, it already publishes every 5 seconds—you will see results on `sensors/normalized` (72°F is below 35°C).

**4. Confirm output**

Select the output topic in the tree and verify the payload in the viewer (normalized value or alert text).

**VS Code Extension**

**1. Deploy the Temperature Alarm action**

Paste the action code in a LoT cell and run it. Confirm success in the Actions list.

**2. Observe output topics**

After deploying, the extension automatically subscribes to the action's output topics and displays their values. Look for messages on `sensors/normalized` and `alerts/high_temp` once test data is published.

**3. Send test data**

Use the HUB Data Viewer, the VS Code extension publish tools, or any MQTT client to publish one of the sample JSON payloads above to `sensors/zone1/temperature`. If the Temperature Simulator from the previous section is still running, it already publishes every 5 seconds and you will see results on `sensors/normalized` (72°F is below 35°C). Check the topic tree displayed below the code cell to see incoming values update in real time.

**4. Confirm output**

Check that the corresponding output topic received the expected message (normalized value or alert).

**MQTT Client**

**1. Deploy the Temperature Alarm action**

Publish the action to `$SYS/Coreflux/Command` with the `-addAction` prefix. On `$SYS/Coreflux/Command/Output`, confirm `"success": true` and that `message` reports Action `TemperatureAlarm` added.

**2. Subscribe to output topics**

Subscribe to `sensors/normalized` and `alerts/high_temp` so you can see responses.

**3. Publish a test payload**

Publish to topic `sensors/zone1/temperature` with payload `{"temperature": 77}` or `{"temperature": 95}` (use one of the sample payloads above).

**4. Confirm output**

You should see a message on `sensors/normalized` (for 77°F) or on `alerts/high_temp` (for 95°F).

This confirms your broker transforms data and applies conditional logic in real time.

### Clean Up (Optional)

To remove the test action:

**Coreflux HUB**

In the **LoT Editor**, expand **Broker → Entities → Actions** in the sidebar, right-click the action, and choose **Remove from broker…**. Confirm—the action is removed from the broker immediately. See [Removal](/hub/lot-editor#removal-four-different-operations) for the other flows.

**VS Code Extension**

On the Coreflux Entities tab, right-click the desired action in your Actions list and select **"Remove"**.

**MQTT Client**

Publish to `$SYS/Coreflux/Command`:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removeAction TemperatureAlarm
```

## Quick Examples

Looking for inspiration? Check out the [**Language of Things Training Repository**](https://github.com/CorefluxCommunity/Language-Of-Things-Training) for common patterns like:

* **Topic-Based Triggers**: Echo messages between topics
* **State Machines**: Toggle switches and conditional logic
* **Event Counters**: Track and aggregate system events

> **[Language of Things Training](https://github.com/CorefluxCommunity/Language-Of-Things-Training)**
>
> Explore a collection of ready-to-use LoT Action examples and templates.

## Troubleshooting

> **Action not executing?**
>
> * Verify the broker is running and you're connected
> * Check `$SYS/Coreflux/Command/Output` for error messages
> * Ensure proper indentation in your LoT action (use consistent tabs or spaces)
> * Confirm the action appears in `$SYS/Coreflux/Actions` or in the HUB LoT Editor Actions list

> **Can't connect to the broker?**
>
> * Verify the broker hostname/IP and port are correct
> * Check that port 1883 (or 8883 for TLS) is open
> * Confirm your username and password are correct
> * If using TLS, ensure certificates are properly configured

> **Messages not appearing on subscribed topics?**
>
> * Verify you're subscribed to the exact topic (including case sensitivity)
> * Check if any Rules are blocking access to the topic
> * Use wildcards (`+` or `#`) to debug topic hierarchies

## Next Steps

Now that you have a working setup, explore the core LoT components:

> **[Actions](/latest/lot-language/actions/syntax)**
>
> React to events and publish data. Create time-based automations or respond to topic changes.

> **[Introduction to LoT](/latest/lot-language/introduction)**
>
> Understand the core concepts and architecture of the Language of Things.


# Installation
Source: https://docs.coreflux.org/latest/quick-start/installation

Get a Coreflux broker and HUB running in minutes with Docker, the HUB desktop app, a free Cloud Trial, or native installs for Windows and Linux.

## Install Coreflux

Most people should use **Docker** or **Docker Compose** for the broker and the [Coreflux HUB](/hub/overview). Native broker installs are in the **Linux** and **Windows** tabs. Just evaluating with nothing to install? Use the [Cloud](#cloud-trial) tab. The **HUB desktop** tab is the standalone app. Packages and desktop builds are on the [Downloads page](https://portal.coreflux.org/downloads).

> [!TIP]
>
> **Coreflux runs as a single install.** No separate databases or message queues—pick a method below and run it.

> **Default login credentials**
>
> Every local install method uses the same defaults:
>
> | Setting | Value |
> | - | - |
> | Username | `root` |
> | Password | `coreflux` |
>
> For a **Cloud Trial**, open the broker in **Coreflux Fleet** at [portal.coreflux.org](https://portal.coreflux.org). The address and login are on that page.

***

**Docker**

> [!TIP]
>
> **\~2 min** if Docker is already installed — broker, HUB, or both.

The broker and [Coreflux HUB](/hub/overview) are **separate images**. Pick the command that matches what you want to run. The HUB desktop app is in the **HUB desktop** tab.

> [!NOTE]
>
> When you open the web HUB, the browser can install it as an app that opens in its own window. Use the browser's install control — often **Install** or **Add to Home Screen**. Browsers offer this on `localhost` and on HTTPS. The **HUB desktop** app is already installed and does not use this.

> [!NOTE]
>
> New to Docker? Install it from the [official Docker install page](https://docs.docker.com/get-started/get-docker/), then confirm with `docker --version` before you continue. Images are on [Docker Hub](https://hub.docker.com/r/coreflux/coreflux-mqtt-broker).

**Broker only**

Start the broker. Docker fetches the latest image automatically:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -p 9100:9100 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest
```

MQTT is on `localhost:1883`. There is no HUB in this command — use **HUB only** or **Broker + HUB**, or the standalone HUB app.

**HUB only**

Start the HUB and connect it to a broker that is already running:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d --name coreflux_hub -p 3000:3000 -v hub-data:/opt/coreflux-hub/data coreflux/coreflux-hub:latest
```

Open `http://localhost:3000`. Click **New Connection** (or **Connect** on a saved one). If the broker is on the same machine, set **Protocol** `mqtt://`, **Host** `host.docker.internal` (Docker Desktop) or the host's LAN IP, and **Port** `1883` — not `localhost`, because the HUB proxies MQTT from inside its container.

**Broker + HUB**

Create a shared network and start both containers in one command:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker network create coreflux && docker run --pull=always -d --name coreflux_broker --network coreflux --network-alias broker -p 1883:1883 -p 5000:5000 -p 9100:9100 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest && docker run --pull=always -d --name coreflux_hub --network coreflux -p 3000:3000 -v hub-data:/opt/coreflux-hub/data coreflux/coreflux-hub:latest
```

Open the HUB at `http://localhost:3000`, click **New Connection**, and connect with **Protocol** `mqtt://`, **Host** `broker`, **Port** `1883` (or **Protocol** `ws://`, **Host** `broker`, **Port** `5000`, **Path** `mqtt`). Skip `docker network create coreflux &&` if the `coreflux` network already exists.

| Port | Service | Description |
| - | - | - |
| `1883` | Broker | MQTT (unencrypted) |
| `5000` | Broker | WebSocket / HTTP API |
| `9100` | Broker | [Operational endpoints](/latest/mqtt-broker/operational-endpoints): `/health`, `/ready`, `/info`, `/license`, `/metrics` |
| `3000` | HUB | [Coreflux HUB](/hub/overview) |

The broker's [MCP server](/latest/mqtt-broker/mcp-server) has its own port, `6278`. It's off by default and isn't published here. To reach it from outside the container, see [Docker and Kubernetes](/latest/mqtt-broker/mcp-server#docker-and-kubernetes).

> [!WARNING]
>
> Port `3000` serves the HUB over plain HTTP. Open it on `localhost`, or put it behind a reverse proxy that terminates TLS and open it over HTTPS. Browsers only allow clipboard access on HTTPS or `localhost`, so on current HUB versions the copy buttons fail when you open the HUB as `http://<LAN IP>:3000`. See [Copy buttons don't work](#copy-buttons-dont-work-in-the-hub) under troubleshooting.

| Command | Broker fields on **New Connection** |
| - | - |
| Broker + HUB | Protocol `mqtt://`, Host `broker`, Port `1883` (or `ws://`, Host `broker`, Port `5000`, Path `mqtt`) |
| HUB only | Protocol `mqtt://`, Host `host.docker.internal` if the broker is on the same machine, or the broker's host address |

The HUB proxies MQTT from inside Docker, so **Host** `localhost` does not reach a broker container.

That's it—Coreflux is now running locally. Confirm it works under [Verify Installation](#verify-installation) below.

> **What does the broker command do?**
>
> Breaking the broker `docker run` down piece by piece:
>
> * `--pull=always` — always fetch the latest image before starting, so you never run a stale version.
> * `-d` — runs the container **detached** (in the background), so your terminal stays free.
> * `--name coreflux_broker` — names the container so you can reference it later (for example `docker logs coreflux_broker`).
> * `-p 1883:1883 -p 5000:5000 -p 9100:9100` — each `-p host:container` maps a port on your machine to the same port inside the container. See the port table above for what each one is for.
> * `-v project-volume:/etc/project` — mounts a named volume so your project (LoT, connectors, configuration) persists across restarts and image updates.
> * `coreflux/coreflux-mqtt-broker:latest` — the broker image, pulled from Docker Hub. The HUB image is `coreflux/coreflux-hub:latest`.

> **TLS/SSL Ports (when using certificates)**
>
> If you configure TLS certificates, expose these additional broker ports (`8883` and `443`):
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> docker run --pull=always -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -p 9100:9100 -p 8883:8883 -p 443:443 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest
> ```
>
> | Port | Protocol | Description |
> | - | - | - |
> | `8883` | TCP/TLS | MQTT over TLS |
> | `443` | WSS | WebSocket / HTTP API over TLS |
>
> See [Broker Configuration](/latest/mqtt-broker/configuration) for TLS setup.

**Docker Compose**

> [!TIP]
>
> **\~3 min** if Docker is already installed — broker and HUB on one network.

Docker Compose starts the broker and the [Coreflux HUB](/hub/overview) as two services on a shared network. Use the `full` profile to run both, or start either service alone. The HUB desktop app is in the **HUB desktop** tab. The web HUB can be installed from the browser as its own window — same install control as in the **Docker** tab (`localhost` or HTTPS).

Create a directory, then add `docker-compose.yml`:

```yaml wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
    # Coreflux — Broker + Hub deployment
    #
    # Profiles:
    #   full   -> broker + hub, on the same network
    #   broker -> broker only
    #   hub    -> hub only
    #
    # Usage:
    #   docker compose --profile full up    # broker + hub
    #   docker compose --profile broker up  # broker only
    #   docker compose --profile hub up     # hub only

    services:
      broker:
        image: coreflux/coreflux-mqtt-broker:latest
        profiles: [full, broker]
        container_name: coreflux-broker
        restart: unless-stopped
        ports:
          - "1883:1883"   # MQTT (plain TCP)
          - "8883:8883"   # MQTT over TLS
          - "5000:5000"   # WebSocket transport / HTTP API
          - "443:443"   # WebSocket / HTTP API over TLS
          - "9100:9100"   # Operational endpoints: /health /ready /info /license /metrics
        volumes:
          # Persists everything under /etc/project (signed license, enrollment,
          # encrypted config, connectors, actions, models, rules, logs, stats, projects).
          - broker-data:/etc/project
        # The published image has no shell, so a shell-based
        # healthcheck cannot run inside the container. Check health externally
        # via HTTP GET http://localhost:9100/health.
        healthcheck:
          disable: true

      hub:
        image: coreflux/coreflux-hub:latest
        profiles: [full, hub]
        container_name: coreflux-hub
        restart: unless-stopped
        ports:
          - "3000:3000"   # Web UI + API + MQTT WebSocket proxy (plain HTTP)
        volumes:
          # Persists writable Hub state (e.g. theme-media uploads).
          - hub-data:/opt/coreflux-hub/data
        # environment:
        #   - HUB_DEFAULT_CONNECTION_HOST=broker
        #   - HUB_DEFAULT_CONNECTION_PROTOCOL=mqtt
        #   - HUB_DEFAULT_CONNECTION_PORT=1883
        #
        # Those variables pre-fill New Connection in the web HUB. They do not
        # save a connection. Because the HUB proxies the MQTT connection
        # server-side, use the broker service name (not "localhost"):
        #   mqtt://broker:1883      (plain MQTT)
        #   ws://broker:5000/mqtt   (MQTT over WebSocket)

    volumes:
      broker-data:
      hub-data:

    # Both services attach to this network and resolve each other by service
    # name ("broker", "hub").
    networks:
      default:
        name: coreflux
```

Then start the stack:

**Broker + HUB**

From the directory that contains `docker-compose.yml`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker compose --profile full up -d
```

Open the HUB at `http://localhost:3000`. Click **New Connection** and set **Protocol** `mqtt://`, **Host** `broker`, **Port** `1883` — the HUB proxies MQTT from inside Docker, so **Host** `localhost` does not reach the broker container.

**Broker only**

Start just the broker:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker compose --profile broker up -d
```

MQTT is on `localhost:1883`. There is no HUB in this profile.

**HUB only**

Start just the HUB (the broker must already be reachable on the `coreflux` network, or you will connect to a remote broker from the UI):

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker compose --profile hub up -d
```

Open the HUB at `http://localhost:3000`, click **New Connection**, and enter the broker **Host**, **Protocol**, and **Port** on the login screen.

| Command | Starts |
| - | - |
| `docker compose --profile full up` | broker + HUB |
| `docker compose --profile broker up` | broker only |
| `docker compose --profile hub up` | HUB only |

| Port | Service | Description |
| - | - | - |
| `1883` | Broker | MQTT (unencrypted) |
| `8883` | Broker | MQTT over TLS |
| `5000` | Broker | WebSocket / HTTP API |
| `443` | Broker | WebSocket / HTTP API over TLS |
| `9100` | Broker | [Operational endpoints](/latest/mqtt-broker/operational-endpoints): `/health`, `/ready`, `/info`, `/license`, `/metrics` |
| `3000` | HUB | [Coreflux HUB](/hub/overview) |

The broker's [MCP server](/latest/mqtt-broker/mcp-server) has its own port, `6278`. It's off by default and isn't published here. To reach it from outside the container, see [Docker and Kubernetes](/latest/mqtt-broker/mcp-server#docker-and-kubernetes).

> [!WARNING]
>
> Port `3000` serves the HUB over plain HTTP. Open it on `localhost`, or put it behind a reverse proxy that terminates TLS and open it over HTTPS. Browsers only allow clipboard access on HTTPS or `localhost`, so on current HUB versions the copy buttons fail when you open the HUB as `http://<LAN IP>:3000`. See [Copy buttons don't work](#copy-buttons-dont-work-in-the-hub) under troubleshooting.

> [!TIP]
>
> The HUB talks to the broker **from inside Docker**. On **New Connection**, set **Host** to the Compose service name (`broker`) — Protocol `mqtt://` and Port `1883`, or Protocol `ws://`, Port `5000`, and Path `mqtt`. Do not use **Host** `localhost`.

That's it—Coreflux is running locally. Confirm it works under [Verify Installation](#verify-installation) below.

> **Check broker health**
>
> The broker image has no shell, so Compose cannot run a healthcheck inside the container. Probe the [operational endpoints](/latest/mqtt-broker/operational-endpoints) from the broker host:
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> curl http://localhost:9100/health
> curl http://localhost:9100/ready
> curl http://localhost:9100/info
> ```
>
> `/health` answers while the process is up. `/ready` stays unavailable until the broker is accepting MQTT connections. `/info` returns version, uptime, and the listener ports.

> **Named volumes**
>
> `broker-data` persists broker configuration, connectors, actions, models, rules, logs, and projects under `/etc/project`. `hub-data` persists HUB state such as theme-media uploads. Stopping or recreating containers does **not** delete these volumes.

> **Stop or remove the stack**
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> docker compose down
> ```
>
> Add `-v` only if you also want to delete the named volumes (this wipes broker and HUB data).

**Linux**

> [!TIP]
>
> **\~10 min** — broker installed from native packages and running as a systemd service.

Install the MQTT broker with your distribution's package manager. Get the packages from the [Downloads page](https://portal.coreflux.org/downloads). The steps below add the repository for Debian-based systems (APT) and RHEL-compatible systems (DNF).

**Debian & Ubuntu (APT)**

APT is the package manager on Debian, Ubuntu, and Debian-based distributions—including **Raspberry Pi OS**. The package manager picks the right architecture (x64 or ARM64) for your machine.

| OS | Codename |
| - | - |
| Ubuntu 22.04 | `jammy` |
| Ubuntu 24.04 | `noble` |
| Debian 12 | `bookworm` |
| Debian 13 | `trixie` |

On Raspberry Pi OS, use the codename that matches your release (for example **bookworm** on Pi OS based on Debian 12, **noble** on releases based on Ubuntu 24.04).

**1. Check your distribution codename**

Run `lsb_release -a` and note the **Codename** line—you will use it in the next step.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
lsb_release -a
```

Example output on Ubuntu 24.04:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Codename:       noble
```

**2. Install the signing key**

Download Coreflux's archive signing key into `/usr/share/keyrings`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo mkdir -p /usr/share/keyrings

curl -fsSL https://packages.coreflux.org/keys/coreflux-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/coreflux-archive-keyring.gpg >/dev/null

sudo chmod 0644 /usr/share/keyrings/coreflux-archive-keyring.gpg
```

**3. Add the APT source**

Run **only** the command that matches your codename. Each command writes `/etc/apt/sources.list.d/coreflux.list`.

**Ubuntu 22.04 (jammy)**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/ubuntu jammy main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**Ubuntu 24.04 (noble)**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/ubuntu noble main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**Debian 12 (bookworm)**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/debian bookworm main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**Debian 13 (trixie)**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/debian trixie main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**4. Install coreflux-broker**

Refresh package lists and install the broker package:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo apt update
sudo apt install coreflux-broker
```

Optional — list available versions before installing:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apt-cache policy coreflux-broker
```

**5. Confirm the service is running**

The package registers and starts `coreflux-broker` as a systemd service:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
systemctl status coreflux-broker.service
```

> [!TIP]
>
> **active (running)** means Coreflux is up. MQTT listens on port `1883` by default.

That's it—the broker is installed under `/opt/coreflux-broker` and managed by systemd. Confirm it works under [Verify Installation](#verify-installation) below. For the HUB, use the **HUB desktop** tab or run the HUB container from the **Docker** tab.

> **Verify the signing key (optional)**
>
> The key UID should show **Coreflux Portugal S.A. Package Signing** with email `packages@coreflux.org`:
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> gpg --no-default-keyring \
>   --keyring /usr/share/keyrings/coreflux-archive-keyring.gpg \
>   --list-keys --with-fingerprint
> ```

> **Manage the service**
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> sudo systemctl stop coreflux-broker
> sudo systemctl start coreflux-broker
> sudo systemctl restart coreflux-broker
> sudo journalctl -u coreflux-broker -f
> ```

**RPM (dnf)**

Use `dnf` on RHEL-compatible distributions—RHEL, Rocky Linux, AlmaLinux, and CentOS Stream. The repository uses `$releasever` and `$basearch`, so one repo file covers your EL version and CPU architecture (`x86_64` or `aarch64`).

| OS family | `$releasever` |
| - | - |
| EL 8 (RHEL / Rocky / Alma / CentOS Stream 8) | `8` |
| EL 9 (RHEL / Rocky / Alma / CentOS Stream 9) | `9` |
| EL 10 (RHEL / Rocky / Alma / CentOS Stream 10) | `10` |

**1. Import the signing key**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo rpm --import https://packages.coreflux.org/keys/coreflux.asc
```

**2. Add the repository**

Create `/etc/yum.repos.d/coreflux.repo`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
printf '%s\n' \
  '[coreflux]' \
  'name=Coreflux stable (GA)' \
  'baseurl=https://packages.coreflux.org/rpm/el/$releasever/$basearch' \
  'enabled=1' \
  'gpgcheck=1' \
  'repo_gpgcheck=1' \
  'gpgkey=https://packages.coreflux.org/keys/coreflux.asc' \
  | sudo tee /etc/yum.repos.d/coreflux.repo
```

**3. Install coreflux-broker**

Refresh the package cache and install the broker:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo dnf makecache --refresh
sudo dnf install coreflux-broker
```

Optional — list available versions before installing:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
dnf list --showduplicates coreflux-broker
```

**4. Confirm the service is running**

The package registers and starts `coreflux-broker` as a systemd service:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
systemctl status coreflux-broker.service
```

> [!TIP]
>
> **active (running)** means Coreflux is up. MQTT listens on port `1883` by default.

That's it—the broker is installed under `/opt/coreflux-broker` and managed by systemd. Confirm it works under [Verify Installation](#verify-installation) below. For the HUB, use the **HUB desktop** tab or run the HUB container from the **Docker** tab.

> **Manage the service**
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> sudo systemctl stop coreflux-broker
> sudo systemctl start coreflux-broker
> sudo systemctl restart coreflux-broker
> sudo journalctl -u coreflux-broker -f
> ```

**Windows**

> [!TIP]
>
> **\~10 min** — broker running as a Windows service.

Download and install Coreflux, then register it as a Windows service using the native `sc` tool.

1. Download the Windows package from the [Downloads page](https://portal.coreflux.org/downloads)
2. Extract the zip file to your preferred location (e.g., `C:\Coreflux`)
3. Open Command Prompt **as Administrator** and run:

```cmd wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sc create CorefluxBroker binPath= "C:\Coreflux\CorefluxMQTTBroker.exe" start= auto DisplayName= "Coreflux MQTT Broker"
sc description CorefluxBroker "Coreflux MQTT Broker Service"
sc start CorefluxBroker
```

That's it—the service is now registered, set to start automatically on boot, and running, so Coreflux is ready to use. For the HUB, use the **HUB desktop** tab or run the HUB container from the **Docker** tab.

> **Manage the service**
>
> Use these native Windows commands to control the service:
>
> ```cmd wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> sc stop CorefluxBroker
> sc start CorefluxBroker
> sc query CorefluxBroker
> ```
>
> You can also manage it from **Services** (`services.msc`) in Windows.

> **Uninstall the service**
>
> Stop and remove the service with:
>
> ```cmd wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> sc stop CorefluxBroker
> sc delete CorefluxBroker
> ```

**Cloud**

> [!TIP]
>
> **\~5 min**, nothing to install — hosted broker and HUB in your browser.

Get a hosted Coreflux instance without installing anything. Register at [portal.coreflux.org](https://portal.coreflux.org). The broker, the [Coreflux HUB](/hub/overview), and the connection details are in **Coreflux Fleet**.

> [!NOTE]
>
> This Cloud Trial is a **hosted** broker and HUB. To try Growth features on a broker you install yourself, register at [portal.coreflux.org](https://portal.coreflux.org) for a **30-day Growth-type license**, then [activate it](/latest/mqtt-broker/licensing).

**1. Register**

Register at [portal.coreflux.org](https://portal.coreflux.org).

**2. Open Coreflux Fleet**

In the portal, open **Coreflux Fleet**. Your trial broker is listed there. Open the HUB from that broker, and use the address and login on the same page for MQTT clients.

That's it—the broker and HUB are in Coreflux Fleet.

> [!TIP]
>
> After the HUB loads, continue with [Getting Started](/latest/quick-start/getting-started) using the **Coreflux HUB** tabs—your trial already includes the HUB and broker.

**HUB desktop**

> [!TIP]
>
> **\~2 min** — no Docker required for the HUB.

The standalone HUB is a desktop application for **Windows x64**, **Linux x64**, and **Linux ARM64**. It does not require a broker on the same machine.

**1. Download**

Download the HUB for your platform from the [Downloads page](https://portal.coreflux.org/downloads#hub-releases).

**2. Run**

Run the executable — the HUB window opens immediately.

**3. Connect**

Click **New Connection**. If the broker is on this machine, set **Protocol** `mqtt://`, **Host** `localhost`, **Port** `1883`, then enter the [default credentials](#default-login-credentials) and click **Connect**.

> [!NOTE]
>
> After this first install, the desktop app updates itself. See [Update the HUB desktop app](/latest/updating-coreflux#hub-desktop).

***

## Verify Installation

The quickest visual check is the [Coreflux HUB](/hub/overview) in your browser. You can also confirm directly by connecting an MQTT client and seeing Coreflux's system topics—that's how the broker is actually used. Use the [default credentials](#default-login-credentials) from the top of the page. For a Cloud Trial, use the address and login in **Coreflux Fleet**.

**Coreflux HUB**

**1. Open the HUB**

Open the HUB for your install. For a **Cloud Trial**, open it from **Coreflux Fleet** in the portal. For **Docker** or **Docker Compose**, use `http://localhost:3000`. For the **HUB desktop** app, the window opens on its own.

![Coreflux HUB login card listing local connections with Coreflux or MQTT broker badges, online status, identity, and Connect buttons, plus All and Starred filters and a New Connection button](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/connections/hub-login-screen-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=19b9b3a1e41004e0baee97fcf8ccdf4b)

Coreflux HUB — choose a stored connection or click New Connection

**2. Choose or create a connection**

The login screen lists **stored connections**. Click **Connect** on a saved one, or click **New Connection** to add a broker.

Fill in the broker fields, then enter the [default credentials](#default-login-credentials) and click **Connect**. For a Cloud Trial, use the login shown in **Coreflux Fleet**. Optionally click **Save connection** so the HUB remembers this broker next time.

| Install | Protocol | Host | Port | Path |
| - | - | - | - | - |
| Docker / Compose (broker + HUB) | `mqtt://` | `broker` | `1883` | — |
| Docker / Compose (WebSocket) | `ws://` | `broker` | `5000` | `mqtt` |
| HUB desktop, broker on this machine | `mqtt://` | `localhost` | `1883` | — |
| HUB-only container, broker on the host | `mqtt://` | `host.docker.internal` | `1883` | — |

![Coreflux HUB New Connection form with Local Hub, ws:// localhost port 5000 path mqtt, username root, Save connection, and Connect](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/connections/hub-login-setup.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=63c5584209052080345ce3fdc8159511)

New Connection — name the broker, set protocol, host, and port, then Connect

**3. Confirm the dashboard loaded**

After a successful login, you should see the HUB home screen with the bottom navigation bar.

![Coreflux HUB dashboard with Start here pointing to the first navigation icon](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/overview/hub-overview-start.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=bab525c05994ccb1c98530f1b50f40e1)

Coreflux HUB after login — start from the first icon in the navigation bar

> [!TIP]
>
> The status bar shows connector count and license info—the broker is reachable from the HUB.

**4. Browse MQTT data**

Select **MQTT** → **Data Viewer**. Expand **\$SYS/Coreflux** in the Topic Tree—you should see broker topics such as **Config**, **Version**, and **Resources** updating live.

![Coreflux HUB Data Viewer with Publish panel, Topic Tree, and tracked topic details](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/mqtt-explorer-overview.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=e9fdfa778a5c182a4c8a3404a3707f30)

Data Viewer — Topic Tree, Publish panel, and live topic values

**MQTT Client**

**1. Open MQTT Explorer**

Download [MQTT Explorer](https://mqtt-explorer.com/) or use any MQTT client of your choice.

**2. Connect to the Broker**

Create a new connection with these settings:

| Setting | Value |
| - | - |
| Host | `localhost`, or the endpoint shown in **Coreflux Fleet** for a Cloud Trial |
| Port | `1883` (local Docker or Compose) or **8883** with MQTTS (Cloud Trial) |
| Username / Password | The default credentials above, or the login shown in **Coreflux Fleet** |

**3. Check System Topics**

Subscribe to `$SYS/#` to see broker status messages. If you see topics such as `$SYS/Coreflux/Version`, the broker is running correctly.

> [!TIP]
>
> You should see Coreflux system topics under `$SYS/Coreflux/`.

### If verification fails

Pick the symptom that matches your setup:

> **All Versions — Broker isn't running or won't accept connections**
>
> If you can't connect, confirm the broker is actually up using the tooling for your install method.
>
> For a **Docker** install, inspect the container:
>
> ```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> # Is the container running?
> docker ps
>
> # View broker logs (live)
> docker logs -f coreflux_broker
>
> # View HUB logs (if you started the HUB container)
> docker logs -f coreflux_hub
>
> # Restart the container
> docker restart coreflux_broker
> ```
>
> For **Docker Compose**, use `docker compose ps` and `docker compose logs -f` from the directory that contains `docker-compose.yml`. The broker container is named `coreflux-broker`.
>
> For a **service install**, check the service status: `sudo systemctl status coreflux-broker` (Linux package install) or `sc query CorefluxBroker` (Windows).

> **Copy buttons don't work in the HUB**
>
> **Symptom:** copy buttons in a Docker or Docker Compose HUB do nothing, and nothing lands on the clipboard. This happens when you open the HUB over plain HTTP on a LAN IP or host name, for example `http://192.168.1.20:3000`.
>
> **Cause:** browsers only give pages clipboard access in a secure context, which means HTTPS or `localhost`. Current HUB versions have no fallback for plain HTTP.
>
> **Fix:** serve the HUB over HTTPS through a reverse proxy that terminates TLS (for example nginx, Caddy, or Traefik) and open the `https://` address. On the HUB's own machine, open `http://localhost:3000` instead. Until then, select the text and copy it with the keyboard. The desktop app is not affected.

> **All Versions — localhost doesn't load the HUB**
>
> **Symptom:** the HUB loads in some environments but not in a Docker-in-VM or remote setup.
>
> **Fix:** use the host's actual address instead of `localhost`.

> **Docker Only — Docker daemon not running**
>
> **Symptom:** the command errors with "cannot connect to the Docker daemon".
>
> **Fix:** start Docker Desktop (or the Docker service) and run the command again.

> **Docker Only — Port already in use**
>
> **Symptom:** an error binding a port, e.g. `3000` or `1883` is already allocated.
>
> **Fix:** stop the process using that port, or remap the host side of the port (for example `-p 1884:1883` on Docker, or change the left-hand port in `docker-compose.yml`).

> **Docker Only — Container exits immediately**
>
> **Symptom:** `docker ps` shows nothing after you start the broker.
>
> **Fix:** run `docker logs coreflux_broker` to see why it exited. For Compose, run `docker compose logs broker` from the directory that contains `docker-compose.yml`.

> **Docker Compose — HUB cannot reach the broker**
>
> **Symptom:** the HUB at `http://localhost:3000` fails to connect when **Host** is `localhost`, or shows **Broker isn't reachable**.
>
> **Fix:** the HUB proxies MQTT from inside Docker. On **New Connection**, set **Host** to `broker`, **Protocol** `mqtt://`, **Port** `1883` (or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`).

> **Cloud Only — Can't connect to your trial**
>
> **Symptom:** the HUB or an MQTT client fails to connect right after you start the trial.
>
> **Fix:** wait until **Coreflux Fleet** shows the broker as ready, then open the HUB from that page. Use the endpoint and login shown there for MQTT clients.

***

## Next Steps

> **[Getting Started](/latest/quick-start/getting-started)**
>
> Create your first LoT Action in under 15 minutes.

> **[VS Code Extension](/latest/quick-start/vscode)**
>
> Set up the LoT language extension for syntax highlighting.


# Using AI with Coreflux
Source: https://docs.coreflux.org/latest/quick-start/using-ai

Go from installation to AI-generated LoT code in minutes — build Actions, Connectors, and documentation with natural language prompts.

## Accelerate Your IIoT Development with AI

You've installed Coreflux and deployed your first Action. Now what if you could describe your next feature in plain English and have an AI assistant write the LoT (Language of Things) code for you — correctly, using verified syntax, following best practices?

That's exactly what Coreflux's AI integration enables. By connecting your AI assistant to the Coreflux MCP (Model Context Protocol), you give it real-time access to the official documentation. The result: you describe your goal, and the AI produces production-ready LoT code — Actions, Connectors, Models, and more — without you memorizing a single keyword.

> [!NOTE]
>
> The MCP connection in this guide is the [documentation MCP](/ai/mcp) (`https://docs.coreflux.org/mcp`). To let the same assistant **operate a live broker**, enable the [MCP Server](/latest/mqtt-broker/mcp-server) (`Mcp.Enabled`) and add it as a second MCP server in the client.

> [!TIP]
>
> **Like hiring a LoT specialist who never sleeps.** You explain what your factory floor needs — "alert me when temperature spikes" — and the specialist drafts the code, wires the database, and writes the documentation.

### When to Use This

* You want to **build IIoT features faster** by describing them in natural language
* You're **new to LoT syntax** and want correct code without a learning curve
* You need to **connect PLCs, databases, and alerts** and want AI to handle the wiring
* You want AI to **document your system** as you build it
* You want the assistant to **operate a live broker** (deploy LoT, run commands) through the [MCP Server](/latest/mqtt-broker/mcp-server)

***

## Step 1: Installation & Prerequisites

Before using AI with Coreflux, ensure the core environment is running.

| Requirement | Details |
| - | - |
| **Coreflux Broker** | Installed and running on your machine or server |
| **AI Assistant** | Cursor, Claude Desktop, Claude.ai, or VS Code with GitHub Copilot |
| **MQTT Client** | MQTT Explorer or any MQTT client for verifying results |

**1. Install the Coreflux Broker**

Follow the [Installation Guide](/latest/quick-start/installation) for your platform (Docker, Docker Compose, Windows, or Linux). Verify the broker is running by connecting with MQTT Explorer.

**2. Verify Your Setup**

Connect to the broker and subscribe to `$SYS/#`. If you see system topics, the broker is ready.

| Setting | Default Value |
| - | - |
| Host | `localhost` |
| Port | `1883` |
| Username | `root` |
| Password | `coreflux` |

> [!NOTE]
>
> If you haven't completed the [Getting Started](/latest/quick-start/getting-started) guide yet, do that first. It takes under 15 minutes and confirms your environment is working.

***

## Step 2: Setup AI (MCP & Agents)

Coreflux uses the **Model Context Protocol (MCP)** to give your AI assistant real-time access to the official documentation. This means the AI doesn't guess at LoT syntax — it looks it up. Combined with an **AGENTS.md** file that defines your project's conventions, your AI assistant becomes a LoT expert that follows your team's rules.

> [!NOTE]
>
> The steps below install the [documentation MCP](/ai/mcp). That server searches official docs. It does **not** control a broker.
>
> To let the assistant deploy LoT and run broker commands on a live broker, also enable the [MCP Server](/latest/mqtt-broker/mcp-server) — the broker's built-in MCP listener (`Mcp.Enabled`, Streamable HTTP `/mcp`) — and add it as a second server in the client.

### Configure the MCP Connection

Add the Coreflux documentation MCP server to your AI client. Use **Native** to install from the contextual menu on any docs page, or **Manual** to add the server URL to a config file.

**Native**

Open the **Copy page** menu (top right) on any Coreflux documentation page. From there you can copy the MCP URL, run the install command, or connect directly to VS Code or Cursor.

![Documentation page contextual menu showing Copy MCP Server, Copy MCP install command, Connect to Cursor, and Connect to VS Code](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/action-menu-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=ab62d6ffe924c7ef063007d4fc93c08b)

Contextual menu with MCP install options

**VS Code**

**1. Connect from the menu**

Select **Connect to VS Code** from the contextual menu.

**2. Install the server**

Click **Install** or **Install in Workspace** on the MCP server page.

![VS Code MCP Server tab for Coreflux Documentation with Install buttons and server URL configuration](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/vscode-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=e83435c5b09e548d23b3b3ef1cb90b4a)

VS Code MCP server install page

**3. Enable in Copilot**

Reload VS Code if needed, open Copilot Chat in **Agent** mode, and enable the Coreflux tools.

**Cursor**

**1. Connect from the menu**

Select **Connect to Cursor** from the contextual menu.

**2. Install the server**

In **Settings → Tools & MCPs**, confirm the **Install MCP Server?** details and click **Install**.

![Cursor Settings Tools page with Install MCP Server dialog for Coreflux Documentation](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/cursor-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=4ba9395dd8281d8683178457bfcb5f20)

Cursor MCP server install dialog

**3. Confirm the connection**

Verify **Coreflux Documentation** appears under **Installed MCP Servers** with tools enabled.

**Other clients**

Use **Copy MCP Server** or **Copy MCP install command** from the menu, then follow the **Manual** tab below or the [MCP Configuration Guide](/ai/mcp#setup) for Claude Desktop and other clients.

**Manual**

Add this URL to your editor's MCP configuration:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
https://docs.coreflux.org/mcp
```

**VS Code**

Create or open `.vscode/mcp.json` in your workspace:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "servers": {
    "coreflux": {
      "type": "sse",
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

Reload VS Code. The tools become available in Copilot's **Agent** mode.

**Cursor**

Add the following to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux": {
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

Restart Cursor and verify the connection under **Settings → MCP**.

**Claude Desktop**

Add the following to your Claude Desktop configuration file:

**Windows**

`%APPDATA%\Claude\claude_desktop_config.json`

**macOS**

`~/Library/Application Support/Claude/claude_desktop_config.json`

**Linux**

`~/.config/Claude/claude_desktop_config.json`

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux": {
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

Restart Claude Desktop. The Coreflux tools appear in the tool picker (hammer icon).

For full setup details, editor-specific steps, and verification, see the [MCP Configuration Guide](/ai/mcp#setup).

### Set Up AGENTS.md (Project Rules)

An **AGENTS.md** file in your project root tells your AI assistant how to write LoT code — naming conventions, patterns, and what to avoid. Without it, the AI may use inconsistent styles or invent syntax.

Create an `AGENTS.md` file in your project root with your project's conventions. The [Best Practices & AGENTS.md](/ai/best-practices#setting-up-your-ai-assistant) page provides a complete starter template covering:

* **Naming rules** — PascalCase for entities, snake\_case for variables
* **Topic hierarchy** — `sensors/`, `processed/`, `alerts/` namespaces
* **Code standards** — Type casting, state management, modular Actions
* **Boundaries** — What the AI should always do, ask about, and never do

For a faster start, clone the [Coreflux AI Starter](https://github.com/CorefluxCommunity/coreflux-ai-starter) repo — it includes ready-to-use templates and pre-built MCP configs for every editor.

### Add Agent Skills

AGENTS.md holds your project's rules. The LoT and broker knowledge itself comes from the [Coreflux agent skills](/ai/agent-skills), published in the public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository. Install them with the skills CLI, the Claude Code plugin, or **Install Agent Skills...** in the LoT Notebooks extension:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
npx skills add CorefluxCommunity/coreflux-skills
```

> [!TIP]
>
> Once the MCP, AGENTS.md, and agent skills are in place, your AI assistant has real-time documentation access, LoT knowledge, **and** your project's coding standards. You're ready to build.

***

## Step 3: Create LoT with AI

With your AI assistant connected via MCP, you can use natural language to perform complex IIoT tasks. The following examples demonstrate the full workflow — from prompt to deployable code.

### A. Generate a LoT Action from Scratch

The most common starting point: you describe a behavior, and the AI writes the Action.

**The Prompt:**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Create a LoT Action called TempAlert that monitors the topic 
"factory/sensor/temp". If the temperature value (from a JSON payload 
with key "value") goes above 50, publish an alert to "alerts/hvac" 
with the current value. Use proper type casting.
```

**AI-Generated Output:**

The AI consults the Coreflux MCP documentation and produces verified LoT syntax:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TempAlert
ON TOPIC "factory/sensor/temp" DO
    SET "current_temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {current_temp} > 50 THEN
        PUBLISH TOPIC "alerts/hvac" WITH "High Temperature Detected: " + {current_temp}
```

**Why this works:**

| Line | What It Does |
| - | - |
| `DEFINE ACTION TempAlert` | Creates an Action named `TempAlert` (PascalCase, verb-like) |
| `ON TOPIC "factory/sensor/temp" DO` | Triggers every time a message arrives on this topic |
| `SET "current_temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)` | Extracts the `value` field from the JSON payload and casts it to a number |
| `IF {current_temp} > 50 THEN` | Conditional check against the threshold |
| `PUBLISH TOPIC "alerts/hvac" WITH ...` | Sends an alert with a descriptive message and the value |

**Deploy and Test:**

**1. Deploy the Action**

Paste the code into a LoT Notebook cell (`.lotnb` file) and run it, or publish to `$SYS/Coreflux/Command` with the `-addAction` prefix.

**2. Send a Test Message**

Publish to `factory/sensor/temp`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"value": 62.5}
```

**3. Verify the Alert**

Subscribe to `alerts/hvac`. You should see:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
High Temperature Detected: 62.5
```

***

### B. PLC Integration & Automated Routing

A real-world scenario: you have a Siemens S7 PLC on the factory floor, and you want its data flowing into a PostgreSQL database. This requires **two Connectors** — one to read from the PLC, and one to store in the database. Topics are the bridge between them.

**The Prompt:**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
I have a Siemens S7-1500 PLC at IP 192.168.1.10. I need to:
1. Read the temperature (REAL at DB1.DBD100) and pressure (REAL at DB1.DBD104) 
   every 500 milliseconds and publish them to MQTT topics
2. Store all readings in a PostgreSQL database called "production_db" 
   at 192.168.1.50, user "flux_user", password "secure_pass"

Create the LoT Connectors for both.
```

**AI Logic:**

1. **Analyze** — The AI identifies the source (Siemens S7 PLC), the data bridge (MQTT topics), and the destination (PostgreSQL)
2. **Design** — It creates two Connectors: an industrial Connector for the PLC, and a data storage Connector for the database
3. **Generate** — Using the MCP to verify syntax, it produces:

**Connector 1 — Read from the PLC:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR S7Factory WITH TYPE SIEMENS_S7
    ADD S7_CONFIG
        WITH IP "192.168.1.10"
        WITH CPU_TYPE "S71500"
        WITH RACK '0'
        WITH SLOT '1'
    ADD MAPPING SensorData
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "DB1.DBD100"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/s7/temperature"
            WITH UNIT "°C"
            WITH DECIMAL_PLACES "2"
        ADD TAG Pressure
            WITH ADDRESS "DB1.DBD104"
            WITH DATA_TYPE "REAL"
            WITH SOURCE_TOPIC "plc/s7/pressure"
            WITH UNIT "bar"
            WITH DECIMAL_PLACES "2"
```

This Connector reads PLC data and publishes it to MQTT topics every 500ms.

**Connector 2 — Store in PostgreSQL:**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "192.168.1.50"
        WITH PORT '5432'
        WITH DATABASE "production_db"
        WITH USERNAME "flux_user"
        WITH PASSWORD "secure_pass"
    ADD EVENT StoreTemperature
        WITH SOURCE_TOPIC "plc/s7/temperature"
        WITH QUERY "INSERT INTO sensor_readings (recorded_at, sensor, value) VALUES (NOW(), 'temperature', '{value}')"
    ADD EVENT StorePressure
        WITH SOURCE_TOPIC "plc/s7/pressure"
        WITH QUERY "INSERT INTO sensor_readings (recorded_at, sensor, value) VALUES (NOW(), 'pressure', '{value}')"
```

The AI generates a database Connector that subscribes to the MQTT topics published by the PLC Connector and inserts every reading into a `sensor_readings` table — complete with SQL templates, connection config, and event triggers, without you writing a single line of SQL manually.

**The Data Flow:**

| Step | Component | What Happens |
| - | - | - |
| 1 | S7 Connector | Reads `DB1.DBD100` and `DB1.DBD104` from the PLC |
| 2 | MQTT Topics | Values published to `plc/s7/temperature` and `plc/s7/pressure` |
| 3 | PostgreSQL Connector | Inserts each reading into the `sensor_readings` table |

> [!NOTE]
>
> The PLC Connector and PostgreSQL Connector are independent — they communicate through MQTT topics. This decoupled architecture means you can add more consumers (alerts, dashboards, other databases) without modifying the PLC Connector. For a step-by-step walkthrough of building a database Connector from scratch, see the [Developing with LoT Using AI](/ai/developing-with-lot#step-4-connect-to-a-database-connector) guide.

***

### C. Modify Existing Code & Generate Documentation

AI excels at iterating on existing code and producing documentation alongside it.

**The Prompt:**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Update the TempAlert action to also log every alert to "system/logs" 
with a timestamp. Then generate a markdown summary documenting this 
action on a project-specific LoT Notebook (LoTNB file).
```

**AI-Updated Code:**

The AI modifies the existing Action and adds the logging line:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TempAlert
ON TOPIC "factory/sensor/temp" DO
    SET "current_temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {current_temp} > 50 THEN
        PUBLISH TOPIC "alerts/hvac" WITH "High Temperature Detected: " + {current_temp}
        SET "log_time" WITH TIMESTAMP "UTC"
        PUBLISH TOPIC "system/logs" WITH "TempAlert triggered at " + {log_time} + " — value: " + {current_temp}
```

| What Changed | Why |
| - | - |
| Added `SET "log_time" WITH TIMESTAMP "UTC"` | Captures the current UTC timestamp into a variable |
| Added `PUBLISH TOPIC "system/logs"` | Creates an audit trail with timestamp and value |

**AI-Generated Documentation:**

The AI also produces a markdown summary you can add directly to your project's LoT Notebook (LoTNB):

```markdown wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
## Action: TempAlert

**Description:** Monitors temperature thresholds for the HVAC system. 
Triggers an alert when the factory temperature sensor exceeds 50°C and 
logs every alert event for auditing.

| Property | Value |
|----------|-------|
| **Trigger** | `factory/sensor/temp` |
| **Condition** | Temperature > 50°C |

**Outputs:**

| Topic | Purpose |
|-------|---------|
| `alerts/hvac` | Real-time alert with temperature value |
| `system/logs` | Timestamped audit trail of all triggered alerts |

**Payload Format:** Expects JSON with a `value` key (e.g., `{"value": 62.5}`)
```

This is the complete cycle: **build → modify → document** — all driven by natural language prompts.

***

## Best Practices

To get the most out of AI-assisted LoT development, keep these principles in mind:

* **Always verify the MCP connection** before starting a session. Without it, the AI may generate plausible-looking but incorrect LoT syntax
* **Be specific in your prompts** — include topic names, payload formats, thresholds, and hardware details. The more context you provide, the more accurate the output
* **Build incrementally** — deploy and test one Action, Connector, or Model at a time before moving to the next

For detailed prompt templates, see [Prompt Patterns That Work](/ai/developing-with-lot#prompt-patterns-that-work). For naming conventions and a project rules template, see [Best Practices & AGENTS.md](/ai/best-practices).

> [!WARNING]
>
> If your AI assistant generates LoT code **without** consulting the MCP, the syntax may be invented. Always verify that the MCP tools are active before trusting the output.

***

## Next Steps

> **[Creating Agents in Coreflux](/latest/quick-start/creating-agents)**
>
> Deploy AI agents on the broker — chat, automation, and multi-agent teams defined in LoT.

> **[Developing with LoT Using AI](/ai/developing-with-lot)**
>
> Deep-dive into the full AI-assisted workflow — planning, building, verifying, and scaling your IIoT system.

> **[Best Practices & AGENTS.md](/ai/best-practices)**
>
> Set up naming conventions, code patterns, and a project rules template to keep your AI assistant consistent.


# Using Coreflux HUB
Source: https://docs.coreflux.org/latest/quick-start/using-hub

Access the Coreflux HUB and manage your broker — MQTT topics, LoT code, connectors, and system settings in one place.

![Coreflux HUB overview screen with a 'Start here' arrow pointing to the first navigation icon in the bottom toolbar](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/overview/hub-overview-start.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=bab525c05994ccb1c98530f1b50f40e1)

Coreflux HUB overview — start here

## Manage Your Broker from the HUB

You have a Coreflux broker running. Now you want to explore MQTT topics, deploy LoT code, configure connectors, and manage users — all without installing desktop tools or memorizing command-line syntax. The Coreflux HUB gives you a desktop or browser interface that puts every management task in one place.

> [!TIP]
>
> **Like the dashboard of your car.** You don't pop the hood to check the speed or fuel level — you glance at the dashboard. The HUB does the same for your broker: real-time data, configuration, and diagnostics, all visible at a glance.

### When to Use This

* You want to **manage your broker visually** without installing MQTT Explorer or VS Code
* You need to **deploy and test LoT code quickly** from any machine
* You're **configuring connectors** to databases or PLCs and want a guided, visual workflow
* You want to **monitor connected clients and system health** in real time

***

> [!TIP]
>
> **Haven't installed the HUB yet?** Follow [Installation](/latest/quick-start/installation) — Docker, Docker Compose (HUB at `http://localhost:3000`), or the **HUB desktop** tab for Windows x64, Linux x64, and Linux ARM64.

## Access the HUB

**Docker Compose**

Open `http://localhost:3000`. Click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — the HUB proxies MQTT from inside Docker, so **Host** `localhost` does not reach the broker service.

| Setting | Value |
| - | - |
| Username | `root` |
| Password | `coreflux` |

**Standalone Desktop App**

Run the downloaded HUB executable for your platform (Windows x64, Linux x64, or Linux ARM64). The HUB window opens — click **New Connection**, enter the broker host, protocol, port, and credentials, then click **Connect**.

The desktop app updates itself. See [Update the HUB desktop app](/latest/updating-coreflux#hub-desktop).

| Setting | Value |
| - | - |
| Username | `root` |
| Password | `coreflux` |

> [!WARNING]
>
> Change the default password before deploying to production. Go to **System → User Management** to update credentials.

On the desktop layout — the standalone app and a desktop browser — the Coreflux logo shows the desktop, and the account pill opens broker tools and **Hub Settings**. Dock and status-bar preferences are on the right-click menus and under **Hub Settings → Desktop**. A phone keeps its own layout. See [Desktop shell](/hub/overview#desktop-shell).

***

## What Can You Do with Coreflux HUB?

Once you're logged in, the HUB gives you four dedicated apps that together cover every broker management task — from inspecting live data to deploying logic and connecting external systems.

> **[MQTT](/hub/mqtt/overview)**
>
> Browse live topics, inspect payloads, publish test messages, and see which clients are connected.

> **[LoT Editor](/hub/lot-editor)**
>
> Write LoT and Python as notebooks and deploy any cell to the broker — no external tools needed.

> **[Connectors](/hub/routes/overview)**
>
> Connect your broker to databases, PLCs, and external systems using templates or LoT code, then monitor each connection in real time.

> **[System](/hub/system/overview)**
>
> Configure the broker, manage users and permissions, run commands, and stream real-time logs for diagnostics.

The table below maps common tasks to the app that handles them so you always know where to go.

| Task | HUB App |
| - | - |
| Browse topics and inspect message payloads | **MQTT** |
| Publish a test message to any topic | **MQTT** |
| See which devices are connected | **MQTT** |
| Write or update an Action, Model, Rule, Connector, or Python script | **LoT Editor** |
| Deploy LoT code to the broker instantly | **LoT Editor** |
| Check whether your code matches what the broker is running | **LoT Editor** |
| Add a connector to a database or PLC | **Connectors** |
| Monitor connector connection health and logs | **Connectors** |
| Change broker network or TLS settings | **System** |
| Create users and assign permissions | **System** |
| View real-time broker logs and run commands | **System** |
| Ask for insights, build dashboards, or draft LoT from plain language | **AI Assistant** |
| Move the dock, hide the status bar, or cap how much the HUB keeps in memory | [Desktop shell](/hub/overview#desktop-shell) |

The sections below walk you through each of these tasks hands-on.

***

## See Your MQTT Data

Open the **MQTT** app to browse every topic flowing through your broker in real time. The topic tree on the left lets you drill into any hierarchy, and selecting a topic shows its latest payload, QoS, and timestamp on the right.

![Coreflux HUB Data Viewer showing the topic tree and a selected message payload](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/view-mqtt-data.gif?s=0c0d326259f91e2d49562aff1c27d5ae)

Data Viewer — browse live topics and inspect message payloads

Use this when you need to verify that a device is publishing, check payload formats, or publish a test message — all without leaving the browser. For a full walkthrough, see [Data Viewer](/hub/mqtt/data-viewer).

***

## Connect to an External Device with a Connector

Open the **Connectors** app to connect your broker to databases, PLCs, or other external systems. Pick a template, fill in the connection details, map MQTT topics to fields, and activate — the HUB handles the rest.

![Coreflux HUB Connectors app showing connector creation with a template and configuration fields](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/overview/route-creation.gif?s=487fb3d962d4be41ce5f667585428841)

Connectors — create a new connector from a template and configure its connection

Each connector card shows a live status indicator so you can tell at a glance whether the connection is healthy. For configuration details, see [Connectors](/hub/routes/overview).

***

## Quickly Change the LoT Running on the Broker

Open the **LoT Editor** to write or redeploy LoT and Python as notebook cells. Run a single cell to deploy just that definition, or **Deploy All** for the whole project. Changes take effect immediately — no build step, no file transfer, no restart.

![Coreflux HUB LoT Editor showing an Action being edited and deployed](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/deploy-action.gif?s=a0a1f1c0fbe805c8e7b3a32726482e75)

LoT Editor — edit an Action and deploy it to the broker in one click

Every cell reports whether it matches the broker, so you can tell at a glance which definitions are live and which are still local. For the full editor reference, see [LoT Editor](/hub/lot-editor).

***

## Build With the AI Assistant

Open the **AI Assistant** from the Coreflux icon in the bottom dock and describe what you want in plain language — ask for insights from live data, build a dashboard with live widgets, or develop a LoT Action. The assistant uses the broker's own tools to draft, refine, and deploy the change in the same panel.

![Coreflux HUB AI Assistant being opened from the dock, receiving a prompt, and deploying the change](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-demo.gif?s=a21be6b72ad7e94afe95ee1a9afd6bdb)

AI Assistant — describe a goal in plain language and the assistant drafts and deploys it on your broker

Use **Insight** mode for read-only exploration or switch to **Agent** mode when you want the assistant to create or update Connectors, Actions, and panels. For setup, modes, and built-in safeguards, see [AI Assistant](/hub/ai-assistant).

***

## Debug Your LoT and Broker

Open the **System** app when something isn't behaving as expected. **Broker Logs** stream trace-level output in real time, and the **Command Console** lets you run broker commands directly — restart actions, inspect state, or change configuration on the fly.

![Coreflux HUB System app showing broker logs and the command console](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/broker-debug.gif?s=a58e41879fefd30e1a812498fca53c73)

System — real-time broker logs and the command console for direct broker interaction

Combine logs with the Data Viewer to trace a message from publish to action execution. For all system tools, see [System](/hub/system/overview).

***

## Next Steps

> **[Explore the HUB](/hub/overview)**
>
> Deep-dive into each app — Data Viewer, LoT Editor, Connectors, and System tools.

> **[Create Your First Action](/latest/quick-start/getting-started)**
>
> Build and deploy a working LoT Action in under 15 minutes.


# Using LoT Notebooks
Source: https://docs.coreflux.org/latest/quick-start/vscode

Use LoT Notebooks as living documentation—run LoT code, document your project, and see MQTT data all in one place.

![VS Code with a LoT notebook open showing markdown and LoT code cells, Coreflux Explorer and project tree on the left, Data Viewer below, and MQTT connection in the status bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lotnb.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=9e0cb958c924dad253919f3ff09f828a)

LoT Notebook workspace in VS Code: editor, Coreflux Explorer, Project, and Data Viewer

## Overview

**LoT Notebooks** are **living documentation**: Markdown for documentation and runnable LoT code in the same file. You **run LoT** to deploy to the **Coreflux MQTT broker**, document with **Markdown** and use the **Data Viewer** to **see what is happening on the broker**.

> [!TIP]
>
> **Write it, run it, see the result in the broker.** With LoT Notebooks and LoT VS Code Extension, document the "why," deploy the "what," and see the MQTT traffic and execution logic side by side with your notebook.

## Before you start

* **Visual Studio Code** installed
* A **Coreflux broker** installed or in another machine you can reach

## Install and connect

**1. Install the extension**

![Animated walkthrough: VS Code Extensions view, search for coreflux, install Coreflux LoT, Coreflux icon appears in the Activity Bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-installation.gif?s=3a2aa4cdbaf895e94e9954d6c45b7abf)

Extensions marketplace: search for Coreflux and install LoT Notebooks

1. Open VS Code.
2. Open the Extensions view in the sidebar (or use the shortcut `Ctrl+Shift+X` on Windows/Linux, `Cmd+Shift+X` on macOS).
3. Search for **LoT Notebooks** by **Coreflux** and install it.

**2. Connect to the broker**

![VS Code: connect to MQTT broker via LoT extension; status bar shows MQTT connected](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-broker-connect.gif?s=faf63084741fb786ec1807145f691a89)

Connect to the broker: pick credentials or connect from the Data Viewer

1. Click on the MQTT Connection Status on bottom left corner of your VS Code or click **Connect to Broker** in the **Data Viewer** (Coreflux sidebar).
2. Enter your broker **URL**, **username**, and **password**.

> **Example URL and default login credentials**
>
> Use a full URL such as `mqtt://localhost:1883` or `mqtts://your-host:8883` for TLS.
>
> | Setting | Example (local defaults) |
> | - | - |
> | URL | `mqtt://localhost:1883` |
> | Username | `root` |
> | Password | `coreflux` (change immediately in production) |

When you are connected, the status bar shows a green **MQTT: Connected**. If any issues occur, the status bar will become red.

## Create a LoT notebook and deploy your first LoT code

![LoT Notebook: Create and deploy to broker from a code cell; success feedback and Coreflux Explorer update](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-and-deploy-lot.gif?s=5cd139e03cbf0b5109848b498d7c65eb)

Create and deploy your first LoT

1. In the Activity Bar (left bar), open **Coreflux**.
2. Under **PROJECT**, use **New File**, give your **LoT Notebook** a name, and it will be created within the **workspace folder** you opened in VS Code.
3. Add a code cell from the notebook toolbar (**+ Code**). Optionally, add a Markdown cell (**+ Markdown**) to document your code.
4. Write or paste a LoT code (for example the Action below) and click **Execute Cell** icon on the cell or **Run All** option above.

   ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
   DEFINE ACTION Heartbeat
   ON EVERY 10 SECONDS DO
       PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
   ```
5. See the data change in the **Data Viewer**, by subscribing to all topics, just like MQTT Explorer. Additionally, you can click on a data topic to see it in more detail, including a replay of the data changes.

## Next Steps

> **[How to Use a LoT Notebook in VS Code](/lot-notebooks/usage)**
>
> Workflow, cells, broker connection, commands, Git, best practices, and troubleshooting.

> **[How to Debug in LoT Extension](/lot-notebooks/debug)**
>
> Data Viewer, replay, execution trace, and debug on LoT Notebooks.


# Updating Your Coreflux
Source: https://docs.coreflux.org/latest/updating-coreflux

Upgrade the broker on Docker, Windows, or Linux. The Coreflux HUB desktop app updates itself.

## When to Update

Update Coreflux when a new release includes fixes or features you need. Check [Release Notes](/product-updates/release-notes) for what changed in each version. The Coreflux HUB desktop app updates itself.

> [!TIP]
>
> **Keep your project files.** Docker named volumes, package install directories, and manual install folders retain LoT, connectors, and configuration when you upgrade only the broker runtime.

> [!NOTE]
>
> **LoT file names changed.** The files that store your Actions, Models, Connectors and Rules in `bin/` are now `actions.lot`, `models.lot`, `routes.lot` and `rules.lot`. The first start of the new version copies your existing files to these names and leaves the old ones in place, so nothing is lost. If you go back to an earlier version, it reads the old files, which do not contain changes made after the upgrade. If the broker cannot read or write one of these files, it exits with code `78` and names the file; see [Startup options](/latest/mqtt-broker/startup-options).

***

## Update Coreflux

**Docker**

To run the latest image, stop and remove the existing container, then start a new one with the same `docker run` command from [Installation](/latest/quick-start/installation). The `--pull=always` flag ensures Docker fetches the newest `latest` tag before each start.

> [!WARNING]
>
> **Use your actual names.** The examples below use the default container name `coreflux_broker` and volume `project-volume`. If you chose different names when you first installed, replace them in every command.

**1. Stop and remove the container**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker stop coreflux_broker
docker rm coreflux_broker
```

This stops the broker and removes the container. Named volumes (such as `project-volume`) are **not** deleted—your project files remain on disk.

**2. Start a new container**

Run the same command you used for installation. For the standard setup:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -p 9100:9100 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest
```

If you use TLS ports, use the command from the [TLS/SSL accordion on Installation](/latest/quick-start/installation)—still with `--pull=always`, the same container name, and the same `project-volume` mount.

**3. Verify**

Confirm the broker is up with `curl http://localhost:9100/health`, or subscribe to `$SYS/Coreflux/Version` from an MQTT client. The broker image does **not** include the HUB — if you also run the HUB container, open [Coreflux HUB](/hub/overview) at `http://localhost:3000`.

**Docker Compose**

Pull the latest images and recreate the stack. Named volumes (`broker-data`, `hub-data`) are kept unless you pass `-v` to `docker compose down`.

**1. Pull and recreate**

From the directory that contains `docker-compose.yml`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
docker compose --profile full pull
docker compose --profile full up -d
```

Both services use the `latest` tag, so `docker compose pull` fetches the newest broker and HUB images. See [Installation](/latest/quick-start/installation) for the Compose file.

**2. Verify**

Open the [Coreflux HUB](/hub/overview) at `http://localhost:3000` and connect with `mqtt://broker:1883`. Subscribe to `$SYS/Coreflux/Version` in the Data Viewer to confirm the broker version. You can also probe `http://localhost:9100/health`.

**Cloud Trial**

Cloud Trial environments are managed by Coreflux. When an update is available, your trial instance is upgraded on the hosted side—you do not run install or update commands locally.

> [!NOTE]
>
> Open the broker from **Coreflux Fleet** at [portal.coreflux.org](https://portal.coreflux.org). If the HUB or an MQTT client fails right after a platform update, wait briefly and reconnect—the broker may still be restarting.

See [Release Notes](/product-updates/release-notes) for new features you can use once the trial environment is on the latest version.

**Windows**

Update a Windows service install by stopping the service, replacing the executable, and starting it again.

> [!WARNING]
>
> **Use your actual service and paths.** Examples use the service name `CorefluxBroker` and install path `C:\Coreflux`. Change these if you registered the service differently—see [Installation](/latest/quick-start/installation).

**1. Stop the service**

Open Command Prompt **as Administrator** and run:

```cmd wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sc stop CorefluxBroker
```

**2. Replace the executable**

Download the latest Windows package from the [Downloads page](https://portal.coreflux.org/downloads), extract it, and copy `CorefluxMQTTBroker.exe` over the file in your install folder (for example `C:\Coreflux`). Do not remove your existing config or project files in that folder.

**3. Start the service**

```cmd wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sc start CorefluxBroker
sc query CorefluxBroker
```

**Linux**

> [!TIP]
>
> **\~2 min** if you installed the Linux package from the [Downloads page](https://portal.coreflux.org/downloads) — refresh indexes and upgrade the `coreflux-broker` package.

Use the tab that matches how you installed the broker. See [Installation](/latest/quick-start/installation) if you still need to add the Coreflux repository.

**Debian & Ubuntu (APT)**

**1. Refresh package lists**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo apt update
```

Optional — see which version is installed and what is available:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
apt-cache policy coreflux-broker
```

**2. Upgrade coreflux-broker**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo apt upgrade coreflux-broker
```

To upgrade only the broker without touching other packages:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo apt install --only-upgrade coreflux-broker
```

**3. Verify**

The package upgrade restarts `coreflux-broker` via systemd. Confirm it is running:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
systemctl status coreflux-broker.service
```

Subscribe to `$SYS/Coreflux/Version` from an MQTT client, or open [Coreflux HUB](/hub/overview) if you run it separately.

**RPM (dnf)**

**1. Refresh the package cache**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo dnf makecache --refresh
```

Optional — list available versions:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
dnf list --showduplicates coreflux-broker
```

**2. Upgrade coreflux-broker**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
sudo dnf upgrade coreflux-broker
```

**3. Verify**

The package upgrade restarts `coreflux-broker` via systemd. Confirm it is running:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
systemctl status coreflux-broker.service
```

Subscribe to `$SYS/Coreflux/Version` from an MQTT client, or open [Coreflux HUB](/hub/overview) if you run it separately.

**HUB desktop**

The Coreflux HUB desktop app updates itself. You choose when to apply the update.

> [!NOTE]
>
> A HUB you open in the browser updates when you pull a new container image. Use the **Docker** or **Docker Compose** tab for that.

***

## Next Steps

> **[Release Notes](/product-updates/release-notes)**
>
> See what changed in recent releases.

> **[Installation](/latest/quick-start/installation)**
>
> Full install commands for every platform.


# balena
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/balena

Connect Coreflux LoT to balenaCloud to inspect devices and fleets, pin releases, manage tags and env vars, and restart, reboot or blink devices

Technical Preview

## Overview

One client-mode connector, **Balena**, for [balenaCloud](https://www.balena.io/cloud) (`https://api.balena-cloud.com`). It covers two APIs that share the same host and the same API key:

* the **balena API v7**, an [OData](https://docs.balena.io/reference/api/overview) interface over fleets (called `application` in the API), devices, releases, tags and variables;
* the **Supervisor API proxy** (`/supervisor/...`), which forwards a command to the balena Supervisor on one device, identified by its UUID.

Use it to let the broker manage the edge gateways it runs next to: watch device health, restart a stuck container when a line alarm fires, pin a fleet to a known-good release before a shift, or tag devices with their UNS location.

| Event | Request | Notes |
| - | - | - |
| ListDevices | `GET /v7/device?{odata}` | Pass the whole OData query string in `odata` |
| GetDevice | `GET /v7/device(uuid='{uuid}')?$select=...` | Health, status, `overall_status`, running and pinned release |
| UpdateDevice | `PATCH /v7/device(uuid='{uuid}')` | Pin to a release, rename, add a note; returns `OK` |
| ListDeviceTags | `GET /v7/device_tag?$filter=device/uuid eq '{uuid}'` | |
| CreateDeviceTag | `POST /v7/device_tag` | Body: `device` (numeric id), `tag_key`, `value` |
| UpdateDeviceTag | `PATCH /v7/device_tag(device={device_id},tag_key='{tag_key}')` | Body: `value` |
| ListDeviceEnvVars | `GET /v7/device_environment_variable?$filter=...` | Device-level variables by UUID |
| CreateDeviceEnvVar | `POST /v7/device_environment_variable` | Body: `device`, `name`, `value` |
| ListFleets | `GET /v7/application?$filter=is_directly_accessible_by__user/any(dau:true)` | Fleets the key can reach |
| GetFleet | `GET /v7/application(slug='{fleet_slug}')` | Target release and tracking flag |
| UpdateFleet | `PATCH /v7/application(slug='{fleet_slug}')` | Pin the whole fleet to a release |
| ListReleases | `GET /v7/release?$filter=belongs_to__application eq {fleet_id}` | Latest 10 releases |
| SupervisorRestartApp | `POST /supervisor/v1/restart` | Restart all containers of the app |
| SupervisorRestartService | `POST /supervisor/v2/applications/{app_id}/restart-service` | Restart one service |
| SupervisorBlink | `POST /supervisor/v1/blink` | Blink the device LED for 15 seconds (identify device), if it has one |
| SupervisorReboot | `POST /supervisor/v1/reboot` | Reboot the device |
| SupervisorUpdate | `POST /supervisor/v1/update` | Check for updates now (`force` skips update locks) |
| SupervisorDeviceState | `POST /supervisor/v1/device` | Supervisor's view of the device (status, commit, update pending) |

Topics use `cloud-iot/balena/<object>/<verb>`; replies land on `<topic>/response`. For openBalena, change `BASE_ADDRESS` to your own API host, for example `https://api.balena.example.com`.

> [!WARNING]
>
> Never commit an API key. Store it as a broker secret (for example `BALENA_API_KEY`) and map it into payloads with `GET SECRET`. A balena API key acts with your full user permissions, and the API has no undo: test every `$filter` with a GET before you use it in a PATCH.

## Authentication

Every event sends `Authorization: Bearer <key>`. Use a **named API key**: in the balenaCloud dashboard open **Preferences**, then **Access tokens**, and create an API key, or run `balena api-key generate coreflux` with the balena CLI. Session tokens also work but expire.

Pass the key as `api_key` on every payload. A missing or invalid key returns `401` on device, tag, variable, fleet-write and Supervisor events. Fleets and releases are publicly readable resources, so without a valid key `GetFleet` and `ListReleases` return `200` with an empty `d` list for private fleets, and `ListFleets` returns `400 Missing binding: @__ACTOR_ID`. Treat an empty `d` on those events as a possible auth problem.

## Basic Syntax

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Balena WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.balena-cloud.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "cloud-iot/balena/device/list"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/device?{value.json.odata}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "cloud-iot/balena/device/get"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/device(uuid='{value.json.uuid}')?$select=id,uuid,device_name,status,overall_status,is_online,last_connectivity_event,os_version,supervisor_version,cpu_temp,cpu_usage,memory_usage,memory_total,storage_usage,storage_total,is_running__release,is_pinned_on__release,should_be_running__release"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT UpdateDevice
        WITH SOURCE_TOPIC "cloud-iot/balena/device/update"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v7/device(uuid='{value.json.uuid}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDeviceTags
        WITH SOURCE_TOPIC "cloud-iot/balena/device-tag/list"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device-tag/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/device_tag?$filter=device/uuid%20eq%20'{value.json.uuid}'"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT CreateDeviceTag
        WITH SOURCE_TOPIC "cloud-iot/balena/device-tag/create"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device-tag/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v7/device_tag"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateDeviceTag
        WITH SOURCE_TOPIC "cloud-iot/balena/device-tag/update"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device-tag/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v7/device_tag(device={value.json.device_id},tag_key='{value.json.tag_key}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDeviceEnvVars
        WITH SOURCE_TOPIC "cloud-iot/balena/device-env/list"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device-env/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/device_environment_variable?$filter=device/any(d:d/uuid%20eq%20'{value.json.uuid}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT CreateDeviceEnvVar
        WITH SOURCE_TOPIC "cloud-iot/balena/device-env/create"
        WITH DESTINATION_TOPIC "cloud-iot/balena/device-env/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v7/device_environment_variable"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListFleets
        WITH SOURCE_TOPIC "cloud-iot/balena/fleet/list"
        WITH DESTINATION_TOPIC "cloud-iot/balena/fleet/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/application?$filter=is_directly_accessible_by__user/any(dau:true)&$select=id,app_name,slug,should_be_running__release,should_track_latest_release"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT GetFleet
        WITH SOURCE_TOPIC "cloud-iot/balena/fleet/get"
        WITH DESTINATION_TOPIC "cloud-iot/balena/fleet/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/application(slug='{value.json.fleet_slug}')?$select=id,app_name,slug,should_be_running__release,should_track_latest_release"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT UpdateFleet
        WITH SOURCE_TOPIC "cloud-iot/balena/fleet/update"
        WITH DESTINATION_TOPIC "cloud-iot/balena/fleet/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v7/application(slug='{value.json.fleet_slug}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListReleases
        WITH SOURCE_TOPIC "cloud-iot/balena/release/list"
        WITH DESTINATION_TOPIC "cloud-iot/balena/release/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/release?$filter=belongs_to__application%20eq%20{value.json.fleet_id}&$select=id,commit,semver,raw_version,status,created_at&$orderby=created_at%20desc&$top=10"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT SupervisorRestartApp
        WITH SOURCE_TOPIC "cloud-iot/balena/supervisor/restart"
        WITH DESTINATION_TOPIC "cloud-iot/balena/supervisor/restart/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/supervisor/v1/restart"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT SupervisorRestartService
        WITH SOURCE_TOPIC "cloud-iot/balena/supervisor/restart-service"
        WITH DESTINATION_TOPIC "cloud-iot/balena/supervisor/restart-service/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/supervisor/v2/applications/{value.json.app_id}/restart-service"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT SupervisorBlink
        WITH SOURCE_TOPIC "cloud-iot/balena/supervisor/blink"
        WITH DESTINATION_TOPIC "cloud-iot/balena/supervisor/blink/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/supervisor/v1/blink"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT SupervisorReboot
        WITH SOURCE_TOPIC "cloud-iot/balena/supervisor/reboot"
        WITH DESTINATION_TOPIC "cloud-iot/balena/supervisor/reboot/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/supervisor/v1/reboot"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT SupervisorUpdate
        WITH SOURCE_TOPIC "cloud-iot/balena/supervisor/update"
        WITH DESTINATION_TOPIC "cloud-iot/balena/supervisor/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/supervisor/v1/update"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT SupervisorDeviceState
        WITH SOURCE_TOPIC "cloud-iot/balena/supervisor/device"
        WITH DESTINATION_TOPIC "cloud-iot/balena/supervisor/device/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/supervisor/v1/device"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
```

## MQTT examples

Request bodies go under `body`, so control fields like `api_key`, `uuid` and `fleet_slug` are not sent to balena.

**Find the devices of a fleet**: publish to `cloud-iot/balena/device/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<balena API key>",
  "odata": "$filter=belongs_to__application/any(a:a/slug%20eq%20'coreflux/line-1')&$select=uuid,device_name,is_online,overall_status"
}
```

The reply is `{"d": [ ... ]}`. Values inside `odata` must be URL-encoded: write spaces as `%20`.

**Check one device**: publish `{"api_key": "<key>", "uuid": "<device uuid>"}` to `cloud-iot/balena/device/get`. The reply includes `is_online`, `overall_status`, CPU temperature, memory and storage use, and the running, pinned and target releases. Use the full 32-character UUID.

**Pin a device to a release**: publish to `cloud-iot/balena/device/update`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<balena API key>",
  "uuid": "<device uuid>",
  "body": {"is_pinned_on__release": 3456789}
}
```

Send `{"is_pinned_on__release": null}` to make the device track its fleet again. The same event renames a device (`{"device_name": "press-07"}`) or sets a note (`{"note": "line 1 maintenance"}`). A successful PATCH returns `200` with the text `OK`.

**Pin the whole fleet**: publish to `cloud-iot/balena/fleet/update`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<balena API key>",
  "fleet_slug": "coreflux/line-1",
  "body": {"should_be_running__release": 3456789, "should_track_latest_release": false}
}
```

Get release ids from `cloud-iot/balena/release/list` with `{"api_key": "<key>", "fleet_id": 1234}`, and the fleet id from `cloud-iot/balena/fleet/get`.

**Tag a device with its UNS location**: publish to `cloud-iot/balena/device-tag/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<balena API key>",
  "body": {"device": 1234567, "tag_key": "uns_path", "value": "porto/line1/press-07"}
}
```

`device` is the numeric device id from `GetDevice`, not the UUID. Change an existing tag with `cloud-iot/balena/device-tag/update` and `{"device_id": 1234567, "tag_key": "uns_path", "body": {"value": "..."}}`; creating the same key twice returns `409`.

**Set a device environment variable**: publish to `cloud-iot/balena/device-env/create` with `{"api_key": "<key>", "body": {"device": 1234567, "name": "MQTT_BROKER", "value": "mqtt://broker.local:1883"}}`. The services on that device restart to pick up the new value.

**Restart one service on a device**: publish to `cloud-iot/balena/supervisor/restart-service`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<balena API key>",
  "app_id": 1234,
  "body": {"uuid": "<device uuid>", "data": {"serviceName": "collector"}}
}
```

The other Supervisor events take `{"uuid": "<device uuid>"}` as the body: blink and reboot as is, `SupervisorRestartApp` with `"data": {"appId": 1234}`, `SupervisorUpdate` with `"data": {"force": true}` and `SupervisorDeviceState` with `"method": "GET"`. The device must be online and connected to the balena VPN.

## Helper actions

Keep the API key in a broker secret, poll fleet health on a timer, and let operators or alarms trigger restarts and release pins with small payloads:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION BalenaPollFleetHealth
ON EVERY 5 MINUTES DO
    SET "key" WITH GET SECRET "BALENA_API_KEY"
    PUBLISH TOPIC "cloud-iot/balena/device/list" WITH { "api_key": {key}, "odata": "$filter=belongs_to__application/any(a:a/slug%20eq%20'coreflux/line-1')&$select=uuid,device_name,is_online,overall_status,cpu_temp,memory_usage,memory_total" }

DEFINE ACTION BalenaRestartServiceOnRequest
ON TOPIC "ops/balena/restart-service" DO
    SET "key" WITH GET SECRET "BALENA_API_KEY"
    SET "uuid" WITH GET JSON "uuid" IN PAYLOAD AS STRING
    SET "app" WITH GET JSON "app_id" IN PAYLOAD AS STRING
    SET "service" WITH GET JSON "service" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/balena/supervisor/restart-service" WITH { "api_key": {key}, "app_id": {app}, "body": { "uuid": {uuid}, "data": { "serviceName": {service} } } }

DEFINE ACTION BalenaPinFleetOnRequest
ON TOPIC "ops/balena/pin-fleet" DO
    SET "key" WITH GET SECRET "BALENA_API_KEY"
    SET "slug" WITH GET JSON "fleet_slug" IN PAYLOAD AS STRING
    SET "release" WITH GET JSON "release_id" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/balena/fleet/update" WITH { "api_key": {key}, "fleet_slug": {slug}, "body": { "should_be_running__release": {release}, "should_track_latest_release": false } }
```

`BalenaPollFleetHealth` publishes the device list of `coreflux/line-1` to `cloud-iot/balena/device/list/response` every five minutes; feed it into a model or dashboard. Restrict who can publish to `ops/balena/#` and read `cloud-iot/balena/#` with a rule: these topics can reboot devices and their payloads carry the API key.

## Notes

* Errors come back on the response topic: `401` for a missing or invalid key, `400` for a bad OData query or unknown field, an empty `d` list when a read matches no device or fleet, `409` for a duplicate tag key or variable name, and `429` with a `Retry-After` header when rate limited. Supervisor events fail when the device is offline or off the VPN.
* `GetDevice` names `overall_status` in `$select` on purpose: balena only returns that field when it is requested.
* Fleet slugs look like `org/fleet` and go inside the quotes as is.
* The Supervisor restart-service call through the cloud proxy follows the documented proxy pattern (`/supervisor/<path>` with `uuid` and `data`); balena documents the local form of that endpoint.
* Deleting devices, fleets, tags or variables, moving devices between fleets, OS and Supervisor upgrades, service and fleet variables, and public device URLs are not part of this template.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Azure IoT Hub](/latest/lot-language/routes/rest-api-apps/azure-iot-hub)
* [AWS IoT Core](/latest/lot-language/routes/rest-api-apps/aws-iot-core)


# Bar Tender Actions
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/bar-tender-actions

LoT connector for the on-premises BarTender Actions API: submit print scripts with MQTT data, follow script status and read script variables

Technical Preview

## Overview

Client-mode REST API connectors for BarTender label printing: print BarTender documents with data from MQTT through the BarTender 2022+ Actions API (on-premises or BarTender Cloud) or Print Portal, follow the print script status and variables, and list printers and Print Portal libraries.

This is one of the templates in the BarTender (Seagull Scientific) label printing REST API app (`bartender-label-printing`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **BarTenderActions**: Windows authentication (Negotiate) on the REST service; not sent by the connector (reverse proxy needed, unverified)
* **BarTenderCloud**: Authorization: Bearer \{value.json.access\_token}
* **BarTenderPrintPortal**: POST /BarTender/api/v1/Authenticate \{userName,password} -> token; Authorization: Bearer \{value.json.token}
* **secret**: \["BARTENDER\_PORTAL\_USERNAME", "BARTENDER\_PORTAL\_PASSWORD"]

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Bar Tender Actions connector | no |
| `BaseUrl` | string | Bar Tender Actions base URL without trailing slash (e.g. http\://YOUR\_BARTENDER\_HOST:5159) | yes |

`BASE_ADDRESS` default: `http://YOUR_BARTENDER_HOST:5159`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `SubmitScript` | POST | `/api/actions?{value.json.query}` | `mes/bartender/script/submit` | `mes/bartender/script/submit/response` | `body`, `query` |
| `ListScripts` | GET | `/api/actions?{value.json.query}` | `mes/bartender/script/list` | `mes/bartender/script/list/response` | `query` |
| `GetScriptStatus` | GET | `/api/actions/{value.json.script_id}?{value.json.query}` | `mes/bartender/script/get` | `mes/bartender/script/get/response` | `query`, `script_id` |
| `UpdateScript` | PATCH | `/api/actions/{value.json.script_id}` | `mes/bartender/script/update` | `mes/bartender/script/update/response` | `body`, `script_id` |
| `ListScriptVariables` | GET | `/api/actions/{value.json.script_id}/variables` | `mes/bartender/script-variable/list` | `mes/bartender/script-variable/list/response` | `script_id` |
| `GetScriptVariable` | GET | `/api/actions/{value.json.script_id}/variables/{value.json.variable}` | `mes/bartender/script-variable/get` | `mes/bartender/script-variable/get/response` | `script_id`, `variable` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode BAR_TENDER_ACTIONS"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BarTenderActions WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_BARTENDER_HOST:5159"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '45'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SubmitScript
        WITH SOURCE_TOPIC "mes/bartender/script/submit"
        WITH DESTINATION_TOPIC "mes/bartender/script/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListScripts
        WITH SOURCE_TOPIC "mes/bartender/script/list"
        WITH DESTINATION_TOPIC "mes/bartender/script/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetScriptStatus
        WITH SOURCE_TOPIC "mes/bartender/script/get"
        WITH DESTINATION_TOPIC "mes/bartender/script/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions/{value.json.script_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT UpdateScript
        WITH SOURCE_TOPIC "mes/bartender/script/update"
        WITH DESTINATION_TOPIC "mes/bartender/script/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/actions/{value.json.script_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListScriptVariables
        WITH SOURCE_TOPIC "mes/bartender/script-variable/list"
        WITH DESTINATION_TOPIC "mes/bartender/script-variable/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions/{value.json.script_id}/variables"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetScriptVariable
        WITH SOURCE_TOPIC "mes/bartender/script-variable/get"
        WITH DESTINATION_TOPIC "mes/bartender/script-variable/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions/{value.json.script_id}/variables/{value.json.variable}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `SubmitScript` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/bartender/script/submit/response' &
mosquitto_pub -t 'mes/bartender/script/submit' -m '{"body": {}, "query": "<query>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Bar Tender Cloud
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/bar-tender-cloud

LoT connector for BarTender Cloud: submit print scripts, track script status and variables, and list printers from MQTT with a Bearer token

Technical Preview

## Overview

Client-mode REST API connectors for BarTender label printing: print BarTender documents with data from MQTT through the BarTender 2022+ Actions API (on-premises or BarTender Cloud) or Print Portal, follow the print script status and variables, and list printers and Print Portal libraries.

This is one of the templates in the BarTender (Seagull Scientific) label printing REST API app (`bartender-label-printing`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **BarTenderActions**: Windows authentication (Negotiate) on the REST service; not sent by the connector (reverse proxy needed, unverified)
* **BarTenderCloud**: Authorization: Bearer \{value.json.access\_token}
* **BarTenderPrintPortal**: POST /BarTender/api/v1/Authenticate \{userName,password} -> token; Authorization: Bearer \{value.json.token}
* **secret**: \["BARTENDER\_PORTAL\_USERNAME", "BARTENDER\_PORTAL\_PASSWORD"]

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Bar Tender Cloud connector | no |
| `BaseUrl` | string | Bar Tender Cloud base URL without trailing slash (e.g. [https://am1.bartendercloud.com](https://am1.bartendercloud.com)) | yes |

`BASE_ADDRESS` default: `https://am1.bartendercloud.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CloudSubmitScript` | POST | `/api/actions?{value.json.query}` | `mes/bartender-cloud/script/submit` | `mes/bartender-cloud/script/submit/response` | `access_token`, `body`, `query` |
| `CloudListScripts` | GET | `/api/actions?{value.json.query}` | `mes/bartender-cloud/script/list` | `mes/bartender-cloud/script/list/response` | `access_token`, `query` |
| `CloudGetScriptStatus` | GET | `/api/actions/{value.json.script_id}?{value.json.query}` | `mes/bartender-cloud/script/get` | `mes/bartender-cloud/script/get/response` | `access_token`, `query`, `script_id` |
| `CloudUpdateScript` | PATCH | `/api/actions/{value.json.script_id}` | `mes/bartender-cloud/script/update` | `mes/bartender-cloud/script/update/response` | `access_token`, `body`, `script_id` |
| `CloudListScriptVariables` | GET | `/api/actions/{value.json.script_id}/variables` | `mes/bartender-cloud/script-variable/list` | `mes/bartender-cloud/script-variable/list/response` | `access_token`, `script_id` |
| `CloudGetScriptVariable` | GET | `/api/actions/{value.json.script_id}/variables/{value.json.variable}` | `mes/bartender-cloud/script-variable/get` | `mes/bartender-cloud/script-variable/get/response` | `access_token`, `script_id`, `variable` |
| `CloudListPrinters` | GET | `/api/devices/printers?{value.json.query}` | `mes/bartender-cloud/printer/list` | `mes/bartender-cloud/printer/list/response` | `access_token`, `query` |
| `CloudGetPrinter` | GET | `/api/devices/printers/{value.json.printer_id}` | `mes/bartender-cloud/printer/get` | `mes/bartender-cloud/printer/get/response` | `access_token`, `printer_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode BAR_TENDER_CLOUD"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BarTenderCloud WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://am1.bartendercloud.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '45'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CloudSubmitScript
        WITH SOURCE_TOPIC "mes/bartender-cloud/script/submit"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/script/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudListScripts
        WITH SOURCE_TOPIC "mes/bartender-cloud/script/list"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/script/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CloudGetScriptStatus
        WITH SOURCE_TOPIC "mes/bartender-cloud/script/get"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/script/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions/{value.json.script_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CloudUpdateScript
        WITH SOURCE_TOPIC "mes/bartender-cloud/script/update"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/script/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/actions/{value.json.script_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudListScriptVariables
        WITH SOURCE_TOPIC "mes/bartender-cloud/script-variable/list"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/script-variable/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions/{value.json.script_id}/variables"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CloudGetScriptVariable
        WITH SOURCE_TOPIC "mes/bartender-cloud/script-variable/get"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/script-variable/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/actions/{value.json.script_id}/variables/{value.json.variable}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CloudListPrinters
        WITH SOURCE_TOPIC "mes/bartender-cloud/printer/list"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/printer/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices/printers?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CloudGetPrinter
        WITH SOURCE_TOPIC "mes/bartender-cloud/printer/get"
        WITH DESTINATION_TOPIC "mes/bartender-cloud/printer/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices/printers/{value.json.printer_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `CloudSubmitScript` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/bartender-cloud/script/submit/response' &
mosquitto_pub -t 'mes/bartender-cloud/script/submit' -m '{"access_token": "<access_token>", "body": {}, "query": "<query>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Bar Tender Print Portal
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/bar-tender-print-portal

LoT connector for BarTender Print Portal: authenticate, list libraries and printers, and print BarTender documents with data from MQTT

Technical Preview

## Overview

Client-mode REST API connectors for BarTender label printing: print BarTender documents with data from MQTT through the BarTender 2022+ Actions API (on-premises or BarTender Cloud) or Print Portal, follow the print script status and variables, and list printers and Print Portal libraries.

This is one of the templates in the BarTender (Seagull Scientific) label printing REST API app (`bartender-label-printing`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **BarTenderActions**: Windows authentication (Negotiate) on the REST service; not sent by the connector (reverse proxy needed, unverified)
* **BarTenderCloud**: Authorization: Bearer \{value.json.access\_token}
* **BarTenderPrintPortal**: POST /BarTender/api/v1/Authenticate \{userName,password} -> token; Authorization: Bearer \{value.json.token}
* **secret**: \["BARTENDER\_PORTAL\_USERNAME", "BARTENDER\_PORTAL\_PASSWORD"]

Auth headers used by the template: `Authorization: Bearer {value.json.token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Bar Tender Print Portal connector | no |
| `BaseUrl` | string | Bar Tender Print Portal base URL without trailing slash (e.g. https\://YOUR\_PRINT\_PORTAL\_HOST) | yes |

`BASE_ADDRESS` default: `https://YOUR_PRINT_PORTAL_HOST`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `PortalAuthenticate` | POST | `/BarTender/api/v1/Authenticate` | `mes/bartender-portal/token/create` | `mes/bartender-portal/token/create/response` | `body` |
| `PortalListLibraries` | GET | `/BarTender/api/v1/libraries` | `mes/bartender-portal/library/list` | `mes/bartender-portal/library/list/response` | `token` |
| `PortalGetLibrary` | GET | `/BarTender/api/v1/libraries/{value.json.library_id}` | `mes/bartender-portal/library/get` | `mes/bartender-portal/library/get/response` | `library_id`, `token` |
| `PortalListPrinters` | GET | `/BarTender/api/v1/printers` | `mes/bartender-portal/printer/list` | `mes/bartender-portal/printer/list/response` | `token` |
| `PortalGetPrinter` | GET | `/BarTender/api/v1/printers/{value.json.printer}` | `mes/bartender-portal/printer/get` | `mes/bartender-portal/printer/get/response` | `printer`, `token` |
| `PortalPrint` | POST | `/BarTender/api/v1/print` | `mes/bartender-portal/label/print` | `mes/bartender-portal/label/print/response` | `body`, `token` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode BAR_TENDER_PRINT_PORTAL"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BarTenderPrintPortal WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_PRINT_PORTAL_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '45'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PortalAuthenticate
        WITH SOURCE_TOPIC "mes/bartender-portal/token/create"
        WITH DESTINATION_TOPIC "mes/bartender-portal/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/BarTender/api/v1/Authenticate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PortalListLibraries
        WITH SOURCE_TOPIC "mes/bartender-portal/library/list"
        WITH DESTINATION_TOPIC "mes/bartender-portal/library/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/BarTender/api/v1/libraries"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT PortalGetLibrary
        WITH SOURCE_TOPIC "mes/bartender-portal/library/get"
        WITH DESTINATION_TOPIC "mes/bartender-portal/library/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/BarTender/api/v1/libraries/{value.json.library_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT PortalListPrinters
        WITH SOURCE_TOPIC "mes/bartender-portal/printer/list"
        WITH DESTINATION_TOPIC "mes/bartender-portal/printer/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/BarTender/api/v1/printers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT PortalGetPrinter
        WITH SOURCE_TOPIC "mes/bartender-portal/printer/get"
        WITH DESTINATION_TOPIC "mes/bartender-portal/printer/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/BarTender/api/v1/printers/{value.json.printer}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT PortalPrint
        WITH SOURCE_TOPIC "mes/bartender-portal/label/print"
        WITH DESTINATION_TOPIC "mes/bartender-portal/label/print/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/BarTender/api/v1/print"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `PortalAuthenticate` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/bartender-portal/token/create/response' &
mosquitto_pub -t 'mes/bartender-portal/token/create' -m '{"body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Blynk Device Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/blynk-device-api

LoT connector for the Blynk Device HTTPS API: check connection, read and update datastreams, upload timestamped data and log device events

Technical Preview

## Overview

Client-mode REST API connectors for Blynk.Cloud: read and write device datastreams, upload timestamped data, raise events and manage devices, templates, webhooks and automations from MQTT, plus an opt-in webhook receiver.

This is one of the templates in the Blynk REST API app (`blynk`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Device connector: device auth token in the query string token=\{value.json.token} (Blynk has no header form for the Device HTTPS API); suggested secret BLYNK\_DEVICE\_TOKEN. Platform connector: OAuth2 client credentials (Developers > OAuth2) as HTTP Basic \{value.json.basic\_auth} on GetAccessToken / RefreshAccessToken, then Authorization: Bearer \{value.json.access\_token}; suggested secrets BLYNK\_CLIENT\_BASIC, BLYNK\_ACCESS\_TOKEN. Platform API needs a Prototype / Production / Enterprise plan. Never commit real tokens.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Blynk Device Api connector | no |
| `BaseUrl` | string | Blynk Device Api base URL without trailing slash (e.g. [https://fra1.blynk.cloud](https://fra1.blynk.cloud)) | yes |

`BASE_ADDRESS` default: `https://fra1.blynk.cloud`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `IsDeviceConnected` | GET | `/external/api/isHardwareConnected?token={value.json.token}` | `cloud-iot/blynk/connection/get` | `cloud-iot/blynk/connection/get/response` | `token` |
| `GetDatastreamValue` | GET | `/external/api/get?token={value.json.token}&{value.json.query}` | `cloud-iot/blynk/datastream/get` | `cloud-iot/blynk/datastream/get/response` | `query`, `token` |
| `GetAllDatastreamValues` | GET | `/external/api/getAll?token={value.json.token}` | `cloud-iot/blynk/datastream/list` | `cloud-iot/blynk/datastream/list/response` | `token` |
| `UpdateDatastreamValue` | GET | `/external/api/update?token={value.json.token}&{value.json.query}` | `cloud-iot/blynk/datastream/update` | `cloud-iot/blynk/datastream/update/response` | `query`, `token` |
| `BatchUpdateDatastreams` | GET | `/external/api/batch/update?token={value.json.token}&{value.json.query}` | `cloud-iot/blynk/datastream/batch-update` | `cloud-iot/blynk/datastream/batch-update/response` | `query`, `token` |
| `UploadTimestampedData` | POST | `/external/api/batch/update?token={value.json.token}&pin={value.json.pin}` | `cloud-iot/blynk/datastream-history/upload` | `cloud-iot/blynk/datastream-history/upload/response` | `body`, `pin`, `token` |
| `UpdateDatastreamProperty` | GET | `/external/api/update/property?token={value.json.token}&pin={value.json.pin}&{value.json.query}` | `cloud-iot/blynk/datastream-property/update` | `cloud-iot/blynk/datastream-property/update/response` | `pin`, `query`, `token` |
| `LogEvent` | GET | `/external/api/logEvent?token={value.json.token}&{value.json.query}` | `cloud-iot/blynk/event/log` | `cloud-iot/blynk/event/log/response` | `query`, `token` |
| `ExportDeviceHistory` | GET | `/external/api/data/get?token={value.json.token}&{value.json.query}` | `cloud-iot/blynk/history/export` | `cloud-iot/blynk/history/export/response` | `query`, `token` |
| `GetDeviceMetafield` | GET | `/external/api/device/meta?token={value.json.token}&{value.json.query}` | `cloud-iot/blynk/metafield/get` | `cloud-iot/blynk/metafield/get/response` | `query`, `token` |
| `UpdateDeviceMetafield` | GET | `/external/api/device/meta/update?token={value.json.token}&{value.json.query}` | `cloud-iot/blynk/metafield/update` | `cloud-iot/blynk/metafield/update/response` | `query`, `token` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode BLYNK_DEVICE_API"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BlynkDeviceApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://fra1.blynk.cloud"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT IsDeviceConnected
        WITH SOURCE_TOPIC "cloud-iot/blynk/connection/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/connection/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/isHardwareConnected?token={value.json.token}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetDatastreamValue
        WITH SOURCE_TOPIC "cloud-iot/blynk/datastream/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/datastream/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/get?token={value.json.token}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetAllDatastreamValues
        WITH SOURCE_TOPIC "cloud-iot/blynk/datastream/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/datastream/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/getAll?token={value.json.token}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT UpdateDatastreamValue
        WITH SOURCE_TOPIC "cloud-iot/blynk/datastream/update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/datastream/update/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/update?token={value.json.token}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT BatchUpdateDatastreams
        WITH SOURCE_TOPIC "cloud-iot/blynk/datastream/batch-update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/datastream/batch-update/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/batch/update?token={value.json.token}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT UploadTimestampedData
        WITH SOURCE_TOPIC "cloud-iot/blynk/datastream-history/upload"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/datastream-history/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/external/api/batch/update?token={value.json.token}&pin={value.json.pin}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateDatastreamProperty
        WITH SOURCE_TOPIC "cloud-iot/blynk/datastream-property/update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/datastream-property/update/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/update/property?token={value.json.token}&pin={value.json.pin}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT LogEvent
        WITH SOURCE_TOPIC "cloud-iot/blynk/event/log"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/event/log/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/logEvent?token={value.json.token}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT ExportDeviceHistory
        WITH SOURCE_TOPIC "cloud-iot/blynk/history/export"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/history/export/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/data/get?token={value.json.token}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetDeviceMetafield
        WITH SOURCE_TOPIC "cloud-iot/blynk/metafield/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/metafield/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/device/meta?token={value.json.token}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT UpdateDeviceMetafield
        WITH SOURCE_TOPIC "cloud-iot/blynk/metafield/update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/metafield/update/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/external/api/device/meta/update?token={value.json.token}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `IsDeviceConnected` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'cloud-iot/blynk/connection/get/response' &
mosquitto_pub -t 'cloud-iot/blynk/connection/get' -m '{"token": "<token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Blynk Platform Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/blynk-platform-api

LoT connector for the Blynk Platform API: get OAuth tokens and manage devices, datastreams, history, events, templates, webhooks and automations

Technical Preview

## Overview

Client-mode REST API connectors for Blynk.Cloud: read and write device datastreams, upload timestamped data, raise events and manage devices, templates, webhooks and automations from MQTT, plus an opt-in webhook receiver.

This is one of the templates in the Blynk REST API app (`blynk`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Device connector: device auth token in the query string token=\{value.json.token} (Blynk has no header form for the Device HTTPS API); suggested secret BLYNK\_DEVICE\_TOKEN. Platform connector: OAuth2 client credentials (Developers > OAuth2) as HTTP Basic \{value.json.basic\_auth} on GetAccessToken / RefreshAccessToken, then Authorization: Bearer \{value.json.access\_token}; suggested secrets BLYNK\_CLIENT\_BASIC, BLYNK\_ACCESS\_TOKEN. Platform API needs a Prototype / Production / Enterprise plan. Never commit real tokens.

Auth headers used by the template: `Authorization: Basic {value.json.basic_auth}`, `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Blynk Platform Api connector | no |
| `BaseUrl` | string | Blynk Platform Api base URL without trailing slash (e.g. [https://fra1.blynk.cloud](https://fra1.blynk.cloud)) | yes |

`BASE_ADDRESS` default: `https://fra1.blynk.cloud`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetAccessToken` | POST | `/oauth2/token?grant_type=client_credentials` | `cloud-iot/blynk/oauth-token/create` | `cloud-iot/blynk/oauth-token/create/response` | `basic_auth` |
| `RefreshAccessToken` | POST | `/oauth2/token?grant_type=refresh_token&refresh_token={value.json.refresh_token}` | `cloud-iot/blynk/oauth-token/refresh` | `cloud-iot/blynk/oauth-token/refresh/response` | `basic_auth`, `refresh_token` |
| `GetOrganization` | GET | `/api/v1/organization/profile` | `cloud-iot/blynk/organization/get` | `cloud-iot/blynk/organization/get/response` | `access_token` |
| `ListDevices` | GET | `/api/v2/organization/devices?{value.json.query}` | `cloud-iot/blynk/device/list` | `cloud-iot/blynk/device/list/response` | `access_token`, `query` |
| `SearchDevices` | GET | `/api/v1/organization/search/devices?{value.json.query}` | `cloud-iot/blynk/device/search` | `cloud-iot/blynk/device/search/response` | `access_token`, `query` |
| `GetDevice` | GET | `/api/v1/organization/device?deviceId={value.json.device_id}` | `cloud-iot/blynk/device/get` | `cloud-iot/blynk/device/get/response` | `access_token`, `device_id` |
| `GetDeviceOnline` | GET | `/api/v1/organization/device/online?deviceId={value.json.device_id}` | `cloud-iot/blynk/device-online/get` | `cloud-iot/blynk/device-online/get/response` | `access_token`, `device_id` |
| `CreateDevice` | POST | `/api/v1/organization/device/create` | `cloud-iot/blynk/device/create` | `cloud-iot/blynk/device/create/response` | `access_token`, `body` |
| `UpdateDevice` | PUT | `/api/v1/organization/device?deviceId={value.json.device_id}` | `cloud-iot/blynk/device/update` | `cloud-iot/blynk/device/update/response` | `access_token`, `body`, `device_id` |
| `GetDeviceDatastreams` | GET | `/api/v2/organization/device/datastreams?deviceId={value.json.device_id}&{value.json.query}` | `cloud-iot/blynk/device-datastream/get` | `cloud-iot/blynk/device-datastream/get/response` | `access_token`, `device_id`, `query` |
| `GetDatastreamsBatch` | GET | `/api/v1/organization/device/datastreams/batch?{value.json.query}` | `cloud-iot/blynk/device-datastream/batch-get` | `cloud-iot/blynk/device-datastream/batch-get/response` | `access_token`, `query` |
| `UpdateDeviceDatastream` | POST | `/api/v1/organization/device/datastream` | `cloud-iot/blynk/device-datastream/update` | `cloud-iot/blynk/device-datastream/update/response` | `access_token`, `body` |
| `UpdateDeviceDatastreams` | POST | `/api/v1/organization/device/datastreams` | `cloud-iot/blynk/device-datastream/batch-update` | `cloud-iot/blynk/device-datastream/batch-update/response` | `access_token`, `body` |
| `BatchUpdateProductDevices` | POST | `/api/v1/organization/product/devices/batch-update` | `cloud-iot/blynk/product-datastream/batch-update` | `cloud-iot/blynk/product-datastream/batch-update/response` | `access_token`, `body` |
| `UpdateDeviceDatastreamProperty` | POST | `/api/v1/organization/device/datastream/property` | `cloud-iot/blynk/device-datastream-property/update` | `cloud-iot/blynk/device-datastream-property/update/response` | `access_token`, `body` |
| `GetDatastreamHistory` | GET | `/api/v1/organization/device/datastream/history?deviceId={value.json.device_id}&{value.json.query}` | `cloud-iot/blynk/device-datastream-history/get` | `cloud-iot/blynk/device-datastream-history/get/response` | `access_token`, `device_id`, `query` |
| `GetDeviceHistory` | GET | `/api/v1/organization/device/datastreams/history?deviceId={value.json.device_id}&{value.json.query}` | `cloud-iot/blynk/device-history/get` | `cloud-iot/blynk/device-history/get/response` | `access_token`, `device_id`, `query` |
| `GetDeviceHistoryAggregated` | GET | `/api/v1/organization/device/datastreams/history/aggregated?deviceId={value.json.device_id}&{value.json.query}` | `cloud-iot/blynk/device-history-aggregated/get` | `cloud-iot/blynk/device-history-aggregated/get/response` | `access_token`, `device_id`, `query` |
| `TriggerDeviceEvent` | POST | `/api/v1/organization/device/trigger-event` | `cloud-iot/blynk/device-event/trigger` | `cloud-iot/blynk/device-event/trigger/response` | `access_token`, `body` |
| `GetDeviceTimeline` | GET | `/api/v1/organization/device/timeline?deviceId={value.json.device_id}&{value.json.query}` | `cloud-iot/blynk/device-timeline/get` | `cloud-iot/blynk/device-timeline/get/response` | `access_token`, `device_id`, `query` |
| `ResolveDeviceEvent` | POST | `/api/v1/organization/device/resolve-event` | `cloud-iot/blynk/device-event/resolve` | `cloud-iot/blynk/device-event/resolve/response` | `access_token`, `body` |
| `ListDeviceMetafields` | GET | `/api/v1/organization/device/metafield?deviceId={value.json.device_id}` | `cloud-iot/blynk/device-metafield/list` | `cloud-iot/blynk/device-metafield/list/response` | `access_token`, `device_id` |
| `UpdateDeviceMetafieldValue` | POST | `/api/v1/organization/device/metafield` | `cloud-iot/blynk/device-metafield/update` | `cloud-iot/blynk/device-metafield/update/response` | `access_token`, `body` |
| `ListDeviceLogs` | GET | `/api/v1/organization/device/logs?deviceId={value.json.device_id}&{value.json.query}` | `cloud-iot/blynk/device-log/list` | `cloud-iot/blynk/device-log/list/response` | `access_token`, `device_id`, `query` |
| `ListTemplates` | GET | `/api/v1/organization/templates?{value.json.query}` | `cloud-iot/blynk/template/list` | `cloud-iot/blynk/template/list/response` | `access_token`, `query` |
| `ListTemplateDatastreams` | GET | `/api/v1/organization/template/datastreams?templateId={value.json.template_id}` | `cloud-iot/blynk/template-datastream/list` | `cloud-iot/blynk/template-datastream/list/response` | `access_token`, `template_id` |
| `ListTags` | GET | `/api/v1/organization/tags` | `cloud-iot/blynk/tag/list` | `cloud-iot/blynk/tag/list/response` | `access_token` |
| `ListWebhooks` | GET | `/api/v1/organization/webhooks` | `cloud-iot/blynk/webhook/list` | `cloud-iot/blynk/webhook/list/response` | `access_token` |
| `CreateWebhook` | POST | `/api/v1/organization/webhook/create` | `cloud-iot/blynk/webhook/create` | `cloud-iot/blynk/webhook/create/response` | `access_token`, `body` |
| `ListAutomations` | GET | `/api/v1/organization/automations` | `cloud-iot/blynk/automation/list` | `cloud-iot/blynk/automation/list/response` | `access_token` |
| `ExecuteAutomation` | POST | `/api/v1/organization/automation/execute` | `cloud-iot/blynk/automation/execute` | `cloud-iot/blynk/automation/execute/response` | `access_token`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode BLYNK_PLATFORM_API"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BlynkPlatformApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://fra1.blynk.cloud"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetAccessToken
        WITH SOURCE_TOPIC "cloud-iot/blynk/oauth-token/create"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/oauth-token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth2/token?grant_type=client_credentials"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
        WITH BODY ""
    ADD EVENT RefreshAccessToken
        WITH SOURCE_TOPIC "cloud-iot/blynk/oauth-token/refresh"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/oauth-token/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth2/token?grant_type=refresh_token&refresh_token={value.json.refresh_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
        WITH BODY ""
    ADD EVENT GetOrganization
        WITH SOURCE_TOPIC "cloud-iot/blynk/organization/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/organization/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/profile"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "cloud-iot/blynk/device/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/organization/devices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT SearchDevices
        WITH SOURCE_TOPIC "cloud-iot/blynk/device/search"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/search/devices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "cloud-iot/blynk/device/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device?deviceId={value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetDeviceOnline
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-online/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-online/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/online?deviceId={value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateDevice
        WITH SOURCE_TOPIC "cloud-iot/blynk/device/create"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/device/create"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateDevice
        WITH SOURCE_TOPIC "cloud-iot/blynk/device/update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v1/organization/device?deviceId={value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDeviceDatastreams
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-datastream/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-datastream/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/organization/device/datastreams?deviceId={value.json.device_id}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetDatastreamsBatch
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-datastream/batch-get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-datastream/batch-get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/datastreams/batch?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UpdateDeviceDatastream
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-datastream/update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-datastream/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/device/datastream"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateDeviceDatastreams
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-datastream/batch-update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-datastream/batch-update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/device/datastreams"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT BatchUpdateProductDevices
        WITH SOURCE_TOPIC "cloud-iot/blynk/product-datastream/batch-update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/product-datastream/batch-update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/product/devices/batch-update"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateDeviceDatastreamProperty
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-datastream-property/update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-datastream-property/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/device/datastream/property"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDatastreamHistory
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-datastream-history/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-datastream-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/datastream/history?deviceId={value.json.device_id}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetDeviceHistory
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-history/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/datastreams/history?deviceId={value.json.device_id}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetDeviceHistoryAggregated
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-history-aggregated/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-history-aggregated/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/datastreams/history/aggregated?deviceId={value.json.device_id}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT TriggerDeviceEvent
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-event/trigger"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-event/trigger/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/device/trigger-event"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDeviceTimeline
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-timeline/get"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-timeline/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/timeline?deviceId={value.json.device_id}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ResolveDeviceEvent
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-event/resolve"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-event/resolve/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/device/resolve-event"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDeviceMetafields
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-metafield/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-metafield/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/metafield?deviceId={value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UpdateDeviceMetafieldValue
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-metafield/update"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-metafield/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/device/metafield"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDeviceLogs
        WITH SOURCE_TOPIC "cloud-iot/blynk/device-log/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/device-log/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/device/logs?deviceId={value.json.device_id}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListTemplates
        WITH SOURCE_TOPIC "cloud-iot/blynk/template/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/template/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/templates?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListTemplateDatastreams
        WITH SOURCE_TOPIC "cloud-iot/blynk/template-datastream/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/template-datastream/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/template/datastreams?templateId={value.json.template_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListTags
        WITH SOURCE_TOPIC "cloud-iot/blynk/tag/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/tag/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListWebhooks
        WITH SOURCE_TOPIC "cloud-iot/blynk/webhook/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/webhook/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateWebhook
        WITH SOURCE_TOPIC "cloud-iot/blynk/webhook/create"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/webhook/create"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListAutomations
        WITH SOURCE_TOPIC "cloud-iot/blynk/automation/list"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/automation/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/organization/automations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ExecuteAutomation
        WITH SOURCE_TOPIC "cloud-iot/blynk/automation/execute"
        WITH DESTINATION_TOPIC "cloud-iot/blynk/automation/execute/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/organization/automation/execute"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetAccessToken` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'cloud-iot/blynk/oauth-token/create/response' &
mosquitto_pub -t 'cloud-iot/blynk/oauth-token/create' -m '{"basic_auth": "<basic_auth>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# BMC Helix ITSM
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/bmc-helix-itsm

Connect Coreflux LoT to BMC Helix ITSM to open, update and resolve incidents from plant events, raise problems, changes and tasks, and find CMDB CIs

Technical Preview

## Overview

A client-mode connector for the [BMC Helix ITSM platform REST API](https://docs.helixops.ai/bin/Service-Management/IT-Service-Management/BMC-Helix-ITSM/itsm252/Developing/Integrating-third-party-applications-with-BMC-Helix-ITSM-by-using-the-platform-REST-API/Overview-of-the-platform-REST-API/), which is the AR System (Remedy) REST API underneath. When a machine, line or edge gateway goes into alarm, the broker can open an incident through the `HPD:IncidentInterface_Create` form, find it again on `HPD:Help Desk`, add work info while the condition evolves and resolve it through `HPD:IncidentInterface` when it clears. Recurring faults can become problem investigations, planned work such as PLC firmware updates can become change requests with linked CIs, and spare parts can be ordered as service requests. Generic entry, merge, association and field-metadata events reach any other AR System form.

One connector carries 30 events (13 GET, 12 POST, 5 PUT; 15 writes, no DELETE). Topics use `itsm/bmc-helix-itsm/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. Replace the placeholder `BASE_ADDRESS` (`https://your-tenant-restapi.onbmc.com`) with your REST host. BMC Helix SaaS tenants use `https://<tenant>-restapi.onbmc.com`; on-premises servers use their own REST host and port over HTTPS (plain HTTP answers `403` except for `/api/about` and `/api/version`).
2. Ask your BMC administrator for an integration user (an AR System user with a fixed or floating license and the Incident, Change, Problem or Asset permissions you need, plus a People record with support company and group for creating records).
3. Keep the username and password in broker secrets (for example `BMC_HELIX_USERNAME` and `BMC_HELIX_PASSWORD`) and build the login body in a LoT action with `GET SECRET`. Never retain topics that carry the password or the token.

## Authentication

The AR REST API uses a JSON Web Token. Publish a form-encoded body to `itsm/bmc-helix-itsm/auth/login`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"body": "username=coreflux.integration&password=<password>"}
```

The response on `itsm/bmc-helix-itsm/auth/login/response` is the raw token text, valid for one hour. Send it as `token` in every other payload; the connector turns it into `Authorization: AR-JWT <token>`. Log in again before the hour is up, and publish `{"token":"..."}` to `itsm/bmc-helix-itsm/auth/logout` when the integration stops.

## Examples

Open an incident when a press overheats (`itsm/bmc-helix-itsm/incidents/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "body": {"values": {"First_Name": "Coreflux", "Last_Name": "Integration", "Description": "Press 7 overtemperature (94 C)", "Impact": "3-Moderate/Limited", "Urgency": "2-High", "Status": "Assigned", "Reported Source": "Direct Input", "Service_Type": "Infrastructure Event", "z1D_Action": "CREATE"}}}
```

The response carries the new `Incident Number`. Add work info as the temperature falls (`itsm/bmc-helix-itsm/incidents/worklog/add`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "body": {"values": {"Incident Number": "INC000000000701", "Description": "Spindle temp 88 C and falling", "Work Log Type": "General Information"}, "mergeOptions": {"mergeType": "DUP_NEW_ID"}}}
```

Find the interface record (`itsm/bmc-helix-itsm/incidents/interface/list`) and resolve it (`itsm/bmc-helix-itsm/incidents/interface/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "query": "q=%27Incident%20Number%27%3D%22INC000000000701%22&fields=values(Request%20ID,Status)"}
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"token": "<jwt>", "id": "<Request ID>", "body": {"values": {"Status": "Resolved", "Status_Reason": "No Further Action Required", "Resolution": "Temperature back to 61 C"}}}
```

Search values are sent as given, so URL-encode AR qualifications (`'Status' = "Assigned"` becomes `q=%27Status%27%20%3D%20%22Assigned%22`) and form names in `form` (`HPD:Help Desk` becomes `HPD%3AHelp%20Desk`). Lists page with `offset` and `limit` and sort with `sort=Submit%20Date.desc`.

> [!TIP]
>
> Field names such as `Service_Type`, `Status_Reason` or `Change Request Status` are BMC's defaults. Tenants are often customised, so read the real names with `itsm/bmc-helix-itsm/forms/fields/list` (`{"token":"...","form":"HPD%3AIncidentInterface_Create","query":"field_type=A"}`) before mapping plant data.

## Events

| Event | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - |
| `AboutGet` | `GET` | `/api/about` | `itsm/bmc-helix-itsm/server/about` | | No credentials: AR System server info. Allowed without a token (and the only endpoint besides /api/version that answers over plain HTTP). |
| `TokenLogin` | `POST` | `/api/jwt/login` | `itsm/bmc-helix-itsm/auth/login` | | Get a JWT (valid 1 hour). body is a form-encoded STRING: "username=coreflux.integration\&password=..." (optional authString header not packaged). Response body is the raw token text; send it as payload field token on every other event. |
| `TokenLogout` | `POST` | `/api/jwt/logout` | `itsm/bmc-helix-itsm/auth/logout` | | Release the token when the integration stops. |
| `IncidentCreate` | `POST` | `/api/arsys/v1/entry/HPD:IncidentInterface_Create?fields=values(Incident%20Number)` | `itsm/bmc-helix-itsm/incidents/create` | Yes | Catalog 'POST entry/HPD:IncidentInterface\_Create'. body: \{"values":\{"First\_Name":"Coreflux","Last\_Name":"Integration","Description":"Press 7 overtemperature","Impact":"3-Moderate/Limited","Urgency":"2-High","Status":"Assigned","Reported Source":"Direct Input","Service\_Type":"Infrastructure Event","z1D\_Action":"CREATE"}}. 201 + Location; response values carry the Incident Number. |
| `IncidentCreateGet` | `GET` | `/api/arsys/v1/entry/HPD:IncidentInterface_Create/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/create/get` | | Read back a create-interface record. id = Request ID from the Location header of IncidentCreate. |
| `IncidentsList` | `GET` | `/api/arsys/v1/entry/HPD:Help%20Desk?{value.json.query}` | `itsm/bmc-helix-itsm/incidents/list` | | Catalog 'GET entry/HPD:Help Desk'. query e.g. q=%27Status%27%3C%224%22%20AND%20%27Description%27%20LIKE%20%22%25Press%207%25%22\&fields=values(Incident%20Number,Status,Description)\&limit=20\&sort=Submit%20Date.desc (URL-encoded AR qualification). |
| `IncidentGet` | `GET` | `/api/arsys/v1/entry/HPD:Help%20Desk/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/get` | | One incident on HPD:Help Desk by entry id (Entry ID / Request ID). |
| `IncidentUpdate` | `PUT` | `/api/arsys/v1/entry/HPD:Help%20Desk/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/update` | Yes | Catalog 'PUT entry/HPD:Help Desk/\{id}'. body: \{"values":\{"Status":"In Progress"}}. 204. BMC recommends IncidentInterfaceUpdate for status changes so ITSM workflow runs. |
| `IncidentInterfaceList` | `GET` | `/api/arsys/v1/entry/HPD:IncidentInterface?{value.json.query}` | `itsm/bmc-helix-itsm/incidents/interface/list` | | Find the interface Request ID for an incident. query e.g. q=%27Incident%20Number%27%3D%22INC000000000701%22\&fields=values(Request%20ID,Status). |
| `IncidentInterfaceUpdate` | `PUT` | `/api/arsys/v1/entry/HPD:IncidentInterface/{value.json.id}` | `itsm/bmc-helix-itsm/incidents/interface/update` | Yes | Documented way to modify an incident. id = Request ID on HPD:IncidentInterface. body: \{"values":\{"Status":"Resolved","Status\_Reason":"No Further Action Required","Resolution":"Temperature back to normal"}}. 204. |
| `IncidentWorkLogAdd` | `POST` | `/api/arsys/v1/mergeEntry/HPD:WorkLog` | `itsm/bmc-helix-itsm/incidents/worklog/add` | Yes | Work info on an incident. body: \{"values":\{"Incident Number":"INC000000000701","Description":"Spindle temp 88 C and falling","Detailed Description":"...","Work Log Type":"General Information"},"mergeOptions":\{"mergeType":"DUP\_NEW\_ID"}}. |
| `IncidentWorkLogsList` | `GET` | `/api/arsys/v1/entry/HPD:WorkLog?{value.json.query}` | `itsm/bmc-helix-itsm/incidents/worklog/list` | | query e.g. q=%27Incident%20Number%27%3D%22INC000000000701%22\&sort=Submit%20Date.desc\&limit=20. |
| `ProblemCreate` | `POST` | `/api/arsys/v1/entry/PBM:ProblemInterface_Create?fields=values(Problem%20Investigation%20ID)` | `itsm/bmc-helix-itsm/problems/create` | Yes | Recurring machine faults. body: \{"values":\{"z1D\_Action":"PROBLEM","Status":"Draft","Investigation Driver":"High Impact Incident","First Name":"Coreflux","Last Name":"Integration","Company":"...","Description":"Press 7 overheats weekly","Impact":"2-Significant/Large","Urgency":"2-High"}}. |
| `ChangeCreate` | `POST` | `/api/arsys/v1/entry/CHG:ChangeInterface_Create` | `itsm/bmc-helix-itsm/changes/create` | Yes | body: \{"values":\{"z1D\_Action":"CREATE","First Name":"Coreflux","Last Name":"Integration","Description":"Firmware update line 2 PLCs","Impact":"3-Moderate/Limited","Urgency":"3-Medium","Status":"Draft","Company":"...","Location Company":"...","Change Type":"Change","Change Timing":"Normal"}}. 201 + Location. |
| `ChangesList` | `GET` | `/api/arsys/v1/entry/CHG:ChangeInterface?{value.json.query}` | `itsm/bmc-helix-itsm/changes/list` | | query e.g. q=%27Change%20Request%20Status%27%3D%22Scheduled%22\&limit=20 (field names vary by version; check FieldsList). |
| `ChangeUpdate` | `PUT` | `/api/arsys/v1/entry/CHG:ChangeInterface/{value.json.id}` | `itsm/bmc-helix-itsm/changes/update` | Yes | id = Request ID on CHG:ChangeInterface. body: \{"values":\{"Change Request Status":"Completed","Status Reason":"Final Review Complete"}}. 204. |
| `ChangeWorkLogAdd` | `POST` | `/api/arsys/v1/entry/CHG:WorkLog` | `itsm/bmc-helix-itsm/changes/worklog/add` | Yes | Work info on a change. body: \{"values":\{"Infrastructure Change ID":"CRQ000000000101","Description":"Line 2 PLC 3 flashed","Work Log Type":"General Information"}}. |
| `ChangeCIAssociate` | `POST` | `/api/arsys/v1/entry/CHG:Associations` | `itsm/bmc-helix-itsm/changes/associations/add` | Yes | Link a CI (asset) to a change. body: \{"values":\{...}} with the change id, CI reconciliation id and association type (field names from FieldsList on CHG:Associations). |
| `TaskCreate` | `POST` | `/api/arsys/v1/entry/TMS:Task` | `itsm/bmc-helix-itsm/tasks/create` | Yes | Task under an incident or change. body: \{"values":\{"TaskName":"Inspect press 7","Summary":"...","TaskType":"Manual","Status":"Pending","RootRequestName":"INC000000000701","RootRequestID":"INC000000000701","RootRequestInstanceID":"...","RootRequestFormName":"HPD:Help Desk","RootRequestMode":"0","Company":"...","Location Company":"..."}}. |
| `TasksList` | `GET` | `/api/arsys/v1/entry/TMS:TaskInterface?{value.json.query}` | `itsm/bmc-helix-itsm/tasks/list` | | query e.g. q=%27RootRequestID%27%3D%22INC000000000701%22\&limit=20. |
| `TaskUpdate` | `PUT` | `/api/arsys/v1/entry/TMS:TaskInterface/{value.json.id}` | `itsm/bmc-helix-itsm/tasks/update` | Yes | body: \{"values":\{"Status":"Closed"}}. 204. |
| `ServiceRequestCreate` | `POST` | `/api/arsys/v1/entry/SRM:RequestInterface_Create` | `itsm/bmc-helix-itsm/service-requests/create` | Yes | Spare-part or service request. body: \{"values":\{"z1D Action":"CREATE","Source Keyword":"Coreflux","TitleInstanceID":"\<offering instance id>","First Name":"...","Last Name":"...","Short Description":"Replace press 7 thermocouple","Status":"Submitted","Company":"..."}}. |
| `AssetCIsList` | `GET` | `/api/arsys/v1/entry/AST:BaseElement?{value.json.query}` | `itsm/bmc-helix-itsm/assets/cis/list` | | Find the CMDB CI for a plant asset (needs Asset Management). query e.g. q=%27Name%27%3D%22PRESS-07%22\&fields=values(Name,Reconciliation%20Identity,Status). |
| `EntriesList` | `GET` | `/api/arsys/v1/entry/{value.json.form}?{value.json.query}` | `itsm/bmc-helix-itsm/entries/list` | | Generic search on any form. form must be URL-encoded (e.g. HPD%3AHelp%20Desk); query uses q, fields, offset, limit, sort. |
| `EntryGet` | `GET` | `/api/arsys/v1/entry/{value.json.form}/{value.json.id}` | `itsm/bmc-helix-itsm/entries/get` | | Generic: one entry on any form. |
| `EntryAssociationsGet` | `GET` | `/api/arsys/v1/entry/{value.json.form}/{value.json.id}/assoc/{value.json.association}` | `itsm/bmc-helix-itsm/entries/associations/get` | | Generic: entries linked to an entry through an association. |
| `EntryCreate` | `POST` | `/api/arsys/v1/entry/{value.json.form}` | `itsm/bmc-helix-itsm/entries/create` | Yes | Generic create on any form. body: \{"values":\{...}}. 201 + Location. |
| `EntryUpdate` | `PUT` | `/api/arsys/v1/entry/{value.json.form}/{value.json.id}` | `itsm/bmc-helix-itsm/entries/update` | Yes | Generic modify. body: \{"values":\{...}}. 204. |
| `EntryMerge` | `POST` | `/api/arsys/v1/mergeEntry/{value.json.form}` | `itsm/bmc-helix-itsm/entries/merge` | Yes | Generic merge (upsert by qualification). body: \{"values":\{...},"mergeOptions":\{"mergeType":"DUP\_MERGE","multimatchOption":0},"qualification":"'Name' = "PRESS-07""}. |
| `FieldsList` | `GET` | `/api/arsys/v1.0/fields/{value.json.form}?{value.json.query}` | `itsm/bmc-helix-itsm/forms/fields/list` | | Field metadata for a form (names and ids to use in values and q). query e.g. field\_type=A or field\_ids=1,7,8 (not both). |

## Responses

Successful reads answer `200` with `entries` (lists) or `values` (one entry). Creates answer `201` with a `Location` header pointing at the new entry (plus the requested `fields=values(...)` in the body); updates answer `204` with no body. Errors come back as a JSON array of AR System messages (`messageType`, `messageNumber`, `messageText`, `messageAppendedText`).

## Not packaged

* All DELETE endpoints on purpose.
* Attachments (`/attach/{fieldName}`), menus, the simplified ITSM REST API, CMDB REST API (`/api/cmdb/v1`), Smart IT and Digital Workplace APIs.
* The incoming direction: BMC Helix can call outbound REST webhooks from workflow; those can post to a separate `ENABLE_SERVER` REST\_API connector.


# Box
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/box

Connect Coreflux LoT to Box to upload and download plant files, manage folders, metadata, shared links, comments, tasks, webhooks and events

Technical Preview

## Overview

Client-mode connectors for the [Box Platform API](https://developer.box.com/reference) that move plant files between the broker and Box. A typical flow writes a shift report, batch record or alarm snapshot as a JSON or CSV file into a plant folder, uploads today's setpoint table as a new version of the same file, reads a recipe back when a line changes over, tags a batch record with metadata (line, batch, product, quality state) and releases it with a metadata update, finds files by metadata or by search, moves processed files to an archive folder, and shares a weekly report with a shared link. New files in an inbox folder can be picked up with a V2 webhook (needs a public HTTPS receiver) or by polling the user event stream with a stream position.

Box serves uploads from a separate host, so the template file `BoxRestApi.lot` holds two connectors:

| Connector | Base address | Format | Events |
| - | - | - | - |
| `BoxRestApi` | `https://api.box.com` | JSON API under `/2.0/...`, and `/oauth2/token` for access tokens | 42 |
| `BoxUploadRestApi` | `https://upload.box.com` | `multipart/form-data` uploads under `/api/2.0/files/content` (new file) and `/api/2.0/files/{file_id}/content` (new version) | 2 |

The connectors carry 44 events (24 GET, 14 POST, 6 PUT; 18 writes, no delete). Topics use `storage/box/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. In the [Box Developer Console](https://app.box.com/developers/console), create a **Platform App** (Custom App) with **Server Authentication (Client Credentials Grant)**. JWT server authentication works the same way, but the broker then needs a signed JWT assertion for each token request.
2. Under **App Access Level**, keep **App Access Only** (the app works as its own service account) or pick **App + Enterprise Access** if it must act as a managed user. Under **Application Scopes**, enable **Read all files and folders stored in Box** and **Write all files and folders stored in Box** (`root_readwrite`), **Manage webhooks** (`manage_webhook`) for the webhook events, and **Manage enterprise properties** (`manage_enterprise_properties`) only if the broker reads enterprise metadata templates.
3. Authorize the app in the Box Admin Console (free developer accounts authorize it automatically) and reauthorize it after every scope change.
4. Note the **Client ID** and **Client Secret** (Configuration tab) and the **Enterprise ID** (General Settings). Keep them in broker secrets, for example `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET` and `BOX_ENTERPRISE_ID`, and the current token in `BOX_ACCESS_TOKEN`. Inject them in a LoT action with `GET SECRET`.
5. The service account has its own, empty root folder. Invite it (its login looks like `AutomationUser_…@boxdevedition.com`, returned by `UserMe`) as an **Editor** collaborator on the plant folders the broker should use, and use those folder ids in payloads.

## Authentication

Every event except `OAuthToken` sends `Authorization: Bearer <token>` built from the `access_token` field of the payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_BOX_ACCESS_TOKEN"}
```

Get the token with `OAuthToken` (`storage/box/oauth/token/create`). It sends no `Authorization` header; the client credentials travel in the form. Use `box_subject_type` `enterprise` with the enterprise id for the service account, or `user` with a user id for a managed user (needs App + Enterprise Access and **Generate user access tokens**):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"form": "grant_type=client_credentials&client_id=<BOX_CLIENT_ID>&client_secret=<BOX_CLIENT_SECRET>&box_subject_type=enterprise&box_subject_id=<BOX_ENTERPRISE_ID>"}
```

Box answers with `access_token` and `expires_in` (about 3600 seconds). The Client Credentials Grant returns no refresh token, so request a new token before the old one expires. JWT apps send `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<signed JWT>&client_id=...&client_secret=...` instead.

> [!WARNING]
>
> The `OAuthToken` request carries the client secret and the response carries the access token. Restrict `storage/box/oauth/#` with ACLs, never retain those topics, and store the new token in the secret instead of passing it around on open topics.

## Payloads

| Field | Used by | Content |
| - | - | - |
| `access_token` | every event except `OAuthToken` | OAuth 2.0 access token |
| `folder_id`, `file_id`, `webhook_id`, `collaboration_id` | events with that id in the path | Box ids as strings. Folder `"0"` is the root (All Files). |
| `scope`, `template_key` | metadata events | `enterprise` (or `global` for `properties`) and the template key, for example `batchRecord` |
| `query` | GET events with `?{value.json.query}` | URL query string without `?`, for example `fields=id,name,size&limit=100`, or `""` |
| `body` | POST and PUT events | JSON request body; a JSON array of JSON Patch operations for `FileMetadataUpdate` |
| `form` | `OAuthToken` | URL-encoded token request |
| `shared_link` | `SharedItemGet` | Shared link URL, sent as the `BoxApi: shared_link=<url>` header |
| `multipart` | `FileUpload`, `FileVersionUpload` | Complete `multipart/form-data` body (see below) |

Send `query` as an empty string when you need no parameters; the connector then calls, for example, `/2.0/users/me?`. Use `fields` to keep responses small enough for MQTT.

## Uploading files

Box takes uploads as `multipart/form-data` with two parts: `attributes` (JSON with `name` and, for a new file, `parent.id`) and then `file`. The `attributes` part must come first; otherwise Box answers `400 metadata_after_file_contents`. The upload connector sets `Content-Type: multipart/form-data; boundary=CorefluxBoxBoundary`, so the payload field `multipart` must hold the whole body with that boundary and CRLF line ends:

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
--CorefluxBoxBoundary
Content-Disposition: form-data; name="attributes"

{"name":"2026-10-05-shift-A.json","parent":{"id":"1001"}}
--CorefluxBoxBoundary
Content-Disposition: form-data; name="file"; filename="2026-10-05-shift-A.json"
Content-Type: application/json

{"line":"2","shift":"A","oee":0.87,"scrap":14}
--CorefluxBoxBoundary--
```

As a JSON payload on `storage/box/files/upload` (build the string in a LoT action or on the publishing client; `\r\n` are the CRLF line ends):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "multipart": "--CorefluxBoxBoundary\r\nContent-Disposition: form-data; name=\"attributes\"\r\n\r\n{\"name\":\"2026-10-05-shift-A.json\",\"parent\":{\"id\":\"1001\"}}\r\n--CorefluxBoxBoundary\r\nContent-Disposition: form-data; name=\"file\"; filename=\"2026-10-05-shift-A.json\"\r\nContent-Type: application/json\r\n\r\n{\"line\":\"2\",\"shift\":\"A\",\"oee\":0.87,\"scrap\":14,\"operator\":\"Jo\\u00e3o\"}\r\n--CorefluxBoxBoundary--\r\n"}
```

Box answers `201` with a collection holding the new file (`id`, `sha1`, `file_version`). If a file with that name already exists in the folder, Box answers `409 item_name_in_use`; upload a new version instead with `FileVersionUpload` (`storage/box/files/versions/upload`, same body, `file_id` in the payload, `attributes` with only `name`). Direct uploads accept up to 50 MB, but keep MQTT payloads small.

## Examples

List a folder (`storage/box/folders/items/list`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "folder_id": "1001", "query": "fields=id,type,name,size,modified_at&limit=100"}
```

Read a recipe back on changeover (`storage/box/files/download`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "file_id": "2001", "query": ""}
```

Box answers `302` with a short-lived `dl.boxcloud.com` link, which needs no token. The broker's HTTP client must follow it to publish the file content. Keep downloads to text and JSON files that fit an MQTT message.

Tag a batch record and release it later (`storage/box/files/metadata/create`, then `storage/box/files/metadata/update` with JSON Patch):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "file_id": "2001", "scope": "enterprise", "template_key": "batchRecord", "body": {"line": "2", "batch": "1005-A", "product": "PX-200", "qualityState": "pending"}}
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "file_id": "2001", "scope": "enterprise", "template_key": "batchRecord", "body": [{"op": "test", "path": "/qualityState", "value": "pending"}, {"op": "replace", "path": "/qualityState", "value": "released"}]}
```

The `test` operation makes the update fail with `409` if somebody changed the value in the meantime.

Find released batch records of line 2 (`storage/box/metadata/query`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "body": {"from": "enterprise_12345.batchRecord", "ancestor_folder_id": "1001", "query": "line = :line AND qualityState = :state", "query_params": {"line": "2", "state": "released"}, "fields": ["name", "metadata.enterprise_12345.batchRecord.batch"], "limit": 100}}
```

Archive a processed file instead of deleting it (`storage/box/files/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "file_id": "2001", "body": {"parent": {"id": "1009"}, "name": "2026-10-05-shift-A.json", "tags": ["processed"]}}
```

Share a weekly report inside the company (`storage/box/files/shared-link/add`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "file_id": "2001", "body": {"shared_link": {"access": "company", "permissions": {"can_download": true}}}}
```

Watch an inbox folder for new files with a V2 webhook (`storage/box/webhooks/create`). The `address` must be HTTPS on port 443:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "body": {"target": {"id": "1006", "type": "folder"}, "address": "https://broker.example.com/box/webhooks", "triggers": ["FILE.UPLOADED", "FILE.MOVED"]}}
```

Or poll the event stream without a public endpoint (`storage/box/events/list`):

1. Get the current position: `{"access_token": "<token>", "query": "stream_position=now"}` returns `next_stream_position` and no events.
2. Ask for changes since then: `{"access_token": "<token>", "query": "stream_type=changes&stream_position=<next_stream_position>&limit=100"}`. Store the new `next_stream_position` after every call. Box may return an event more than once or out of order, so de-duplicate by `event_id`.

## Events

| Event | Connector | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - | - |
| `UserMe` | API | `GET` | `/2.0/users/me?{value.json.query}` | `storage/box/users/me/get` | | Smoke: the user behind the token (for client credentials: the app's service account, or the managed user from box\_subject\_type=user). query e.g. `fields=id,name,login,enterprise` (or empty). |
| `OAuthToken` | API | `POST` | `/oauth2/token` | `storage/box/oauth/token/create` | | Get an access token (about 60 minutes; Client Credentials Grant has no refresh token, so ask again before expiry). No Authorization header; credentials go in the form. form: `grant_type=client_credentials&client_id=<BOX_CLIENT_ID>&client_secret=<BOX_CLIENT_SECRET>&box_subject_type=enterprise&box_subject_id=<BOX_ENTERPRISE_ID>` (or box\_subject\_type=user\&box\_subject\_id=`<user id>`; JWT apps send grant\_type=urn:ietf:params:oauth:grant-type:jwt-bearer\&assertion=`<signed JWT>`\&client\_id=...\&client\_secret=...). The response carries access\_token: never retain it, restrict storage/box/oauth/# with ACLs. |
| `FolderGet` | API | `GET` | `/2.0/folders/{value.json.folder_id}?{value.json.query}` | `storage/box/folders/get` | | Folder info (name, path\_collection, item\_collection, size, modified\_at, shared\_link). folder\_id "0" is the root (All Files). query e.g. `fields=id,name,path_collection,item_status` (or empty). |
| `FolderItemsList` | API | `GET` | `/2.0/folders/{value.json.folder_id}/items?{value.json.query}` | `storage/box/folders/items/list` | | Catalog 'GET folders/`{id}`/items'. Files, folders and web links in a folder. query e.g. `fields=id,type,name,size,modified_at,sha1&limit=1000&usemarker=true` (then marker=`<next_marker>`), or sort=date\&direction=DESC\&offset=0. |
| `FolderCreate` | API | `POST` | `/2.0/folders` | `storage/box/folders/create` | Yes | Create a folder, e.g. one per line, batch or day. body: `{"name":"2026-10-05","parent":{"id":"<line-2 folder id>"}}`. 409 item\_name\_in\_use if it exists (the error context\_info holds the existing folder). |
| `FolderUpdate` | API | `PUT` | `/2.0/folders/{value.json.folder_id}` | `storage/box/folders/update` | Yes | Rename or move a folder, or set its description and tags (archive a finished batch folder instead of deleting it). body: `{"name":"batch-1005-A (closed)","parent":{"id":"<archive folder id>"},"description":"Closed 2026-10-05 by line 2","tags":["closed","line-2"]}`. |
| `FolderCopy` | API | `POST` | `/2.0/folders/{value.json.folder_id}/copy` | `storage/box/folders/copy` | Yes | Copy a folder tree, e.g. a template folder for a new work order. body: `{"parent":{"id":"<maintenance folder id>"},"name":"WO-4711"}`. |
| `FolderSharedLinkAdd` | API | `PUT` | `/2.0/folders/{value.json.folder_id}?fields=shared_link` | `storage/box/folders/shared-link/add` | Yes | Create or change the shared link of a folder (e.g. a report folder for a customer). body: `{"shared_link":{"access":"company","permissions":{"can_download":true},"unshared_at":"2026-12-31T23:59:59Z"}}` (access open / company / collaborators; unshared\_at needs a paid account). Returns shared\_link.url. |
| `FolderCollaborationsList` | API | `GET` | `/2.0/folders/{value.json.folder_id}/collaborations?{value.json.query}` | `storage/box/folders/collaborations/list` | | Who has access to a folder and with which role (editor, viewer, uploader, ...). query e.g. `fields=id,role,accessible_by,status&limit=100` (or empty). |
| `FolderMetadataList` | API | `GET` | `/2.0/folders/{value.json.folder_id}/metadata` | `storage/box/folders/metadata/list` | | All metadata instances on a folder (every template applied to it). folder\_id "0" is not allowed for metadata. |
| `FolderMetadataGet` | API | `GET` | `/2.0/folders/{value.json.folder_id}/metadata/{value.json.scope}/{value.json.template_key}` | `storage/box/folders/metadata/get` | | One metadata instance on a folder. scope enterprise (or global for properties); template\_key e.g. plantFolder. 404 instance\_not\_found if it is not applied. |
| `FolderMetadataCreate` | API | `POST` | `/2.0/folders/{value.json.folder_id}/metadata/{value.json.scope}/{value.json.template_key}` | `storage/box/folders/metadata/create` | Yes | Apply a metadata template to a folder. body: the field values, e.g. `{"plant":"Porto","line":"2","costCenter":"PT-OPS-02"}` (keys = template field keys). 409 tuple\_already\_exists if applied; use the file-style JSON Patch update then. |
| `FileGet` | API | `GET` | `/2.0/files/{value.json.file_id}?{value.json.query}` | `storage/box/files/get` | | File info (name, size, sha1, version, parent, modified\_at, lock, shared\_link). query e.g. `fields=id,name,size,sha1,file_version,modified_at,parent,lock` (or empty). |
| `FileUpdate` | API | `PUT` | `/2.0/files/{value.json.file_id}` | `storage/box/files/update` | Yes | Rename or move a file (archive a processed report instead of deleting it), set description or tags, or lock it while a line uses it. body: `{"parent":{"id":"<archive folder id>"},"name":"2026-10-05-shift-A.json","tags":["processed"]}` or `{"lock":{"access":"lock","is_download_prevented":false}}`. |
| `FileCopy` | API | `POST` | `/2.0/files/{value.json.file_id}/copy` | `storage/box/files/copy` | Yes | Copy a file, e.g. a recipe template into a batch folder. body: `{"parent":{"id":"<batch folder id>"},"name":"batch-1005-A-recipe.json"}` (optional version for an older file version). |
| `FileDownload` | API | `GET` | `/2.0/files/{value.json.file_id}/content?{value.json.query}` | `storage/box/files/download` | | Read a file back (recipe, config, setpoint table). Box answers 302 with a short-lived dl.boxcloud.com location; the connector must follow it to return the bytes (202 with Retry-After if the file is not ready). query e.g. `version=<file version id>` (or empty). Text and JSON files only through MQTT. |
| `FileVersionsList` | API | `GET` | `/2.0/files/{value.json.file_id}/versions?{value.json.query}` | `storage/box/files/versions/list` | | Earlier versions of a file (who changed a recipe or config and when; the current version is not in the list). query e.g. `fields=id,sha1,size,modified_at,modified_by&limit=100` (or empty). Needs a paid account. |
| `FileVersionPromote` | API | `POST` | `/2.0/files/{value.json.file_id}/versions/current` | `storage/box/files/versions/promote` | Yes | Roll back a file to an earlier version (a copy of it becomes the new current version). body: `{"id":"<file version id from FileVersionsList>","type":"file_version"}`. |
| `FileSharedLinkAdd` | API | `PUT` | `/2.0/files/{value.json.file_id}?fields=shared_link` | `storage/box/files/shared-link/add` | Yes | Create or change the shared link of a file (e.g. a weekly OEE report). body: `{"shared_link":{"access":"company","permissions":{"can_download":true}}}` (access open / company / collaborators; optional password, vanity\_name, unshared\_at). Returns shared\_link.url and download\_url. |
| `FileSharedLinkGet` | API | `GET` | `/2.0/files/{value.json.file_id}?fields=shared_link` | `storage/box/files/shared-link/get` | | The shared link of a file (url, download\_url, access, effective\_permission, unshared\_at), or null if none. |
| `SharedItemGet` | API | `GET` | `/2.0/shared_items` | `storage/box/shared-items/get` | | Resolve a shared link to its file or folder (e.g. a supplier's spec sheet shared with the plant), then use FileGet / FileDownload with the returned id. shared\_link: the link URL, e.g. [https://app.box.com/s/abc123](https://app.box.com/s/abc123) (append \&shared\_link\_password=`<password>` if it has one); sent as header BoxApi: shared\_link=`<url>`. |
| `FileCollaborationsList` | API | `GET` | `/2.0/files/{value.json.file_id}/collaborations?{value.json.query}` | `storage/box/files/collaborations/list` | | Who has access to a file directly (not inherited from folders). query e.g. `fields=id,role,accessible_by,status&limit=100` (or empty). |
| `CollaborationGet` | API | `GET` | `/2.0/collaborations/{value.json.collaboration_id}` | `storage/box/collaborations/get` | | One collaboration (item, accessible\_by user or group, role, status, expires\_at). |
| `FileMetadataList` | API | `GET` | `/2.0/files/{value.json.file_id}/metadata` | `storage/box/files/metadata/list` | | All metadata instances on a file (batch, asset, quality state, ...). |
| `FileMetadataGet` | API | `GET` | `/2.0/files/{value.json.file_id}/metadata/{value.json.scope}/{value.json.template_key}` | `storage/box/files/metadata/get` | | One metadata instance on a file. scope enterprise (or global for properties); template\_key e.g. batchRecord. 404 instance\_not\_found if it is not applied. |
| `FileMetadataCreate` | API | `POST` | `/2.0/files/{value.json.file_id}/metadata/{value.json.scope}/{value.json.template_key}` | `storage/box/files/metadata/create` | Yes | Tag a file with structured metadata, e.g. a batch record with line, batch, product and quality state. body: `{"line":"2","batch":"1005-A","product":"PX-200","qualityState":"pending"}` (keys = template field keys; global/properties takes any string keys). 409 tuple\_already\_exists if applied. |
| `FileMetadataUpdate` | API | `PUT` | `/2.0/files/{value.json.file_id}/metadata/{value.json.scope}/{value.json.template_key}` | `storage/box/files/metadata/update` | Yes | Change metadata values with JSON Patch (Content-Type application/json-patch+json), e.g. release a batch. body: `[{"op":"test","path":"/qualityState","value":"pending"},{"op":"replace","path":"/qualityState","value":"released"}]` (op add / replace / test / remove / move / copy; remove only clears one field). |
| `MetadataQuery` | API | `POST` | `/2.0/metadata_queries/execute_read` | `storage/box/metadata/query` | | Find files and folders by metadata values (read-only although it is a POST), e.g. all released batch records of line 2. body: `{"from":"enterprise_<BOX_ENTERPRISE_ID>.batchRecord","ancestor_folder_id":"<plant folder id>","query":"line = :line AND qualityState = :state","query_params":{"line":"2","state":"released"},"fields":["name","metadata.enterprise_<BOX_ENTERPRISE_ID>.batchRecord.batch"],"limit":100}`. Page with marker. |
| `MetadataTemplatesList` | API | `GET` | `/2.0/metadata_templates/enterprise?{value.json.query}` | `storage/box/metadata-templates/list` | | Metadata templates of the enterprise (templateKey, displayName, fields). query e.g. `limit=100` (or empty). |
| `MetadataTemplateSchemaGet` | API | `GET` | `/2.0/metadata_templates/{value.json.scope}/{value.json.template_key}/schema` | `storage/box/metadata-templates/schema/get` | | Fields of one template (keys, types, enum options) before writing metadata. scope enterprise; template\_key e.g. batchRecord. |
| `Search` | API | `GET` | `/2.0/search?{value.json.query}` | `storage/box/items/search` | | Search names, descriptions, tags and file content under folders. query (URL-encoded) e.g. query=press-7\&type=file\&file\_extensions=pdf,csv\&ancestor\_folder\_ids=`<plant folder id>`\&fields=id,name,parent,modified\_at\&limit=50 (sort=modified\_at\&direction=DESC). Box indexes new and changed files with a delay, so a file just uploaded may not be found yet. |
| `FileCommentsList` | API | `GET` | `/2.0/files/{value.json.file_id}/comments?{value.json.query}` | `storage/box/files/comments/list` | | Comments on a file (e.g. a technician's notes on an inspection report). query e.g. `fields=id,message,created_by,created_at&limit=100` (or empty). |
| `CommentCreate` | API | `POST` | `/2.0/comments` | `storage/box/comments/create` | Yes | Comment on a file, e.g. attach an alarm summary to the shift report. body: `{"message":"Press 7 stopped 14 min (bearing temperature 92 C)","item":{"type":"file","id":"<file id>"}}` (item type comment replies to a comment). |
| `TaskCreate` | API | `POST` | `/2.0/tasks` | `storage/box/tasks/create` | Yes | Ask for a review or completion of a file, e.g. QA sign-off of a batch record. body: `{"item":{"type":"file","id":"<file id>"},"action":"review","message":"Release batch 1005-A","due_at":"2026-10-06T12:00:00Z","completion_rule":"any_assignee"}` (assign people afterwards in Box or with task assignments, not packaged). |
| `WebhookCreate` | API | `POST` | `/2.0/webhooks` | `storage/box/webhooks/create` | Yes | Catalog 'POST webhooks'. Get a notification (V2 webhook) when files arrive in a folder. body: `{"target":{"id":"<inbox folder id>","type":"folder"},"address":"https://broker.example.com/box/webhooks","triggers":["FILE.UPLOADED","FILE.MOVED"]}`. address must be HTTPS on port 443; one webhook per target and app. Verify box-signature-primary / secondary with the app's signature keys on the receiver. |
| `WebhooksList` | API | `GET` | `/2.0/webhooks?{value.json.query}` | `storage/box/webhooks/list` | | Webhooks of this app for the user behind the token. query e.g. `limit=100` (then marker=`<next_marker>`), or empty. |
| `WebhookGet` | API | `GET` | `/2.0/webhooks/{value.json.webhook_id}` | `storage/box/webhooks/get` | | One webhook (target, address, triggers, created\_by). |
| `WebhookUpdate` | API | `PUT` | `/2.0/webhooks/{value.json.webhook_id}` | `storage/box/webhooks/update` | Yes | Change a webhook's address, target or triggers (e.g. move the receiver to a new broker). body: `{"address":"https://broker2.example.com/box/webhooks","triggers":["FILE.UPLOADED","FILE.MOVED","FILE.COPIED"]}`. |
| `EventsList` | API | `GET` | `/2.0/events?{value.json.query}` | `storage/box/events/list` | | User event stream without a public endpoint (polling alternative to webhooks). query: stream\_position=now first (returns next\_stream\_position only), then stream\_type=changes\&stream\_position=`<next_stream_position>`\&limit=100; store next\_stream\_position after every call. Events may repeat or arrive out of order: de-duplicate by event\_id. Enterprise admin\_logs needs an admin token. |
| `RecentItemsList` | API | `GET` | `/2.0/recent_items?{value.json.query}` | `storage/box/recent-items/list` | | Items the user accessed recently (last 90 days, at most 1000). query e.g. `fields=id,name,modified_at&limit=100` (or empty). |
| `TrashItemsList` | API | `GET` | `/2.0/folders/trash/items?{value.json.query}` | `storage/box/trash/items/list` | | Files and folders in the trash (e.g. find a recipe that someone deleted by mistake). query e.g. `fields=id,type,name,trashed_at,parent&limit=100` (or empty). |
| `FileTrashRestore` | API | `POST` | `/2.0/files/{value.json.file_id}` | `storage/box/files/trash/restore` | Yes | Restore a file from the trash (the inverse of a delete). body: `{}` to restore it in place, or `{"name":"recipe.json","parent":{"id":"<folder id>"}}` if the old folder is gone or the name is taken. |
| `FileUpload` | Upload | `POST` | `/api/2.0/files/content` | `storage/box/files/upload` | Yes | Catalog 'POST files/content'. Upload a new file (JSON record, CSV, text) from an MQTT payload; Box allows up to 50 MB in one request, keep MQTT payloads small. multipart: the whole multipart/form-data body with boundary CorefluxBoxBoundary: an attributes part `{"name":"2026-10-05-shift-A.json","parent":{"id":"<line-2 folder id>"}}` first, then a file part with the content (see the docs). 201 returns a collection with the new file (id, sha1, file\_version); 409 item\_name\_in\_use if the name exists (use FileVersionUpload). |
| `FileVersionUpload` | Upload | `POST` | `/api/2.0/files/{value.json.file_id}/content` | `storage/box/files/versions/upload` | Yes | Upload a new version of an existing file (e.g. today's setpoint table over yesterday's; older versions stay in FileVersionsList). multipart: same body as FileUpload; the attributes part carries the file name, e.g. `{"name":"setpoints.csv"}` (the spec marks name required; a different name renames the file). 201 returns the file with its new file\_version. |

## Limits

* Box allows about 1000 API requests per minute and 240 upload requests per minute per user, and 6 searches per second (60 per minute) per user. Above the limit it answers `429` with a `retry-after` header. Wait that long before you retry.
* Direct uploads accept files up to 50 MB. Larger files need chunked upload sessions, which are not packaged.
* `FolderItemsList` returns at most 1000 entries per page (use `usemarker=true` and `marker`), `Search` at most 200, `EventsList` at most 500.
* One webhook per item and app, at most 1000 webhooks per app and user, HTTPS on port 443 only.
* File versions are tracked on paid accounts only. Recent items cover the last 90 days or 1000 items.
* Box indexes new and changed files with a delay, so `Search` may not find a file that was just uploaded. `MetadataQuery` and `FolderItemsList` see it right away.

## Not packaged

* Delete events on purpose: files, folders, trash (permanent delete), file versions, metadata instances, shared link removal, collaborations, comments, tasks and webhooks. Archive files with `FileUpdate` or `FolderUpdate` (move) instead.
* Chunked upload sessions for files over 50 MB, the upload preflight check (`OPTIONS /2.0/files/content`), thumbnails, zip downloads and the long-poll real-time server (`OPTIONS /2.0/events`).
* The `As-User` header (act on behalf of another user from an admin token); request a user token with `box_subject_type=user` instead. The `If-Match` / `If-None-Match` headers and the `content-md5` upload header.
* Collaboration create and update (granting access), users and groups administration, legal holds, retention, Shield, Sign, Box AI, Hubs, Doc Gen and enterprise events (`admin_logs`).
* The webhook receiver. A receiver would be a separate `ENABLE_SERVER` REST\_API connector on a public HTTPS address that checks `BOX-SIGNATURE-PRIMARY` / `BOX-SIGNATURE-SECONDARY` (HMAC-SHA256 of the body plus `BOX-DELIVERY-TIMESTAMP` with the app's signature keys) and rejects old timestamps. `EventsList` covers the same need without a public endpoint.


# Box Upload
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/box-upload

LoT connector for Box uploads: send shift reports and batch records from MQTT to Box as new files or new file versions with an OAuth token

Technical Preview

## Overview

Client-mode REST API connectors for Box: upload shift reports, batch records and setpoint tables from MQTT as files or new versions, download recipes and configs, list, copy and move folders and files to archive, tag files with metadata and query by it, search, share with shared links, read collaborations, comment, open review tasks, register V2 webhooks and poll the event stream.

This is one of the templates in the Box REST API app (`box`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector). See [Box](/latest/lot-language/routes/rest-api-apps/box) for the package overview.

## Auth

* **schemes**: \["Authorization: Bearer \{value.json.access\_token} on every event except OAuthToken (OAuth 2.0 access token; about 60 minutes)", "OAuthToken: POST [https://api.box.com/oauth2/token](https://api.box.com/oauth2/token), application/x-www-form-urlencoded \{value.json.form} = grant\_type=client\_credentials\&client\_id=...\&client\_secret=...\&box\_subject\_type=enterprise|user\&box\_subject\_id=\<enterprise id|user id> (Client Credentials Grant, no refresh token) or grant\_type=urn:ietf:params:oauth:grant-type:jwt-bearer\&assertion=\<signed JWT>\&client\_id\&client\_secret (JWT apps), no Authorization header", "SharedItemGet additionally sends BoxApi: shared\_link=\{value.json.shared\_link}"]
* **secrets**: \["BOX\_ACCESS\_TOKEN", "BOX\_CLIENT\_ID", "BOX\_CLIENT\_SECRET", "BOX\_ENTERPRISE\_ID"]
* **scopes**: \["root\_readwrite (Read and write all files and folders)", "manage\_webhook (Manage webhooks)", "manage\_enterprise\_properties (only for enterprise metadata templates)"]
* **note**: Inject secrets with a LoT action (GET SECRET); never retain topics that carry the token or client secret; restrict storage/box/oauth/# with ACLs (the response carries the access token). The CCG service account has its own empty root: invite it ([AutomationUser\_...@boxdevedition.com](mailto:AutomationUser_...@boxdevedition.com), from UserMe) as Editor on the plant folders. App must be authorized in the Box Admin Console (automatic on free developer accounts) and reauthorized after scope changes.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Box Upload connector | no |
| `BaseUrl` | string | Box Upload base URL without trailing slash (e.g. [https://upload.box.com](https://upload.box.com)) | yes |

`BASE_ADDRESS` default: `https://upload.box.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `FileUpload` | POST | `/api/2.0/files/content` | `storage/box/files/upload` | `storage/box/files/upload/response` | `access_token`, `multipart` |
| `FileVersionUpload` | POST | `/api/2.0/files/{value.json.file_id}/content` | `storage/box/files/versions/upload` | `storage/box/files/versions/upload/response` | `access_token`, `file_id`, `multipart` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode BOX_UPLOAD"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BoxUploadRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://upload.box.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT FileUpload
        WITH SOURCE_TOPIC "storage/box/files/upload"
        WITH DESTINATION_TOPIC "storage/box/files/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2.0/files/content"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "multipart/form-data; boundary=CorefluxBoxBoundary"
        WITH BODY "{value.json.multipart}"
    ADD EVENT FileVersionUpload
        WITH SOURCE_TOPIC "storage/box/files/versions/upload"
        WITH DESTINATION_TOPIC "storage/box/files/versions/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2.0/files/{value.json.file_id}/content"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "multipart/form-data; boundary=CorefluxBoxBoundary"
        WITH BODY "{value.json.multipart}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `FileUpload` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'storage/box/files/upload/response' &
mosquitto_pub -t 'storage/box/files/upload' -m '{"access_token": "<access_token>", "multipart": "<multipart>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Canary Read
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/canary-read

LoT connector for the Canary Historian Views Read API: browse nodes and tags, read history, aggregates, live data, annotations and events

Technical Preview

## Overview

Client-mode REST API connectors for the Canary Historian: browse nodes and tags, read last values, raw history and aggregates, poll live data, annotations and events through the Views Read API, and write MQTT values into Canary through the Store and Forward Write API session (getSessionToken, storeData, keepAlive).

This is one of the templates in the Canary Historian REST API app (`canary-historian`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **token**: Identity API token as apiToken inside the JSON body (payload field body); sessionToken / liveDataToken / userToken for session, live data and Windows-account calls
* **windows**: Read API GetUserToken over https with username/password of a Windows account mapped to a Canary user -> userToken (5 min idle expiry). Not available on the v24+ Write API.
* **secret**: \["CANARY\_API\_TOKEN"]
* **unauthenticated**: \["GetVersion"]
* **note**: No Authorization header is sent; the Read API would also accept 'Authorization: Bearer \<apiToken>' but the Write API documents only the body field, so both connectors use the body for consistency. Canary services typically use a self-signed certificate; the broker host must trust it.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Canary Read connector | no |
| `BaseUrl` | string | Canary Read base URL without trailing slash (e.g. https\://YOUR\_CANARY\_HOST:55236) | yes |

`BASE_ADDRESS` default: `https://YOUR_CANARY_HOST:55236`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetUserToken` | POST | `/api/v2/getUserToken` | `historian/canary/user-token/create` | `historian/canary/user-token/create/response` | `body` |
| `RevokeUserToken` | POST | `/api/v2/revokeUserToken` | `historian/canary/user-token/delete` | `historian/canary/user-token/delete/response` | `body` |
| `BrowseNodes` | POST | `/api/v2/browseNodes` | `historian/canary/node/list` | `historian/canary/node/list/response` | `body` |
| `BrowseTags` | POST | `/api/v2/browseTags` | `historian/canary/tag/list` | `historian/canary/tag/list/response` | `body` |
| `GetTagProperties` | POST | `/api/v2/getTagProperties` | `historian/canary/tag-property/get` | `historian/canary/tag-property/get/response` | `body` |
| `GetTagData` | POST | `/api/v2/getTagData` | `historian/canary/tag-data/get` | `historian/canary/tag-data/get/response` | `body` |
| `GetAggregates` | POST | `/api/v2/getAggregates` | `historian/canary/aggregate/list` | `historian/canary/aggregate/list/response` | `body` |
| `GetAnnotations` | POST | `/api/v2/getAnnotations` | `historian/canary/annotation/get` | `historian/canary/annotation/get/response` | `body` |
| `GetLiveDataToken` | POST | `/api/v2/getLiveDataToken` | `historian/canary/live-token/create` | `historian/canary/live-token/create/response` | `body` |
| `GetLiveData` | POST | `/api/v2/getLiveData` | `historian/canary/live-data/get` | `historian/canary/live-data/get/response` | `body` |
| `RevokeLiveDataToken` | POST | `/api/v2/revokeLiveDataToken` | `historian/canary/live-token/delete` | `historian/canary/live-token/delete/response` | `body` |
| `GetEvents` | POST | `/api/v2/getEvents` | `historian/canary/event/list` | `historian/canary/event/list/response` | `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode CANARY_READ"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CanaryRead WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CANARY_HOST:55236"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetUserToken
        WITH SOURCE_TOPIC "historian/canary/user-token/create"
        WITH DESTINATION_TOPIC "historian/canary/user-token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getUserToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RevokeUserToken
        WITH SOURCE_TOPIC "historian/canary/user-token/delete"
        WITH DESTINATION_TOPIC "historian/canary/user-token/delete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/revokeUserToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT BrowseNodes
        WITH SOURCE_TOPIC "historian/canary/node/list"
        WITH DESTINATION_TOPIC "historian/canary/node/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/browseNodes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT BrowseTags
        WITH SOURCE_TOPIC "historian/canary/tag/list"
        WITH DESTINATION_TOPIC "historian/canary/tag/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/browseTags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTagProperties
        WITH SOURCE_TOPIC "historian/canary/tag-property/get"
        WITH DESTINATION_TOPIC "historian/canary/tag-property/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getTagProperties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTagData
        WITH SOURCE_TOPIC "historian/canary/tag-data/get"
        WITH DESTINATION_TOPIC "historian/canary/tag-data/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getTagData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetAggregates
        WITH SOURCE_TOPIC "historian/canary/aggregate/list"
        WITH DESTINATION_TOPIC "historian/canary/aggregate/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getAggregates"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetAnnotations
        WITH SOURCE_TOPIC "historian/canary/annotation/get"
        WITH DESTINATION_TOPIC "historian/canary/annotation/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getAnnotations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetLiveDataToken
        WITH SOURCE_TOPIC "historian/canary/live-token/create"
        WITH DESTINATION_TOPIC "historian/canary/live-token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getLiveDataToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetLiveData
        WITH SOURCE_TOPIC "historian/canary/live-data/get"
        WITH DESTINATION_TOPIC "historian/canary/live-data/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getLiveData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RevokeLiveDataToken
        WITH SOURCE_TOPIC "historian/canary/live-token/delete"
        WITH DESTINATION_TOPIC "historian/canary/live-token/delete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/revokeLiveDataToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetEvents
        WITH SOURCE_TOPIC "historian/canary/event/list"
        WITH DESTINATION_TOPIC "historian/canary/event/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/getEvents"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetUserToken` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/canary/user-token/create/response' &
mosquitto_pub -t 'historian/canary/user-token/create' -m '{"body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Canary Write
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/canary-write

LoT connector for the Canary Store and Forward Write API: open a session, configure tags, store MQTT values and keep the session alive

Technical Preview

## Overview

Client-mode REST API connectors for the Canary Historian: browse nodes and tags, read last values, raw history and aggregates, poll live data, annotations and events through the Views Read API, and write MQTT values into Canary through the Store and Forward Write API session (getSessionToken, storeData, keepAlive).

This is one of the templates in the Canary Historian REST API app (`canary-historian`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **token**: Identity API token as apiToken inside the JSON body (payload field body); sessionToken / liveDataToken / userToken for session, live data and Windows-account calls
* **windows**: Read API GetUserToken over https with username/password of a Windows account mapped to a Canary user -> userToken (5 min idle expiry). Not available on the v24+ Write API.
* **secret**: \["CANARY\_API\_TOKEN"]
* **unauthenticated**: \["GetVersion"]
* **note**: No Authorization header is sent; the Read API would also accept 'Authorization: Bearer \<apiToken>' but the Write API documents only the body field, so both connectors use the body for consistency. Canary services typically use a self-signed certificate; the broker host must trust it.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Canary Write connector | no |
| `BaseUrl` | string | Canary Write base URL without trailing slash (e.g. https\://YOUR\_CANARY\_HOST:55293) | yes |

`BASE_ADDRESS` default: `https://YOUR_CANARY_HOST:55293`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetVersion` | POST | `/api/v1/version` | `historian/canary-write/version/get` | `historian/canary-write/version/get/response` | `body` |
| `GetDatasets` | POST | `/api/v1/getDatasets` | `historian/canary-write/dataset/list` | `historian/canary-write/dataset/list/response` | `body` |
| `GetSessionToken` | POST | `/api/v1/getSessionToken` | `historian/canary-write/session/create` | `historian/canary-write/session/create/response` | `body` |
| `UpdateSettings` | POST | `/api/v1/updateSettings` | `historian/canary-write/session/update` | `historian/canary-write/session/update/response` | `body` |
| `KeepAlive` | POST | `/api/v1/keepAlive` | `historian/canary-write/session/refresh` | `historian/canary-write/session/refresh/response` | `body` |
| `RevokeSessionToken` | POST | `/api/v1/revokeSessionToken` | `historian/canary-write/session/delete` | `historian/canary-write/session/delete/response` | `body` |
| `ConfigureTags` | POST | `/api/v1/configureTags` | `historian/canary-write/tag-config/update` | `historian/canary-write/tag-config/update/response` | `body` |
| `StoreData` | POST | `/api/v1/storeData` | `historian/canary-write/tag-data/store` | `historian/canary-write/tag-data/store/response` | `body` |
| `ManualEntryStoreData` | POST | `/api/v1/manualEntryStoreData` | `historian/canary-write/manual-entry/store` | `historian/canary-write/manual-entry/store/response` | `body` |
| `WriteNoData` | POST | `/api/v1/noData` | `historian/canary-write/no-data/create` | `historian/canary-write/no-data/create/response` | `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode CANARY_WRITE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CanaryWrite WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CANARY_HOST:55293"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetVersion
        WITH SOURCE_TOPIC "historian/canary-write/version/get"
        WITH DESTINATION_TOPIC "historian/canary-write/version/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/version"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDatasets
        WITH SOURCE_TOPIC "historian/canary-write/dataset/list"
        WITH DESTINATION_TOPIC "historian/canary-write/dataset/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/getDatasets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetSessionToken
        WITH SOURCE_TOPIC "historian/canary-write/session/create"
        WITH DESTINATION_TOPIC "historian/canary-write/session/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/getSessionToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateSettings
        WITH SOURCE_TOPIC "historian/canary-write/session/update"
        WITH DESTINATION_TOPIC "historian/canary-write/session/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/updateSettings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT KeepAlive
        WITH SOURCE_TOPIC "historian/canary-write/session/refresh"
        WITH DESTINATION_TOPIC "historian/canary-write/session/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/keepAlive"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RevokeSessionToken
        WITH SOURCE_TOPIC "historian/canary-write/session/delete"
        WITH DESTINATION_TOPIC "historian/canary-write/session/delete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/revokeSessionToken"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConfigureTags
        WITH SOURCE_TOPIC "historian/canary-write/tag-config/update"
        WITH DESTINATION_TOPIC "historian/canary-write/tag-config/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/configureTags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT StoreData
        WITH SOURCE_TOPIC "historian/canary-write/tag-data/store"
        WITH DESTINATION_TOPIC "historian/canary-write/tag-data/store/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/storeData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ManualEntryStoreData
        WITH SOURCE_TOPIC "historian/canary-write/manual-entry/store"
        WITH DESTINATION_TOPIC "historian/canary-write/manual-entry/store/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/manualEntryStoreData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT WriteNoData
        WITH SOURCE_TOPIC "historian/canary-write/no-data/create"
        WITH DESTINATION_TOPIC "historian/canary-write/no-data/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/noData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetVersion` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/canary-write/version/get/response' &
mosquitto_pub -t 'historian/canary-write/version/get' -m '{"body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# ChirpStack v4
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/chirpstack-v4

Client-mode REST API connector for a curated ChirpStack v4 slice via chirpstack-rest-api: list/get devices, enqueue/get downlink queue, and get application

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [ChirpStack v4](https://www.chirpstack.io/docs/chirpstack/api/rest.html) covering these connector events. ChirpStack v4 does **not** ship a built-in REST API — use [chirpstack-rest-api](https://github.com/chirpstack/chirpstack-rest-api) (gRPC gateway), typically on port **8090**.

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET devices by application | `GET /api/devices?applicationId=` | DeviceService.List |
| POST device queue (downlink) | `POST /api/devices/{devEui}/queue` | DeviceService.Enqueue |
| (get device) | `GET /api/devices/{devEui}` | DeviceService.Get |
| (get queue) | `GET /api/devices/{devEui}/queue` | DeviceService.GetQueue |
| (get application) | `GET /api/applications/{applicationId}` | ApplicationService.Get |
| HTTP integration `event=up` | inbound webhook | **Companion Server connector** — not in this client template |

Default `BASE_ADDRESS` is `https://localhost:8090` (no trailing slash; substitute `https://{host}:8090`). Topics use `cloud-iot/chirpstack-v4/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth header:** Pass the full `Authorization` value via MQTT JSON field `authorization` as `Bearer {api_token}` (ChirpStack API key / JWT). Prefer Hub secrets (`CHIRPSTACK_AUTH`). Never commit real credentials. Some deployments also accept `Grpc-Metadata-Authorization: Bearer …`. See the [REST API notes](https://www.chirpstack.io/docs/chirpstack/api/rest.html) and [API reference](https://www.chirpstack.io/docs/chirpstack/api/api.html).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — ChirpStack v4 curated slice
# Auth: Authorization via {value.json.authorization} (Bearer API token)
# BASE_ADDRESS: https://localhost:8090  → substitute host / TLS

DEFINE CONNECTOR ChirpStackV4RestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://localhost:8090"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "cloud-iot/chirpstack-v4/device/list"
        WITH DESTINATION_TOPIC "cloud-iot/chirpstack-v4/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices?applicationId={value.json.applicationId}&limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "cloud-iot/chirpstack-v4/device/get"
        WITH DESTINATION_TOPIC "cloud-iot/chirpstack-v4/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices/{value.json.devEui}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT EnqueueDeviceQueue
        WITH SOURCE_TOPIC "cloud-iot/chirpstack-v4/device/queue/enqueue"
        WITH DESTINATION_TOPIC "cloud-iot/chirpstack-v4/device/queue/enqueue/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/devices/{value.json.devEui}/queue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT GetDeviceQueue
        WITH SOURCE_TOPIC "cloud-iot/chirpstack-v4/device/queue/get"
        WITH DESTINATION_TOPIC "cloud-iot/chirpstack-v4/device/queue/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices/{value.json.devEui}/queue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetApplication
        WITH SOURCE_TOPIC "cloud-iot/chirpstack-v4/application/get"
        WITH DESTINATION_TOPIC "cloud-iot/chirpstack-v4/application/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/applications/{value.json.applicationId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

## MQTT topics

| Action | Source topic | Response topic |
| - | - | - |
| ListDevices | `cloud-iot/chirpstack-v4/device/list` | `…/device/list/response` |
| GetDevice | `cloud-iot/chirpstack-v4/device/get` | `…/device/get/response` |
| EnqueueDeviceQueue | `cloud-iot/chirpstack-v4/device/queue/enqueue` | `…/device/queue/enqueue/response` |
| GetDeviceQueue | `cloud-iot/chirpstack-v4/device/queue/get` | `…/device/queue/get/response` |
| GetApplication | `cloud-iot/chirpstack-v4/application/get` | `…/application/get/response` |

## References

* [ChirpStack REST API](https://www.chirpstack.io/docs/chirpstack/api/rest.html)
* [ChirpStack API / protobuf reference](https://www.chirpstack.io/docs/chirpstack/api/api.html)
* [chirpstack-rest-api (GitHub)](https://github.com/chirpstack/chirpstack-rest-api)
* [HTTP integration](https://www.chirpstack.io/docs/chirpstack/integrations/http.html)


# Clarify (Searis)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/clarify

Connect Coreflux LoT to Clarify by Searis to insert time series, save and publish signals, and read data frames through the JSON-RPC API

Technical Preview

## Overview

[Clarify](https://www.clarify.io/) by Searis is a cloud time-series tool where operators and engineers explore and annotate industrial data together. This connector lets the broker push readings from the unified namespace straight into Clarify signals and read rolled-up or calculated data back onto MQTT, without a separate collector.

The template has one client connector, **ClarifyApi** (`ClarifyRestApi.lot`) on `https://api.clarify.io`, with 8 events: the OAuth 2.0 token call, 3 writes and 4 reads. Nothing is deleted.

> [!NOTE]
>
> Clarify is a JSON-RPC 2.0 API, not a classic REST API. Every method is a `POST` to `/v1/rpc` with the method name in the body, and the `X-API-Version: 1.1` header selects the API version. Each event in this template sends the payload field `request` (the full JSON-RPC object) unchanged, so put the method that matches the topic in it. The events follow the public [Clarify API reference 1.1](https://docs.clarify.io/api/1.1/).

## Events

| Event | Topic | Clarify method | Kind | What it does |
| - | - | - | - | - |
| `GetAccessToken` | `historian/clarify/token/get` | `POST /v1/oauth/token` | Token | OAuth 2.0 client-credentials token (form body); reply access\_token, token\_type Bearer, expires\_in 86400. Token calls are rate limited, so reuse the token until it expires |
| `InsertData` | `historian/clarify/data/insert` | `integration.insert` | Write | insert time series into the integration's own signals (data frame: times\[] + series\{input key: values\[]}); unknown input keys create signals. 1 request/s |
| `SaveSignals` | `historian/clarify/signals/save` | `integration.saveSignals` | Write | create or update signal metadata (name, description, labels, engUnit, valueType, sampleInterval, gapDetection) by input key. 1 request/s |
| `SelectSignals` | `historian/clarify/signals/select` | `admin.selectSignals` | Read | List signals of an integration with a resource query (filter, limit up to 1000, skip, total); include item to side-load published items. Needs the admin namespace |
| `PublishSignals` | `historian/clarify/items/publish` | `admin.publishSignals` | Write | create or update items (the organisation-visible view in Clarify) from signal IDs, so new signals show up for users. Needs the admin namespace |
| `SelectItems` | `historian/clarify/items/select` | `clarify.selectItems` | Read | List published items organisation wide with a resource query (filter, limit up to 1000). Needs the clarify namespace |
| `DataFrame` | `historian/clarify/data-frame/query` | `clarify.dataFrame` | Read | Raw or rolled-up item data (count, min, max, sum, avg; state histograms for enums) for up to 50 items; 40-day window for raw data. 1 request/s |
| `Evaluate` | `historian/clarify/evaluate/run` | `clarify.evaluate` | Read | Server-side aggregation plus formulas over up to 50 items (for example hourly OEE-style ratios). 1 request/s |

Replies arrive on the same topic with `/response` appended.

## Authentication

> [!WARNING]
>
> Credentials of an integration can write data into Clarify, and with the admin or clarify namespace granted they can read organisation-wide data. Keep the client secret and passwords in Hub secrets with `GET SECRET`, keep the access token on an internal topic, and grant the integration only the namespaces it needs.

Create an integration in Clarify under **Admin panel**, then **Integrations**, and create credentials on its **Access control** tab. Clarify offers two kinds:

* **OAuth 2.0 client credentials (recommended):** publish `client_id` and `client_secret` from `clarify-credentials.json` to `historian/clarify/token/get`. The reply carries `access_token`, valid for about 24 hours (`expires_in` 86400). Send it as `Bearer <access_token>`. Token calls are rate limited, so reuse the token until it expires.
* **Basic Auth:** send `Basic <base64 of username:password>`. The user name is also the integration ID.

Every `/v1/rpc` event sends the payload field `authorization` as the `Authorization` header.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "client_id": "<clientId from clarify-credentials.json>",
  "client_secret": "<clientSecret from clarify-credentials.json>"
}
```

### Namespaces

`integration.insert` and `integration.saveSignals` work for every integration and only touch its own signals. `admin.selectSignals` and `admin.publishSignals` need the **admin** namespace, and `clarify.selectItems`, `clarify.dataFrame` and `clarify.evaluate` need the **clarify** namespace. Grant them on the integration in the Clarify admin panel.

## Payload conventions

* `request` is the JSON-RPC 2.0 object: `jsonrpc` `"2.0"`, `method`, `id` and `params`. Set `id` (for example `"1"`) to get a reply; without it Clarify treats the call as a notification and answers `204` with no body.
* `integration` in `params` is the integration ID from the credentials file.
* `InsertData` takes a data frame: `times` is a list of RFC 3339 timestamps and `series` maps each signal input key to a list of values of the same length (`null` for gaps). An unknown input key creates a new signal.
* Resource queries (`query`) use Clarify's filter syntax, for example `{"labels.line": {"$in": ["line1"]}}`, plus `limit`, `skip` and `total`.
* Data queries (`data`) take `filter.times` with `$gte` / `$lt` and an ISO 8601 `rollup` such as `PT1H` or `P1D`.

Insert two readings:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "<Bearer access_token from GetAccessToken, or Basic base64(username:password) from Basic Auth credentials>",
  "request": {
    "jsonrpc": "2.0",
    "method": "integration.insert",
    "id": "1",
    "params": {
      "integration": "<YOUR_INTEGRATION_ID>",
      "data": {
        "times": [
          "2026-10-06T06:00:00Z",
          "2026-10-06T06:01:00Z"
        ],
        "series": {
          "porto/line1/press01/pressure": [
            101.3,
            101.7
          ],
          "porto/line1/press01/temperature": [
            61.2,
            null
          ]
        }
      }
    }
  }
}
```

Hourly rollup for the last day:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "<Bearer access_token from GetAccessToken, or Basic base64(username:password) from Basic Auth credentials>",
  "request": {
    "jsonrpc": "2.0",
    "method": "clarify.dataFrame",
    "id": "1",
    "params": {
      "query": {
        "filter": {
          "labels.line": {
            "$in": [
              "line1"
            ]
          }
        },
        "limit": 10
      },
      "data": {
        "filter": {
          "times": {
            "$gte": "2026-10-05T00:00:00Z",
            "$lt": "2026-10-06T00:00:00Z"
          }
        },
        "rollup": "PT1H"
      },
      "include": [
        "item"
      ]
    }
  }
}
```

> [!WARNING]
>
> Clarify answers HTTP `200` for JSON-RPC errors such as invalid params (`-32602`), forbidden (`-32003`, often a namespace that is not granted) or too many requests (`-32011`). Always check for an `error` object in the `/response` payload, not only the HTTP status.

## Limits

Clarify rate-limits each method: `integration.insert`, `integration.saveSignals`, `clarify.dataFrame` and `clarify.evaluate` allow 1 request per second, `admin.publishSignals` 5, and `admin.selectSignals` and `clarify.selectItems` 10. Requests are capped at about 8 MiB of JSON. Signals should average no more than one sample per minute (bursts up to one per second), so batch several readings into one `InsertData` call. `clarify.dataFrame` and `clarify.evaluate` read at most 50 items per call, and raw data (no rollup) is limited to a 40-day window.

## Connector

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Clarify (Searis) (beta): push MQTT readings into Clarify as time series, create and
#   update signal metadata, publish signals as items, list signals and items, and read raw, rolled-up or calculated
#   data frames back, over the Clarify JSON-RPC 2.0 API v1.1 (POST /v1/rpc), plus the OAuth 2.0 token call.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/clarify
#
# Auth: publish "authorization" as "Bearer <access_token>" (GetAccessToken with clientId / clientSecret from the
#   integration's credentials file, valid about 24 h) or "Basic <base64 username:password>" (Basic Auth credentials).
#   Keep credentials in Hub secrets (GET SECRET) and the token in an internal topic. Never commit them.
# Payloads: "request" is the complete JSON-RPC 2.0 object sent unchanged, {"jsonrpc": "2.0", "method": "<method>",
#   "id": "1", "params": {...}}. Use the method that matches the topic (InsertData -> integration.insert, ...).
#   Clarify answers HTTP 200 even for RPC errors: check "error" in the /response body. Without "id" Clarify returns
#   204 with no body (notification).
#     InsertData  {"authorization": "...", "request": {"jsonrpc": "2.0", "method": "integration.insert", "id": "1",
#                  "params": {"integration": "<id>", "data": {"times": ["2026-10-06T06:00:00Z"], "series": {"press01/pressure": [101.3]}}}}}
# Namespaces: integration.* works for every integration; admin.* and clarify.* need that namespace granted to the
#   integration in Clarify Admin panel -> Integrations. Rate limits: insert, saveSignals, dataFrame, evaluate 1 req/s.

DEFINE CONNECTOR ClarifyApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.clarify.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # OAuth 2.0 client-credentials token (form body); reply access_token, token_type Bearer, expires_in 86400. Token calls are rate limited, so reuse the token until it expires
    ADD EVENT GetAccessToken
        WITH SOURCE_TOPIC "historian/clarify/token/get"
        WITH DESTINATION_TOPIC "historian/clarify/token/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "grant_type=client_credentials&client_id={value.json.client_id}&client_secret={value.json.client_secret}&audience=https%3A%2F%2Fapi.clarify.io%2Fv1%2F"
    # WRITE: insert time series into the integration's own signals (data frame: times[] + series{input key: values[]}); unknown input keys create signals. 1 request/s
    ADD EVENT InsertData
        WITH SOURCE_TOPIC "historian/clarify/data/insert"
        WITH DESTINATION_TOPIC "historian/clarify/data/insert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-API-Version" "1.1"
        WITH BODY "{value.json.request}"
    # WRITE: create or update signal metadata (name, description, labels, engUnit, valueType, sampleInterval, gapDetection) by input key. 1 request/s
    ADD EVENT SaveSignals
        WITH SOURCE_TOPIC "historian/clarify/signals/save"
        WITH DESTINATION_TOPIC "historian/clarify/signals/save/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-API-Version" "1.1"
        WITH BODY "{value.json.request}"
    # List signals of an integration with a resource query (filter, limit up to 1000, skip, total); include item to side-load published items. Needs the admin namespace
    ADD EVENT SelectSignals
        WITH SOURCE_TOPIC "historian/clarify/signals/select"
        WITH DESTINATION_TOPIC "historian/clarify/signals/select/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-API-Version" "1.1"
        WITH BODY "{value.json.request}"
    # WRITE: create or update items (the organisation-visible view in Clarify) from signal IDs, so new signals show up for users. Needs the admin namespace
    ADD EVENT PublishSignals
        WITH SOURCE_TOPIC "historian/clarify/items/publish"
        WITH DESTINATION_TOPIC "historian/clarify/items/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-API-Version" "1.1"
        WITH BODY "{value.json.request}"
    # List published items organisation wide with a resource query (filter, limit up to 1000). Needs the clarify namespace
    ADD EVENT SelectItems
        WITH SOURCE_TOPIC "historian/clarify/items/select"
        WITH DESTINATION_TOPIC "historian/clarify/items/select/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-API-Version" "1.1"
        WITH BODY "{value.json.request}"
    # Raw or rolled-up item data (count, min, max, sum, avg; state histograms for enums) for up to 50 items; 40-day window for raw data. 1 request/s
    ADD EVENT DataFrame
        WITH SOURCE_TOPIC "historian/clarify/data-frame/query"
        WITH DESTINATION_TOPIC "historian/clarify/data-frame/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-API-Version" "1.1"
        WITH BODY "{value.json.request}"
    # Server-side aggregation plus formulas over up to 50 items (for example hourly OEE-style ratios). 1 request/s
    ADD EVENT Evaluate
        WITH SOURCE_TOPIC "historian/clarify/evaluate/run"
        WITH DESTINATION_TOPIC "historian/clarify/evaluate/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-API-Version" "1.1"
        WITH BODY "{value.json.request}"
```

## Example actions

These actions refresh the token twice a day, keep it on an internal topic, push a press pressure reading into Clarify, and request an hourly rollup.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ClarifyTokenRefresh
ON EVERY 12 HOURS DO
    SET "cid" WITH GET SECRET "CLARIFY_CLIENT_ID"
    SET "csecret" WITH GET SECRET "CLARIFY_CLIENT_SECRET"
    PUBLISH TOPIC "historian/clarify/token/get" WITH { "client_id": {cid}, "client_secret": {csecret} }

DEFINE ACTION ClarifyKeepToken
ON TOPIC "historian/clarify/token/get/response" DO
    SET "tok" WITH (GET JSON "access_token" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/clarify/authorization" WITH "Bearer " + {tok}

DEFINE ACTION ClarifyInsertPressure
ON TOPIC "porto/line1/press01/pressure" DO
    SET "auth" WITH GET TOPIC "internal/clarify/authorization" AS STRING
    SET "integ" WITH GET SECRET "CLARIFY_INTEGRATION_ID"
    SET "v" WITH PAYLOAD AS DOUBLE
    SET "ts" WITH TIMESTAMP "ISO"
    PUBLISH TOPIC "historian/clarify/data/insert" WITH { "authorization": {auth}, "request": { "jsonrpc": "2.0", "method": "integration.insert", "id": "1", "params": { "integration": {integ}, "data": { "times": [{ts}], "series": { "porto/line1/press01/pressure": [{v}] } } } } }

DEFINE ACTION ClarifyHourlyRollup
ON EVERY 1 HOUR DO
    SET "auth" WITH GET TOPIC "internal/clarify/authorization" AS STRING
    PUBLISH TOPIC "historian/clarify/data-frame/query" WITH { "authorization": {auth}, "request": { "jsonrpc": "2.0", "method": "clarify.dataFrame", "id": "1", "params": { "query": { "filter": { "labels.line": { "$in": ["line1"] } }, "limit": 10 }, "data": { "rollup": "PT1H" } } } }
```

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Clarify API reference](https://docs.clarify.io/api/1.1/)


# ClickHouse
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/clickhouse

Client-mode REST API connector for ClickHouse: async JSONEachRow inserts from MQTT, SQL over POST with JSON results, read-only GET queries, and /ping health

Technical Preview

## Overview

A client-mode connector for the [ClickHouse HTTP interface](https://clickhouse.com/docs/interfaces/http) that streams MQTT telemetry into ClickHouse tables and runs SQL from MQTT. It works with self-hosted ClickHouse and ClickHouse Cloud.

| Catalog connector event | Endpoint | Notes |
| - | - | - |
| POST insert (JSONEachRow) | `POST /?query=INSERT INTO {table} FORMAT JSONEachRow&async_insert=1&wait_for_async_insert=1` | The MQTT payload is the row. [Async inserts](https://clickhouse.com/docs/optimize/asynchronous-inserts) let the server batch many small writes. |
| POST SQL | `POST /?default_format=JSON` | Raw SQL in the body: `SELECT … FORMAT JSON`, `CREATE TABLE`, `INSERT … VALUES` |
| GET query | `GET /?query=&default_format=JSON` | Read-only SQL in the URL (ClickHouse treats every GET as read-only) |
| GET ping | `GET /ping` | Health check, `200 Ok.` |

Default `BASE_ADDRESS` is `https://YOUR_CLICKHOUSE_HOST:8443` (ClickHouse Cloud and TLS). For a self-hosted server on plain HTTP, use `http://YOUR_CLICKHOUSE_HOST:8123` and set `USE_SSL "false"`. Topics use `data/clickhouse/<object>/<verb>`.

> [!NOTE]
>
> **GET is read-only.** ClickHouse rejects `CREATE`, `INSERT`, or `DROP` sent with GET (`Cannot execute query in readonly mode`). Send those through the `ExecSql` event, which uses POST.

## Auth

The connector sends HTTP Basic auth from `WITH USERNAME` and `WITH PASSWORD` in `REST_API_CONFIG`. Store the password as a broker secret named `CLICKHOUSE_PASSWORD` and read it with `GET SECRET`; never commit it. ClickHouse Cloud users are usually `default` with the password shown when the service is created. ClickHouse also accepts the `X-ClickHouse-User` and `X-ClickHouse-Key` headers if you prefer them.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ClickhouseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CLICKHOUSE_HOST:8443"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        WITH USERNAME "default"
        WITH PASSWORD GET SECRET "CLICKHOUSE_PASSWORD"
    ADD EVENT Ping
        WITH SOURCE_TOPIC "data/clickhouse/ping"
        WITH DESTINATION_TOPIC "data/clickhouse/ping/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ping"
    ADD EVENT InsertJsonEachRow
        WITH SOURCE_TOPIC "data/clickhouse/rows/insert"
        WITH DESTINATION_TOPIC "data/clickhouse/rows/insert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/?query=INSERT%20INTO%20{value.json.table}%20FORMAT%20JSONEachRow&async_insert=1&wait_for_async_insert=1&input_format_skip_unknown_fields=1&date_time_input_format=best_effort"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT ExecSql
        WITH SOURCE_TOPIC "data/clickhouse/sql/exec"
        WITH DESTINATION_TOPIC "data/clickhouse/sql/exec/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/?default_format=JSON"
        WITH HEADERS
            ADD "Content-Type" "text/plain; charset=utf-8"
        WITH BODY "{payload}"
    ADD EVENT QueryJson
        WITH SOURCE_TOPIC "data/clickhouse/query/json"
        WITH DESTINATION_TOPIC "data/clickhouse/query/json/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/?query={value.json.query}&default_format=JSON"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Example MQTT payloads

**Insert a row (topic `data/clickhouse/rows/insert`).** The payload is the JSON row. The `table` field picks the target table and is skipped as a column because the endpoint sets `input_format_skip_unknown_fields=1`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "table": "sensor_readings", "ts": "2026-10-04 22:15:00.000", "site": "porto", "value": 21.5 }
```

Create the table first, for example through `ExecSql`:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CREATE TABLE IF NOT EXISTS sensor_readings (ts DateTime64(3), site String, value Float64) ENGINE = MergeTree ORDER BY ts
```

**Run SQL (topic `data/clickhouse/sql/exec`).** Publish the raw SQL text, not JSON:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SELECT site, avg(value) AS avg_value FROM sensor_readings GROUP BY site FORMAT JSON
```

The response topic receives ClickHouse's JSON, for example `{"meta":[…],"data":[{"site":"porto","avg_value":21.5}],"rows":1,…}`. DDL and `INSERT … VALUES` return an empty body with HTTP 200.

**Read-only query (topic `data/clickhouse/query/json`).** URL-encode the SQL before publishing:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "query": "SELECT%20count()%20FROM%20sensor_readings" }
```

**Health (topic `data/clickhouse/ping`)** takes any payload, such as `{}`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [QuestDB](/latest/lot-language/routes/rest-api-apps/questdb)
* [InfluxDB](/latest/lot-language/routes/rest-api-apps/influxdb)


# Cloud Firestore
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/cloud-firestore

LoT connector for Cloud Firestore: create, upsert, merge, get, list and query Firestore documents from MQTT with a Google OAuth2 token

Technical Preview

## Overview

Client-mode REST API connectors for Firebase: write device state, append events, and query history in the Realtime Database, and upsert, merge, and query Cloud Firestore documents from MQTT.

This is one of the templates in the Firebase Realtime Database and Cloud Firestore REST API app (`firebase-realtime-database-and-cloud-firestore`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector). See [Firebase Realtime Database and Cloud Firestore](/latest/lot-language/routes/rest-api-apps/firebase-realtime-database-and-cloud-firestore) for the package overview.

## Auth

Bearer \{value.json.access\_token} on both connectors. RTDB: Google OAuth2 SA token (userinfo.email + firebase.database); alt ?access\_token= or Firebase ID token via ?auth=. Firestore: Google OAuth2 SA token (roles/datastore.user) or Firebase ID token (rules apply). Hub secret FIREBASE\_ACCESS\_TOKEN.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Cloud Firestore connector | no |
| `BaseUrl` | string | Cloud Firestore base URL without trailing slash (e.g. [https://firestore.googleapis.com](https://firestore.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://firestore.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `UpsertDocument` | PATCH | `/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}` | `data/firebase/firestore/document/upsert` | `data/firebase/firestore/document/upsert/response` | `access_token`, `document`, `document_path`, `project_id` |
| `MergeFields` | PATCH | `/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}?{value.json.update_mask}` | `data/firebase/firestore/document/merge` | `data/firebase/firestore/document/merge/response` | `access_token`, `document`, `document_path`, `project_id`, `update_mask` |
| `CreateDocument` | POST | `/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.collection}` | `data/firebase/firestore/document/create` | `data/firebase/firestore/document/create/response` | `access_token`, `collection`, `document`, `project_id` |
| `GetDocument` | GET | `/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}` | `data/firebase/firestore/document/get` | `data/firebase/firestore/document/get/response` | `access_token`, `document_path`, `project_id` |
| `ListDocuments` | GET | `/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.collection}?pageSize={value.json.page_size}` | `data/firebase/firestore/documents/list` | `data/firebase/firestore/documents/list/response` | `access_token`, `collection`, `page_size`, `project_id` |
| `RunQuery` | POST | `/v1/projects/{value.json.project_id}/databases/(default)/documents:runQuery` | `data/firebase/firestore/documents/query` | `data/firebase/firestore/documents/query/response` | `access_token`, `project_id`, `query` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode CLOUD_FIRESTORE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CloudFirestoreRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://firestore.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT UpsertDocument
        WITH SOURCE_TOPIC "data/firebase/firestore/document/upsert"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/upsert/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.document}"
    ADD EVENT MergeFields
        WITH SOURCE_TOPIC "data/firebase/firestore/document/merge"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/merge/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}?{value.json.update_mask}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.document}"
    ADD EVENT CreateDocument
        WITH SOURCE_TOPIC "data/firebase/firestore/document/create"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.collection}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.document}"
    ADD EVENT GetDocument
        WITH SOURCE_TOPIC "data/firebase/firestore/document/get"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListDocuments
        WITH SOURCE_TOPIC "data/firebase/firestore/documents/list"
        WITH DESTINATION_TOPIC "data/firebase/firestore/documents/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.collection}?pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RunQuery
        WITH SOURCE_TOPIC "data/firebase/firestore/documents/query"
        WITH DESTINATION_TOPIC "data/firebase/firestore/documents/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents:runQuery"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.query}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `UpsertDocument` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'data/firebase/firestore/document/upsert/response' &
mosquitto_pub -t 'data/firebase/firestore/document/upsert' -m '{"access_token": "<access_token>", "document": "<document>", "document_path": "<document_path>", "project_id": "<project_id>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Coupa
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/coupa

Client-mode REST API connector for the Coupa Core API: OAuth token plus purchase orders and requisitions and invoices and suppliers and receipts

Technical Preview

## Overview

Client-mode REST API connector for the Coupa Core API: OAuth token plus purchase orders and requisitions and invoices and suppliers and receipts. `BASE_ADDRESS` defaults to `https://YOUR_INSTANCE.coupahost.com`. Topics use `erp/coupa/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `OAuthToken` | `POST /oauth2/token` | `erp/coupa/oauth/token/create` |
| `PurchaseOrdersList` | `GET /api/purchase_orders?{value.json.query}` | `erp/coupa/purchase-orders/list` |
| `PurchaseOrderGet` | `GET /api/purchase_orders/{value.json.id}` | `erp/coupa/purchase-orders/get` |
| `RequisitionsList` | `GET /api/requisitions?{value.json.query}` | `erp/coupa/requisitions/list` |
| `RequisitionCreate` | `POST /api/requisitions` | `erp/coupa/requisitions/create` |
| `InvoicesList` | `GET /api/invoices?{value.json.query}` | `erp/coupa/invoices/list` |
| `SuppliersList` | `GET /api/suppliers?{value.json.query}` | `erp/coupa/suppliers/list` |
| `ReceivingTransactionsList` | `GET /api/receiving_transactions?{value.json.query}` | `erp/coupa/receipts/list` |
| `ReceivingTransactionCreate` | `POST /api/receiving_transactions` | `erp/coupa/receipts/create` |

## Authentication

OAuth 2.0 / OIDC client credentials. OAuthToken posts the form grant\_type=client\_credentials\&client\_id=...\&client\_secret=...\&scope=core.purchase\_order.read ... to /oauth2/token; the access token (about 24 h) goes in Authorization: Bearer \{value.json.access\_token}. Scopes per resource (core.purchase\_order.read, core.invoice.read, core.supplier.read, core.requisition.write ...). Legacy X-COUPA-API-KEY is deprecated.

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* The OIDC client is created by a Coupa admin in the customer instance (Setup > Integrations > OAuth2/OpenID Connect Clients); no partner program is needed.
* OAuthToken is the only event whose body carries a credential (the token form), the same pattern as the Box OAuthToken event. Never retain erp/coupa/oauth/#.
* Use query filters such as updated-at\[gt]=2026-10-01\&limit=50 and return\_object=shallow to keep responses small.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CoupaRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.coupahost.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT OAuthToken
        WITH SOURCE_TOPIC "erp/coupa/oauth/token/create"
        WITH DESTINATION_TOPIC "erp/coupa/oauth/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth2/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    ADD EVENT PurchaseOrdersList
        WITH SOURCE_TOPIC "erp/coupa/purchase-orders/list"
        WITH DESTINATION_TOPIC "erp/coupa/purchase-orders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/purchase_orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT PurchaseOrderGet
        WITH SOURCE_TOPIC "erp/coupa/purchase-orders/get"
        WITH DESTINATION_TOPIC "erp/coupa/purchase-orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/purchase_orders/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RequisitionsList
        WITH SOURCE_TOPIC "erp/coupa/requisitions/list"
        WITH DESTINATION_TOPIC "erp/coupa/requisitions/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/requisitions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RequisitionCreate
        WITH SOURCE_TOPIC "erp/coupa/requisitions/create"
        WITH DESTINATION_TOPIC "erp/coupa/requisitions/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/requisitions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT InvoicesList
        WITH SOURCE_TOPIC "erp/coupa/invoices/list"
        WITH DESTINATION_TOPIC "erp/coupa/invoices/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/invoices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT SuppliersList
        WITH SOURCE_TOPIC "erp/coupa/suppliers/list"
        WITH DESTINATION_TOPIC "erp/coupa/suppliers/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/suppliers?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ReceivingTransactionsList
        WITH SOURCE_TOPIC "erp/coupa/receipts/list"
        WITH DESTINATION_TOPIC "erp/coupa/receipts/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/receiving_transactions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ReceivingTransactionCreate
        WITH SOURCE_TOPIC "erp/coupa/receipts/create"
        WITH DESTINATION_TOPIC "erp/coupa/receipts/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/receiving_transactions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
```

## Sources

* [https://docs.coupa.com/en/developer-documentation/the-coupa-core-api/oauth-2.0-and-oidc](https://docs.coupa.com/en/developer-documentation/the-coupa-core-api/oauth-2.0-and-oidc)
* [https://docs.coupa.com/en/developer-documentation/the-coupa-core-api/oauth-2.0-and-oidc/set-up-an-openid-connect-client](https://docs.coupa.com/en/developer-documentation/the-coupa-core-api/oauth-2.0-and-oidc/set-up-an-openid-connect-client)
* [https://docs.coupa.com/en/developer-documentation/the-coupa-core-api/resources/transactional-resources/purchase-orders-api-purchase\_orders](https://docs.coupa.com/en/developer-documentation/the-coupa-core-api/resources/transactional-resources/purchase-orders-api-purchase_orders)


# Critical Manufacturing MES
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/critical-manufacturing-mes

Connect Coreflux LoT to Critical Manufacturing MES to track materials in and out, hold and release, post data collection and read dispatch lists

Technical Preview

## Overview

[Critical Manufacturing MES](https://www.criticalmanufacturing.com/) (CM MES) runs material tracking, dispatch, resources, data collection and quality for complex discrete and semiconductor plants. Every MES service is exposed as REST on the MES host. This connector lets plant logic on MQTT track materials in and out, post machine readings and log machine state changes, without custom code.

**CriticalManufacturingMesApi** (`CriticalManufacturingMesRestApi.lot`) is one client connector on `https://YOUR_CMF_SERVER` with 37 events: 2 Security Portal token events, 17 reads and 18 writes. No event deletes, terminates or removes anything.

> [!NOTE]
>
> The events follow CM's public [REST API catalog](https://developer.criticalmanufacturing.com/11.2/reference/api-rest/index.html), which publishes one Swagger 2.0 file per service (for example `Material.swagger.json`), and the [Host API reference](https://developer.criticalmanufacturing.com/11.2/reference/api-host/index.html) for input and business objects. The catalog has 66 services and about 2,000 operations. This app packages the shop-floor slice. To add another operation, copy an event and change the endpoint to `/api/<Service>/<Operation>`.

## Server host

CM MES is installed per customer, on premises or hosted by CM. Replace `YOUR_CMF_SERVER` with the host of your MES UI, with no trailing slash. REST services live under `/api/<Service>/<Operation>`. The Security Portal is on the same host under `/SecurityPortal`. If your Security Portal runs on a different host, copy the two token events into a second connector on that host.

## Authentication

> [!WARNING]
>
> A Personal Access Token (PAT) acts as its MES user. Keep PATs and client secrets in Hub secrets, map them in with `GET SECRET`, and never publish them on a topic other clients can read.

CM MES uses the Security Portal (OAuth 2.0). Pick one of these:

1. **Personal Access Token.** In the MES UI, open your **User Profile** and create an access token for the Coreflux service user. Publish `{"tenant": "<TenantName>", "client_id": "MES", "pat": "<PAT>"}` on `mes/critical-manufacturing-mes/token/create`. The Security Portal validates the PAT with the `refresh_token` grant and returns a Bearer `access_token`. Use the Security Portal client ID set on your environment (`/Cmf/System/Configuration/SecurityPortal/ClientId/`, usually `MES`).
2. **Client credentials.** For application-to-application calls with no user, publish `{"tenant": "<TenantName>", "client_id": "<id>", "client_secret": "<secret>"}` on `mes/critical-manufacturing-mes/token-client/create`.

Then send `"authorization": "Bearer <access_token>"` in every other payload. Tokens expire, so request a new one on a timer (the example actions use 30 minutes).

A PAT does **not** work as a Bearer token. CM's community answer is to send it with Basic authentication instead, as `"authorization": "Basic <base64 of <PAT>:>"`, that is the PAT as user name with an empty password. That form comes from a community answer and has not been tested here. The token flow is the documented path.

`TenantName` is the tenant configured for your environment. Calls run with the MES roles and data groups of the PAT owner or client application.

Suggested secrets: `CMF_PAT` and `CMF_TENANT`, or `CMF_CLIENT_ID` and `CMF_CLIENT_SECRET`.

## Payload conventions

* **Body.** Almost every service is `POST`. `"body"` is sent unchanged as the operation's input object, with the PascalCase properties from the Swagger file, for example `ComplexTrackInMaterialInput` has `Material`, `Resource`, `CurrentDataCollectionPoints` and `SkipDCValidation`.
* **Entity references.** Reference materials, resources and other entities by `Name` (or `Id`) with a `"$type"`, for example `{"$type": "Cmf.Navigo.BusinessObjects.Material, Cmf.Navigo.BusinessObjects", "Name": "MAT-0001"}`. Resources use `Cmf.Navigo.BusinessObjects.Resource`, state models `Cmf.Foundation.BusinessObjects.StateModel, Cmf.Foundation.BusinessObjects`.
* **Readings.** A data collection point is `{"$type": "Cmf.Navigo.BusinessObjects.DataCollectionPoint, Cmf.Navigo.BusinessObjects", "TargetEntity": {"$type": "Cmf.Navigo.BusinessObjects.Parameter, Cmf.Navigo.BusinessObjects", "Name": "Temperature"}, "Value": 72.4, "ReadingNumber": 1, "SampleId": "Sample 1"}`.
* **Losses.** Loss lines are `LossBonusAffectedQuantity` objects with `Reason` and `ReasonPrimaryQuantity`. Hold lines are `MaterialHoldReason` objects with `TargetEntity` (the reason) and `Comment`.
* **Enums.** Enums are integers, for example `Direction` 0 Ascendant / 1 Descendant on `GetMaterialGenealogy`, and `ComplexPerformDataCollectionMode` 0 Material, 1 Resource, 2 first material in the resource, 3 all materials in the resource.
* **Query.** `GetObjectByName` and `GetObjectById` take `"query"` as the URL query string, for example `"query": "Type=Material&Name=MAT-0001&LevelsToLoad=1"`.
* **Token form.** The token body is form-encoded with raw substitution, so keep the tenant, client ID and secret free of `&` and `=`.

> [!NOTE]
>
> Two details are not shown in the public Swagger files: the exact `Type` value `GetObjectByName` expects (a short name such as `Material`, or the URL-encoded type name), and whether your host needs `"$type"` on every reference. The `"$type"` form matches CM's Connect IoT workflow samples. Check both against your MES before going live.

## Events

### Tokens and session

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetTokenFromPat | `POST /SecurityPortal/api/tenant/{tenant}/oauth2/token` | `mes/critical-manufacturing-mes/token/create` | Exchange a Personal Access Token (User Profile > Access Tokens) for a Bearer access\_token with the refresh\_token grant; calls run as the PAT owner |
| GetTokenClientCredentials | `POST /SecurityPortal/api/tenant/{tenant}/oauth2/token` | `mes/critical-manufacturing-mes/token-client/create` | OAuth 2.0 client credentials grant for application-to-application calls with no user (Client Id / Secret configured on the environment) |
| Echo | `GET /api/Security/Echo` | `mes/critical-manufacturing-mes/echo/get` | Security Echo: connectivity and token check (returns a string) |
| GetCurrentUser | `POST /api/Security/GetCurrentUser` | `mes/critical-manufacturing-mes/current-user/get` | The MES user behind the token (PAT owner or client application) |

### Generic objects and saved queries

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetObjectByName | `GET /api/GenericService/GetObjectByName?{query}` | `mes/critical-manufacturing-mes/object/get` | Any entity by type and name (query: Type, Name, Revision, Version, LevelsToLoad). The Type format is not shown in the spec: see caveats |
| GetObjectById | `GET /api/GenericService/GetObjectById?{query}` | `mes/critical-manufacturing-mes/object-id/get` | Any entity by type and Id (query: Type, Id, LevelsToLoad) |
| ExecuteQueryByName | `POST /api/Query/ExecuteQueryByName` | `mes/critical-manufacturing-mes/query/execute` | Run a saved MES query by name with parameters (read) |

### Materials, dispatch lists and production orders (read)

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetMaterialBasicInformation | `POST /api/Material/GetMaterialBasicInformation` | `mes/critical-manufacturing-mes/material/get` | Material state, step, flow, quantity, resource and container relations |
| GetMaterialHistory | `POST /api/Material/GetMaterialHistory` | `mes/critical-manufacturing-mes/material-history/get` | Material operation history (optional Filters) |
| GetMaterialGenealogy | `POST /api/Material/GetMaterialGenealogy` | `mes/critical-manufacturing-mes/material-genealogy/get` | Material genealogy; Direction 0 Ascendant, 1 Descendant (required), optional StartDate |
| GetDispatchListForResource | `POST /api/Dispatch/GetDispatchListForResource` | `mes/critical-manufacturing-mes/dispatch-list/get` | Materials dispatchable to a resource (the machine work queue) |
| GetMaterialsForProductionOrder | `POST /api/Order/GetMaterialsForProductionOrder` | `mes/critical-manufacturing-mes/production-order-materials/list` | Materials of a production order (optional MaterialNameFilter, FilterCollection) |

### Material transactions (write)

| Event | Request | Topic | Notes |
| - | - | - | - |
| DispatchMaterial | `POST /api/Material/DispatchMaterial` | `mes/critical-manufacturing-mes/material/dispatch` | **Write.** Dispatch a material to a resource |
| TrackInMaterial | `POST /api/Material/TrackInMaterial` | `mes/critical-manufacturing-mes/material/track-in` | **Write.** Track-In a material at a resource (simple transaction) |
| ComplexTrackInMaterial | `POST /api/Material/ComplexTrackInMaterial` | `mes/critical-manufacturing-mes/material-complex/track-in` | **Write.** Track-In with data collection points, checklist, recipe and instruments in one call (what the MES UI wizard uses) |
| ComplexDispatchAndTrackInMaterial | `POST /api/Material/ComplexDispatchAndTrackInMaterial` | `mes/critical-manufacturing-mes/material/dispatch-track-in` | **Write.** Dispatch and Track-In in one call |
| TrackOutMaterial | `POST /api/Material/TrackOutMaterial` | `mes/critical-manufacturing-mes/material/track-out` | **Write.** Track-Out a material (simple transaction) |
| ComplexTrackOutMaterial | `POST /api/Material/ComplexTrackOutMaterial` | `mes/critical-manufacturing-mes/material-complex/track-out` | **Write.** Track-Out with losses, bonuses, data collection points and checklist parameters |
| ComplexTrackOutAndMoveMaterialToNextStep | `POST /api/Material/ComplexTrackOutAndMoveMaterialToNextStep` | `mes/critical-manufacturing-mes/material/track-out-move` | **Write.** Track-Out and move to the next step (optional FlowPath) |
| MoveMaterialToNextStep | `POST /api/Material/MoveMaterialToNextStep` | `mes/critical-manufacturing-mes/material/move-next` | **Write.** Move-Next a material (optional FlowPath) |
| AbortMaterialProcess | `POST /api/Material/AbortMaterialProcess` | `mes/critical-manufacturing-mes/material/abort` | **Write.** Abort a tracked-in material process (back to queued; nothing is deleted) |
| HoldMaterial | `POST /api/Material/HoldMaterial` | `mes/critical-manufacturing-mes/material/hold` | **Write.** Put a material on hold with hold reasons |
| ReleaseMaterial | `POST /api/Material/ReleaseMaterial` | `mes/critical-manufacturing-mes/material/release` | **Write.** Release hold reasons from a material |
| RecordMaterialLoss | `POST /api/Material/RecordMaterialLoss` | `mes/critical-manufacturing-mes/material-loss/post` | **Write.** Record scrap / loss quantities with loss reasons |
| ChangeMaterialQuantity | `POST /api/Material/ChangeMaterialQuantity` | `mes/critical-manufacturing-mes/material-quantity/change` | **Write.** Change a material's primary / secondary quantity with a reason |
| LogMaterialEvent | `POST /api/Material/LogMaterialEvent` | `mes/critical-manufacturing-mes/material-event/post` | **Write.** Log a material state model transition |

### Resources (machines)

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetResourceByName | `POST /api/Resource/GetResourceByName` | `mes/critical-manufacturing-mes/resource/get` | One resource (machine / line / area equipment) by name |
| GetResourceMaterialInformation | `POST /api/Resource/GetResourceMaterialInformation` | `mes/critical-manufacturing-mes/resource-materials/get` | Materials in process / dispatched at a resource |
| GetResourcePossibleTransitions | `POST /api/Resource/GetResourcePossibleTransitions` | `mes/critical-manufacturing-mes/resource-transitions/get` | State transitions allowed from the resource's current state (names for LogResourceEvent) |
| GetResourceKPIs | `POST /api/Resource/GetResourceKPIs` | `mes/critical-manufacturing-mes/resource-kpi/get` | KPIs of a resource |
| LogResourceEvent | `POST /api/Resource/LogResourceEvent` | `mes/critical-manufacturing-mes/resource-event/post` | **Write.** Log a resource state transition (machine state change, for example Productive to Standby) |

### Data collection (EDC)

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetDataCollectionInstancesForMaterial | `POST /api/DataCollection/GetDataCollectionInstancesForMaterial` | `mes/critical-manufacturing-mes/dc-instance-material/list` | Open data collection instances of a material |
| GetDataCollectionInstancesForResource | `POST /api/DataCollection/GetDataCollectionInstancesForResource` | `mes/critical-manufacturing-mes/dc-instance-resource/list` | Open data collection instances of a resource |
| GetDataCollectionPointsAsDataSet | `POST /api/DataCollection/GetDataCollectionPointsAsDataSet` | `mes/critical-manufacturing-mes/dc-points/get` | Points already posted on a data collection instance |
| PostDataCollectionPoints | `POST /api/DataCollection/PostDataCollectionPoints` | `mes/critical-manufacturing-mes/dc-points/post` | **Write.** Post readings (parameter, value, reading number, sample) to an open data collection instance |
| ComplexPerformDataCollection | `POST /api/DataCollection/ComplexPerformDataCollection` | `mes/critical-manufacturing-mes/data-collection/post` | **Write.** Ad-hoc data collection in one call; ComplexPerformDataCollectionMode 0 Material, 1 Resource, 2 first material in resource, 3 all materials in resource |

### Production orders (write)

| Event | Request | Topic | Notes |
| - | - | - | - |
| ReleaseProductionOrders | `POST /api/Order/ReleaseProductionOrders` | `mes/critical-manufacturing-mes/production-order/release` | **Write.** Release production orders to the shop floor |

Every event replies on its topic plus `/response`.

## Example: connector excerpt

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CriticalManufacturingMesApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CMF_SERVER"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetTokenFromPat
        WITH SOURCE_TOPIC "mes/critical-manufacturing-mes/token/create"
        WITH DESTINATION_TOPIC "mes/critical-manufacturing-mes/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/SecurityPortal/api/tenant/{value.json.tenant}/oauth2/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "grant_type=refresh_token&client_id={value.json.client_id}&refresh_token={value.json.pat}"
    ADD EVENT ComplexTrackInMaterial
        WITH SOURCE_TOPIC "mes/critical-manufacturing-mes/material-complex/track-in"
        WITH DESTINATION_TOPIC "mes/critical-manufacturing-mes/material-complex/track-in/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/Material/ComplexTrackInMaterial"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
```

## Example: plant actions

These actions get a token every 30 minutes, keep it on an internal topic, track a material in and out when the press loads and finishes it, send the press temperature to an ad-hoc data collection, log machine state transitions and poll the dispatch list.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CmfMesLogin
ON EVERY 30 MINUTES DO
    SET "pat" WITH GET SECRET "CMF_PAT"
    SET "tenant" WITH GET SECRET "CMF_TENANT"
    PUBLISH TOPIC "mes/critical-manufacturing-mes/token/create" WITH { "tenant": {tenant}, "client_id": "MES", "pat": {pat} }

DEFINE ACTION CmfMesKeepToken
ON TOPIC "mes/critical-manufacturing-mes/token/create/response" DO
    SET "token" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "internal/critical-manufacturing-mes/authorization" WITH "Bearer " + {token}

DEFINE ACTION CmfMesTrackIn
ON TOPIC "porto/line1/press01/material-loaded" DO
    SET "auth" WITH GET TOPIC "internal/critical-manufacturing-mes/authorization" AS STRING
    SET "mat" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "mes/critical-manufacturing-mes/material-complex/track-in" WITH { "authorization": {auth}, "body": { "Material": { "$type": "Cmf.Navigo.BusinessObjects.Material, Cmf.Navigo.BusinessObjects", "Name": {mat} }, "Resource": { "$type": "Cmf.Navigo.BusinessObjects.Resource, Cmf.Navigo.BusinessObjects", "Name": "PRESS-01" } } }

DEFINE ACTION CmfMesTrackOut
ON TOPIC "porto/line1/press01/material-done" DO
    SET "auth" WITH GET TOPIC "internal/critical-manufacturing-mes/authorization" AS STRING
    SET "mat" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "mes/critical-manufacturing-mes/material-complex/track-out" WITH { "authorization": {auth}, "body": { "Material": { "$type": "Cmf.Navigo.BusinessObjects.Material, Cmf.Navigo.BusinessObjects", "Name": {mat} } } }

DEFINE ACTION CmfMesTemperatureToEdc
ON TOPIC "porto/line1/press01/temperature" DO
    SET "auth" WITH GET TOPIC "internal/critical-manufacturing-mes/authorization" AS STRING
    SET "temp" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "mes/critical-manufacturing-mes/data-collection/post" WITH { "authorization": {auth}, "body": { "DataCollection": { "$type": "Cmf.Navigo.BusinessObjects.DataCollection, Cmf.Navigo.BusinessObjects", "Name": "PRESS-01 Process" }, "ComplexPerformDataCollectionMode": 1, "Resource": { "$type": "Cmf.Navigo.BusinessObjects.Resource, Cmf.Navigo.BusinessObjects", "Name": "PRESS-01" }, "DataCollectionPointCollection": [ { "$type": "Cmf.Navigo.BusinessObjects.DataCollectionPoint, Cmf.Navigo.BusinessObjects", "TargetEntity": { "$type": "Cmf.Navigo.BusinessObjects.Parameter, Cmf.Navigo.BusinessObjects", "Name": "Temperature" }, "Value": {temp}, "ReadingNumber": 1, "SampleId": "Sample 1" } ] } }

DEFINE ACTION CmfMesMachineState
ON TOPIC "porto/line1/press01/state-transition" DO
    SET "auth" WITH GET TOPIC "internal/critical-manufacturing-mes/authorization" AS STRING
    SET "transition" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "mes/critical-manufacturing-mes/resource-event/post" WITH { "authorization": {auth}, "body": { "Resource": { "$type": "Cmf.Navigo.BusinessObjects.Resource, Cmf.Navigo.BusinessObjects", "Name": "PRESS-01" }, "StateModel": { "$type": "Cmf.Foundation.BusinessObjects.StateModel, Cmf.Foundation.BusinessObjects", "Name": "SEMI E10" }, "StateModelTransition": { "$type": "Cmf.Foundation.BusinessObjects.StateModelTransition, Cmf.Foundation.BusinessObjects", "Name": {transition} }, "Reason": "Machine signal" } }

DEFINE ACTION CmfMesDispatchPoll
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET TOPIC "internal/critical-manufacturing-mes/authorization" AS STRING
    PUBLISH TOPIC "mes/critical-manufacturing-mes/dispatch-list/get" WITH { "authorization": {auth}, "body": { "Resource": { "$type": "Cmf.Navigo.BusinessObjects.Resource, Cmf.Navigo.BusinessObjects", "Name": "PRESS-01" }, "LevelsToLoad": 1 } }
```

## Not packaged

* Every `Delete*`, `Remove*`, `Terminate*` and `Unterminate*` operation, by policy.
* Master data and configuration (`Create*`, `FullUpdate*`, `Update*` of products, flows, recipes, roles and data collections).
* `/api/Security/Login`. It is not in the public REST catalog; use the Security Portal token endpoint.
* Outbound webhooks. CM's public documentation lists no outbound webhook feature, so no receiver connector is packaged. Pushing MES events to MQTT is a job for Connect IoT or integration entries, configured inside MES.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app catalog](/latest/lot-language/routes/rest-api-apps/index)


# Cumulocity
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/cumulocity

Client-mode REST API connector for a curated Cumulocity IoT slice: measurements, alarms, inventory managed objects, events, and current-user check

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [Cumulocity IoT](https://cumulocity.com/api/core/) covering current-user connectivity and the POST events:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST measurement/measurements | `POST /measurement/measurements` | Telemetry / sensor readings |
| POST alarm/alarms | `POST /alarm/alarms` | Alarms (severity + status) |
| POST inventory/managedObjects | `POST /inventory/managedObjects` | Devices / assets |
| POST event/events | `POST /event/events` | Discrete device/app events |
| (auth helper) | `GET /user/currentUser` | Checks that you are signed in |

Default `BASE_ADDRESS` is `https://trial.cumulocity.com` (no trailing slash; substitute `{tenant}`). Topics use `cloud-iot/cumulocity/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth header:** Pass the full `Authorization` value via MQTT JSON field `authorization` — either `Basic <Base64(tenantID/username:password)>` or `Bearer {access_token}` (OAuth 2.0 / OAI-Secure / Cumulocity IdP). On the tenant host URL, the username may omit the `tenantID/` prefix. Prefer Hub secrets (`CUMULOCITY_AUTH`). Never commit real credentials.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Cumulocity IoT curated slice
# Auth: Authorization via {value.json.authorization} (Basic … or Bearer …)
# BASE_ADDRESS: https://trial.cumulocity.com  → substitute https://{tenant}.cumulocity.com

DEFINE CONNECTOR CumulocityRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://trial.cumulocity.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetCurrentUser
        WITH SOURCE_TOPIC "cloud-iot/cumulocity/user/current"
        WITH DESTINATION_TOPIC "cloud-iot/cumulocity/user/current/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/user/currentUser"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateMeasurement
        WITH SOURCE_TOPIC "cloud-iot/cumulocity/measurement/create"
        WITH DESTINATION_TOPIC "cloud-iot/cumulocity/measurement/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/measurement/measurements"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT CreateAlarm
        WITH SOURCE_TOPIC "cloud-iot/cumulocity/alarm/create"
        WITH DESTINATION_TOPIC "cloud-iot/cumulocity/alarm/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/alarm/alarms"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT CreateManagedObject
        WITH SOURCE_TOPIC "cloud-iot/cumulocity/inventory/create"
        WITH DESTINATION_TOPIC "cloud-iot/cumulocity/inventory/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/inventory/managedObjects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT CreateEvent
        WITH SOURCE_TOPIC "cloud-iot/cumulocity/event/create"
        WITH DESTINATION_TOPIC "cloud-iot/cumulocity/event/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/event/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
```

## Example MQTT payloads

**GetCurrentUser:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic dGVuYW50L3VzZXI6cGFzc3dvcmQ="
}
```

**CreateMeasurement:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic dGVuYW50L3VzZXI6cGFzc3dvcmQ=",
  "payload": "{\"source\":{\"id\":\"12345\"},\"time\":\"2026-10-04T08:00:00.000Z\",\"type\":\"c8y_TemperatureMeasurement\",\"c8y_TemperatureMeasurement\":{\"T\":{\"value\":21.5,\"unit\":\"C\"}}}"
}
```

**CreateAlarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer eyJhbGciOiJSUzI1NiJ9...",
  "payload": "{\"source\":{\"id\":\"12345\"},\"time\":\"2026-10-04T08:00:00.000Z\",\"type\":\"c8y_ThresholdAlarm\",\"text\":\"Temp high\",\"severity\":\"MAJOR\",\"status\":\"ACTIVE\"}"
}
```

**CreateManagedObject:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic dGVuYW50L3VzZXI6cGFzc3dvcmQ=",
  "payload": "{\"name\":\"Coreflux demo device\",\"type\":\"c8y_Device\",\"c8y_IsDevice\":{}}"
}
```

**CreateEvent:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic dGVuYW50L3VzZXI6cGFzc3dvcmQ=",
  "payload": "{\"source\":{\"id\":\"12345\"},\"time\":\"2026-10-04T08:00:00.000Z\",\"type\":\"c8y_LocationUpdate\",\"text\":\"Position update\"}"
}
```

## References

* [Cumulocity OpenAPI (core)](https://cumulocity.com/api/core/)
* [Device integration REST](https://cumulocity.com/docs/device-integration/device-integration-rest/)
* [Microservice REST](https://cumulocity.com/docs/microservice-sdk/rest/)
* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)


# Databricks
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/databricks

Connect Coreflux LoT to Databricks: run SQL on a warehouse, trigger job runs, poll status and land files in Unity Catalog volumes from MQTT

Technical Preview

## Overview

A client-mode connector for the [Databricks REST API](https://docs.databricks.com/api/workspace/) that writes MQTT data into the lakehouse and kicks off downstream pipelines:

| Catalog connector event | Endpoint | Notes |
| - | - | - |
| Run SQL (INSERT or SELECT) | `POST /api/2.0/sql/statements` | [Statement Execution API](https://docs.databricks.com/api/workspace/statementexecution/executestatement). Needs `warehouse_id`. Execution errors come back as `HTTP 200` with `status.state: FAILED`. |
| Poll a statement | `GET /api/2.0/sql/statements/{statement_id}` | Status, manifest and first result chunk. Use it after `PENDING` / `RUNNING`. |
| Next result chunk | `GET /api/2.0/sql/statements/{statement_id}/result/chunks/{chunk_index}` | Follow `next_chunk_index`. |
| Cancel a statement | `POST /api/2.0/sql/statements/{statement_id}/cancel` | Empty response; poll to see `CANCELED`. |
| Trigger a pipeline | `POST /api/2.2/jobs/run-now` | [Jobs run-now](https://docs.databricks.com/api/workspace/jobs/runnow): `job_id`, `job_parameters`, `idempotency_token`. Returns `run_id`. |
| Run status | `GET /api/2.2/jobs/runs/get?run_id=…` | `status.state` (`QUEUED`, `RUNNING`, `TERMINATED`, …) and `termination_details`. |
| Land a file in a volume | `PUT /api/2.0/fs/files/Volumes/…?overwrite=…` | [Files API](https://docs.databricks.com/api/workspace/files/upload) (Public Preview): raw bytes, up to 5 GiB, `204 No Content`. |
| Read a file / metadata | `GET` / `HEAD /api/2.0/fs/files/Volumes/…` | Bytes, or `content-length` + `last-modified` headers only. |
| List / create a directory | `GET` / `PUT /api/2.0/fs/directories/Volumes/…` | `contents[]` listing; create is `mkdir -p`. |
| Who am I / warehouses | `GET /api/2.0/preview/scim/v2/Me`, `GET /api/2.0/sql/warehouses` | Credential check and `warehouse_id` lookup. |

`BASE_ADDRESS` is your workspace URL, with no trailing slash. Replace `YOUR_WORKSPACE.cloud.databricks.com` with yours. Topics use `data/databricks/<object>/<verb>`, and replies go to `<topic>/response`.

| Cloud | Workspace URL shape |
| - | - |
| AWS | `https://dbc-xxxxxxxx-xxxx.cloud.databricks.com` (or a named `https://<name>.cloud.databricks.com`) |
| Azure | `https://adb-<workspace-id>.<n>.azuredatabricks.net` |
| GCP | `https://<workspace-id>.<n>.gcp.databricks.com` |

See [Get identifiers for workspace objects](https://docs.databricks.com/aws/en/workspace/workspace-details). One connector instance talks to one workspace.

> [!WARNING]
>
> **API versions differ by service.** SQL Statement Execution, Files, SCIM and Warehouses are under `/api/2.0`. Jobs uses `/api/2.2` (the `/api/2.1` paths still work, but 2.2 paginates the `tasks` array in `runs/get`). The catalog base URL `…/api/2.0/` is not a single prefix for every event, so each endpoint carries its own version.

## Auth

Every call sends `Authorization: Bearer …`. The template reads the token from the MQTT payload field `access_token`. Keep it in a Hub secret such as `GET SECRET "DATABRICKS_TOKEN"` and never commit it.

* **Personal access token (PAT):** a `dapi…` token from **Settings → Developer → Access tokens**. Use a dedicated service principal's token in production, not a person's. See [Databricks personal access tokens](https://docs.databricks.com/aws/en/dev-tools/auth/pat).
* **OAuth M2M (service principal):** mint an access token out of band with `POST https://<workspace>/oidc/v1/token`, `grant_type=client_credentials`, `scope=all-apis`, and the service principal's client id and secret. Tokens last about **1 hour**, so the publisher must refresh them. See [OAuth M2M](https://docs.databricks.com/aws/en/dev-tools/auth/oauth-m2m). On Azure, a Microsoft Entra ID token for the Azure Databricks resource also works.
* **Permissions:** `CAN USE` on the SQL warehouse, table privileges (`USE CATALOG`, `USE SCHEMA`, `SELECT`, `MODIFY`) for SQL, `CAN MANAGE RUN` on the job, and `READ VOLUME` / `WRITE VOLUME` on the Unity Catalog volume.

A `401` response with `Credential was not sent or was of an unsupported type for this API.` means the token is missing or malformed. `403` with `Invalid access token` means it was rejected or has expired.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DatabricksRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_WORKSPACE.cloud.databricks.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth (prefer Hub secrets / GET SECRET "DATABRICKS_TOKEN"):
        #   PAT or OAuth access_token on each MQTT payload → Bearer header below (refresh OAuth before ~1 h expiry).
        #   Aliases: DATABRICKS_ACCESS_TOKEN, DATABRICKS_PAT.
        #   {"warehouse_id":"…","statement":"SELECT 1","wait_timeout":"30s"} → 200 + status.state SUCCEEDED.
        # REQUEST_TIMEOUT 60 s covers the 50 s max wait_timeout.
    ADD EVENT GetCurrentUser
        WITH SOURCE_TOPIC "data/databricks/user/me"
        WITH DESTINATION_TOPIC "data/databricks/user/me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2.0/preview/scim/v2/Me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListWarehouses
        WITH SOURCE_TOPIC "data/databricks/warehouses/list"
        WITH DESTINATION_TOPIC "data/databricks/warehouses/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2.0/sql/warehouses"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ExecuteStatement
        WITH SOURCE_TOPIC "data/databricks/statement/execute"
        WITH DESTINATION_TOPIC "data/databricks/statement/execute/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2.0/sql/statements"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetStatement
        WITH SOURCE_TOPIC "data/databricks/statement/get"
        WITH DESTINATION_TOPIC "data/databricks/statement/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2.0/sql/statements/{value.json.statement_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetStatementResultChunk
        WITH SOURCE_TOPIC "data/databricks/statement/chunk"
        WITH DESTINATION_TOPIC "data/databricks/statement/chunk/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2.0/sql/statements/{value.json.statement_id}/result/chunks/{value.json.chunk_index}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CancelStatement
        WITH SOURCE_TOPIC "data/databricks/statement/cancel"
        WITH DESTINATION_TOPIC "data/databricks/statement/cancel/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2.0/sql/statements/{value.json.statement_id}/cancel"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT RunJobNow
        WITH SOURCE_TOPIC "data/databricks/job/run-now"
        WITH DESTINATION_TOPIC "data/databricks/job/run-now/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2.2/jobs/run-now"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetJobRun
        WITH SOURCE_TOPIC "data/databricks/run/get"
        WITH DESTINATION_TOPIC "data/databricks/run/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2.2/jobs/runs/get?run_id={value.json.run_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UploadFile
        WITH SOURCE_TOPIC "data/databricks/file/upload"
        WITH DESTINATION_TOPIC "data/databricks/file/upload/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2.0/fs/files{value.json.file_path}?overwrite={value.json.overwrite}"
        WITH HEADERS
            ADD "Content-Type" "application/octet-stream"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.content}"
    ADD EVENT DownloadFile
        WITH SOURCE_TOPIC "data/databricks/file/download"
        WITH DESTINATION_TOPIC "data/databricks/file/download/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2.0/fs/files{value.json.file_path}"
        WITH HEADERS
            ADD "Accept" "application/octet-stream"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetFileMetadata
        WITH SOURCE_TOPIC "data/databricks/file/metadata"
        WITH DESTINATION_TOPIC "data/databricks/file/metadata/response"
        WITH METHOD "HEAD"
        WITH ENDPOINT "/api/2.0/fs/files{value.json.file_path}"
        WITH HEADERS
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListDirectory
        WITH SOURCE_TOPIC "data/databricks/directory/list"
        WITH DESTINATION_TOPIC "data/databricks/directory/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2.0/fs/directories{value.json.directory_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateDirectory
        WITH SOURCE_TOPIC "data/databricks/directory/create"
        WITH DESTINATION_TOPIC "data/databricks/directory/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2.0/fs/directories{value.json.directory_path}"
        WITH HEADERS
            ADD "Authorization" "Bearer {value.json.access_token}"
```

> [!NOTE]
>
> JSON request bodies come from `{value.json.body}`, not `{payload}`. The MQTT payload carries control fields (`access_token`, `statement_id`, `chunk_index`, `run_id`, `file_path`, `directory_path`, `overwrite`) next to a `body` object, and only `body` is sent to Databricks. `UploadFile` sends `{value.json.content}` as the raw file body with `Content-Type: application/octet-stream`.

## Example MQTT payloads

**Find a warehouse (topic `data/databricks/warehouses/list`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "access_token": "<from DATABRICKS_TOKEN>" }
```

Use the `id` of a `RUNNING` (or serverless, auto-starting) warehouse as `warehouse_id`.

**Insert telemetry with SQL (topic `data/databricks/statement/execute`).** Use named parameter markers instead of string-building SQL:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from DATABRICKS_TOKEN>",
  "body": {
    "warehouse_id": "abcdef0123456789",
    "catalog": "main",
    "schema": "iiot",
    "statement": "INSERT INTO telemetry (ts, site, temperature) VALUES (:ts, :site, :temperature)",
    "parameters": [
      { "name": "ts", "value": "2026-10-04T22:30:00Z", "type": "TIMESTAMP" },
      { "name": "site", "value": "porto" },
      { "name": "temperature", "value": "21.5", "type": "DOUBLE" }
    ],
    "wait_timeout": "30s"
  }
}
```

A finished insert returns `status.state: SUCCEEDED` with `num_affected_rows` / `num_inserted_rows` in `result.data_array`. One row per call is fine for low rates. For high-rate telemetry, batch rows into one multi-row `INSERT`, or land files with `UploadFile` and load them with `COPY INTO` or Auto Loader in a job.

**Query (same topic):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from DATABRICKS_TOKEN>",
  "body": {
    "warehouse_id": "abcdef0123456789",
    "statement": "SELECT site, avg(temperature) AS avg_t FROM main.iiot.telemetry WHERE ts > current_timestamp() - INTERVAL 1 HOUR GROUP BY site",
    "wait_timeout": "30s",
    "on_wait_timeout": "CONTINUE",
    "disposition": "INLINE",
    "format": "JSON_ARRAY"
  }
}
```

Rows come back in `result.data_array` as arrays of strings (`null` for NULL), with column names in `manifest.schema.columns`.

**Poll, page, or cancel (topics `data/databricks/statement/get`, `…/statement/chunk`, `…/statement/cancel`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "access_token": "<from DATABRICKS_TOKEN>", "statement_id": "01eda0e7-e315-1846-84e2-79a963ffad44", "chunk_index": 1, "body": {} }
```

`GetStatement` only needs `statement_id`, `GetStatementResultChunk` also needs `chunk_index`, and `CancelStatement` needs `"body": {}`.

**Trigger a pipeline when a batch completes (topic `data/databricks/job/run-now`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from DATABRICKS_TOKEN>",
  "body": {
    "job_id": 11223344,
    "job_parameters": { "batch_id": "porto-2026-10-04T22", "source": "coreflux" },
    "idempotency_token": "porto-2026-10-04T22"
  }
}
```

The response is `{"run_id": 455644833, "number_in_job": 455644833}`. Poll `data/databricks/run/get` with `{ "access_token": "…", "run_id": 455644833 }`.

**Land a batch file in a volume (topic `data/databricks/file/upload`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from DATABRICKS_TOKEN>",
  "file_path": "/Volumes/main/iiot/landing/porto/2026-10-04T22.csv",
  "overwrite": "true",
  "content": "ts,site,temperature\n2026-10-04T22:30:00Z,porto,21.5\n"
}
```

A successful upload returns `204` with an empty body. Check it with `data/databricks/file/metadata` (`HEAD`, `{ "access_token": "…", "file_path": "…" }`), or list the folder with `data/databricks/directory/list` (`directory_path`).

> [!TIP]
>
> `file_path` and `directory_path` must start with `/` (for example `/Volumes/<catalog>/<schema>/<volume>/…`). The template joins them straight onto `/api/2.0/fs/files` and `/api/2.0/fs/directories` with no extra slash. Always send `overwrite` (`"true"` or `"false"`), because the template puts it in the query string. With `"false"`, uploading to an existing path fails with `409`.

## Gotchas

* **`warehouse_id` is required** for every statement. SQL runs on a SQL warehouse (serverless or pro recommended), not on an all-purpose cluster. A stopped classic warehouse starts on the first statement, which can take minutes, so expect `PENDING`.
* **`wait_timeout`** is `"0s"` (asynchronous: returns `PENDING` and a `statement_id` straight away) or `"5s"` to `"50s"` (synchronous up to that limit; default `10s`). Any other value returns `400`. If the limit passes, `on_wait_timeout: CONTINUE` (default) keeps it running for you to poll, and `CANCEL` stops it. The connector's `REQUEST_TIMEOUT` is 60 s, which is above the 50 s maximum.
* **Check `status.state`, not just the HTTP code.** SQL errors such as syntax errors or missing tables come back as `HTTP 200` with `status.state: FAILED` and `status.error.message`. Statements stay readable for at least 12 hours after they finish, then `GetStatement` returns `404`.
* **`INLINE` vs `EXTERNAL_LINKS`:** `INLINE` supports `JSON_ARRAY` only, up to 25 MiB per result; larger results are aborted. `EXTERNAL_LINKS` (up to 100 GiB; `JSON_ARRAY`, `CSV` or `ARROW_STREAM`) returns short-lived presigned / SAS / signed URLs (≤ 15 minutes) that must be fetched **without** the `Authorization` header. That second fetch is outside this connector.
* **Parameters** use named markers (`:name`); positional `?` is not supported. Values are strings, with an optional `type`.
* **`idempotency_token`** (max 64 chars) on `run-now`: if a run with that token exists, Databricks returns the same `run_id` instead of starting a second run. Derive it from the batch id so MQTT redelivery doesn't trigger duplicate pipelines.
* **Files API body is raw bytes.** Databricks stores exactly what it receives. `{value.json.content}` suits text (CSV, JSON lines); it does **not** decode base64, so binary formats such as Parquet need a different path. Max 5 GiB per `PUT`. `overwrite` defaults to `true` on the Databricks side when omitted.
* **Files API is Public Preview** and works on Unity Catalog volumes (`/Volumes/…`), workspace files, and DBFS paths. The legacy DBFS API (`/api/2.0/dbfs/put`, base64 in 1 MB blocks) is not templated.
* Deletes (files, directories, jobs, warehouses), job create / reset / update, and `runs/submit` are left out on purpose.

## Rate limits

Databricks applies per-workspace rate limits per endpoint and returns `429` with `Retry-After` when you exceed them. Statement Execution and `jobs/run-now` are meant for moderate rates (batches, not one call per sensor sample). Back off on `429` and `503 TEMPORARILY_UNAVAILABLE`. See [Resource limits](https://docs.databricks.com/aws/en/resources/limits).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [Google BigQuery](/latest/lot-language/routes/rest-api-apps/google-bigquery)
* [Amazon S3](/latest/lot-language/routes/rest-api-apps/amazon-s3)
* [Azure Blob Storage and Data Lake Gen2](/latest/lot-language/routes/rest-api-apps/azure-blob-storage-and-data-lake-gen2)


# Datacake
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/datacake

Connect Coreflux LoT to Datacake: read devices and measurements, record values, send downlinks via GraphQL and REST, plus an opt-in webhook receiver

Technical Preview

## Overview

[Datacake](https://datacake.co) is a low-code IoT platform for LoRaWAN, cellular, MQTT and HTTP devices, with dashboards, a rule engine and white-label portals. These connectors connect the Coreflux broker to the Datacake API, so plant logic can read sensor values, push broker data into Datacake devices, change set points and thresholds, and trigger downlinks over MQTT.

* **DatacakeApi** (`DatacakeRestApi.lot`) is a client connector on `https://api.datacake.co` with 23 events: 21 on the [GraphQL API](https://docs.datacake.de/api/graphql-api) and 2 REST endpoints ([record measurements](https://docs.datacake.de/api/record-measurements-via-api) and the product [HTTP ingest URL](https://docs.datacake.de/integrations/webhook)).
* **DatacakeWebhookReceiver** (`cloud-iot_datacake_webhook.lot`, opt-in, server mode) receives Datacake [outgoing webhooks](https://docs.datacake.de/integrations/outgoing-webhooks) and Rule Engine webhook actions, so new measurements, downlinks and alerts reach MQTT without polling.

Datacake publishes no OpenAPI definition. The GraphQL events were checked against the live schema (introspection of `https://api.datacake.co/graphql/`), and every preset query below was validated by the live API.

## Authentication

> [!WARNING]
>
> A personal Datacake token carries every right you have in every workspace you belong to. Prefer an API User token scoped to the workspace and devices this connector needs, keep it in a Hub secret, map it in with `GET SECRET`, and never publish it on a topic other clients can read.

| Token | Where to find it |
| - | - |
| API User token (recommended) | **Members → API Users → Add API User**, then pick workspace permissions and device permissions. |
| Personal token | **Account Settings → API Token**. |

Every event except `IngestProductWebhook` takes `"api_token"` in its MQTT payload and sends `Authorization: Token <api_token>`. Store the token as the secret `DATACAKE_API_TOKEN`.

An invalid token returns `401` with an empty body. A request without a token is treated as anonymous: reads return empty lists or `null`, and writes return `ok: false`.

`IngestProductWebhook` sends no `Authorization` header. The product key in the URL is the credential, so treat it like a secret.

## Payload conventions

* GraphQL events POST `"body"` to `/graphql/` unchanged. The body is `{"query": "...", "variables": {...}}`. The named events are topic presets on the same endpoint, so the query you send decides what comes back. Use the preset queries below as a starting point.
* Validation errors come back as `400` with an `errors` array. Permission problems and unknown ids come back as `200` with `null` data or `ok: false`.
* `RecordMeasurements` takes `"device_id"` (the device UUID shown in the portal URL) and a JSON array body.
* `IngestProductWebhook` takes `"product_key"`, `"path"` (`""` or a custom sub-path ending in `/`, for example `"status/"`) and any JSON body for the product's payload decoder.

## Account and workspaces

| Event | Topic | Notes |
| - | - | - |
| GraphqlQuery | `cloud-iot/datacake/graphql/query` | Any read query from the Datacake GraphQL schema; body \{"query": "...", "variables": \{...}} |
| GraphqlMutation | `cloud-iot/datacake/graphql/mutate` | Any mutation from the schema (266 in Mutations); restrict who may publish here **(write)** |
| GetUser | `cloud-iot/datacake/user/get` | Credential check: the token's user; data.user is null when the token is not accepted |
| ListWorkspaces | `cloud-iot/datacake/workspace/list` | Workspaces the token can see (workspace id = inWorkspace for ListDevices) |

**GraphqlMutation** (`cloud-iot/datacake/graphql/mutate`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($input: SetValueInputType!) { setValue(input: $input) { ok } }",
  "variables": {
    "input": {
      "deviceId": "00000000-0000-0000-0000-000000000000",
      "fieldName": "SETPOINT",
      "value": {
        "valueFloat": 21.5
      }
    }
  }
}
```

**GetUser** (`cloud-iot/datacake/user/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query { user { id email fullName isApiuser } }"
}
```

**ListWorkspaces** (`cloud-iot/datacake/workspace/list`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query { allWorkspaces { id name slug } }"
}
```

## Devices

| Event | Topic | Notes |
| - | - | - |
| ListDevices | `cloud-iot/datacake/device/list` | Catalog: devices in a workspace (filters inWorkspace, searchTag, searchName, online) |
| GetDevice | `cloud-iot/datacake/device/get` | One device by id |
| CreateApiDevices | `cloud-iot/datacake/device/create` | Create API (HTTP) devices in a new or existing product; may bill the workspace, needs device-creation rights **(write)** |
| UpdateDevice | `cloud-iot/datacake/device/update` | Rename a device, set tags, location or metadata **(write)** |

**ListDevices** (`cloud-iot/datacake/device/list`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query($workspace: String, $tag: String) { allDevices(inWorkspace: $workspace, searchTag: $tag) { id serialNumber verboseName online lastHeard tags product { id name } } }",
  "variables": {
    "workspace": "00000000-0000-0000-0000-000000000000",
    "tag": null
  }
}
```

**GetDevice** (`cloud-iot/datacake/device/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query($id: String) { device(deviceId: $id) { id serialNumber verboseName online lastHeard location tags metadata product { id name } } }",
  "variables": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}
```

**CreateApiDevices** (`cloud-iot/datacake/device/create`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($input: CreateApiDevicesInputType!) { createApiDevices(input: $input) { ok devices { id serialNumber verboseName } } }",
  "variables": {
    "input": {
      "workspace": "00000000-0000-0000-0000-000000000000",
      "plan": "free",
      "productKind": "EXISTING",
      "existingProduct": "00000000-0000-0000-0000-000000000000",
      "devices": [
        {
          "name": "Line 1 sensor",
          "serial": "LINE1-001"
        }
      ]
    }
  }
}
```

**UpdateDevice** (`cloud-iot/datacake/device/update`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($id: String!, $input: UpdateDeviceInputType) { updateDevice(deviceId: $id, input: $input) { ok device { id verboseName tags location } } }",
  "variables": {
    "id": "00000000-0000-0000-0000-000000000000",
    "input": {
      "verboseName": "Line 1 sensor",
      "tags": [
        "porto",
        "line-1"
      ]
    }
  }
}
```

## Measurements

| Event | Topic | Notes |
| - | - | - |
| GetCurrentMeasurements | `cloud-iot/datacake/measurement-current/get` | Latest value of every active field on a device |
| GetDeviceHistory | `cloud-iot/datacake/measurement-history/get` | Historical data; resolution raw or 30s / 20m / 2h / 1d / 1w (raw max 31 days, max 1024 buckets) |

**GetCurrentMeasurements** (`cloud-iot/datacake/measurement-current/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query($id: String) { device(deviceId: $id) { id verboseName currentMeasurements(allActiveFields: true) { value valueString modified field { fieldName verboseFieldName unit } } } }",
  "variables": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}
```

**GetDeviceHistory** (`cloud-iot/datacake/measurement-history/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query($id: String, $fields: [String], $start: String!, $end: String!, $res: String) { device(deviceId: $id) { id history(fields: $fields, timerangestart: $start, timerangeend: $end, resolution: $res) } }",
  "variables": {
    "id": "00000000-0000-0000-0000-000000000000",
    "fields": [
      "TEMPERATURE"
    ],
    "start": "2026-10-05T00:00:00Z",
    "end": "2026-10-06T00:00:00Z",
    "res": "30m"
  }
}
```

## Products

| Event | Topic | Notes |
| - | - | - |
| ListProducts | `cloud-iot/datacake/product/list` | Products (device templates: fields, decoder, dashboard) |
| GetProduct | `cloud-iot/datacake/product/get` | One product with its database fields |

**ListProducts** (`cloud-iot/datacake/product/list`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query { allProducts { id name slug deviceCount } }"
}
```

**GetProduct** (`cloud-iot/datacake/product/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query($id: String!) { product(id: $id) { id name slug measurementFields { fieldName verboseFieldName fieldType unit } } }",
  "variables": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}
```

## Values, configuration and downlinks

| Event | Topic | Notes |
| - | - | - |
| SetValue | `cloud-iot/datacake/field-value/set` | Write a value into a device field (manual input / set value widget) **(write)** |
| SetDeviceConfigurationValue | `cloud-iot/datacake/config-value/set` | Override a configuration field (per-device threshold) or resetToDefault **(write)** |
| SendDownlink | `cloud-iot/datacake/downlink/send` | Queue a configured LoRaWAN downlink (downlink id from the product) to a device **(write)** |
| SendApiDownlink | `cloud-iot/datacake/api-downlink/send` | Trigger a configured HTTP downlink on an API device **(write)** |
| SendMqttDownlink | `cloud-iot/datacake/mqtt-downlink/send` | Trigger a configured MQTT downlink on an MQTT device **(write)** |

**SetValue** (`cloud-iot/datacake/field-value/set`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($input: SetValueInputType!) { setValue(input: $input) { ok } }",
  "variables": {
    "input": {
      "deviceId": "00000000-0000-0000-0000-000000000000",
      "fieldName": "SETPOINT",
      "value": {
        "valueFloat": 21.5
      }
    }
  }
}
```

**SetDeviceConfigurationValue** (`cloud-iot/datacake/config-value/set`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($input: SetDeviceConfigurationValueInputType!) { setDeviceConfigurationValue(input: $input) { ok } }",
  "variables": {
    "input": {
      "device": "00000000-0000-0000-0000-000000000000",
      "field": "MAX_TEMP",
      "valueNumber": 8.0
    }
  }
}
```

**SendDownlink** (`cloud-iot/datacake/downlink/send`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($device: String!, $downlink: String!) { sendDownlink(device: $device, downlink: $downlink) { ok } }",
  "variables": {
    "device": "00000000-0000-0000-0000-000000000000",
    "downlink": "00000000-0000-0000-0000-000000000000"
  }
}
```

**SendApiDownlink** (`cloud-iot/datacake/api-downlink/send`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($device: String!, $downlink: String!) { sendApiDownlink(device: $device, downlink: $downlink) { ok } }",
  "variables": {
    "device": "00000000-0000-0000-0000-000000000000",
    "downlink": "00000000-0000-0000-0000-000000000000"
  }
}
```

**SendMqttDownlink** (`cloud-iot/datacake/mqtt-downlink/send`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($device: String!, $downlink: String!) { sendMqttDownlink(device: $device, downlink: $downlink) { ok } }",
  "variables": {
    "device": "00000000-0000-0000-0000-000000000000",
    "downlink": "00000000-0000-0000-0000-000000000000"
  }
}
```

## Outgoing webhooks and exports

| Event | Topic | Notes |
| - | - | - |
| CreateWebhook | `cloud-iot/datacake/webhook/create` | Create an outgoing webhook that pushes events to the receiver connector **(write)** |
| UpdateWebhook | `cloud-iot/datacake/webhook/update` | Update or pause an outgoing webhook **(write)** |
| ListWebhookLogs | `cloud-iot/datacake/webhook-log/list` | Recent deliveries of an outgoing webhook |
| CreateManualExport | `cloud-iot/datacake/export/create` | Start a CSV / Excel export of workspace data, delivered by email **(write)** |

**CreateWebhook** (`cloud-iot/datacake/webhook/create`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($input: CreateWebhookInputType!) { createWebhook(input: $input) { ok webhook { id endpointUrl } } }",
  "variables": {
    "input": {
      "workspace": "00000000-0000-0000-0000-000000000000",
      "endpointUrl": "https://broker.example.com/datacake/webhook/measurements",
      "description": "Coreflux",
      "eventsToSend": [
        "device_measurement"
      ],
      "requestHeaders": [
        {
          "key": "Authorization",
          "value": "Bearer <shared secret>"
        }
      ]
    }
  }
}
```

**UpdateWebhook** (`cloud-iot/datacake/webhook/update`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($input: UpdateWebhookInputType!) { updateWebhook(input: $input) { ok webhook { id endpointUrl } } }",
  "variables": {
    "input": {
      "workspace": "00000000-0000-0000-0000-000000000000",
      "id": "00000000-0000-0000-0000-000000000000",
      "description": "Coreflux (line 1)"
    }
  }
}
```

**ListWebhookLogs** (`cloud-iot/datacake/webhook-log/list`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "query($id: String!) { webhookLogs(webhookId: $id) { datetime request } }",
  "variables": {
    "id": "00000000-0000-0000-0000-000000000000"
  }
}
```

**CreateManualExport** (`cloud-iot/datacake/export/create`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "mutation($input: CreateManualExportInputType!) { createManualExport(input: $input) { ok errors } }",
  "variables": {
    "input": {
      "workspaceId": "00000000-0000-0000-0000-000000000000",
      "name": "Line 1 week",
      "exportFrom": "2026-09-28T00:00:00Z",
      "exportUntil": "2026-10-05T00:00:00Z",
      "emailReceivers": [
        "ops@example.com"
      ]
    }
  }
}
```

## REST events

| Event | Request | Topic | Notes |
| - | - | - | - |
| RecordMeasurements | `POST /v1/devices/{device_id}/record/?batch=true` | `cloud-iot/datacake/measurement/record` | Catalog: record field values into a device; body \[\{"field": "TEMPERATURE", "value": 23.5, "timestamp": 1759708800}] (timestamp optional; 1 write per second per field) **(write)** |
| IngestProductWebhook | `POST /integrations/api/{product_key}/{path}` | `cloud-iot/datacake/ingest/send` | Unauthenticated product HTTP URL (API devices): any JSON body, the product's payload decoder connectors it by serial; path "" or a custom sub-path like "status/" **(write)** |

Datacake rate-limits recorded measurements to 1 write per second per field. Add an optional Unix `timestamp` to each item to backfill.

## Webhook receiver

`DatacakeWebhookReceiver` listens on port `9005` and publishes each delivery on MQTT unchanged:

| Path | Datacake source | MQTT topic |
| - | - | - |
| `/datacake/webhook/measurements` | Outgoing webhook, event *Device measurements* (`device_measurement`) | `cloud-iot/datacake/webhook-measurement/received` |
| `/datacake/webhook/decoder-output` | Outgoing webhook, event *Decoder output* (`decoder_output`) | `cloud-iot/datacake/webhook-decoder-output/received` |
| `/datacake/webhook/downlinks` | Outgoing webhook, event *Downlinks* (`downlink`) | `cloud-iot/datacake/webhook-downlink/received` |
| `/datacake/webhook/rules` | Rule Engine webhook action | `cloud-iot/datacake/webhook-rule/received` |

1. In Datacake, open **Integrations → Webhooks → Add Webhook** (or publish on `cloud-iot/datacake/webhook/create`), use one webhook per event type, and point it at a public HTTPS URL.
2. Add a request header with a shared secret, for example `Authorization: Bearer <secret>`. Datacake recommends this over IP allow lists because its infrastructure scales dynamically.
3. Put a reverse proxy or tunnel with a public TLS certificate in front of port `9005`, have it check the header, and forward to `http://<broker>:9005/datacake/webhook/...`. The connector itself does not check headers.

> [!WARNING]
>
> Deploying the receiver opens an HTTP port on the broker. Deploy it only where you need push delivery.

## Examples

Read the latest values of one device:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<DATACAKE_API_TOKEN>",
  "body": {
    "query": "query($id: String) { device(deviceId: $id) { id verboseName currentMeasurements(allActiveFields: true) { value valueString modified field { fieldName verboseFieldName unit } } } }",
    "variables": {
      "id": "00000000-0000-0000-0000-000000000000"
    }
  }
}
```

Record a plant reading into a Datacake device:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<DATACAKE_API_TOKEN>",
  "device_id": "<device uuid>",
  "body": [
    {
      "field": "TEMPERATURE",
      "value": 23.5
    }
  ]
}
```

Helper actions (poll a device every minute, forward a plant topic into Datacake, fan webhook events out to plant topics):

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DatacakePollCurrentMeasurements
ON EVERY 1 MINUTE DO
    SET "token" WITH GET SECRET "DATACAKE_API_TOKEN"
    SET "dev" WITH GET SECRET "DATACAKE_DEVICE_ID"
    PUBLISH TOPIC "cloud-iot/datacake/measurement-current/get" WITH { "api_token": {token}, "body": { "query": "query($id: String) { device(deviceId: $id) { id verboseName currentMeasurements(allActiveFields: true) { value valueString modified field { fieldName verboseFieldName unit } } } }", "variables": { "id": {dev} } } }

DEFINE ACTION DatacakeRecordLineTemperature
ON TOPIC "porto/line1/temperature" DO
    SET "token" WITH GET SECRET "DATACAKE_API_TOKEN"
    SET "dev" WITH GET SECRET "DATACAKE_DEVICE_ID"
    PUBLISH TOPIC "cloud-iot/datacake/measurement/record" WITH { "api_token": {token}, "device_id": {dev}, "body": [ { "field": "TEMPERATURE", "value": PAYLOAD } ] }

DEFINE ACTION DatacakeWebhookToPlant
ON TOPIC "cloud-iot/datacake/webhook-measurement/received" DO
    SET "kind" WITH (GET JSON "event" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "plant/datacake/" + {kind} WITH PAYLOAD
```

## Writes

Write events: GraphqlMutation, CreateApiDevices, UpdateDevice, SetValue, SetDeviceConfigurationValue, SendDownlink, SendApiDownlink, SendMqttDownlink, CreateWebhook, UpdateWebhook, CreateManualExport, RecordMeasurements, IngestProductWebhook. `GraphqlMutation` can run any of the 266 mutations in the schema, including deletes, so restrict who may publish on `cloud-iot/datacake/graphql/mutate` with a broker rule. `CreateApiDevices` can add billed devices to the workspace. No preset deletes anything.

## Not packaged

Account, billing, white-label, SSO, Node-RED (CakeRed) and organization mutations; product decoder and dashboard editing; LoRaWAN network server and gateway provisioning; rule creation; every delete. They stay reachable through `GraphqlMutation` if you need them. Datacake's own MQTT broker (`mqtt.datacake.co`) is better reached with a Coreflux MQTT bridge connector than over REST.


# Datadog
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/datadog

Client-mode REST API connector for a curated Datadog slice: submit metrics series from MQTT, post events, send logs via HTTP intake, and list monitors

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of the [Datadog API](https://docs.datadoghq.com/api/latest/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST series (metrics from MQTT) | `POST /api/v2/series` | **Host:** `https://api.datadoghq.com` — Metrics API v2; `DD-API-KEY`; expect **202** |
| POST events | `POST /api/v1/events` | Same API host — Events API v1; `title` + `text` required |
| POST logs | `POST /api/v2/logs` | **Host:** `https://http-intake.logs.datadoghq.com` — logs intake differs from API host |
| GET monitor | `GET /api/v1/monitor` | Same API host — list monitors; needs `DD-API-KEY` **and** `DD-APPLICATION-KEY` |

Default `BASE_ADDRESS` is `https://api.datadoghq.com` (US1). Topics use `itsm/datadog/<object>/<verb>`.

> [!NOTE]
>
> Logs intake is **not** on `api.datadoghq.com`. Official US1 path is `https://http-intake.logs.datadoghq.com/api/v2/logs`. When calling `Submitlogs`, set connector `BASE_ADDRESS` to the logs intake host (or deploy a second connector copy). EU and other sites use matching hostnames (`api.datadoghq.eu`, `http-intake.logs.datadoghq.eu`, `api.us3.datadoghq.com`, …).

> [!NOTE]
>
> Prefer Hub secrets for API and application keys.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Datadog (metrics, events, logs, monitors curated slice)
# Auth: DD-API-KEY={value.json.api_key}; DD-APPLICATION-KEY={value.json.app_key}
# BASE_ADDRESS API: https://api.datadoghq.com
# Logs: set BASE_ADDRESS to https://http-intake.logs.datadoghq.com

DEFINE CONNECTOR DatadogRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.datadoghq.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Submitmetrics
        WITH SOURCE_TOPIC "itsm/datadog/metric/submit"
        WITH DESTINATION_TOPIC "itsm/datadog/metric/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/series"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "DD-API-KEY" "{value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Createevent
        WITH SOURCE_TOPIC "itsm/datadog/event/create"
        WITH DESTINATION_TOPIC "itsm/datadog/event/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "DD-API-KEY" "{value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Submitlogs
        WITH SOURCE_TOPIC "itsm/datadog/log/submit"
        WITH DESTINATION_TOPIC "itsm/datadog/log/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/logs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "DD-API-KEY" "{value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Listmonitors
        WITH SOURCE_TOPIC "itsm/datadog/monitor/list"
        WITH DESTINATION_TOPIC "itsm/datadog/monitor/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/monitor?page_size={value.json.page_size}&page={value.json.page}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "DD-API-KEY" "{value.json.api_key}"
            ADD "DD-APPLICATION-KEY" "{value.json.app_key}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Submitmetrics | POST | `/api/v2/series` | `itsm/datadog/metric/submit` | `itsm/datadog/metric/submit/response` |
| Createevent | POST | `/api/v1/events` | `itsm/datadog/event/create` | `itsm/datadog/event/create/response` |
| Submitlogs | POST | `/api/v2/logs` | `itsm/datadog/log/submit` | `itsm/datadog/log/submit/response` |
| Listmonitors | GET | `/api/v1/monitor?page_size=&page=` | `itsm/datadog/monitor/list` | `itsm/datadog/monitor/list/response` |

## Auth

1. Create a Datadog [API key and Application key](https://docs.datadoghq.com/account_management/api-app-keys/) in Organization Settings.
2. Pass `api_key` on MQTT payloads so headers resolve to `DD-API-KEY: {value.json.api_key}`.
3. For `Listmonitors`, also pass `app_key` → `DD-APPLICATION-KEY: {value.json.app_key}`.
4. Prefer Hub secrets / `GET SECRET "DD_API_KEY"` and `GET SECRET "DD_APP_KEY"`. Never commit real credentials.
5. Metrics, events, and logs intake typically need the **API key only**; listing monitors needs **both**.

## Site / region

| Site | API host | Logs intake host |
| - | - | - |
| US1 (default) | `https://api.datadoghq.com` | `https://http-intake.logs.datadoghq.com` |
| EU | `https://api.datadoghq.eu` | `https://http-intake.logs.datadoghq.eu` |
| US3 | `https://api.us3.datadoghq.com` | `https://http-intake.logs.us3.datadoghq.com` |
| US5 | `https://api.us5.datadoghq.com` | `https://http-intake.logs.us5.datadoghq.com` |
| AP1 | `https://api.ap1.datadoghq.com` | `https://http-intake.logs.ap1.datadoghq.com` |

Paths stay the same; only the hostname changes.

## Example payloads

**Submit metrics** (API host):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_DD_API_KEY",
  "series": [
    {
      "metric": "coreflux.plant.vibration_rms",
      "type": 3,
      "points": [{"timestamp": 1728000000, "value": 12.4}],
      "tags": ["line:a", "source:coreflux"]
    }
  ]
}
```

Expect **HTTP 202**.

**Create event:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_DD_API_KEY",
  "title": "Vibration above threshold — Zone A",
  "text": "Coreflux: RMS 12.4 mm/s (threshold 8.0)",
  "alert_type": "warning",
  "tags": ["line:a", "source:coreflux"]
}
```

**Submit logs** (logs intake host; body is a JSON **array**):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "message": "vibration_rms=12.4 threshold=8.0",
    "ddsource": "coreflux",
    "service": "broker",
    "hostname": "edge-line-a",
    "ddtags": "env:lab,line:a",
    "status": "warn"
  }
]
```

Include `api_key` in the MQTT envelope for the header placeholder; the HTTP body should be the array Datadog expects.

**List monitors:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_DD_API_KEY",
  "app_key": "YOUR_DD_APP_KEY",
  "page_size": "1",
  "page": "0"
}
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Datadog Metrics — Submit metrics](https://docs.datadoghq.com/api/latest/metrics/#submit-metrics)
* [Datadog Events — Post an event](https://docs.datadoghq.com/api/latest/events/#post-an-event)
* [Datadog Logs — Send logs](https://docs.datadoghq.com/api/latest/logs/#send-logs)
* [Datadog Monitors — Get all monitors](https://docs.datadoghq.com/api/latest/monitors/#get-all-monitor-details)


# DELMIA Apriso (Dassault Systèmes)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/delmia-apriso

Connect Coreflux LoT to DELMIA Apriso: get STS tokens, run published Standard Operations and queue Business Integrator messages from MQTT

Technical Preview

## Overview

[DELMIA Apriso](https://www.3ds.com/products/delmia/apriso) is Dassault Systemes' manufacturing operations platform (MES, quality, warehouse, maintenance). Its Web API lets an external system call the **Standard Operations** you publish as REST web services, and its Business Integrator accepts inbound XML messages. This connector lets plant logic on MQTT declare production, push machine status, record quality results and read orders in Apriso without custom code.

* **DelmiaAprisoApi** (`DelmiaAprisoRestApi.lot`) is a client connector on `https://YOUR_APRISO_SERVER` with 16 events.
* **DelmiaAprisoWebhookReceiver** (`mes_delmia-apriso_webhook.lot`, optional) is a server connector on port `9008` that receives calls from Apriso.

> [!WARNING]
>
> Dassault Systemes does not publish an OpenAPI file for Apriso. Each server generates its own Web API Reference at `/Apriso/HttpServices/help`, and the help center needs a 3DS login. These events come from the public DELMIA Apriso 2021 Technical Guides **Web API** and **Business Integrator: Integration Planning**. Check the endpoints and scopes against your server's Web API Reference (the `GetApiHelp` event returns it) before you rely on them.

## Server host

Apriso is installed per customer on IIS. Replace `YOUR_APRISO_SERVER` in `BASE_ADDRESS` with your Apriso web server, with no trailing slash. The endpoints already include the `/Apriso` application path: the Web API lives under `/Apriso/HttpServices` and the Secure Token Service (STS) at `/Apriso/Portal/sts/2.0/token`. On a lab server without TLS, use `http://` and set `USE_SSL` to `"false"`.

## Authentication

> [!WARNING]
>
> API keys, client secrets and access tokens act as an Apriso client application. Keep them in Hub secrets, map them in with `GET SECRET`, and never publish them on a topic other clients can read.

1. Register Coreflux as a client application in `ClientApplications.xml` (in the server's `CentralConfiguration` folder) with a `ClientId`, and an `ApiKey` and/or a `ClientSecret`, the `Scopes` it may request (`standard_operations`, `message_processing`, ...) and the `ClientCredentials` grant. Restart the Apriso services.
2. Pick a flow. Every Web API event takes `"authorization"` and `"client_id"` in its MQTT payload and sends them as `Authorization` and `X-Client-Application`.
   * **API key:** `"authorization": "ApiKey <ApiKey>"`, `"client_id": "<ClientId>"`. Check it with `HelloApiKey`.
   * **Access token:** publish `GetToken` (client credentials) with `client_id`, `client_secret` and `scope`, then send `"authorization": "Bearer <access_token>"`. Check it with `HelloToken`. `GetUserToken` (password grant, `login_type` `standard` or `ldap`) and `RefreshToken` are there too.
3. Publish the Standard Operations you want to call in **Process Builder > Web Services Manager**, with security level API Key or Access Token.

Suggested secrets: `APRISO_CLIENT_ID`, `APRISO_API_KEY` and `APRISO_CLIENT_SECRET`. Wrong or missing credentials return `401 Unauthorized`. A token only reaches the endpoints of the scopes it was issued for.

## Payload conventions

* **Standard Operations.** `DescribeOperation` returns the operation's `Inputs`, `Outputs` and a sample `ExecutionParameters` body. The run events send `"body"` unchanged: `{"Inputs": {...}, "ExecutionMode": 1, "JobPool": "", "Retries": 1, "SleepTime": 1000, "SynchronuousQueue": "", "Timeout": 5000}`. Only `Inputs` is required. `ExecutionMode` is `0` (in the IIS process), `1` (synchronous through Job Executor, the default) or `2` (queued asynchronously). The response carries `Outputs`.
* **Revisions.** Calls use the operation's default revision. The `...Revision` events take a `revision` such as `REV.001.001`.
* **Presets.** `DeclareProduction`, `ReportMachineStatus`, `PostQualityInspectionResult` and `GetOrder` use the same contract on their own topics, so each plant use case gets a clean topic. Their operation codes and Inputs are examples: send the codes and Inputs of the operations you published.
* **Business Integrator.** `ProcessMessageAsync` sends `"body"` as an XML string with `Content-Type: application/xml` for the `message_name` of your external system, and needs a token with the `message_processing` scope.
* **Formats.** Apriso answers JSON by default. Token requests are form-encoded, so keep the values in `client_secret`, `password` and `scope` free of `&` and `=`.

## Tokens and auth checks

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetToken | `POST /Apriso/Portal/sts/2.0/token` | `mes/delmia-apriso/token/create` | Client Credentials grant: access token for the user set in FlexNet.BackgroundProcessingContext EmployeeID (expires\_in 86400 in the guide) |
| GetUserToken | `POST /Apriso/Portal/sts/2.0/token` | `mes/delmia-apriso/user-token/create` | Resource Owner Password grant (Standard or LDAP login): access token for an Apriso user |
| RefreshToken | `POST /Apriso/Portal/sts/2.0/token` | `mes/delmia-apriso/token/refresh` | Refresh an Authorization Code token (refresh\_token from the code flow) |
| HelloApiKey | `GET /Apriso/HttpServices/hello/apiKeySecured` | `mes/delmia-apriso/hello-api-key/get` | Credential check (API key): answers "Correct API Key passed!"; 401 on a wrong key or client id |
| HelloToken | `GET /Apriso/HttpServices/hello/tokenSecured` | `mes/delmia-apriso/hello-token/get` | Credential check (access token): 200 with a valid Bearer token, 401 otherwise |

## Standard Operations

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListOperations | `GET /Apriso/HttpServices/operations` | `mes/delmia-apriso/operation/list` | Standard Operations published through the Web API on this server (scope standard\_operations) |
| DescribeOperation | `GET /Apriso/HttpServices/operations/{operation_code}` | `mes/delmia-apriso/operation/describe` | Inputs, Outputs and a sample ExecutionParameters payload of the operation's default revision |
| DescribeOperationRevision | `GET /Apriso/HttpServices/operations/{operation_code}/{revision}` | `mes/delmia-apriso/operation-revision/describe` | Same as DescribeOperation for one revision (e.g. REV.001.001) |
| RunOperation | `POST /Apriso/HttpServices/operations/{operation_code}` | `mes/delmia-apriso/operation/run` | Execute a published Standard Operation (default revision) with Inputs + execution parameters; returns Outputs. Writes whatever the operation writes |
| RunOperationRevision | `POST /Apriso/HttpServices/operations/{operation_code}/{revision}` | `mes/delmia-apriso/operation-revision/run` | Execute one revision of a published Standard Operation |

## Plant presets

| Event | Request | Topic | Notes |
| - | - | - | - |
| DeclareProduction | `POST /Apriso/HttpServices/operations/{operation_code}` | `mes/delmia-apriso/production-declaration/post` | Preset: declare produced quantity against a WIP order through your published production-declaration operation (Inputs are operation-specific examples) |
| ReportMachineStatus | `POST /Apriso/HttpServices/operations/{operation_code}` | `mes/delmia-apriso/machine-status/post` | Preset: push a machine / resource status change from the UNS into your published status operation (ExecutionMode 2 = queued async) |
| PostQualityInspectionResult | `POST /Apriso/HttpServices/operations/{operation_code}` | `mes/delmia-apriso/quality-inspection-result/post` | Preset: record an inspection / data collection result through your published quality operation |
| GetOrder | `POST /Apriso/HttpServices/operations/{operation_code}` | `mes/delmia-apriso/order/get` | Preset: read an order through your published read-only order query operation (Standard Operations execute with POST even when they only read) |

## Business Integrator and discovery

| Event | Request | Topic | Notes |
| - | - | - | - |
| ProcessMessageAsync | `POST /Apriso/HttpServices/ProcessMessageASync/{message_name}` | `mes/delmia-apriso/bi-message/send` | Queue an inbound Business Integrator XML message for the named external system (scope message\_processing); returns true when accepted |
| GetApiHelp | `GET /Apriso/HttpServices/help` | `mes/delmia-apriso/api-help/get` | The server's generated Web API Reference (HTML): every controller, endpoint and required scope on your version |

## Receiving calls from Apriso (optional)

Deploy `mes_delmia-apriso_webhook.lot` to let Apriso call the broker. It runs in server mode on port `9008` and republishes each request body unchanged.

| Event | Endpoint | Topic | Use |
| - | - | - | - |
| OutboundMessage | `POST /delmia-apriso/outbound/message` | `mes/delmia-apriso/outbound-message/received` | Business Integrator REST Adapter (Job Action Type 39): the mapped external XML (or internal XML) POSTed to the REST Client URL + RELATIVEURI |
| OutboundWebApiCall | `POST /delmia-apriso/outbound/event` | `mes/delmia-apriso/outbound-event/received` | Process Builder / Portal Web API Client (Apr.WebAPI ApiKeyClient Post) calling Coreflux as an external provider with a JSON body |

For the Business Integrator REST Adapter, set the REST Client URL to `http(s)://<broker>:9008` and `RELATIVEURI` to `/delmia-apriso/outbound/message`. The connector has no authentication, so keep the port on the plant network or behind a reverse proxy with TLS.

## Examples

Get a token (client credentials):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "client_id": "<client id>",
  "client_secret": "<client secret>",
  "scope": "standard_operations,message_processing",
  "state": "coreflux"
}
```

Run a published operation with an API key:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "ApiKey <api key>  (or: Bearer <access_token>)",
  "client_id": "<client id>",
  "operation_code": "GetEmployee",
  "body": {
    "Inputs": {
      "Id": 1
    },
    "ExecutionMode": 1,
    "Retries": 1,
    "SleepTime": 1000,
    "Timeout": 5000
  }
}
```

Declare production against a WIP order:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "ApiKey <api key>  (or: Bearer <access_token>)",
  "client_id": "<client id>",
  "operation_code": "ProductionDeclaration",
  "body": {
    "Inputs": {
      "WipOrderNo": "WO-1001",
      "OperationSequenceNo": "10",
      "Quantity": 12,
      "UomCode": "EA"
    },
    "ExecutionMode": 1,
    "Retries": 1,
    "SleepTime": 1000,
    "Timeout": 5000
  }
}
```

Queue a Business Integrator message:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <access_token with message_processing>",
  "client_id": "<client id>",
  "message_name": "MyExternalSystem1",
  "body": "<FlexNet_WorkCenters Version=\"1.0\"><WorkCenter><Code>WP02</Code><Facility>C1P</Facility></WorkCenter></FlexNet_WorkCenters>"
}
```

Keep a token fresh and forward a good-part count from the UNS (from `docs-helper-actions.lot`):

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AprisoLogin
ON EVERY 12 HOURS DO
    SET "cid" WITH GET SECRET "APRISO_CLIENT_ID"
    SET "csec" WITH GET SECRET "APRISO_CLIENT_SECRET"
    PUBLISH TOPIC "mes/delmia-apriso/token/create" WITH { "client_id": {cid}, "client_secret": {csec}, "scope": "standard_operations,message_processing", "state": "coreflux" }

DEFINE ACTION AprisoKeepToken
ON TOPIC "mes/delmia-apriso/token/create/response" DO
    SET "token" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "internal/delmia-apriso/authorization" WITH "Bearer " + {token}
```

## Writes

Write events: RunOperation, RunOperationRevision, DeclareProduction, ReportMachineStatus, PostQualityInspectionResult, ProcessMessageAsync. They change data in Apriso through the operations you published or through Business Integrator. `GetOrder` posts too, but only runs the read-only operation you point it at. No event deletes anything.

## Not packaged

The SOAP web services (`IFlexNetMessageProcessor`), the Implicit and Authorization Code browser flows (they need a user in the Apriso Portal), the cache, personalization and data paging controllers (their endpoints are only in each server's Web API Reference), 3DPassport authentication, and any `DELETE`.


# Dhl Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dhl-api

LoT connector for DHL Shipment Tracking Unified: track shipments across DHL divisions and manage Tracking Push subscriptions with a DHL API key

Technical Preview

## Overview

Client-mode REST API connectors for the DHL API Developer Portal: Shipment Tracking Unified (every DHL division) with Tracking Push subscriptions, Location Finder service points, DHL Express MyDHL API (rates, landed cost, shipments and labels, pickups, tracking, proof of delivery, paperless trade uploads) and Post & Parcel Germany (Parcel DE Shipping, Pickup and Returns with OAuth); purchases marked; companion server connector for DHL Tracking Push webhooks.

This is one of the templates in the DHL API Developer Portal REST API app (`dhl-api-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Per product: DhlApi + DhlLocationFinder header DHL-API-Key (developer.dhl.com app key); MyDhlExpress HTTP Basic MyDHL username:password (from DHL Express, not the portal key) + x-version 3.3.3 + Message-Reference; DhlParcelDeAuth OAuth 2.0 password grant (form grant\_type=password, username, password = GKP system user, client\_id = API key, client\_secret = API secret; reply access\_token Bearer, expires\_in 1799, no refresh token); DhlParcelDe Authorization: Bearer only (bearer + dhl-api-key together -> 401). Every event sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `DHL-API-Key: {value.json.api_key}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Dhl Api connector | no |
| `BaseUrl` | string | Dhl Api base URL without trailing slash (e.g. [https://api-eu.dhl.com](https://api-eu.dhl.com)) | yes |

`BASE_ADDRESS` default: `https://api-eu.dhl.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `TrackShipment` | GET | `/track/shipments?{value.json.query}` | `fleet/dhl/shipment-tracking/get` | `fleet/dhl/shipment-tracking/get/response` | `api_key`, `query` |
| `CreateTrackingSubscription` | POST | `/tracking/push/v1/subscription` | `fleet/dhl/tracking-subscription/create` | `fleet/dhl/tracking-subscription/create/response` | `api_key`, `body` |
| `ActivateTrackingSubscription` | POST | `/tracking/push/v1/subscription/{value.json.id}` | `fleet/dhl/tracking-subscription/activate` | `fleet/dhl/tracking-subscription/activate/response` | `api_key`, `hook_secret`, `id` |
| `GetTrackingSubscription` | GET | `/tracking/push/v1/subscription/{value.json.id}` | `fleet/dhl/tracking-subscription/get` | `fleet/dhl/tracking-subscription/get/response` | `api_key`, `id` |
| `ListTrackingSubscriptions` | GET | `/tracking/push/v1/subscriptions` | `fleet/dhl/tracking-subscription/list` | `fleet/dhl/tracking-subscription/list/response` | `api_key` |
| `DeleteTrackingSubscription` | DELETE | `/tracking/push/v1/subscription/{value.json.id}` | `fleet/dhl/tracking-subscription/delete` | `fleet/dhl/tracking-subscription/delete/response` | `api_key`, `hook_secret`, `id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DHL_API"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DhlApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api-eu.dhl.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TrackShipment
        WITH SOURCE_TOPIC "fleet/dhl/shipment-tracking/get"
        WITH DESTINATION_TOPIC "fleet/dhl/shipment-tracking/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/track/shipments?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
    ADD EVENT CreateTrackingSubscription
        WITH SOURCE_TOPIC "fleet/dhl/tracking-subscription/create"
        WITH DESTINATION_TOPIC "fleet/dhl/tracking-subscription/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tracking/push/v1/subscription"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ActivateTrackingSubscription
        WITH SOURCE_TOPIC "fleet/dhl/tracking-subscription/activate"
        WITH DESTINATION_TOPIC "fleet/dhl/tracking-subscription/activate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tracking/push/v1/subscription/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
            ADD "DHL-API-Hook-Secret" "{value.json.hook_secret}"
        WITH BODY ""
    ADD EVENT GetTrackingSubscription
        WITH SOURCE_TOPIC "fleet/dhl/tracking-subscription/get"
        WITH DESTINATION_TOPIC "fleet/dhl/tracking-subscription/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tracking/push/v1/subscription/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
    ADD EVENT ListTrackingSubscriptions
        WITH SOURCE_TOPIC "fleet/dhl/tracking-subscription/list"
        WITH DESTINATION_TOPIC "fleet/dhl/tracking-subscription/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tracking/push/v1/subscriptions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
    ADD EVENT DeleteTrackingSubscription
        WITH SOURCE_TOPIC "fleet/dhl/tracking-subscription/delete"
        WITH DESTINATION_TOPIC "fleet/dhl/tracking-subscription/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/tracking/push/v1/subscription/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
            ADD "DHL-API-Hook-Secret" "{value.json.hook_secret}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `TrackShipment` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/dhl/shipment-tracking/get/response' &
mosquitto_pub -t 'fleet/dhl/shipment-tracking/get' -m '{"api_key": "<api_key>", "query": "<query>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Dhl Location Finder
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dhl-location-finder

LoT connector for the DHL Location Finder API: search DHL service points by address, coordinates or keyword ID and get location details from MQTT

Technical Preview

## Overview

Client-mode REST API connectors for the DHL API Developer Portal: Shipment Tracking Unified (every DHL division) with Tracking Push subscriptions, Location Finder service points, DHL Express MyDHL API (rates, landed cost, shipments and labels, pickups, tracking, proof of delivery, paperless trade uploads) and Post & Parcel Germany (Parcel DE Shipping, Pickup and Returns with OAuth); purchases marked; companion server connector for DHL Tracking Push webhooks.

This is one of the templates in the DHL API Developer Portal REST API app (`dhl-api-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Per product: DhlApi + DhlLocationFinder header DHL-API-Key (developer.dhl.com app key); MyDhlExpress HTTP Basic MyDHL username:password (from DHL Express, not the portal key) + x-version 3.3.3 + Message-Reference; DhlParcelDeAuth OAuth 2.0 password grant (form grant\_type=password, username, password = GKP system user, client\_id = API key, client\_secret = API secret; reply access\_token Bearer, expires\_in 1799, no refresh token); DhlParcelDe Authorization: Bearer only (bearer + dhl-api-key together -> 401). Every event sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `DHL-API-Key: {value.json.api_key}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Dhl Location Finder connector | no |
| `BaseUrl` | string | Dhl Location Finder base URL without trailing slash (e.g. [https://api.dhl.com](https://api.dhl.com)) | yes |

`BASE_ADDRESS` default: `https://api.dhl.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `FindLocationsByAddress` | GET | `/location-finder/v1/find-by-address?{value.json.query}` | `fleet/dhl/location/search` | `fleet/dhl/location/search/response` | `api_key`, `query` |
| `FindLocationsByGeo` | GET | `/location-finder/v1/find-by-geo?{value.json.query}` | `fleet/dhl/location-geo/search` | `fleet/dhl/location-geo/search/response` | `api_key`, `query` |
| `FindLocationsByKeywordId` | GET | `/location-finder/v1/find-by-keyword-id?{value.json.query}` | `fleet/dhl/location-keyword/search` | `fleet/dhl/location-keyword/search/response` | `api_key`, `query` |
| `GetLocation` | GET | `/location-finder/v1/locations/{value.json.id}` | `fleet/dhl/location/get` | `fleet/dhl/location/get/response` | `api_key`, `id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DHL_LOCATION_FINDER"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DhlLocationFinder WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.dhl.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT FindLocationsByAddress
        WITH SOURCE_TOPIC "fleet/dhl/location/search"
        WITH DESTINATION_TOPIC "fleet/dhl/location/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/location-finder/v1/find-by-address?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
    ADD EVENT FindLocationsByGeo
        WITH SOURCE_TOPIC "fleet/dhl/location-geo/search"
        WITH DESTINATION_TOPIC "fleet/dhl/location-geo/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/location-finder/v1/find-by-geo?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
    ADD EVENT FindLocationsByKeywordId
        WITH SOURCE_TOPIC "fleet/dhl/location-keyword/search"
        WITH DESTINATION_TOPIC "fleet/dhl/location-keyword/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/location-finder/v1/find-by-keyword-id?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
    ADD EVENT GetLocation
        WITH SOURCE_TOPIC "fleet/dhl/location/get"
        WITH DESTINATION_TOPIC "fleet/dhl/location/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/location-finder/v1/locations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "DHL-API-Key" "{value.json.api_key}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `FindLocationsByAddress` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/dhl/location/search/response' &
mosquitto_pub -t 'fleet/dhl/location/search' -m '{"api_key": "<api_key>", "query": "<query>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Dhl Parcel De
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dhl-parcel-de

LoT connector for DHL Parcel DE: validate and create shipments, get labels, close manifests, book pickups and create return labels with OAuth

Technical Preview

## Overview

Client-mode REST API connectors for the DHL API Developer Portal: Shipment Tracking Unified (every DHL division) with Tracking Push subscriptions, Location Finder service points, DHL Express MyDHL API (rates, landed cost, shipments and labels, pickups, tracking, proof of delivery, paperless trade uploads) and Post & Parcel Germany (Parcel DE Shipping, Pickup and Returns with OAuth); purchases marked; companion server connector for DHL Tracking Push webhooks.

This is one of the templates in the DHL API Developer Portal REST API app (`dhl-api-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Per product: DhlApi + DhlLocationFinder header DHL-API-Key (developer.dhl.com app key); MyDhlExpress HTTP Basic MyDHL username:password (from DHL Express, not the portal key) + x-version 3.3.3 + Message-Reference; DhlParcelDeAuth OAuth 2.0 password grant (form grant\_type=password, username, password = GKP system user, client\_id = API key, client\_secret = API secret; reply access\_token Bearer, expires\_in 1799, no refresh token); DhlParcelDe Authorization: Bearer only (bearer + dhl-api-key together -> 401). Every event sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Dhl Parcel De connector | no |
| `BaseUrl` | string | Dhl Parcel De base URL without trailing slash (e.g. [https://api-eu.dhl.com](https://api-eu.dhl.com)) | yes |

`BASE_ADDRESS` default: `https://api-eu.dhl.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ParcelDeCheckToken` | GET | `/parcel/de/account/auth/ropc/v1/hello` | `fleet/dhl/parcel-de-token/get` | `fleet/dhl/parcel-de-token/get/response` | `access_token` |
| `ParcelDeValidateShipments` | POST | `/parcel/de/shipping/v2/orders?validate=true` | `fleet/dhl/parcel-de-shipment/validate` | `fleet/dhl/parcel-de-shipment/validate/response` | `access_token`, `body` |
| `ParcelDeCreateShipments` | POST | `/parcel/de/shipping/v2/orders?{value.json.query}` | `fleet/dhl/parcel-de-shipment/create` | `fleet/dhl/parcel-de-shipment/create/response` | `access_token`, `body`, `query` |
| `ParcelDeGetShipmentDocuments` | GET | `/parcel/de/shipping/v2/orders?{value.json.query}` | `fleet/dhl/parcel-de-shipment-documents/get` | `fleet/dhl/parcel-de-shipment-documents/get/response` | `access_token`, `query` |
| `ParcelDeDeleteShipments` | DELETE | `/parcel/de/shipping/v2/orders?{value.json.query}` | `fleet/dhl/parcel-de-shipment/delete` | `fleet/dhl/parcel-de-shipment/delete/response` | `access_token`, `query` |
| `ParcelDeCloseManifest` | POST | `/parcel/de/shipping/v2/manifests` | `fleet/dhl/parcel-de-manifest/create` | `fleet/dhl/parcel-de-manifest/create/response` | `access_token`, `body` |
| `ParcelDeGetManifest` | GET | `/parcel/de/shipping/v2/manifests?{value.json.query}` | `fleet/dhl/parcel-de-manifest/get` | `fleet/dhl/parcel-de-manifest/get/response` | `access_token`, `query` |
| `ParcelDeValidatePickup` | POST | `/parcel/de/transportation/pickup/v3/orders?validate=true` | `fleet/dhl/parcel-de-pickup/validate` | `fleet/dhl/parcel-de-pickup/validate/response` | `access_token`, `body` |
| `ParcelDeCreatePickup` | POST | `/parcel/de/transportation/pickup/v3/orders` | `fleet/dhl/parcel-de-pickup/create` | `fleet/dhl/parcel-de-pickup/create/response` | `access_token`, `body` |
| `ParcelDeGetPickups` | GET | `/parcel/de/transportation/pickup/v3/orders?{value.json.query}` | `fleet/dhl/parcel-de-pickup/get` | `fleet/dhl/parcel-de-pickup/get/response` | `access_token`, `query` |
| `ParcelDeCancelPickup` | DELETE | `/parcel/de/transportation/pickup/v3/orders?{value.json.query}` | `fleet/dhl/parcel-de-pickup/cancel` | `fleet/dhl/parcel-de-pickup/cancel/response` | `access_token`, `query` |
| `ParcelDeGetPickupLocations` | GET | `/parcel/de/transportation/pickup/v3/locations?{value.json.query}` | `fleet/dhl/parcel-de-pickup-location/get` | `fleet/dhl/parcel-de-pickup-location/get/response` | `access_token`, `query` |
| `ParcelDeCreateReturnLabel` | POST | `/parcel/de/shipping/returns/v1/orders?{value.json.query}` | `fleet/dhl/parcel-de-return-label/create` | `fleet/dhl/parcel-de-return-label/create/response` | `access_token`, `body`, `query` |
| `ParcelDeGetReturnLocations` | GET | `/parcel/de/shipping/returns/v1/locations?{value.json.query}` | `fleet/dhl/parcel-de-return-location/get` | `fleet/dhl/parcel-de-return-location/get/response` | `access_token`, `query` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DHL_PARCEL_DE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DhlParcelDe WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api-eu.dhl.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ParcelDeCheckToken
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-token/get"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-token/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/parcel/de/account/auth/ropc/v1/hello"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ParcelDeValidateShipments
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-shipment/validate"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-shipment/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/parcel/de/shipping/v2/orders?validate=true"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ParcelDeCreateShipments
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-shipment/create"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-shipment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/parcel/de/shipping/v2/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ParcelDeGetShipmentDocuments
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-shipment-documents/get"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-shipment-documents/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/parcel/de/shipping/v2/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ParcelDeDeleteShipments
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-shipment/delete"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-shipment/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/parcel/de/shipping/v2/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ParcelDeCloseManifest
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-manifest/create"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-manifest/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/parcel/de/shipping/v2/manifests"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ParcelDeGetManifest
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-manifest/get"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-manifest/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/parcel/de/shipping/v2/manifests?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ParcelDeValidatePickup
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-pickup/validate"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-pickup/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/parcel/de/transportation/pickup/v3/orders?validate=true"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ParcelDeCreatePickup
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-pickup/create"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-pickup/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/parcel/de/transportation/pickup/v3/orders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ParcelDeGetPickups
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-pickup/get"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-pickup/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/parcel/de/transportation/pickup/v3/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ParcelDeCancelPickup
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-pickup/cancel"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-pickup/cancel/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/parcel/de/transportation/pickup/v3/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ParcelDeGetPickupLocations
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-pickup-location/get"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-pickup-location/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/parcel/de/transportation/pickup/v3/locations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ParcelDeCreateReturnLabel
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-return-label/create"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-return-label/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/parcel/de/shipping/returns/v1/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ParcelDeGetReturnLocations
        WITH SOURCE_TOPIC "fleet/dhl/parcel-de-return-location/get"
        WITH DESTINATION_TOPIC "fleet/dhl/parcel-de-return-location/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/parcel/de/shipping/returns/v1/locations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ParcelDeCheckToken` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/dhl/parcel-de-token/get/response' &
mosquitto_pub -t 'fleet/dhl/parcel-de-token/get' -m '{"access_token": "<access_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Discord
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/discord

Connect Coreflux LoT to Discord API v10: execute incoming webhooks, post channel messages with embeds, and check bot, channel and gateway info

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Discord API v10](https://discord.com/developers/docs/reference):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST webhooks/\{id}/\{token} | `POST /webhooks/{webhook_id}/{webhook_token}` | Incoming webhook; path credentials; embeds OK |
| POST channels/\{id}/messages | `POST /channels/{channel_id}/messages` | Bot token; `content` and/or `embeds[]` |
| GET users/@me | `GET /users/@me` | Bot credential check |
| GET channels/\{id} | `GET /channels/{channel_id}` | Channel lookup |
| GET gateway/bot | `GET /gateway/bot` | Bot gateway URL + limits |

Default `BASE_ADDRESS` is `https://discord.com/api/v10`. Topics use `messaging/discord/<object>/<verb>`.

> [!NOTE]
>
> Bot REST methods send `Authorization: Bot {token}`. Incoming webhook execute uses **only** the webhook id and token in the path — do not send a Bot header on that event. Prefer Hub secrets. Discord returns **429** with `retry_after` under rate limits. Gateway WebSocket / Interactions inbound → MQTT is out of scope for this client-mode package.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Discord API v10
# Auth: Bot {value.json.bot_token} on Bot REST; webhook path credentials on Executewebhook
# BASE_ADDRESS: https://discord.com/api/v10

DEFINE CONNECTOR DiscordRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://discord.com/api/v10"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getmyuser
        WITH SOURCE_TOPIC "messaging/discord/user/get-me"
        WITH DESTINATION_TOPIC "messaging/discord/user/get-me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/users/@me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bot {value.json.bot_token}"
    ADD EVENT Getchannel
        WITH SOURCE_TOPIC "messaging/discord/channel/get"
        WITH DESTINATION_TOPIC "messaging/discord/channel/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/channels/{value.json.channel_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bot {value.json.bot_token}"
    ADD EVENT Createmessage
        WITH SOURCE_TOPIC "messaging/discord/message/create"
        WITH DESTINATION_TOPIC "messaging/discord/message/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/channels/{value.json.channel_id}/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bot {value.json.bot_token}"
        WITH BODY "{payload}"
    ADD EVENT Executewebhook
        WITH SOURCE_TOPIC "messaging/discord/webhook/execute"
        WITH DESTINATION_TOPIC "messaging/discord/webhook/execute/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webhooks/{value.json.webhook_id}/{value.json.webhook_token}?wait={value.json.wait}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getbotgateway
        WITH SOURCE_TOPIC "messaging/discord/gateway/bot"
        WITH DESTINATION_TOPIC "messaging/discord/gateway/bot/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/gateway/bot"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bot {value.json.bot_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getmyuser | GET | `/users/@me` | `messaging/discord/user/get-me` | `messaging/discord/user/get-me/response` |
| Getchannel | GET | `/channels/{channel_id}` | `messaging/discord/channel/get` | `messaging/discord/channel/get/response` |
| Createmessage | POST | `/channels/{channel_id}/messages` | `messaging/discord/message/create` | `messaging/discord/message/create/response` |
| Executewebhook | POST | `/webhooks/{webhook_id}/{webhook_token}` | `messaging/discord/webhook/execute` | `messaging/discord/webhook/execute/response` |
| Getbotgateway | GET | `/gateway/bot` | `messaging/discord/gateway/bot` | `messaging/discord/gateway/bot/response` |

## Auth

1. Create a Discord application + bot in the [Developer Portal](https://discord.com/developers/applications) and copy the bot token. Invite the bot to a lab guild with `Send Messages` (and related) permissions.
2. Set connector `BASE_ADDRESS` to `https://discord.com/api/v10`.
3. For Bot REST events, pass `bot_token` on the MQTT payload so `Authorization: Bot {value.json.bot_token}` resolves.
4. For incoming webhooks, create a channel webhook and pass `webhook_id` + `webhook_token` (optional `wait`); do **not** send a Bot Authorization header on Executewebhook.
5. Store secrets in Hub / `GET SECRET "DISCORD_BOT_TOKEN"`. Never commit real credentials.
6. Successful `GET /users/@me` returns **HTTP 200** with a user JSON object. `POST .../messages` returns **200**. Webhook execute returns **204** (`wait` false/omitted) or **200** (`wait=true`).

## Example payloads

**getMyUser:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "bot_token": "YOUR_DISCORD_BOT_TOKEN"
}
```

**createMessage:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "bot_token": "YOUR_DISCORD_BOT_TOKEN",
  "channel_id": "123456789012345678",
  "content": "Coreflux alarm: vibration above threshold — Zone A",
  "embeds": [
    {
      "title": "Zone A vibration",
      "description": "RMS exceeded limit",
      "color": 15158332
    }
  ]
}
```

**executeWebhook:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "webhook_id": "YOUR_WEBHOOK_ID",
  "webhook_token": "YOUR_WEBHOOK_TOKEN",
  "wait": "true",
  "content": "Coreflux alert",
  "embeds": [
    {
      "title": "Factory alert",
      "description": "Line 3 stopped"
    }
  ]
}
```

## Install

1. The template ships with the broker. List it with `-listTemplates` or fetch it from the Hub catalog.
2. Deploy with `-addConnector` from `DiscordRestApi.lot` (not `hub-metadata.lot`).

## See also

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Docker Hub
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/docker-hub

Client-mode REST API connector for a curated Docker Hub v2 slice: list repositories and image tags

Technical Preview

# Docker Hub

Client-mode REST API connector for a curated Docker Hub v2 slice: list repositories and image tags.

* Hub category: **Work and DevOps**.
* Base: `https://hub.docker.com`

## Template reference

Generated from the shipped broker template `docker-hub` (`-connectorCode DOCKER_HUB`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Docker Hub connector | no |
| `BaseUrl` | string | Docker Hub base URL without trailing slash (e.g. [https://hub.docker.com](https://hub.docker.com)) | yes |

`BASE_ADDRESS` default: `https://hub.docker.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listrepos` | GET | `/v2/repositories/{value.json.namespace}/` | `devops/dockerhub/repos/list` | `devops/dockerhub/repos/list/response` | `api_token`, `namespace` |
| `Listtags` | GET | `/v2/repositories/{value.json.namespace}/{value.json.repository}/tags` | `devops/dockerhub/tags/list` | `devops/dockerhub/tags/list/response` | `api_token`, `namespace`, `repository` |
| `Getrepo` | GET | `/v2/repositories/{value.json.namespace}/{value.json.repository}/` | `devops/dockerhub/repos/get` | `devops/dockerhub/repos/get/response` | `api_token`, `namespace`, `repository` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DOCKER_HUB"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DockerHubRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://hub.docker.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listrepos
        WITH SOURCE_TOPIC "devops/dockerhub/repos/list"
        WITH DESTINATION_TOPIC "devops/dockerhub/repos/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/repositories/{value.json.namespace}/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listtags
        WITH SOURCE_TOPIC "devops/dockerhub/tags/list"
        WITH DESTINATION_TOPIC "devops/dockerhub/tags/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/repositories/{value.json.namespace}/{value.json.repository}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getrepo
        WITH SOURCE_TOPIC "devops/dockerhub/repos/get"
        WITH DESTINATION_TOPIC "devops/dockerhub/repos/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/repositories/{value.json.namespace}/{value.json.repository}/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listrepos` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'devops/dockerhub/repos/list/response' &
mosquitto_pub -t 'devops/dockerhub/repos/list' -m '{"api_token": "<api_token>", "namespace": "<namespace>"}'
```


# Docu Sign ESignature
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/docu-sign-esignature

LoT connector for DocuSign eSignature: create envelopes from MQTT, track envelope and recipient status, read form data and download signed documents

Technical Preview

## Overview

Client-mode REST API connectors for DocuSign eSignature: send inspection reports, test certificates and permits for signature from MQTT, follow envelope and recipient status, read signed field values and download the signed PDF with its certificate of completion, authenticated with the OAuth 2.0 JWT grant; a server-mode companion connector receives DocuSign Connect webhooks.

This is one of the templates in the DocuSign eSignature REST API app (`docusign-esignature`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["JwtToken: POST /oauth/token on DocuSignOAuth, form body grant\_type=urn:ietf:params:oauth:grant-type:jwt-bearer (baked in) + assertion (JWT RS256 signed outside the broker with the integration key's RSA private key; claims iss = integration key, sub = user ID GUID, aud = account-d.docusign.com / account.docusign.com without https\://, iat, exp \<= 1 h, scope 'signature impersonation'); returns access\_token, Bearer, expires\_in 3600, no refresh token", "UserInfo: GET /oauth/userinfo with Bearer -> accounts\[].account\_id + base\_uri (sets BASE\_ADDRESS and account\_id)", "Authorization: Bearer \{value.json.access\_token} on every eSignature event except ServiceInformation (no auth)", "One-time consent (browser): [https://account-d.docusign.com/oauth/auth?response\_type=code\&scope=signature%20impersonation\&client\_id=\<key>\&redirect\_uri=\<uri](https://account-d.docusign.com/oauth/auth?response_type=code\&scope=signature%20impersonation\&client_id=\<key>\&redirect_uri=\<uri)>, or organization admin consent", "Authorization Code grant and the legacy X-DocuSign-Authentication header not packaged"]
* **secrets**: \["DOCUSIGN\_INTEGRATION\_KEY", "DOCUSIGN\_USER\_ID", "DOCUSIGN\_PRIVATE\_KEY (for the external JWT signer only; never in the broker connector)", "DOCUSIGN\_ACCESS\_TOKEN (optional, current token)", "DOCUSIGN\_ACCOUNT\_ID"]
* **permissions**: The token acts as the impersonated user (permission profile must allow sending envelopes; Connect reads need account admin).
* **note**: Inject secrets with a LoT action (GET SECRET); never retain topics that carry a JWT or token; restrict finance/docusign-esignature/auth/# with ACLs. LoT cannot sign RS256, so a signer service publishes the JWT.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Docu Sign ESignature connector | no |
| `BaseUrl` | string | Docu Sign ESignature base URL without trailing slash (e.g. https\://YOUR\_BASE\_URI) | yes |

`BASE_ADDRESS` default: `https://YOUR_BASE_URI`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ServiceInformation` | GET | `/restapi/service_information` | `finance/docusign-esignature/service/info` | `finance/docusign-esignature/service/info/response` | none |
| `AccountGet` | GET | `/restapi/v2.1/accounts/{value.json.account_id}?{value.json.query}` | `finance/docusign-esignature/account/get` | `finance/docusign-esignature/account/get/response` | `access_token`, `account_id`, `query` |
| `UsersList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/users?{value.json.query}` | `finance/docusign-esignature/users/list` | `finance/docusign-esignature/users/list/response` | `access_token`, `account_id`, `query` |
| `UserGet` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/users/{value.json.user_id}?{value.json.query}` | `finance/docusign-esignature/users/get` | `finance/docusign-esignature/users/get/response` | `access_token`, `account_id`, `query`, `user_id` |
| `EnvelopeCreate` | POST | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes` | `finance/docusign-esignature/envelopes/create` | `finance/docusign-esignature/envelopes/create/response` | `access_token`, `account_id`, `body` |
| `EnvelopeCreateFromTemplate` | POST | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes` | `finance/docusign-esignature/envelopes/create-from-template` | `finance/docusign-esignature/envelopes/create-from-template/response` | `access_token`, `account_id`, `body` |
| `EnvelopesList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes?{value.json.query}` | `finance/docusign-esignature/envelopes/list` | `finance/docusign-esignature/envelopes/list/response` | `access_token`, `account_id`, `query` |
| `EnvelopeGet` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}?{value.json.query}` | `finance/docusign-esignature/envelopes/get` | `finance/docusign-esignature/envelopes/get/response` | `access_token`, `account_id`, `envelope_id`, `query` |
| `EnvelopeAuditEvents` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/audit_events?{value.json.query}` | `finance/docusign-esignature/envelopes/audit-events` | `finance/docusign-esignature/envelopes/audit-events/response` | `access_token`, `account_id`, `envelope_id`, `query` |
| `EnvelopeFormData` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/form_data` | `finance/docusign-esignature/envelopes/form-data` | `finance/docusign-esignature/envelopes/form-data/response` | `access_token`, `account_id`, `envelope_id` |
| `EnvelopeCustomFields` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/custom_fields` | `finance/docusign-esignature/envelopes/custom-fields` | `finance/docusign-esignature/envelopes/custom-fields/response` | `access_token`, `account_id`, `envelope_id` |
| `RecipientsList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/recipients?{value.json.query}` | `finance/docusign-esignature/recipients/list` | `finance/docusign-esignature/recipients/list/response` | `access_token`, `account_id`, `envelope_id`, `query` |
| `RecipientTabsGet` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/recipients/{value.json.recipient_id}/tabs?{value.json.query}` | `finance/docusign-esignature/recipients/tabs` | `finance/docusign-esignature/recipients/tabs/response` | `access_token`, `account_id`, `envelope_id`, `query`, `recipient_id` |
| `RecipientViewCreate` | POST | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/views/recipient` | `finance/docusign-esignature/recipients/view` | `finance/docusign-esignature/recipients/view/response` | `access_token`, `account_id`, `body`, `envelope_id` |
| `DocumentsList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/documents?{value.json.query}` | `finance/docusign-esignature/documents/list` | `finance/docusign-esignature/documents/list/response` | `access_token`, `account_id`, `envelope_id`, `query` |
| `DocumentGet` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/documents/{value.json.document_id}?{value.json.query}` | `finance/docusign-esignature/documents/get` | `finance/docusign-esignature/documents/get/response` | `access_token`, `account_id`, `document_id`, `envelope_id`, `query` |
| `TemplatesList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/templates?{value.json.query}` | `finance/docusign-esignature/templates/list` | `finance/docusign-esignature/templates/list/response` | `access_token`, `account_id`, `query` |
| `TemplateGet` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/templates/{value.json.template_id}?{value.json.query}` | `finance/docusign-esignature/templates/get` | `finance/docusign-esignature/templates/get/response` | `access_token`, `account_id`, `query`, `template_id` |
| `TemplateRecipientsList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/templates/{value.json.template_id}/recipients?{value.json.query}` | `finance/docusign-esignature/templates/recipients` | `finance/docusign-esignature/templates/recipients/response` | `access_token`, `account_id`, `query`, `template_id` |
| `TemplateDocumentsList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/templates/{value.json.template_id}/documents?{value.json.query}` | `finance/docusign-esignature/templates/documents` | `finance/docusign-esignature/templates/documents/response` | `access_token`, `account_id`, `query`, `template_id` |
| `FoldersList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/folders?{value.json.query}` | `finance/docusign-esignature/folders/list` | `finance/docusign-esignature/folders/list/response` | `access_token`, `account_id`, `query` |
| `FolderItemsList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/folders/{value.json.folder_id}?{value.json.query}` | `finance/docusign-esignature/folders/items` | `finance/docusign-esignature/folders/items/response` | `access_token`, `account_id`, `folder_id`, `query` |
| `ConnectConfigsList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/connect` | `finance/docusign-esignature/connect/configs/list` | `finance/docusign-esignature/connect/configs/list/response` | `access_token`, `account_id` |
| `ConnectConfigGet` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/connect/{value.json.connect_id}` | `finance/docusign-esignature/connect/configs/get` | `finance/docusign-esignature/connect/configs/get/response` | `access_token`, `account_id`, `connect_id` |
| `ConnectFailuresList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/connect/failures?{value.json.query}` | `finance/docusign-esignature/connect/failures/list` | `finance/docusign-esignature/connect/failures/list/response` | `access_token`, `account_id`, `query` |
| `ConnectLogsList` | GET | `/restapi/v2.1/accounts/{value.json.account_id}/connect/logs?{value.json.query}` | `finance/docusign-esignature/connect/logs/list` | `finance/docusign-esignature/connect/logs/list/response` | `access_token`, `account_id`, `query` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DOCU_SIGN_ESIGNATURE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DocuSignESignatureRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_BASE_URI"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ServiceInformation
        WITH SOURCE_TOPIC "finance/docusign-esignature/service/info"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/service/info/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/service_information"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT AccountGet
        WITH SOURCE_TOPIC "finance/docusign-esignature/account/get"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/account/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UsersList
        WITH SOURCE_TOPIC "finance/docusign-esignature/users/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/users/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/users?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UserGet
        WITH SOURCE_TOPIC "finance/docusign-esignature/users/get"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/users/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/users/{value.json.user_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EnvelopeCreate
        WITH SOURCE_TOPIC "finance/docusign-esignature/envelopes/create"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/envelopes/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT EnvelopeCreateFromTemplate
        WITH SOURCE_TOPIC "finance/docusign-esignature/envelopes/create-from-template"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/envelopes/create-from-template/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT EnvelopesList
        WITH SOURCE_TOPIC "finance/docusign-esignature/envelopes/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/envelopes/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EnvelopeGet
        WITH SOURCE_TOPIC "finance/docusign-esignature/envelopes/get"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/envelopes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EnvelopeAuditEvents
        WITH SOURCE_TOPIC "finance/docusign-esignature/envelopes/audit-events"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/envelopes/audit-events/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/audit_events?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EnvelopeFormData
        WITH SOURCE_TOPIC "finance/docusign-esignature/envelopes/form-data"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/envelopes/form-data/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/form_data"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EnvelopeCustomFields
        WITH SOURCE_TOPIC "finance/docusign-esignature/envelopes/custom-fields"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/envelopes/custom-fields/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/custom_fields"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RecipientsList
        WITH SOURCE_TOPIC "finance/docusign-esignature/recipients/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/recipients/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/recipients?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RecipientTabsGet
        WITH SOURCE_TOPIC "finance/docusign-esignature/recipients/tabs"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/recipients/tabs/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/recipients/{value.json.recipient_id}/tabs?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RecipientViewCreate
        WITH SOURCE_TOPIC "finance/docusign-esignature/recipients/view"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/recipients/view/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/views/recipient"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DocumentsList
        WITH SOURCE_TOPIC "finance/docusign-esignature/documents/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/documents/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/documents?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT DocumentGet
        WITH SOURCE_TOPIC "finance/docusign-esignature/documents/get"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/documents/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/envelopes/{value.json.envelope_id}/documents/{value.json.document_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/pdf"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Transfer-Encoding" "base64"
    ADD EVENT TemplatesList
        WITH SOURCE_TOPIC "finance/docusign-esignature/templates/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/templates/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/templates?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT TemplateGet
        WITH SOURCE_TOPIC "finance/docusign-esignature/templates/get"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/templates/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/templates/{value.json.template_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT TemplateRecipientsList
        WITH SOURCE_TOPIC "finance/docusign-esignature/templates/recipients"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/templates/recipients/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/templates/{value.json.template_id}/recipients?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT TemplateDocumentsList
        WITH SOURCE_TOPIC "finance/docusign-esignature/templates/documents"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/templates/documents/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/templates/{value.json.template_id}/documents?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT FoldersList
        WITH SOURCE_TOPIC "finance/docusign-esignature/folders/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/folders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/folders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT FolderItemsList
        WITH SOURCE_TOPIC "finance/docusign-esignature/folders/items"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/folders/items/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/folders/{value.json.folder_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConnectConfigsList
        WITH SOURCE_TOPIC "finance/docusign-esignature/connect/configs/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/connect/configs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/connect"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConnectConfigGet
        WITH SOURCE_TOPIC "finance/docusign-esignature/connect/configs/get"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/connect/configs/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/connect/{value.json.connect_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConnectFailuresList
        WITH SOURCE_TOPIC "finance/docusign-esignature/connect/failures/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/connect/failures/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/connect/failures?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConnectLogsList
        WITH SOURCE_TOPIC "finance/docusign-esignature/connect/logs/list"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/connect/logs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/restapi/v2.1/accounts/{value.json.account_id}/connect/logs?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ServiceInformation` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'finance/docusign-esignature/service/info/response' &
mosquitto_pub -t 'finance/docusign-esignature/service/info' -m '{}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Docu Sign OAuth
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/docu-sign-oauth

LoT connector for DocuSign OAuth: exchange an externally signed JWT for an access token and read user info for the DocuSign eSignature connectors

Beta

> [!NOTE]
>
> **Beta.** This REST API app template is beta. Hub metadata sets `WITH STATUS "beta"`. The deployable `.lot` file does not include `ADD METADATA`.

## Overview

Client-mode REST API connectors for DocuSign eSignature: send inspection reports, test certificates and permits for signature from MQTT, follow envelope and recipient status, read signed field values and download the signed PDF with its certificate of completion, authenticated with the OAuth 2.0 JWT grant; a server-mode companion connector receives DocuSign Connect webhooks.

This is one of the templates in the DocuSign eSignature REST API app (`docusign-esignature`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["JwtToken: POST /oauth/token on DocuSignOAuth, form body grant\_type=urn:ietf:params:oauth:grant-type:jwt-bearer (baked in) + assertion (JWT RS256 signed outside the broker with the integration key's RSA private key; claims iss = integration key, sub = user ID GUID, aud = account-d.docusign.com / account.docusign.com without https\://, iat, exp \<= 1 h, scope 'signature impersonation'); returns access\_token, Bearer, expires\_in 3600, no refresh token", "UserInfo: GET /oauth/userinfo with Bearer -> accounts\[].account\_id + base\_uri (sets BASE\_ADDRESS and account\_id)", "Authorization: Bearer \{value.json.access\_token} on every eSignature event except ServiceInformation (no auth)", "One-time consent (browser): [https://account-d.docusign.com/oauth/auth?response\_type=code\&scope=signature%20impersonation\&client\_id=\<key>\&redirect\_uri=\<uri](https://account-d.docusign.com/oauth/auth?response_type=code\&scope=signature%20impersonation\&client_id=\<key>\&redirect_uri=\<uri)>, or organization admin consent", "Authorization Code grant and the legacy X-DocuSign-Authentication header not packaged"]
* **secrets**: \["DOCUSIGN\_INTEGRATION\_KEY", "DOCUSIGN\_USER\_ID", "DOCUSIGN\_PRIVATE\_KEY (for the external JWT signer only; never in the broker connector)", "DOCUSIGN\_ACCESS\_TOKEN (optional, current token)", "DOCUSIGN\_ACCOUNT\_ID"]
* **permissions**: The token acts as the impersonated user (permission profile must allow sending envelopes; Connect reads need account admin).
* **note**: Inject secrets with a LoT action (GET SECRET); never retain topics that carry a JWT or token; restrict finance/docusign-esignature/auth/# with ACLs. LoT cannot sign RS256, so a signer service publishes the JWT.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Docu Sign OAuth connector | no |
| `BaseUrl` | string | Docu Sign OAuth base URL without trailing slash (e.g. [https://account-d.docusign.com](https://account-d.docusign.com)) | yes |

`BASE_ADDRESS` default: `https://account-d.docusign.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `JwtToken` | POST | `/oauth/token` | `finance/docusign-esignature/auth/token` | `finance/docusign-esignature/auth/token/response` | `assertion` |
| `UserInfo` | GET | `/oauth/userinfo` | `finance/docusign-esignature/auth/userinfo` | `finance/docusign-esignature/auth/userinfo/response` | `access_token` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DOCU_SIGN_OAUTH"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DocuSignOAuth WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://account-d.docusign.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT JwtToken
        WITH SOURCE_TOPIC "finance/docusign-esignature/auth/token"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/auth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion={value.json.assertion}"
    ADD EVENT UserInfo
        WITH SOURCE_TOPIC "finance/docusign-esignature/auth/userinfo"
        WITH DESTINATION_TOPIC "finance/docusign-esignature/auth/userinfo/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/oauth/userinfo"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `JwtToken` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'finance/docusign-esignature/auth/token/response' &
mosquitto_pub -t 'finance/docusign-esignature/auth/token' -m '{"assertion": "<assertion>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Domo
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/domo

Connect Coreflux LoT to Domo: push plant data into DataSets and Streams, query DataSets with SQL, and read users, groups, pages and activity logs

Technical Preview

## Overview

A client-mode connector for the [Domo Platform APIs](https://developer.domo.com/portal/8ba9aedad3679-ap-is) (DataSet, Simple, Stream, User, Group, Page, Activity Log and Embed APIs). Use it to land plant data in Domo, such as OEE per minute, counters at shift end or historian tags, and to bring Domo results back to the shop floor: run SQL on a DataSet and publish the rows for an andon board or HMI, or issue an embed token to show a Domo card on a panel.

The connector `DomoRestApi` in `DomoRestApi.lot` has 33 events (20 GET, 6 POST, 6 PUT, 1 PATCH). 11 are writes: `DatasetCreate`, `DatasetUpdate`, `DatasetImport`, `SimpleDatasetCreate`, `SimpleImport`, `StreamCreate`, `StreamUpdate`, `StreamExecutionCreate`, `StreamPartUpload`, `StreamExecutionCommit`, `StreamExecutionAbort`. There are no DELETE events.

Domo Platform APIs run on one host for every customer: set `BASE_ADDRESS` to `https://api.domo.com` (already set in the template), with no trailing slash and no `/v1`. Topics use `analytics/domo/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

## Setup

1. Sign in at [developer.domo.com](https://developer.domo.com) with a Domo account of your instance and open **My Account > New Client**.
2. Give the client a name and the scopes the broker needs: `data` for DataSets and Streams, `user` for users and groups, `dashboard` for pages, `audit` for the activity log. Save the **Client ID** and **Client Secret**.
3. The client acts as the Domo user that created it. To write to a DataSet that user needs the **Manage DataSet** grant (or ownership of the DataSet).
4. Keep `DOMO_CLIENT_ID`, `DOMO_CLIENT_SECRET` and the derived `DOMO_BASIC_AUTH` (see below) in broker secrets and inject them with `GET SECRET`.

## Authentication

`OAuthToken` calls `GET /oauth/token?grant_type=client_credentials&scope=<scope>` with `Authorization: Basic <credentials>`. `basic_auth` is the Base64 of `<DOMO_CLIENT_ID>:<DOMO_CLIENT_SECRET>`; store it as the secret `DOMO_BASIC_AUTH`. `scope` is a space-separated subset of the client's scopes, URL-encoded (`data`, `data%20user`). The reply carries an `access_token` that is valid for about one hour. Every other event sends `Authorization: Bearer <access_token>` from the `access_token` field of the payload.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<DOMO_BASIC_AUTH>", "scope": "data%20user"}
```

> [!WARNING]
>
> `basic_auth` and `access_token` grant API access as the client's user. Never retain topics that carry them, restrict `analytics/domo/auth/#` and `analytics/domo/embed/#` with ACLs, and create a separate client for the broker. A wrong client ID or secret returns `401` with `{"error":"invalid_client"}`; an expired or malformed token returns `401` with a `WWW-Authenticate: Bearer error="invalid_token"` header. Ask for a new token before the hour runs out.

## Events

| Event | Request | Source topic | Notes |
| - | - | - | - |
| OAuthToken | `GET /oauth/token?grant_type=client_credentials&scope={value.json.scope}` | `analytics/domo/auth/token` | Get an access token (OAuth 2.0 client credentials, expires\_in about 3600 s). |
| DatasetsList | `GET /v1/datasets?{value.json.query}` | `analytics/domo/datasets/list` | List DataSets (scope data). |
| DatasetGet | `GET /v1/datasets/{value.json.dataset_id}` | `analytics/domo/datasets/get` | DataSet details: schema, rows, columns, owner, updatedAt. |
| DatasetCreate | `POST /v1/datasets` | `analytics/domo/datasets/create` | Write. Create a DataSet with a schema (column types STRING, DECIMAL, LONG, DOUBLE, DATE, DATETIME). |
| DatasetUpdate | `PUT /v1/datasets/{value.json.dataset_id}` | `analytics/domo/datasets/update` | Write. Update DataSet metadata (name, description, pdpEnabled, schema). |
| DatasetImport | `PUT /v1/datasets/{value.json.dataset_id}/data?updateMethod={value.json.update_method}` | `analytics/domo/datasets/import` | Write. Import CSV rows (catalog event). update\_method APPEND or REPLACE (uppercase; REPLACE replaces all rows). |
| DatasetExport | `GET /v1/datasets/{value.json.dataset_id}/data?{value.json.query}` | `analytics/domo/datasets/export` | Export DataSet rows as CSV (Accept text/csv). |
| DatasetQuery | `POST /v1/datasets/query/execute/{value.json.dataset_id}` | `analytics/domo/datasets/query` | Run SQL on one DataSet and publish columns, metadata and rows (read only; the table is always called table). |
| PdpPoliciesList | `GET /v1/datasets/{value.json.dataset_id}/policies` | `analytics/domo/datasets/policies/list` | Personalized Data Permission (PDP) policies of a DataSet (row-level filters). |
| PdpPolicyGet | `GET /v1/datasets/{value.json.dataset_id}/policies/{value.json.pdp_id}` | `analytics/domo/datasets/policies/get` | One PDP policy (filters, users, groups). |
| SimpleDatasetCreate | `POST /v1/json?name={value.json.name}&description={value.json.description}` | `analytics/domo/simple/create` | Write. Simple API: create a DataSet whose schema comes from the first JSON import. name / description URL-encoded (a space is %20). |
| SimpleImport | `PUT /v1/json/{value.json.dataset_id}/data?updateMethod={value.json.update_method}` | `analytics/domo/simple/import` | Write. Simple API: import a JSON array of row objects (Domo converts it to CSV). update\_method APPEND or REPLACE. |
| StreamsList | `GET /v1/streams?{value.json.query}` | `analytics/domo/streams/list` | List Streams (bulk upload pipes). |
| StreamsSearch | `GET /v1/streams/search?q={value.json.q}&fields={value.json.fields}` | `analytics/domo/streams/search` | Find the Stream of a DataSet. q: dataSource.id:\<dataset\_id> or dataSource.owner.id:\<user\_id>. fields: all, or a comma list of id,dataset,updateMethod,createdAt,modifiedAt. |
| StreamGet | `GET /v1/streams/{value.json.stream_id}?{value.json.query}` | `analytics/domo/streams/get` | One Stream with its DataSet. |
| StreamCreate | `POST /v1/streams` | `analytics/domo/streams/create` | Write. Create a Stream and its DataSet (Stream imports only work on DataSets created this way). updateMethod APPEND or REPLACE; keyColumnNames + APPEND makes an upsert DataSet. |
| StreamUpdate | `PATCH /v1/streams/{value.json.stream_id}?updateMethod={value.json.update_method}` | `analytics/domo/streams/update` | Write. Change the Stream's import behaviour (updateMethod is required as a query parameter). update\_method APPEND or REPLACE. |
| StreamExecutionsList | `GET /v1/streams/{value.json.stream_id}/executions?{value.json.query}` | `analytics/domo/streams/executions/list` | Executions (upload runs) of a Stream. |
| StreamExecutionGet | `GET /v1/streams/{value.json.stream_id}/executions/{value.json.execution_id}` | `analytics/domo/streams/executions/get` | One execution: currentState ACTIVE, SUCCESS, ERROR or ABORTED. |
| StreamExecutionCreate | `POST /v1/streams/{value.json.stream_id}/executions` | `analytics/domo/streams/executions/create` | Write. Start an upload run (catalog event). Returns the execution id used by StreamPartUpload, StreamExecutionCommit and StreamExecutionAbort. |
| StreamPartUpload | `PUT /v1/streams/{value.json.stream_id}/executions/{value.json.execution_id}/part/{value.json.part_id}` | `analytics/domo/streams/executions/part` | Write. Upload one part of CSV rows (no header) to an active execution. part\_id 1, 2, 3 ... in increasing order; retry a failed part with the same id. |
| StreamExecutionCommit | `PUT /v1/streams/{value.json.stream_id}/executions/{value.json.execution_id}/commit` | `analytics/domo/streams/executions/commit` | Write. Commit the execution: Domo imports all parts into the DataSet (catalog event). |
| StreamExecutionAbort | `PUT /v1/streams/{value.json.stream_id}/executions/{value.json.execution_id}/abort` | `analytics/domo/streams/executions/abort` | Write. Abort an active execution (its parts are discarded; the DataSet is unchanged). |
| UsersList | `GET /v1/users?{value.json.query}` | `analytics/domo/users/list` | List users (scope user). |
| UserGet | `GET /v1/users/{value.json.user_id}` | `analytics/domo/users/get` | One user (name, email, role, groups). |
| GroupsList | `GET /v1/groups?{value.json.query}` | `analytics/domo/groups/list` | List groups (scope user). |
| GroupGet | `GET /v1/groups/{value.json.group_id}` | `analytics/domo/groups/get` | One group. |
| GroupUsersList | `GET /v1/groups/{value.json.group_id}/users?{value.json.query}` | `analytics/domo/groups/users` | User ids in a group. |
| PagesList | `GET /v1/pages?{value.json.query}` | `analytics/domo/pages/list` | List pages (dashboards, scope dashboard). |
| PageGet | `GET /v1/pages/{value.json.page_id}` | `analytics/domo/pages/get` | One page with its card ids, owners and visibility. |
| PageCollectionsGet | `GET /v1/pages/{value.json.page_id}/collections` | `analytics/domo/pages/collections` | Card collections on a page. |
| AuditLogList | `GET /v1/audit?start={value.json.start}&{value.json.query}` | `analytics/domo/audit/list` | Activity log entries (scope audit). start: epoch milliseconds (required). |
| CardEmbedToken | `POST /v1/cards/embed/auth` | `analytics/domo/embed/cards/token` | Issue an embed token for embedded cards (Domo Everywhere programmatic filtering) to show a Domo card in an HMI. |

## Payloads

| Field | Used by | Content |
| - | - | - |
| `basic_auth` | `OAuthToken` | Base64 of `client_id:client_secret` |
| `scope` | `OAuthToken` | URL-encoded, space-separated scopes, for example `data%20user` |
| `access_token` | every event except `OAuthToken` | Token from `OAuthToken` |
| `dataset_id`, `stream_id`, `execution_id`, `part_id`, `pdp_id`, `user_id`, `group_id`, `page_id` | events with ids in the path | Domo ids (DataSet ids are UUIDs, the others are numbers) |
| `query` | list and export events, `StreamGet`, `AuditLogList` | URL query string without `?`, or `""`, for example `limit=50&offset=0&nameLike=OEE` |
| `update_method` | `DatasetImport`, `SimpleImport`, `StreamUpdate` | `APPEND` or `REPLACE`, uppercase (Domo falls back to `REPLACE` on anything else) |
| `csv` | `DatasetImport`, `StreamPartUpload` | CSV rows without a header, matching the DataSet schema, one row per line |
| `body` | JSON events | JSON object, or a JSON array of row objects for `SimpleImport` |
| `q`, `fields` | `StreamsSearch` | `dataSource.id:<dataset_id>` and `all` |
| `start` | `AuditLogList` | Epoch milliseconds (required) |
| `name`, `description` | `SimpleDatasetCreate` | URL-encoded DataSet name and description |

## Basic Syntax

An excerpt of the template (the full file has all 33 events and comments):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DomoRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.domo.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT OAuthToken
        WITH SOURCE_TOPIC "analytics/domo/auth/token"
        WITH DESTINATION_TOPIC "analytics/domo/auth/token/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/oauth/token?grant_type=client_credentials&scope={value.json.scope}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    ADD EVENT DatasetImport
        WITH SOURCE_TOPIC "analytics/domo/datasets/import"
        WITH DESTINATION_TOPIC "analytics/domo/datasets/import/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v1/datasets/{value.json.dataset_id}/data?updateMethod={value.json.update_method}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "text/csv"
        WITH BODY "{value.json.csv}"
    ADD EVENT DatasetQuery
        WITH SOURCE_TOPIC "analytics/domo/datasets/query"
        WITH DESTINATION_TOPIC "analytics/domo/datasets/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/datasets/query/execute/{value.json.dataset_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT SimpleImport
        WITH SOURCE_TOPIC "analytics/domo/simple/import"
        WITH DESTINATION_TOPIC "analytics/domo/simple/import/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v1/json/{value.json.dataset_id}/data?updateMethod={value.json.update_method}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT StreamExecutionCreate
        WITH SOURCE_TOPIC "analytics/domo/streams/executions/create"
        WITH DESTINATION_TOPIC "analytics/domo/streams/executions/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/streams/{value.json.stream_id}/executions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY ""
    ADD EVENT StreamPartUpload
        WITH SOURCE_TOPIC "analytics/domo/streams/executions/part"
        WITH DESTINATION_TOPIC "analytics/domo/streams/executions/part/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v1/streams/{value.json.stream_id}/executions/{value.json.execution_id}/part/{value.json.part_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "text/csv"
        WITH BODY "{value.json.csv}"
    ADD EVENT StreamExecutionCommit
        WITH SOURCE_TOPIC "analytics/domo/streams/executions/commit"
        WITH DESTINATION_TOPIC "analytics/domo/streams/executions/commit/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v1/streams/{value.json.stream_id}/executions/{value.json.execution_id}/commit"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY ""
```

## Examples

### Keep a token for the other actions

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DomoToken
ON EVERY 50 MINUTES DO
    SET "auth" WITH GET SECRET "DOMO_BASIC_AUTH"
    PUBLISH TOPIC "analytics/domo/auth/token" WITH { "basic_auth": {auth}, "scope": "data%20user" }

DEFINE ACTION DomoKeepToken
ON TOPIC "analytics/domo/auth/token/response" DO
    SET "token" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "state/domo/access_token" WITH {token}
```

### Append OEE samples to a DataSet

The Simple API takes JSON rows and converts them to CSV. Create the DataSet once with `SimpleDatasetCreate` (the first import sets the schema) or with `DatasetCreate` and an explicit schema, then append:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DomoAppendOee
ON TOPIC "plant/line2/oee" DO
    SET "token" WITH GET TOPIC "state/domo/access_token" AS STRING
    SET "ts" WITH GET JSON "ts" IN PAYLOAD AS STRING
    SET "oee" WITH GET JSON "oee" IN PAYLOAD AS DOUBLE
    PUBLISH TOPIC "analytics/domo/simple/import" WITH { "access_token": {token}, "dataset_id": "0c1e0dbe-9f71-4625-9b50-b79e6e4266f2", "update_method": "APPEND", "body": [ { "ts": {ts}, "line": "Line 2", "oee": {oee} } ] }
```

The same rows as CSV, published to `analytics/domo/datasets/import` (Domo answers `204` with an empty body):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "dataset_id": "0c1e0dbe-9f71-4625-9b50-b79e6e4266f2", "update_method": "APPEND", "csv": "2026-10-05T10:00:00,Line 2,0.87\n2026-10-05T10:01:00,Line 2,0.86\n"}
```

### Bulk load with the Stream API

For large or frequent loads, create a Stream once with `StreamCreate` (it creates its own DataSet; Stream imports only work on DataSets created this way). Then for each load:

1. Publish `{"access_token": "<access_token>", "stream_id": "42"}` to `analytics/domo/streams/executions/create`. The reply carries the execution `id`.
2. Publish each part to `analytics/domo/streams/executions/part` with `part_id` 1, 2, 3 and so on. Parts can be sent in parallel; retry a failed part with the same `part_id`.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "stream_id": "42", "execution_id": "1", "part_id": "1", "csv": "2026-10-05T10:00:00,L2.Temp,71.5\n2026-10-05T10:00:00,L2.Pressure,3.2\n"}
```

3. Publish `{"access_token": "<access_token>", "stream_id": "42", "execution_id": "1"}` to `analytics/domo/streams/executions/commit`. Domo imports all parts at once. Use `analytics/domo/streams/executions/abort` instead to drop the parts.

### Query a DataSet and publish the rows

Publish to `analytics/domo/datasets/query`. The table is always called `table`. The reply has `columns`, `metadata` and `rows`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "dataset_id": "0c1e0dbe-9f71-4625-9b50-b79e6e4266f2", "body": {"sql": "SELECT line, AVG(oee) AS oee FROM table GROUP BY line"}}
```

## Notes

* Use `DatasetImport` or `SimpleImport` for small DataSets that are updated now and then, and the Stream API for large or fast-growing DataSets, as Domo recommends. `REPLACE` replaces every row; the schema must match on every import.
* `StreamsSearch` with `q` `dataSource.id:<dataset_id>` finds the Stream of a DataSet. `StreamExecutionGet` shows `currentState` (`ACTIVE`, `SUCCESS`, `ERROR`, `ABORTED`).
* `DatasetExport` returns CSV (`Accept: text/csv`), published as received. For large DataSets query only the rows you need with `DatasetQuery`.
* `CardEmbedToken` needs a card embed id from Domo Everywhere and returns a token for the embed page. Treat the reply like a credential.
* List events default to 50 items (`limit` up to 50 for DataSets, 500 for users and Streams); page with `offset`.
* Not packaged on purpose: every DELETE (DataSets, Streams, PDP policies, groups, pages, collections, group members), user, group and page writes, PDP policy writes, the Account and Projects APIs, gzip-compressed parts, and the instance Product APIs (`<instance>.domo.com/api/...` with developer tokens).
* Domo's data platform business is now part of Progress Software; the Platform API host and the OAuth flow are unchanged.


# Dropbox
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dropbox

Connect Coreflux LoT to Dropbox API v2: upload and download plant files, watch folders, search, move, archive and share files from MQTT

Technical Preview

## Overview

Client-mode connectors for the [Dropbox API v2](https://docs.dropboxapi.com/dropbox-api/docs/overview) that move plant files between the broker and Dropbox. A typical flow writes a shift report, batch record or alarm snapshot as a JSON or CSV file into a plant folder, reads a recipe or configuration file back when a line changes over, watches an inbox folder for files that people drop in (cursor plus longpoll, no polling loop), moves processed files to an archive folder, and hands out a temporary link or a shared link to a report. File requests let technicians and suppliers upload photos, certificates and PDFs into a plant folder without a Dropbox account.

Dropbox splits its API over three hosts with different request formats, so the template file `DropboxRestApi.lot` holds three connectors:

| Connector | Base address | Format | Events |
| - | - | - | - |
| `DropboxRestApi` | `https://api.dropboxapi.com` | RPC: `POST`, JSON argument in the body, JSON result. Also `/oauth2/token`. | 34 |
| `DropboxContentRestApi` | `https://content.dropboxapi.com` | Upload and download: JSON argument in the `Dropbox-API-Arg` header, file bytes in the body | 3 |
| `DropboxNotifyRestApi` | `https://notify.dropboxapi.com` | `files/list_folder/longpoll` only, without an `Authorization` header | 1 |

The connectors carry 38 events (36 POST, 2 GET; 13 writes, no delete). Topics use `storage/dropbox/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. In the [App Console](https://www.dropbox.com/developers/apps), create a **Scoped access** app. Pick **App folder** to keep the broker inside `/Apps/<app name>/`, or **Full Dropbox** if it must reach existing team folders. Paths in payloads are relative to that root.
2. Under **Permissions**, enable the scopes the events need: `account_info.read`, `files.metadata.read`, `files.metadata.write`, `files.content.read`, `files.content.write`, `sharing.read`, `sharing.write`, `file_requests.read`, `file_requests.write`. Leave out the ones you do not use.
3. Authorise the app once with `token_access_type=offline` (for example `https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&token_access_type=offline&response_type=code`) and exchange the code at `/oauth2/token`. Keep the refresh token, app key and app secret in broker secrets (for example `DROPBOX_REFRESH_TOKEN`, `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET`). For a quick test, **Generate access token** on the app's settings page gives a short-lived token.
4. Keep the current access token in a broker secret (for example `DROPBOX_ACCESS_TOKEN`) and inject it in a LoT action with `GET SECRET`. Never retain topics that carry it.

## Authentication

Every event on `DropboxRestApi` and `DropboxContentRestApi` sends `Authorization: Bearer <token>` built from the `access_token` field of the payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_DROPBOX_ACCESS_TOKEN"}
```

Dropbox access tokens are short-lived: `/oauth2/token` returns `expires_in` 14400 (4 hours). Refresh the token before it expires with `OAuthTokenRefresh` (`storage/dropbox/oauth/token/refresh`). That event sends no `Authorization` header; the app key and secret travel in the form:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"form": "grant_type=refresh_token&refresh_token=<DROPBOX_REFRESH_TOKEN>&client_id=<DROPBOX_APP_KEY>&client_secret=<DROPBOX_APP_SECRET>"}
```

> [!WARNING]
>
> The `OAuthTokenRefresh` response carries the new `access_token`, and the request carries the app secret. Restrict `storage/dropbox/oauth/#` with ACLs, never retain those topics, and store the new token in the secret instead of passing it around on open topics.

`FolderLongpoll` takes no token at all. Dropbox answers `400` if a longpoll request includes an `Authorization` header, so `DropboxNotifyRestApi` sends none.

## Payloads

| Connector | Fields |
| - | - |
| `DropboxRestApi` | `access_token` and `body` (JSON object, the function's argument). `AccountGetCurrent` and `SpaceUsageGet` take no argument (the connector sends JSON `null`). `OAuthTokenRefresh` takes `form` only. |
| `DropboxContentRestApi` | `access_token`, `arg` (JSON object sent in the `Dropbox-API-Arg` header) and, for `FileUpload`, `content` (the file body). |
| `DropboxNotifyRestApi` | `body` with `cursor` and `timeout` (30 to 480 seconds). |

Paths are relative to the app folder or the Dropbox root. The root is `""`; every other path starts with `/` and never ends with `/`. File ids (`id:...`) work wherever the reference accepts a path or id. The `Dropbox-API-Arg` header must be HTTP-header-safe: escape non-ASCII characters and `0x7F` as `\uXXXX` (a standard JSON encoder with ASCII output does this).

## Examples

Write a shift report as a JSON file (`storage/dropbox/files/upload`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "arg": {"path": "/Coreflux/Porto/line-2/2026-10-05-shift-A.json", "mode": "add", "autorename": true, "mute": true}, "content": {"line": "2", "shift": "A", "oee": 0.87, "scrap": 14}}
```

Dropbox answers with the file metadata (`id`, `rev`, `size`, `content_hash`). Use `"mode": "overwrite"` to replace a file, or `{".tag": "update", "update": "<rev>"}` to replace it only if nobody changed it since that revision.

Read a recipe back on changeover (`storage/dropbox/files/download`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "arg": {"path": "/Coreflux/Porto/line-2/recipe.json"}}
```

The response body is the file content. Dropbox sends the file metadata in the `Dropbox-API-Result` response header. Keep downloads to text and JSON files that fit an MQTT message.

Watch an inbox folder for new files without polling:

1. Get a cursor for future changes (`storage/dropbox/folders/latest-cursor/get`):

   ```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
   {"access_token": "<token>", "body": {"path": "/Coreflux/Porto/inbox", "recursive": true}}
   ```

2. Wait for a change (`storage/dropbox/folders/longpoll`, no token). The call blocks for up to `timeout` seconds plus up to 90 seconds of jitter, then returns `{"changes": true}` or `{"changes": false}`, sometimes with `backoff` (seconds to wait before the next longpoll):

   ```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
   {"body": {"cursor": "<cursor>", "timeout": 120}}
   ```

3. When `changes` is true, list them (`storage/dropbox/folders/list/continue`) and store the new cursor from the response:

   ```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
   {"access_token": "<token>", "body": {"cursor": "<cursor>"}}
   ```

A `409` with `reset` means the cursor expired. Start again with `FolderList` or `FolderLatestCursorGet`.

Archive a processed file instead of deleting it (`storage/dropbox/files/move`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "body": {"from_path": "/Coreflux/Porto/inbox/report.csv", "to_path": "/Coreflux/Porto/archive/2026-10/report.csv", "autorename": true}}
```

Hand a firmware file to an edge device with a direct link that expires after four hours (`storage/dropbox/files/temporary-link/get`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "body": {"path": "/Coreflux/firmware/gw-2.4.1.bin"}}
```

Ask a technician for photos of a failed bearing (`storage/dropbox/file-requests/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "body": {"title": "Press 7 bearing photos", "destination": "/Coreflux/Porto/maintenance/press-7", "open": true, "description": "Work order WO-4711"}}
```

## Events

| Event | Connector | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - | - |
| `CheckUser` | API | `POST` | `/2/check/user` | `storage/dropbox/connection/check` | | Smoke: Dropbox echoes query back if the access token is valid (preview endpoint, no side effects). body: `{"query":"porto-line-2"}`. |
| `AccountGetCurrent` | API | `POST` | `/2/users/get_current_account` | `storage/dropbox/account/get-current` | | The account behind the token (account\_id, email, name, team, root\_info.root\_namespace\_id). No argument: the connector sends JSON null. |
| `SpaceUsageGet` | API | `POST` | `/2/users/get_space_usage` | `storage/dropbox/account/space-usage/get` | | Used and allocated space (individual or team allocation), e.g. to alarm before uploads start failing. No argument. |
| `AccountGet` | API | `POST` | `/2/users/get_account` | `storage/dropbox/accounts/get` | | Another account by id, e.g. who modified a file (sharing\_info.modified\_by). body: `{"account_id":"dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"}`. |
| `FolderList` | API | `POST` | `/2/files/list_folder` | `storage/dropbox/folders/list` | | Catalog 'POST files/list\_folder'. First page of a folder plus a cursor (keep it: it also returns later changes). body: `{"path":"/Coreflux/Porto/line-2","recursive":false,"limit":200}` ("" = root). |
| `FolderListContinue` | API | `POST` | `/2/files/list_folder/continue` | `storage/dropbox/folders/list/continue` | | Next page, or the changes since the cursor was issued (new / changed files, deleted entries). Always store the new cursor; 409 reset means start again with FolderList. body: `{"cursor":"AAH4f..."}`. |
| `FolderLatestCursorGet` | API | `POST` | `/2/files/list_folder/get_latest_cursor` | `storage/dropbox/folders/latest-cursor/get` | | A cursor for 'changes from now on' without listing the folder first (then FolderLongpoll + FolderListContinue). body: same as FolderList, e.g. `{"path":"/Coreflux/Porto/inbox","recursive":true}`. |
| `FolderCreate` | API | `POST` | `/2/files/create_folder_v2` | `storage/dropbox/folders/create` | Yes | Create a folder, e.g. one per line, batch or day. body: `{"path":"/Coreflux/Porto/line-2/2026-10-05","autorename":false}`. 409 path/conflict/folder if it exists. |
| `FolderCreateBatch` | API | `POST` | `/2/files/create_folder_batch` | `storage/dropbox/folders/create-batch` | Yes | Create up to 10000 folders in one call (e.g. a folder tree for a new plant). body: `{"paths":["/Coreflux/Porto/line-1","/Coreflux/Porto/line-2"],"autorename":false,"force_async":false}`. May return async\_job\_id; poll FolderCreateBatchCheck. |
| `FolderCreateBatchCheck` | API | `POST` | `/2/files/create_folder_batch/check` | `storage/dropbox/folders/create-batch/check` | | Status of an async folder batch. body: `{"async_job_id":"<id from FolderCreateBatch>"}`. |
| `MetadataGet` | API | `POST` | `/2/files/get_metadata` | `storage/dropbox/files/metadata/get` | | Metadata of one file or folder (id, rev, size, server\_modified, content\_hash). body: `{"path":"/Coreflux/Porto/line-2/recipe.json","include_deleted":false}` (path or "id:..."). |
| `Search` | API | `POST` | `/2/files/search_v2` | `storage/dropbox/files/search` | | Search names (and content on paid plans) under a folder. body: `{"query":"press-7","options":{"path":"/Coreflux/Porto","max_results":50,"file_extensions":["pdf","csv"],"file_status":"active"}}`. |
| `SearchContinue` | API | `POST` | `/2/files/search/continue_v2` | `storage/dropbox/files/search/continue` | | Next page of a search (has\_more true). body: `{"cursor":"<cursor from Search>"}`. |
| `FileCopy` | API | `POST` | `/2/files/copy_v2` | `storage/dropbox/files/copy` | Yes | Copy a file or folder, e.g. a recipe template into a new batch folder. body: `{"from_path":"/Coreflux/templates/batch.json","to_path":"/Coreflux/Porto/line-2/batch-1005-A.json","autorename":true}`. |
| `FileMove` | API | `POST` | `/2/files/move_v2` | `storage/dropbox/files/move` | Yes | Move or rename a file or folder; archive processed files instead of deleting them. body: `{"from_path":"/Coreflux/Porto/inbox/report.csv","to_path":"/Coreflux/Porto/archive/2026-10/report.csv","autorename":true}`. |
| `CopyBatch` | API | `POST` | `/2/files/copy_batch_v2` | `storage/dropbox/files/copy-batch` | Yes | Copy up to 1000 entries in one async job. body: `{"entries":[{"from_path":"/Coreflux/templates/a.json","to_path":"/Coreflux/Porto/line-2/a.json"}],"autorename":true}`. Poll CopyBatchCheck with the async\_job\_id. |
| `CopyBatchCheck` | API | `POST` | `/2/files/copy_batch/check_v2` | `storage/dropbox/files/copy-batch/check` | | Status of an async copy batch (in\_progress / complete with per-entry results). body: `{"async_job_id":"<id>"}`. |
| `MoveBatch` | API | `POST` | `/2/files/move_batch_v2` | `storage/dropbox/files/move-batch` | Yes | Move up to 1000 entries in one async job (e.g. archive a whole shift). body: `{"entries":[{"from_path":"/Coreflux/Porto/inbox/a.csv","to_path":"/Coreflux/Porto/archive/a.csv"}],"autorename":true}`. Poll MoveBatchCheck. |
| `MoveBatchCheck` | API | `POST` | `/2/files/move_batch/check_v2` | `storage/dropbox/files/move-batch/check` | | Status of an async move batch. body: `{"async_job_id":"<id>"}`. |
| `TemporaryLinkGet` | API | `POST` | `/2/files/get_temporary_link` | `storage/dropbox/files/temporary-link/get` | | A direct download link valid for 4 hours (e.g. hand a firmware or recipe file to an edge device over HTTP). body: `{"path":"/Coreflux/firmware/gw-2.4.1.bin"}`. |
| `TemporaryUploadLinkGet` | API | `POST` | `/2/files/get_temporary_upload_link` | `storage/dropbox/files/temporary-upload-link/get` | | A one-time upload link (60..14400 s) so a gateway or camera can POST a file directly (Content-Type application/octet-stream) without a token. body: `{"commit_info":{"path":"/Coreflux/Porto/cam-3/2026-10-05T14-20.jpg","mode":"add","autorename":true},"duration":3600}`. No file changes until the link is used. |
| `RevisionsList` | API | `POST` | `/2/files/list_revisions` | `storage/dropbox/files/revisions/list` | | Revisions of a file (who and when changed a recipe or config). body: `{"path":"/Coreflux/Porto/line-2/recipe.json","mode":"path","limit":10}`. |
| `FileRestore` | API | `POST` | `/2/files/restore` | `storage/dropbox/files/restore` | Yes | Restore a file to an earlier revision (roll back a bad recipe or config). body: `{"path":"/Coreflux/Porto/line-2/recipe.json","rev":"a1c10ce0dd78"}` (rev from RevisionsList). |
| `SaveUrl` | API | `POST` | `/2/files/save_url` | `storage/dropbox/files/save-url` | Yes | Dropbox downloads a public URL into a file (e.g. a nightly CSV export or a camera snapshot URL); the transfer must finish within 15 minutes. body: `{"path":"/Coreflux/Porto/exports/2026-10-05-oee.csv","url":"https://broker.example.com/exports/oee.csv"}`. Poll SaveUrlCheck with async\_job\_id. |
| `SaveUrlCheck` | API | `POST` | `/2/files/save_url/check_job_status` | `storage/dropbox/files/save-url/check` | | Status of a save\_url job (in\_progress / complete with metadata / failed). body: `{"async_job_id":"<id from SaveUrl>"}`. |
| `TagsAdd` | API | `POST` | `/2/files/tags/add` | `storage/dropbox/files/tags/add` | Yes | Tag a file or folder (preview endpoint; tag\_text is 1..32 word characters, lower-cased by Dropbox, at most 20 tags per item). body: `{"path":"/Coreflux/Porto/line-2/batch-1005-A.json","tag_text":"qa_released"}`. |
| `TagsGet` | API | `POST` | `/2/files/tags/get` | `storage/dropbox/files/tags/get` | | Tags on files or folders (preview endpoint). body: `{"paths":["/Coreflux/Porto/line-2/batch-1005-A.json"]}`. |
| `SharedLinkCreate` | API | `POST` | `/2/sharing/create_shared_link_with_settings` | `storage/dropbox/shared-links/create` | Yes | Create a shared link to a report or folder (409 shared\_link\_already\_exists returns the existing link's metadata). body: `{"path":"/Coreflux/Porto/reports/2026-W41.pdf","settings":{"audience":"team","access":"viewer","allow_download":true}}` (team audience needs a team account; basic users cannot set expires). |
| `SharedLinksList` | API | `POST` | `/2/sharing/list_shared_links` | `storage/dropbox/shared-links/list` | | Shared links of a path, or all links of the account (cursor paging). body: `{"path":"/Coreflux/Porto/reports/2026-W41.pdf","direct_only":true}` or `{}` or `{"cursor":"..."}`. |
| `SharedLinkMetadataGet` | API | `POST` | `/2/sharing/get_shared_link_metadata` | `storage/dropbox/shared-links/metadata/get` | | Metadata behind a shared link (name, size, link\_permissions, expires). body: `{"url":"https://www.dropbox.com/scl/fi/abc123/report.pdf?rlkey=xyz&dl=0"}`. |
| `SharedLinkSettingsUpdate` | API | `POST` | `/2/sharing/modify_shared_link_settings` | `storage/dropbox/shared-links/settings/update` | Yes | Change who can open a shared link or let it expire (instead of revoking it). body: `{"url":"https://www.dropbox.com/scl/fi/abc123/report.pdf?rlkey=xyz&dl=0","settings":{"audience":"no_one"},"remove_expiration":false}`. |
| `FileRequestCreate` | API | `POST` | `/2/file_requests/create` | `storage/dropbox/file-requests/create` | Yes | Open a file request so technicians or suppliers upload photos, certificates or PDFs into a plant folder without an account. body: `{"title":"Press 7 bearing photos","destination":"/Coreflux/Porto/maintenance/press-7","open":true,"description":"Work order WO-4711"}` (deadline only on Professional and Business accounts). |
| `FileRequestsList` | API | `POST` | `/2/file_requests/list_v2` | `storage/dropbox/file-requests/list` | | File requests of the account (id, url, destination, file\_count, is\_open). body: `{"limit":100}`. |
| `OAuthTokenRefresh` | API | `POST` | `/oauth2/token` | `storage/dropbox/oauth/token/refresh` | | Exchange the long-lived refresh token for a new short-lived access token (expires\_in 14400 s). No Authorization header; app key and secret go in the form. form: `grant_type=refresh_token&refresh_token=<DROPBOX_REFRESH_TOKEN>&client_id=<DROPBOX_APP_KEY>&client_secret=<DROPBOX_APP_SECRET>`. The response carries access\_token: never retain it, restrict storage/dropbox/oauth/# with ACLs. |
| `FileUpload` | Content | `POST` | `/2/files/upload` | `storage/dropbox/files/upload` | Yes | Catalog 'POST files/upload'. Write the MQTT payload's content as a file (JSON record, CSV, text, up to 150 MiB by spec; keep MQTT payloads small). arg: `{"path":"/Coreflux/Porto/line-2/2026-10-05-shift-A.json","mode":"add","autorename":true,"mute":true}` (or "mode":"overwrite", or `{".tag":"update","update":"<rev>"}` for safe edits). content: the file body. Returns FileMetadata (id, rev, size, content\_hash). |
| `FileDownload` | Content | `GET` | `/2/files/download` | `storage/dropbox/files/download` | | Read a file back (recipe, config, setpoint table). The response body is the file content; the metadata is in the Dropbox-API-Result response header. arg: `{"path":"/Coreflux/Porto/line-2/recipe.json"}` (optionally "rev"). Text and JSON files only through MQTT. |
| `SharedLinkFileGet` | Content | `GET` | `/2/sharing/get_shared_link_file` | `storage/dropbox/shared-links/file/get` | | Read a file through a shared link (e.g. a supplier's spec sheet shared with the plant). arg: `{"url":"https://www.dropbox.com/scl/fi/abc123/spec.json?rlkey=xyz&dl=0"}` (add "path" for a file inside a shared folder link). |
| `FolderLongpoll` | Notify | `POST` | `/2/files/list_folder/longpoll` | `storage/dropbox/folders/longpoll` | | Wait for changes under a cursor without polling: blocks up to timeout (30..480 s, plus up to 90 s jitter) and returns `{"changes":true\|false,"backoff":<s>}`; on true call FolderListContinue. No Authorization header (Dropbox answers 400 if one is sent). body: `{"cursor":"<cursor from FolderList / FolderLatestCursorGet>","timeout":120}`. Connector timeout is 600 s. |

## Limits

* Dropbox rate-limits per linked user (per team for team-linked apps) and does not publish the numbers. Above the limit it answers `429` with a `Retry-After` header. Wait that long, and batch work (`FolderCreateBatch`, `CopyBatch`, `MoveBatch`) instead of sending many single calls.
* `FileUpload` accepts up to 150 MiB per file, but keep MQTT payloads small. Larger files need upload sessions, which are not packaged.
* On Dropbox Business plans with a data transport limit, upload and download calls count against the team's monthly allowance. Over the limit Dropbox answers `403` `invalid_account_type/feature`.
* `FolderList` returns at most 2000 entries per page; follow `has_more` with `FolderListContinue`. `FolderLongpoll` accepts a `timeout` from 30 to 480 seconds, and the notify connector allows 600 seconds per request.
* Temporary links expire after four hours. Temporary upload links last 60 to 14400 seconds. `SaveUrl` transfers must finish within 15 minutes.

## Not packaged

* Delete-style functions on purpose: `files/delete_v2`, `delete_batch`, `permanently_delete`, `files/tags/remove`, shared link revoke and file request delete. Archive files with `FileMove` instead.
* Upload sessions (`upload_session/start`, `append_v2`, `finish`, batch variants) for files over 150 MiB, and binary downloads such as thumbnails, previews, `download_zip` and `export`.
* Team (Business) endpoints and the `Dropbox-API-Select-User`, `Dropbox-API-Select-Admin` and `Dropbox-API-Path-Root` headers for team spaces. Shared folder membership, Paper, file properties templates, file locking, contacts and account administration.
* Webhooks. Dropbox registers webhook URIs in the App Console, not through the API. A receiver would be a separate `ENABLE_SERVER` REST\_API connector that answers the `GET` verification by echoing `challenge` within ten seconds and checks `X-Dropbox-Signature` (HMAC-SHA256 of the body with the app secret). Notifications only carry account ids, so the connector would then call `FolderListContinue`. `FolderLongpoll` covers the same need without a public endpoint.


# Dropbox Content
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dropbox-content

LoT connector for the Dropbox content host: upload files from MQTT, download files and fetch shared link files with an OAuth 2.0 access token

Technical Preview

## Overview

Client-mode REST API connectors for Dropbox: upload shift reports, batch records and alarm snapshots from MQTT as files, download recipes and configs, watch folders for new files with a cursor and longpoll, search, copy, move to archive, restore revisions, save URLs, tag files, and share them with temporary links, shared links and file requests.

This is one of the templates in the Dropbox REST API app (`dropbox`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector). See [Dropbox](/latest/lot-language/routes/rest-api-apps/dropbox) for the package overview.

## Auth

* **schemes**: \["Authorization: Bearer \{value.json.access\_token} on every DropboxRestApi and DropboxContentRestApi event except OAuthTokenRefresh (OAuth 2.0 access token of a scoped Dropbox app; short-lived, expires\_in 14400 s)", "OAuthTokenRefresh: POST [https://api.dropboxapi.com/oauth2/token](https://api.dropboxapi.com/oauth2/token), application/x-www-form-urlencoded \{value.json.form} = grant\_type=refresh\_token\&refresh\_token=...\&client\_id=\<app key>\&client\_secret=\<app secret>, no Authorization header", "FolderLongpoll (notify host): no Authorization header (Dropbox answers 400 'Your request includes an Authorization header, but this function does not use it.')"]
* **secrets**: \["DROPBOX\_ACCESS\_TOKEN", "DROPBOX\_REFRESH\_TOKEN", "DROPBOX\_APP\_KEY", "DROPBOX\_APP\_SECRET"]
* **scopes**: \["account\_info.read", "file\_requests.read", "file\_requests.write", "files.content.read", "files.content.write", "files.metadata.read", "files.metadata.write", "sharing.read", "sharing.write"]
* **note**: Inject secrets with a LoT action (GET SECRET); never retain topics that carry the token, refresh token or app secret; restrict storage/dropbox/oauth/# with ACLs (the refresh response carries the new access token). Authorise once with token\_access\_type=offline to get a refresh token. App folder apps see only /Apps/\<app>/.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Dropbox Content connector | no |
| `BaseUrl` | string | Dropbox Content base URL without trailing slash (e.g. [https://content.dropboxapi.com](https://content.dropboxapi.com)) | yes |

`BASE_ADDRESS` default: `https://content.dropboxapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `FileUpload` | POST | `/2/files/upload` | `storage/dropbox/files/upload` | `storage/dropbox/files/upload/response` | `access_token`, `arg`, `content` |
| `FileDownload` | GET | `/2/files/download` | `storage/dropbox/files/download` | `storage/dropbox/files/download/response` | `access_token`, `arg` |
| `SharedLinkFileGet` | GET | `/2/sharing/get_shared_link_file` | `storage/dropbox/shared-links/file/get` | `storage/dropbox/shared-links/file/get/response` | `access_token`, `arg` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DROPBOX_CONTENT"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DropboxContentRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://content.dropboxapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/octet-stream"
    ADD EVENT FileUpload
        WITH SOURCE_TOPIC "storage/dropbox/files/upload"
        WITH DESTINATION_TOPIC "storage/dropbox/files/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2/files/upload"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Dropbox-API-Arg" "{value.json.arg}"
            ADD "Content-Type" "application/octet-stream"
        WITH BODY "{value.json.content}"
    ADD EVENT FileDownload
        WITH SOURCE_TOPIC "storage/dropbox/files/download"
        WITH DESTINATION_TOPIC "storage/dropbox/files/download/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/files/download"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Dropbox-API-Arg" "{value.json.arg}"
    ADD EVENT SharedLinkFileGet
        WITH SOURCE_TOPIC "storage/dropbox/shared-links/file/get"
        WITH DESTINATION_TOPIC "storage/dropbox/shared-links/file/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2/sharing/get_shared_link_file"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Dropbox-API-Arg" "{value.json.arg}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `FileUpload` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'storage/dropbox/files/upload/response' &
mosquitto_pub -t 'storage/dropbox/files/upload' -m '{"access_token": "<access_token>", "arg": "<arg>", "content": "<content>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Dropbox Notify
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dropbox-notify

LoT connector for the Dropbox notify host: longpoll a folder cursor so the broker learns when files change, without sending an access token

Technical Preview

## Overview

Client-mode REST API connectors for Dropbox: upload shift reports, batch records and alarm snapshots from MQTT as files, download recipes and configs, watch folders for new files with a cursor and longpoll, search, copy, move to archive, restore revisions, save URLs, tag files, and share them with temporary links, shared links and file requests.

This is one of the templates in the Dropbox REST API app (`dropbox`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector). See [Dropbox](/latest/lot-language/routes/rest-api-apps/dropbox) for the package overview.

## Auth

* **schemes**: \["Authorization: Bearer \{value.json.access\_token} on every DropboxRestApi and DropboxContentRestApi event except OAuthTokenRefresh (OAuth 2.0 access token of a scoped Dropbox app; short-lived, expires\_in 14400 s)", "OAuthTokenRefresh: POST [https://api.dropboxapi.com/oauth2/token](https://api.dropboxapi.com/oauth2/token), application/x-www-form-urlencoded \{value.json.form} = grant\_type=refresh\_token\&refresh\_token=...\&client\_id=\<app key>\&client\_secret=\<app secret>, no Authorization header", "FolderLongpoll (notify host): no Authorization header (Dropbox answers 400 'Your request includes an Authorization header, but this function does not use it.')"]
* **secrets**: \["DROPBOX\_ACCESS\_TOKEN", "DROPBOX\_REFRESH\_TOKEN", "DROPBOX\_APP\_KEY", "DROPBOX\_APP\_SECRET"]
* **scopes**: \["account\_info.read", "file\_requests.read", "file\_requests.write", "files.content.read", "files.content.write", "files.metadata.read", "files.metadata.write", "sharing.read", "sharing.write"]
* **note**: Inject secrets with a LoT action (GET SECRET); never retain topics that carry the token, refresh token or app secret; restrict storage/dropbox/oauth/# with ACLs (the refresh response carries the new access token). Authorise once with token\_access\_type=offline to get a refresh token. App folder apps see only /Apps/\<app>/.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Dropbox Notify connector | no |
| `BaseUrl` | string | Dropbox Notify base URL without trailing slash (e.g. [https://notify.dropboxapi.com](https://notify.dropboxapi.com)) | yes |

`BASE_ADDRESS` default: `https://notify.dropboxapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `FolderLongpoll` | POST | `/2/files/list_folder/longpoll` | `storage/dropbox/folders/longpoll` | `storage/dropbox/folders/longpoll/response` | `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode DROPBOX_NOTIFY"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR DropboxNotifyRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://notify.dropboxapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '600'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT FolderLongpoll
        WITH SOURCE_TOPIC "storage/dropbox/folders/longpoll"
        WITH DESTINATION_TOPIC "storage/dropbox/folders/longpoll/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2/files/list_folder/longpoll"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `FolderLongpoll` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'storage/dropbox/folders/longpoll/response' &
mosquitto_pub -t 'storage/dropbox/folders/longpoll' -m '{"body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Dynamics 365 Field Service and Connected Field Service
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dynamics-365-field-service-and-connected-field-service

Connect Coreflux LoT to Dynamics 365 Field Service: raise IoT alerts from MQTT alarms, create and query work orders and update customer assets

Technical Preview

## Overview

A client-mode connector for a **curated Field Service / Connected Field Service** slice of the [Dataverse Web API](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview) on Dynamics 365 Field Service (`https://YOUR_ORG.api.crm.dynamics.com`):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST msdyn\_iotalerts (from MQTT alarm) | `POST /api/data/v9.2/msdyn_iotalerts` | Connected Field Service [IoT Alert](https://learn.microsoft.com/en-us/dynamics365/developer/reference/entities/msdyn_iotalert); `msdyn_description` required |
| POST msdyn\_workorders | `POST /api/data/v9.2/msdyn_workorders` | [Create work order](https://learn.microsoft.com/en-us/dynamics365/field-service/create-work-order-api-example); use `@odata.bind` for lookups |
| PATCH msdyn\_customerassets | `PATCH /api/data/v9.2/msdyn_customerassets({id})` | [Customer Asset](https://learn.microsoft.com/en-us/dynamics365/field-service/developer/reference/entities/msdyn_customerasset); `If-Match: *` |
| GET msdyn\_workorders?\$filter= | `GET /api/data/v9.2/msdyn_workorders?$filter=…` | OData filter / select / top |

`BASE_ADDRESS` is `https://{org}.api.crm{N}.dynamics.com` (no trailing slash; endpoints already include `/api/data/v9.2/...`). Topics use `cmms/dynamics-365-field-service-and-connected-field-service/<object>/<verb>`.

This package is **distinct** from the general Dataverse CRM template [Dynamics 365](/latest/lot-language/routes/rest-api-apps/dynamics365) (accounts / contacts / WhoAmI).

> [!NOTE]
>
> Prefer Hub secrets for Entra access tokens.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Dynamics 365 Field Service / Connected Field Service
# Auth: Entra Bearer {value.json.api_token}
# BASE_ADDRESS: https://YOUR_ORG.api.crm.dynamics.com

DEFINE CONNECTOR Dynamics365FieldServiceRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ORG.api.crm.dynamics.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Createiotalert
        WITH SOURCE_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_iotalerts/create"
        WITH DESTINATION_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_iotalerts/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data/v9.2/msdyn_iotalerts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "return=representation,odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Createworkorder
        WITH SOURCE_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_workorders/create"
        WITH DESTINATION_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_workorders/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data/v9.2/msdyn_workorders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "return=representation,odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Patchcustomerasset
        WITH SOURCE_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_customerassets/patch"
        WITH DESTINATION_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_customerassets/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/data/v9.2/msdyn_customerassets({value.json.msdyn_customerassetid})"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "If-Match" "*"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Listworkorders
        WITH SOURCE_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_workorders/list"
        WITH DESTINATION_TOPIC "cmms/dynamics-365-field-service-and-connected-field-service/msdyn_workorders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v9.2/msdyn_workorders?$filter={value.json.filter}&$select={value.json.select}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Parameters

| Parameter | Required | Description |
| - | - | - |
| `BASE_ADDRESS` | Yes | `https://{org}.api.crm{N}.dynamics.com` — org API host, no trailing slash |
| `api_token` (MQTT JSON) | Yes | Entra ID access token (audience = org URL) for `Authorization: Bearer …` |
| `filter` | For list | OData `$filter`, e.g. `msdyn_systemstatus eq 690970000` |
| `select` | For list | OData `$select` column list |
| `top` | For list | OData `$top` page size |
| `msdyn_customerassetid` | For PATCH | Customer asset GUID (path) |
| `{payload}` | POST/PATCH | Dataverse JSON body (lookups as `@odata.bind` paths) |

## Authentication

* **Entra ID OAuth 2.0 Bearer** for the Dataverse org resource (client credentials or delegated).
* Prefer Hub secrets / `GET SECRET`. Never commit real tokens.
* See [Authenticate to Dataverse with the Web API](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/authenticate-oauth).

## MQTT topics

| Event | Source topic | Method |
| - | - | - |
| Create IoT alert | `cmms/dynamics-365-field-service-and-connected-field-service/msdyn_iotalerts/create` | POST |
| Create work order | `cmms/dynamics-365-field-service-and-connected-field-service/msdyn_workorders/create` | POST |
| Patch customer asset | `cmms/dynamics-365-field-service-and-connected-field-service/msdyn_customerassets/patch` | PATCH |
| List work orders | `cmms/dynamics-365-field-service-and-connected-field-service/msdyn_workorders/list` | GET |

Responses publish on the same topic with `/response` appended.

## Example payloads

**IoT alert from MQTT alarm**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "msdyn_description": "IIoT alarm — high vibration Zone A",
  "msdyn_alerttime": "2026-10-04T11:00:00Z",
  "msdyn_alerttype": 192350000,
  "msdyn_deviceid": "edge-compressor-01",
  "msdyn_alertdata": "{\"metric\":\"vibration_rms\",\"value\":12.4}",
  "msdyn_customerasset@odata.bind": "/msdyn_customerassets(00000000-0000-0000-0000-000000000001)"
}
```

Alert types: `192350000` Anomaly, `192350001` Info, `192350002` Preventive Maintenance, `192350003` Test.

**Work order**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "msdyn_serviceaccount@odata.bind": "/accounts(…)",
  "msdyn_workordertype@odata.bind": "/msdyn_workordertypes(…)",
  "msdyn_systemstatus": 690970000,
  "msdyn_instructions": "Investigate IoT alert from Coreflux"
}
```

**Filter work orders**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "filter": "msdyn_systemstatus eq 690970000",
  "select": "msdyn_name,msdyn_systemstatus,msdyn_workorderid",
  "top": "20"
}
```

## Notes

* Successful creates often return **204** with an `OData-EntityId` header (or a body when `Prefer: return=representation` is honored).
* Never send bare GUIDs for lookup fields — always `/entityset(guid)` via `@odata.bind`.
* Connected Field Service IoT alerts can be converted to work orders in the Field Service UI / BPF; this connector also supports creating work orders directly and optionally binding `msdyn_iotalert@odata.bind`.
* Requires Field Service (and Connected Field Service entities for IoT alerts) installed in the Dataverse environment.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Dynamics 365 (Dataverse CRM)](/latest/lot-language/routes/rest-api-apps/dynamics365)
* [IBM Maximo Manage](/latest/lot-language/routes/rest-api-apps/ibm-maximo-manage)


# Dynamics 365 Dataverse Web API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dynamics365

Client-mode REST API connector for a curated Dataverse Web API subset: WhoAmI, accounts, contacts, and entity metadata

Technical Preview

## Overview

A client-mode connector for a **curated eight-operation** slice of the [Dataverse Web API](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/overview) used by Dynamics 365 / Power Platform: WhoAmI, account CRUD helpers, contacts, and EntityDefinitions. It is meant for ERP/CRM edge bridges, not the full Dynamics surface. Set `BASE_ADDRESS` to the **customer org** URL (for example `https://contoso.crm.dynamics.com`, or `.crm4.dynamics.com` for many EU tenants).

> [!NOTE]
>
> Dataverse requires an Azure AD Bearer access token for the org resource. A placeholder org host does not resolve. Unauthenticated global discovery returns HTTP 400 without a tenant.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Dynamics 365 (Dataverse Web API)
# Generated from curated OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes
# Auth: Azure AD Bearer via {value.json.api_token}. Prefer Hub secrets / GET SECRET.
# BASE_ADDRESS: replace YOUR_ORG (and region: .crm / .crm4 / etc.) with the customer org URL.

DEFINE CONNECTOR Dynamics365RestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ORG.crm.dynamics.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Azure AD access token for the Dataverse org resource as Bearer.
        # Prefer Hub secrets / GET SECRET upstream — never commit real tokens.
        # EU orgs often use https://YOUR_ORG.crm4.dynamics.com (set BASE_ADDRESS to match).
    ADD EVENT Whoami
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Whoami"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Whoami"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v9.2/WhoAmI"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listaccounts
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Listaccounts"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Listaccounts"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v9.2/accounts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createaccount
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Createaccount"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Createaccount"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data/v9.2/accounts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Getaccount
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Getaccount"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Getaccount"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v9.2/accounts({value.json.accountid})"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Updateaccount
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Updateaccount"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Updateaccount"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/data/v9.2/accounts({value.json.accountid})"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Listcontacts
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Listcontacts"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Listcontacts"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v9.2/contacts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getcontact
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Getcontact"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Getcontact"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v9.2/contacts({value.json.contactid})"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listentitydefinitions
        WITH SOURCE_TOPIC "integrations/dynamics365/request/Listentitydefinitions"
        WITH DESTINATION_TOPIC "integrations/dynamics365/response/Listentitydefinitions"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v9.2/EntityDefinitions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Prefer" "odata.include-annotations=\"*\""
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Whoami | GET | `/api/data/v9.2/WhoAmI` | `integrations/dynamics365/request/Whoami` | `integrations/dynamics365/response/Whoami` |
| Listaccounts | GET | `/api/data/v9.2/accounts` | `integrations/dynamics365/request/Listaccounts` | `integrations/dynamics365/response/Listaccounts` |
| Createaccount | POST | `/api/data/v9.2/accounts` | `integrations/dynamics365/request/Createaccount` | `integrations/dynamics365/response/Createaccount` |
| Getaccount | GET | `/api/data/v9.2/accounts({value.json.accountid})` | `integrations/dynamics365/request/Getaccount` | `integrations/dynamics365/response/Getaccount` |
| Updateaccount | PATCH | `/api/data/v9.2/accounts({value.json.accountid})` | `integrations/dynamics365/request/Updateaccount` | `integrations/dynamics365/response/Updateaccount` |
| Listcontacts | GET | `/api/data/v9.2/contacts` | `integrations/dynamics365/request/Listcontacts` | `integrations/dynamics365/response/Listcontacts` |
| Getcontact | GET | `/api/data/v9.2/contacts({value.json.contactid})` | `integrations/dynamics365/request/Getcontact` | `integrations/dynamics365/response/Getcontact` |
| Listentitydefinitions | GET | `/api/data/v9.2/EntityDefinitions` | `integrations/dynamics365/request/Listentitydefinitions` | `integrations/dynamics365/response/Listentitydefinitions` |

List endpoints accept OData query options (`$select`, `$filter`, `$top`, `$orderby`) when you extend the `ENDPOINT` or append them in a custom variant.

## Auth

Azure AD Bearer plus Dataverse OData headers:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Accept" "application/json"
ADD "OData-MaxVersion" "4.0"
ADD "OData-Version" "4.0"
ADD "Prefer" "odata.include-annotations=\"*\""
ADD "Authorization" "Bearer {value.json.api_token}"
```

**api\_token** `string` *required*

Azure AD access token for the Dataverse org resource (audience = org URL). Obtain via client credentials or a delegated OAuth 2.0 flow. Prefer a Hub secret. Never commit the token.

**accountid** `string`

Account GUID. Required on Getaccount and Updateaccount.

**contactid** `string`

Contact GUID. Required on Getcontact.

High-level token flow (no secrets in the template):

1. Register an Entra ID app with permission to the Dynamics / Dataverse API (or use an existing app registration).
2. Acquire a token with **client credentials** (app-only) or a **delegated** user flow against the org resource URL.
3. Publish the access token as `api_token` on the MQTT request payload (or inject from Hub secret upstream).

WhoAmI:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_AZURE_AD_ACCESS_TOKEN"}
```

Get account:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_AZURE_AD_ACCESS_TOKEN", "accountid": "00000000-0000-0000-0000-000000000000"}
```

Create account (connector body is `{payload}`; include `name`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_AZURE_AD_ACCESS_TOKEN", "name": "Contoso Plant"}
```

## Try it

1. Set `BASE_ADDRESS` to your org URL and add the connector on your broker.
2. Publish token JSON to `integrations/dynamics365/request/Whoami`.
3. Subscribe to `integrations/dynamics365/response/Whoami`.
4. Accounts / contacts: include `accountid` or `contactid` as needed.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Dynamics 365 Business Central
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dynamics365-bc

Client-mode REST API connector for a curated Business Central API v2.0 slice: items, journalLines, salesOrders, and webhook subscriptions on items

Technical Preview

## Overview

A client-mode connector for a **curated inventory / sales / webhook** slice of [Business Central Standard API v2.0](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/api-endpoint-structure) under `https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/v2.0/`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET items | `companies({companyId})/items` | Items; supports `$filter`, `$select`, `$top` |
| POST itemLedgerEntries via journals | `companies({companyId})/journals({journalId})/journalLines` | Standard writable journal path (G/L or Bank). `itemLedgerEntries` are **GET-only**; inventory Item Journal → custom API |
| GET salesOrders | `companies({companyId})/salesOrders` | Sales order headers; optional `$expand=salesOrderLines` |
| subscribe webhook on items | `subscriptions` | POST with `resource` = `/api/v2.0/companies({id})/items`; handshake required |

`BASE_ADDRESS` is the Standard API root (no trailing slash in the template). Topics use `erp/dynamics365-bc/<object>/<verb>`.

> [!NOTE]
>
> This is **Business Central** cloud API v2.0, not Dataverse and not Finance & Operations. For CRM/Dataverse Web API see [Dynamics 365 (Dataverse)](/latest/lot-language/routes/rest-api-apps/dynamics365). For F\&O OData see [Dynamics 365 Finance and Supply Chain](/latest/lot-language/routes/rest-api-apps/dynamics365-fscm).

> [!NOTE]
>
> Business Central API v2.0 requires a real tenant + environment, a company GUID, and an Entra ID OAuth 2.0 Bearer token. Prefer Hub secrets for tokens. Discover companies with `GET .../api/v2.0/companies`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Microsoft Dynamics 365 Business Central (API v2.0 slice)
# Auth: Bearer {value.json.access_token} (Entra ID)
# BASE_ADDRESS: https://api.businesscentral.dynamics.com/v2.0/YOUR_TENANT/YOUR_ENV/api/v2.0

DEFINE CONNECTOR Dynamics365BcRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.businesscentral.dynamics.com/v2.0/YOUR_TENANT/YOUR_ENV/api/v2.0"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getitems
        WITH SOURCE_TOPIC "erp/dynamics365-bc/items/get"
        WITH DESTINATION_TOPIC "erp/dynamics365-bc/items/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/companies({value.json.companyId})/items?$top={value.json.top}&$filter={value.json.filter}&$select={value.json.select}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createjournallines
        WITH SOURCE_TOPIC "erp/dynamics365-bc/journal-lines/create"
        WITH DESTINATION_TOPIC "erp/dynamics365-bc/journal-lines/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/companies({value.json.companyId})/journals({value.json.journalId})/journalLines"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getsalesorders
        WITH SOURCE_TOPIC "erp/dynamics365-bc/sales-orders/get"
        WITH DESTINATION_TOPIC "erp/dynamics365-bc/sales-orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/companies({value.json.companyId})/salesOrders?$top={value.json.top}&$filter={value.json.filter}&$select={value.json.select}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createsubscription
        WITH SOURCE_TOPIC "erp/dynamics365-bc/subscriptions/create"
        WITH DESTINATION_TOPIC "erp/dynamics365-bc/subscriptions/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/subscriptions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getitems | GET | `/companies({companyId})/items` | `erp/dynamics365-bc/items/get` | `erp/dynamics365-bc/items/get/response` |
| Createjournallines | POST | `/companies({companyId})/journals({journalId})/journalLines` | `erp/dynamics365-bc/journal-lines/create` | `erp/dynamics365-bc/journal-lines/create/response` |
| Getsalesorders | GET | `/companies({companyId})/salesOrders` | `erp/dynamics365-bc/sales-orders/get` | `erp/dynamics365-bc/sales-orders/get/response` |
| Createsubscription | POST | `/subscriptions` | `erp/dynamics365-bc/subscriptions/create` | `erp/dynamics365-bc/subscriptions/create/response` |

## Auth

**OAuth 2.0 (Entra ID) — default in the template:**

1. Register an app in Microsoft Entra ID; create a client secret; grant Dynamics 365 Business Central API permissions (e.g. `API.ReadWrite.All`).
2. In Business Central: **Azure Active Directory Applications** (Microsoft Entra Applications) — add the client ID and assign permission sets.
3. Request a token (client credentials example):

```http theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={clientId}&client_secret={secret}&scope=https://api.businesscentral.dynamics.com/.default
```

Delegated / authorization-code flows also work when your BC setup requires a licensed user context.

4. Pass the access token and company GUID on the MQTT request payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_ENTRA_ACCESS_TOKEN", "companyId": "YOUR_COMPANY_GUID", "top": "10", "filter": "number eq '1896-S'", "select": "id,number,displayName,inventory,unitPrice"}
```

The connector sends `Authorization: Bearer {value.json.access_token}`. Prefer Hub secrets / `GET SECRET`. Never commit real tokens.

## Companies and OData

Resolve `companyId` with `GET https://api.businesscentral.dynamics.com/v2.0/{tenant}/{env}/api/v2.0/companies`. All company-scoped entities nest under `companies({id})/...`. Send OData headers `Accept: application/json`, `OData-Version: 4.0`, `OData-MaxVersion: 4.0`.

## Item ledger vs journals

[itemLedgerEntry](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_itemledgerentry) supports **GET only**. Catalog “POST itemLedgerEntries via journals” maps to the standard API writable journal path [`journalLines`](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/api/dynamics_journalline_create) (G/L or Bank). Inventory quantity adjustments that create item ledger entries need a **custom Item Journal API** in AL.

## Webhooks

[Working with webhooks](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-subscriptions): `items` is a supported entity. Example subscription body:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "notificationUrl": "https://YOUR_PUBLIC_HTTPS_ENDPOINT/bc-webhook",
  "resource": "/api/v2.0/companies(YOUR_COMPANY_GUID)/items",
  "clientState": "optionalSharedSecret"
}
```

Handshake is mandatory: BC GETs `notificationUrl?validationToken=...` and expects the token in the 200 response body. Renew with `PATCH /subscriptions({id})` before expiry (\~3 days).

## Deploy

1. Copy `Dynamics365BcRestApi.lot` (no `ADD METADATA`).
2. Replace `YOUR_TENANT` and `YOUR_ENV` in `BASE_ADDRESS`.
3. `-addConnector` on the broker (or Hub deploy).
4. Publish JSON to a request topic; subscribe to the matching `/response` topic.

Hub catalog metadata (icon, description, `STATUS "beta"`) is in `hub-metadata.lot` for Hub / `-listTemplates` only.

## References

* [API endpoint structure — Business Central](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/api-endpoint-structure)
* [item resource type](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_item)
* [salesOrder resource type](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_salesorder)
* [Create journalLines](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/api/dynamics_journalline_create)
* [Working with webhooks](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-subscriptions)
* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)


# Microsoft Dynamics 365 Finance and Supply Chain
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dynamics365-fscm

Connect Coreflux LoT to Dynamics 365 Finance and Supply Chain OData: read production orders, report as finished, post inventory journals and read maintenance

Technical Preview

## Overview

A client-mode connector for a **curated manufacturing / inventory / maintenance** slice of [Dynamics 365 Finance & Operations OData](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/odata) under `https://{env}.operations.dynamics.com/data/`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET ProductionOrderHeaders | `ProductionOrderHeaders` | Production order headers; supports `$filter`, `cross-company` |
| POST ProdReportAsFinished | `ReportAsFinishedProductionJournalEntries` | Report-as-finished production journal entries ([dynamics.fo](https://dynamics.fo/data-entity/report-finished-production-journal-entries)) |
| POST InventoryJournalLines | `InventoryMovementJournalEntries` | Inventory movement journal headers/lines; confirm PublicCollectionName on tenant `$metadata` (V1/V2 obsolete; V3 in CDM) |
| GET MaintenanceRequests | `AssetMaintenanceRequestsV2` | Asset management maintenance requests V2 (10.0.32+) |

`BASE_ADDRESS` is the F\&O OData root (`https://{env}.operations.dynamics.com/data`). Topics use `erp/dynamics365-fscm/<object>/<verb>`.

> [!NOTE]
>
> This is **Finance & Operations / Supply Chain**, not Dataverse. For CRM Web API (accounts, incidents, Field Service), see [Dynamics 365 (Dataverse)](/latest/lot-language/routes/rest-api-apps/dynamics365).

> [!NOTE]
>
> F\&O OData requires a real environment URL and an Entra ID OAuth 2.0 Bearer token (client credentials). Prefer Hub secrets for tokens. Discover public entities with `GET .../data/` or `GET .../data/$metadata`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Microsoft Dynamics 365 Finance and Supply Chain (F&O OData slice)
# Auth: Bearer {value.json.access_token} (Entra ID client credentials)
# BASE_ADDRESS: https://YOUR_ENV.operations.dynamics.com/data

DEFINE CONNECTOR Dynamics365FscmRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ENV.operations.dynamics.com/data"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getproductionorderheaders
        WITH SOURCE_TOPIC "erp/dynamics365-fscm/production-order-headers/get"
        WITH DESTINATION_TOPIC "erp/dynamics365-fscm/production-order-headers/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ProductionOrderHeaders?cross-company=true&$top={value.json.top}&$filter={value.json.filter}&$select={value.json.select}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createprodreportasfinished
        WITH SOURCE_TOPIC "erp/dynamics365-fscm/prod-report-as-finished/create"
        WITH DESTINATION_TOPIC "erp/dynamics365-fscm/prod-report-as-finished/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/ReportAsFinishedProductionJournalEntries"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Createinventoryjournallines
        WITH SOURCE_TOPIC "erp/dynamics365-fscm/inventory-journal-lines/create"
        WITH DESTINATION_TOPIC "erp/dynamics365-fscm/inventory-journal-lines/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/InventoryMovementJournalEntries"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getmaintenancerequests
        WITH SOURCE_TOPIC "erp/dynamics365-fscm/maintenance-requests/get"
        WITH DESTINATION_TOPIC "erp/dynamics365-fscm/maintenance-requests/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/AssetMaintenanceRequestsV2?cross-company=true&$top={value.json.top}&$filter={value.json.filter}&$select={value.json.select}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "OData-MaxVersion" "4.0"
            ADD "OData-Version" "4.0"
            ADD "Authorization" "Bearer {value.json.access_token}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getproductionorderheaders | GET | `/ProductionOrderHeaders` | `erp/dynamics365-fscm/production-order-headers/get` | `erp/dynamics365-fscm/production-order-headers/get/response` |
| Createprodreportasfinished | POST | `/ReportAsFinishedProductionJournalEntries` | `erp/dynamics365-fscm/prod-report-as-finished/create` | `erp/dynamics365-fscm/prod-report-as-finished/create/response` |
| Createinventoryjournallines | POST | `/InventoryMovementJournalEntries` | `erp/dynamics365-fscm/inventory-journal-lines/create` | `erp/dynamics365-fscm/inventory-journal-lines/create/response` |
| Getmaintenancerequests | GET | `/AssetMaintenanceRequestsV2` | `erp/dynamics365-fscm/maintenance-requests/get` | `erp/dynamics365-fscm/maintenance-requests/get/response` |

## Auth

**OAuth 2.0 client credentials (Entra ID) — default in the template:**

1. Register an app in Microsoft Entra ID; create a client secret; grant Dynamics ERP API permissions as required by your tenant.
2. In F\&O: **System administration > Setup > Microsoft Entra applications** — add the client ID and map it to a service user.
3. Request a token:

```http theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={clientId}&client_secret={secret}&scope=https://{env}.operations.dynamics.com/.default
```

4. Pass the access token on the MQTT request payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_ENTRA_ACCESS_TOKEN", "top": "10", "filter": "ProductionOrderStatus eq Microsoft.Dynamics.DataEntities.ProdStatus'Started'", "select": "ProductionOrderNumber,ProductionOrderStatus,ItemNumber"}
```

The connector sends `Authorization: Bearer {value.json.access_token}`. Prefer Hub secrets / `GET SECRET`. Never commit real tokens.

## Cross-company and keys

By default OData returns only the service user's default company. The GET endpoints append `cross-company=true`. To filter one company: `$filter=dataAreaId eq 'usmf'` with `cross-company=true`. Entity keys usually include `dataAreaId` plus a business key (e.g. `ProductionOrderNumber`) — see Microsoft Learn OData addressing.

## Entity name notes

Public collection names can differ by F\&O version. This package uses documented PublicCollectionName values from [dynamics.fo](https://dynamics.fo/) and community usage. Always confirm on your tenant with `GET https://{env}.operations.dynamics.com/data/$metadata` or Excel workbook designer. Report-as-finished and inventory journal **posting** may require a bound OData action after create — loading the journal line alone does not always post.

## Deploy

1. Copy `Dynamics365FscmRestApi.lot` (no `ADD METADATA`).
2. Replace `YOUR_ENV` in `BASE_ADDRESS`.
3. `-addConnector` on the broker (or Hub deploy).
4. Publish JSON to a request topic; subscribe to the matching `/response` topic.

Hub catalog metadata (icon, description, `STATUS "beta"`) is in `hub-metadata.lot` for Hub / `-listTemplates` only.

## References

* [Open Data Protocol (OData) — Finance & Operations](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/odata)
* [Service endpoints overview](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/services-home-page)
* [Report production orders as finished](https://learn.microsoft.com/en-us/dynamics365/supply-chain/production-control/report-production-orders-as-finished)
* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)


# Dynatrace
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/dynatrace

Connect Coreflux LoT to the Dynatrace Environment API v2: ingest metrics, events and logs from MQTT and list open problems

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of the [Dynatrace Environment API v2](https://docs.dynatrace.com/docs/dynatrace-api):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST metrics/ingest | `POST /api/v2/metrics/ingest` | Line protocol (`text/plain`); scope `metrics.ingest`; expect **202** |
| POST events/ingest | `POST /api/v2/events/ingest` | JSON event body; scope `events.ingest`; expect **201** |
| GET problems | `GET /api/v2/problems` | List problems; scope `problems.read`; credential check → **200** |
| POST logs/ingest | `POST /api/v2/logs/ingest` | JSON array preferred; scope `logs.ingest`; expect **204** |

Default `BASE_ADDRESS` is `https://YOUR_ENVIRONMENT_ID.live.dynatrace.com`. Topics use `itsm/dynatrace/<object>/<verb>`.

> [!NOTE]
>
> Replace `YOUR_ENVIRONMENT_ID` with your Dynatrace environment id. ActiveGate deployments use `https://{activegate}:9999/e/{environment-id}` as BASE instead.

> [!NOTE]
>
> Prefer Hub secrets for the access token (`DYNATRACE_API_TOKEN`) and environment id.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Dynatrace (Metrics/Events/Logs + Problems)
# Auth: Authorization: Api-Token {value.json.api_token}
# BASE_ADDRESS: https://YOUR_ENVIRONMENT_ID.live.dynatrace.com

DEFINE CONNECTOR DynatraceRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ENVIRONMENT_ID.live.dynatrace.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Ingestmetrics
        WITH SOURCE_TOPIC "itsm/dynatrace/metric/ingest"
        WITH DESTINATION_TOPIC "itsm/dynatrace/metric/ingest/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/metrics/ingest"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain; charset=utf-8"
            ADD "Authorization" "Api-Token {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Ingestevent
        WITH SOURCE_TOPIC "itsm/dynatrace/event/ingest"
        WITH DESTINATION_TOPIC "itsm/dynatrace/event/ingest/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/events/ingest"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Api-Token {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Listproblems
        WITH SOURCE_TOPIC "itsm/dynatrace/problem/list"
        WITH DESTINATION_TOPIC "itsm/dynatrace/problem/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/problems?pageSize={value.json.page_size}&from={value.json.from}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Api-Token {value.json.api_token}"
    ADD EVENT Ingestlogs
        WITH SOURCE_TOPIC "itsm/dynatrace/log/ingest"
        WITH DESTINATION_TOPIC "itsm/dynatrace/log/ingest/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/logs/ingest"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Api-Token {value.json.api_token}"
        WITH BODY "{payload}"
```

## Authentication

| Mode | Header | Notes |
| - | - | - |
| Classic access token | `Authorization: Api-Token {value.json.api_token}` | Default in this template |
| Platform token / OAuth | `Authorization: Bearer {value.json.api_token}` | Change the realm string |

Scopes for the curated ops: `metrics.ingest`, `events.ingest`, `problems.read`, `logs.ingest` (or platform `openpipeline:*` / storage equivalents). Store the token in Hub secrets (`DYNATRACE_API_TOKEN`) and resolve via `GET SECRET` — never commit credentials.

## MQTT examples

**Metrics** (line protocol body):

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
coreflux.plant.vibration_rms,line=a,source=coreflux 12.4
```

Publish with `api_token` so the connector can set `Authorization`. Expect **HTTP 202**.

**Events:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "eventType": "CUSTOM_INFO",
  "title": "Coreflux plant alarm",
  "entitySelector": "type(CUSTOM_DEVICE),entityName.equals(line-a)",
  "properties": {"vibration_rms": "12.4"}
}
```

Expect **HTTP 201**.

**Problems list:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_API_TOKEN",
  "page_size": "1",
  "from": "now-2h"
}
```

Expect **HTTP 200**.

**Logs** (JSON array):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "content": "vibration_rms=12.4 threshold=8.0",
    "status": "WARN",
    "service.name": "coreflux-broker"
  }
]
```

Expect **HTTP 204**.

## Sources

* [Metrics ingest](https://docs.dynatrace.com/docs/dynatrace-api/environment-api/metric-v2/post-ingest-metrics)
* [Events ingest](https://docs.dynatrace.com/docs/dynatrace-api/environment-api/events-v2/post-event)
* [Problems list](https://docs.dynatrace.com/docs/dynatrace-api/environment-api/problems-v2/problems/get-problems-list)
* [Logs ingest](https://docs.dynatrace.com/docs/dynatrace-api/environment-api/log-monitoring-v2/post-ingest-logs)
* [Tokens and authentication](https://docs.dynatrace.com/docs/dynatrace-api/basics/dynatrace-api-authentication)

## Package

Broker template folder: `src/CorefluxCentral/Routes/Templates/RestApiConnectors/dynatrace/`

Deployable file: `DynatraceRestApi.lot` (no `ADD METADATA`). Hub icon/status: `hub-metadata.lot`.


# EasyPost
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/easypost

Connect Coreflux LoT to EasyPost: verify addresses, compare rates, buy labels, book pickups and track parcels, with a webhook receiver for tracker updates

Technical Preview

## Overview

[EasyPost](https://www.easypost.com) is a multi-carrier shipping API (USPS, UPS, FedEx, DHL, DPD, CTT Express and 100+ more): it verifies addresses, compares **rates**, buys **labels**, schedules **pickups**, prints **scan forms** (manifests) and **tracks** packages, and it pushes tracking updates as **webhook Events**. This connector lets the broker ship what the plant produces: when a packing line finishes a pallet or carton, an MQTT message creates the shipment, the cheapest allowed rate is bought, the label goes to the line's ZPL printer, and tracking updates come back on MQTT under `logistics/shipments/<id>`.

The template (`EasypostRestApi.lot`) is one client connector, **EasyPostApi**, on `https://api.easypost.com`, with 53 events: 25 `GET`, 27 `POST` and 1 `PATCH` (no `PUT` or `DELETE`). 29 are reads, 19 are writes and **5 are purchases** that spend money with a production key (`BuyShipment`, `InsureShipment`, `BuyOrder`, `BuyBatch`, `BuyPickup`). `CreateShipment` and `CreateOrder` also purchase when you add `service` and `carrier_accounts` (One-Call Buy).

The optional companion (`fleet_easypost_webhook.lot`) is a server connector, **EasyPostWebhookReceiver**, that receives EasyPost webhook Events and publishes them on MQTT.

> [!WARNING]
>
> **Purchases cost money.** With a production key (`EZAK...`), every event marked **Purchase** (and a One-Call Buy) charges the EasyPost Wallet: postage, insurance or a pickup fee. Start with a **test key** (`EZTK...`): test mode buys nothing and contacts no carrier. Restrict who can publish to `fleet/easypost/+/buy`, `fleet/easypost/shipment/insure` and `fleet/easypost/shipment/create` with broker ACLs.

## Events

| Event | Topic | Request | Kind | What it does |
| - | - | - | - | - |
| `GetUser` | `fleet/easypost/user/get` | `GET /v2/users` | Read | The authenticated user (id, name, balance, recharge settings, child users) |
| `ListCarrierAccounts` | `fleet/easypost/carrier-account/list` | `GET /v2/carrier_accounts` | Read | Carrier accounts on the EasyPost account (ids ca\_... for carrier\_accounts in shipments) |
| `ListCarrierTypes` | `fleet/easypost/carrier-type/list` | `GET /v2/carrier_types` | Read | Carrier types that can be added and their credential fields |
| `GetCarrierMetadata` | `fleet/easypost/carrier-metadata/get` | `GET /v2/metadata/carriers?{query}` | Read | Carrier metadata: service levels, predefined packages, shipment options, supported features |
| `CreateAddress` | `fleet/easypost/address/create` | `POST /v2/addresses` | Write | Create an address; verify / verify\_strict run address verification (result in verifications) |
| `CreateAndVerifyAddress` | `fleet/easypost/address/create-verify` | `POST /v2/addresses/create_and_verify` | Write | Create and strictly verify an address in one call; fails with ADDRESS.VERIFY.FAILURE when it cannot be verified |
| `VerifyAddress` | `fleet/easypost/address/verify` | `GET /v2/addresses/{id}/verify` | Read | Verify an existing address |
| `GetAddress` | `fleet/easypost/address/get` | `GET /v2/addresses/{id}` | Read | One address by id |
| `CreateParcel` | `fleet/easypost/parcel/create` | `POST /v2/parcels` | Write | Create a parcel (inches and ounces, or a predefined\_package) |
| `CreateCustomsInfo` | `fleet/easypost/customs-info/create` | `POST /v2/customs_infos` | Write | Customs declaration (with customs items) for international shipments |
| `CreateShipment` | `fleet/easypost/shipment/create` | `POST /v2/shipments` | Write (One-Call Buy can purchase) | Create a shipment and get its rates (no charge). Adding service + carrier\_accounts makes it a One-Call Buy that purchases postage |
| `GetShipment` | `fleet/easypost/shipment/get` | `GET /v2/shipments/{id}` | Read | One shipment (rates, selected\_rate, postage\_label, tracker, fees) |
| `ListShipments` | `fleet/easypost/shipment/list` | `GET /v2/shipments?{query}` | Read | Shipments, newest first; page\_size (max 100), before\_id / after\_id, start\_datetime / end\_datetime; has\_more |
| `BuyShipment` | `fleet/easypost/shipment/buy` | `POST /v2/shipments/{id}/buy` | **Purchase** | Buy the label for one rate (adds tracking\_code, postage\_label, tracker); optional insurance (USD string) and end\_shipper\_id |
| `ConvertShipmentLabel` | `fleet/easypost/label/convert` | `GET /v2/shipments/{id}/label?{query}` | Read | Convert a bought PNG label to ZPL, EPL2 or PDF (label\_zpl\_url / label\_epl2\_url / label\_pdf\_url) |
| `RerateShipment` | `fleet/easypost/rate/rerate` | `POST /v2/shipments/{id}/rerate` | Read | Regenerate the rates of an unbought shipment (no body, no charge) |
| `GetShipmentSmartRates` | `fleet/easypost/smartrate/get` | `GET /v2/shipments/{id}/smartrate` | Read | SmartRate: rates with time-in-transit percentiles for the shipment |
| `InsureShipment` | `fleet/easypost/shipment/insure` | `POST /v2/shipments/{id}/insure` | **Purchase** | Insure a bought shipment for amount (USD); charges the insurance fee |
| `RefundShipment` | `fleet/easypost/shipment/refund` | `POST /v2/shipments/{id}/refund` | Write | Request a refund of an unused label (refund\_status submitted; USPS refunds take up to 15 days) |
| `GetRate` | `fleet/easypost/rate/get` | `GET /v2/rates/{id}` | Read | One rate by id |
| `EstimateRates` | `fleet/easypost/rate/estimate` | `POST /beta/rates` | Read | Stateless rates for addresses and a parcel without creating a shipment (beta API under /beta) |
| `SmartRateDeliverBy` | `fleet/easypost/smartrate/deliver-by` | `POST /v2/smartrate/deliver_by` | Read | Delivery date predictions by carrier and service for a ZIP pair and ship date |
| `CreateTracker` | `fleet/easypost/tracker/create` | `POST /v2/trackers` | Write | Track a package not bought through EasyPost (EZ... test codes simulate statuses with a test key); trackers may be billed in production |
| `GetTracker` | `fleet/easypost/tracker/get` | `GET /v2/trackers/{id}` | Read | One tracker (status, est\_delivery\_date, tracking\_details, carrier\_detail) |
| `ListTrackers` | `fleet/easypost/tracker/list` | `GET /v2/trackers?{query}` | Read | Trackers, newest first; filter by tracking\_code and carrier |
| `RetrieveTrackerBatch` | `fleet/easypost/tracker/batch` | `POST /v2/trackers/batch` | Read | Many trackers by tracking\_codes in one call (POST, read only) |
| `CreateOrder` | `fleet/easypost/order/create` | `POST /v2/orders` | Write (One-Call Buy can purchase) | Multi-parcel order (one shipment per carton) with rates; only some carriers (FedEx, UPS, DHLExpress, ...); service + carrier\_accounts make it a One-Call Buy |
| `BuyOrder` | `fleet/easypost/order/buy` | `POST /v2/orders/{id}/buy` | **Purchase** | Buy every shipment of an order for one carrier + service |
| `GetOrder` | `fleet/easypost/order/get` | `GET /v2/orders/{id}` | Read | One order with its shipments and rates |
| `CreateBatch` | `fleet/easypost/batch/create` | `POST /v2/batches` | Write | Group shipments into a batch (end-of-shift label run) |
| `GetBatch` | `fleet/easypost/batch/get` | `GET /v2/batches/{id}` | Read | One batch (state, status counts, label\_url, scan\_form) |
| `ListBatches` | `fleet/easypost/batch/list` | `GET /v2/batches?{query}` | Read | Batches, newest first |
| `AddBatchShipments` | `fleet/easypost/batch-shipment/add` | `POST /v2/batches/{id}/add_shipments` | Write | Add shipments to a batch |
| `RemoveBatchShipments` | `fleet/easypost/batch-shipment/remove` | `POST /v2/batches/{id}/remove_shipments` | Write | Remove shipments from a batch |
| `BuyBatch` | `fleet/easypost/batch/buy` | `POST /v2/batches/{id}/buy` | **Purchase** | Buy every shipment in a batch (asynchronous; batch.updated events; no body) |
| `CreateBatchLabel` | `fleet/easypost/batch-label/create` | `POST /v2/batches/{id}/label` | Write | One merged label file (PDF, EPL2 or ZPL) for a bought batch (asynchronous; label\_url) |
| `CreateBatchScanForm` | `fleet/easypost/batch-scan-form/create` | `POST /v2/batches/{id}/scan_form` | Write | ScanForm (manifest) for a bought batch (no body) |
| `CreateScanForm` | `fleet/easypost/scan-form/create` | `POST /v2/scan_forms` | Write | ScanForm (manifest) for bought shipments of one carrier and from address, for the driver to scan at pickup |
| `GetScanForm` | `fleet/easypost/scan-form/get` | `GET /v2/scan_forms/{id}` | Read | One ScanForm (status, form\_url, tracking\_codes) |
| `ListScanForms` | `fleet/easypost/scan-form/list` | `GET /v2/scan_forms?{query}` | Read | ScanForms, newest first |
| `CreatePickup` | `fleet/easypost/pickup/create` | `POST /v2/pickups` | Write | Request a carrier pickup window for a bought shipment (or batch); reply carries pickup\_rates |
| `BuyPickup` | `fleet/easypost/pickup/buy` | `POST /v2/pickups/{id}/buy` | **Purchase** | Buy one pickup rate by carrier + service (not by id); confirmation in the reply |
| `CancelPickup` | `fleet/easypost/pickup/cancel` | `POST /v2/pickups/{id}/cancel` | Write | Cancel a scheduled pickup (no body) |
| `GetPickup` | `fleet/easypost/pickup/get` | `GET /v2/pickups/{id}` | Read | One pickup (status, confirmation, pickup\_rates) |
| `ListPickups` | `fleet/easypost/pickup/list` | `GET /v2/pickups?{query}` | Read | Pickups, newest first |
| `CreateRefund` | `fleet/easypost/refund/create` | `POST /v2/refunds` | Write | Refund labels by carrier + tracking codes |
| `ListEvents` | `fleet/easypost/event/list` | `GET /v2/events?{query}` | Read | Events (tracker.updated, batch.updated, scan\_form.updated, refund.successful, ...) for webhook catch-up; result is not included |
| `GetEvent` | `fleet/easypost/event/get` | `GET /v2/events/{id}` | Read | One event (description, status, pending\_urls, completed\_urls) |
| `ListEventPayloads` | `fleet/easypost/event-payload/list` | `GET /v2/events/{id}/payloads` | Read | Webhook delivery attempts of one event (request body, response code, URL) |
| `CreateWebhook` | `fleet/easypost/webhook/create` | `POST /v2/webhooks` | Write | Register a webhook URL for this key's mode (a test key registers a test-mode webhook); every event is sent to every webhook |
| `ListWebhooks` | `fleet/easypost/webhook/list` | `GET /v2/webhooks` | Read | Webhooks of this mode (url, disabled\_at) |
| `GetWebhook` | `fleet/easypost/webhook/get` | `GET /v2/webhooks/{id}` | Read | One webhook |
| `UpdateWebhook` | `fleet/easypost/webhook/update` | `PATCH /v2/webhooks/{id}` | Write | Re-enable a disabled webhook and / or replace webhook\_secret and custom\_headers (custom\_headers is replaced as a whole) |

Every reply is published on the event topic plus `/response`. Objects carry `object` and `mode` (`test` or `production`). Lists return `{"<objects>": [...], "has_more"}`, newest first; `page_size` is at most 100 (most default to 20), and the next page uses `before_id` = the last id (or `start_datetime` / `end_datetime`). Errors return `{"error": {"code", "message", "errors"}}` with a `4xx` or `5xx` status.

### Webhook receiver (server connector)

| Event | Receives | Publishes on | EasyPost events |
| - | - | - | - |
| `WebhookEvents` | `POST /easypost/webhooks` | `fleet/easypost/webhook/received` | production-mode events: tracker.created / tracker.updated, batch.created / batch.updated, scan\_form.created / scan\_form.updated, refund.successful, insurance.*, report.*, payment.*, shipment.invoice.*, claim.\* |
| `TestWebhookEvents` | `POST /easypost/webhooks/test` | `fleet/easypost/webhook-test/received` | test-mode events (webhook created with a test API key; EZ... test tracking codes trigger tracker events) |

EasyPost sends **every** Event of a mode to **every** webhook of that mode; there is no per-type filter. Create one webhook with the production key (`https://<public host>/easypost/webhooks`) and, for testing, one with the test key (`https://<public host>/easypost/webhooks/test`), with `CreateWebhook` or in the Dashboard (**Webhooks and Events**). Route by the Event's `description` (`tracker.updated`, `batch.updated`, ...) in an action. Delivery is at least once, so make handlers idempotent (Event `id`). EasyPost needs HTTPS with a publicly trusted certificate: put a reverse proxy or tunnel in front of `SERVER_PORT` `9014`. Answer `2xx`; webhooks that keep failing are disabled, and `UpdateWebhook` re-enables them.

> [!WARNING]
>
> With a `webhook_secret`, EasyPost signs each body in the `X-Hmac-Signature` header (HMAC-SHA256); with `https://user:pass@host/...` it sends Basic auth instead. The receiver connector checks neither. Verify the signature in the reverse proxy, or keep the URL secret and restrict source addresses. Deploying the receiver opens an HTTP port on the broker.

## Prerequisites

* An EasyPost account. EasyPost issues API keys only after the **Wallet** is set up and a **ship-from address** is added.
* An API key from **Account Settings > API Keys**: a **test key** (`EZTK...`) to start, a production key (`EZAK...`) for real labels.
* At least one carrier account for the key (`ListCarrierAccounts`), such as the account's default USPS account or your own UPS, FedEx, DHL Express or CTT Express account.
* Address and parcel data: parcel `length`, `width`, `height` in **inches** and `weight` in **ounces**; customs info for international shipments.
* Outbound HTTPS from the broker to `api.easypost.com`; for webhooks, a public HTTPS URL that forwards to port `9014`.
* Optional: Python scripts enabled on the broker for the `EasyPostHelper` script (auto-buy example).

## Authentication

> [!WARNING]
>
> An EasyPost API key acts on the whole account, including the Wallet. Store it in Hub secrets, read it with `GET SECRET`, never put it in a connector file, and do not retain topics that carry it.

EasyPost uses HTTP Basic auth: the API key is the **username** and the password is **empty**, so the header is `Authorization: Basic <base64 of "<api key>:">` (note the trailing colon). Every event sends `Authorization: Basic {basic}`, where `basic` comes from the payload. Store the encoded value once as the secret `EASYPOST_BASIC`:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
printf '%s:' "$EASYPOST_API_KEY" | base64
```

Keys are per mode: a test key creates test objects and test webhooks, a production key real ones. A request without `Authorization` gets `401 UNAUTHORIZED`; a wrong, disabled or revoked key gets `403 APIKEY.INACTIVE`.

## Payload fields

| Field | Used by | Meaning |
| - | - | - |
| `basic` | every event | base64 of `<api key>:` (Hub secret `EASYPOST_BASIC`) |
| `id` | events with `{id}` in the path | EasyPost object id (`shp_...`, `rate_...`, `adr_...`, `trk_...`, `batch_...`, `order_...`, `pickup_...`, `sf_...`, `evt_...`, `hook_...`). Placed in the path |
| `query` | list events, `GetCarrierMetadata`, `ConvertShipmentLabel` | URL query string without `?`, e.g. `page_size=20&before_id=shp_...`; URL-encode values yourself |
| `body` | POST / PATCH events with a body | JSON request body with EasyPost's wrapper key where it has one (`{"shipment": {...}}`, `{"tracker": {...}}`, `{"address": {...}}`, ...) |

`RerateShipment`, `RefundShipment`, `BuyBatch`, `CreateBatchScanForm` and `CancelPickup` send no body. Pass `id` values you got from EasyPost, never raw user input, because they go into the URL path.

## Examples

Create a shipment for a finished pallet's carton and get rates (no charge):

```json fleet/easypost/shipment/create theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic": "<base64 of '<api key>:' (Hub secret EASYPOST_BASIC)>",
  "body": {
    "shipment": {
      "reference": "PALLET-2026-10-06-0042",
      "to_address": {
        "name": "Dr. Steve Brule",
        "street1": "179 N Harbor Dr",
        "city": "Redondo Beach",
        "state": "CA",
        "zip": "90277",
        "country": "US",
        "phone": "8573875756",
        "email": "dr_steve_brule@gmail.com"
      },
      "from_address": {
        "name": "EasyPost",
        "street1": "417 Montgomery Street",
        "street2": "5th Floor",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94104",
        "country": "US",
        "phone": "4153334445",
        "email": "support@easypost.com"
      },
      "parcel": {
        "length": 20.2,
        "width": 10.9,
        "height": 5,
        "weight": 65.9
      },
      "carrier_accounts": [
        "<ca_... from ListCarrierAccounts>"
      ]
    }
  }
}
```

Buy the label for one rate (**purchase** with a production key):

```json fleet/easypost/shipment/buy theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic": "<base64 of '<api key>:' (Hub secret EASYPOST_BASIC)>",
  "id": "shp_...",
  "body": {
    "rate": {
      "id": "rate_..."
    }
  }
}
```

Convert the bought label to ZPL for a Zebra printer on the line:

```json fleet/easypost/label/convert theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic": "<base64 of '<api key>:' (Hub secret EASYPOST_BASIC)>",
  "id": "shp_...",
  "query": "file_format=ZPL"
}
```

Track an inbound package bought elsewhere (with a test key, `EZ1000000001`-style codes simulate statuses and send test webhooks):

```json fleet/easypost/tracker/create theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic": "<base64 of '<api key>:' (Hub secret EASYPOST_BASIC)>",
  "body": {
    "tracker": {
      "tracking_code": "EZ1000000001",
      "carrier": "USPS"
    }
  }
}
```

End of shift: batch the day's shipments, then buy them, print one merged label file and a scan form:

```json fleet/easypost/batch/create theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic": "<base64 of '<api key>:' (Hub secret EASYPOST_BASIC)>",
  "body": {
    "batch": {
      "shipments": [
        {
          "id": "shp_..."
        },
        {
          "id": "shp_..."
        }
      ]
    }
  }
}
```

Register the webhook receiver:

```json fleet/easypost/webhook/create theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic": "<base64 of '<api key>:' (Hub secret EASYPOST_BASIC)>",
  "body": {
    "webhook": {
      "url": "https://<public host>/easypost/webhooks",
      "webhook_secret": "<webhook secret (Hub secret EASYPOST_WEBHOOK_SECRET)>"
    }
  }
}
```

## Example actions

These actions create a shipment when a pallet completes, buy the cheapest allowed rate, send the label to the line printer (ZPL), turn tracker webhooks into `logistics/shipments/<shipment id>` messages (or `logistics/trackers/<tracking code>` for trackers without a shipment), and track inbound packages. Replace the `<...>` placeholders.

> [!WARNING]
>
> `EasyPostBuyCheapestRate` buys postage for **every** shipment created on `fleet/easypost/shipment/create`. Run it with a test key first. With a production key, every pallet costs money.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the EasyPostApi / EasyPostWebhookReceiver routes (docs page). Not part of the route template.
# Secret: EASYPOST_BASIC = base64 of "<api key>:" (API key as the Basic username, empty password), e.g.
#   printf '%s:' "$EASYPOST_API_KEY" | base64. Start with a test key (EZTK...): nothing is bought, no carrier is
#   contacted. Replace the <...> placeholders (address ids, carrier account id) with ids from your account.
# EasyPostBuyCheapestRate needs the Python script EasyPostHelper (easypost_helper.py) deployed first, and it BUYS
#   postage for every created shipment when EASYPOST_BASIC holds a production key.

DEFINE ACTION EasyPostPalletShipment
ON TOPIC "porto/line3/palletizer/pallet-complete" DO
    SET "auth" WITH GET SECRET "EASYPOST_BASIC"
    SET "pallet" WITH (GET JSON "pallet_id" IN PAYLOAD AS STRING)
    SET "oz" WITH (GET JSON "weight_oz" IN PAYLOAD AS DOUBLE)
    PUBLISH TOPIC "fleet/easypost/shipment/create" WITH { "basic": {auth}, "body": { "shipment": { "reference": {pallet}, "from_address": { "id": "<adr_... ship-from dock>" }, "to_address": { "id": "<adr_... customer>" }, "parcel": { "length": 24, "width": 16, "height": 12, "weight": {oz} }, "carrier_accounts": [ "<ca_... from ListCarrierAccounts>" ] } } }

DEFINE ACTION EasyPostBuyCheapestRate
ON TOPIC "fleet/easypost/shipment/create/response" DO
    SET "auth" WITH GET SECRET "EASYPOST_BASIC"
    SET "shipment" WITH PAYLOAD
    CALL PYTHON "EasyPostHelper.pick_rate"
        WITH ({shipment}, "UPS,FedEx,USPS", "")
        RETURN AS {pick}
    SET "ok" WITH (GET JSON "ok" IN {pick} AS BOOL)
    IF {ok} EQUALS TRUE THEN
        SET "sid" WITH (GET JSON "shipment_id" IN {pick} AS STRING)
        SET "rid" WITH (GET JSON "rate_id" IN {pick} AS STRING)
        PUBLISH TOPIC "fleet/easypost/shipment/buy" WITH { "basic": {auth}, "id": {sid}, "body": { "rate": { "id": {rid} } } }
    ELSE
        PUBLISH TOPIC "porto/line3/shipping/rate-error" WITH {pick}

DEFINE ACTION EasyPostLabelToPrinter
ON TOPIC "fleet/easypost/shipment/buy/response" DO
    SET "auth" WITH GET SECRET "EASYPOST_BASIC"
    SET "sid" WITH (GET JSON "id" IN PAYLOAD AS STRING)
    SET "code" WITH (GET JSON "tracking_code" IN PAYLOAD AS STRING)
    SET "ref" WITH (GET JSON "reference" IN PAYLOAD AS STRING)
    SET "png" WITH (GET JSON "postage_label.label_url" IN PAYLOAD AS STRING)
    IF {code} == "null" THEN
        PUBLISH TOPIC "porto/line3/shipping/buy-error" WITH PAYLOAD
    ELSE
        PUBLISH TOPIC "porto/line3/shipping/label" WITH { "shipment_id": {sid}, "reference": {ref}, "tracking_code": {code}, "label_url": {png} }
        PUBLISH TOPIC "fleet/easypost/label/convert" WITH { "basic": {auth}, "id": {sid}, "query": "file_format=ZPL" }

DEFINE ACTION EasyPostTrackerToShipment
ON TOPIC "fleet/easypost/webhook/received" DO
    SET "desc" WITH (GET JSON "description" IN PAYLOAD AS STRING)
    IF {desc} STARTS_WITH "tracker." THEN
        SET "sid" WITH (GET JSON "result.shipment_id" IN PAYLOAD AS STRING)
        SET "code" WITH (GET JSON "result.tracking_code" IN PAYLOAD AS STRING)
        SET "carrier" WITH (GET JSON "result.carrier" IN PAYLOAD AS STRING)
        SET "status" WITH (GET JSON "result.status" IN PAYLOAD AS STRING)
        SET "eta" WITH (GET JSON "result.est_delivery_date" IN PAYLOAD AS STRING)
        IF {sid} == "null" THEN
            PUBLISH TOPIC "logistics/trackers/" + {code} WITH { "tracking_code": {code}, "carrier": {carrier}, "status": {status}, "est_delivery_date": {eta}, "event": {desc} }
        ELSE
            PUBLISH TOPIC "logistics/shipments/" + {sid} WITH { "tracking_code": {code}, "carrier": {carrier}, "status": {status}, "est_delivery_date": {eta}, "event": {desc} }

DEFINE ACTION EasyPostTrackInbound
ON TOPIC "porto/receiving/inbound/expected" DO
    SET "auth" WITH GET SECRET "EASYPOST_BASIC"
    SET "code" WITH (GET JSON "tracking_code" IN PAYLOAD AS STRING)
    SET "carrier" WITH (GET JSON "carrier" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "fleet/easypost/tracker/create" WITH { "basic": {auth}, "body": { "tracker": { "tracking_code": {code}, "carrier": {carrier} } } }
```

`EasyPostBuyCheapestRate` needs the Python script `EasyPostHelper` (`easypost_helper.py`), because LoT cannot loop over the `rates` array. Deploy it before the actions:

```python theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Script Name: EasyPostHelper
# Coreflux broker Python helper for the EasyPostApi REST_API route (beta). Optional: only the
# EasyPostBuyCheapestRate example action uses it. LoT cannot loop over the rates array of a Shipment reply, so this
# script picks the rate to buy.
# pick_rate(shipment, carriers, services)
#   shipment  the JSON reply of CreateShipment / GetShipment / RerateShipment (string or object)
#   carriers  comma-separated carrier names to allow, e.g. "UPS,FedEx,USPS" ("" = any carrier)
#   services  comma-separated service names to allow, e.g. "Ground,GROUND_HOME_DELIVERY" ("" = any service)
# Returns {"ok": true, "shipment_id", "rate_id", "carrier", "service", "rate", "currency", "delivery_days",
#   "reference"} for the cheapest matching rate, or {"ok": false, "reason", "shipment_id", "messages"} when the reply
#   is an error, the shipment is already bought, or no rate matches (carrier errors are in "messages").
import json

def _csv(value):
    return [v.strip().lower() for v in (value or "").split(",") if v.strip()]

def pick_rate(shipment, carriers="", services=""):
    try:
        s = json.loads(shipment) if isinstance(shipment, str) else (shipment or {})
    except ValueError:
        return {"ok": False, "reason": "reply is not JSON", "shipment_id": None, "messages": []}
    if not isinstance(s, dict):
        return {"ok": False, "reason": "reply is not a JSON object", "shipment_id": None, "messages": []}
    sid = s.get("id")
    messages = s.get("messages") or []
    if "error" in s:
        return {"ok": False, "reason": "EasyPost error: " + str((s.get("error") or {}).get("code")), "shipment_id": sid, "messages": messages}
    if s.get("object") != "Shipment" or not sid:
        return {"ok": False, "reason": "not a Shipment object", "shipment_id": sid, "messages": messages}
    if s.get("selected_rate") or s.get("postage_label"):
        return {"ok": False, "reason": "shipment already bought", "shipment_id": sid, "messages": messages}
    allow_c, allow_s = _csv(carriers), _csv(services)
    best = None
    for r in s.get("rates") or []:
        try:
            price = float(r.get("rate"))
        except (TypeError, ValueError):
            continue
        if allow_c and str(r.get("carrier", "")).lower() not in allow_c:
            continue
        if allow_s and str(r.get("service", "")).lower() not in allow_s:
            continue
        if best is None or price < best[0]:
            best = (price, r)
    if best is None:
        return {"ok": False, "reason": "no rate matches the carrier / service filter", "shipment_id": sid, "messages": messages}
    r = best[1]
    return {"ok": True, "shipment_id": sid, "rate_id": r.get("id"), "carrier": r.get("carrier"), "service": r.get("service"),
            "rate": r.get("rate"), "currency": r.get("currency"), "delivery_days": r.get("delivery_days"), "reference": s.get("reference")}
```

## Connector template

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — EasyPost (beta): multi-carrier shipping labels, rates and tracking.
#   Addresses (create, verify), parcels, customs, shipments (create with rates, buy label, convert label to ZPL /
#   EPL2 / PDF, rerate, SmartRate, insure, refund), stateless rate estimates, trackers (create, get, list, batch),
#   multi-parcel orders, batches (bulk buy, merged label, scan form), scan forms (manifests), carrier pickups, label
#   refunds, events and webhooks, carrier accounts / types / metadata and the account user (wallet balance).
#   easypost-python v10.7.0 services (client-python/). EasyPost publishes no OpenAPI spec. Credentials are
#   placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/easypost
#
# One client route EasyPostApi on https://api.easypost.com. Endpoints carry /v2 (the queue hint
#   https://api.easypost.com/v2/) except EstimateRates, which is the beta API under /beta.
# Auth: HTTP Basic with the API key as the username and an empty password, i.e. Authorization: Basic
#   base64("<api key>:"). Pass that base64 value as "basic" in every payload; keep it in a Hub secret
#   (EASYPOST_BASIC, or build it from EASYPOST_API_KEY) and read it with GET SECRET in an action. Never commit it.
#   Test keys (EZTK...) are free: no postage is bought and no carrier is contacted. Production keys (EZAK...) spend
#   wallet money on every event marked # PURCHASE (and on One-Call Buy). Keys act on the whole account.
#   Live (2026-10-06): no Authorization -> 401 UNAUTHORIZED for every packaged method + path (an unknown method or
#   path -> 404 NOT_FOUND); a fake key, Basic or Bearer -> 403 APIKEY.INACTIVE.
# Payload fields (control fields stay out of bodies; request bodies come from {value.json.body}):
#   basic, id, query, body
#   id is the EasyPost object id (shp_..., rate_..., adr_..., trk_..., batch_..., order_..., pickup_..., sf_...,
#   evt_..., hook_...), placed in the path: pass ids you got from EasyPost, never raw user input. query is the URL
#   query string without '?', e.g. page_size=20&before_id=shp_... (URL-encode values yourself). body is the JSON body
#   with EasyPost's wrapper key where it has one ({"shipment": {...}}, {"tracker": {...}}, {"address": {...}}, ...).
# Units: parcel length / width / height in inches, weight in ounces; money as decimal strings in USD.
# Replies: objects as JSON with "object" and "mode" (test / production); lists as {"<objects>": [...], "has_more"}
#   (newest first, page_size max 100, next page with before_id = last id). Errors: {"error": {"code", "message",
#   "errors": [...]}} with 4xx / 5xx. Rate-limited calls answer 429.

DEFINE CONNECTOR EasyPostApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.easypost.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # The authenticated user (id, name, balance, recharge settings, child users)
    ADD EVENT GetUser
        WITH SOURCE_TOPIC "fleet/easypost/user/get"
        WITH DESTINATION_TOPIC "fleet/easypost/user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Carrier accounts on the EasyPost account (ids ca_... for carrier_accounts in shipments)
    ADD EVENT ListCarrierAccounts
        WITH SOURCE_TOPIC "fleet/easypost/carrier-account/list"
        WITH DESTINATION_TOPIC "fleet/easypost/carrier-account/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/carrier_accounts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Carrier types that can be added and their credential fields
    ADD EVENT ListCarrierTypes
        WITH SOURCE_TOPIC "fleet/easypost/carrier-type/list"
        WITH DESTINATION_TOPIC "fleet/easypost/carrier-type/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/carrier_types"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Carrier metadata: service levels, predefined packages, shipment options, supported features
    ADD EVENT GetCarrierMetadata
        WITH SOURCE_TOPIC "fleet/easypost/carrier-metadata/get"
        WITH DESTINATION_TOPIC "fleet/easypost/carrier-metadata/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/metadata/carriers?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreateAddress changes data in EasyPost. Restrict who can publish to fleet/easypost/address/create.
    # Create an address; verify / verify_strict run address verification (result in verifications)
    ADD EVENT CreateAddress
        WITH SOURCE_TOPIC "fleet/easypost/address/create"
        WITH DESTINATION_TOPIC "fleet/easypost/address/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/addresses"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: CreateAndVerifyAddress changes data in EasyPost. Restrict who can publish to fleet/easypost/address/create-verify.
    # Create and strictly verify an address in one call; fails with ADDRESS.VERIFY.FAILURE when it cannot be verified
    ADD EVENT CreateAndVerifyAddress
        WITH SOURCE_TOPIC "fleet/easypost/address/create-verify"
        WITH DESTINATION_TOPIC "fleet/easypost/address/create-verify/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/addresses/create_and_verify"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Verify an existing address
    ADD EVENT VerifyAddress
        WITH SOURCE_TOPIC "fleet/easypost/address/verify"
        WITH DESTINATION_TOPIC "fleet/easypost/address/verify/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/addresses/{value.json.id}/verify"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # One address by id
    ADD EVENT GetAddress
        WITH SOURCE_TOPIC "fleet/easypost/address/get"
        WITH DESTINATION_TOPIC "fleet/easypost/address/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/addresses/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreateParcel changes data in EasyPost. Restrict who can publish to fleet/easypost/parcel/create.
    # Create a parcel (inches and ounces, or a predefined_package)
    ADD EVENT CreateParcel
        WITH SOURCE_TOPIC "fleet/easypost/parcel/create"
        WITH DESTINATION_TOPIC "fleet/easypost/parcel/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/parcels"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: CreateCustomsInfo changes data in EasyPost. Restrict who can publish to fleet/easypost/customs-info/create.
    # Customs declaration (with customs items) for international shipments
    ADD EVENT CreateCustomsInfo
        WITH SOURCE_TOPIC "fleet/easypost/customs-info/create"
        WITH DESTINATION_TOPIC "fleet/easypost/customs-info/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/customs_infos"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: CreateShipment changes data in EasyPost. With service + carrier_accounts in the body it is a One-Call Buy and PURCHASES postage. Restrict who can publish to fleet/easypost/shipment/create.
    # Create a shipment and get its rates (no charge). Adding service + carrier_accounts makes it a One-Call Buy that purchases postage
    ADD EVENT CreateShipment
        WITH SOURCE_TOPIC "fleet/easypost/shipment/create"
        WITH DESTINATION_TOPIC "fleet/easypost/shipment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/shipments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # One shipment (rates, selected_rate, postage_label, tracker, fees)
    ADD EVENT GetShipment
        WITH SOURCE_TOPIC "fleet/easypost/shipment/get"
        WITH DESTINATION_TOPIC "fleet/easypost/shipment/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/shipments/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Shipments, newest first; page_size (max 100), before_id / after_id, start_datetime / end_datetime; has_more
    ADD EVENT ListShipments
        WITH SOURCE_TOPIC "fleet/easypost/shipment/list"
        WITH DESTINATION_TOPIC "fleet/easypost/shipment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/shipments?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # PURCHASE: BuyShipment spends money on a production key. Use a test key first; restrict who can publish to fleet/easypost/shipment/buy.
    # Buy the label for one rate (adds tracking_code, postage_label, tracker); optional insurance (USD string) and end_shipper_id
    ADD EVENT BuyShipment
        WITH SOURCE_TOPIC "fleet/easypost/shipment/buy"
        WITH DESTINATION_TOPIC "fleet/easypost/shipment/buy/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/shipments/{value.json.id}/buy"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Convert a bought PNG label to ZPL, EPL2 or PDF (label_zpl_url / label_epl2_url / label_pdf_url)
    ADD EVENT ConvertShipmentLabel
        WITH SOURCE_TOPIC "fleet/easypost/label/convert"
        WITH DESTINATION_TOPIC "fleet/easypost/label/convert/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/shipments/{value.json.id}/label?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Regenerate the rates of an unbought shipment (no body, no charge)
    ADD EVENT RerateShipment
        WITH SOURCE_TOPIC "fleet/easypost/rate/rerate"
        WITH DESTINATION_TOPIC "fleet/easypost/rate/rerate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/shipments/{value.json.id}/rerate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # SmartRate: rates with time-in-transit percentiles for the shipment
        WITH BODY ""
    ADD EVENT GetShipmentSmartRates
        WITH SOURCE_TOPIC "fleet/easypost/smartrate/get"
        WITH DESTINATION_TOPIC "fleet/easypost/smartrate/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/shipments/{value.json.id}/smartrate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # PURCHASE: InsureShipment spends money on a production key. Use a test key first; restrict who can publish to fleet/easypost/shipment/insure.
    # Insure a bought shipment for amount (USD); charges the insurance fee
    ADD EVENT InsureShipment
        WITH SOURCE_TOPIC "fleet/easypost/shipment/insure"
        WITH DESTINATION_TOPIC "fleet/easypost/shipment/insure/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/shipments/{value.json.id}/insure"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: RefundShipment changes data in EasyPost. Restrict who can publish to fleet/easypost/shipment/refund.
    # Request a refund of an unused label (refund_status submitted; USPS refunds take up to 15 days)
    ADD EVENT RefundShipment
        WITH SOURCE_TOPIC "fleet/easypost/shipment/refund"
        WITH DESTINATION_TOPIC "fleet/easypost/shipment/refund/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/shipments/{value.json.id}/refund"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # One rate by id
        WITH BODY ""
    ADD EVENT GetRate
        WITH SOURCE_TOPIC "fleet/easypost/rate/get"
        WITH DESTINATION_TOPIC "fleet/easypost/rate/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/rates/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Stateless rates for addresses and a parcel without creating a shipment (beta API under /beta)
    ADD EVENT EstimateRates
        WITH SOURCE_TOPIC "fleet/easypost/rate/estimate"
        WITH DESTINATION_TOPIC "fleet/easypost/rate/estimate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/beta/rates"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Delivery date predictions by carrier and service for a ZIP pair and ship date
    ADD EVENT SmartRateDeliverBy
        WITH SOURCE_TOPIC "fleet/easypost/smartrate/deliver-by"
        WITH DESTINATION_TOPIC "fleet/easypost/smartrate/deliver-by/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/smartrate/deliver_by"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: CreateTracker changes data in EasyPost. Restrict who can publish to fleet/easypost/tracker/create.
    # Track a package not bought through EasyPost (EZ... test codes simulate statuses with a test key); trackers may be billed in production
    ADD EVENT CreateTracker
        WITH SOURCE_TOPIC "fleet/easypost/tracker/create"
        WITH DESTINATION_TOPIC "fleet/easypost/tracker/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/trackers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # One tracker (status, est_delivery_date, tracking_details, carrier_detail)
    ADD EVENT GetTracker
        WITH SOURCE_TOPIC "fleet/easypost/tracker/get"
        WITH DESTINATION_TOPIC "fleet/easypost/tracker/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/trackers/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Trackers, newest first; filter by tracking_code and carrier
    ADD EVENT ListTrackers
        WITH SOURCE_TOPIC "fleet/easypost/tracker/list"
        WITH DESTINATION_TOPIC "fleet/easypost/tracker/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/trackers?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Many trackers by tracking_codes in one call (POST, read only)
    ADD EVENT RetrieveTrackerBatch
        WITH SOURCE_TOPIC "fleet/easypost/tracker/batch"
        WITH DESTINATION_TOPIC "fleet/easypost/tracker/batch/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/trackers/batch"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: CreateOrder changes data in EasyPost. With service + carrier_accounts in the body it is a One-Call Buy and PURCHASES postage. Restrict who can publish to fleet/easypost/order/create.
    # Multi-parcel order (one shipment per carton) with rates; only some carriers (FedEx, UPS, DHLExpress, ...); service + carrier_accounts make it a One-Call Buy
    ADD EVENT CreateOrder
        WITH SOURCE_TOPIC "fleet/easypost/order/create"
        WITH DESTINATION_TOPIC "fleet/easypost/order/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/orders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # PURCHASE: BuyOrder spends money on a production key. Use a test key first; restrict who can publish to fleet/easypost/order/buy.
    # Buy every shipment of an order for one carrier + service
    ADD EVENT BuyOrder
        WITH SOURCE_TOPIC "fleet/easypost/order/buy"
        WITH DESTINATION_TOPIC "fleet/easypost/order/buy/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/orders/{value.json.id}/buy"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # One order with its shipments and rates
    ADD EVENT GetOrder
        WITH SOURCE_TOPIC "fleet/easypost/order/get"
        WITH DESTINATION_TOPIC "fleet/easypost/order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/orders/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreateBatch changes data in EasyPost. Restrict who can publish to fleet/easypost/batch/create.
    # Group shipments into a batch (end-of-shift label run)
    ADD EVENT CreateBatch
        WITH SOURCE_TOPIC "fleet/easypost/batch/create"
        WITH DESTINATION_TOPIC "fleet/easypost/batch/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/batches"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # One batch (state, status counts, label_url, scan_form)
    ADD EVENT GetBatch
        WITH SOURCE_TOPIC "fleet/easypost/batch/get"
        WITH DESTINATION_TOPIC "fleet/easypost/batch/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/batches/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Batches, newest first
    ADD EVENT ListBatches
        WITH SOURCE_TOPIC "fleet/easypost/batch/list"
        WITH DESTINATION_TOPIC "fleet/easypost/batch/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/batches?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: AddBatchShipments changes data in EasyPost. Restrict who can publish to fleet/easypost/batch-shipment/add.
    # Add shipments to a batch
    ADD EVENT AddBatchShipments
        WITH SOURCE_TOPIC "fleet/easypost/batch-shipment/add"
        WITH DESTINATION_TOPIC "fleet/easypost/batch-shipment/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/batches/{value.json.id}/add_shipments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: RemoveBatchShipments changes data in EasyPost. Restrict who can publish to fleet/easypost/batch-shipment/remove.
    # Remove shipments from a batch
    ADD EVENT RemoveBatchShipments
        WITH SOURCE_TOPIC "fleet/easypost/batch-shipment/remove"
        WITH DESTINATION_TOPIC "fleet/easypost/batch-shipment/remove/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/batches/{value.json.id}/remove_shipments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # PURCHASE: BuyBatch spends money on a production key. Use a test key first; restrict who can publish to fleet/easypost/batch/buy.
    # Buy every shipment in a batch (asynchronous; batch.updated events; no body)
    ADD EVENT BuyBatch
        WITH SOURCE_TOPIC "fleet/easypost/batch/buy"
        WITH DESTINATION_TOPIC "fleet/easypost/batch/buy/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/batches/{value.json.id}/buy"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreateBatchLabel changes data in EasyPost. Restrict who can publish to fleet/easypost/batch-label/create.
    # One merged label file (PDF, EPL2 or ZPL) for a bought batch (asynchronous; label_url)
        WITH BODY ""
    ADD EVENT CreateBatchLabel
        WITH SOURCE_TOPIC "fleet/easypost/batch-label/create"
        WITH DESTINATION_TOPIC "fleet/easypost/batch-label/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/batches/{value.json.id}/label"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: CreateBatchScanForm changes data in EasyPost. Restrict who can publish to fleet/easypost/batch-scan-form/create.
    # ScanForm (manifest) for a bought batch (no body)
    ADD EVENT CreateBatchScanForm
        WITH SOURCE_TOPIC "fleet/easypost/batch-scan-form/create"
        WITH DESTINATION_TOPIC "fleet/easypost/batch-scan-form/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/batches/{value.json.id}/scan_form"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreateScanForm changes data in EasyPost. Restrict who can publish to fleet/easypost/scan-form/create.
    # ScanForm (manifest) for bought shipments of one carrier and from address, for the driver to scan at pickup
        WITH BODY ""
    ADD EVENT CreateScanForm
        WITH SOURCE_TOPIC "fleet/easypost/scan-form/create"
        WITH DESTINATION_TOPIC "fleet/easypost/scan-form/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/scan_forms"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # One ScanForm (status, form_url, tracking_codes)
    ADD EVENT GetScanForm
        WITH SOURCE_TOPIC "fleet/easypost/scan-form/get"
        WITH DESTINATION_TOPIC "fleet/easypost/scan-form/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/scan_forms/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # ScanForms, newest first
    ADD EVENT ListScanForms
        WITH SOURCE_TOPIC "fleet/easypost/scan-form/list"
        WITH DESTINATION_TOPIC "fleet/easypost/scan-form/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/scan_forms?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreatePickup changes data in EasyPost. Restrict who can publish to fleet/easypost/pickup/create.
    # Request a carrier pickup window for a bought shipment (or batch); reply carries pickup_rates
    ADD EVENT CreatePickup
        WITH SOURCE_TOPIC "fleet/easypost/pickup/create"
        WITH DESTINATION_TOPIC "fleet/easypost/pickup/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/pickups"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # PURCHASE: BuyPickup spends money on a production key. Use a test key first; restrict who can publish to fleet/easypost/pickup/buy.
    # Buy one pickup rate by carrier + service (not by id); confirmation in the reply
    ADD EVENT BuyPickup
        WITH SOURCE_TOPIC "fleet/easypost/pickup/buy"
        WITH DESTINATION_TOPIC "fleet/easypost/pickup/buy/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/pickups/{value.json.id}/buy"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: CancelPickup changes data in EasyPost. Restrict who can publish to fleet/easypost/pickup/cancel.
    # Cancel a scheduled pickup (no body)
    ADD EVENT CancelPickup
        WITH SOURCE_TOPIC "fleet/easypost/pickup/cancel"
        WITH DESTINATION_TOPIC "fleet/easypost/pickup/cancel/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/pickups/{value.json.id}/cancel"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # One pickup (status, confirmation, pickup_rates)
        WITH BODY ""
    ADD EVENT GetPickup
        WITH SOURCE_TOPIC "fleet/easypost/pickup/get"
        WITH DESTINATION_TOPIC "fleet/easypost/pickup/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/pickups/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Pickups, newest first
    ADD EVENT ListPickups
        WITH SOURCE_TOPIC "fleet/easypost/pickup/list"
        WITH DESTINATION_TOPIC "fleet/easypost/pickup/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/pickups?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreateRefund changes data in EasyPost. Restrict who can publish to fleet/easypost/refund/create.
    # Refund labels by carrier + tracking codes
    ADD EVENT CreateRefund
        WITH SOURCE_TOPIC "fleet/easypost/refund/create"
        WITH DESTINATION_TOPIC "fleet/easypost/refund/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/refunds"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Events (tracker.updated, batch.updated, scan_form.updated, refund.successful, ...) for webhook catch-up; result is not included
    ADD EVENT ListEvents
        WITH SOURCE_TOPIC "fleet/easypost/event/list"
        WITH DESTINATION_TOPIC "fleet/easypost/event/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/events?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # One event (description, status, pending_urls, completed_urls)
    ADD EVENT GetEvent
        WITH SOURCE_TOPIC "fleet/easypost/event/get"
        WITH DESTINATION_TOPIC "fleet/easypost/event/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/events/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # Webhook delivery attempts of one event (request body, response code, URL)
    ADD EVENT ListEventPayloads
        WITH SOURCE_TOPIC "fleet/easypost/event-payload/list"
        WITH DESTINATION_TOPIC "fleet/easypost/event-payload/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/events/{value.json.id}/payloads"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: CreateWebhook changes data in EasyPost. Restrict who can publish to fleet/easypost/webhook/create.
    # Register a webhook URL for this key's mode (a test key registers a test-mode webhook); every event is sent to every webhook
    ADD EVENT CreateWebhook
        WITH SOURCE_TOPIC "fleet/easypost/webhook/create"
        WITH DESTINATION_TOPIC "fleet/easypost/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Webhooks of this mode (url, disabled_at)
    ADD EVENT ListWebhooks
        WITH SOURCE_TOPIC "fleet/easypost/webhook/list"
        WITH DESTINATION_TOPIC "fleet/easypost/webhook/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # One webhook
    ADD EVENT GetWebhook
        WITH SOURCE_TOPIC "fleet/easypost/webhook/get"
        WITH DESTINATION_TOPIC "fleet/easypost/webhook/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/webhooks/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    # WRITE: UpdateWebhook changes data in EasyPost. Restrict who can publish to fleet/easypost/webhook/update.
    # Re-enable a disabled webhook and / or replace webhook_secret and custom_headers (custom_headers is replaced as a whole)
    ADD EVENT UpdateWebhook
        WITH SOURCE_TOPIC "fleet/easypost/webhook/update"
        WITH DESTINATION_TOPIC "fleet/easypost/webhook/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/webhooks/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

### Webhook receiver template

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# EasyPost webhook receiver — REST_API route (server mode, beta, companion of EasypostRestApi.lot)
#   Receives EasyPost webhook Events (tracker, batch, scan form, refund, insurance, report, payment, invoice, claim)
#   and publishes each JSON body on MQTT, so tracking updates reach the broker without polling. Opt-in: deploying it
#   opens an HTTP port.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/easypost
#
# Set up: create one webhook per API key mode with CreateWebhook (or Dashboard > Webhooks and Events): the production
#   key -> https://<public host>/easypost/webhooks, the test key -> https://<public host>/easypost/webhooks/test.
#   EasyPost sends every Event of that mode to every webhook (no per-type filter); route by "description"
#   (tracker.updated, batch.updated, ...) in an action. Delivery is at least once, so handle duplicates (Event id).
#   EasyPost needs HTTPS with a publicly trusted certificate: put a reverse proxy or tunnel in front of SERVER_PORT 9014.
#   Answer 2xx; endpoints that keep failing are disabled (re-enable with UpdateWebhook). With a webhook_secret, EasyPost
#   signs each body in the X-Hmac-Signature header (HMAC-SHA256); with https://user:pass@host/... it sends Basic auth.
#   This route checks neither, so verify them in the proxy (or keep the URL secret and restrict source addresses).

DEFINE CONNECTOR EasyPostWebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9014'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # production-mode events: tracker.created / tracker.updated, batch.created / batch.updated, scan_form.created / scan_form.updated, refund.successful, insurance.*, report.*, payment.*, shipment.invoice.*, claim.* (POST https://<public host>/easypost/webhooks)
    ADD EVENT WebhookEvents
        WITH ENDPOINT "/easypost/webhooks"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "fleet/easypost/webhook/received"
    # test-mode events (webhook created with a test API key; EZ... test tracking codes trigger tracker events) (POST https://<public host>/easypost/webhooks/test)
    ADD EVENT TestWebhookEvents
        WITH ENDPOINT "/easypost/webhooks/test"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "fleet/easypost/webhook-test/received"
```

## Limits and behaviour

* **Units:** parcel dimensions in inches, weight in ounces; money as decimal strings in USD (`insurance`, `amount`).
* **Pallets:** EasyPost is a parcel API. A whole pallet over the carriers' parcel weight or size limits needs LTL freight, which this API does not cover. Ship the pallet's cartons as parcels, one `CreateShipment` each or one multi-parcel `CreateOrder` (only some carriers support orders).
* **Labels** are PNG by default; `ConvertShipmentLabel` converts a bought label to ZPL, EPL2 or PDF, or set `options.label_format` when you create the shipment. `CreateBatchLabel` builds one merged file for a bought batch.
* **Asynchronous objects:** batch buy and batch labels, scan forms and refunds finish later; follow them with `GetBatch` / `GetScanForm` or the `batch.updated`, `scan_form.updated` and `refund.successful` webhook Events.
* **Refunds:** `RefundShipment` and `CreateRefund` work on unused labels; USPS refunds can take up to 15 days (`refund.successful`).
* **Trackers** are created automatically when a label is bought. Standalone `CreateTracker` calls for labels bought elsewhere may be billed in production; check EasyPost pricing.
* **Test mode:** a test key returns test objects (`mode: test`), buys nothing and contacts no carrier; test tracking codes simulate tracker statuses and send test-mode webhook Events.
* **Webhooks:** every Event goes to every webhook of the mode, at least once. `ListEvents` and `ListEventPayloads` help to catch up after downtime.
* **Errors:** `{"error": {"code", "message", "errors"}}`. `401 UNAUTHORIZED` means no credentials, `403 APIKEY.INACTIVE` a wrong or disabled key, `404 NOT_FOUND` an unknown id or path, `422` a validation error (for example `SHIPMENT.POSTAGE.EXISTS` when buying twice). Rate-limited calls answer `429`.

### Notes on the EasyPost docs

* The rendered cURL tabs on several docs.easypost.com pages show a different call than their heading: `POST /shipments/:id/buy` shows `POST /v2/shipments` (create), `GET /shipments/:id/label` shows a plain retrieve, `POST /trackers/batch` shows `POST /v2/trackers`, `POST /orders/:id/buy` shows `POST /v2/orders`, `POST /pickups/:id/buy` and `/cancel` show `POST /v2/pickups`, `GET /events/:event_id/payloads` shows the single-payload URL, and the EndShipper page labels its create call `POST /shipments/:id/buy`. The template follows the headings, the official EasyPost/examples cURL files and easypost-python v10.7.0.
* Some docs JSON bodies are not valid JSON (trailing commas in the webhook create / update examples, unquoted `[UPS]` in the SmartRate deliver\_by / deliver\_on examples); the template examples are valid JSON.
* The rate estimate API is `POST /beta/rates`, outside `/v2`, so the connector base is `https://api.easypost.com` and each endpoint carries `/v2` or `/beta`.
* The docs describe HTTP Basic (key as username, empty password); the official client libraries send `Authorization: Bearer <key>`. The auth layer parses both (same `403` for a fake key); the template uses Basic as documented.
* `GetRate` (`GET /v2/rates/{id}`) has no docs page; it is the official client's `rate.retrieve`.
* No official OpenAPI spec is published (llms.txt points to Markdown twins and doc-index.json); request parameter tables on the docs pages are rendered client-side and missing from the Markdown twins, so query parameter names come from cURL examples, the pagination page and the official client.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps catalog](/latest/lot-language/routes/rest-api-apps/index)
* [EasyPost API docs](https://docs.easypost.com)
* [EasyPost webhooks](https://docs.easypost.com/docs/webhooks)


# Eclipse Ditto (digital twins)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/eclipse-ditto

Connect Coreflux LoT to Eclipse Ditto digital twins: create and merge things, write feature properties from telemetry, send live messages and search twins

Technical Preview

## Overview

One client-mode connector, **EclipseDitto**, for the [Eclipse Ditto](https://eclipse.dev/ditto/) HTTP API 2. Ditto is an open-source digital twin framework: every device or asset is a **thing** with attributes (static metadata) and **features** (groups of live properties and desired properties), and access is controlled per thing by a **policy**.

Use the connector to keep a twin in step with the plant floor: merge each telemetry message from the broker into a feature, tag things with their UNS path and line, read the twin or a single property back, set a desired setpoint, send a live command through Ditto to the device, and find every twin on a line with one RQL search.

| Event | Request | Notes |
| - | - | - |
| ListThings | `GET /things?ids={ids}` | `ids` is a comma-separated list of thing ids |
| GetThing | `GET /things/{thing_id}` | Whole twin: policy id, attributes, features |
| CreateThing | `POST /things` | Ditto generates the thing id; returns `201` |
| PutThing | `PUT /things/{thing_id}` | `201` created or `204` replaced |
| PatchThing | `PATCH /things/{thing_id}` | JSON merge patch; `null` deletes a key |
| DeleteThing | `DELETE /things/{thing_id}` | Returns `204` |
| GetAttributes | `GET /things/{thing_id}/attributes` | |
| PutAttribute | `PUT /things/{thing_id}/attributes/{attribute_path}` | Body is the raw JSON value |
| ListFeatures | `GET /things/{thing_id}/features` | |
| GetFeature | `GET /things/{thing_id}/features/{feature_id}` | |
| PutFeature | `PUT /things/{thing_id}/features/{feature_id}` | Whole feature with `properties` |
| GetFeatureProperties | `GET /things/{thing_id}/features/{feature_id}/properties` | |
| PutFeatureProperties | `PUT /things/{thing_id}/features/{feature_id}/properties` | |
| PatchFeatureProperties | `PATCH /things/{thing_id}/features/{feature_id}/properties` | Merge telemetry into a feature; returns `204` |
| GetFeatureProperty | `GET /things/{thing_id}/features/{feature_id}/properties/{property_path}` | `property_path` may contain slashes |
| PutFeatureProperty | `PUT /things/{thing_id}/features/{feature_id}/properties/{property_path}` | |
| GetDesiredProperties | `GET /things/{thing_id}/features/{feature_id}/desiredProperties` | |
| PutDesiredProperty | `PUT /things/{thing_id}/features/{feature_id}/desiredProperties/{property_path}` | Desired value the device should converge to |
| SendThingMessage | `POST /things/{thing_id}/inbox/messages/{subject}?timeout={timeout}` | `timeout` `0` returns `202`; otherwise waits for the reply |
| SendFeatureMessage | `POST /things/{thing_id}/features/{feature_id}/inbox/messages/{subject}?timeout={timeout}` | Same, addressed to one feature |
| SearchThings | `GET /search/things?{query}` | Pre-encoded RQL query, e.g. `filter=...&option=size(50)` |
| CountThings | `GET /search/things/count?{query}` | Same `query`; returns a number |
| GetPolicy | `GET /policies/{policy_id}` | |
| PutPolicy | `PUT /policies/{policy_id}` | Who can read and write the thing |
| WhoAmI | `GET /whoami` | Shows the subject your credentials map to |
| ListConnections | `GET /connections` | Devops credentials |
| GetConnectionStatus | `GET /connections/{connection_id}/status` | Devops credentials |

Topics are `cloud-iot/eclipse-ditto/<object>/<verb>`; every reply goes to `<topic>/response`. Paths in the table are relative to `/api/2`.

## Authentication

Ditto is self-hosted or run by a vendor, so authentication depends on how your gateway is set up. Every event sends `Authorization: {authorization}`, so pass the whole header value:

* `"Basic <base64(user:password)>"` when Ditto sits behind nginx basic auth (the default Docker Compose stack, with user `ditto`).
* `"Bearer <JWT>"` when Ditto is configured for an OpenID Connect provider such as Keycloak or Microsoft Entra ID.

Keep it in a broker secret (suggested `DITTO_AUTHORIZATION`) and map it in with `GET SECRET`. `ListConnections` and `GetConnectionStatus` are devops endpoints and need the devops credentials instead (suggested `DITTO_DEVOPS_AUTHORIZATION`). Wrong credentials return `401`; a policy that does not grant `READ` or `WRITE` returns `403` or `404`.

## Basic Syntax

Set `BASE_ADDRESS` to your Ditto gateway or nginx front, with no trailing slash. For the local Docker Compose stack that is `http://localhost:8080`, with `USE_SSL "false"`.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EclipseDitto WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DITTO_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListThings
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/thing/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/thing/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things?ids={value.json.ids}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetThing
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/thing/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/thing/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateThing
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/thing/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/thing/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2/things"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT PutThing
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/thing/put"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/thing/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT PatchThing
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/thing/patch"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/thing/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/merge-patch+json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteThing
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/thing/delete"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/thing/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetAttributes
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/attributes/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/attributes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/attributes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT PutAttribute
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/attribute/put"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/attribute/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/attributes/{value.json.attribute_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListFeatures
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetFeature
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT PutFeature
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature/put"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetFeatureProperties
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature-properties/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature-properties/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT PutFeatureProperties
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature-properties/put"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature-properties/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT PatchFeatureProperties
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature-properties/patch"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature-properties/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/merge-patch+json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetFeatureProperty
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature-property/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature-property/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/properties/{value.json.property_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT PutFeatureProperty
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature-property/put"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature-property/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/properties/{value.json.property_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDesiredProperties
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/desired-properties/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/desired-properties/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/desiredProperties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT PutDesiredProperty
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/desired-property/put"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/desired-property/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/desiredProperties/{value.json.property_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT SendThingMessage
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/thing-message/send"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/thing-message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/inbox/messages/{value.json.subject}?timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT SendFeatureMessage
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/feature-message/send"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/feature-message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/2/things/{value.json.thing_id}/features/{value.json.feature_id}/inbox/messages/{value.json.subject}?timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT SearchThings
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/search/things"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/search/things/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/search/things?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CountThings
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/search/count"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/search/count/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/search/things/count?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetPolicy
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/policy/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/policy/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/policies/{value.json.policy_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT PutPolicy
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/policy/put"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/policy/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/2/policies/{value.json.policy_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT WhoAmI
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/whoami/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/whoami/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/whoami"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListConnections
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/connection/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/connection/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/connections"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetConnectionStatus
        WITH SOURCE_TOPIC "cloud-iot/eclipse-ditto/connection/status"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-ditto/connection/status/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/2/connections/{value.json.connection_id}/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

## MQTT examples

Request bodies go under `body`, so control fields like `authorization`, `thing_id` and `feature_id` are not sent to Ditto. Thing ids are `<namespace>:<name>`.

**Create a twin for a press**: create its policy on `cloud-iot/eclipse-ditto/policy/put`, then publish to `cloud-iot/eclipse-ditto/thing/put`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "thing_id": "org.coreflux:press-07",
  "body": {
    "policyId": "org.coreflux:press-07",
    "attributes": {"site": "porto", "line": "line-1", "uns": "porto/line1/press07"},
    "features": {"telemetry": {"properties": {"temperature": 0, "pressure": 0}}}
  }
}
```

Ditto returns `201` with the new thing, or `204` when it replaced an existing one.

**Merge telemetry into the twin**: publish each reading to `cloud-iot/eclipse-ditto/feature-properties/patch`. It sends a JSON merge patch, so only the keys you send change and `null` removes a key:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "thing_id": "org.coreflux:press-07",
  "feature_id": "telemetry",
  "body": {"temperature": 71.4, "pressure": 4.2, "state": "RUNNING"}
}
```

**Read one property back**: publish `{"authorization": "...", "thing_id": "org.coreflux:press-07", "feature_id": "telemetry", "property_path": "temperature"}` to `cloud-iot/eclipse-ditto/feature-property/get`. Nested paths use slashes, for example `"status/alarm"`.

**Set a desired setpoint**: publish to `cloud-iot/eclipse-ditto/desired-property/put` with `"property_path": "speed"` and `"body": 1500`. The body is the raw JSON value, so a string must be a JSON string such as `"body": "\"AUTO\""`.

**Send a live command to the device**: publish to `cloud-iot/eclipse-ditto/thing-message/send`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "thing_id": "org.coreflux:press-07",
  "subject": "set-speed",
  "timeout": "10s",
  "body": {"setpoint": 1500}
}
```

With `"timeout": "0"` Ditto accepts the message with `202` and does not wait; with a timeout it waits for the device's reply and returns `408` if no device answers in time.

**Find every twin on a line**: publish to `cloud-iot/eclipse-ditto/search/things` with a pre-encoded [RQL](https://eclipse.dev/ditto/basic-rql.html) query:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "query": "filter=eq(attributes%2Fline%2C%22line-1%22)&option=size(50)"
}
```

`cloud-iot/eclipse-ditto/search/count` takes the same `query` and returns a number.

## Helper actions

Keep the credentials in a broker secret and mirror plant telemetry into Ditto as it arrives:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DittoMirrorPressTelemetry
ON TOPIC "porto/line1/+/telemetry" DO
    SET "auth" WITH GET SECRET "DITTO_AUTHORIZATION"
    SET "machine" WITH TOPIC POSITION 3
    SET "thing" WITH "org.coreflux:" + {machine}
    SET "temperature" WITH GET JSON "temperature" IN PAYLOAD AS DOUBLE
    SET "pressure" WITH GET JSON "pressure" IN PAYLOAD AS DOUBLE
    PUBLISH TOPIC "cloud-iot/eclipse-ditto/feature-properties/patch" WITH { "authorization": {auth}, "thing_id": {thing}, "feature_id": "telemetry", "body": { "temperature": {temperature}, "pressure": {pressure} } }

DEFINE ACTION DittoCountLineTwins
ON EVERY 15 MINUTES DO
    SET "auth" WITH GET SECRET "DITTO_AUTHORIZATION"
    PUBLISH TOPIC "cloud-iot/eclipse-ditto/search/count" WITH { "authorization": {auth}, "query": "filter=eq(attributes%2Fline%2C%22line-1%22)" }
```

`DittoMirrorPressTelemetry` assumes thing ids match the machine segment of the topic, for example `org.coreflux:press07`. Restrict who can publish to `cloud-iot/eclipse-ditto/#` with a rule: its payloads carry the credentials and can change twins and send commands to devices.

## Notes

* Errors come back on the response topic: `400` for bad JSON, a bad RQL filter or an invalid id, `401` for missing or wrong credentials, `403` when the policy does not allow the change, `404` for an unknown thing, feature, property or policy (or one you cannot see), `408` when a message times out, `412` when a condition fails, and `413` when an entity is too large.
* `PatchThing` and `PatchFeatureProperties` send `application/merge-patch+json`. Every other write is a plain JSON `PUT` or `POST`.
* The `query` field on search events and `ids` on `ListThings` must be URL-encoded. `ListThings` needs at least one id; use `SearchThings` to list without ids.
* Ditto also has WebSocket, Server-Sent Events and its own MQTT and Kafka connections. For high-rate telemetry, a Ditto MQTT connection that subscribes to your Coreflux broker can be cheaper than one HTTP call per message. This template covers the HTTP API only and does not create connections.
* The public sandbox `https://ditto.eclipseprojects.io` listed in the Ditto OpenAPI spec refused every request from our test machine, so test against your own instance.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Azure Digital Twins](/latest/lot-language/routes/rest-api-apps/azure-digital-twins)
* [Mender](/latest/lot-language/routes/rest-api-apps/mender)


# Eclipse hawkBit (OTA)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/eclipse-hawkbit

Connect Coreflux LoT to Eclipse hawkBit: register devices, assign firmware, follow update actions and run staged OTA rollouts from MQTT

Technical Preview

## Overview

One client-mode connector, **EclipseHawkbit**, for the [Eclipse hawkBit](https://eclipse.dev/hawkbit/) Management API. hawkBit is an open-source server for rolling out software and firmware updates to devices. Each device is a **target** (identified by its controller id), each piece of firmware or software is a **software module**, modules are bundled into a **distribution set**, and a **rollout** deploys a set to a filtered group of targets in stages.

Use the connector to drive updates from the broker: register a device when it first appears on the UNS, push a firmware set to one machine, watch the action until it finishes, or start a staged rollout to a whole line and pause it if the error rate climbs.

| Event | Request | Notes |
| - | - | - |
| ListTargets | `GET /targets?{query}` | `query` = pre-encoded `q` (FIQL), `offset`, `limit`, `sort` |
| GetTarget | `GET /targets/{controller_id}` | |
| CreateTargets | `POST /targets` | JSON array of targets; returns `201` |
| UpdateTarget | `PUT /targets/{controller_id}` | Returns `200` with the updated target |
| DeleteTarget | `DELETE /targets/{controller_id}` | Returns `204` |
| GetTargetAttributes | `GET /targets/{controller_id}/attributes` | Attributes the device reported; `204` when none yet |
| CreateTargetMetadata | `POST /targets/{controller_id}/metadata` | JSON array of `{key, value}`; returns `201` |
| GetAssignedDistributionSet | `GET /targets/{controller_id}/assignedDS` | |
| GetInstalledDistributionSet | `GET /targets/{controller_id}/installedDS` | `204` until the device reports a finished install |
| AssignDistributionSet | `POST /targets/{controller_id}/assignedDS` | `[{"id": <set>, "type": "forced"}]`; returns `200` with the action ids |
| ListTargetActions | `GET /targets/{controller_id}/actions?{query}` | Deployment history of one device |
| GetTargetAction | `GET /targets/{controller_id}/actions/{action_id}` | |
| CancelTargetAction | `DELETE /targets/{controller_id}/actions/{action_id}` | Returns `204`; `405` when the action can no longer be cancelled |
| ListActions | `GET /actions?{query}` | All actions, filterable with FIQL |
| ListSoftwareModules | `GET /softwaremodules?{query}` | |
| CreateSoftwareModules | `POST /softwaremodules` | JSON array; `type` is a module type key such as `os` or `application` |
| ListDistributionSets | `GET /distributionsets?{query}` | |
| GetDistributionSet | `GET /distributionsets/{distribution_set_id}` | |
| CreateDistributionSets | `POST /distributionsets` | JSON array; `type` is a set type key such as `os` or `os_app` |
| AssignSoftwareModules | `POST /distributionsets/{distribution_set_id}/assignedSM` | `[{"id": <module>}]`; returns `204` |
| GetDistributionSetStatistics | `GET /distributionsets/{distribution_set_id}/statistics` | Action and rollout counts by status |
| ListRollouts | `GET /rollouts?{query}` | |
| GetRollout | `GET /rollouts/{rollout_id}` | |
| CreateRollout | `POST /rollouts` | Target filter, groups, success / error conditions; returns `201` |
| StartRollout | `POST /rollouts/{rollout_id}/start` | Returns `204` once the rollout is `ready` |
| PauseRollout | `POST /rollouts/{rollout_id}/pause` | Returns `204` |
| ResumeRollout | `POST /rollouts/{rollout_id}/resume` | Returns `204` |
| ListRolloutGroups | `GET /rollouts/{rollout_id}/deploygroups?{query}` | Deployment groups and their status |

Every request is relative to `/rest/v1`. Replies arrive on `<topic>/response`.

## Authentication

hawkBit is self-hosted or run by a vendor. Every event sends `Authorization: {authorization}`, so pass the whole header value:

* `"Basic <base64(user:password)>"` for a hawkBit user. The stock server ships with `admin` / `admin` on tenant `DEFAULT`; change it before the server is reachable from anywhere else.
* `"Bearer <token>"` when hawkBit is configured for OAuth 2.0 or OpenID Connect.

Keep it in a broker secret (suggested `HAWKBIT_AUTHORIZATION`) and map it in with `GET SECRET`. Wrong credentials return `401`; a user without the right permission gets `403`.

## Basic Syntax

Set `BASE_ADDRESS` to your hawkBit server, with no trailing slash. For a local server that is `http://localhost:8080`, with `USE_SSL "false"`.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EclipseHawkbit WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_HAWKBIT_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListTargets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetTarget
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateTargets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/targets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateTarget
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/update"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteTarget
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/delete"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetTargetAttributes
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-attributes/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-attributes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/attributes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateTargetMetadata
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-metadata/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-metadata/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/metadata"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetAssignedDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/assignedDS"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetInstalledDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-installed-ds/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-installed-ds/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/installedDS"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT AssignDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/assign"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/assign/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/assignedDS"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListTargetActions
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-action/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-action/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetTargetAction
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-action/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-action/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/actions/{value.json.action_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CancelTargetAction
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-action/cancel"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-action/cancel/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/actions/{value.json.action_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListActions
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/action/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/action/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListSoftwareModules
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/software-module/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/software-module/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/softwaremodules?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateSoftwareModules
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/software-module/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/software-module/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/softwaremodules"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDistributionSets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/distributionsets?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/distributionsets/{value.json.distribution_set_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateDistributionSets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/distributionsets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT AssignSoftwareModules
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-modules/assign"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-modules/assign/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/distributionsets/{value.json.distribution_set_id}/assignedSM"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDistributionSetStatistics
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-statistics/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-statistics/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/distributionsets/{value.json.distribution_set_id}/statistics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListRollouts
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/rollouts?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT StartRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/start"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/start"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT PauseRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/pause"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/pause/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/pause"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT ResumeRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/resume"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/resume/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/resume"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT ListRolloutGroups
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout-group/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout-group/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/deploygroups?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

## MQTT examples

Request bodies go under `body`, so control fields like `authorization` and `controller_id` are not sent to hawkBit. List events always need a `query` field; send `""` when you have no filter.

**Register a device**: publish to `cloud-iot/eclipse-hawkbit/target/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "body": [{"controllerId": "press-07", "name": "Press 07", "description": "porto/line1/press07"}]
}
```

hawkBit returns `201` with the new target, or `409` if the controller id already exists.

**Push firmware to one machine**: publish to `cloud-iot/eclipse-hawkbit/target-assigned-ds/assign`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "controller_id": "press-07",
  "body": [{"id": 12, "type": "forced"}]
}
```

The reply has `assigned`, `alreadyAssigned` and `assignedActions` with the new action id. Use `"type": "soft"` to let the device choose when to install.

**Follow the update**: publish `{"authorization": "...", "controller_id": "press-07", "query": "limit=5&sort=id%3ADESC"}` to `cloud-iot/eclipse-hawkbit/target-action/list`, or read one action on `cloud-iot/eclipse-hawkbit/target-action/get` with `action_id`. `cloud-iot/eclipse-hawkbit/target-installed-ds/get` returns `204` until the device reports a finished install.

**Find devices with failed updates**: publish to `cloud-iot/eclipse-hawkbit/target/list` with a pre-encoded [FIQL](https://eclipse.dev/hawkbit/apis/mgmt_api/) filter:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "query": "q=updateStatus%3D%3Derror&limit=50"
}
```

**Roll out to a whole line**: create the rollout on `cloud-iot/eclipse-hawkbit/rollout/create`, wait until `rollout/get` shows `"status": "ready"`, then publish `{"authorization": "...", "rollout_id": 3}` to `cloud-iot/eclipse-hawkbit/rollout/start`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "body": {
    "name": "fw-2.4-line-1",
    "distributionSetId": 12,
    "targetFilterQuery": "description==porto/line1/*",
    "amountGroups": 2,
    "successCondition": {"condition": "THRESHOLD", "expression": "80"},
    "successAction": {"action": "NEXTGROUP", "expression": ""},
    "errorCondition": {"condition": "THRESHOLD", "expression": "20"},
    "errorAction": {"action": "PAUSE", "expression": ""}
  }
}
```

`rollout/pause` and `rollout/resume` take the same `rollout_id`; `rollout-group/list` shows each group's progress.

## Helper actions

Register new machines as they appear and check rollout progress on a timer:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION HawkbitRegisterMachine
ON TOPIC "porto/line1/+/online" DO
    SET "auth" WITH GET SECRET "HAWKBIT_AUTHORIZATION"
    SET "machine" WITH TOPIC POSITION 3
    PUBLISH TOPIC "cloud-iot/eclipse-hawkbit/target/create" WITH { "authorization": {auth}, "body": [ { "controllerId": {machine}, "name": {machine}, "description": "porto/line1" } ] }

DEFINE ACTION HawkbitFailedUpdates
ON EVERY 15 MINUTES DO
    SET "auth" WITH GET SECRET "HAWKBIT_AUTHORIZATION"
    PUBLISH TOPIC "cloud-iot/eclipse-hawkbit/target/list" WITH { "authorization": {auth}, "query": "q=updateStatus%3D%3Derror&limit=50" }
```

A `409` on the create response just means the machine is already registered. Restrict who can publish to `cloud-iot/eclipse-hawkbit/#` with a rule: its payloads carry the credentials and can push firmware to devices.

## Notes

* Errors come back on the response topic: `400` for bad JSON or a bad FIQL filter, `401` for missing or wrong credentials, `403` for a missing permission, `404` for an unknown target, action, set or rollout, `405` when an action can no longer be cancelled, `409` for a duplicate id or a rollout in the wrong state, `423` when a distribution set is locked, and `429` when a quota is exceeded.
* `query` must be URL-encoded. hawkBit filters use FIQL, for example `controllerId==press*` or `updateStatus==error`.
* A distribution set is only deployable once it holds its required modules (`AssignSoftwareModules`). Uploading the firmware file itself is a multipart upload and is not covered by this template; do it in the hawkBit UI or with a script.
* Devices talk to hawkBit over its separate Direct Device Integration (DDI) API or the Device Management Federation (DMF) API. This template covers the Management API only.
* Rollouts are created asynchronously: start one only after `GetRollout` reports `ready`, or hawkBit answers `409`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Mender](/latest/lot-language/routes/rest-api-apps/mender)
* [balena](/latest/lot-language/routes/rest-api-apps/balena)
* [Eclipse Ditto](/latest/lot-language/routes/rest-api-apps/eclipse-ditto)


# Elasticsearch and Elastic Cloud
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/elasticsearch-and-elastic-cloud

Connect Coreflux LoT to Elasticsearch or Elastic Cloud: index MQTT telemetry, bulk-load batches into data streams and query with search, count and ES|QL

Technical Preview

## Overview

A client-mode connector for the [Elasticsearch REST API](https://www.elastic.co/docs/api/doc/elasticsearch) that writes MQTT data into Elasticsearch and reads it back:

| Catalog connector event | Endpoint | Notes |
| - | - | - |
| Index a document | `POST /{index}/_doc` | [Index API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-index). Auto-generated `_id`, returns `201` with `"result":"created"`. Works for data streams too. |
| Bulk-load a batch | `POST /_bulk` | [Bulk API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk). NDJSON body (`application/x-ndjson`) of action + source line pairs. Returns `200` even when some items fail, so check `errors`. |
| Search | `POST /{index}/_search` | [Search API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-search) with Query DSL, sort, aggregations. |
| Put / get / update by id | `PUT /{index}/_doc/{id}`, `GET /{index}/_doc/{id}`, `POST /{index}/_update/{id}` | Latest asset state keyed by a stable id (for example `pump-7`). Not for data streams. |
| Count | `POST /{index}/_count` | Query DSL count. |
| ES\|QL | `POST /_query` | [ES\|QL query](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-query), for example `FROM metrics-coreflux-* \| STATS AVG(temperature) BY site`. |
| Refresh | `POST /{index}/_refresh` | Make recent writes searchable now (normally about 1 s). Use sparingly. |
| Time-series setup | `PUT /_index_template/{name}`, `GET /_data_stream/{name}` | Create an index template with `"data_stream": {}` so writes to `metrics-…` create a [data stream](https://www.elastic.co/docs/manage-data/data-store/data-streams). |
| Smoke | `GET /`, `GET /_cluster/health` | Cluster info and health. |

Topics use `data/elasticsearch/<object>/<verb>`, and replies go to `<topic>/response`. `BASE_ADDRESS` has no trailing slash; one connector instance talks to one cluster or project:

| Deployment | `BASE_ADDRESS` |
| - | - |
| Elastic Cloud Hosted | `https://<deployment>.es.<region>.<provider>.elastic-cloud.com` (port 443) |
| Elastic Cloud Serverless | `https://<project>.es.<region>.<provider>.elastic.cloud` (port 443) |
| Self-managed | `https://<host>:9200` |

Copy the Elasticsearch endpoint from the Elastic Cloud console (**Manage** / **Connection details**), not the Kibana URL.

## Auth

Every event sends `Authorization: ApiKey …`. The template reads the key from the MQTT payload field `api_key`. Keep it in a Hub secret such as `GET SECRET "ELASTICSEARCH_API_KEY"` and never commit it.

* **API key (recommended, required on Serverless):** create one in Kibana (**Stack Management → API keys**) or with `POST /_security/api_key`, and use the `encoded` value, which is base64 of `id:api_key`. See [Elasticsearch API keys](https://www.elastic.co/docs/deploy-manage/api-keys/elasticsearch-api-keys).
* **Scope the key** to what the connector writes. A key like the one used in testing:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "name": "coreflux-writer",
  "role_descriptors": {
    "coreflux_writer": {
      "cluster": ["monitor", "manage_index_templates"],
      "indices": [{
        "names": ["factory-*", "metrics-coreflux-*"],
        "privileges": ["create_doc", "index", "read", "view_index_metadata", "create_index", "auto_configure", "maintenance"]
      }]
    }
  }
}
```

Drop `manage_index_templates` once the template exists, and drop `index` if the connector only appends (`create_doc`).

* **Basic auth (alternative, self-managed and Hosted):** remove the `Authorization` header lines and add `WITH USERNAME "coreflux_writer"` and `WITH PASSWORD GET SECRET "ELASTICSEARCH_PASSWORD"` to `REST_API_CONFIG`. Don't use the `elastic` superuser.

A `401` `security_exception` means the key is missing, wrong or expired. A `403` naming an action such as `indices:admin/auto_create` means the key is valid but lacks that privilege on that index.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ElasticsearchRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DEPLOYMENT.es.YOUR_REGION.aws.elastic-cloud.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth (prefer Hub secrets / GET SECRET "ELASTICSEARCH_API_KEY"): api_key on each MQTT payload → ApiKey header below.
    ADD EVENT GetClusterInfo
        WITH SOURCE_TOPIC "data/elasticsearch/cluster/info"
        WITH DESTINATION_TOPIC "data/elasticsearch/cluster/info/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
    ADD EVENT GetClusterHealth
        WITH SOURCE_TOPIC "data/elasticsearch/cluster/health"
        WITH DESTINATION_TOPIC "data/elasticsearch/cluster/health/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/_cluster/health"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
    ADD EVENT IndexDocument
        WITH SOURCE_TOPIC "data/elasticsearch/document/index"
        WITH DESTINATION_TOPIC "data/elasticsearch/document/index/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.index}/_doc"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT PutDocument
        WITH SOURCE_TOPIC "data/elasticsearch/document/put"
        WITH DESTINATION_TOPIC "data/elasticsearch/document/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.index}/_doc/{value.json.id}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDocument
        WITH SOURCE_TOPIC "data/elasticsearch/document/get"
        WITH DESTINATION_TOPIC "data/elasticsearch/document/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.index}/_doc/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
    ADD EVENT UpdateDocument
        WITH SOURCE_TOPIC "data/elasticsearch/document/update"
        WITH DESTINATION_TOPIC "data/elasticsearch/document/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.index}/_update/{value.json.id}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT BulkIndex
        WITH SOURCE_TOPIC "data/elasticsearch/bulk"
        WITH DESTINATION_TOPIC "data/elasticsearch/bulk/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/_bulk"
        WITH HEADERS
            ADD "Content-Type" "application/x-ndjson"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.content}"
    ADD EVENT Search
        WITH SOURCE_TOPIC "data/elasticsearch/search"
        WITH DESTINATION_TOPIC "data/elasticsearch/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.index}/_search"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT CountDocuments
        WITH SOURCE_TOPIC "data/elasticsearch/count"
        WITH DESTINATION_TOPIC "data/elasticsearch/count/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.index}/_count"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT EsqlQuery
        WITH SOURCE_TOPIC "data/elasticsearch/esql/query"
        WITH DESTINATION_TOPIC "data/elasticsearch/esql/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/_query"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT RefreshIndex
        WITH SOURCE_TOPIC "data/elasticsearch/index/refresh"
        WITH DESTINATION_TOPIC "data/elasticsearch/index/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.index}/_refresh"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
    ADD EVENT PutIndexTemplate
        WITH SOURCE_TOPIC "data/elasticsearch/index-template/put"
        WITH DESTINATION_TOPIC "data/elasticsearch/index-template/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/_index_template/{value.json.name}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDataStream
        WITH SOURCE_TOPIC "data/elasticsearch/data-stream/get"
        WITH DESTINATION_TOPIC "data/elasticsearch/data-stream/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/_data_stream/{value.json.name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "ApiKey {value.json.api_key}"
```

> [!NOTE]
>
> JSON bodies come from the payload field `body`, so control fields (`api_key`, `index`, `id`, `name`) are not sent to Elasticsearch. `BulkIndex` sends the payload field `content` as the raw NDJSON body.

## Example MQTT payloads

Index one reading into a data stream (`data/elasticsearch/document/index`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<from GET SECRET ELASTICSEARCH_API_KEY>",
  "index": "metrics-coreflux-factory",
  "body": { "@timestamp": "2026-10-04T22:50:00.000Z", "site": "porto", "line": "L1", "temperature": 22.0 }
}
```

Bulk-load a batch (`data/elasticsearch/bulk`). Every line ends in `\n`, including the last one. Data streams only accept `create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<…>",
  "content": "{\"create\":{\"_index\":\"metrics-coreflux-factory\"}}\n{\"@timestamp\":\"2026-10-04T22:50:00.000Z\",\"site\":\"porto\",\"temperature\":21.5}\n{\"index\":{\"_index\":\"factory-assets\",\"_id\":\"pump-7\"}}\n{\"asset\":\"pump-7\",\"state\":\"running\",\"rpm\":1450}\n"
}
```

Upsert the latest state of an asset (`data/elasticsearch/document/put`, then `data/elasticsearch/document/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "api_key": "<…>", "index": "factory-assets", "id": "press-3", "body": { "asset": "press-3", "state": "idle", "rpm": 0 } }
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "api_key": "<…>", "index": "factory-assets", "id": "press-3", "body": { "doc": { "state": "running", "rpm": 900 }, "doc_as_upsert": true } }
```

Search the latest readings for a site (`data/elasticsearch/search`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<…>",
  "index": "metrics-coreflux-factory",
  "body": { "size": 5, "query": { "term": { "site": "porto" } }, "sort": [ { "@timestamp": "desc" } ] }
}
```

Average temperature by site with ES|QL (`data/elasticsearch/esql/query`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "api_key": "<…>", "body": { "query": "FROM metrics-coreflux-factory | STATS avg_t = AVG(temperature) BY site | SORT site" } }
```

Create the time-series index template once (`data/elasticsearch/index-template/put`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<…>",
  "name": "coreflux-factory-metrics",
  "body": {
    "index_patterns": ["metrics-coreflux-*"],
    "data_stream": {},
    "priority": 500,
    "template": {
      "mappings": { "properties": {
        "@timestamp": { "type": "date" }, "site": { "type": "keyword" },
        "line": { "type": "keyword" }, "temperature": { "type": "float" }
      } }
    }
  }
}
```

Smoke (`data/elasticsearch/cluster/info`): `{ "api_key": "<…>" }`.

> [!TIP]
>
> Batch high-rate telemetry with `_bulk` (a few hundred to a few thousand docs, or about 5 to 15 MB per request) instead of one `_doc` call per sample. Elastic recommends this for indexing throughput.

## Gotchas

* **`_bulk` returns `200` even when items fail.** Check `"errors": true` and each `items[].<action>.status` in the response. A body that doesn't end in a newline is rejected with `400` `The bulk request must be terminated by a newline [\n]`.
* **Data streams are append-only.** Each document needs `@timestamp`. In `_bulk`, use `create`, not `index`. `PUT /{ds}/_doc/{id}` and `_update` are rejected on data streams; use a regular index (such as `factory-assets`) for latest-state documents.
* **Index names** must be lowercase and can't start with `_`, `-` or `+`. Several indices can be comma-separated in `Search`, `CountDocuments` and `RefreshIndex` (for example `factory-telemetry,metrics-coreflux-*`).
* **Near real-time:** new documents become searchable after the next refresh (about 1 s by default; on Serverless refreshes are managed). Call `RefreshIndex` only in tests or after a batch, never per document.
* **Self-managed TLS:** Elasticsearch 8.x and 9.x turn on TLS with a self-signed CA at first start. The broker host must trust that CA (or use a publicly trusted certificate) for `USE_SSL "true"` to work.
* **Serverless** doesn't expose every API. Per Elastic's Serverless OpenAPI, `GET /_cluster/health` is not available there (use `GET /` as the connectivity check instead), and some index settings such as `number_of_replicas` are managed for you. Indexing, `_bulk`, search, count, `_update`, `_refresh`, ES|QL, index templates and data streams are all available.
* Deletes (documents, indices, data streams, templates), `_delete_by_query`, `_update_by_query`, security and API key management, cluster settings, snapshots, ILM and Kibana APIs are left out on purpose.

## Rate limits

Elasticsearch has no fixed request quota. When the write thread pool queue is full, it returns `429` `es_rejected_execution_exception`, either for the whole request or for individual `_bulk` items. Back off and retry only the rejected items. Elastic Cloud Serverless also applies per-project ingest limits. See [Tune for indexing speed](https://www.elastic.co/docs/deploy-manage/production-guidance/optimize-performance/indexing-speed).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [ClickHouse](/latest/lot-language/routes/rest-api-apps/clickhouse)
* [InfluxDB](/latest/lot-language/routes/rest-api-apps/influxdb)
* [Splunk Enterprise and Cloud](/latest/lot-language/routes/rest-api-apps/splunk-enterprise-and-cloud)


# Electricity Maps
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/electricity-maps

Connect Coreflux LoT to Electricity Maps API v4: grid carbon intensity, power mix, prices and forecasts per zone for carbon-aware scheduling

Technical Preview

> [!WARNING]
>
> **API key and plan.** Every data endpoint needs an Electricity Maps API key in the `auth-token` header. Which signals, zones and granularities a key can reach depends on its plan (14-day trial or paid). Call `ListZones` with your key to see what each zone allows.

## Overview

[Electricity Maps](https://www.electricitymaps.com) publishes hourly and sub-hourly data about the electricity on the grid in about 350 zones worldwide: how carbon-intensive it is, which sources produce it, what it costs on the day-ahead market, and forecasts of all of these. The **API v4** (`https://api.electricitymaps.com/v4`) is documented at [app.electricitymaps.com/docs](https://app.electricitymaps.com/docs).

The **ElectricityMapsApi** connector maps 35 MQTT topics onto that API, all read-only `GET` calls. Typical uses are carbon-aware scheduling (shift flexible loads such as compressors, chillers, EV charging or batch processes into low-carbon or low-price hours), Scope 2 reporting per production line, and showing grid carbon intensity on a plant dashboard next to energy meters. Each event publishes the API reply on `<topic>/response`.

| Event | Topic | Request | Use |
| - | - | - | - |
| `ListZones` | `energy/electricitymaps/zone/list` | `GET /v4/zones` | All commercially available zones (zoneKey, zoneName, countryCode, tier); with a token also the endpoints each zone allows. Works with token "" |
| `GetZone` | `energy/electricitymaps/zone/get` | `GET /v4/zone?{query}` | Metadata for one zone, or resolve lat=\&lon= to a zone key; query zone=PT or lat=41.15\&lon=-8.61. Works with token "" |
| `GetUpdatedSince` | `energy/electricitymaps/updated-since/get` | `GET /v4/updated-since?{query}` | Data points of a zone changed since a datetime (to refresh stored history); query zone=\&since=\&start=\&end= (required) |
| `GetCarbonIntensityLatest` | `energy/electricitymaps/carbon-intensity/latest/get` | `GET /v4/carbon-intensity/latest?{query}` | Grid carbon intensity (gCO2eq/kWh), lifecycle or direct, flow-traced by default: latest value |
| `GetCarbonIntensityForecast` | `energy/electricitymaps/carbon-intensity/forecast/get` | `GET /v4/carbon-intensity/forecast?{query}` | Grid carbon intensity (gCO2eq/kWh), lifecycle or direct, flow-traced by default: forecast; query horizonHours= |
| `GetCarbonIntensityHistory` | `energy/electricitymaps/carbon-intensity/history/get` | `GET /v4/carbon-intensity/history?{query}` | Grid carbon intensity (gCO2eq/kWh), lifecycle or direct, flow-traced by default: last 24 h |
| `GetCarbonIntensityPast` | `energy/electricitymaps/carbon-intensity/past/get` | `GET /v4/carbon-intensity/past?{query}` | Grid carbon intensity (gCO2eq/kWh), lifecycle or direct, flow-traced by default: one past point; query datetime= (required) |
| `GetCarbonIntensityPastRange` | `energy/electricitymaps/carbon-intensity/past-range/get` | `GET /v4/carbon-intensity/past-range?{query}` | Grid carbon intensity (gCO2eq/kWh), lifecycle or direct, flow-traced by default: past range; query start=\&end= (required) |
| `GetElectricityMixLatest` | `energy/electricitymaps/electricity-mix/latest/get` | `GET /v4/electricity-mix/latest?{query}` | Generation / consumption mix per source in MW (v4 replacement of power-breakdown): latest value |
| `GetElectricityMixForecast` | `energy/electricitymaps/electricity-mix/forecast/get` | `GET /v4/electricity-mix/forecast?{query}` | Generation / consumption mix per source in MW (v4 replacement of power-breakdown): forecast; query horizonHours= |
| `GetElectricityMixHistory` | `energy/electricitymaps/electricity-mix/history/get` | `GET /v4/electricity-mix/history?{query}` | Generation / consumption mix per source in MW (v4 replacement of power-breakdown): last 24 h |
| `GetElectricityMixPast` | `energy/electricitymaps/electricity-mix/past/get` | `GET /v4/electricity-mix/past?{query}` | Generation / consumption mix per source in MW (v4 replacement of power-breakdown): one past point; query datetime= (required) |
| `GetElectricityMixPastRange` | `energy/electricitymaps/electricity-mix/past-range/get` | `GET /v4/electricity-mix/past-range?{query}` | Generation / consumption mix per source in MW (v4 replacement of power-breakdown): past range; query start=\&end= (required) |
| `GetDayAheadPriceLatest` | `energy/electricitymaps/price-day-ahead/latest/get` | `GET /v4/price-day-ahead/latest?{query}` | Day-ahead wholesale price (EU), EUR/MWh: latest value |
| `GetDayAheadPriceForecast` | `energy/electricitymaps/price-day-ahead/forecast/get` | `GET /v4/price-day-ahead/forecast?{query}` | Day-ahead wholesale price (EU), EUR/MWh: forecast; query horizonHours= |
| `GetDayAheadPriceActual` | `energy/electricitymaps/price-day-ahead/actual/get` | `GET /v4/price-day-ahead/actual?{query}` | Day-ahead wholesale price (EU), EUR/MWh: settled / published prices; query start=\&end= (required) |
| `GetDayAheadPriceCombined` | `energy/electricitymaps/price-day-ahead/combined/get` | `GET /v4/price-day-ahead/combined?{query}` | Day-ahead wholesale price (EU), EUR/MWh: actuals + forecast in one reply |
| `GetDayAheadPriceHistory` | `energy/electricitymaps/price-day-ahead/history/get` | `GET /v4/price-day-ahead/history?{query}` | Day-ahead wholesale price (EU), EUR/MWh: last 24 h |
| `GetRenewableEnergyLatest` | `energy/electricitymaps/renewable-energy/latest/get` | `GET /v4/renewable-energy/latest?{query}` | Renewable share of electricity (%): latest value |
| `GetRenewableEnergyForecast` | `energy/electricitymaps/renewable-energy/forecast/get` | `GET /v4/renewable-energy/forecast?{query}` | Renewable share of electricity (%): forecast; query horizonHours= |
| `GetCarbonFreeEnergyLatest` | `energy/electricitymaps/carbon-free-energy/latest/get` | `GET /v4/carbon-free-energy/latest?{query}` | Carbon-free share (renewables + nuclear, %): latest value |
| `GetCarbonFreeEnergyForecast` | `energy/electricitymaps/carbon-free-energy/forecast/get` | `GET /v4/carbon-free-energy/forecast?{query}` | Carbon-free share (renewables + nuclear, %): forecast; query horizonHours= |
| `GetTotalLoadLatest` | `energy/electricitymaps/total-load/latest/get` | `GET /v4/total-load/latest?{query}` | Total electricity load (MW): latest value |
| `GetTotalLoadForecast` | `energy/electricitymaps/total-load/forecast/get` | `GET /v4/total-load/forecast?{query}` | Total electricity load (MW): forecast; query horizonHours= |
| `GetNetLoadLatest` | `energy/electricitymaps/net-load/latest/get` | `GET /v4/net-load/latest?{query}` | Net load = load minus wind and solar (MW): latest value |
| `GetNetLoadForecast` | `energy/electricitymaps/net-load/forecast/get` | `GET /v4/net-load/forecast?{query}` | Net load = load minus wind and solar (MW): forecast; query horizonHours= |
| `GetElectricityFlowsLatest` | `energy/electricitymaps/electricity-flows/latest/get` | `GET /v4/electricity-flows/latest?{query}` | Cross-border import / export flows per neighbour zone (MW): latest value |
| `GetCarbonIntensityLevelLatest` | `energy/electricitymaps/carbon-intensity-level/latest/get` | `GET /v4/carbon-intensity-level/latest?{query}` | Traffic-light level (high / moderate / low) of carbon intensity vs the zone's recent history: latest value |
| `GetCarbonIntensityLevelForecast` | `energy/electricitymaps/carbon-intensity-level/forecast/get` | `GET /v4/carbon-intensity-level/forecast?{query}` | Traffic-light level (high / moderate / low) of carbon intensity vs the zone's recent history: forecast; query horizonHours= |
| `GetRenewablePercentageLevelLatest` | `energy/electricitymaps/renewable-percentage-level/latest/get` | `GET /v4/renewable-percentage-level/latest?{query}` | Traffic-light level of the renewable share: latest value |
| `GetCarbonIntensityFossilOnlyLatest` | `energy/electricitymaps/carbon-intensity-fossil-only/latest/get` | `GET /v4/carbon-intensity-fossil-only/latest?{query}` | Carbon intensity of the fossil part of the mix only: latest value |
| `GetElectricitySourceLatest` | `energy/electricitymaps/electricity-source/latest/get` | `GET /v4/electricity-source/{source_type}/latest?{query}` | One generation source (source\_type = solar, wind, nuclear, ...), MW: latest value |
| `GetElectricitySourceForecast` | `energy/electricitymaps/electricity-source/forecast/get` | `GET /v4/electricity-source/{source_type}/forecast?{query}` | One generation source (source\_type = solar, wind, ...), MW: forecast; query horizonHours= |
| `GetLmpDayAheadLatest` | `energy/electricitymaps/lmp-day-ahead/latest/get` | `GET /v4/locational-marginal-price-day-ahead/latest?{query}` | US day-ahead locational marginal price for a pricing node; query node= (required) |
| `GetSignal` | `energy/electricitymaps/signal/get` | `GET /v4/{signal}/{variant}?{query}` | Any other documented v4 data path: signal = total-reported-load, variant = latest (or past, past-range, ...) |

## Authentication

Every request sends `auth-token: {value.json.token}`. Keep the API key in a broker secret, for example `ELECTRICITY_MAPS_TOKEN`, and map it into the payload with `GET SECRET`. `ListZones` and `GetZone` answer without a key, so send `token = ""` for them. A wrong key on `ListZones` returns `401 Token is invalid`; the data endpoints return `401 Invalid auth-token` without a valid key.

## Choosing a zone

Pass `zone=PT` (zone keys come from `ListZones`) or `lat=` and `lon=` in `query`. `GetZone` turns coordinates into a zone key once, for example `lat=41.15&lon=-8.61` returns `PT` for Porto. Without a zone or coordinates the API falls back to the location of the caller's IP address, which for a broker in a data center is usually the wrong grid. Add `disableCallerLookup=true` to turn that fallback off.

## Request payload

Every event reads its values from the JSON payload published on the request topic:

| Field | Used by | Example |
| - | - | - |
| `token` | all events | `(GET SECRET "ELECTRICITY_MAPS_TOKEN")`, or `""` for `ListZones` / `GetZone` |
| `query` | all events except `ListZones` | `zone=PT&temporalGranularity=15_minutes` |
| `source_type` | `GetElectricitySourceLatest`, `GetElectricitySourceForecast` | `solar`, `wind`, `nuclear`, `hydro`, `gas`, `coal`, `biomass`, `geothermal`, `oil`, `unknown`, `hydro-discharge`, `battery-discharge` |
| `signal`, `variant` | `GetSignal` | `total-reported-load` and `latest` |

Common query parameters are `temporalGranularity` (`5_minutes`, `15_minutes` or `hourly`), `emissionFactorType` (`lifecycle` or `direct`), `flowTraced` (`true` for consumption-based values, `false` for the zone's own production), `disableEstimations`, `horizonHours` for forecasts, `datetime` for a past point and `start` plus `end` for a past range (ISO 8601, UTC). Leave `query` as `""` when an event needs no parameters, which leaves a harmless trailing `?` on the URL.

## Connector template

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ElectricityMapsApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.electricitymaps.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListZones
        WITH SOURCE_TOPIC "energy/electricitymaps/zone/list"
        WITH DESTINATION_TOPIC "energy/electricitymaps/zone/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v4/zones"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "auth-token" "{value.json.token}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetZone
        WITH SOURCE_TOPIC "energy/electricitymaps/zone/get"
        WITH DESTINATION_TOPIC "energy/electricitymaps/zone/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v4/zone?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "auth-token" "{value.json.token}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # ... 33 more events in the package file (ElectricityMapsRestApi.lot)
```

The complete connector with all 35 events is in the package file `ElectricityMapsRestApi.lot`.

## Example actions

These actions poll Portugal (`PT`) at about 6 calls per hour. Replace the zone with your own.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the ElectricityMapsApi route (docs page). Not part of the route template.
# Secret: ELECTRICITY_MAPS_TOKEN = the API key from the Electricity Maps portal (sent as the auth-token header).
# Zone PT = Portugal (mainland grid, Tier A). Replace it with your own zone key (ListZones / GetZone).
# Inline JSON object literals are not supported when publishing to a topic, so the request payload is a COLLAPSED
#   model sent with PUBLISH MODEL.
# Budget: about 4 + 1 + 1 + 0.04 = 6 calls per hour. Hourly data changes once an hour; 15-minute polling only
#   helps with temporalGranularity=15_minutes or 5_minutes on plans that include them.

DEFINE MODEL ElectricityMapsRequest COLLAPSED
    ADD STRING "token"
    ADD STRING "query"

DEFINE ACTION GridCarbonIntensityEvery15Minutes
ON EVERY 15 MINUTES DO
    PUBLISH MODEL ElectricityMapsRequest TO "energy/electricitymaps/carbon-intensity/latest/get" WITH
        token = (GET SECRET "ELECTRICITY_MAPS_TOKEN")
        query = "zone=PT&disableCallerLookup=true"

DEFINE ACTION GridMixHourly
ON EVERY 1 HOUR DO
    PUBLISH MODEL ElectricityMapsRequest TO "energy/electricitymaps/electricity-mix/latest/get" WITH
        token = (GET SECRET "ELECTRICITY_MAPS_TOKEN")
        query = "zone=PT&disableCallerLookup=true"

DEFINE ACTION GridCarbonForecastHourly
ON EVERY 1 HOUR DO
    PUBLISH MODEL ElectricityMapsRequest TO "energy/electricitymaps/carbon-intensity/forecast/get" WITH
        token = (GET SECRET "ELECTRICITY_MAPS_TOKEN")
        query = "zone=PT&horizonHours=24&disableCallerLookup=true"

DEFINE ACTION DayAheadPriceForecastDaily
ON EVERY 1 DAY DO
    PUBLISH MODEL ElectricityMapsRequest TO "energy/electricitymaps/price-day-ahead/forecast/get" WITH
        token = (GET SECRET "ELECTRICITY_MAPS_TOKEN")
        query = "zone=PT&horizonHours=48&disableCallerLookup=true"
```

## Testing

1. Store your key: add the secret `ELECTRICITY_MAPS_TOKEN` on the broker.
2. Deploy `ElectricityMapsRestApi.lot`.
3. Publish `{"token": "", "query": "lat=41.15&lon=-8.61"}` to `energy/electricitymaps/zone/get` and check that `energy/electricitymaps/zone/get/response` returns `"zoneKey":"PT"`.
4. Publish `{"token": "<your key>", "query": "zone=PT"}` to `energy/electricitymaps/carbon-intensity/latest/get` and check that the response carries `carbonIntensity` and `datetime`.

## Notes and limits

* Version: this connector uses v4. The v3 paths still answer, but in v4 the old `power-breakdown` endpoints are called `electricity-mix`.
* Hourly data changes once an hour. Polling faster only helps with `5_minutes` or `15_minutes` granularity on plans that include it.
* `GetLmpDayAheadLatest` is for US pricing nodes (`node=` is required); `price-day-ahead` covers European zones.
* Marginal emission signals were discontinued by Electricity Maps and are not part of this connector.


# Enphase
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/enphase

Client-mode REST API connector for a curated Enphase v4 slice: list systems and read a system summary

Technical Preview

# Enphase

Client-mode REST API connector for a curated Enphase v4 slice: list systems and read a system summary.

* Hub category: **Energy**.
* Base: `https://api.enphaseenergy.com`

## Template reference

Generated from the shipped broker template `enphase` (`-connectorCode ENPHASE`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Enphase connector | no |
| `BaseUrl` | string | Enphase base URL without trailing slash (e.g. [https://api.enphaseenergy.com](https://api.enphaseenergy.com)) | yes |

`BASE_ADDRESS` default: `https://api.enphaseenergy.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listsystems` | GET | `/api/v4/systems?key={value.json.api_key}` | `energy/enphase/systems/list` | `energy/enphase/systems/list/response` | `api_key`, `api_token` |
| `Getsummary` | GET | `/api/v4/systems/{value.json.system_id}/summary?key={value.json.api_key}` | `energy/enphase/systems/summary` | `energy/enphase/systems/summary/response` | `api_key`, `api_token`, `system_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode ENPHASE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EnphaseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.enphaseenergy.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listsystems
        WITH SOURCE_TOPIC "energy/enphase/systems/list"
        WITH DESTINATION_TOPIC "energy/enphase/systems/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getsummary
        WITH SOURCE_TOPIC "energy/enphase/systems/summary"
        WITH DESTINATION_TOPIC "energy/enphase/systems/summary/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.system_id}/summary?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listsystems` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/enphase/systems/list/response' &
mosquitto_pub -t 'energy/enphase/systems/list' -m '{"api_key": "<api_key>", "api_token": "<api_token>"}'
```


# Enphase Enlighten API v4
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/enphase-enlighten-api-v4

Connect Coreflux LoT to the Enphase Monitoring API v4: publish PV production, consumption, battery and EV charger data on MQTT and manage battery settings

Technical Preview

## Overview

Enphase IQ microinverters, IQ Batteries, meters and EV chargers report to the Enlighten cloud. The **Enphase Monitoring API v4** (`https://api.enphaseenergy.com/api/v4`) gives read (and limited write) access to that data. It is documented on the [Enphase developer portal](https://developer-v4.enphase.com/docs) with an official Swagger 2.0 export for the Monitoring API.

The **EnphaseEnlightenApi** connector maps 28 MQTT topics onto that API: 22 Watt (free), 2 Kilowatt and 4 Megawatt events. Typical uses are putting site PV production, consumption and battery power on the broker next to plant data, turning Enphase alarms into broker alarms, and (on Megawatt) reading or changing battery mode. Each event publishes the Enphase reply on `<topic>/response`.

| Event | Topic | Request | Plan | Use |
| - | - | - | - | - |
| `ListSystems` | `energy/enphase/system/list` | `GET /api/v4/systems?key={api_key}&{query}` | Watt | Systems the token can read, e.g. query page=1\&size=100\&sort\_by=id |
| `SearchSystems` | `energy/enphase/system/search` | `POST /api/v4/systems/search?key={api_key}&{query}` | Watt | Filter systems by ids, name, reference or status; body \{"system":\{"statuses":\["comm","micro"]}}, query page=\&size=\&live\_stream= |
| `GetSystem` | `energy/enphase/system/get` | `GET /api/v4/systems/{id}?key={api_key}` | Watt | System details: name, timezone, address, connection type, status, last report |
| `GetSystemSummary` | `energy/enphase/system-summary/get` | `GET /api/v4/systems/{id}/summary?key={api_key}&{query}` | Watt | Current power (W), energy today and lifetime (Wh), size, modules, status; query summary\_date=YYYY-MM-DD or "" |
| `ListSystemDevices` | `energy/enphase/device/list` | `GET /api/v4/systems/{id}/devices?key={api_key}` | Watt | Micros, meters, gateways (Envoy), batteries (Encharge), Enpower, EVSE with serials and status |
| `RetrieveSystemId` | `energy/enphase/system-id/get` | `GET /api/v4/systems/retrieve_system_id?key={api_key}&{query}` | Watt | System id for an IQ Gateway (Envoy) serial; query serial\_num=\<envoy serial> |
| `GetLatestTelemetry` | `energy/enphase/latest-telemetry/get` | `GET /api/v4/systems/{id}/latest_telemetry?key={api_key}` | Watt | Last reported PV, consumption, battery and EVSE power (W) plus battery / heat pump / EVSE operating mode |
| `GetProductionMeterReadings` | `energy/enphase/production-meter-readings/get` | `GET /api/v4/systems/{id}/production_meter_readings?key={api_key}&{query}` | Watt | Last odometer reading of each revenue-grade production meter; query end\_at=\<epoch>\&include\_channels=true or "" |
| `GetEnergyLifetime` | `energy/enphase/energy-lifetime/get` | `GET /api/v4/systems/{id}/energy_lifetime?key={api_key}&{query}` | Watt | Daily production series (Wh); query start\_date=YYYY-MM-DD\&end\_date=YYYY-MM-DD\&production=all |
| `GetRgmStats` | `energy/enphase/rgm-stats/get` | `GET /api/v4/systems/{id}/rgm_stats?key={api_key}&{query}` | Watt | 15-minute revenue-grade meter intervals (max 1 week); query start\_at=\<epoch>\&end\_at=\<epoch> |
| `GetProductionMicroTelemetry` | `energy/enphase/production-micro-telemetry/get` | `GET /api/v4/systems/{id}/telemetry/production_micro?key={api_key}&{query}` | Watt | Production of all microinverters; query start\_at=\<epoch>\&granularity=5mins/15mins/day/week |
| `GetProductionMeterTelemetry` | `energy/enphase/production-meter-telemetry/get` | `GET /api/v4/systems/{id}/telemetry/production_meter?key={api_key}&{query}` | Watt | Production meter intervals; query start\_at=\<epoch>\&granularity=... |
| `GetConsumptionMeterTelemetry` | `energy/enphase/consumption-meter-telemetry/get` | `GET /api/v4/systems/{id}/telemetry/consumption_meter?key={api_key}&{query}` | Watt | Consumption meter intervals; query start\_at=\<epoch>\&granularity=... |
| `GetBatteryTelemetry` | `energy/enphase/battery-telemetry/get` | `GET /api/v4/systems/{id}/telemetry/battery?key={api_key}&{query}` | Watt | Battery charge / discharge and state of charge intervals; query start\_at=\<epoch>\&granularity=... |
| `GetEnergyImportTelemetry` | `energy/enphase/energy-import-telemetry/get` | `GET /api/v4/systems/{id}/energy_import_telemetry?key={api_key}&{query}` | Watt | Energy imported from the grid per interval; query start\_at=\<epoch>\&granularity=... |
| `GetEnergyExportTelemetry` | `energy/enphase/energy-export-telemetry/get` | `GET /api/v4/systems/{id}/energy_export_telemetry?key={api_key}&{query}` | Watt | Energy exported to the grid per interval; query start\_at=\<epoch>\&granularity=... |
| `GetConsumptionLifetime` | `energy/enphase/consumption-lifetime/get` | `GET /api/v4/systems/{id}/consumption_lifetime?key={api_key}&{query}` | Watt | Daily consumption series (Wh); query start\_date=\&end\_date= |
| `ListOpenAlarms` | `energy/enphase/open-alarm/list` | `GET /api/v4/systems/{id}/open_alarms?key={api_key}` | Watt | All open alarms of a site |
| `ListAlarms` | `energy/enphase/alarm/list` | `GET /api/v4/systems/{id}/alarms?key={api_key}&{query}` | Watt | Active and closed alarms; query start\_time=\<epoch> (required, max 7-day window)\&end\_time=\&cleared=true/false |
| `ListOpenEvents` | `energy/enphase/open-event/list` | `GET /api/v4/systems/{id}/open_events?key={api_key}` | Watt | All open events of a site |
| `ListEvents` | `energy/enphase/event/list` | `GET /api/v4/systems/{id}/events?key={api_key}&{query}` | Watt | Active and closed events; query start\_time=\<epoch> (required, max 1 week)\&end\_time= |
| `ListEventTypes` | `energy/enphase/event-type/list` | `GET /api/v4/systems/event_types?key={api_key}&{query}` | Watt | Static event type catalog with description and recommended action; query event\_type\_id= or "" |
| `GetMicroTelemetry` | `energy/enphase/micro-telemetry/get` | `GET /api/v4/systems/{id}/devices/micros/{serial}/telemetry?key={api_key}&{query}` | Kilowatt | Kilowatt+: one microinverter's telemetry; query start\_at=\&granularity= |
| `GetLiveData` | `energy/enphase/live-data/get` | `GET /api/v4/systems/{id}/live_data?key={api_key}` | Kilowatt | Kilowatt+ Streaming API: on-demand real-time PV, grid, load, battery, generator and EVSE power (USD 0.10 per hit; default 30 s stream) |
| `GetBatterySettings` | `energy/enphase/battery-settings/get` | `GET /api/v4/systems/config/{id}/battery_settings?key={api_key}` | Megawatt | Megawatt: battery mode, reserve SoC, energy independence, charge from grid |
| `UpdateBatterySettings` | `energy/enphase/battery-settings/update` | `PUT /api/v4/systems/config/{id}/battery_settings?key={api_key}` | Megawatt | Megawatt: change battery mode / reserve SoC; body \{"battery\_mode":"Self-consumption","reserve\_soc":30} (writes to a real home battery) |
| `GetStormGuard` | `energy/enphase/storm-guard/get` | `GET /api/v4/systems/config/{id}/storm_guard?key={api_key}` | Megawatt | Megawatt: Storm Guard state |
| `GetGridStatus` | `energy/enphase/grid-status/get` | `GET /api/v4/systems/config/{id}/grid_status?key={api_key}` | Megawatt | Megawatt: on-grid / off-grid status of the system |

`SearchSystems` is a `POST` that only filters systems. The only real write is `UpdateBatterySettings` (Megawatt): it changes a home battery's mode and reserve SoC, so gate it behind an operator action. EV charger start / stop are marked "illustrative only" in the spec and are **not** packaged.

> [!TIP]
>
> For local, sub-second inverter data without the cloud, talk to the IQ Gateway over its local LAN API or Modbus TCP instead. This connector is for Enlighten cloud fleet data.

## Prerequisites

* An **Enphase developer account** at [developer-v4.enphase.com](https://developer-v4.enphase.com). The free **Watt** plan starts with 1,000 hits per month and 10 calls per minute.
* An **application** with its API key (`key`), client id and client secret.
* At least one **system owner** who approved the app (OAuth authorization code), so you have a working access token and refresh token.
* The **system id** of each site you want to read (from `system/list`) and, for micro telemetry, the microinverter serial (from `device/list`).
* For Kilowatt / Megawatt events: the matching paid plan. Lower plans get `403`.
* Outbound HTTPS from the broker to `api.enphaseenergy.com`. TLS 1.2 or newer is required.

## Authentication

Every event sends **both**:

1. Query parameter `key={value.json.api_key}` — the application API key from the developer portal.
2. Header `Authorization: {value.json.authorization}` — the string `Bearer <access_token>`.

Store them as Hub secrets, for example `ENPHASE_API_KEY` and `ENPHASE_AUTHORIZATION`, and read them with `GET SECRET` in the action that publishes to the connector.

| Response | Meaning |
| - | - |
| `401` `{"message":"Not Authorized","details":"User is not authorized","code":401}` | No `Authorization` header |
| `401` `{"message":"Not Authorized","details":"Token is invalid","code":401}` | Bad or expired access token |
| `401` `{"type":"authentication_error",...,"message":"API Key is invalid"}` | Bad `key` on the Streaming API (`live_data`) |
| `403` | Token valid but no access to that system / plan too low |
| `429` | Rate or monthly hit limit |

### Getting tokens (outside this connector)

1. Send the system owner: `https://api.enphaseenergy.com/oauth/authorize?response_type=code&client_id=<client_id>&redirect_uri=<uri>&state=<state>`.
2. Exchange the code: `POST https://api.enphaseenergy.com/oauth/token?grant_type=authorization_code&redirect_uri=<uri>&code=<code>` with Basic auth `client_id:client_secret`.
3. Refresh before expiry: `POST .../oauth/token?grant_type=refresh_token&refresh_token=<refresh_token>` with the same Basic auth. Access tokens last **1 day**, refresh tokens **1 month** on Watt / Kilowatt / Megawatt.

Partner applications can issue tokens without a homeowner click; that flow is documented in the Quick Start and is not part of this connector.

## Plans and rate limits

| Plan | Hits / minute | Hits / month | Extra |
| - | - | - | - |
| Watt (free) | 10 | 1,000 | System details, site production / consumption, EV charger monitoring |
| Kilowatt (USD 249 / mo) | 50 | 50,000 | Device-level monitoring, Streaming API (`live_data`, USD 0.10 / hit) |
| Megawatt (USD 999 / mo) | 100 | 300,000 | System configurations (battery settings, Storm Guard, grid status) |

Over-limit responses are `429`. Telemetry arrives at 5 or 15 minute resolution, so poll every 15 minutes or slower and prefer the site-level events on the free plan.

## Payload

| Field | Type | Required | Notes |
| - | - | - | - |
| `authorization` | string | yes | `Bearer <access_token>` |
| `api_key` | string | yes | Application key, rendered into `?key=` |
| `id` | string | most events | Enphase system id |
| `serial` | string | `GetMicroTelemetry` | Microinverter serial |
| `query` | string | when the endpoint has optional query params | Pre-encoded string after `?key=`, or `""` |
| `body` | object / string | `SearchSystems`, `UpdateBatterySettings` | JSON body |

Examples:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization":"Bearer eyJ...","api_key":"<key>","id":"698905955","query":""}
{"authorization":"Bearer eyJ...","api_key":"<key>","id":"698905955","query":"start_at=1759644000&granularity=15mins"}
{"authorization":"Bearer eyJ...","api_key":"<key>","id":"698905955","body":{"battery_mode":"Self-consumption","reserve_soc":30}}
```

## Example actions

These four actions stay inside a free Watt budget for one system (\~775 hits / month). Replace the example system id and wire the Hub secrets.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the EnphaseEnlightenApi route (docs page). Not part of the route template.
# Secrets: ENPHASE_API_KEY = the application API key from developer-v4.enphase.com (sent as ?key=);
#   ENPHASE_AUTHORIZATION = "Bearer <access_token>" (access token lives 1 day; refresh it outside these actions).
# System id 698905955 is an example id from the Enphase v4 spec. Replace it with your own (from system/list).
# Inline JSON object literals are not supported when publishing to a topic, so the request payload is a COLLAPSED
#   model sent with PUBLISH MODEL.
# Budget: the free Watt plan allows 1,000 hits / month and 10 per minute. These four actions use about
#   372 + 248 + 124 + 31 = 775 hits / month for one system.

DEFINE MODEL EnphaseRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "api_key"
    ADD STRING "id"
    ADD STRING "query"

DEFINE ACTION EnphaseSummaryEvery2Hours
ON EVERY 2 HOURS DO
    PUBLISH MODEL EnphaseRequest TO "energy/enphase/system-summary/get" WITH
        authorization = (GET SECRET "ENPHASE_AUTHORIZATION")
        api_key = (GET SECRET "ENPHASE_API_KEY")
        id = "698905955"
        query = ""

DEFINE ACTION EnphaseLatestTelemetryEvery3Hours
ON EVERY 3 HOURS DO
    PUBLISH MODEL EnphaseRequest TO "energy/enphase/latest-telemetry/get" WITH
        authorization = (GET SECRET "ENPHASE_AUTHORIZATION")
        api_key = (GET SECRET "ENPHASE_API_KEY")
        id = "698905955"
        query = ""

DEFINE ACTION EnphaseOpenAlarmsEvery6Hours
ON EVERY 6 HOURS DO
    PUBLISH MODEL EnphaseRequest TO "energy/enphase/open-alarm/list" WITH
        authorization = (GET SECRET "ENPHASE_AUTHORIZATION")
        api_key = (GET SECRET "ENPHASE_API_KEY")
        id = "698905955"
        query = ""

DEFINE ACTION EnphaseEnergyLifetimeDaily
ON EVERY 1 DAY DO
    PUBLISH MODEL EnphaseRequest TO "energy/enphase/energy-lifetime/get" WITH
        authorization = (GET SECRET "ENPHASE_AUTHORIZATION")
        api_key = (GET SECRET "ENPHASE_API_KEY")
        id = "698905955"
        query = ""
```

## Deployable connector

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Enphase Monitoring API v4 (Enlighten cloud: IQ microinverters, IQ Battery, meters, EVSE):
#   list and search systems, read system details and summary, device inventory, latest power snapshot, production /
#   consumption / battery / grid import-export telemetry and lifetime series, revenue-grade meter readings, open and
#   historical alarms and events; on paid plans also single-microinverter telemetry, the Streaming API live status,
#   battery settings (read and update), Storm Guard and grid status.
#   Credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/enphase-enlighten-api-v4
#
# Auth: every call needs BOTH the application API key as query parameter ?key=<api_key> AND
#   Authorization: Bearer <access_token> (OAuth 2.0). Payload fields: api_key (from the developer portal application)
#   and authorization ("Bearer <access_token>"). Keep both in Hub secrets (suggested ENPHASE_API_KEY and
#   ENPHASE_AUTHORIZATION) and map them into the payload with GET SECRET.
#   Tokens: the system owner approves your app at https://api.enphaseenergy.com/oauth/authorize?response_type=code&
#   client_id=<client_id>&redirect_uri=<uri>; exchange the code with POST https://api.enphaseenergy.com/oauth/token?
#   grant_type=authorization_code&redirect_uri=<uri>&code=<code> and Basic auth client_id:client_secret. Access token
#   lives 1 day, refresh token 1 month (grant_type=refresh_token). Refresh outside this route (or in a companion route).
#   Missing token: 401 {"message":"Not Authorized","details":"User is not authorized","code":401}; bad token:
#   401 {"message":"Not Authorized","details":"Token is invalid","code":401}.
# Plans (per developer application): Watt (free) 10 hits / minute, 1,000 / month: system details, site-level
#   production and consumption, EV charger monitoring. Kilowatt (USD 249 / month) 50 / min, 50,000 / month: adds
#   device-level monitoring and the Streaming API (USD 0.10 per live-status hit). Megawatt (USD 999 / month) 100 / min,
#   300,000 / month: adds system configurations. Events outside your plan answer 403; over the limit answers 429.
#   Telemetry granularity is 5 / 15 minutes at best, so poll every 15 minutes or slower.
# Queries: events with a "query" field take the pre-encoded extra query string ("" for none); it is appended after
#   ?key=. Times are epoch seconds (start_at, end_at, start_time, end_time) or YYYY-MM-DD (start_date, end_date,
#   summary_date); granularity = 5mins|15mins|day|week (default day).
# Writes: only UpdateBatterySettings (PUT, Megawatt) and SearchSystems (POST, read-only filter). UpdateBatterySettings
#   changes a real home battery's mode / reserve: gate it behind an operator action. EV charger start / stop are
#   "illustrative only - access via VPP API for partners" in the spec and are not packaged.
#
# Payload fields: authorization, api_key, id (Enphase system id), serial (microinverter serial), query, body
#     GetSystemSummary            id = "698905955", query = ""
#     GetProductionMicroTelemetry id = "698905955", query = "start_at=1759644000&granularity=15mins"
#     GetEnergyLifetime           id = "698905955", query = "start_date=2026-10-01&end_date=2026-10-04"
#     ListAlarms                  id = "698905955", query = "start_time=1759100000&cleared=false"
#     UpdateBatterySettings       id = "698905955", body = {"battery_mode":"Self-consumption","reserve_soc":30}

DEFINE CONNECTOR EnphaseEnlightenApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.enphaseenergy.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListSystems
        WITH SOURCE_TOPIC "energy/enphase/system/list"
        WITH DESTINATION_TOPIC "energy/enphase/system/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT SearchSystems
        WITH SOURCE_TOPIC "energy/enphase/system/search"
        WITH DESTINATION_TOPIC "energy/enphase/system/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v4/systems/search?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetSystem
        WITH SOURCE_TOPIC "energy/enphase/system/get"
        WITH DESTINATION_TOPIC "energy/enphase/system/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSystemSummary
        WITH SOURCE_TOPIC "energy/enphase/system-summary/get"
        WITH DESTINATION_TOPIC "energy/enphase/system-summary/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/summary?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListSystemDevices
        WITH SOURCE_TOPIC "energy/enphase/device/list"
        WITH DESTINATION_TOPIC "energy/enphase/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/devices?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RetrieveSystemId
        WITH SOURCE_TOPIC "energy/enphase/system-id/get"
        WITH DESTINATION_TOPIC "energy/enphase/system-id/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/retrieve_system_id?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetLatestTelemetry
        WITH SOURCE_TOPIC "energy/enphase/latest-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/latest-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/latest_telemetry?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetProductionMeterReadings
        WITH SOURCE_TOPIC "energy/enphase/production-meter-readings/get"
        WITH DESTINATION_TOPIC "energy/enphase/production-meter-readings/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/production_meter_readings?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetEnergyLifetime
        WITH SOURCE_TOPIC "energy/enphase/energy-lifetime/get"
        WITH DESTINATION_TOPIC "energy/enphase/energy-lifetime/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/energy_lifetime?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetRgmStats
        WITH SOURCE_TOPIC "energy/enphase/rgm-stats/get"
        WITH DESTINATION_TOPIC "energy/enphase/rgm-stats/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/rgm_stats?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetProductionMicroTelemetry
        WITH SOURCE_TOPIC "energy/enphase/production-micro-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/production-micro-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/telemetry/production_micro?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetProductionMeterTelemetry
        WITH SOURCE_TOPIC "energy/enphase/production-meter-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/production-meter-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/telemetry/production_meter?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetConsumptionMeterTelemetry
        WITH SOURCE_TOPIC "energy/enphase/consumption-meter-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/consumption-meter-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/telemetry/consumption_meter?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetBatteryTelemetry
        WITH SOURCE_TOPIC "energy/enphase/battery-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/battery-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/telemetry/battery?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetEnergyImportTelemetry
        WITH SOURCE_TOPIC "energy/enphase/energy-import-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/energy-import-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/energy_import_telemetry?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetEnergyExportTelemetry
        WITH SOURCE_TOPIC "energy/enphase/energy-export-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/energy-export-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/energy_export_telemetry?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetConsumptionLifetime
        WITH SOURCE_TOPIC "energy/enphase/consumption-lifetime/get"
        WITH DESTINATION_TOPIC "energy/enphase/consumption-lifetime/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/consumption_lifetime?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListOpenAlarms
        WITH SOURCE_TOPIC "energy/enphase/open-alarm/list"
        WITH DESTINATION_TOPIC "energy/enphase/open-alarm/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/open_alarms?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListAlarms
        WITH SOURCE_TOPIC "energy/enphase/alarm/list"
        WITH DESTINATION_TOPIC "energy/enphase/alarm/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/alarms?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListOpenEvents
        WITH SOURCE_TOPIC "energy/enphase/open-event/list"
        WITH DESTINATION_TOPIC "energy/enphase/open-event/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/open_events?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListEvents
        WITH SOURCE_TOPIC "energy/enphase/event/list"
        WITH DESTINATION_TOPIC "energy/enphase/event/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/events?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListEventTypes
        WITH SOURCE_TOPIC "energy/enphase/event-type/list"
        WITH DESTINATION_TOPIC "energy/enphase/event-type/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/event_types?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetMicroTelemetry
        WITH SOURCE_TOPIC "energy/enphase/micro-telemetry/get"
        WITH DESTINATION_TOPIC "energy/enphase/micro-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/devices/micros/{value.json.serial}/telemetry?key={value.json.api_key}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetLiveData
        WITH SOURCE_TOPIC "energy/enphase/live-data/get"
        WITH DESTINATION_TOPIC "energy/enphase/live-data/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/{value.json.id}/live_data?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetBatterySettings
        WITH SOURCE_TOPIC "energy/enphase/battery-settings/get"
        WITH DESTINATION_TOPIC "energy/enphase/battery-settings/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/config/{value.json.id}/battery_settings?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT UpdateBatterySettings
        WITH SOURCE_TOPIC "energy/enphase/battery-settings/update"
        WITH DESTINATION_TOPIC "energy/enphase/battery-settings/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v4/systems/config/{value.json.id}/battery_settings?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetStormGuard
        WITH SOURCE_TOPIC "energy/enphase/storm-guard/get"
        WITH DESTINATION_TOPIC "energy/enphase/storm-guard/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/config/{value.json.id}/storm_guard?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetGridStatus
        WITH SOURCE_TOPIC "energy/enphase/grid-status/get"
        WITH DESTINATION_TOPIC "energy/enphase/grid-status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/systems/config/{value.json.id}/grid_status?key={value.json.api_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```


# ENTSO-E Transparency Platform REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/entso-e-transparency-platform

Client-mode REST API connector for European day-ahead prices, generation per type, and system load (IEC 62325 XML)

Technical Preview

## Overview

The [ENTSO-E Transparency Platform](https://transparency.entsoe.eu/) publishes pan-European electricity market data under EU Regulation 543/2013. This connector calls the production Web API at `https://web-api.tp.entsoe.eu` with `BASE_ADDRESS` set to that origin and path `/api`. Responses are **IEC 62325 XML** (`Accept: application/xml`), not JSON.

> [!NOTE]
>
> A call without a valid `securityToken` returns HTTP 401 (`Acknowledgement_MarketDocument`: missing or invalid security token). Register on the Transparency Platform, request RESTful API access from [transparency@entsoe.eu](mailto:transparency@entsoe.eu), generate a token under My Account, and pass it only at runtime.

## Auth

Pass the personal **security token** as the `securityToken` query parameter via `{value.json.securityToken}`. Prefer Hub secrets / `GET SECRET "ENTSOE_SECURITY_TOKEN"`. Never commit real tokens into the `.lot`.

## Area codes

Queries use EIC area codes. Portugal example (documentation only): `10YPT-REN------W`. For day-ahead prices (A44), `in_Domain` and `out_Domain` must be the same bidding-zone EIC. Load items (A65) use `outBiddingZone_Domain`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EntsoETransparencyPlatformRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://web-api.tp.entsoe.eu"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/xml"
    ADD EVENT GetDayAheadPrices
        WITH SOURCE_TOPIC "integrations/entso-e-transparency-platform/request/GetDayAheadPrices"
        WITH DESTINATION_TOPIC "integrations/entso-e-transparency-platform/response/GetDayAheadPrices"
        WITH METHOD "GET"
        WITH ENDPOINT "/api?securityToken={value.json.securityToken}&documentType=A44&in_Domain={value.json.in_Domain}&out_Domain={value.json.out_Domain}&periodStart={value.json.periodStart}&periodEnd={value.json.periodEnd}"
        WITH HEADERS
            ADD "Accept" "application/xml"
    ADD EVENT GetActualGenerationPerType
        WITH SOURCE_TOPIC "integrations/entso-e-transparency-platform/request/GetActualGenerationPerType"
        WITH DESTINATION_TOPIC "integrations/entso-e-transparency-platform/response/GetActualGenerationPerType"
        WITH METHOD "GET"
        WITH ENDPOINT "/api?securityToken={value.json.securityToken}&documentType=A75&processType=A16&in_Domain={value.json.in_Domain}&periodStart={value.json.periodStart}&periodEnd={value.json.periodEnd}"
        WITH HEADERS
            ADD "Accept" "application/xml"
    ADD EVENT GetTotalLoad
        WITH SOURCE_TOPIC "integrations/entso-e-transparency-platform/request/GetTotalLoad"
        WITH DESTINATION_TOPIC "integrations/entso-e-transparency-platform/response/GetTotalLoad"
        WITH METHOD "GET"
        WITH ENDPOINT "/api?securityToken={value.json.securityToken}&documentType=A65&processType=A16&outBiddingZone_Domain={value.json.outBiddingZone_Domain}&periodStart={value.json.periodStart}&periodEnd={value.json.periodEnd}"
        WITH HEADERS
            ADD "Accept" "application/xml"
```

## Events in this package

| Event | documentType | Focus |
| - | - | - |
| GetDayAheadPrices | A44 | Day-ahead prices |
| GetActualGenerationPerType | A75 | Actual generation per type (`processType=A16`) |
| GetTotalLoad | A65 | Actual total load (`processType=A16`) |
| GetCrossBorderPhysicalFlows | A11 | Cross-border physical flows |
| GetWindAndSolarGeneration | A74 | Wind and solar generation |
| GetDayAheadTotalLoadForecast | A65 + A01 | Day-ahead total load forecast |

`periodStart` / `periodEnd` use `yyyyMMddHHmm` UTC.

## Example request payload

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "securityToken": "YOUR_ENTSOE_SECURITY_TOKEN",
  "in_Domain": "10YPT-REN------W",
  "out_Domain": "10YPT-REN------W",
  "periodStart": "202610010000",
  "periodEnd": "202610020000"
}
```

For load events, use `outBiddingZone_Domain` instead of `in_Domain` / `out_Domain`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [ENTSO-E Transparency Platform](https://transparency.entsoe.eu/)
* [How to get a security token](https://transparencyplatform.zendesk.com/hc/en-us/articles/12845911031188-How-to-get-security-token)


# Epicor Kinetic REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/epicor-kinetic

Client-mode REST API connector for Epicor Kinetic OData v2 (Jobs, Labor, Parts, Inventory)

Technical Preview

## Overview

Client-mode REST API connector for Epicor Kinetic OData v2 (Jobs, Labor, Parts, Inventory). `BASE_ADDRESS` defaults to `https://YOUR_SERVER/YOUR_INSTANCE/api/v2/odata/YOUR_COMPANY`. Auth: **Basic or API key + Bearer (Epicor Identity)**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

Basic or API key + Bearer (Epicor Identity). Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR EpicorKineticRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_SERVER/YOUR_INSTANCE/api/v2/odata/YOUR_COMPANY"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Authorization Bearer {value.json.access_token} — prefer Hub secrets / GET SECRET.
        # Optional Basic: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Listjobs
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Listjobs"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Listjobs"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.JobEntrySvc/Jobs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getjob
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Getjob"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Getjob"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.JobEntrySvc/Jobs('{value.json.JobNum}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createlabor
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Createlabor"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Createlabor"
        WITH METHOD "POST"
        WITH ENDPOINT "/Erp.BO.LaborSvc/Labors"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/epicor-kinetic/request/...`; responses on `integrations/epicor-kinetic/response/...`.

## Template reference

Generated from the shipped broker template `epicor-kinetic` (`-connectorCode EPICOR_KINETIC`). It lists every event the template defines.

### Auth

Basic or API key + Bearer (Epicor Identity)

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`, `x-api-key: {value.json.api_key}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Epicor Kinetic connector | no |
| `BaseUrl` | string | Epicor Kinetic base URL without trailing slash (e.g. https\://YOUR\_SERVER/YOUR\_INSTANCE/api/v2/odata/YOUR\_COMPANY) | yes |

`BASE_ADDRESS` default: `https://YOUR_SERVER/YOUR_INSTANCE/api/v2/odata/YOUR_COMPANY`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listjobs` | GET | `/Erp.BO.JobEntrySvc/Jobs` | `integrations/epicor-kinetic/request/Listjobs` | `integrations/epicor-kinetic/response/Listjobs` | `access_token`, `api_key` |
| `Getjob` | GET | `/Erp.BO.JobEntrySvc/Jobs('{value.json.JobNum}')` | `integrations/epicor-kinetic/request/Getjob` | `integrations/epicor-kinetic/response/Getjob` | `JobNum`, `access_token`, `api_key` |
| `Createlabor` | POST | `/Erp.BO.LaborSvc/Labors` | `integrations/epicor-kinetic/request/Createlabor` | `integrations/epicor-kinetic/response/Createlabor` | `access_token`, `api_key`, `body` |
| `Listparts` | GET | `/Erp.BO.PartSvc/Parts` | `integrations/epicor-kinetic/request/Listparts` | `integrations/epicor-kinetic/response/Listparts` | `access_token`, `api_key` |
| `Getpart` | GET | `/Erp.BO.PartSvc/Parts('{value.json.PartNum}')` | `integrations/epicor-kinetic/request/Getpart` | `integrations/epicor-kinetic/response/Getpart` | `PartNum`, `access_token`, `api_key` |
| `Createinventoryqtyadj` | POST | `/Erp.BO.InventoryQtyAdjSvc/InventoryQtyAdjs` | `integrations/epicor-kinetic/request/Createinventoryqtyadj` | `integrations/epicor-kinetic/response/Createinventoryqtyadj` | `access_token`, `api_key`, `body` |
| `Listemployees` | GET | `/Erp.BO.EmpBasicSvc/EmpBasics` | `integrations/epicor-kinetic/request/Listemployees` | `integrations/epicor-kinetic/response/Listemployees` | `access_token`, `api_key` |
| `Searchjobs` | GET | `/Erp.BO.JobEntrySvc/Jobs?$filter={value.json.filter}&$top={value.json.top}` | `integrations/epicor-kinetic/request/Searchjobs` | `integrations/epicor-kinetic/response/Searchjobs` | `access_token`, `api_key`, `filter`, `top` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode EPICOR_KINETIC"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EpicorKineticRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_SERVER/YOUR_INSTANCE/api/v2/odata/YOUR_COMPANY"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listjobs
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Listjobs"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Listjobs"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.JobEntrySvc/Jobs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT Getjob
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Getjob"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Getjob"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.JobEntrySvc/Jobs('{value.json.JobNum}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT Createlabor
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Createlabor"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Createlabor"
        WITH METHOD "POST"
        WITH ENDPOINT "/Erp.BO.LaborSvc/Labors"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT Listparts
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Listparts"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Listparts"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.PartSvc/Parts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT Getpart
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Getpart"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Getpart"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.PartSvc/Parts('{value.json.PartNum}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT Createinventoryqtyadj
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Createinventoryqtyadj"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Createinventoryqtyadj"
        WITH METHOD "POST"
        WITH ENDPOINT "/Erp.BO.InventoryQtyAdjSvc/InventoryQtyAdjs"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT Listemployees
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Listemployees"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Listemployees"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.EmpBasicSvc/EmpBasics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT Searchjobs
        WITH SOURCE_TOPIC "integrations/epicor-kinetic/request/Searchjobs"
        WITH DESTINATION_TOPIC "integrations/epicor-kinetic/response/Searchjobs"
        WITH METHOD "GET"
        WITH ENDPOINT "/Erp.BO.JobEntrySvc/Jobs?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-api-key" "{value.json.api_key}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listjobs` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/epicor-kinetic/response/Listjobs' &
mosquitto_pub -t 'integrations/epicor-kinetic/request/Listjobs' -m '{"access_token": "<access_token>", "api_key": "<api_key>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# ERedes Open Data
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/eredes-open-data

LoT connector for E-REDES open data in Portugal: national consumption and production, consumption forecasts and municipality usage, no API key needed

Technical Preview

## Overview

Client-mode REST API connectors for Portuguese grid open data with no API key: E-REDES distribution datasets (15-minute national consumption and production, consumption forecast, consumption by municipality) and REN DataHub electricity and gas balances, production by source and market prices.

This is one of the templates in the E-REDES and REN open data (Portugal) REST API app (`e-redes-and-ren-open-data`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["none"]
* **secrets**: \[]
* **note**: Both keyless. E-REDES optional portal API key (Authorization: Apikey ...) for higher quota; not wired by default.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the ERedes Open Data connector | no |
| `BaseUrl` | string | ERedes Open Data base URL without trailing slash (e.g. [https://e-redes.opendatasoft.com](https://e-redes.opendatasoft.com)) | yes |

`BASE_ADDRESS` default: `https://e-redes.opendatasoft.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ERedesCatalogDatasets` | GET | `/api/explore/v2.1/catalog/datasets?limit={value.json.limit}{value.json.params}` | `energy/pt/eredes/catalog/datasets/get` | `energy/pt/eredes/catalog/datasets/get/response` | `limit`, `params` |
| `ERedesDataset` | GET | `/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}` | `energy/pt/eredes/dataset/get` | `energy/pt/eredes/dataset/get/response` | `dataset_id` |
| `ERedesRecords` | GET | `/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/records?limit={value.json.limit}{value.json.params}` | `energy/pt/eredes/records/get` | `energy/pt/eredes/records/get/response` | `dataset_id`, `limit`, `params` |
| `ERedesRecord` | GET | `/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/records/{value.json.record_id}` | `energy/pt/eredes/record/get` | `energy/pt/eredes/record/get/response` | `dataset_id`, `record_id` |
| `ERedesFacets` | GET | `/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/facets?facet={value.json.facet}{value.json.params}` | `energy/pt/eredes/facets/get` | `energy/pt/eredes/facets/get/response` | `dataset_id`, `facet`, `params` |
| `ERedesExportJson` | GET | `/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/exports/json?limit={value.json.limit}{value.json.params}` | `energy/pt/eredes/export/get` | `energy/pt/eredes/export/get/response` | `dataset_id`, `limit`, `params` |
| `ERedesMunicipalityConsumption` | GET | `/api/explore/v2.1/catalog/datasets/3-consumos-faturados-por-municipio-ultimos-10-anos/records?refine=concelho:{value.json.municipality}&order_by=-data&limit={value.json.limit}{value.json.params}` | `energy/pt/eredes/municipality-consumption/get` | `energy/pt/eredes/municipality-consumption/get/response` | `limit`, `municipality`, `params` |
| `ERedesNationalConsumption` | GET | `/api/explore/v2.1/catalog/datasets/consumo-total-nacional/records?order_by=-datahora&limit={value.json.limit}{value.json.params}` | `energy/pt/eredes/national-consumption/get` | `energy/pt/eredes/national-consumption/get/response` | `limit`, `params` |
| `ERedesNationalProduction` | GET | `/api/explore/v2.1/catalog/datasets/energia-produzida-total-nacional/records?order_by=-datahora&limit={value.json.limit}{value.json.params}` | `energy/pt/eredes/national-production/get` | `energy/pt/eredes/national-production/get/response` | `limit`, `params` |
| `ERedesConsumptionForecast` | GET | `/api/explore/v2.1/catalog/datasets/previsao-de-consumo/records?refine=data:{value.json.date}&order_by=datahora&limit={value.json.limit}{value.json.params}` | `energy/pt/eredes/consumption-forecast/get` | `energy/pt/eredes/consumption-forecast/get/response` | `date`, `limit`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode EREDES_OPEN_DATA"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ERedesOpenData WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://e-redes.opendatasoft.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ERedesCatalogDatasets
        WITH SOURCE_TOPIC "energy/pt/eredes/catalog/datasets/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/catalog/datasets/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets?limit={value.json.limit}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesDataset
        WITH SOURCE_TOPIC "energy/pt/eredes/dataset/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/dataset/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesRecords
        WITH SOURCE_TOPIC "energy/pt/eredes/records/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/records/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/records?limit={value.json.limit}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesRecord
        WITH SOURCE_TOPIC "energy/pt/eredes/record/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/record/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/records/{value.json.record_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesFacets
        WITH SOURCE_TOPIC "energy/pt/eredes/facets/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/facets/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/facets?facet={value.json.facet}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesExportJson
        WITH SOURCE_TOPIC "energy/pt/eredes/export/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/export/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/{value.json.dataset_id}/exports/json?limit={value.json.limit}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesMunicipalityConsumption
        WITH SOURCE_TOPIC "energy/pt/eredes/municipality-consumption/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/municipality-consumption/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/3-consumos-faturados-por-municipio-ultimos-10-anos/records?refine=concelho:{value.json.municipality}&order_by=-data&limit={value.json.limit}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesNationalConsumption
        WITH SOURCE_TOPIC "energy/pt/eredes/national-consumption/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/national-consumption/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/consumo-total-nacional/records?order_by=-datahora&limit={value.json.limit}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesNationalProduction
        WITH SOURCE_TOPIC "energy/pt/eredes/national-production/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/national-production/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/energia-produzida-total-nacional/records?order_by=-datahora&limit={value.json.limit}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ERedesConsumptionForecast
        WITH SOURCE_TOPIC "energy/pt/eredes/consumption-forecast/get"
        WITH DESTINATION_TOPIC "energy/pt/eredes/consumption-forecast/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/explore/v2.1/catalog/datasets/previsao-de-consumo/records?refine=data:{value.json.date}&order_by=datahora&limit={value.json.limit}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ERedesCatalogDatasets` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/pt/eredes/catalog/datasets/get/response' &
mosquitto_pub -t 'energy/pt/eredes/catalog/datasets/get' -m '{"limit": "<limit>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Excel Online
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/excel-online

Client-mode REST API connector for Excel workbooks in OneDrive and SharePoint through Microsoft Graph: sessions plus table rows and range read and write

Technical Preview

## Overview

Client-mode REST API connector for Excel workbooks in OneDrive and SharePoint through Microsoft Graph: sessions plus table rows and range read and write. `BASE_ADDRESS` defaults to `https://graph.microsoft.com`. Topics use `data/excel-online/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `SessionCreate` | `POST /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/createSession` | `data/excel-online/sessions/create` |
| `SessionClose` | `POST /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/closeSession` | `data/excel-online/sessions/close` |
| `WorksheetsList` | `GET /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/worksheets` | `data/excel-online/worksheets/list` |
| `TablesList` | `GET /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/tables` | `data/excel-online/tables/list` |
| `TableRowsList` | `GET /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/tables/{value.json.table}/rows?$top={value.json.top}&$skip={value.json.skip}` | `data/excel-online/tables/rows/list` |
| `TableRowsAdd` | `POST /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/tables/{value.json.table}/rows` | `data/excel-online/tables/rows/add` |
| `RangeGet` | `GET /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/worksheets/{value.json.sheet}/range(address='{value.json.address}')` | `data/excel-online/ranges/get` |
| `RangeUpdate` | `PATCH /v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/worksheets/{value.json.sheet}/range(address='{value.json.address}')` | `data/excel-online/ranges/update` |

## Authentication

Microsoft Entra ID OAuth 2.0 access token for Microsoft Graph (Files.ReadWrite or Files.ReadWrite.All / Sites.ReadWrite.All for app-only) in Authorization: Bearer \{value.json.access\_token}. Get the token from login.microsoftonline.com upstream (see the SharePoint and OneDrive connector).

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* Only .xlsx files in OneDrive for Business or SharePoint are supported by the Graph workbook API.
* workbook-session-id is optional; send an empty string to work sessionless, or create a persistent session with SessionCreate (body \{"persistChanges":true}) for many writes.
* RangeGet / RangeUpdate use range(address='A1:D10'); pass sheet and address in the payload.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ExcelOnlineRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://graph.microsoft.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SessionCreate
        WITH SOURCE_TOPIC "data/excel-online/sessions/create"
        WITH DESTINATION_TOPIC "data/excel-online/sessions/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/createSession"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT SessionClose
        WITH SOURCE_TOPIC "data/excel-online/sessions/close"
        WITH DESTINATION_TOPIC "data/excel-online/sessions/close/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/closeSession"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "workbook-session-id" "{value.json.session_id}"
        WITH BODY ""
    ADD EVENT WorksheetsList
        WITH SOURCE_TOPIC "data/excel-online/worksheets/list"
        WITH DESTINATION_TOPIC "data/excel-online/worksheets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/worksheets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "workbook-session-id" "{value.json.session_id}"
    ADD EVENT TablesList
        WITH SOURCE_TOPIC "data/excel-online/tables/list"
        WITH DESTINATION_TOPIC "data/excel-online/tables/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/tables"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "workbook-session-id" "{value.json.session_id}"
    ADD EVENT TableRowsList
        WITH SOURCE_TOPIC "data/excel-online/tables/rows/list"
        WITH DESTINATION_TOPIC "data/excel-online/tables/rows/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/tables/{value.json.table}/rows?$top={value.json.top}&$skip={value.json.skip}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "workbook-session-id" "{value.json.session_id}"
    ADD EVENT TableRowsAdd
        WITH SOURCE_TOPIC "data/excel-online/tables/rows/add"
        WITH DESTINATION_TOPIC "data/excel-online/tables/rows/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/tables/{value.json.table}/rows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "workbook-session-id" "{value.json.session_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT RangeGet
        WITH SOURCE_TOPIC "data/excel-online/ranges/get"
        WITH DESTINATION_TOPIC "data/excel-online/ranges/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/worksheets/{value.json.sheet}/range(address='{value.json.address}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "workbook-session-id" "{value.json.session_id}"
    ADD EVENT RangeUpdate
        WITH SOURCE_TOPIC "data/excel-online/ranges/update"
        WITH DESTINATION_TOPIC "data/excel-online/ranges/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v1.0/drives/{value.json.driveId}/items/{value.json.itemId}/workbook/worksheets/{value.json.sheet}/range(address='{value.json.address}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "workbook-session-id" "{value.json.session_id}"
        WITH BODY "{value.json.body}"
```

## Sources

* [https://learn.microsoft.com/en-us/graph/api/resources/excel](https://learn.microsoft.com/en-us/graph/api/resources/excel)
* [https://learn.microsoft.com/en-us/graph/api/workbook-createsession](https://learn.microsoft.com/en-us/graph/api/workbook-createsession)
* [https://learn.microsoft.com/en-us/graph/api/table-post-rows](https://learn.microsoft.com/en-us/graph/api/table-post-rows)
* [https://learn.microsoft.com/en-us/graph/api/tablerow-list](https://learn.microsoft.com/en-us/graph/api/tablerow-list)
* [https://learn.microsoft.com/en-us/graph/api/range-get](https://learn.microsoft.com/en-us/graph/api/range-get)
* [https://learn.microsoft.com/en-us/graph/api/range-update](https://learn.microsoft.com/en-us/graph/api/range-update)


# Fed Ex Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/fed-ex-api

LoT connector for FedEx APIs: track shipments, get rates, validate addresses, create shipments and labels, book pickups and check trade regulations

Technical Preview

## Overview

Client-mode REST API connector for the FedEx Developer Portal APIs: OAuth 2.0 client credentials, tracking (tracking number, reference, TCN, multiple-piece shipments, proof of delivery documents, e-mail notifications), rates and transit times, address and postal code validation, service availability, location search, shipments and labels (purchase), cancel, return tags (purchase), pickups (purchase), Global Trade regulatory details, Advanced Integrated Visibility subscriptions (billed) and trade document upload; companion server connector for AIV tracking webhooks.

This is one of the templates in the FedEx Developer Portal REST API app (`fedex-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 client credentials (credentials in the form body, client\_secret\_post): GetToken posts grant\_type=client\_credentials\&client\_id\&client\_secret (application/x-www-form-urlencoded) to /oauth/token; GetTokenChild uses client\_pc\_credentials or csp\_credentials + child\_Key + child\_secret. Reply access\_token, token\_type bearer, expires\_in 3600, scope; no refresh token. FedExApi / FedExDocs events: Authorization: Bearer \<access\_token> and x-customer-transaction-id; FedExApi also x-locale en\_US. Every event sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Fed Ex Api connector | no |
| `BaseUrl` | string | Fed Ex Api base URL without trailing slash (e.g. [https://apis.fedex.com](https://apis.fedex.com)) | yes |

`BASE_ADDRESS` default: `https://apis.fedex.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `TrackByTrackingNumber` | POST | `/track/v1/trackingnumbers` | `fleet/fedex/track/get` | `fleet/fedex/track/get/response` | `access_token`, `body`, `trans_id` |
| `TrackByReference` | POST | `/track/v1/referencenumbers` | `fleet/fedex/track-reference/get` | `fleet/fedex/track-reference/get/response` | `access_token`, `body`, `trans_id` |
| `TrackByTcn` | POST | `/track/v1/tcn` | `fleet/fedex/track-tcn/get` | `fleet/fedex/track-tcn/get/response` | `access_token`, `body`, `trans_id` |
| `TrackMultiPieceShipment` | POST | `/track/v1/associatedshipments` | `fleet/fedex/track-associated/get` | `fleet/fedex/track-associated/get/response` | `access_token`, `body`, `trans_id` |
| `GetTrackingDocument` | POST | `/track/v1/trackingdocuments` | `fleet/fedex/tracking-document/get` | `fleet/fedex/tracking-document/get/response` | `access_token`, `body`, `trans_id` |
| `SendTrackingNotification` | POST | `/track/v1/notifications` | `fleet/fedex/tracking-notification/create` | `fleet/fedex/tracking-notification/create/response` | `access_token`, `body`, `trans_id` |
| `RateQuote` | POST | `/rate/v1/rates/quotes` | `fleet/fedex/rate/get` | `fleet/fedex/rate/get/response` | `access_token`, `body`, `trans_id` |
| `ValidateAddress` | POST | `/address/v1/addresses/resolve` | `fleet/fedex/address/validate` | `fleet/fedex/address/validate/response` | `access_token`, `body`, `trans_id` |
| `ValidatePostalCode` | POST | `/country/v1/postal/validate` | `fleet/fedex/postal-code/validate` | `fleet/fedex/postal-code/validate/response` | `access_token`, `body`, `trans_id` |
| `GetTransitTimes` | POST | `/availability/v1/transittimes` | `fleet/fedex/transit-time/get` | `fleet/fedex/transit-time/get/response` | `access_token`, `body`, `trans_id` |
| `GetPackageAndServiceOptions` | POST | `/availability/v1/packageandserviceoptions` | `fleet/fedex/service-option/get` | `fleet/fedex/service-option/get/response` | `access_token`, `body`, `trans_id` |
| `GetSpecialServiceOptions` | POST | `/availability/v1/specialserviceoptions` | `fleet/fedex/special-service-option/get` | `fleet/fedex/special-service-option/get/response` | `access_token`, `body`, `trans_id` |
| `FindLocations` | POST | `/location/v1/locations` | `fleet/fedex/location/search` | `fleet/fedex/location/search/response` | `access_token`, `body`, `trans_id` |
| `ValidateShipment` | POST | `/ship/v1/shipments/packages/validate` | `fleet/fedex/shipment/validate` | `fleet/fedex/shipment/validate/response` | `access_token`, `body`, `trans_id` |
| `CreateShipment` | POST | `/ship/v1/shipments` | `fleet/fedex/shipment/create` | `fleet/fedex/shipment/create/response` | `access_token`, `body`, `trans_id` |
| `GetShipmentResults` | POST | `/ship/v1/shipments/results` | `fleet/fedex/shipment-results/get` | `fleet/fedex/shipment-results/get/response` | `access_token`, `body`, `trans_id` |
| `CancelShipment` | PUT | `/ship/v1/shipments/cancel` | `fleet/fedex/shipment/cancel` | `fleet/fedex/shipment/cancel/response` | `access_token`, `body`, `trans_id` |
| `CreateTag` | POST | `/ship/v1/shipments/tag` | `fleet/fedex/tag/create` | `fleet/fedex/tag/create/response` | `access_token`, `body`, `trans_id` |
| `CancelTag` | PUT | `/ship/v1/shipments/tag/cancel/{value.json.id}` | `fleet/fedex/tag/cancel` | `fleet/fedex/tag/cancel/response` | `access_token`, `body`, `id`, `trans_id` |
| `CheckPickupAvailability` | POST | `/pickup/v1/pickups/availabilities` | `fleet/fedex/pickup-availability/get` | `fleet/fedex/pickup-availability/get/response` | `access_token`, `body`, `trans_id` |
| `CreatePickup` | POST | `/pickup/v1/pickups` | `fleet/fedex/pickup/create` | `fleet/fedex/pickup/create/response` | `access_token`, `body`, `trans_id` |
| `CancelPickup` | PUT | `/pickup/v1/pickups/cancel` | `fleet/fedex/pickup/cancel` | `fleet/fedex/pickup/cancel/response` | `access_token`, `body`, `trans_id` |
| `GetRegulatoryDetails` | POST | `/globaltrade/v1/shipments/regulatorydetails/retrieve` | `fleet/fedex/regulatory/get` | `fleet/fedex/regulatory/get/response` | `access_token`, `body`, `trans_id` |
| `AssociateTrackingNumbers` | POST | `/webhook/v1/subscriptions/trackingnumbers/association` | `fleet/fedex/aiv-tracking-number/associate` | `fleet/fedex/aiv-tracking-number/associate/response` | `access_token`, `action`, `body`, `trans_id` |
| `AssociateTrackingNumbersSync` | POST | `/webhook/v1/subscriptions/trackingnumbers/syncassociation` | `fleet/fedex/aiv-tracking-number-sync/associate` | `fleet/fedex/aiv-tracking-number-sync/associate/response` | `access_token`, `body`, `trans_id` |
| `GetAssociationJobStatus` | GET | `/webhook/v1/subscriptions/trackingnumbers/jobstatus?{value.json.query}` | `fleet/fedex/aiv-job-status/get` | `fleet/fedex/aiv-job-status/get/response` | `access_token`, `query`, `trans_id` |
| `GetAssociationJobDetails` | GET | `/webhook/v1/subscriptions/trackingnumbers/jobdetails?{value.json.query}` | `fleet/fedex/aiv-job-details/get` | `fleet/fedex/aiv-job-details/get/response` | `access_token`, `query`, `trans_id` |
| `GetAccountSubscription` | GET | `/webhook/v3/subscriptions?{value.json.query}` | `fleet/fedex/aiv-subscription/get` | `fleet/fedex/aiv-subscription/get/response` | `access_token`, `query`, `trans_id` |
| `UpdateAccountSubscription` | PUT | `/webhook/v3/subscriptions` | `fleet/fedex/aiv-subscription/update` | `fleet/fedex/aiv-subscription/update/response` | `access_token`, `body`, `trans_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode FED_EX_API"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FedExApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://apis.fedex.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TrackByTrackingNumber
        WITH SOURCE_TOPIC "fleet/fedex/track/get"
        WITH DESTINATION_TOPIC "fleet/fedex/track/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/track/v1/trackingnumbers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TrackByReference
        WITH SOURCE_TOPIC "fleet/fedex/track-reference/get"
        WITH DESTINATION_TOPIC "fleet/fedex/track-reference/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/track/v1/referencenumbers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TrackByTcn
        WITH SOURCE_TOPIC "fleet/fedex/track-tcn/get"
        WITH DESTINATION_TOPIC "fleet/fedex/track-tcn/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/track/v1/tcn"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TrackMultiPieceShipment
        WITH SOURCE_TOPIC "fleet/fedex/track-associated/get"
        WITH DESTINATION_TOPIC "fleet/fedex/track-associated/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/track/v1/associatedshipments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTrackingDocument
        WITH SOURCE_TOPIC "fleet/fedex/tracking-document/get"
        WITH DESTINATION_TOPIC "fleet/fedex/tracking-document/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/track/v1/trackingdocuments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT SendTrackingNotification
        WITH SOURCE_TOPIC "fleet/fedex/tracking-notification/create"
        WITH DESTINATION_TOPIC "fleet/fedex/tracking-notification/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/track/v1/notifications"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RateQuote
        WITH SOURCE_TOPIC "fleet/fedex/rate/get"
        WITH DESTINATION_TOPIC "fleet/fedex/rate/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rate/v1/rates/quotes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ValidateAddress
        WITH SOURCE_TOPIC "fleet/fedex/address/validate"
        WITH DESTINATION_TOPIC "fleet/fedex/address/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/address/v1/addresses/resolve"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ValidatePostalCode
        WITH SOURCE_TOPIC "fleet/fedex/postal-code/validate"
        WITH DESTINATION_TOPIC "fleet/fedex/postal-code/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/country/v1/postal/validate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTransitTimes
        WITH SOURCE_TOPIC "fleet/fedex/transit-time/get"
        WITH DESTINATION_TOPIC "fleet/fedex/transit-time/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/availability/v1/transittimes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetPackageAndServiceOptions
        WITH SOURCE_TOPIC "fleet/fedex/service-option/get"
        WITH DESTINATION_TOPIC "fleet/fedex/service-option/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/availability/v1/packageandserviceoptions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetSpecialServiceOptions
        WITH SOURCE_TOPIC "fleet/fedex/special-service-option/get"
        WITH DESTINATION_TOPIC "fleet/fedex/special-service-option/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/availability/v1/specialserviceoptions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT FindLocations
        WITH SOURCE_TOPIC "fleet/fedex/location/search"
        WITH DESTINATION_TOPIC "fleet/fedex/location/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/location/v1/locations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ValidateShipment
        WITH SOURCE_TOPIC "fleet/fedex/shipment/validate"
        WITH DESTINATION_TOPIC "fleet/fedex/shipment/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/ship/v1/shipments/packages/validate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateShipment
        WITH SOURCE_TOPIC "fleet/fedex/shipment/create"
        WITH DESTINATION_TOPIC "fleet/fedex/shipment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/ship/v1/shipments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetShipmentResults
        WITH SOURCE_TOPIC "fleet/fedex/shipment-results/get"
        WITH DESTINATION_TOPIC "fleet/fedex/shipment-results/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/ship/v1/shipments/results"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CancelShipment
        WITH SOURCE_TOPIC "fleet/fedex/shipment/cancel"
        WITH DESTINATION_TOPIC "fleet/fedex/shipment/cancel/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/ship/v1/shipments/cancel"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateTag
        WITH SOURCE_TOPIC "fleet/fedex/tag/create"
        WITH DESTINATION_TOPIC "fleet/fedex/tag/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/ship/v1/shipments/tag"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CancelTag
        WITH SOURCE_TOPIC "fleet/fedex/tag/cancel"
        WITH DESTINATION_TOPIC "fleet/fedex/tag/cancel/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/ship/v1/shipments/tag/cancel/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CheckPickupAvailability
        WITH SOURCE_TOPIC "fleet/fedex/pickup-availability/get"
        WITH DESTINATION_TOPIC "fleet/fedex/pickup-availability/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/pickup/v1/pickups/availabilities"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CreatePickup
        WITH SOURCE_TOPIC "fleet/fedex/pickup/create"
        WITH DESTINATION_TOPIC "fleet/fedex/pickup/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/pickup/v1/pickups"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CancelPickup
        WITH SOURCE_TOPIC "fleet/fedex/pickup/cancel"
        WITH DESTINATION_TOPIC "fleet/fedex/pickup/cancel/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/pickup/v1/pickups/cancel"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetRegulatoryDetails
        WITH SOURCE_TOPIC "fleet/fedex/regulatory/get"
        WITH DESTINATION_TOPIC "fleet/fedex/regulatory/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/globaltrade/v1/shipments/regulatorydetails/retrieve"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT AssociateTrackingNumbers
        WITH SOURCE_TOPIC "fleet/fedex/aiv-tracking-number/associate"
        WITH DESTINATION_TOPIC "fleet/fedex/aiv-tracking-number/associate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webhook/v1/subscriptions/trackingnumbers/association"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
            ADD "x-action" "{value.json.action}"
            ADD "x-type" "tracking"
        WITH BODY "{value.json.body}"
    ADD EVENT AssociateTrackingNumbersSync
        WITH SOURCE_TOPIC "fleet/fedex/aiv-tracking-number-sync/associate"
        WITH DESTINATION_TOPIC "fleet/fedex/aiv-tracking-number-sync/associate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webhook/v1/subscriptions/trackingnumbers/syncassociation"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
            ADD "X-Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetAssociationJobStatus
        WITH SOURCE_TOPIC "fleet/fedex/aiv-job-status/get"
        WITH DESTINATION_TOPIC "fleet/fedex/aiv-job-status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webhook/v1/subscriptions/trackingnumbers/jobstatus?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
    ADD EVENT GetAssociationJobDetails
        WITH SOURCE_TOPIC "fleet/fedex/aiv-job-details/get"
        WITH DESTINATION_TOPIC "fleet/fedex/aiv-job-details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webhook/v1/subscriptions/trackingnumbers/jobdetails?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
    ADD EVENT GetAccountSubscription
        WITH SOURCE_TOPIC "fleet/fedex/aiv-subscription/get"
        WITH DESTINATION_TOPIC "fleet/fedex/aiv-subscription/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webhook/v3/subscriptions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
    ADD EVENT UpdateAccountSubscription
        WITH SOURCE_TOPIC "fleet/fedex/aiv-subscription/update"
        WITH DESTINATION_TOPIC "fleet/fedex/aiv-subscription/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/webhook/v3/subscriptions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "x-locale" "en_US"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `TrackByTrackingNumber` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/fedex/track/get/response' &
mosquitto_pub -t 'fleet/fedex/track/get' -m '{"access_token": "<access_token>", "body": {}, "trans_id": "<trans_id>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Fed Ex Auth
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/fed-ex-auth

LoT connector for FedEx OAuth: get access tokens with client credentials or child credentials for the other FedEx Developer Portal connectors

Technical Preview

## Overview

Client-mode REST API connector for the FedEx Developer Portal APIs: OAuth 2.0 client credentials, tracking (tracking number, reference, TCN, multiple-piece shipments, proof of delivery documents, e-mail notifications), rates and transit times, address and postal code validation, service availability, location search, shipments and labels (purchase), cancel, return tags (purchase), pickups (purchase), Global Trade regulatory details, Advanced Integrated Visibility subscriptions (billed) and trade document upload; companion server connector for AIV tracking webhooks.

This is one of the templates in the FedEx Developer Portal REST API app (`fedex-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 client credentials (credentials in the form body, client\_secret\_post): GetToken posts grant\_type=client\_credentials\&client\_id\&client\_secret (application/x-www-form-urlencoded) to /oauth/token; GetTokenChild uses client\_pc\_credentials or csp\_credentials + child\_Key + child\_secret. Reply access\_token, token\_type bearer, expires\_in 3600, scope; no refresh token. FedExApi / FedExDocs events: Authorization: Bearer \<access\_token> and x-customer-transaction-id; FedExApi also x-locale en\_US. Every event sends User-Agent: Coreflux-Broker.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Fed Ex Auth connector | no |
| `BaseUrl` | string | Fed Ex Auth base URL without trailing slash (e.g. [https://apis.fedex.com](https://apis.fedex.com)) | yes |

`BASE_ADDRESS` default: `https://apis.fedex.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetToken` | POST | `/oauth/token` | `fleet/fedex/token/create` | `fleet/fedex/token/create/response` | `form` |
| `GetTokenChild` | POST | `/oauth/token` | `fleet/fedex/token-child/create` | `fleet/fedex/token-child/create/response` | `form` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode FED_EX_AUTH"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FedExAuth WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://apis.fedex.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetToken
        WITH SOURCE_TOPIC "fleet/fedex/token/create"
        WITH DESTINATION_TOPIC "fleet/fedex/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    ADD EVENT GetTokenChild
        WITH SOURCE_TOPIC "fleet/fedex/token-child/create"
        WITH DESTINATION_TOPIC "fleet/fedex/token-child/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetToken` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/fedex/token/create/response' &
mosquitto_pub -t 'fleet/fedex/token/create' -m '{"form": "<form>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Fed Ex Docs
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/fed-ex-docs

LoT connector for the FedEx document API: upload electronic trade documents and encoded document images from MQTT with a FedEx access token

Technical Preview

## Overview

Client-mode REST API connector for the FedEx Developer Portal APIs: OAuth 2.0 client credentials, tracking (tracking number, reference, TCN, multiple-piece shipments, proof of delivery documents, e-mail notifications), rates and transit times, address and postal code validation, service availability, location search, shipments and labels (purchase), cancel, return tags (purchase), pickups (purchase), Global Trade regulatory details, Advanced Integrated Visibility subscriptions (billed) and trade document upload; companion server connector for AIV tracking webhooks.

This is one of the templates in the FedEx Developer Portal REST API app (`fedex-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 client credentials (credentials in the form body, client\_secret\_post): GetToken posts grant\_type=client\_credentials\&client\_id\&client\_secret (application/x-www-form-urlencoded) to /oauth/token; GetTokenChild uses client\_pc\_credentials or csp\_credentials + child\_Key + child\_secret. Reply access\_token, token\_type bearer, expires\_in 3600, scope; no refresh token. FedExApi / FedExDocs events: Authorization: Bearer \<access\_token> and x-customer-transaction-id; FedExApi also x-locale en\_US. Every event sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Fed Ex Docs connector | no |
| `BaseUrl` | string | Fed Ex Docs base URL without trailing slash (e.g. [https://documentapi.prod.fedex.com](https://documentapi.prod.fedex.com)) | yes |

`BASE_ADDRESS` default: `https://documentapi.prod.fedex.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `UploadTradeDocuments` | POST | `/documents/v1/etds/encodedmultiupload` | `fleet/fedex/trade-document/upload` | `fleet/fedex/trade-document/upload/response` | `access_token`, `body`, `trans_id` |
| `UploadDocumentImage` | POST | `/documents/v1/lhsimages/encodedupload` | `fleet/fedex/document-image/upload` | `fleet/fedex/document-image/upload/response` | `access_token`, `body`, `trans_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode FED_EX_DOCS"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FedExDocs WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://documentapi.prod.fedex.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT UploadTradeDocuments
        WITH SOURCE_TOPIC "fleet/fedex/trade-document/upload"
        WITH DESTINATION_TOPIC "fleet/fedex/trade-document/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/documents/v1/etds/encodedmultiupload"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UploadDocumentImage
        WITH SOURCE_TOPIC "fleet/fedex/document-image/upload"
        WITH DESTINATION_TOPIC "fleet/fedex/document-image/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/documents/v1/lhsimages/encodedupload"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "x-customer-transaction-id" "{value.json.trans_id}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `UploadTradeDocuments` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/fedex/trade-document/upload/response' &
mosquitto_pub -t 'fleet/fedex/trade-document/upload' -m '{"access_token": "<access_token>", "body": {}, "trans_id": "<trans_id>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Firebase Cloud Messaging (HTTP v1)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/firebase-cloud-messaging

Connect Coreflux LoT to Firebase Cloud Messaging HTTP v1: send push notifications to a device token or topic and data-only messages for app sync

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Firebase Cloud Messaging HTTP v1 API](https://firebase.google.com/docs/reference/fcm/rest):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST messages:send (token/topic) | `POST /v1/projects/{project_id}/messages:send` | Notification to registration token or topic |
| POST data message (app sync) | `POST /v1/projects/{project_id}/messages:send` | Data-only `message.data` (same endpoint) |

Default `BASE_ADDRESS` is `https://fcm.googleapis.com`. Topics use `messaging/fcm/<object>/<verb>`.

> [!NOTE]
>
> Auth is **OAuth 2.0 Bearer** from a Google service account with scope `https://www.googleapis.com/auth/firebase.messaging`. Prefer Hub secrets `FCM_ACCESS_TOKEN` and project id `FCM_PROJECT_ID` (alias `FIREBASE_PROJECT_ID`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Firebase Cloud Messaging HTTP v1
# Auth: Authorization: Bearer {value.json.access_token}
# BASE_ADDRESS: https://fcm.googleapis.com

DEFINE CONNECTOR FirebaseCloudMessagingRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://fcm.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Sendmessage
        WITH SOURCE_TOPIC "messaging/fcm/message/send"
        WITH DESTINATION_TOPIC "messaging/fcm/message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/messages:send"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Senddatamessage
        WITH SOURCE_TOPIC "messaging/fcm/message/send-data"
        WITH DESTINATION_TOPIC "messaging/fcm/message/send-data/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/messages:send"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Sendmessage | POST | `/v1/projects/{project_id}/messages:send` | `messaging/fcm/message/send` | `messaging/fcm/message/send/response` |
| Senddatamessage | POST | `/v1/projects/{project_id}/messages:send` | `messaging/fcm/message/send-data` | `messaging/fcm/message/send-data/response` |

## Auth

1. Create a [Firebase / Google Cloud service account](https://firebase.google.com/docs/cloud-messaging/auth-server) with permission to use FCM (scope `https://www.googleapis.com/auth/firebase.messaging`).
2. Exchange a signed JWT for a short-lived access token at `https://oauth2.googleapis.com/token` (or use Application Default Credentials / `gcloud` offline). Store the token in Hub as `FCM_ACCESS_TOKEN`.
3. Set connector `BASE_ADDRESS` to `https://fcm.googleapis.com`.
4. Pass `access_token` and `project_id` on MQTT JSON payloads so the Authorization header and path resolve. Put the FCM `message` object (and optional `validateOnly`) in the same JSON — `{payload}` is the HTTP body.
5. Never commit service-account JSON, `GOOGLE_APPLICATION_CREDENTIALS` files, or live tokens.
6. Successful send returns **HTTP 200** with a `Message` including `name`. Use `validateOnly: true` for a dry run.

## Example payloads

**sendMessage (token notification):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "YOUR_FIREBASE_PROJECT_ID",
  "access_token": "YOUR_FCM_ACCESS_TOKEN",
  "message": {
    "token": "YOUR_DEVICE_REGISTRATION_TOKEN",
    "notification": {
      "title": "Coreflux alarm — Zone A",
      "body": "RMS exceeded limit on Zone A"
    }
  }
}
```

**sendMessage (topic):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "YOUR_FIREBASE_PROJECT_ID",
  "access_token": "YOUR_FCM_ACCESS_TOKEN",
  "message": {
    "topic": "plant-alarms",
    "notification": {
      "title": "Plant-wide alert",
      "body": "Line 3 stopped"
    }
  }
}
```

**sendDataMessage (app sync):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "YOUR_FIREBASE_PROJECT_ID",
  "access_token": "YOUR_FCM_ACCESS_TOKEN",
  "message": {
    "token": "YOUR_DEVICE_REGISTRATION_TOKEN",
    "data": {
      "device_id": "zone-a-vib-01",
      "metric": "vibration_rms",
      "value": "12.4"
    }
  }
}
```

**validateOnly dry-run:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "YOUR_FIREBASE_PROJECT_ID",
  "access_token": "YOUR_FCM_ACCESS_TOKEN",
  "validateOnly": true,
  "message": {
    "topic": "coreflux-alerts",
    "notification": { "title": "alert", "body": "validateOnly" }
  }
}
```

## Install

1. The template ships with the broker. List it with `-listTemplates` or fetch it from the Hub catalog.
2. Deploy with `-addConnector` from `FirebaseCloudMessagingRestApi.lot` (not `hub-metadata.lot`).

## See also

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Firebase Realtime Database
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/firebase-realtime-database

LoT connector for the Firebase Realtime Database: set device state, append events, merge fields and query the latest children at any path from MQTT

Technical Preview

## Overview

Client-mode REST API connectors for Firebase: write device state, append events, and query history in the Realtime Database, and upsert, merge, and query Cloud Firestore documents from MQTT.

This is one of the templates in the Firebase Realtime Database and Cloud Firestore REST API app (`firebase-realtime-database-and-cloud-firestore`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector). See [Firebase Realtime Database and Cloud Firestore](/latest/lot-language/routes/rest-api-apps/firebase-realtime-database-and-cloud-firestore) for the package overview.

## Auth

Bearer \{value.json.access\_token} on both connectors. RTDB: Google OAuth2 SA token (userinfo.email + firebase.database); alt ?access\_token= or Firebase ID token via ?auth=. Firestore: Google OAuth2 SA token (roles/datastore.user) or Firebase ID token (rules apply). Hub secret FIREBASE\_ACCESS\_TOKEN.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Firebase Realtime Database connector | no |
| `BaseUrl` | string | Firebase Realtime Database base URL without trailing slash (e.g. [https://YOUR\_DATABASE-default-rtdb.firebaseio.com](https://YOUR_DATABASE-default-rtdb.firebaseio.com)) | yes |

`BASE_ADDRESS` default: `https://YOUR_DATABASE-default-rtdb.firebaseio.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `SetDeviceState` | PUT | `/{value.json.path}.json` | `data/firebase/rtdb/state/set` | `data/firebase/rtdb/state/set/response` | `access_token`, `data`, `path` |
| `AppendEvent` | POST | `/{value.json.path}.json` | `data/firebase/rtdb/event/append` | `data/firebase/rtdb/event/append/response` | `access_token`, `data`, `path` |
| `UpdateFields` | PATCH | `/{value.json.path}.json` | `data/firebase/rtdb/fields/update` | `data/firebase/rtdb/fields/update/response` | `access_token`, `data`, `path` |
| `ReadPath` | GET | `/{value.json.path}.json` | `data/firebase/rtdb/path/get` | `data/firebase/rtdb/path/get/response` | `access_token`, `path` |
| `QueryLatest` | GET | `/{value.json.path}.json?orderBy={value.json.order_by}&limitToLast={value.json.limit}` | `data/firebase/rtdb/path/query` | `data/firebase/rtdb/path/query/response` | `access_token`, `limit`, `order_by`, `path` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode FIREBASE_REALTIME_DATABASE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FirebaseRealtimeDatabaseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DATABASE-default-rtdb.firebaseio.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SetDeviceState
        WITH SOURCE_TOPIC "data/firebase/rtdb/state/set"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/state/set/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.data}"
    ADD EVENT AppendEvent
        WITH SOURCE_TOPIC "data/firebase/rtdb/event/append"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/event/append/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.data}"
    ADD EVENT UpdateFields
        WITH SOURCE_TOPIC "data/firebase/rtdb/fields/update"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/fields/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.data}"
    ADD EVENT ReadPath
        WITH SOURCE_TOPIC "data/firebase/rtdb/path/get"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/path/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT QueryLatest
        WITH SOURCE_TOPIC "data/firebase/rtdb/path/query"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/path/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.path}.json?orderBy={value.json.order_by}&limitToLast={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `SetDeviceState` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'data/firebase/rtdb/state/set/response' &
mosquitto_pub -t 'data/firebase/rtdb/state/set' -m '{"access_token": "<access_token>", "data": "<data>", "path": "<path>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Firebase Realtime Database and Cloud Firestore
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/firebase-realtime-database-and-cloud-firestore

Connect Coreflux LoT to Firebase: write device state and query history in the Realtime Database, and upsert, merge and query Cloud Firestore documents

Technical Preview

## Overview

Firebase has two databases with different REST APIs and different hosts, so this package ships **two connectors** that you can deploy together or on their own:

* `FirebaseRealtimeDatabaseRestApi` talks to the [Realtime Database REST API](https://firebase.google.com/docs/database/rest/start) on `https://<database>.firebaseio.com`. Any path plus `.json` is an endpoint, and plain JSON goes in and out.
* `CloudFirestoreRestApi` talks to the [Cloud Firestore REST API](https://firebase.google.com/docs/firestore/use-rest-api) on `https://firestore.googleapis.com`. Documents use Firestore typed values.

### Realtime Database events

| Connector event | Method and endpoint | Notes |
| - | - | - |
| `SetDeviceState` | `PUT /{path}.json` | Write or replace the value at a path, such as `devices/press-01/state`. [Save data](https://firebase.google.com/docs/database/rest/save-data) |
| `AppendEvent` | `POST /{path}.json` | Append a child with a generated push key. Returns `{"name":"-P38..."}`. |
| `UpdateFields` | `PATCH /{path}.json` | Merge only the given children. |
| `ReadPath` | `GET /{path}.json` | Read the value at a path. |
| `QueryLatest` | `GET /{path}.json?orderBy=...&limitToLast=N` | Latest N children ordered by `$key` or an indexed child. [Retrieve data](https://firebase.google.com/docs/database/rest/retrieve-data) |

Topics use `data/firebase/rtdb/<object>/<verb>`.

### Cloud Firestore events

| Connector event | Method and endpoint | Notes |
| - | - | - |
| `UpsertDocument` | `PATCH /v1/projects/{p}/databases/(default)/documents/{document_path}` | Create or replace a document. [patch](https://firebase.google.com/docs/firestore/reference/rest/v1/projects.databases.documents/patch) |
| `MergeFields` | Same, with `?updateMask.fieldPaths=...` | Update only the listed fields and keep the rest. |
| `CreateDocument` | `POST .../documents/{collection}` | New document with a generated ID. [createDocument](https://firebase.google.com/docs/firestore/reference/rest/v1/projects.databases.documents/createDocument) |
| `GetDocument` | `GET .../documents/{document_path}` | Read one document. |
| `ListDocuments` | `GET .../documents/{collection}?pageSize=N` | List a collection page. |
| `RunQuery` | `POST .../documents:runQuery` | Structured query, such as all events for one device. [runQuery](https://firebase.google.com/docs/firestore/reference/rest/v1/projects.databases.documents/runQuery) |

Topics use `data/firebase/firestore/<object>/<verb>`. Replies for both connectors arrive on `<topic>/response`.

## Auth

Both connectors send `Authorization: Bearer {value.json.access_token}`. Mint the token outside the connector (a Python action, edge service, or SDK) and keep the service account key or token in Hub secrets, for example `FIREBASE_ACCESS_TOKEN`. Never commit keys.

* **Realtime Database:** a Google OAuth2 access token from a service account with scopes `https://www.googleapis.com/auth/userinfo.email` and `https://www.googleapis.com/auth/firebase.database`. The API also accepts the token as `?access_token=`, and a Firebase Auth ID token as `?auth=<ID_TOKEN>`; edit the endpoints if you use those. See [Authenticate REST requests](https://firebase.google.com/docs/database/rest/auth).
* **Cloud Firestore:** a Google OAuth2 access token for a service account with a Datastore role such as `roles/datastore.user` (scope `https://www.googleapis.com/auth/datastore` or `cloud-platform`). Service account tokens bypass security rules. A Firebase Auth ID token also works and is checked against your rules.

Access tokens expire after about an hour, so refresh them before they lapse.

## Basic Syntax

### Realtime Database

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FirebaseRealtimeDatabaseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DATABASE-default-rtdb.firebaseio.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SetDeviceState
        WITH SOURCE_TOPIC "data/firebase/rtdb/state/set"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/state/set/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.data}"
    ADD EVENT AppendEvent
        WITH SOURCE_TOPIC "data/firebase/rtdb/event/append"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/event/append/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.data}"
    ADD EVENT UpdateFields
        WITH SOURCE_TOPIC "data/firebase/rtdb/fields/update"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/fields/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.data}"
    ADD EVENT ReadPath
        WITH SOURCE_TOPIC "data/firebase/rtdb/path/get"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/path/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.path}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT QueryLatest
        # order_by must be URL-encoded and quoted, e.g. %22%24key%22 ("$key") or %22ts%22 ("ts", needs .indexOn rule)
        WITH SOURCE_TOPIC "data/firebase/rtdb/path/query"
        WITH DESTINATION_TOPIC "data/firebase/rtdb/path/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.path}.json?orderBy={value.json.order_by}&limitToLast={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

### Cloud Firestore

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CloudFirestoreRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://firestore.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT UpsertDocument
        WITH SOURCE_TOPIC "data/firebase/firestore/document/upsert"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/upsert/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.document}"
    ADD EVENT MergeFields
        WITH SOURCE_TOPIC "data/firebase/firestore/document/merge"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/merge/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}?{value.json.update_mask}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.document}"
    ADD EVENT CreateDocument
        WITH SOURCE_TOPIC "data/firebase/firestore/document/create"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.collection}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.document}"
    ADD EVENT GetDocument
        WITH SOURCE_TOPIC "data/firebase/firestore/document/get"
        WITH DESTINATION_TOPIC "data/firebase/firestore/document/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.document_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListDocuments
        WITH SOURCE_TOPIC "data/firebase/firestore/documents/list"
        WITH DESTINATION_TOPIC "data/firebase/firestore/documents/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents/{value.json.collection}?pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RunQuery
        WITH SOURCE_TOPIC "data/firebase/firestore/documents/query"
        WITH DESTINATION_TOPIC "data/firebase/firestore/documents/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/databases/(default)/documents:runQuery"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.query}"
```

Set `BASE_ADDRESS` on the Realtime Database connector to your instance URL: `https://<database>-default-rtdb.firebaseio.com` for US instances, or `https://<database>-default-rtdb.<region>.firebasedatabase.app` elsewhere. The Firestore connector targets the `(default)` database; edit the endpoints for a named database.

## Payload examples

### Realtime Database

Set device state, with a server-side timestamp, on `data/firebase/rtdb/state/set`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "path": "devices/press-01/state", "data": {"state": "RUN", "temp": 21.5, "lastSeen": {".sv": "timestamp"}}}
```

Append an event on `data/firebase/rtdb/event/append`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "path": "devices/press-01/events", "data": {"ts": 1791155235, "code": "E2"}}
```

Merge one field on `data/firebase/rtdb/fields/update`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "path": "devices/press-01/state", "data": {"state": "IDLE"}}
```

Latest two events by `ts` on `data/firebase/rtdb/path/query` (`order_by` is URL-encoded and quoted, here `"ts"`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "path": "devices/press-01/events", "order_by": "%22ts%22", "limit": 2}
```

Ordering by a child needs an index rule such as `".indexOn": ["ts"]`; ordering by `%22%24key%22` (`"$key"`) needs none.

### Cloud Firestore

Upsert a device document on `data/firebase/firestore/document/upsert`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "project_id": "my-project", "document_path": "devices/press-01",
 "document": {"fields": {"state": {"stringValue": "RUN"}, "temp": {"doubleValue": 21.5}, "count": {"integerValue": "42"}}}}
```

Merge two fields on `data/firebase/firestore/document/merge`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "project_id": "my-project", "document_path": "devices/press-01",
 "update_mask": "updateMask.fieldPaths=state&updateMask.fieldPaths=lastSeen",
 "document": {"fields": {"state": {"stringValue": "IDLE"}, "lastSeen": {"timestampValue": "2026-10-05T00:10:00Z"}}}}
```

Create an event document on `data/firebase/firestore/document/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "project_id": "my-project", "collection": "events",
 "document": {"fields": {"deviceId": {"stringValue": "press-01"}, "ts": {"integerValue": "1791155235"}}}}
```

Query events for one device on `data/firebase/firestore/documents/query`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "ya29....", "project_id": "my-project",
 "query": {"structuredQuery": {"from": [{"collectionId": "events"}],
   "where": {"fieldFilter": {"field": {"fieldPath": "deviceId"}, "op": "EQUAL", "value": {"stringValue": "press-01"}}}, "limit": 5}}}
```

Firestore integers are strings (`"integerValue": "42"`), and timestamps are RFC 3339 (`timestampValue`).

## Errors and limits

* **Realtime Database:** `401 {"error":"Permission denied"}` means a missing or bad token or a rules denial. `404 {"error":"404 Not Found"}` usually means the `BASE_ADDRESS` instance URL is wrong. Add `print=silent` to write endpoints to get `204 No Content` instead of the echoed data.
* **Cloud Firestore:** `401 UNAUTHENTICATED` (bad or expired token), `403 PERMISSION_DENIED` (missing role, rules, or API not enabled on the project), `404 NOT_FOUND`, `400 INVALID_ARGUMENT` (bad typed value or mask). `MergeFields` needs a non-empty `update_mask`; send an upsert instead if you want to replace the whole document.
* Firestore writes to a single document are limited to about one per second sustained; spread high-rate telemetry across documents or use the Realtime Database.
* Realtime Database streaming (Server-Sent Events) is not covered by these client connectors.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app catalog](/latest/lot-language/routes/rest-api-apps/index)
* [Firebase Cloud Messaging](/latest/lot-language/routes/rest-api-apps/firebase-cloud-messaging)


# Flow Fuse Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/flow-fuse-api

LoT connector for the FlowFuse API: manage teams, applications and hosted instances, start or stop instances, read logs, take snapshots and list devices

Technical Preview

## Overview

Client-mode REST API connectors for Node-RED and FlowFuse: read and deploy Node-RED flows through the Admin API, start and stop flows, read context, manage node modules, send MQTT data to your own HTTP In endpoints, and manage FlowFuse teams, applications, hosted instances, snapshots and devices from MQTT.

This is one of the templates in the Node-RED (Admin API, HTTP In nodes) and FlowFuse REST API app (`node-red-and-flowfuse`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Auth headers used by the template: `Authorization: Bearer {value.json.token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Flow Fuse Api connector | no |
| `BaseUrl` | string | Flow Fuse Api base URL without trailing slash (e.g. [https://app.flowfuse.com](https://app.flowfuse.com)) | yes |

`BASE_ADDRESS` default: `https://app.flowfuse.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetPlatformSettings` | GET | `/api/v1/settings/` | `historian/flowfuse/platform-settings/get` | `historian/flowfuse/platform-settings/get/response` | none |
| `GetCurrentUser` | GET | `/api/v1/user/` | `historian/flowfuse/user/get` | `historian/flowfuse/user/get/response` | `token` |
| `ListUserTeams` | GET | `/api/v1/user/teams` | `historian/flowfuse/team/list` | `historian/flowfuse/team/list/response` | `token` |
| `GetTeam` | GET | `/api/v1/teams/{value.json.teamId}` | `historian/flowfuse/team/get` | `historian/flowfuse/team/get/response` | `teamId`, `token` |
| `GetTeamBySlug` | GET | `/api/v1/teams/slug/{value.json.slug}` | `historian/flowfuse/team-slug/get` | `historian/flowfuse/team-slug/get/response` | `slug`, `token` |
| `ListTeamApplications` | GET | `/api/v1/teams/{value.json.teamId}/applications` | `historian/flowfuse/application/list` | `historian/flowfuse/application/list/response` | `teamId`, `token` |
| `ListTeamApplicationsStatus` | GET | `/api/v1/teams/{value.json.teamId}/applications/status` | `historian/flowfuse/application-status/list` | `historian/flowfuse/application-status/list/response` | `teamId`, `token` |
| `GetApplication` | GET | `/api/v1/applications/{value.json.applicationId}` | `historian/flowfuse/application/get` | `historian/flowfuse/application/get/response` | `applicationId`, `token` |
| `ListApplicationInstances` | GET | `/api/v1/applications/{value.json.applicationId}/instances` | `historian/flowfuse/instance/list` | `historian/flowfuse/instance/list/response` | `applicationId`, `token` |
| `ListApplicationInstancesStatus` | GET | `/api/v1/applications/{value.json.applicationId}/instances/status` | `historian/flowfuse/instance-status/list` | `historian/flowfuse/instance-status/list/response` | `applicationId`, `token` |
| `GetInstance` | GET | `/api/v1/projects/{value.json.id}` | `historian/flowfuse/instance/get` | `historian/flowfuse/instance/get/response` | `id`, `token` |
| `GetInstanceStatus` | GET | `/api/v1/projects/{value.json.id}/status` | `historian/flowfuse/instance-status/get` | `historian/flowfuse/instance-status/get/response` | `id`, `token` |
| `StartInstance` | POST | `/api/v1/projects/{value.json.id}/actions/start` | `historian/flowfuse/instance/start` | `historian/flowfuse/instance/start/response` | `id`, `token` |
| `StopInstance` | POST | `/api/v1/projects/{value.json.id}/actions/stop` | `historian/flowfuse/instance/stop` | `historian/flowfuse/instance/stop/response` | `id`, `token` |
| `RestartInstance` | POST | `/api/v1/projects/{value.json.id}/actions/restart` | `historian/flowfuse/instance/restart` | `historian/flowfuse/instance/restart/response` | `id`, `token` |
| `SuspendInstance` | POST | `/api/v1/projects/{value.json.id}/actions/suspend` | `historian/flowfuse/instance/suspend` | `historian/flowfuse/instance/suspend/response` | `id`, `token` |
| `RollbackInstance` | POST | `/api/v1/projects/{value.json.id}/actions/rollback` | `historian/flowfuse/instance/rollback` | `historian/flowfuse/instance/rollback/response` | `body`, `id`, `token` |
| `GetInstanceLogs` | GET | `/api/v1/projects/{value.json.id}/logs` | `historian/flowfuse/instance-log/list` | `historian/flowfuse/instance-log/list/response` | `id`, `token` |
| `ImportInstanceFlows` | POST | `/api/v1/projects/{value.json.id}/import` | `historian/flowfuse/instance-flows/import` | `historian/flowfuse/instance-flows/import/response` | `body`, `id`, `token` |
| `ListInstanceSnapshots` | GET | `/api/v1/projects/{value.json.id}/snapshots/` | `historian/flowfuse/snapshot/list` | `historian/flowfuse/snapshot/list/response` | `id`, `token` |
| `CreateInstanceSnapshot` | POST | `/api/v1/projects/{value.json.id}/snapshots/` | `historian/flowfuse/snapshot/create` | `historian/flowfuse/snapshot/create/response` | `body`, `id`, `token` |
| `ListTeamDevices` | GET | `/api/v1/teams/{value.json.teamId}/devices/` | `historian/flowfuse/device/list` | `historian/flowfuse/device/list/response` | `teamId`, `token` |
| `ListApplicationDevices` | GET | `/api/v1/applications/{value.json.applicationId}/devices` | `historian/flowfuse/application-device/list` | `historian/flowfuse/application-device/list/response` | `applicationId`, `token` |
| `GetDevice` | GET | `/api/v1/devices/{value.json.deviceId}` | `historian/flowfuse/device/get` | `historian/flowfuse/device/get/response` | `deviceId`, `token` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode FLOW_FUSE_API"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FlowFuseApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://app.flowfuse.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetPlatformSettings
        WITH SOURCE_TOPIC "historian/flowfuse/platform-settings/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/platform-settings/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/settings/"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetCurrentUser
        WITH SOURCE_TOPIC "historian/flowfuse/user/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/user/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListUserTeams
        WITH SOURCE_TOPIC "historian/flowfuse/team/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/team/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/user/teams"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetTeam
        WITH SOURCE_TOPIC "historian/flowfuse/team/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/team/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/teams/{value.json.teamId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetTeamBySlug
        WITH SOURCE_TOPIC "historian/flowfuse/team-slug/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/team-slug/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/teams/slug/{value.json.slug}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListTeamApplications
        WITH SOURCE_TOPIC "historian/flowfuse/application/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/application/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/teams/{value.json.teamId}/applications"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListTeamApplicationsStatus
        WITH SOURCE_TOPIC "historian/flowfuse/application-status/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/application-status/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/teams/{value.json.teamId}/applications/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetApplication
        WITH SOURCE_TOPIC "historian/flowfuse/application/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/application/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/applications/{value.json.applicationId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListApplicationInstances
        WITH SOURCE_TOPIC "historian/flowfuse/instance/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/applications/{value.json.applicationId}/instances"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListApplicationInstancesStatus
        WITH SOURCE_TOPIC "historian/flowfuse/instance-status/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance-status/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/applications/{value.json.applicationId}/instances/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetInstance
        WITH SOURCE_TOPIC "historian/flowfuse/instance/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetInstanceStatus
        WITH SOURCE_TOPIC "historian/flowfuse/instance-status/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance-status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT StartInstance
        WITH SOURCE_TOPIC "historian/flowfuse/instance/start"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/actions/start"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{}"
    ADD EVENT StopInstance
        WITH SOURCE_TOPIC "historian/flowfuse/instance/stop"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance/stop/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/actions/stop"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{}"
    ADD EVENT RestartInstance
        WITH SOURCE_TOPIC "historian/flowfuse/instance/restart"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance/restart/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/actions/restart"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{}"
    ADD EVENT SuspendInstance
        WITH SOURCE_TOPIC "historian/flowfuse/instance/suspend"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance/suspend/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/actions/suspend"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{}"
    ADD EVENT RollbackInstance
        WITH SOURCE_TOPIC "historian/flowfuse/instance/rollback"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance/rollback/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/actions/rollback"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetInstanceLogs
        WITH SOURCE_TOPIC "historian/flowfuse/instance-log/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance-log/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/logs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ImportInstanceFlows
        WITH SOURCE_TOPIC "historian/flowfuse/instance-flows/import"
        WITH DESTINATION_TOPIC "historian/flowfuse/instance-flows/import/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/import"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListInstanceSnapshots
        WITH SOURCE_TOPIC "historian/flowfuse/snapshot/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/snapshot/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/snapshots/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT CreateInstanceSnapshot
        WITH SOURCE_TOPIC "historian/flowfuse/snapshot/create"
        WITH DESTINATION_TOPIC "historian/flowfuse/snapshot/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/projects/{value.json.id}/snapshots/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListTeamDevices
        WITH SOURCE_TOPIC "historian/flowfuse/device/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/teams/{value.json.teamId}/devices/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListApplicationDevices
        WITH SOURCE_TOPIC "historian/flowfuse/application-device/list"
        WITH DESTINATION_TOPIC "historian/flowfuse/application-device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/applications/{value.json.applicationId}/devices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "historian/flowfuse/device/get"
        WITH DESTINATION_TOPIC "historian/flowfuse/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/devices/{value.json.deviceId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetPlatformSettings` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/flowfuse/platform-settings/get/response' &
mosquitto_pub -t 'historian/flowfuse/platform-settings/get' -m '{}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Fracttal One Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/fracttal-one-api

Connect Coreflux LoT to Fracttal One CMMS: create work requests and work orders from alarms, update status and notes, manage assets, meters and meter readings

Technical Preview

## Overview

Client-mode REST API connector for Fracttal One CMMS: create work requests from alarms, turn them into pending tasks and work orders, update work order status and notes or cancel them, read and update assets, create meters and push meter readings, with OAuth 2.0 client credentials.

This is one of the templates in the Fracttal One REST API app (`fracttal-one`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 client credentials (queue hint 'API key + secret' refers to the older Hawk scheme, which needs a per-request MAC and is not used). GetToken / RefreshToken: Basic base64(key:secret) + form body to [https://one.fracttal.com/oauth/token](https://one.fracttal.com/oauth/token); tokens last 7200 s. API events: Authorization: Bearer \<access\_token> from payload. Every event also sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Fracttal One Api connector | no |
| `BaseUrl` | string | Fracttal One Api base URL without trailing slash (e.g. [https://app.fracttal.com](https://app.fracttal.com)) | yes |

`BASE_ADDRESS` default: `https://app.fracttal.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ListAssets` | GET | `/api/items/?{value.json.query}` | `cmms/fracttal/asset/list` | `cmms/fracttal/asset/list/response` | `access_token`, `query` |
| `GetAsset` | GET | `/api/items/{value.json.code}` | `cmms/fracttal/asset/get` | `cmms/fracttal/asset/get/response` | `access_token`, `code` |
| `UpdateAsset` | PUT | `/api/items/{value.json.code}` | `cmms/fracttal/asset/update` | `cmms/fracttal/asset/update/response` | `access_token`, `body`, `code` |
| `ListMeters` | GET | `/api/meters_list/?{value.json.query}` | `cmms/fracttal/meter/list` | `cmms/fracttal/meter/list/response` | `access_token`, `query` |
| `ListMeterReadings` | GET | `/api/meters_reading_list/?{value.json.query}` | `cmms/fracttal/meter-reading/list` | `cmms/fracttal/meter-reading/list/response` | `access_token`, `query` |
| `CreateMeter` | POST | `/api/meters` | `cmms/fracttal/meter/create` | `cmms/fracttal/meter/create/response` | `access_token`, `body` |
| `AddMeterReading` | PUT | `/api/meter_reading/{value.json.code}` | `cmms/fracttal/meter-reading/create` | `cmms/fracttal/meter-reading/create/response` | `access_token`, `body`, `code` |
| `ListWorkRequests` | GET | `/api/work_requests?{value.json.query}` | `cmms/fracttal/work-request/list` | `cmms/fracttal/work-request/list/response` | `access_token`, `query` |
| `GetWorkRequest` | GET | `/api/work_requests/{value.json.code}` | `cmms/fracttal/work-request/get` | `cmms/fracttal/work-request/get/response` | `access_token`, `code` |
| `ListWorkRequestStatusChanges` | GET | `/api/work_requests_status/?{value.json.query}` | `cmms/fracttal/work-request-status/list` | `cmms/fracttal/work-request-status/list/response` | `access_token`, `query` |
| `CreateWorkRequest` | POST | `/api/work_requests` | `cmms/fracttal/work-request/create` | `cmms/fracttal/work-request/create/response` | `access_token`, `body` |
| `UpdateWorkRequestData` | PUT | `/api/work_requests_data/{value.json.code}` | `cmms/fracttal/work-request/update` | `cmms/fracttal/work-request/update/response` | `access_token`, `body`, `code` |
| `CreateTaskFromWorkRequest` | POST | `/api/tasks_from_work_request/` | `cmms/fracttal/work-request/to-task` | `cmms/fracttal/work-request/to-task/response` | `access_token`, `body` |
| `CreateUnscheduledTask` | POST | `/api/tasks_nonscheduled` | `cmms/fracttal/task/create-unscheduled` | `cmms/fracttal/task/create-unscheduled/response` | `access_token`, `body` |
| `ListWorkOrders` | GET | `/api/work_orders?{value.json.query}` | `cmms/fracttal/work-order/list` | `cmms/fracttal/work-order/list/response` | `access_token`, `query` |
| `GetWorkOrder` | GET | `/api/work_orders/{value.json.folio}` | `cmms/fracttal/work-order/get` | `cmms/fracttal/work-order/get/response` | `access_token`, `folio` |
| `CreateWorkOrder` | POST | `/api/work_orders` | `cmms/fracttal/work-order/create` | `cmms/fracttal/work-order/create/response` | `access_token`, `body` |
| `UpdateWorkOrderStatus` | PUT | `/api/work_order_change_status/{value.json.folio}` | `cmms/fracttal/work-order/status` | `cmms/fracttal/work-order/status/response` | `access_token`, `body`, `folio` |
| `UpdateWorkOrderNote` | PUT | `/api/work_orders/{value.json.folio}` | `cmms/fracttal/work-order/note` | `cmms/fracttal/work-order/note/response` | `access_token`, `body`, `folio` |
| `CancelWorkOrder` | PUT | `/api/work_order_cancel?folio={value.json.folio}` | `cmms/fracttal/work-order/cancel` | `cmms/fracttal/work-order/cancel/response` | `access_token`, `body`, `folio` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode FRACTTAL_ONE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FracttalOneApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://app.fracttal.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListAssets
        WITH SOURCE_TOPIC "cmms/fracttal/asset/list"
        WITH DESTINATION_TOPIC "cmms/fracttal/asset/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/items/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetAsset
        WITH SOURCE_TOPIC "cmms/fracttal/asset/get"
        WITH DESTINATION_TOPIC "cmms/fracttal/asset/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/items/{value.json.code}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UpdateAsset
        WITH SOURCE_TOPIC "cmms/fracttal/asset/update"
        WITH DESTINATION_TOPIC "cmms/fracttal/asset/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/items/{value.json.code}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListMeters
        WITH SOURCE_TOPIC "cmms/fracttal/meter/list"
        WITH DESTINATION_TOPIC "cmms/fracttal/meter/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/meters_list/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListMeterReadings
        WITH SOURCE_TOPIC "cmms/fracttal/meter-reading/list"
        WITH DESTINATION_TOPIC "cmms/fracttal/meter-reading/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/meters_reading_list/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateMeter
        WITH SOURCE_TOPIC "cmms/fracttal/meter/create"
        WITH DESTINATION_TOPIC "cmms/fracttal/meter/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/meters"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT AddMeterReading
        WITH SOURCE_TOPIC "cmms/fracttal/meter-reading/create"
        WITH DESTINATION_TOPIC "cmms/fracttal/meter-reading/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/meter_reading/{value.json.code}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListWorkRequests
        WITH SOURCE_TOPIC "cmms/fracttal/work-request/list"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-request/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/work_requests?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetWorkRequest
        WITH SOURCE_TOPIC "cmms/fracttal/work-request/get"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-request/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/work_requests/{value.json.code}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListWorkRequestStatusChanges
        WITH SOURCE_TOPIC "cmms/fracttal/work-request-status/list"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-request-status/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/work_requests_status/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateWorkRequest
        WITH SOURCE_TOPIC "cmms/fracttal/work-request/create"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-request/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/work_requests"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateWorkRequestData
        WITH SOURCE_TOPIC "cmms/fracttal/work-request/update"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-request/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/work_requests_data/{value.json.code}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateTaskFromWorkRequest
        WITH SOURCE_TOPIC "cmms/fracttal/work-request/to-task"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-request/to-task/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/tasks_from_work_request/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateUnscheduledTask
        WITH SOURCE_TOPIC "cmms/fracttal/task/create-unscheduled"
        WITH DESTINATION_TOPIC "cmms/fracttal/task/create-unscheduled/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/tasks_nonscheduled"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListWorkOrders
        WITH SOURCE_TOPIC "cmms/fracttal/work-order/list"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-order/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/work_orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetWorkOrder
        WITH SOURCE_TOPIC "cmms/fracttal/work-order/get"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/work_orders/{value.json.folio}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateWorkOrder
        WITH SOURCE_TOPIC "cmms/fracttal/work-order/create"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-order/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/work_orders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateWorkOrderStatus
        WITH SOURCE_TOPIC "cmms/fracttal/work-order/status"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-order/status/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/work_order_change_status/{value.json.folio}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateWorkOrderNote
        WITH SOURCE_TOPIC "cmms/fracttal/work-order/note"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-order/note/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/work_orders/{value.json.folio}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CancelWorkOrder
        WITH SOURCE_TOPIC "cmms/fracttal/work-order/cancel"
        WITH DESTINATION_TOPIC "cmms/fracttal/work-order/cancel/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/work_order_cancel?folio={value.json.folio}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ListAssets` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'cmms/fracttal/asset/list/response' &
mosquitto_pub -t 'cmms/fracttal/asset/list' -m '{"access_token": "<access_token>", "query": "<query>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Freshdesk and Freshservice REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/freshdesk-and-freshservice

Client-mode REST API connector for Freshdesk tickets and Freshservice assets

Technical Preview

## Overview

Client-mode REST API connector for Freshdesk tickets and Freshservice assets. `BASE_ADDRESS` defaults to `https://YOUR_DOMAIN.freshdesk.com`. Auth: **Basic (API key as username, password X) or Bearer**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

Basic (API key as username, password X) or Bearer. Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR FreshdeskAndFreshserviceRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DOMAIN.freshdesk.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Prefer Basic: WITH USERNAME "{value.json.api_key_or_literal}" / WITH PASSWORD "X"
        #   or WITH USERNAME GET SECRET "FRESHDESK_API_KEY" / WITH PASSWORD "X"
        # Or OAuth/Bearer via Authorization header below ({value.json.api_key}).
    ADD EVENT Listtickets
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Listtickets"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Listtickets"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Createticket
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Createticket"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Createticket"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/tickets"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Getticket
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Getticket"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Getticket"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/freshdesk-and-freshservice/request/...`; responses on `integrations/freshdesk-and-freshservice/response/...`.

## Template reference

Generated from the shipped broker template `freshdesk-and-freshservice` (`-connectorCode FRESHDESK_AND_FRESHSERVICE`). It lists every event the template defines.

### Auth

Basic (API key as username, password X) or Bearer

Auth headers used by the template: `Authorization: Bearer {value.json.api_key}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Freshdesk and Freshservice connector | no |
| `BaseUrl` | string | Freshdesk and Freshservice base URL without trailing slash (e.g. [https://YOUR\_DOMAIN.freshdesk.com](https://YOUR_DOMAIN.freshdesk.com)) | yes |

`BASE_ADDRESS` default: `https://YOUR_DOMAIN.freshdesk.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listtickets` | GET | `/api/v2/tickets` | `integrations/freshdesk-and-freshservice/request/Listtickets` | `integrations/freshdesk-and-freshservice/response/Listtickets` | `api_key` |
| `Createticket` | POST | `/api/v2/tickets` | `integrations/freshdesk-and-freshservice/request/Createticket` | `integrations/freshdesk-and-freshservice/response/Createticket` | `api_key`, `body` |
| `Getticket` | GET | `/api/v2/tickets/{value.json.id}` | `integrations/freshdesk-and-freshservice/request/Getticket` | `integrations/freshdesk-and-freshservice/response/Getticket` | `api_key`, `id` |
| `Updateticket` | PUT | `/api/v2/tickets/{value.json.id}` | `integrations/freshdesk-and-freshservice/request/Updateticket` | `integrations/freshdesk-and-freshservice/response/Updateticket` | `api_key`, `body`, `id` |
| `Filtertickets` | GET | `/api/v2/tickets?filter={value.json.filter}` | `integrations/freshdesk-and-freshservice/request/Filtertickets` | `integrations/freshdesk-and-freshservice/response/Filtertickets` | `api_key`, `filter` |
| `Listcontacts` | GET | `/api/v2/contacts` | `integrations/freshdesk-and-freshservice/request/Listcontacts` | `integrations/freshdesk-and-freshservice/response/Listcontacts` | `api_key` |
| `Addticketnote` | POST | `/api/v2/tickets/{value.json.id}/notes` | `integrations/freshdesk-and-freshservice/request/Addticketnote` | `integrations/freshdesk-and-freshservice/response/Addticketnote` | `api_key`, `body`, `id` |
| `Createfreshserviceasset` | POST | `/api/v2/assets` | `integrations/freshdesk-and-freshservice/request/Createfreshserviceasset` | `integrations/freshdesk-and-freshservice/response/Createfreshserviceasset` | `api_key`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode FRESHDESK_AND_FRESHSERVICE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FreshdeskAndFreshserviceRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DOMAIN.freshdesk.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listtickets
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Listtickets"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Listtickets"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Createticket
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Createticket"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Createticket"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/tickets"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getticket
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Getticket"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Getticket"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Updateticket
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Updateticket"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Updateticket"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v2/tickets/{value.json.id}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT Filtertickets
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Filtertickets"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Filtertickets"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets?filter={value.json.filter}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Listcontacts
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Listcontacts"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Listcontacts"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/contacts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Addticketnote
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Addticketnote"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Addticketnote"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/tickets/{value.json.id}/notes"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT Createfreshserviceasset
        WITH SOURCE_TOPIC "integrations/freshdesk-and-freshservice/request/Createfreshserviceasset"
        WITH DESTINATION_TOPIC "integrations/freshdesk-and-freshservice/response/Createfreshserviceasset"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/assets"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listtickets` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/freshdesk-and-freshservice/response/Listtickets' &
mosquitto_pub -t 'integrations/freshdesk-and-freshservice/request/Listtickets' -m '{"api_key": "<api_key>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# Fronius Solar API (local)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/fronius-solar-api

Read local Fronius Solar API V1 data in LoT: power flow, inverter, smart meter, battery and Ohmpilot realtime values, device info and archive data

Technical Preview

## Overview

Fronius inverters (GEN24 Plus, Tauro, Verto) and the Fronius Datamanager 2.0 / Hybridmanager (SnapINverter, Symo Hybrid) serve the **Fronius Solar API V1**: a read-only JSON API on the plant LAN at `http://<device-ip>/solar_api/v1/`. It is documented in the [Fronius Solar API V1 operating instructions](https://www.fronius.com/en/help-center/solar-energy/products/monitoring-control/solutions/open-interfaces/fronius-solar-api-json-) and Fronius ships an OpenAPI 3.0 file for GEN24 / Tauro / Verto.

The **FroniusSolarApi** connector maps 17 MQTT topics onto that API. Typical uses are putting live PV, grid, load and battery power on the broker every few seconds, feeding smart-meter values into energy dashboards and load control, and alarming on inverter status and error codes, all without the Solar.web cloud. Each event publishes the device reply on `<topic>/response`.

| Event | Topic | Request | Platforms | Use |
| - | - | - | - | - |
| `GetApiVersion` | `energy/fronius/api-version/get` | `GET /solar_api/GetAPIVersion.cgi` | Datamanager, Hybrid, GEN24/Tauro/Verto | Highest API version, BaseURL and CompatibilityRange; use as a reachability check |
| `GetInverterRealtimeSystem` | `energy/fronius/inverter-realtime/system/get` | `GET /solar_api/v1/GetInverterRealtimeData.cgi?Scope=System` | Datamanager, Hybrid, GEN24/Tauro/Verto | Whole system (CumulationInverterData): PAC, DAY / YEAR / TOTAL\_ENERGY per inverter |
| `GetInverterRealtimeDevice` | `energy/fronius/inverter-realtime/device/get` | `GET /solar_api/v1/GetInverterRealtimeData.cgi?Scope=Device&DeviceId={device_id}&DataCollection={collection}` | Datamanager, Hybrid, GEN24/Tauro/Verto | One inverter: CommonInverterData (PAC, UAC, IAC, FAC, UDC, IDC, energies, DeviceStatus), CumulationInverterData, 3PInverterData (per phase), MinMaxInverterData (not Hybrid / GEN24) |
| `GetInverterInfo` | `energy/fronius/inverter-info/get` | `GET /solar_api/v1/GetInverterInfo.cgi` | Datamanager, Hybrid, GEN24/Tauro/Verto | All inverters: device type, PV power, custom name, serial, StatusCode, ErrorCode, Show |
| `GetActiveDeviceInfo` | `energy/fronius/active-device/get` | `GET /solar_api/v1/GetActiveDeviceInfo.cgi?DeviceClass={device_class}` | Datamanager, Hybrid, GEN24/Tauro/Verto | Devices currently online for a class: Inverter, Storage, Ohmpilot, SensorCard, StringControl, Meter or System (all classes) |
| `GetPowerFlowRealtime` | `energy/fronius/power-flow/get` | `GET /solar_api/v1/GetPowerFlowRealtimeData.fcgi` | Datamanager, Hybrid, GEN24/Tauro/Verto | Site power flow: P\_PV, P\_Grid (+ import / - export), P\_Load, P\_Akku, SOC, rel\_Autonomy, rel\_SelfConsumption, energy counters, Mode |
| `GetMeterRealtimeSystem` | `energy/fronius/meter-realtime/system/get` | `GET /solar_api/v1/GetMeterRealtimeData.cgi?Scope=System` | Datamanager, Hybrid, GEN24/Tauro/Verto | All smart meters: per-phase voltage, current, active / reactive / apparent power, power factor, frequency, import / export energy, Meter\_Location\_Current |
| `GetMeterRealtimeDevice` | `energy/fronius/meter-realtime/device/get` | `GET /solar_api/v1/GetMeterRealtimeData.cgi?Scope=Device&DeviceId={device_id}` | Datamanager, Hybrid, GEN24/Tauro/Verto | One smart meter (DeviceId 0 = primary meter on most sites) |
| `GetStorageRealtimeSystem` | `energy/fronius/storage-realtime/system/get` | `GET /solar_api/v1/GetStorageRealtimeData.cgi?Scope=System` | Datamanager, Hybrid, GEN24/Tauro/Verto | All batteries: StateOfCharge\_Relative, Capacity\_Maximum, Current\_DC, Voltage\_DC, Temperature\_Cell, manufacturer / model / serial |
| `GetStorageRealtimeDevice` | `energy/fronius/storage-realtime/device/get` | `GET /solar_api/v1/GetStorageRealtimeData.cgi?Scope=Device&DeviceId={device_id}` | Datamanager, Hybrid, GEN24/Tauro/Verto | One battery (DeviceId from active-device/get with device\_class Storage) |
| `GetOhmPilotRealtimeSystem` | `energy/fronius/ohmpilot-realtime/system/get` | `GET /solar_api/v1/GetOhmPilotRealtimeData.cgi?Scope=System` | Datamanager 3.8.1-4+, Hybrid 1.6.1-4+, GEN24 1.13+ | All Ohmpilots (PV heat diverter): power, consumed energy, temperature, CodeOfState |
| `GetOhmPilotRealtimeDevice` | `energy/fronius/ohmpilot-realtime/device/get` | `GET /solar_api/v1/GetOhmPilotRealtimeData.cgi?Scope=Device&DeviceId={device_id}` | Datamanager 3.8.1-4+, Hybrid 1.6.1-4+, GEN24 1.13+ | One Ohmpilot |
| `GetSensorRealtimeData` | `energy/fronius/sensor-realtime/get` | `GET /solar_api/v1/GetSensorRealtimeData.cgi?Scope=Device&DeviceId={device_id}&DataCollection={collection}` | Datamanager, Hybrid (error on GEN24/Tauro/Verto) | Sensor Card channels (irradiance, module / ambient temperature, digital inputs): NowSensorData or MinMaxSensorData |
| `GetStringRealtimeData` | `energy/fronius/string-realtime/get` | `GET /solar_api/v1/GetStringRealtimeData.cgi?{query}` | Datamanager (NowStringControlData also listed for GEN24, but String Control does not exist there) | String Control currents: query Scope=Device\&DeviceId=\&DataCollection=NowStringControlData / LastErrorStringControlData / CurrentSumStringControlData (+ TimePeriod=Day/Year/Total) |
| `GetLoggerInfo` | `energy/fronius/logger-info/get` | `GET /solar_api/v1/GetLoggerInfo.cgi` | Datamanager, Hybrid (error on GEN24/Tauro/Verto) | Datamanager / Hybridmanager: unique id, product and hardware / software versions, time zone, CO2 and cash factors, UTC offset |
| `GetLoggerLedInfo` | `energy/fronius/logger-led/get` | `GET /solar_api/v1/GetLoggerLEDInfo.cgi` | Datamanager, Hybrid (error on GEN24/Tauro/Verto) | Datamanager LED states (power, solar net, WLAN, solar web) and colors |
| `GetArchiveData` | `energy/fronius/archive/get` | `GET /solar_api/v1/GetArchiveData.cgi?{query}` | Datamanager 3.3.4-5+, Hybrid 1.1.2-16+ (NEVER on GEN24/Tauro/Verto) | Historic logger data: query Scope=System/Device, StartDate, EndDate, Channel (repeatable, e.g. EnergyReal\_WAC\_Sum\_Produced, InverterErrors), SeriesType=Detail/DailySum, DeviceClass + DeviceId for Device scope; one call per 120 s |

Every event is a `GET`. The Solar API has no write operations: to control an inverter (export limits, battery charge) use Modbus TCP (SunSpec) instead.

> [!TIP]
>
> This connector talks to the device directly. For fleet-wide or historic data across sites, use the Fronius Solar.web Query API (cloud) instead.

## Prerequisites

* A Fronius **GEN24 / Tauro / Verto** inverter or a **Datamanager 2.0 / Hybridmanager** reachable from the broker over the plant LAN (default port 80).
* On GEN24 / Tauro / Verto: the Solar API **switched on** in the inverter WebUI under **Communication > Solar API**. New devices (and factory resets) from bundle 1.14.1 ship with it off; a disabled API answers `404` with "Solar API disabled by customer config".
* The device address in `BASE_ADDRESS` (for example `http://192.168.1.50`, no trailing slash). Give the inverter a fixed IP or DHCP reservation.
* The device ids you want (from `active-device/get` with `device_class` `System`): inverter `1` and primary meter `0` on most single-inverter sites.

## Connection and security

* **No authentication.** Anyone on the network can read the Solar API, so keep the inverter on the OT VLAN and do not expose it to the internet.
* **HTTP vs HTTPS.** Private addresses (10/8, 172.16/12, 192.168/16) answer over plain HTTP, so the connector ships with `USE_SSL "false"`. GEN24 / Tauro / Verto from firmware 1.35 also serve HTTPS with a Fronius self-signed certificate and redirect non-private addresses to HTTPS. Switch to an `https://` base and `USE_SSL "true"` only when the broker trusts that certificate.
* **One connector per inverter.** On GEN24 / Tauro / Verto the `System` scope only covers the inverter you call. Copy the connector with another name and base address for each additional inverter.

## Pacing and errors

* At most **2 realtime requests in parallel**, with about **4 seconds** between calls. Archive requests run one at a time, **120 seconds** apart. Poll power flow every 5 to 10 seconds and slower for everything else.
* Realtime data only exists while the devices are awake: expect missing inverter values at night.
* The HTTP status is `200` even when the request fails. Always check `Head.Status.Code` in the response:

| `Head.Status.Code` | Meaning |
| - | - |
| `0` | OK, data valid |
| `1` / `11` | Not implemented / not supported on this device |
| `5` / `8` | Timeout talking to the device |
| `6` | Argument error (missing or wrong `DeviceId`, `DataCollection`, archive parameters) |
| `12` | Device not available (for example an inverter in night standby) |
| `255` | Unknown error (also used for unsupported batteries) |

## Platform support

| Event group | Datamanager / SnapINverter | Symo Hybrid | GEN24 / Tauro / Verto |
| - | - | - | - |
| API version, inverter info, active devices, power flow | yes | yes | yes |
| Inverter realtime | yes | not all collections | not `MinMaxInverterData`; `3PInverterData` on 3-phase only |
| Meter, storage, Ohmpilot realtime | yes (meter from 3.3.4-8, Ohmpilot from 3.8.1-4) | yes | yes (meter from 1.13, Ohmpilot from 1.13) |
| Sensor Card, logger info, logger LED | yes | yes | returns an error |
| String Control | yes | no hardware | does not exist |
| Archive | yes (from 3.3.4-5) | yes (from 1.1.2-16) | never |

## Payload

| Field | Type | Used by | Notes |
| - | - | - | - |
| `device_id` | string | `*Device` events, `GetSensorRealtimeData` | Device index, for example `"1"` (inverter) or `"0"` (meter) |
| `collection` | string | `GetInverterRealtimeDevice`, `GetSensorRealtimeData` | `CommonInverterData`, `CumulationInverterData`, `3PInverterData`, `MinMaxInverterData`, `NowSensorData`, `MinMaxSensorData` |
| `device_class` | string | `GetActiveDeviceInfo` | `System`, `Inverter`, `Meter`, `Storage`, `Ohmpilot`, `SensorCard`, `StringControl` |
| `query` | string | `GetStringRealtimeData`, `GetArchiveData` | Whole pre-encoded query string |

Events without fields accept any payload, for example `{}`.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"device_id":"1","collection":"CommonInverterData"}
{"device_class":"System"}
{"query":"Scope=Device&DeviceId=1&DataCollection=CurrentSumStringControlData&TimePeriod=Day"}
{"query":"Scope=System&StartDate=2026-10-04&EndDate=2026-10-04&SeriesType=DailySum&Channel=EnergyReal_WAC_Sum_Produced"}
```

## Example actions

These actions poll power flow every 10 seconds, the inverter and meters every 30 seconds and the inverter list every 5 minutes, well inside the Solar API pacing rules. No secrets are needed.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the FroniusSolarApi route (docs page). Not part of the route template.
# No secrets: the Fronius Solar API is unauthenticated on the plant LAN. Set BASE_ADDRESS in the route first.
# Inline JSON object literals are not supported when publishing to a topic, so device requests use a COLLAPSED
#   model sent with PUBLISH MODEL. Parameterless events accept any payload.
# Pacing: the Solar API allows 2 parallel realtime requests and ~4 s between calls; these actions stay far below.

DEFINE MODEL FroniusDeviceRequest COLLAPSED
    ADD STRING "device_id"
    ADD STRING "collection"

DEFINE ACTION FroniusPowerFlowEvery10Seconds
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "energy/fronius/power-flow/get" WITH "{}"

DEFINE ACTION FroniusInverterEvery30Seconds
ON EVERY 30 SECONDS DO
    PUBLISH MODEL FroniusDeviceRequest TO "energy/fronius/inverter-realtime/device/get" WITH
        device_id = "1"
        collection = "CommonInverterData"

DEFINE ACTION FroniusMeterEvery30Seconds
ON EVERY 30 SECONDS DO
    PUBLISH TOPIC "energy/fronius/meter-realtime/system/get" WITH "{}"

DEFINE ACTION FroniusInverterInfoEvery5Minutes
ON EVERY 5 MINUTES DO
    PUBLISH TOPIC "energy/fronius/inverter-info/get" WITH "{}"
```

## Deployable connector

Set `BASE_ADDRESS` to your inverter or Datamanager before deploying.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Fronius Solar API V1 (local JSON API on the inverter / Datamanager, LAN only):
#   API version, inverter realtime data (system total or one inverter: common, cumulation, 3-phase, min/max),
#   inverter list and status codes, active devices per class, power flow (PV, grid, load, battery, autonomy),
#   smart meter, battery storage and Ohmpilot realtime data, Sensor Card and String Control data, Datamanager
#   logger info and LED state, and historic archive data (Datamanager / Hybridmanager only).
#   42,0410,2012,EN (rev. 021-15052025) plus the official GEN24 / Tauro / Verto OpenAPI 3.0 file (solarApiv1.json
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/fronius-solar-api
#
# Host: the Solar API runs on each inverter (GEN24 / Tauro / Verto) or Datamanager 2.0 / Hybridmanager on the
#   plant LAN. Replace BASE_ADDRESS with its address, no trailing slash, for example http://192.168.1.50. Private
#   IPs (10/8, 172.16/12, 192.168/16) answer over plain HTTP (USE_SSL "false"). GEN24 / Tauro / Verto from
#   firmware 1.35 also serve HTTPS with a Fronius self-signed certificate and redirect non-private addresses to
#   HTTPS; use USE_SSL "true" only when the broker trusts that certificate. Use one route per inverter: GEN24 does
#   not aggregate other inverters ("System" scope covers only itself). This is not the Solar.web cloud API.
# Auth: none. The Solar API is read-only and unauthenticated; keep it on the OT network. On GEN24 it can be
#   switched off (WebUI > Communication > Solar API); since bundle 1.14.1 new or factory-reset devices ship with it
#   OFF, and a disabled API answers 404 "Solar API disabled by customer config".
# Pacing: at most 2 realtime requests in parallel and about 4 s between calls; archive requests one at a time,
#   120 s apart. Poll every 5-10 s or slower. Realtime data is only available while the devices are awake (no
#   inverter data at night); Head.Status.Code 0 = OK, 12 = DeviceNotAvailable, 6 = argument error, 255 = unknown.
# Platform gaps: GetSensorRealtimeData, GetLoggerInfo and GetLoggerLEDInfo return an error on GEN24 / Tauro /
#   Verto; GetArchiveData is NEVER available on GEN24 / Tauro / Verto (Datamanager / Hybridmanager only);
#   MinMaxInverterData is not on Hybrid or GEN24; String Control does not exist on GEN24.
#
# Payload fields: device_id (Solar Net / device index as a string), collection (DataCollection name),
#   device_class, query (whole pre-encoded query string). Events without fields accept any payload, e.g. {}.
#     GetInverterRealtimeDevice  device_id = "1", collection = "CommonInverterData"
#                                (or CumulationInverterData, 3PInverterData, MinMaxInverterData)
#     GetActiveDeviceInfo        device_class = "System" (or Inverter, Meter, Storage, Ohmpilot, SensorCard,
#                                StringControl)
#     GetMeterRealtimeDevice     device_id = "0"
#     GetSensorRealtimeData      device_id = "1", collection = "NowSensorData" (or MinMaxSensorData)
#     GetStringRealtimeData      query = "Scope=Device&DeviceId=1&DataCollection=CurrentSumStringControlData&TimePeriod=Day"
#     GetArchiveData             query = "Scope=System&StartDate=2026-10-04&EndDate=2026-10-04&SeriesType=DailySum&Channel=EnergyReal_WAC_Sum_Produced"

DEFINE CONNECTOR FroniusSolarApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://192.168.1.50"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '10'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Replace BASE_ADDRESS with your inverter / Datamanager (http://<lan-ip>); GEN24 1.35+ HTTPS -> USE_SSL "true".
    ADD EVENT GetApiVersion
        WITH SOURCE_TOPIC "energy/fronius/api-version/get"
        WITH DESTINATION_TOPIC "energy/fronius/api-version/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/GetAPIVersion.cgi"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetInverterRealtimeSystem
        WITH SOURCE_TOPIC "energy/fronius/inverter-realtime/system/get"
        WITH DESTINATION_TOPIC "energy/fronius/inverter-realtime/system/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetInverterRealtimeData.cgi?Scope=System"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetInverterRealtimeDevice
        WITH SOURCE_TOPIC "energy/fronius/inverter-realtime/device/get"
        WITH DESTINATION_TOPIC "energy/fronius/inverter-realtime/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetInverterRealtimeData.cgi?Scope=Device&DeviceId={value.json.device_id}&DataCollection={value.json.collection}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetInverterInfo
        WITH SOURCE_TOPIC "energy/fronius/inverter-info/get"
        WITH DESTINATION_TOPIC "energy/fronius/inverter-info/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetInverterInfo.cgi"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetActiveDeviceInfo
        WITH SOURCE_TOPIC "energy/fronius/active-device/get"
        WITH DESTINATION_TOPIC "energy/fronius/active-device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetActiveDeviceInfo.cgi?DeviceClass={value.json.device_class}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetPowerFlowRealtime
        WITH SOURCE_TOPIC "energy/fronius/power-flow/get"
        WITH DESTINATION_TOPIC "energy/fronius/power-flow/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetPowerFlowRealtimeData.fcgi"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetMeterRealtimeSystem
        WITH SOURCE_TOPIC "energy/fronius/meter-realtime/system/get"
        WITH DESTINATION_TOPIC "energy/fronius/meter-realtime/system/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetMeterRealtimeData.cgi?Scope=System"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetMeterRealtimeDevice
        WITH SOURCE_TOPIC "energy/fronius/meter-realtime/device/get"
        WITH DESTINATION_TOPIC "energy/fronius/meter-realtime/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetMeterRealtimeData.cgi?Scope=Device&DeviceId={value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetStorageRealtimeSystem
        WITH SOURCE_TOPIC "energy/fronius/storage-realtime/system/get"
        WITH DESTINATION_TOPIC "energy/fronius/storage-realtime/system/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetStorageRealtimeData.cgi?Scope=System"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetStorageRealtimeDevice
        WITH SOURCE_TOPIC "energy/fronius/storage-realtime/device/get"
        WITH DESTINATION_TOPIC "energy/fronius/storage-realtime/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetStorageRealtimeData.cgi?Scope=Device&DeviceId={value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetOhmPilotRealtimeSystem
        WITH SOURCE_TOPIC "energy/fronius/ohmpilot-realtime/system/get"
        WITH DESTINATION_TOPIC "energy/fronius/ohmpilot-realtime/system/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetOhmPilotRealtimeData.cgi?Scope=System"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetOhmPilotRealtimeDevice
        WITH SOURCE_TOPIC "energy/fronius/ohmpilot-realtime/device/get"
        WITH DESTINATION_TOPIC "energy/fronius/ohmpilot-realtime/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetOhmPilotRealtimeData.cgi?Scope=Device&DeviceId={value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSensorRealtimeData
        WITH SOURCE_TOPIC "energy/fronius/sensor-realtime/get"
        WITH DESTINATION_TOPIC "energy/fronius/sensor-realtime/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetSensorRealtimeData.cgi?Scope=Device&DeviceId={value.json.device_id}&DataCollection={value.json.collection}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetStringRealtimeData
        WITH SOURCE_TOPIC "energy/fronius/string-realtime/get"
        WITH DESTINATION_TOPIC "energy/fronius/string-realtime/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetStringRealtimeData.cgi?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetLoggerInfo
        WITH SOURCE_TOPIC "energy/fronius/logger-info/get"
        WITH DESTINATION_TOPIC "energy/fronius/logger-info/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetLoggerInfo.cgi"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetLoggerLedInfo
        WITH SOURCE_TOPIC "energy/fronius/logger-led/get"
        WITH DESTINATION_TOPIC "energy/fronius/logger-led/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetLoggerLEDInfo.cgi"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetArchiveData
        WITH SOURCE_TOPIC "energy/fronius/archive/get"
        WITH DESTINATION_TOPIC "energy/fronius/archive/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/solar_api/v1/GetArchiveData.cgi?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```


# GE Vernova Proficy Historian
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ge-vernova-proficy-historian

Connect Coreflux LoT to GE Vernova Proficy Historian: get UAA tokens, read current, raw, interpolated and sampled tag data, write samples, and manage tags

Technical Preview

## Overview

Proficy Historian (GE Vernova, formerly GE Digital) stores plant time-series data. Its **Historian REST API** is installed with the Historian **web-based clients** and lives under `https://<host>/historian-rest-api/v1/`. Calls carry an OAuth2 bearer token issued by **Proficy Authentication** (UAA) on the same host at `/uaa/oauth/token`.

The **ProficyHistorian** connector covers the token request, server and system status, tag management, every read mode (current value, raw, interpolated, calculated, sampled) and writing samples with `datapoints/create`. Each event publishes the server's reply on `<topic>/response`.

| Event | Topic | Request | Notes |
| - | - | - | - |
| GetToken | `historian/proficy-historian/token/create` | `POST /uaa/oauth/token` | Proficy Authentication (UAA) client\_credentials token; authorization = Basic base64(client\_id:client\_secret) -> access\_token |
| GetUserToken | `historian/proficy-historian/user-token/create` | `POST /uaa/oauth/token` | Password grant for a Proficy Authentication user (e.g. client historian\_public\_rest\_api) -> access\_token |
| GetServerProperties | `historian/proficy-historian/server-property/get` | `GET /historian-rest-api/v1/serverproperties` | Storages, data stores and archiver services (connectivity probe) |
| GetSystemStats | `historian/proficy-historian/system-stat/get` | `GET /historian-rest-api/v1/systemstats` | Utilization, queue sizes, compression ratio |
| ListTags | `historian/proficy-historian/tag/list` | `GET /historian-rest-api/v1/tags?nameMask={nameMask}&maxNumber={maxNumber}` | Tag names matching a mask (\* and ?); maxNumber 0 = all, ErrorCode 14 = more tags than requested |
| ListTagsPaged | `historian/proficy-historian/tag-page/list` | `GET /historian-rest-api/v1/tagslist?{query}` | Tags with properties, paged (pageno, pagesize default 128, lastmodified); first/prev/next/last links |
| GetTagProperties | `historian/proficy-historian/tag-property/get` | `GET /historian-rest-api/v1/tags/properties/{tag}` | All properties of one tag (unknown tag returns an error) |
| AddTag | `historian/proficy-historian/tag/create` | `POST /historian-rest-api/v1/tags/addtag` | Add one tag; body needs Name + DataType (existing tag: new properties applied) |
| UpdateTagProperties | `historian/proficy-historian/tag-property/update` | `PUT /historian-rest-api/v1/tags/properties/{tag}` | Set tag properties, e.g. \{"Description": "..."} (no rename) |
| DeleteTag | `historian/proficy-historian/tag/delete` | `DELETE /historian-rest-api/v1/tags/{tag}?permanentDelete={permanentDelete}` | Delete a tag; permanentDelete true also removes it from the archive index |
| GetCurrentValue | `historian/proficy-historian/current-value/get` | `GET /historian-rest-api/v1/datapoints/currentvalue?tagNames={tagNames}` | Latest sample (TimeStamp, Value, Quality) per tag; tagNames separated by ; |
| GetRawData | `historian/proficy-historian/raw-data/get` | `GET /historian-rest-api/v1/datapoints/raw/{tagNames}/{start}/{end}/{direction}/{count}` | Raw samples; count 0 = by time, count > 0 = by number; direction 0 forward, 1 backward |
| GetInterpolatedData | `historian/proficy-historian/interpolated-data/get` | `GET /historian-rest-api/v1/datapoints/interpolated/{tagNames}/{start}/{end}/{count}/{intervalMs}` | Interpolated samples by count or interval |
| GetCalculatedData | `historian/proficy-historian/calculated-data/get` | `GET /historian-rest-api/v1/datapoints/calculated/{tagNames}/{start}/{end}/{calculationMode}/{count}/{intervalMs}` | Calculated samples (calculationMode 1 = Average, see CalculationModeType) |
| GetSampledData | `historian/proficy-historian/sampled-data/get` | `GET /historian-rest-api/v1/datapoints/sampled?{query}` | Any sampling mode via query (tagNames, start, end, samplingMode, calculationMode, direction, count, intervalMs) |
| CreateDataPoints | `historian/proficy-historian/data-point/create` | `POST /historian-rest-api/v1/datapoints/create` | Write samples: \{"TagName": ..., "samples": \[\{"TimeStamp", "Value", "Quality": 3}]} (REST API admin or write permission) |

## Prerequisites

1. Proficy Historian 8.x, 9.x, 2022, 2023 or 2024 (Windows) with the **web-based clients** installed. That install adds the Historian REST API and Proficy Authentication. The broker host must reach the web-based clients node on HTTPS port **443**. Historian 7.x used port **8443** for both the REST API and UAA.
2. A Proficy Authentication **client** (client ID and secret) for the `client_credentials` grant, or a Historian web user plus the `historian_public_rest_api` client for the password grant. Writes (`datapoints/create`, tag add / update / delete) need the REST API administrator or a user with write permission.
3. The certificate of the web-based clients node, trusted on the broker host. The default install uses a self-signed certificate.
4. Store the client credentials in a Hub secret, for example `PROFICY_HISTORIAN_CLIENT` holding `Basic <base64 of client_id:client_secret>`.

## Authentication

1. Publish `{ "authorization": "Basic <base64 of client_id:client_secret>" }` to `historian/proficy-historian/token/create`. The response carries `access_token`, `token_type` `bearer` and `expires_in` (seconds).
2. Send `"authorization": "Bearer <access_token>"` with every other event. Request a new token before `expires_in` runs out.

As an alternative, `historian/proficy-historian/user-token/create` uses the password grant: `client_id` (`historian_public_rest_api`), `client_secret` (set during install), `username` (default `<machinename>.admin`) and `password` go in the payload. It sends no `Authorization` header.

> [!WARNING]
>
> Keep client secrets and passwords in Hub secrets and add them with `GET SECRET`. Never put them in the connector file or in retained topics.

## Configuration

* Replace `YOUR_HISTORIAN_HOST` in `BASE_ADDRESS` with the web-based clients node. For Historian 7.x use `https://<host>:8443`.
* Tag names go into the URL as given. URL-encode special characters (`#` becomes `%23`). Separate several tags in `tagNames` with `;`.
* Timestamps are ISO 8601 UTC, for example `2026-10-05T07:00:00.000Z`.
* Responses are JSON `{ "ErrorCode": 0, "ErrorMessage": null, "Data": ... }`. Check `ErrorCode` as well as the HTTP status. `ErrorCode` `14` on the tag list means more tags exist than `maxNumber`.
* The server also serves Swagger UI at `https://<host>/historian-rest-api/swagger-ui.html` for the exact API of your version.

## Examples

Get the current value of two tags:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/proficy-historian/current-value/get
{ "authorization": "Bearer <token>", "tagNames": "Line1.Temperature;Line1.Pressure" }
// historian/proficy-historian/current-value/get/response
{ "ErrorCode": 0, "ErrorMessage": null,
  "Data": [{ "TagName": "Line1.Temperature", "ErrorCode": 0, "DataType": "DoubleFloat",
             "Samples": [{ "TimeStamp": "2026-10-05T06:59:58.000Z", "Value": "21.4", "Quality": 3 }] }, ...] }
```

Read raw samples for the last hour (`count` 0 reads by time; a positive `count` reads that many samples; `direction` 0 is forward):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/proficy-historian/raw-data/get
{ "authorization": "Bearer <token>", "tagNames": "Line1.Temperature",
  "start": "2026-10-05T06:00:00.000Z", "end": "2026-10-05T07:00:00.000Z", "direction": 0, "count": 0 }
```

Ten-minute averages (`calculationMode` 1 is Average):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/proficy-historian/calculated-data/get
{ "authorization": "Bearer <token>", "tagNames": "Line1.Temperature",
  "start": "2026-10-05T06:00:00.000Z", "end": "2026-10-05T07:00:00.000Z", "calculationMode": 1, "count": 0, "intervalMs": 600000 }
```

Write a sample from MQTT into the historian (`Quality` 3 is Good):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/proficy-historian/data-point/create
{ "authorization": "Bearer <token>",
  "body": { "TagName": "Coreflux.Line1.Temperature",
            "samples": [{ "TimeStamp": "2026-10-05T07:00:00.000Z", "Value": "21.4", "Quality": 3 }] } }
// historian/proficy-historian/data-point/create/response
{ "ErrorCode": 0, "ErrorMessage": "" }
```

Add a tag before writing to it (`Name` and `DataType` are required):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/proficy-historian/tag/create
{ "authorization": "Bearer <token>", "body": { "Name": "Coreflux.Line1.Temperature", "DataType": 3 } }
```

Example actions: refresh and keep the token, poll two tags, store an MQTT value in the historian, and a health check:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProficyRefreshToken
ON EVERY 1 HOUR DO
    SET "client" WITH GET SECRET "PROFICY_HISTORIAN_CLIENT"
    PUBLISH TOPIC "historian/proficy-historian/token/create" WITH { "authorization": {client} }

DEFINE ACTION ProficyKeepToken
ON TOPIC "historian/proficy-historian/token/create/response" DO
    SET "token" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "internal/proficy-historian/authorization" WITH "Bearer " + {token}

DEFINE ACTION ProficyPollLine1
ON EVERY 10 SECONDS DO
    SET "auth" WITH GET TOPIC "internal/proficy-historian/authorization"
    PUBLISH TOPIC "historian/proficy-historian/current-value/get" WITH { "authorization": {auth}, "tagNames": "Line1.Temperature;Line1.Pressure" }

DEFINE ACTION ProficyStoreLine1Temperature
ON TOPIC "plant/line1/temperature" DO
    SET "auth" WITH GET TOPIC "internal/proficy-historian/authorization"
    SET "value" WITH PAYLOAD AS STRING
    SET "ts" WITH TIMESTAMP "UTC"
    PUBLISH TOPIC "historian/proficy-historian/data-point/create" WITH { "authorization": {auth}, "body": { "TagName": "Coreflux.Line1.Temperature", "samples": [ { "TimeStamp": {ts}, "Value": {value}, "Quality": 3 } ] } }

DEFINE ACTION ProficyHealthCheck
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET TOPIC "internal/proficy-historian/authorization"
    PUBLISH TOPIC "historian/proficy-historian/system-stat/get" WITH { "authorization": {auth} }
```

## Not covered

* POST variants of the read APIs (tagNames in the body), trend data (`datapoints/trend`), tag rename, add many tags (`tags/addtags`) and data store / collection settings. Use the same URL pattern with your own event if you need them.
* Systems administration (machines, mirror groups, storages, DHS services, performance counters), Historian model, collectors and collector instances, data stores, and alarms and events.
* Proficy Operations Hub, the Historian Web Admin console, the Historian SDK / User API / OLE DB provider, and Historian collectors (including the MQTT collector, which can ingest from this broker directly).

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app catalog](/latest/lot-language/routes/rest-api-apps/index)
* [Proficy Historian REST APIs: Managing Tags](https://www.gevernova.com/software/documentation/historian/version2024/r_managing_tags_apis.html)
* [Proficy Historian: About Security and Authentication](https://www.gevernova.com/software/documentation/historian/version2024/c_about_security_and_authentication.html)


# Gemini Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/gemini-api

LoT connector for the Google Gemini API: generate content for alarm triage and shift summaries, create embeddings, count tokens and list models with an API key

Technical Preview

## Overview

Client-mode REST API connectors for Google Gemini: triage alarms and summarize shift logs with generateContent (structured JSON output), create embeddings, count tokens and list models with a Gemini API key, run Gemini and custom anomaly models on Vertex AI (predict on your endpoint), and get Google OAuth 2.0 access tokens.

This is one of the templates in the Google Gemini API and Vertex AI REST API app (`google-gemini-api-and-vertex-ai`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Gemini API: header x-goog-api-key \{value.json.api\_key} (Google AI Studio / Cloud API key; Hub secret GEMINI\_API\_KEY via GET SECRET). Vertex AI: Authorization: Bearer \{value.json.access\_token}, OAuth 2.0 access token with scope [https://www.googleapis.com/auth/cloud-platform](https://www.googleapis.com/auth/cloud-platform) for an identity with roles/aiplatform.user (\~1 h lifetime); GoogleOAuthToken connector gets it (refresh\_token grant with client id/secret/refresh token, or service-account JWT bearer grant with a JWT signed outside the broker). Hub secrets GEMINI\_API\_KEY, GOOGLE\_OAUTH\_CLIENT\_ID, GOOGLE\_OAUTH\_CLIENT\_SECRET, GOOGLE\_OAUTH\_REFRESH\_TOKEN. Never commit keys, tokens or service-account JSON.

Auth headers used by the template: `x-goog-api-key: {value.json.api_key}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Gemini Api connector | no |
| `BaseUrl` | string | Gemini Api base URL without trailing slash (e.g. [https://generativelanguage.googleapis.com](https://generativelanguage.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://generativelanguage.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GenerateContent` | POST | `/v1beta/models/{value.json.model}:generateContent` | `ai/gemini/content/generate` | `ai/gemini/content/generate/response` | `api_key`, `body`, `model` |
| `CountTokens` | POST | `/v1beta/models/{value.json.model}:countTokens` | `ai/gemini/tokens/count` | `ai/gemini/tokens/count/response` | `api_key`, `body`, `model` |
| `EmbedContent` | POST | `/v1beta/models/{value.json.model}:embedContent` | `ai/gemini/embedding/create` | `ai/gemini/embedding/create/response` | `api_key`, `body`, `model` |
| `BatchEmbedContents` | POST | `/v1beta/models/{value.json.model}:batchEmbedContents` | `ai/gemini/embedding/batch` | `ai/gemini/embedding/batch/response` | `api_key`, `body`, `model` |
| `ListModels` | GET | `/v1beta/models?pageSize={value.json.page_size}&pageToken={value.json.page_token}` | `ai/gemini/model/list` | `ai/gemini/model/list/response` | `api_key`, `page_size`, `page_token` |
| `GetModel` | GET | `/v1beta/models/{value.json.model}` | `ai/gemini/model/get` | `ai/gemini/model/get/response` | `api_key`, `model` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GEMINI_API"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GeminiApiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://generativelanguage.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GenerateContent
        WITH SOURCE_TOPIC "ai/gemini/content/generate"
        WITH DESTINATION_TOPIC "ai/gemini/content/generate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1beta/models/{value.json.model}:generateContent"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "x-goog-api-key" "{value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT CountTokens
        WITH SOURCE_TOPIC "ai/gemini/tokens/count"
        WITH DESTINATION_TOPIC "ai/gemini/tokens/count/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1beta/models/{value.json.model}:countTokens"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "x-goog-api-key" "{value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT EmbedContent
        WITH SOURCE_TOPIC "ai/gemini/embedding/create"
        WITH DESTINATION_TOPIC "ai/gemini/embedding/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1beta/models/{value.json.model}:embedContent"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "x-goog-api-key" "{value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT BatchEmbedContents
        WITH SOURCE_TOPIC "ai/gemini/embedding/batch"
        WITH DESTINATION_TOPIC "ai/gemini/embedding/batch/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1beta/models/{value.json.model}:batchEmbedContents"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "x-goog-api-key" "{value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListModels
        WITH SOURCE_TOPIC "ai/gemini/model/list"
        WITH DESTINATION_TOPIC "ai/gemini/model/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1beta/models?pageSize={value.json.page_size}&pageToken={value.json.page_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-goog-api-key" "{value.json.api_key}"
    ADD EVENT GetModel
        WITH SOURCE_TOPIC "ai/gemini/model/get"
        WITH DESTINATION_TOPIC "ai/gemini/model/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1beta/models/{value.json.model}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-goog-api-key" "{value.json.api_key}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GenerateContent` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/gemini/content/generate/response' &
mosquitto_pub -t 'ai/gemini/content/generate' -m '{"api_key": "<api_key>", "body": {}, "model": "<model>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Geotab (MyGeotab API) REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/geotab

Client-mode REST API connector for Geotab MyGeotab JSON-RPC (GetFeed, Device, TextMessage)

Technical Preview

## Overview

Client-mode REST API connector for Geotab MyGeotab JSON-RPC (GetFeed, Device, TextMessage). `BASE_ADDRESS` defaults to `https://my.geotab.com`. Auth: **Session via Authenticate (JSON-RPC); then credentials.sessionId**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

Session via Authenticate (JSON-RPC); then credentials.sessionId. Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR GeotabRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://my.geotab.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Optional: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Authenticate
        WITH SOURCE_TOPIC "integrations/geotab/request/Authenticate"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Authenticate"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Get
        WITH SOURCE_TOPIC "integrations/geotab/request/Get"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Get"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getfeed
        WITH SOURCE_TOPIC "integrations/geotab/request/Getfeed"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Getfeed"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Add
        WITH SOURCE_TOPIC "integrations/geotab/request/Add"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/geotab/request/...`; responses on `integrations/geotab/response/...`.

## Template reference

Generated from the shipped broker template `geotab` (`-connectorCode GEOTAB`). It lists every event the template defines.

### Auth

Session via Authenticate (JSON-RPC); then credentials.sessionId

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Geotab connector | no |
| `BaseUrl` | string | Geotab base URL without trailing slash (e.g. [https://my.geotab.com](https://my.geotab.com)) | yes |

`BASE_ADDRESS` default: `https://my.geotab.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Authenticate` | POST | `/apiv1` | `integrations/geotab/request/Authenticate` | `integrations/geotab/response/Authenticate` | none |
| `Get` | POST | `/apiv1` | `integrations/geotab/request/Get` | `integrations/geotab/response/Get` | none |
| `Getfeed` | POST | `/apiv1` | `integrations/geotab/request/Getfeed` | `integrations/geotab/response/Getfeed` | none |
| `Add` | POST | `/apiv1` | `integrations/geotab/request/Add` | `integrations/geotab/response/Add` | none |
| `Set` | POST | `/apiv1` | `integrations/geotab/request/Set` | `integrations/geotab/response/Set` | none |
| `Remove` | POST | `/apiv1` | `integrations/geotab/request/Remove` | `integrations/geotab/response/Remove` | none |
| `Getcountof` | POST | `/apiv1` | `integrations/geotab/request/Getcountof` | `integrations/geotab/response/Getcountof` | none |
| `Executemulticall` | POST | `/apiv1` | `integrations/geotab/request/Executemulticall` | `integrations/geotab/response/Executemulticall` | none |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GEOTAB"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GeotabRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://my.geotab.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Authenticate
        WITH SOURCE_TOPIC "integrations/geotab/request/Authenticate"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Authenticate"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Get
        WITH SOURCE_TOPIC "integrations/geotab/request/Get"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Get"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getfeed
        WITH SOURCE_TOPIC "integrations/geotab/request/Getfeed"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Getfeed"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Add
        WITH SOURCE_TOPIC "integrations/geotab/request/Add"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Add"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Set
        WITH SOURCE_TOPIC "integrations/geotab/request/Set"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Set"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Remove
        WITH SOURCE_TOPIC "integrations/geotab/request/Remove"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Remove"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getcountof
        WITH SOURCE_TOPIC "integrations/geotab/request/Getcountof"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Getcountof"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Executemulticall
        WITH SOURCE_TOPIC "integrations/geotab/request/Executemulticall"
        WITH DESTINATION_TOPIC "integrations/geotab/response/Executemulticall"
        WITH METHOD "POST"
        WITH ENDPOINT "/apiv1"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Authenticate` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/geotab/response/Authenticate' &
mosquitto_pub -t 'integrations/geotab/request/Authenticate' -m '{}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# GitHub REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/github

Client-mode REST API connector for a curated GitHub REST subset: user, repos, issues, pulls, and Actions

Technical Preview

## Overview

A client-mode connector for a **curated eight-operation** slice of the [GitHub REST API](https://docs.github.com/en/rest): rate limit, the authenticated user, repositories, issues, pull requests, and Actions workflow runs. It is meant for edge or IT-ops demos, not the full GitHub surface. Prefer a fine-grained personal access token with least privilege.

> [!NOTE]
>
> `GET /rate_limit` can return HTTP 200 without a token. Authenticated connectors need a PAT. An invalid Bearer token returns HTTP 401. Unauthenticated calls to other public connectors may return HTTP 403 when the IP is rate limited.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — GitHub REST
# Generated from curated OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes
# Auth: Bearer PAT / fine-grained token via {value.json.api_token}. Prefer Hub secrets.
# Optional: ADD "X-GitHub-Api-Version" "2022-11-28" on events if you pin an API version.

DEFINE CONNECTOR GithubRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.github.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: GitHub PAT / fine-grained token as Bearer — pass {value.json.api_token}.
        # Prefer Hub secrets / GET SECRET upstream — never commit real tokens.
    ADD EVENT Getratelimit
        WITH SOURCE_TOPIC "integrations/github/request/Getratelimit"
        WITH DESTINATION_TOPIC "integrations/github/response/Getratelimit"
        WITH METHOD "GET"
        WITH ENDPOINT "/rate_limit"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getauthenticateduser
        WITH SOURCE_TOPIC "integrations/github/request/Getauthenticateduser"
        WITH DESTINATION_TOPIC "integrations/github/response/Getauthenticateduser"
        WITH METHOD "GET"
        WITH ENDPOINT "/user"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listuserrepos
        WITH SOURCE_TOPIC "integrations/github/request/Listuserrepos"
        WITH DESTINATION_TOPIC "integrations/github/response/Listuserrepos"
        WITH METHOD "GET"
        WITH ENDPOINT "/user/repos"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getrepo
        WITH SOURCE_TOPIC "integrations/github/request/Getrepo"
        WITH DESTINATION_TOPIC "integrations/github/response/Getrepo"
        WITH METHOD "GET"
        WITH ENDPOINT "/repos/{value.json.owner}/{value.json.repo}"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listissues
        WITH SOURCE_TOPIC "integrations/github/request/Listissues"
        WITH DESTINATION_TOPIC "integrations/github/response/Listissues"
        WITH METHOD "GET"
        WITH ENDPOINT "/repos/{value.json.owner}/{value.json.repo}/issues"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createissue
        WITH SOURCE_TOPIC "integrations/github/request/Createissue"
        WITH DESTINATION_TOPIC "integrations/github/response/Createissue"
        WITH METHOD "POST"
        WITH ENDPOINT "/repos/{value.json.owner}/{value.json.repo}/issues"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Listpulls
        WITH SOURCE_TOPIC "integrations/github/request/Listpulls"
        WITH DESTINATION_TOPIC "integrations/github/response/Listpulls"
        WITH METHOD "GET"
        WITH ENDPOINT "/repos/{value.json.owner}/{value.json.repo}/pulls"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listworkflowruns
        WITH SOURCE_TOPIC "integrations/github/request/Listworkflowruns"
        WITH DESTINATION_TOPIC "integrations/github/response/Listworkflowruns"
        WITH METHOD "GET"
        WITH ENDPOINT "/repos/{value.json.owner}/{value.json.repo}/actions/runs"
        WITH HEADERS
            ADD "Accept" "application/vnd.github+json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getratelimit | GET | `/rate_limit` | `integrations/github/request/Getratelimit` | `integrations/github/response/Getratelimit` |
| Getauthenticateduser | GET | `/user` | `integrations/github/request/Getauthenticateduser` | `integrations/github/response/Getauthenticateduser` |
| Listuserrepos | GET | `/user/repos` | `integrations/github/request/Listuserrepos` | `integrations/github/response/Listuserrepos` |
| Getrepo | GET | `/repos/{value.json.owner}/{value.json.repo}` | `integrations/github/request/Getrepo` | `integrations/github/response/Getrepo` |
| Listissues | GET | `/repos/{value.json.owner}/{value.json.repo}/issues` | `integrations/github/request/Listissues` | `integrations/github/response/Listissues` |
| Createissue | POST | `/repos/{value.json.owner}/{value.json.repo}/issues` | `integrations/github/request/Createissue` | `integrations/github/response/Createissue` |
| Listpulls | GET | `/repos/{value.json.owner}/{value.json.repo}/pulls` | `integrations/github/request/Listpulls` | `integrations/github/response/Listpulls` |
| Listworkflowruns | GET | `/repos/{value.json.owner}/{value.json.repo}/actions/runs` | `integrations/github/request/Listworkflowruns` | `integrations/github/response/Listworkflowruns` |

## Auth

Bearer token plus the GitHub media type:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Accept" "application/vnd.github+json"
ADD "Authorization" "Bearer {value.json.api_token}"
```

**api\_token** `string` *required*

Classic or fine-grained PAT. Publish it as `api_token`. Prefer a Hub secret. Never commit the token.

**owner** `string`

Repository owner. Required on repo, issue, pull, and Actions events.

**repo** `string`

Repository name. Required with `owner`.

Optional header on each event: `X-GitHub-Api-Version` `2022-11-28`.

Rate limit or authenticated user:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_GITHUB_PAT"}
```

List issues:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_GITHUB_PAT", "owner": "octocat", "repo": "Hello-World"}
```

Create issue (connector body is `{payload}`; include `title` and `body`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_GITHUB_PAT", "owner": "OWNER", "repo": "REPO", "title": "From Coreflux", "body": "Opened via REST_API route"}
```

## Try it

1. Add the connector on your broker.
2. Publish the token JSON to `integrations/github/request/Getratelimit` or `integrations/github/request/Getauthenticateduser`.
3. Subscribe to the matching `integrations/github/response/...` topic.
4. Issues: publish `api_token`, `owner`, and `repo` to `integrations/github/request/Listissues`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# GitLab
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/gitlab

Use a LoT REST API connector for GitLab API v4 to trigger pipelines, list releases, create issues, download generic packages and create project webhooks

Technical Preview

## Overview

A client-mode connector for a **curated DevOps** slice of the [GitLab REST API v4](https://docs.gitlab.com/ee/api/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST trigger/pipeline | `POST /projects/{id}/trigger/pipeline` | Pipeline **trigger token** + `ref` (not a PAT) |
| GET releases | `GET /projects/{id}/releases` | List project releases |
| POST issues | `POST /projects/{id}/issues` | Create issue from alarm / MQTT |
| GET generic package file | `GET /projects/{id}/packages/generic/{name}/{version}/{file}` | Firmware / artifact download |
| GET /user | `GET /user` | Credential check → `id` / `username` |
| POST hooks | `POST /projects/{id}/hooks` | Register GitLab → HTTPS target |

Default `BASE_ADDRESS` is `https://gitlab.com/api/v4` (no trailing slash). Self-hosted: `https://YOUR_HOST/api/v4`. Topics use `devops/gitlab/<object>/<verb>`.

> [!NOTE]
>
> Auth prefers **`PRIVATE-TOKEN`** (personal / project / group access token). OAuth 2.0 may use `Authorization: Bearer …` instead. Prefer Hub secret `GITLAB_TOKEN` (aliases `GITLAB_PRIVATE_TOKEN`, `GITLAB_ACCESS_TOKEN`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — GitLab REST API v4
# Auth: PRIVATE-TOKEN {value.json.private_token} (PAT); trigger uses query token
# BASE_ADDRESS: https://gitlab.com/api/v4

DEFINE CONNECTOR GitlabRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://gitlab.com/api/v4"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuser
        WITH SOURCE_TOPIC "devops/gitlab/user/get"
        WITH DESTINATION_TOPIC "devops/gitlab/user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/user"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
    ADD EVENT Triggerpipeline
        WITH SOURCE_TOPIC "devops/gitlab/pipeline/trigger"
        WITH DESTINATION_TOPIC "devops/gitlab/pipeline/trigger/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/projects/{value.json.project_id}/trigger/pipeline?token={value.json.trigger_token}&ref={value.json.ref}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Listreleases
        WITH SOURCE_TOPIC "devops/gitlab/release/list"
        WITH DESTINATION_TOPIC "devops/gitlab/release/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/projects/{value.json.project_id}/releases"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
    ADD EVENT Createissue
        WITH SOURCE_TOPIC "devops/gitlab/issue/create"
        WITH DESTINATION_TOPIC "devops/gitlab/issue/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/projects/{value.json.project_id}/issues"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
        WITH BODY "{payload}"
    ADD EVENT Downloadgenericpackage
        WITH SOURCE_TOPIC "devops/gitlab/package/generic/get"
        WITH DESTINATION_TOPIC "devops/gitlab/package/generic/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/projects/{value.json.project_id}/packages/generic/{value.json.package_name}/{value.json.package_version}/{value.json.file_name}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
    ADD EVENT Createprojecthook
        WITH SOURCE_TOPIC "devops/gitlab/hook/create"
        WITH DESTINATION_TOPIC "devops/gitlab/hook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/projects/{value.json.project_id}/hooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "PRIVATE-TOKEN" "{value.json.private_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuser | GET | `/user` | `devops/gitlab/user/get` | `devops/gitlab/user/get/response` |
| Triggerpipeline | POST | `/projects/{id}/trigger/pipeline` | `devops/gitlab/pipeline/trigger` | `devops/gitlab/pipeline/trigger/response` |
| Listreleases | GET | `/projects/{id}/releases` | `devops/gitlab/release/list` | `devops/gitlab/release/list/response` |
| Createissue | POST | `/projects/{id}/issues` | `devops/gitlab/issue/create` | `devops/gitlab/issue/create/response` |
| Downloadgenericpackage | GET | `/projects/{id}/packages/generic/...` | `devops/gitlab/package/generic/get` | `devops/gitlab/package/generic/get/response` |
| Createprojecthook | POST | `/projects/{id}/hooks` | `devops/gitlab/hook/create` | `devops/gitlab/hook/create/response` |

## Auth

1. Create a [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) (or project/group token) with appropriate scopes (`api` / `read_api` as needed), **or** obtain an OAuth 2.0 access token.
2. For pipeline triggers, create a [pipeline trigger token](https://docs.gitlab.com/ci/triggers/) on the project (separate from the PAT).
3. Set connector `BASE_ADDRESS` to `https://gitlab.com/api/v4` or your self-hosted `https://HOST/api/v4`.
4. Pass `private_token` on MQTT JSON payloads so the `PRIVATE-TOKEN` header resolves. For path params, also pass `project_id` / package path fields. For triggers, pass `trigger_token` and `ref`.
5. Store secrets in Hub / `GET SECRET "GITLAB_TOKEN"` (aliases `GITLAB_PRIVATE_TOKEN`, `GITLAB_ACCESS_TOKEN`). Never commit real credentials.
6. A successful check: `GET /user` → **HTTP 200** with `id`. Invalid tokens → **HTTP 401**.

## Example payloads

**getUser:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "private_token": "YOUR_GITLAB_PRIVATE_TOKEN"
}
```

**triggerPipeline:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "123",
  "trigger_token": "YOUR_PIPELINE_TRIGGER_TOKEN",
  "ref": "main"
}
```

**createIssue:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "title": "Coreflux alarm — Zone A",
  "description": "RMS exceeded limit"
}
```

**createProjectHook:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "url": "https://YOUR_PUBLIC_HTTPS_CALLBACK/gitlab-webhook",
  "push_events": true,
  "pipeline_events": true
}
```

## Server / inbound companion

`POST /projects/{id}/hooks` is **client-mode** registration (MQTT → GitLab). GitLab then POSTs events to your `url`. Receiving those callbacks into MQTT requires a separate companion `ENABLE_SERVER` connector — not included in `GitlabRestApi.lot`.

## Deploy notes

* Deploy `GitlabRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/gitlab](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/gitlab)

## Sources

* [GitLab REST API](https://docs.gitlab.com/ee/api/)
* [Authentication](https://docs.gitlab.com/api/rest/authentication/)
* [Pipeline triggers](https://docs.gitlab.com/api/pipeline_triggers/)
* [Releases](https://docs.gitlab.com/api/releases/)
* [Issues](https://docs.gitlab.com/api/issues/)
* [Generic packages](https://docs.gitlab.com/user/packages/generic_packages/)
* [Project webhooks](https://docs.gitlab.com/api/project_webhooks/)
* [OpenAPI v2](https://docs.gitlab.com/ee/api/openapi/openapi_v2.yaml)


# Golioth
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/golioth

Connect Coreflux LoT to the Golioth Management API: manage devices, read and write LightDB State, query LightDB Stream, call RPCs and manage settings and OTA

Technical Preview

## Overview

[Golioth](https://golioth.io) is an IoT device management cloud for microcontroller fleets (Zephyr, nRF Connect SDK, ESP-IDF and ModusToolbox through the Golioth Firmware SDK). Devices talk to Golioth over CoAP, and the [Management API](https://docs.golioth.io/reference/management-api/) exposes the same project to applications. These connectors let the Coreflux broker read device state and time series from Golioth, push desired state, settings and RPC calls back to devices, and drive OTA updates from MQTT.

* **GoliothManagementApi** (`GoliothRestApi.lot`) is a client connector on `https://api.golioth.io` with 45 events.
* **GoliothWebhookReceiver** (`cloud-iot_golioth_webhook.lot`, opt-in, server mode) receives data that a Golioth Pipeline sends with the `webhook` destination, so device stream data reaches MQTT without polling.

The events follow the Management API [OpenAPI definition](https://api.golioth.io/openapi.json).

## Authentication

> [!WARNING]
>
> Golioth API keys are project scoped and can run Management API operations in that project. Keep the key in a Hub secret, map it in with `GET SECRET`, and never publish it on a topic other clients can read.

1. In the Golioth console, open your project and create an API key under **API Keys** (or run `goliothctl apikeys create`).
2. Store it as the secret `GOLIOTH_API_KEY`. Every event takes `"api_key"` in its MQTT payload and sends it in the `x-api-key` header.
3. Every event also takes `"project_id"`. The OTA cohort, package, deployment, location and pipeline events use organization-scoped paths and take `"organization_id"` too.

A missing or wrong key returns `401` with `{"code": 7, "message": "failed to check permissions to access/modify this resource: user not allowed to call method"}`.

## Payload conventions

* Path ids (`device_id`, `tag_id`, `setting_id`, `blueprint_id`, `artifact_id`, `release_id`, `cohort_id`, `deployment_id`, `pipeline_id`) go at the top level of the MQTT payload.
* LightDB paths go in `"path"` without a leading slash, for example `env/temp`.
* Events marked `?{query}` take the query string already URL-encoded, for example `page=0&perPage=100`. Send `"query": ""` when there is nothing to add.
* Request bodies come from `"body"` and are sent as JSON.

## Devices

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetProject | `GET /v1/projects/{project_id}` | `cloud-iot/golioth/project/get` | Credential check: the project behind the API key (API keys are project scoped) |
| ListDevices | `GET /v1/projects/{project_id}/devices?{query}` | `cloud-iot/golioth/device/list` | Devices in the project (paged, max 100 per page); query page=0\&perPage=100 \| tags=\<tagId> \| term=press \| cohortId=... \| statePath=env (send "" for none) |
| GetDevice | `GET /v1/projects/{project_id}/devices/{device_id}` | `cloud-iot/golioth/device/get` | One device: name, hardware ids, tag ids, blueprint, cohort, enabled, status, lastReport, metadata |
| CreateDevice | `POST /v1/projects/{project_id}/devices` | `cloud-iot/golioth/device/create` | **Write.** Create a device; body \{"name": "press-01", "tagIds": \["..."], "blueprintId": "...", "cohortId": "..."} (credentials are not packaged) |
| UpdateDevice | `PATCH /v1/projects/{project_id}/devices/{device_id}` | `cloud-iot/golioth/device/update` | **Write.** Partial device update; body \{"name": "press-01", "addTagId": \["..."], "cohortId": "...", "enabled": true}; cohortId "" leaves the cohort |
| GetDeviceNetwork | `GET /v1/projects/{project_id}/devices/{device_id}/network` | `cloud-iot/golioth/device-network/get` | Network the device belongs to (network id, device count, last seen) |

## LightDB State, LightDB Stream and RPC

LightDB State is the device twin: devices observe paths such as `config/temp` and react when you write them. LightDB Stream holds the time series that devices send to `/.s/` paths.

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetDeviceState | `GET /v1/projects/{project_id}/devices/{device_id}/data/{path}` | `cloud-iot/golioth/state/get` | Catalog: LightDB State at a path, e.g. path env/temp or config (no leading slash) |
| SetDeviceState | `POST /v1/projects/{project_id}/devices/{device_id}/data/{path}` | `cloud-iot/golioth/state/set` | **Write.** Catalog: write desired state at a path the device observes; body \{"min": 20.0, "max": 40.0} or a single value (true, 42, "on") |
| SetStateByTag | `POST /v1/projects/{project_id}/devicesByTag/{tag_id}/data/{path}` | `cloud-iot/golioth/state-by-tag/set` | **Write.** Bulk: write the same LightDB State path on every device with a tag; body as SetDeviceState |
| GetDeviceStream | `GET /v1/projects/{project_id}/devices/{device_id}/stream?{query}` | `cloud-iot/golioth/stream/get` | Time-series points of one device; query start=2026-10-06T00:00:00Z\&end=2026-10-06T12:00:00Z\&perPage=100 \| interval=1h |
| QueryDeviceStream | `POST /v1/projects/{project_id}/devices/{device_id}/stream` | `cloud-iot/golioth/stream/query` | Read (POST): LightDB Stream query for one device; body \{"start": "...Z", "end": "...Z", "query": \{"fields": \[\{"path": "time"}, \{"path": "env.temp", "agg": "avg", "type": "float"}], "timeBucket": "15m"}} |
| QueryProjectStream | `POST /v1/projects/{project_id}/stream` | `cloud-iot/golioth/project-stream/query` | Read (POST): LightDB Stream query across devices; body as QueryDeviceStream plus "deviceId": \[...] or "tags": \[...] |
| CallDeviceRpc | `POST /v1/projects/{project_id}/devices/{device_id}/rpc` | `cloud-iot/golioth/rpc/call` | **Write.** Call a method the firmware registered; body \{"method": "set\_speed", "params": \[1200], "timeout": 10}; device must be online |

## Settings, tags and blueprints

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListSettings | `GET /v1/projects/{project_id}/settings?{query}` | `cloud-iot/golioth/setting/list` | Project, blueprint or device settings; query deviceId=... \| blueprintId=... (send "" for project level) |
| GetDeviceSettings | `GET /v1/projects/{project_id}/devices/{device_id}/settings` | `cloud-iot/golioth/device-setting/get` | Effective settings of one device (project, blueprint and device overrides) |
| CreateSetting | `POST /v1/projects/{project_id}/settings` | `cloud-iot/golioth/setting/create` | **Write.** Create a setting; body \{"key": "LOOP\_DELAY\_S", "dataType": "integer", "value": 60} (+ "deviceId" or "blueprintId" for an override) |
| UpdateSetting | `PATCH /v1/projects/{project_id}/settings/{setting_id}` | `cloud-iot/golioth/setting/update` | **Write.** Change a setting value; body \{"value": 30}; devices pick it up through the Settings service |
| ListTags | `GET /v1/projects/{project_id}/tags?{query}` | `cloud-iot/golioth/tag/list` | Device tags; query page=0\&perPage=100 \| tagName=line-1 |
| CreateTag | `POST /v1/projects/{project_id}/tags` | `cloud-iot/golioth/tag/create` | **Write.** Create a device tag; body \{"name": "line-1"} |
| ListBlueprints | `GET /v1/projects/{project_id}/blueprints?{query}` | `cloud-iot/golioth/blueprint/list` | Blueprints (hardware / firmware families); query page=0\&perPage=100 \| blueprintName=... |
| GetBlueprint | `GET /v1/projects/{project_id}/blueprints/{blueprint_id}` | `cloud-iot/golioth/blueprint/get` | One blueprint: name, board, platform |

## OTA updates

Golioth has two OTA models in the same API. **Artifacts and releases** target devices by tag and blueprint. **Packages, cohorts and deployments** group devices into cohorts, and a new deployment starts updating every device in the cohort right away.

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListArtifacts | `GET /v1/projects/{project_id}/artifacts?{query}` | `cloud-iot/golioth/artifact/list` | Uploaded firmware / file artifacts; query package=main\&perPage=50 \| version=1.2.0 \| blueprintId=... |
| GetArtifact | `GET /v1/projects/{project_id}/artifacts/{artifact_id}` | `cloud-iot/golioth/artifact/get` | One artifact: package, version, size, hash, blueprint |
| CreateArtifact | `POST /v1/artifacts` | `cloud-iot/golioth/artifact/create` | **Write.** Upload an artifact; body \{"projectId": "...", "package": "main", "version": "1.2.0", "content": "\<base64 binary>"} (mind MQTT payload size) |
| ListReleases | `GET /v1/projects/{project_id}/releases?{query}` | `cloud-iot/golioth/release/list` | OTA releases; query rollout=true \| deviceTags=\<tagId> \| perPage=50 (send "" for none) |
| GetRelease | `GET /v1/projects/{project_id}/releases/{release_id}` | `cloud-iot/golioth/release/get` | One release: artifacts, device tags, release tags, rollout flag |
| CreateRelease | `POST /v1/projects/{project_id}/releases` | `cloud-iot/golioth/release/create` | **Write.** Create a release from artifacts; body \{"artifactIds": \["..."], "deviceTagIds": \["..."], "releaseTags": \["v1.2.0"], "rollout": false} |
| UpdateRelease | `PATCH /v1/projects/{project_id}/releases/{release_id}` | `cloud-iot/golioth/release/update` | **Write.** Start or stop a rollout, retarget tags; body \{"rollout": true} \| \{"addDeviceTagId": \["..."]} |
| ListPackages | `GET /v1/organizations/{organization_id}/projects/{project_id}/packages?{query}` | `cloud-iot/golioth/package/list` | OTA packages (upgradeable components: main firmware, modem, ML model); query page=0\&perPage=100 |
| CreatePackage | `POST /v1/organizations/{organization_id}/projects/{project_id}/packages` | `cloud-iot/golioth/package/create` | **Write.** Create a package; body \{"packageId": "main", "description": "Main firmware", "metadata": \{"board": "nrf9160dk"}} |
| ListCohorts | `GET /v1/organizations/{organization_id}/projects/{project_id}/cohorts?{query}` | `cloud-iot/golioth/cohort/list` | Cohorts (device groups that share a deployment); query page=0\&perPage=100 |
| GetCohort | `GET /v1/organizations/{organization_id}/projects/{project_id}/cohorts/{cohort_id}` | `cloud-iot/golioth/cohort/get` | One cohort and its active deployment |
| CreateCohort | `POST /v1/organizations/{organization_id}/projects/{project_id}/cohorts` | `cloud-iot/golioth/cohort/create` | **Write.** Create a cohort; body \{"name": "porto-line-1"}; add devices with UpdateDevice cohortId |
| ListDeployments | `GET /v1/organizations/{organization_id}/projects/{project_id}/cohorts/{cohort_id}/deployments?{query}` | `cloud-iot/golioth/deployment/list` | Deployments of a cohort; query page=0\&perPage=50 \| name=... |
| GetDeployment | `GET /v1/organizations/{organization_id}/projects/{project_id}/cohorts/{cohort_id}/deployments/{deployment_id}` | `cloud-iot/golioth/deployment/get` | One deployment: artifacts and creation time |
| CreateDeployment | `POST /v1/organizations/{organization_id}/projects/{project_id}/cohorts/{cohort_id}/deployments` | `cloud-iot/golioth/deployment/create` | **Write.** Deploy artifacts to every device in the cohort (devices start updating immediately); body \{"name": "1.2.0", "artifactIds": \["..."]} |
| ListOtaEvents | `GET /v1/organizations/{organization_id}/projects/{project_id}/ota-events?{query}` | `cloud-iot/golioth/ota-event/list` | OTA progress events from devices; query cohortId=...\&deviceId=...\&startTime=...Z\&limit=100 \| pageToken=... |
| GetOtaEventStats | `GET /v1/organizations/{organization_id}/projects/{project_id}/ota-events/stats?{query}` | `cloud-iot/golioth/ota-event-stats/get` | OTA outcome counts; query cohortId=...\&startTime=...Z (send "" for none) |

## Logs, locations and pipelines

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListDeviceLocations | `GET /v1/organizations/{organization_id}/projects/{project_id}/location?{query}` | `cloud-iot/golioth/location/list` | Latest device locations (Location service); query deviceIds=\<id> (repeat for several, send "" for all) |
| ListLogs | `GET /v1/projects/{project_id}/logs?{query}` | `cloud-iot/golioth/log/list` | Device logs sent with the Golioth logging service; query deviceId=...\&level=error\&start=...Z\&end=...Z \| module=app |
| ListDeviceActivityLogs | `GET /v1/projects/{project_id}/device-activity-logs?{query}` | `cloud-iot/golioth/activity-log/list` | Latest device activity (connects, disconnects, errors); query page=0\&perPage=100 |
| ListFirmwareLogs | `GET /v1/projects/{project_id}/firmware/logs?{query}` | `cloud-iot/golioth/firmware-log/list` | Firmware update state reports; query deviceId=...\&state=... \| version=1.2.0\&target=main |
| ListPipelines | `GET /v1/organizations/{organization_id}/projects/{project_id}/pipelines` | `cloud-iot/golioth/pipeline/list` | Data routing pipelines (filter, transformers, destinations such as webhook) |
| GetPipeline | `GET /v1/organizations/{organization_id}/projects/{project_id}/pipelines/{pipeline_id}` | `cloud-iot/golioth/pipeline/get` | One pipeline; the YAML document is returned base64 encoded |
| CreatePipeline | `POST /v1/organizations/{organization_id}/projects/{project_id}/pipelines` | `cloud-iot/golioth/pipeline/create` | **Write.** Create a pipeline, e.g. the webhook to cloud-iot\_golioth\_webhook.lot; body \{"name": "to-coreflux", "enabled": true, "pipeline": "\<base64 YAML>"} (usage billed) |

## Webhook receiver

Deploy `cloud-iot_golioth_webhook.lot` only if you want Golioth to push data to the broker. It opens HTTP port `9003`. Put a reverse proxy or tunnel with a public TLS certificate in front of it and have it check a shared header, because the connector itself doesn't.

Golioth delivers data through [Pipelines](https://docs.golioth.io/data-routing), which replace the older Output Streams. Create a pipeline in the console (or with `CreatePipeline`, base64-encoding the YAML) that sends data to the [webhook destination](https://docs.golioth.io/data-routing/destinations/webhook):

```yaml theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
filter:
  path: "*"
  content_type: application/cbor
steps:
  - name: to-json
    transformer:
      type: cbor-to-json
      version: v1
  - name: to-coreflux
    transformer:
      type: inject-metadata
      version: v1
    destination:
      type: webhook
      version: v1
      parameters:
        url: https://<public host>/golioth/webhook/stream
        headers:
          x-coreflux-secret: $COREFLUX_WEBHOOK_SECRET
```

Store `COREFLUX_WEBHOOK_SECRET` as a pipeline secret in the Golioth project. The `inject-metadata` step puts `device_id`, `project_id` and `timestamp` in the body, because the receiver only forwards the body to MQTT. Deliveries are published on `cloud-iot/golioth/webhook-stream/received`. Other pipelines can post to `/golioth/webhook/events`, which publishes on `cloud-iot/golioth/webhook-event/received`. Webhook deliveries count as Golioth usage after the free tier.

## Examples

Write alert limits that the device observes at `config/temp`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "<GOLIOTH_API_KEY>", "project_id": "coreflux-porto", "device_id": "<device id>", "path": "config/temp", "body": {"min": 20.0, "max": 40.0}}
```

Get the 15-minute average temperature of one device:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "<GOLIOTH_API_KEY>", "project_id": "coreflux-porto", "device_id": "<device id>", "body": {"start": "2026-10-06T00:00:00Z", "end": "2026-10-06T12:00:00Z", "query": {"fields": [{"path": "time"}, {"path": "env.temp", "alias": "temperature", "agg": "avg", "type": "float"}], "timeBucket": "15m"}}}
```

Call a firmware RPC:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "<GOLIOTH_API_KEY>", "project_id": "coreflux-porto", "device_id": "<device id>", "body": {"method": "set_speed", "params": [1200], "timeout": 10}}
```

Deploy firmware to a cohort:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "<GOLIOTH_API_KEY>", "organization_id": "<org id>", "project_id": "coreflux-porto", "cohort_id": "<cohort id>", "body": {"name": "1.2.0", "artifactIds": ["<artifact id>"]}}
```

LoT actions that wire these events to plant topics:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION GoliothSetTempLimits
ON TOPIC "porto/line-1/temp-limits/set" DO
    SET "key" WITH GET SECRET "GOLIOTH_API_KEY"
    SET "proj" WITH GET SECRET "GOLIOTH_PROJECT_ID"
    SET "dev" WITH GET SECRET "GOLIOTH_DEVICE_ID"
    SET "lo" WITH GET JSON "min" IN PAYLOAD AS STRING
    SET "hi" WITH GET JSON "max" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/golioth/state/set" WITH { "api_key": {key}, "project_id": {proj}, "device_id": {dev}, "path": "config/temp", "body": { "min": {lo}, "max": {hi} } }

DEFINE ACTION GoliothPollDevices
ON EVERY 1 MINUTE DO
    SET "key" WITH GET SECRET "GOLIOTH_API_KEY"
    SET "proj" WITH GET SECRET "GOLIOTH_PROJECT_ID"
    PUBLISH TOPIC "cloud-iot/golioth/device/list" WITH { "api_key": {key}, "project_id": {proj}, "query": "perPage=100&statePath=env" }

DEFINE ACTION GoliothWebhookToPlant
ON TOPIC "cloud-iot/golioth/webhook-stream/received" DO
    SET "dev" WITH (GET JSON "device_id" IN PAYLOAD AS STRING)
    SET "data" WITH (GET JSON "data" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "plant/golioth/" + {dev} + "/stream" WITH {data}
```

## Writes

15 events change data in Golioth or on devices, and each one is marked **Write** above. `CreateDeployment`, `UpdateRelease` with `"rollout": true`, `SetStateByTag` and `CallDeviceRpc` act on devices in the field, so test them on a lab cohort or tag first. No `DELETE` operation is packaged.

## Not packaged

Device credentials (PSKs and certificates), provisioning, API keys, users and access policies, PKI, pipeline secrets, billing and usage, and every `DELETE` are left out of this template.


# Google Address Validation
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-address-validation

LoT connector for the Google Address Validation API: send an address over MQTT and get back the validation result using a Google Maps API key

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Address Validation connector | no |
| `BaseUrl` | string | Google Address Validation base URL without trailing slash (e.g. [https://addressvalidation.googleapis.com](https://addressvalidation.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://addressvalidation.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ValidateAddress` | POST | `/v1:validateAddress?key={value.json.apikey}` | `fleet/google-maps/address/validate` | `fleet/google-maps/address/validate/response` | `apikey`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_ADDRESS_VALIDATION"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleAddressValidation WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://addressvalidation.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ValidateAddress
        WITH SOURCE_TOPIC "fleet/google-maps/address/validate"
        WITH DESTINATION_TOPIC "fleet/google-maps/address/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1:validateAddress?key={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ValidateAddress` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/address/validate/response' &
mosquitto_pub -t 'fleet/google-maps/address/validate' -m '{"apikey": "<apikey>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Google Air Quality
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-air-quality

LoT connector for the Google Air Quality API: look up current air quality conditions for a location from MQTT and publish the response using a Maps API key

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Air Quality connector | no |
| `BaseUrl` | string | Google Air Quality base URL without trailing slash (e.g. [https://airquality.googleapis.com](https://airquality.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://airquality.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CurrentAirQuality` | POST | `/v1/currentConditions:lookup?key={value.json.apikey}` | `fleet/google-maps/airquality/current` | `fleet/google-maps/airquality/current/response` | `apikey`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_AIR_QUALITY"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleAirQuality WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://airquality.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CurrentAirQuality
        WITH SOURCE_TOPIC "fleet/google-maps/airquality/current"
        WITH DESTINATION_TOPIC "fleet/google-maps/airquality/current/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/currentConditions:lookup?key={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `CurrentAirQuality` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/airquality/current/response' &
mosquitto_pub -t 'fleet/google-maps/airquality/current' -m '{"apikey": "<apikey>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Google BigQuery
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-bigquery

Connect Coreflux LoT to Google BigQuery v2: stream rows from MQTT with insertAll, run SQL queries, read job results, and list or create datasets and tables

Technical Preview

## Overview

A client-mode connector for the [BigQuery API v2](https://cloud.google.com/bigquery/docs/reference/rest) that streams MQTT telemetry into BigQuery tables and runs SQL from MQTT:

| Catalog connector event | Endpoint | Notes |
| - | - | - |
| Streaming insert | `POST /bigquery/v2/projects/{p}/datasets/{d}/tables/{t}/insertAll` | [`tabledata.insertAll`](https://cloud.google.com/bigquery/docs/reference/rest/v2/tabledata/insertAll). Row-level failures come back as `HTTP 200` with `insertErrors`. |
| Run SQL | `POST /bigquery/v2/projects/{p}/queries` | [`jobs.query`](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query). Synchronous up to `timeoutMs`; returns `jobReference`, `schema`, `rows`, `jobComplete`. |
| Query results | `GET /bigquery/v2/projects/{p}/queries/{jobId}?location=…&maxResults=…` | [`jobs.getQueryResults`](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/getQueryResults). Poll when `jobComplete` was `false`, or page with more rows. |
| Job status | `GET /bigquery/v2/projects/{p}/jobs/{jobId}?location=…` | `jobs.get`: state, statistics, error result. |
| List datasets | `GET /bigquery/v2/projects/{p}/datasets` | Credential check. |
| Create dataset / table | `POST …/datasets`, `POST …/datasets/{d}/tables` | One-time setup: dataset location and table schema. |
| List tables / rows | `GET …/datasets/{d}/tables`, `GET …/tables/{t}/data?maxResults=…` | Read-back with `tabledata.list`. |

Default `BASE_ADDRESS` is `https://bigquery.googleapis.com`. Replace `YOUR_PROJECT_ID` in the endpoints with your GCP project id. Topics use `data/google-bigquery/<object>/<verb>`.

> [!WARNING]
>
> **Storage Write API is not included.** The BigQuery Storage Write API (and Storage Read API) is gRPC/protobuf only, so a `REST_API` connector can't call it. This template uses the legacy `tabledata.insertAll` streaming endpoint, which is plain HTTPS + JSON. Load jobs with media upload (`/upload/bigquery/v2/…`) and destructive deletes are also left out.

## Auth

BigQuery needs an OAuth 2.0 access token in `Authorization: Bearer …`. The template reads it from the MQTT payload field `access_token`; keep the token in a Hub secret such as `GET SECRET "GOOGLE_BIGQUERY_ACCESS_TOKEN"` and never commit it.

* **Minting the token is out of band.** Exchange a service-account key (signed JWT) for an access token with `gcloud auth print-access-token`, a Google auth SDK, or your own token service, then publish or refresh it. Access tokens expire after about **1 hour**.
* **Scopes:** `https://www.googleapis.com/auth/bigquery` (full), `https://www.googleapis.com/auth/bigquery.insertdata` (streaming insert only), or `https://www.googleapis.com/auth/cloud-platform`.
* **IAM:** the service account needs BigQuery Data Editor on the dataset and BigQuery Job User on the project to run queries.

A `401 UNAUTHENTICATED` response with `Request had invalid authentication credentials` means the token is missing, malformed, or expired.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleBigqueryRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://bigquery.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth (prefer Hub secrets / GET SECRET "GOOGLE_BIGQUERY_ACCESS_TOKEN"):
        #   OAuth access_token on each MQTT payload → Bearer header below (refresh before ~1 h expiry).
        #   Aliases: BIGQUERY_ACCESS_TOKEN, GOOGLE_ACCESS_TOKEN.
        #   {"query":"SELECT 1","useLegacySql":false} → 200 + jobComplete true.
    ADD EVENT ListDatasets
        WITH SOURCE_TOPIC "data/google-bigquery/datasets/list"
        WITH DESTINATION_TOPIC "data/google-bigquery/datasets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/datasets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateDataset
        WITH SOURCE_TOPIC "data/google-bigquery/dataset/create"
        WITH DESTINATION_TOPIC "data/google-bigquery/dataset/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/datasets"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListTables
        WITH SOURCE_TOPIC "data/google-bigquery/tables/list"
        WITH DESTINATION_TOPIC "data/google-bigquery/tables/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/datasets/{value.json.datasetId}/tables"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateTable
        WITH SOURCE_TOPIC "data/google-bigquery/table/create"
        WITH DESTINATION_TOPIC "data/google-bigquery/table/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/datasets/{value.json.datasetId}/tables"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT InsertRows
        WITH SOURCE_TOPIC "data/google-bigquery/rows/insert"
        WITH DESTINATION_TOPIC "data/google-bigquery/rows/insert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/datasets/{value.json.datasetId}/tables/{value.json.tableId}/insertAll"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListRows
        WITH SOURCE_TOPIC "data/google-bigquery/rows/list"
        WITH DESTINATION_TOPIC "data/google-bigquery/rows/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/datasets/{value.json.datasetId}/tables/{value.json.tableId}/data?maxResults={value.json.maxResults}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RunQuery
        WITH SOURCE_TOPIC "data/google-bigquery/query/run"
        WITH DESTINATION_TOPIC "data/google-bigquery/query/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/queries"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetQueryResults
        WITH SOURCE_TOPIC "data/google-bigquery/query/results"
        WITH DESTINATION_TOPIC "data/google-bigquery/query/results/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/queries/{value.json.jobId}?location={value.json.location}&maxResults={value.json.maxResults}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetJob
        WITH SOURCE_TOPIC "data/google-bigquery/job/get"
        WITH DESTINATION_TOPIC "data/google-bigquery/job/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bigquery/v2/projects/YOUR_PROJECT_ID/jobs/{value.json.jobId}?location={value.json.location}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

> [!NOTE]
>
> Request bodies come from `{value.json.body}`, not `{payload}`. The MQTT payload carries control fields (`access_token`, `datasetId`, `tableId`, `jobId`, `location`, `maxResults`) next to a `body` object, and only `body` is sent to Google. Google APIs reject unknown top-level fields with `400 Invalid JSON payload received`.

## Example MQTT payloads

**Create a dataset (topic `data/google-bigquery/dataset/create`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from GOOGLE_BIGQUERY_ACCESS_TOKEN>",
  "body": { "datasetReference": { "projectId": "YOUR_PROJECT_ID", "datasetId": "coreflux_iiot" }, "location": "EU" }
}
```

**Create a telemetry table (topic `data/google-bigquery/table/create`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from GOOGLE_BIGQUERY_ACCESS_TOKEN>",
  "datasetId": "coreflux_iiot",
  "body": {
    "tableReference": { "projectId": "YOUR_PROJECT_ID", "datasetId": "coreflux_iiot", "tableId": "telemetry" },
    "schema": { "fields": [
      { "name": "ts", "type": "TIMESTAMP" },
      { "name": "site", "type": "STRING" },
      { "name": "temperature", "type": "FLOAT" }
    ] }
  }
}
```

**Stream rows (topic `data/google-bigquery/rows/insert`).** `insertId` gives best-effort de-duplication on retries:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from GOOGLE_BIGQUERY_ACCESS_TOKEN>",
  "datasetId": "coreflux_iiot",
  "tableId": "telemetry",
  "body": {
    "skipInvalidRows": false,
    "rows": [
      { "insertId": "porto-1", "json": { "ts": "2026-10-04T21:55:00Z", "site": "porto", "temperature": 21.5 } }
    ]
  }
}
```

A clean insert returns `{"kind":"bigquery#tableDataInsertAllResponse"}`. Rejected rows return `HTTP 200` with `insertErrors` (for example `no such field: pressure.`), so check the response body, not just the status.

**Run SQL (topic `data/google-bigquery/query/run`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from GOOGLE_BIGQUERY_ACCESS_TOKEN>",
  "body": {
    "query": "SELECT site, AVG(temperature) AS avg_t FROM `YOUR_PROJECT_ID.coreflux_iiot.telemetry` GROUP BY site",
    "useLegacySql": false,
    "location": "EU",
    "timeoutMs": 10000
  }
}
```

**Fetch results or job status (topics `data/google-bigquery/query/results`, `data/google-bigquery/job/get`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "access_token": "<from GOOGLE_BIGQUERY_ACCESS_TOKEN>", "jobId": "<jobReference.jobId>", "location": "EU", "maxResults": 100 }
```

> [!TIP]
>
> Always send `location` and `maxResults` for the GET events, since the template puts them in the query string. Use the dataset's location (`US`, `EU`, `europe-west1`, …); jobs outside the US and EU multi-regions are not found without it.

## Quotas and limits

* `insertAll`: up to 10 MB per request; Google recommends about 500 rows per request. Streamed rows are queryable within seconds, but they can't be changed with DML for a short window after insert.
* `jobs.query` waits up to `timeoutMs` (default 10 s). If `jobComplete` is `false`, poll `GetQueryResults` with `jobReference.jobId`.
* On-demand queries are billed by bytes scanned. Use partitioned tables and `WHERE` filters on high-rate telemetry. See [BigQuery quotas](https://cloud.google.com/bigquery/quotas).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [Google Cloud Storage](/latest/lot-language/routes/rest-api-apps/google-cloud-storage)
* [ClickHouse](/latest/lot-language/routes/rest-api-apps/clickhouse)


# Google Cloud Pub/Sub
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-cloud-pub-sub

Connect Coreflux LoT to Google Cloud Pub/Sub: publish messages with attributes, pull, acknowledge or nack them, and create topics and subscriptions over HTTPS

Technical Preview

## Overview

A client-mode connector that moves broker data in and out of [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/docs/overview) over the REST v1 API. Use it to stream plant telemetry into Google Cloud (Dataflow, BigQuery subscriptions, Cloud Run, Vertex AI) or to pull commands and results back into MQTT, without running a gRPC client.

| Event | Request | Notes |
| - | - | - |
| Publish | `POST /v1/projects/{p}/topics/{t}:publish` | `messages[]` with base64 `data`, `attributes`, `orderingKey`; returns `messageIds` |
| Pull | `POST /v1/projects/{p}/subscriptions/{s}:pull` | `{"maxMessages": N}`; returns `receivedMessages[]` with `ackId` |
| Acknowledge | `POST /v1/projects/{p}/subscriptions/{s}:acknowledge` | `{"ackIds": [...]}` from Pull |
| ModifyAckDeadline | `POST /v1/projects/{p}/subscriptions/{s}:modifyAckDeadline` | `ackDeadlineSeconds` 0 = nack (redeliver), 10 to 600 = extend |
| ListTopics | `GET /v1/projects/{p}/topics?pageSize=N` | Smoke / discovery |
| CreateTopic | `PUT /v1/projects/{p}/topics/{t}` | `{}` or labels / retention; 409 if it exists |
| CreateSubscription | `PUT /v1/projects/{p}/subscriptions/{s}` | `topic` full name, `ackDeadlineSeconds`, `enableMessageOrdering`, optional `pushConfig` |

Default `BASE_ADDRESS` is `https://pubsub.googleapis.com` (no trailing slash). `project_id`, `topic` and `subscription` are short ids taken from the MQTT payload. Topics use `data/google-cloud-pub-sub/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** `Authorization: Bearer {value.json.access_token}`, an OAuth 2.0 access token minted from a **service account** with scope `https://www.googleapis.com/auth/pubsub` (or `cloud-platform`). Grant `roles/pubsub.publisher` to publish and `roles/pubsub.subscriber` to pull and acknowledge; creating topics and subscriptions needs `roles/pubsub.editor`. Keep the key in Hub secrets (suggested name `GCP_PUBSUB_ACCESS_TOKEN`) and refresh the token upstream (tokens last about one hour). Never commit keys into the `.lot`.

> [!NOTE]
>
> **Base64 is your job.** Pub/Sub requires `data` to be base64. The connector forwards the payload as-is and does not encode, so encode upstream (for example in a Python script called from an action; `base64` is available) or have the device publish base64. Pulled messages come back base64-encoded too.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleCloudPubSubRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://pubsub.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Publish
        WITH SOURCE_TOPIC "data/google-cloud-pub-sub/messages/publish"
        WITH DESTINATION_TOPIC "data/google-cloud-pub-sub/messages/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/topics/{value.json.topic}:publish"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Pull
        WITH SOURCE_TOPIC "data/google-cloud-pub-sub/messages/pull"
        WITH DESTINATION_TOPIC "data/google-cloud-pub-sub/messages/pull/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/subscriptions/{value.json.subscription}:pull"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Acknowledge
        WITH SOURCE_TOPIC "data/google-cloud-pub-sub/messages/ack"
        WITH DESTINATION_TOPIC "data/google-cloud-pub-sub/messages/ack/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/subscriptions/{value.json.subscription}:acknowledge"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ModifyAckDeadline
        WITH SOURCE_TOPIC "data/google-cloud-pub-sub/messages/ack-deadline"
        WITH DESTINATION_TOPIC "data/google-cloud-pub-sub/messages/ack-deadline/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/subscriptions/{value.json.subscription}:modifyAckDeadline"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListTopics
        WITH SOURCE_TOPIC "data/google-cloud-pub-sub/topics/list"
        WITH DESTINATION_TOPIC "data/google-cloud-pub-sub/topics/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/topics?pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateTopic
        WITH SOURCE_TOPIC "data/google-cloud-pub-sub/topics/create"
        WITH DESTINATION_TOPIC "data/google-cloud-pub-sub/topics/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/topics/{value.json.topic}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateSubscription
        WITH SOURCE_TOPIC "data/google-cloud-pub-sub/subscriptions/create"
        WITH DESTINATION_TOPIC "data/google-cloud-pub-sub/subscriptions/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v1/projects/{value.json.project_id}/subscriptions/{value.json.subscription}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
```

## MQTT examples

**Publish** (`data/google-cloud-pub-sub/messages/publish`), expect **200** `{"messageIds":["..."]}`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "my-plant-project",
  "topic": "press-telemetry",
  "access_token": "ya29.<service-account-access-token>",
  "body": {
    "messages": [
      {
        "data": "eyJEZXZpY2VJZCI6InByZXNzLTAxIiwidGVtcCI6MzcuMn0=",
        "attributes": { "line": "A", "source": "coreflux" },
        "orderingKey": "press-01"
      }
    ]
  }
}
```

`data` above is base64 of `{"DeviceId":"press-01","temp":37.2}`. Up to 1000 messages and 10 MB per request.

**Pull** (`data/google-cloud-pub-sub/messages/pull`), expect **200** with `receivedMessages` (or `{}` when nothing is waiting):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "my-plant-project",
  "subscription": "press-telemetry-coreflux",
  "access_token": "ya29.<service-account-access-token>",
  "body": { "maxMessages": 10 }
}
```

Response shape:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "receivedMessages": [
    {
      "ackId": "RkhRNxkIaFEOT14jPzUgKEUSA...",
      "message": {
        "data": "eyJEZXZpY2VJZCI6InByZXNzLTAxIiwidGVtcCI6MzcuMn0=",
        "attributes": { "line": "A", "source": "coreflux" },
        "messageId": "1234567890",
        "publishTime": "2026-10-05T00:40:00.123Z",
        "orderingKey": "press-01"
      }
    }
  ]
}
```

**Acknowledge** (`data/google-cloud-pub-sub/messages/ack`), expect **200** `{}`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "my-plant-project",
  "subscription": "press-telemetry-coreflux",
  "access_token": "ya29.<service-account-access-token>",
  "body": { "ackIds": ["RkhRNxkIaFEOT14jPzUgKEUSA..."] }
}
```

**ModifyAckDeadline** (`data/google-cloud-pub-sub/messages/ack-deadline`), expect **200** `{}`. Use `0` to nack so the message is redelivered right away:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "my-plant-project",
  "subscription": "press-telemetry-coreflux",
  "access_token": "ya29.<service-account-access-token>",
  "body": { "ackIds": ["RkhRNxkIaFEOT14jPzUgKEUSA..."], "ackDeadlineSeconds": 0 }
}
```

**CreateTopic** (`data/google-cloud-pub-sub/topics/create`), expect **200** with the topic resource:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "my-plant-project",
  "topic": "press-telemetry",
  "access_token": "ya29.<service-account-access-token>",
  "body": { "labels": { "site": "porto" } }
}
```

**CreateSubscription** (`data/google-cloud-pub-sub/subscriptions/create`), expect **200** with the subscription resource:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project_id": "my-plant-project",
  "subscription": "press-telemetry-coreflux",
  "access_token": "ya29.<service-account-access-token>",
  "body": {
    "topic": "projects/my-plant-project/topics/press-telemetry",
    "ackDeadlineSeconds": 30,
    "enableMessageOrdering": true
  }
}
```

**ListTopics** (`data/google-cloud-pub-sub/topics/list`): `{"project_id": "my-plant-project", "page_size": "50", "access_token": "ya29.<service-account-access-token>"}`.

`body` becomes the HTTP body, so control fields (`project_id`, `topic`, `subscription`, `access_token`, `page_size`) are never sent to Google.

## Getting an access token

For a quick test, with the service account active in the Google Cloud CLI:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
gcloud auth print-access-token --impersonate-service-account=coreflux-pubsub@my-plant-project.iam.gserviceaccount.com
```

In production, mint the token from the service account key (JWT bearer grant to `https://oauth2.googleapis.com/token`) in a helper that reads the key from Hub secrets, and refresh it before the one-hour expiry.

## Push subscriptions (companion, not packaged)

Pub/Sub can also **push** messages to an HTTPS endpoint (`pushConfig.pushEndpoint` on CreateSubscription). Each delivery is a `POST` with a JSON envelope `{"message": {"data", "attributes", "messageId", "publishTime", "orderingKey"}, "subscription": "projects/.../subscriptions/..."}`, and a `200`, `201`, `202`, `204` or `102` reply acknowledges it. Receiving pushes needs a separate `ENABLE_SERVER` REST API connector on a publicly reachable HTTPS address (optionally verifying the OIDC token Pub/Sub adds to `Authorization`). That companion connector is not part of this template.

## Notes

* Strict ordering by `orderingKey` needs `enableMessageOrdering` on the subscription and publishing through one regional endpoint (for example `https://europe-west1-pubsub.googleapis.com`).
* Pull can hold the request open for a bounded time when the subscription is empty, so `REQUEST_TIMEOUT` is `120`. `returnImmediately` is deprecated.
* The emulator (`gcloud beta emulators pubsub start`) speaks the same REST API on `http://localhost:8085`, ignores auth, and is handy for local tests. Set `USE_SSL "false"` and point `BASE_ADDRESS` at it.
* Not covered: deletes, seek and snapshots, schemas, IAM policy calls, StreamingPull (gRPC only).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Pub/Sub REST reference](https://cloud.google.com/pubsub/docs/reference/rest)
* [topics.publish](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/publish)
* [subscriptions.pull](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/pull)
* [Push subscriptions](https://cloud.google.com/pubsub/docs/push)
* [Access control](https://cloud.google.com/pubsub/docs/access-control)


# Google Cloud Storage
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-cloud-storage

Use a LoT connector for the Google Cloud Storage JSON API to upload objects, read object metadata and bytes, list buckets, and upload through signed URLs

Technical Preview

## Overview

A client-mode connector for a **curated IIoT object-storage** slice of the [Google Cloud Storage JSON API](https://cloud.google.com/storage/docs/json_api/v1) under `https://storage.googleapis.com`:

| Catalog connector event | Entity / path | Notes | |
| - | - | - | - |
| | `GET /storage/v1/b?project={project}` | ListBuckets for the OAuth identity | |
| (alternate) | `GET /storage/v1/b/{bucket}` | Bucket metadata | |
| POST upload (media) | `POST /upload/storage/v1/b/{bucket}/o?uploadType=media&name=` | Objects.insert media; body = raw bytes | |
| GET object | `GET /storage/v1/b/{bucket}/o/{object}` | Object metadata (JSON) | |
| GET object bytes | `GET …/o/{object}?alt=media` | Object data | |
| PUT/POST to signed URL | \`PUT | POST \` | No Authorization; switch BASE to URL origin |
| Pub/Sub notifications | — | Docs-only; future `ENABLE_SERVER` | |

`BASE_ADDRESS` defaults to `https://storage.googleapis.com` (no trailing slash). JSON API paths use `/storage/v1/...`; media upload uses `/upload/storage/v1/...` on the **same host**. Topics use `storage/google-cloud-storage/<object>/<verb>`.

> [!NOTE]
>
> **Object names:** path segments with `/` must be URL-encoded as `%2F` (e.g. `line-a%2Fsnapshot.json`).

> [!NOTE]
>
> **Signed URL:** set `BASE_ADDRESS` to the signed URL origin only, put path+query in `signed_path`, and omit Bearer — the query string carries the signature. Typical GCS V4 upload signed URLs use **PUT** (`PutSignedurl`); use `PostSignedurl` only when the signer issued POST.

> [!NOTE]
>
> **Pub/Sub / bucket notifications** are not inbound HTTP on this client connector. Receiving notification POSTs needs a separate `ENABLE_SERVER` REST\_API template (not packaged).

> [!NOTE]
>
> Prefer Hub secrets for `GCS_ACCESS_TOKEN` (or `GOOGLE_CLOUD_STORAGE_ACCESS_TOKEN` / `GOOGLE_ACCESS_TOKEN`). Service-account JWT → access-token exchange is out of band.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Google Cloud Storage JSON API curated slice
# Auth: Bearer {value.json.access_token} — or Put/PostSignedurl (no Authorization)
# BASE_ADDRESS: https://storage.googleapis.com

DEFINE CONNECTOR GoogleCloudStorageRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://storage.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/octet-stream"
    ADD EVENT Listbuckets
        WITH SOURCE_TOPIC "storage/google-cloud-storage/buckets/list"
        WITH DESTINATION_TOPIC "storage/google-cloud-storage/buckets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/storage/v1/b?project={value.json.project}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getbucket
        WITH SOURCE_TOPIC "storage/google-cloud-storage/bucket/get"
        WITH DESTINATION_TOPIC "storage/google-cloud-storage/bucket/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/storage/v1/b/{value.json.bucket}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Uploadobjectmedia
        WITH SOURCE_TOPIC "storage/google-cloud-storage/object/upload"
        WITH DESTINATION_TOPIC "storage/google-cloud-storage/object/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/upload/storage/v1/b/{value.json.bucket}/o?uploadType=media&name={value.json.name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getobject
        WITH SOURCE_TOPIC "storage/google-cloud-storage/object/get"
        WITH DESTINATION_TOPIC "storage/google-cloud-storage/object/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/storage/v1/b/{value.json.bucket}/o/{value.json.object}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getobjectmedia
        WITH SOURCE_TOPIC "storage/google-cloud-storage/object/get-media"
        WITH DESTINATION_TOPIC "storage/google-cloud-storage/object/get-media/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/storage/v1/b/{value.json.bucket}/o/{value.json.object}?alt=media"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Putsignedurl
        WITH SOURCE_TOPIC "storage/google-cloud-storage/object/put-signed"
        WITH DESTINATION_TOPIC "storage/google-cloud-storage/object/put-signed/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "{value.json.signed_path}"
        WITH HEADERS
            ADD "Content-Type" "{value.json.content_type}"
        WITH BODY "{payload}"
    ADD EVENT Postsignedurl
        WITH SOURCE_TOPIC "storage/google-cloud-storage/object/post-signed"
        WITH DESTINATION_TOPIC "storage/google-cloud-storage/object/post-signed/response"
        WITH METHOD "POST"
        WITH ENDPOINT "{value.json.signed_path}"
        WITH HEADERS
            ADD "Content-Type" "{value.json.content_type}"
        WITH BODY "{payload}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `GoogleCloudStorageRestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://storage.googleapis.com` |
| Topic prefix | `storage/google-cloud-storage/...` |
| Default Content-Type | `application/octet-stream` |
| Hub status | Technical preview (`WITH STATUS "beta"`) |

## Authentication

### OAuth 2.0 Bearer

Pass a short-lived access token on each MQTT payload:

| MQTT JSON field | HTTP header |
| - | - |
| `access_token` | `Authorization: Bearer …` |

Prefer Hub secrets / `GET SECRET "GCS_ACCESS_TOKEN"` (aliases `GOOGLE_CLOUD_STORAGE_ACCESS_TOKEN`, `GOOGLE_ACCESS_TOKEN`). Scope: `https://www.googleapis.com/auth/devstorage.read_write` (or `.full_control` / `.read_only`). Service-account JWT assertion exchange is **out of band** — use `gcloud`, ADC, or your IdP, then place only the access token in the Hub secret / MQTT payload. Never commit real credentials.

### Signed URLs (recommended for edge)

Generate a time-limited V4 signed URL with `gsutil` / `gcloud` / client libraries. For PutSignedurl:

1. Point `BASE_ADDRESS` at the URL origin.
2. Put path + query into `signed_path`.
3. Omit Authorization — do not re-sign on the broker.

## MQTT topics

| Event | Request topic | Response topic |
| - | - | - |
| ListBuckets | `storage/google-cloud-storage/buckets/list` | `…/response` |
| GetBucket | `storage/google-cloud-storage/bucket/get` | `…/response` |
| UploadObjectMedia | `storage/google-cloud-storage/object/upload` | `…/response` |
| GetObject | `storage/google-cloud-storage/object/get` | `…/response` |
| GetObjectMedia | `storage/google-cloud-storage/object/get-media` | `…/response` |
| PutSignedurl | `storage/google-cloud-storage/object/put-signed` | `…/response` |
| PostSignedurl | `storage/google-cloud-storage/object/post-signed` | `…/response` |

## Example payloads

**ListBuckets:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "project": "my-gcp-project",
  "access_token": "ya29...."
}
```

**Media upload (CSV rollup):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "bucket": "my-iiot-rollups",
  "name": "line-a%2F2026-10-04%2Frollup.csv",
  "content_type": "text/csv",
  "access_token": "ya29....",
  "payload": "ts,device,temp\n2026-10-04T04:01:00Z,sensor-01,72.5\n"
}
```

**Get object metadata:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "bucket": "my-iiot-rollups",
  "object": "line-a%2F2026-10-04%2Frollup.csv",
  "access_token": "ya29...."
}
```

**PutSignedurl:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "signed_path": "/my-iiot-rollups/line-a/snapshot.json?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...&X-Goog-Signature=...",
  "content_type": "application/json",
  "payload": "{\"device\":\"sensor-01\",\"temp\":72.5}"
}
```

## References

* [Objects: insert](https://cloud.google.com/storage/docs/json_api/v1/objects/insert)
* [Objects: get](https://cloud.google.com/storage/docs/json_api/v1/objects/get)
* [Buckets: list](https://cloud.google.com/storage/docs/json_api/v1/buckets/list)
* [V4 signed URLs](https://cloud.google.com/storage/docs/access-control/signed-urls)
* [Discovery document](https://storage.googleapis.com/\$discovery/rest?version=v1)
* [Coreflux REST API Connectors](/latest/lot-language/routes/rest-api-routes)

## Package status


# Google Drive
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-drive

Use a LoT REST API connector for Google Drive API v3 to list and search files, get, create, update or delete file metadata, and upload file content

Technical Preview

## Overview

A client-mode connector for a **curated** slice of [Google Drive API v3](https://developers.google.com/workspace/drive/api/reference/rest/v3) under `https://www.googleapis.com`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET files?q= | `GET /drive/v3/files?q=...&pageSize=...` | Search / list — `q` must be URL-encoded |
| PATCH file metadata | `PATCH /drive/v3/files/{fileId}` | Rename, describe, tag `appProperties`, trash |
| POST upload (advanced) | `POST /upload/drive/v3/files?uploadType=media` | Simple media upload (≤5 MB, content only) |
| (supporting) about.get | `GET /drive/v3/about?fields=user,storageQuota` | Credential check |
| (supporting) files.get | `GET /drive/v3/files/{fileId}` | File metadata |
| (supporting) files.create | `POST /drive/v3/files` | Metadata-only file or folder |
| (supporting) files.delete | `DELETE /drive/v3/files/{fileId}` | Permanent delete (skips trash) |

Default `BASE_ADDRESS` is `https://www.googleapis.com` (no trailing slash). Metadata endpoints start with `/drive/v3/`; media uploads use `/upload/drive/v3/`. Topics use `storage/google-drive/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Search queries:** put the Drive query in `{value.json.q}` already URL-encoded. Example: `name contains 'line-a' and trashed=false` → `name%20contains%20%27line-a%27%20and%20trashed%3Dfalse`. Send `"q": ""` to list everything visible to the token.

> [!NOTE]
>
> **Shared drives:** every event sends `supportsAllDrives=true` and the list event also sends `includeItemsFromAllDrives=true`, so files in shared drives work without extra flags.

> [!NOTE]
>
> Prefer Hub secrets for access tokens (`GET SECRET "GOOGLE_DRIVE_TOKEN"` or `"GOOGLE_ACCESS_TOKEN"`). Scope: `https://www.googleapis.com/auth/drive.file` (least privilege, files the app created or opened) or `https://www.googleapis.com/auth/drive` (full).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Google Drive API v3
# Auth: Bearer {value.json.api_token}
# BASE_ADDRESS: https://www.googleapis.com

DEFINE CONNECTOR GoogleDriveRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://www.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth (prefer Hub secrets / GET SECRET):
        #   OAuth 2.0 access token on each MQTT payload → header below.
        #   Optional: WITH PASSWORD GET SECRET "GOOGLE_DRIVE_TOKEN"
        #     (only if your broker maps PASSWORD into Authorization for REST_API).
        #   Scope: https://www.googleapis.com/auth/drive or .../auth/drive.file
    ADD EVENT GetAbout
        WITH SOURCE_TOPIC "storage/google-drive/about/get"
        WITH DESTINATION_TOPIC "storage/google-drive/about/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/drive/v3/about?fields=user,storageQuota"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT ListFiles
        WITH SOURCE_TOPIC "storage/google-drive/files/list"
        WITH DESTINATION_TOPIC "storage/google-drive/files/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/drive/v3/files?q={value.json.q}&pageSize={value.json.pageSize}&supportsAllDrives=true&includeItemsFromAllDrives=true&fields=nextPageToken,files(id,name,mimeType,size,modifiedTime,parents)"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT GetFile
        WITH SOURCE_TOPIC "storage/google-drive/file/get"
        WITH DESTINATION_TOPIC "storage/google-drive/file/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/drive/v3/files/{value.json.fileId}?supportsAllDrives=true&fields=id,name,mimeType,size,modifiedTime,parents,appProperties,webViewLink"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT CreateFile
        WITH SOURCE_TOPIC "storage/google-drive/file/create"
        WITH DESTINATION_TOPIC "storage/google-drive/file/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/drive/v3/files?supportsAllDrives=true&fields=id,name,mimeType,parents"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT UpdateFile
        WITH SOURCE_TOPIC "storage/google-drive/file/update"
        WITH DESTINATION_TOPIC "storage/google-drive/file/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/drive/v3/files/{value.json.fileId}?supportsAllDrives=true&fields=id,name,mimeType,parents,trashed,appProperties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT DeleteFile
        WITH SOURCE_TOPIC "storage/google-drive/file/delete"
        WITH DESTINATION_TOPIC "storage/google-drive/file/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/drive/v3/files/{value.json.fileId}?supportsAllDrives=true"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT UploadFileMedia
        WITH SOURCE_TOPIC "storage/google-drive/file/upload"
        WITH DESTINATION_TOPIC "storage/google-drive/file/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/upload/drive/v3/files?uploadType=media&supportsAllDrives=true&fields=id,name,mimeType,size"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
```

## Auth

1. Enable **Google Drive API** on a Google Cloud project.
2. Obtain an OAuth 2.0 user access token **or** a service-account access token. A service account has its own Drive: share the target folder (or shared drive) with the service-account email, or use domain-wide delegation in Google Workspace.
3. Scope: `https://www.googleapis.com/auth/drive.file` covers files the connector creates. Use `https://www.googleapis.com/auth/drive` to read or update files created elsewhere. Use `.../drive.metadata.readonly` only if you stick to GET events.
4. Pass `api_token` on each MQTT payload → `Authorization: Bearer {value.json.api_token}`. Prefer Hub secrets / `GET SECRET "GOOGLE_DRIVE_TOKEN"` or `"GOOGLE_ACCESS_TOKEN"`. Never commit real tokens.

Access tokens expire after about one hour. Refresh them outside the connector (service-account JWT exchange or OAuth refresh token) and update the secret.

## MQTT topics

| Event | Source topic | Response topic |
| - | - | - |
| GetAbout | `storage/google-drive/about/get` | `.../about/get/response` |
| ListFiles | `storage/google-drive/files/list` | `.../files/list/response` |
| GetFile | `storage/google-drive/file/get` | `.../file/get/response` |
| CreateFile | `storage/google-drive/file/create` | `.../file/create/response` |
| UpdateFile | `storage/google-drive/file/update` | `.../file/update/response` |
| DeleteFile | `storage/google-drive/file/delete` | `.../file/delete/response` |
| UploadFileMedia | `storage/google-drive/file/upload` | `.../file/upload/response` |

## Example payloads

**Credential check** (`GetAbout`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN"
}
```

**Search a line folder** (`ListFiles`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "q": "%27YOUR_FOLDER_ID%27%20in%20parents%20and%20trashed%3Dfalse",
  "pageSize": 20
}
```

> [!NOTE]
>
> **Body fields:** `CreateFile`, `UpdateFile`, and `UploadFileMedia` send `{payload}` as the body. Google APIs can reject unknown JSON fields (such as `api_token` or `fileId`) with HTTP 400. If your broker forwards the whole payload, publish only Drive file fields and inject the Bearer from a Hub secret or connector wiring.

**Create a per-device folder** (`CreateFile`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "name": "line-a-sensor-01",
  "mimeType": "application/vnd.google-apps.folder",
  "parents": ["YOUR_PARENT_FOLDER_ID"],
  "appProperties": { "deviceId": "line-a-sensor-01", "site": "porto" }
}
```

**Rename and tag a report** (`UpdateFile`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "fileId": "YOUR_FILE_ID",
  "name": "shift-report-2026-10-04.json",
  "description": "Shift A telemetry snapshot",
  "appProperties": { "shift": "A", "status": "final" }
}
```

**Move to trash** (recoverable — prefer this over `DeleteFile`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "fileId": "YOUR_FILE_ID",
  "trashed": true
}
```

**Delete permanently** (`DeleteFile` → HTTP 204):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "fileId": "YOUR_FILE_ID"
}
```

## Uploads (advanced)

`UploadFileMedia` uses `uploadType=media`: the whole MQTT payload becomes the file content (`application/json`, up to 5 MB). Drive names the file `Untitled` with no parent, so follow with `UpdateFile` using the returned `id` to set `name` and move it with `addParents`.

> [!WARNING]
>
> With `uploadType=media`, everything in `{payload}` is stored in the file. Do not put `api_token` in the payload for this event in production. Inject the Bearer from a Hub secret or connector wiring instead, or the token ends up inside the uploaded file.

`uploadType=multipart` (metadata and content in one `multipart/related` request) and `uploadType=resumable` (large files) are not templated. They need a multipart body or a two-step session that a single MQTT JSON payload does not map to cleanly.

## Push notifications

Drive can push change notifications (`files.watch`, `changes.watch`) to an HTTPS webhook. That is a server-mode companion (`ENABLE_SERVER`) and is not part of this client template.

## Quotas and limits

Google Drive API enforces [per-project and per-user quotas](https://developers.google.com/workspace/drive/api/guides/limits). Bursts from many devices can return HTTP 403 `userRateLimitExceeded` or 429. Batch snapshots at the edge and back off on errors.

## Deploy notes

* Deploy **only** `GoogleDriveRestApi.lot` with `-addConnector` / Hub deploy. Do **not** deploy `hub-metadata.lot`.
* Hub listing uses `hub-metadata.lot` (`WITH IMAGE`, `WITH STATUS "beta"`, doclink).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Google Sheets](/latest/lot-language/routes/rest-api-apps/google-sheets)
* [Google Cloud Storage](/latest/lot-language/routes/rest-api-apps/google-cloud-storage)
* [Google Drive API reference](https://developers.google.com/workspace/drive/api/reference/rest/v3)
* Discovery: `https://www.googleapis.com/discovery/v1/apis/drive/v3/rest`


# Google Geolocation
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-geolocation

LoT connector for the Google Geolocation API: estimate a device location from a geolocate request body sent over MQTT, using a Google Maps API key

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Geolocation connector | no |
| `BaseUrl` | string | Google Geolocation base URL without trailing slash (e.g. [https://www.googleapis.com](https://www.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://www.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Geolocate` | POST | `/geolocation/v1/geolocate?key={value.json.apikey}` | `fleet/google-maps/geolocate` | `fleet/google-maps/geolocate/response` | `apikey`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_GEOLOCATION"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleGeolocation WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://www.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Geolocate
        WITH SOURCE_TOPIC "fleet/google-maps/geolocate"
        WITH DESTINATION_TOPIC "fleet/google-maps/geolocate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/geolocation/v1/geolocate?key={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `Geolocate` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/geolocate/response' &
mosquitto_pub -t 'fleet/google-maps/geolocate' -m '{"apikey": "<apikey>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Google Maps Web Services
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-maps-web-services

LoT connector for Google Maps Web Services: geocode addresses, reverse geocode coordinates, and look up elevation and time zone data from MQTT requests

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Maps Web Services connector | no |
| `BaseUrl` | string | Google Maps Web Services base URL without trailing slash (e.g. [https://maps.googleapis.com](https://maps.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://maps.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Geocode` | GET | `/maps/api/geocode/json?key={value.json.apikey}&address={value.json.address}{value.json.params}` | `fleet/google-maps/geocode/get` | `fleet/google-maps/geocode/get/response` | `address`, `apikey`, `params` |
| `ReverseGeocode` | GET | `/maps/api/geocode/json?key={value.json.apikey}&latlng={value.json.latlng}{value.json.params}` | `fleet/google-maps/revgeocode/get` | `fleet/google-maps/revgeocode/get/response` | `apikey`, `latlng`, `params` |
| `Elevation` | GET | `/maps/api/elevation/json?key={value.json.apikey}&locations={value.json.locations}{value.json.params}` | `fleet/google-maps/elevation/get` | `fleet/google-maps/elevation/get/response` | `apikey`, `locations`, `params` |
| `TimeZone` | GET | `/maps/api/timezone/json?key={value.json.apikey}&location={value.json.location}&timestamp={value.json.timestamp}{value.json.params}` | `fleet/google-maps/timezone/get` | `fleet/google-maps/timezone/get/response` | `apikey`, `location`, `params`, `timestamp` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_MAPS_WEB_SERVICES"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleMapsWebServices WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://maps.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Geocode
        WITH SOURCE_TOPIC "fleet/google-maps/geocode/get"
        WITH DESTINATION_TOPIC "fleet/google-maps/geocode/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/maps/api/geocode/json?key={value.json.apikey}&address={value.json.address}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ReverseGeocode
        WITH SOURCE_TOPIC "fleet/google-maps/revgeocode/get"
        WITH DESTINATION_TOPIC "fleet/google-maps/revgeocode/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/maps/api/geocode/json?key={value.json.apikey}&latlng={value.json.latlng}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT Elevation
        WITH SOURCE_TOPIC "fleet/google-maps/elevation/get"
        WITH DESTINATION_TOPIC "fleet/google-maps/elevation/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/maps/api/elevation/json?key={value.json.apikey}&locations={value.json.locations}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT TimeZone
        WITH SOURCE_TOPIC "fleet/google-maps/timezone/get"
        WITH DESTINATION_TOPIC "fleet/google-maps/timezone/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/maps/api/timezone/json?key={value.json.apikey}&location={value.json.location}&timestamp={value.json.timestamp}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `Geocode` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/geocode/get/response' &
mosquitto_pub -t 'fleet/google-maps/geocode/get' -m '{"address": "<address>", "apikey": "<apikey>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Google Places
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-places

LoT connector for Google Places API (New): run text and nearby place searches and get place details from MQTT, using an API key and a field mask header

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

Auth headers used by the template: `X-Goog-Api-Key: {value.json.apikey}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Places connector | no |
| `BaseUrl` | string | Google Places base URL without trailing slash (e.g. [https://places.googleapis.com](https://places.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://places.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `SearchText` | POST | `/v1/places:searchText` | `fleet/google-maps/places/search/text` | `fleet/google-maps/places/search/text/response` | `apikey`, `body`, `fieldmask` |
| `SearchNearby` | POST | `/v1/places:searchNearby` | `fleet/google-maps/places/search/nearby` | `fleet/google-maps/places/search/nearby/response` | `apikey`, `body`, `fieldmask` |
| `GetPlace` | GET | `/v1/places/{value.json.placeid}?languageCode=en{value.json.params}` | `fleet/google-maps/places/get` | `fleet/google-maps/places/get/response` | `apikey`, `fieldmask`, `params`, `placeid` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_PLACES"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GooglePlaces WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://places.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SearchText
        WITH SOURCE_TOPIC "fleet/google-maps/places/search/text"
        WITH DESTINATION_TOPIC "fleet/google-maps/places/search/text/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/places:searchText"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "X-Goog-Api-Key" "{value.json.apikey}"
            ADD "X-Goog-FieldMask" "{value.json.fieldmask}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT SearchNearby
        WITH SOURCE_TOPIC "fleet/google-maps/places/search/nearby"
        WITH DESTINATION_TOPIC "fleet/google-maps/places/search/nearby/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/places:searchNearby"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "X-Goog-Api-Key" "{value.json.apikey}"
            ADD "X-Goog-FieldMask" "{value.json.fieldmask}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetPlace
        WITH SOURCE_TOPIC "fleet/google-maps/places/get"
        WITH DESTINATION_TOPIC "fleet/google-maps/places/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/places/{value.json.placeid}?languageCode=en{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "X-Goog-Api-Key" "{value.json.apikey}"
            ADD "X-Goog-FieldMask" "{value.json.fieldmask}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `SearchText` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/places/search/text/response' &
mosquitto_pub -t 'fleet/google-maps/places/search/text' -m '{"apikey": "<apikey>", "body": {}, "fieldmask": "<fieldmask>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Google Roads
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-roads

LoT connector for the Google Roads API: snap GPS points to roads, find the nearest roads, and look up speed limits along a path from MQTT requests

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Roads connector | no |
| `BaseUrl` | string | Google Roads base URL without trailing slash (e.g. [https://roads.googleapis.com](https://roads.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://roads.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `SnapToRoads` | GET | `/v1/snapToRoads?key={value.json.apikey}&path={value.json.path}{value.json.params}` | `fleet/google-maps/roads/snap` | `fleet/google-maps/roads/snap/response` | `apikey`, `params`, `path` |
| `NearestRoads` | GET | `/v1/nearestRoads?key={value.json.apikey}&points={value.json.points}` | `fleet/google-maps/roads/nearest` | `fleet/google-maps/roads/nearest/response` | `apikey`, `points` |
| `SpeedLimits` | GET | `/v1/speedLimits?key={value.json.apikey}&path={value.json.path}{value.json.params}` | `fleet/google-maps/roads/speedlimits` | `fleet/google-maps/roads/speedlimits/response` | `apikey`, `params`, `path` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_ROADS"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleRoads WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://roads.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SnapToRoads
        WITH SOURCE_TOPIC "fleet/google-maps/roads/snap"
        WITH DESTINATION_TOPIC "fleet/google-maps/roads/snap/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/snapToRoads?key={value.json.apikey}&path={value.json.path}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT NearestRoads
        WITH SOURCE_TOPIC "fleet/google-maps/roads/nearest"
        WITH DESTINATION_TOPIC "fleet/google-maps/roads/nearest/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/nearestRoads?key={value.json.apikey}&points={value.json.points}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT SpeedLimits
        WITH SOURCE_TOPIC "fleet/google-maps/roads/speedlimits"
        WITH DESTINATION_TOPIC "fleet/google-maps/roads/speedlimits/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/speedLimits?key={value.json.apikey}&path={value.json.path}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `SnapToRoads` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/roads/snap/response' &
mosquitto_pub -t 'fleet/google-maps/roads/snap' -m '{"apikey": "<apikey>", "params": "<params>", "path": "<path>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Google Routes
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-routes

LoT connector for the Google Routes API: compute routes with ETAs and route matrices between origins and destinations from MQTT requests

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

Auth headers used by the template: `X-Goog-Api-Key: {value.json.apikey}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Routes connector | no |
| `BaseUrl` | string | Google Routes base URL without trailing slash (e.g. [https://routes.googleapis.com](https://routes.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://routes.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ComputeRoutes` | POST | `/directions/v2:computeRoutes` | `fleet/google-maps/routes/compute` | `fleet/google-maps/routes/compute/response` | `apikey`, `body`, `fieldmask` |
| `ComputeRouteMatrix` | POST | `/distanceMatrix/v2:computeRouteMatrix` | `fleet/google-maps/routes/matrix` | `fleet/google-maps/routes/matrix/response` | `apikey`, `body`, `fieldmask` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_ROUTES"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleRoutes WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://routes.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ComputeRoutes
        WITH SOURCE_TOPIC "fleet/google-maps/routes/compute"
        WITH DESTINATION_TOPIC "fleet/google-maps/routes/compute/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/directions/v2:computeRoutes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "X-Goog-Api-Key" "{value.json.apikey}"
            ADD "X-Goog-FieldMask" "{value.json.fieldmask}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ComputeRouteMatrix
        WITH SOURCE_TOPIC "fleet/google-maps/routes/matrix"
        WITH DESTINATION_TOPIC "fleet/google-maps/routes/matrix/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/distanceMatrix/v2:computeRouteMatrix"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "X-Goog-Api-Key" "{value.json.apikey}"
            ADD "X-Goog-FieldMask" "{value.json.fieldmask}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ComputeRoutes` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/routes/compute/response' &
mosquitto_pub -t 'fleet/google-maps/routes/compute' -m '{"apikey": "<apikey>", "body": {}, "fieldmask": "<fieldmask>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Google Sheets
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-sheets

Client-mode REST API connector for a curated Google Sheets API v4 slice: get/append/update values, batchUpdate, batchGet, and spreadsheet metadata

Technical Preview

## Overview

A client-mode connector for a **curated** slice of [Google Sheets API v4](https://developers.google.com/sheets/api/reference/rest) under `https://sheets.googleapis.com`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET values/\{range} | `GET /v4/spreadsheets/{spreadsheetId}/values/{range}` | A1 notation — Bearer OAuth / SA token |
| POST values/\{range}:append | `POST /v4/spreadsheets/{spreadsheetId}/values/{range}:append` | One row (or more) per MQTT message — `valueInputOption` required |
| PUT values/\{range} | `PUT /v4/spreadsheets/{spreadsheetId}/values/{range}` | Live cell / overwrite — `valueInputOption` required |
| values.batchUpdate | `POST /v4/spreadsheets/{spreadsheetId}/values:batchUpdate` | Multi-range write — body `valueInputOption` + `data[]` |
| (supporting) values.batchGet | `GET /v4/spreadsheets/{spreadsheetId}/values:batchGet?{ranges_query}` | Multi-range read |
| (supporting) spreadsheets.get | `GET /v4/spreadsheets/{spreadsheetId}` | Metadata |

Default `BASE_ADDRESS` is `https://sheets.googleapis.com` (no trailing slash). Topics use `storage/google-sheets/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **A1 encoding:** put the sheet range in `{value.json.range}`. URL-encode `!` as `%21` and `:` as `%3A` if the publisher or broker does not encode path segments (example: `Sheet1!A1:D10` → `Sheet1%21A1%3AD10`).

> [!NOTE]
>
> **valueInputOption:** Append and Update require query `valueInputOption=RAW` or `USER_ENTERED`. BatchUpdate places `valueInputOption` in the JSON body with `data` (array of ValueRange).

> [!NOTE]
>
> Prefer Hub secrets for access tokens (`GET SECRET "GOOGLE_SHEETS_TOKEN"` or `"GOOGLE_ACCESS_TOKEN"`). Scope: `https://www.googleapis.com/auth/spreadsheets`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Google Sheets API v4
# Auth: Bearer {value.json.api_token}
# BASE_ADDRESS: https://sheets.googleapis.com

DEFINE CONNECTOR GoogleSheetsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://sheets.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getvalues
        WITH SOURCE_TOPIC "storage/google-sheets/values/get"
        WITH DESTINATION_TOPIC "storage/google-sheets/values/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v4/spreadsheets/{value.json.spreadsheetId}/values/{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Appendvalues
        WITH SOURCE_TOPIC "storage/google-sheets/values/append"
        WITH DESTINATION_TOPIC "storage/google-sheets/values/append/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v4/spreadsheets/{value.json.spreadsheetId}/values/{value.json.range}:append?valueInputOption={value.json.valueInputOption}&insertDataOption={value.json.insertDataOption}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Updatevalues
        WITH SOURCE_TOPIC "storage/google-sheets/values/update"
        WITH DESTINATION_TOPIC "storage/google-sheets/values/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v4/spreadsheets/{value.json.spreadsheetId}/values/{value.json.range}?valueInputOption={value.json.valueInputOption}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Batchupdatevalues
        WITH SOURCE_TOPIC "storage/google-sheets/values/batch-update"
        WITH DESTINATION_TOPIC "storage/google-sheets/values/batch-update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v4/spreadsheets/{value.json.spreadsheetId}/values:batchUpdate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Batchgetvalues
        WITH SOURCE_TOPIC "storage/google-sheets/values/batch-get"
        WITH DESTINATION_TOPIC "storage/google-sheets/values/batch-get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v4/spreadsheets/{value.json.spreadsheetId}/values:batchGet?{value.json.ranges_query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getspreadsheet
        WITH SOURCE_TOPIC "storage/google-sheets/spreadsheet/get"
        WITH DESTINATION_TOPIC "storage/google-sheets/spreadsheet/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v4/spreadsheets/{value.json.spreadsheetId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Auth

1. Enable **Google Sheets API** on a Google Cloud project.
2. Obtain an OAuth 2.0 user access token **or** a service-account access token (share the target spreadsheet with the service-account email).
3. Scope: `https://www.googleapis.com/auth/spreadsheets` (read/write). Use `.../spreadsheets.readonly` only if you stick to GET events.
4. Pass `api_token` on each MQTT payload → `Authorization: Bearer {value.json.api_token}`. Prefer Hub secrets / `GET SECRET "GOOGLE_SHEETS_TOKEN"` or `"GOOGLE_ACCESS_TOKEN"`. Never commit real tokens.

## MQTT topics

| Event | Source topic | Response topic |
| - | - | - |
| Getvalues | `storage/google-sheets/values/get` | `.../get/response` |
| Appendvalues | `storage/google-sheets/values/append` | `.../append/response` |
| Updatevalues | `storage/google-sheets/values/update` | `.../update/response` |
| Batchupdatevalues | `storage/google-sheets/values/batch-update` | `.../batch-update/response` |
| Batchgetvalues | `storage/google-sheets/values/batch-get` | `.../batch-get/response` |
| Getspreadsheet | `storage/google-sheets/spreadsheet/get` | `.../get/response` |

## Example payloads

**Append telemetry row** (body is `{payload}` — include Sheets `values` array):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "spreadsheetId": "YOUR_SPREADSHEET_ID",
  "range": "Sheet1%21A%3AA",
  "valueInputOption": "USER_ENTERED",
  "insertDataOption": "INSERT_ROWS",
  "values": [["2026-10-04T05:00:00Z", "line-a-sensor-01", 72.5, "OK"]]
}
```

**Update live cell:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "spreadsheetId": "YOUR_SPREADSHEET_ID",
  "range": "Sheet1%21B2",
  "valueInputOption": "USER_ENTERED",
  "values": [["OK"]]
}
```

**Batch get** (`ranges_query` is the full query string after `?`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_OAUTH_OR_SA_ACCESS_TOKEN",
  "spreadsheetId": "YOUR_SPREADSHEET_ID",
  "ranges_query": "ranges=Sheet1%21A1%3AB2&ranges=Sheet1%21D1%3AE2"
}
```

## Quotas and limits

Google Sheets API enforces [per-project quotas](https://developers.google.com/sheets/api/limits). Burst append/update from many devices can hit write quotas — batch or throttle at the edge when possible.

## Deploy notes

* Deploy **only** `GoogleSheetsRestApi.lot` with `-addConnector` / Hub deploy. Do **not** deploy `hub-metadata.lot`.
* Hub listing uses `hub-metadata.lot` (`WITH IMAGE`, `WITH STATUS "beta"`, doclink).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Google Sheets API reference](https://developers.google.com/sheets/api/reference/rest)
* Discovery: `https://sheets.googleapis.com/$discovery/rest?version=v4`


# Google Weather
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/google-weather

LoT connector for the Google Weather API: get current conditions, hourly forecasts and public weather alerts for a latitude and longitude from MQTT

Technical Preview

## Overview

Client-mode REST API connectors for Google Maps Platform: geocoding, elevation, time zone, device geolocation, Routes API ETAs and matrices, Roads API snap to roads and speed limits, Places search, Address Validation, Weather and Air Quality.

This is one of the templates in the Google Maps Platform REST API app (`google-maps-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter key= (Geocoding, Elevation, Time Zone, Geolocation, Roads, Address Validation, Weather, Air Quality)", "X-Goog-Api-Key header + required X-Goog-FieldMask header (Routes API, Places API (New))"]
* **secrets**: \["GOOGLE\_MAPS\_API\_KEY"]
* **note**: OAuth 2.0 service accounts not packaged (Fleet Engine and Route Optimization need OAuth).

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Google Weather connector | no |
| `BaseUrl` | string | Google Weather base URL without trailing slash (e.g. [https://weather.googleapis.com](https://weather.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://weather.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CurrentWeather` | GET | `/v1/currentConditions:lookup?key={value.json.apikey}&location.latitude={value.json.lat}&location.longitude={value.json.lng}{value.json.params}` | `fleet/google-maps/weather/current` | `fleet/google-maps/weather/current/response` | `apikey`, `lat`, `lng`, `params` |
| `HourlyForecast` | GET | `/v1/forecast/hours:lookup?key={value.json.apikey}&location.latitude={value.json.lat}&location.longitude={value.json.lng}{value.json.params}` | `fleet/google-maps/weather/forecast/hours` | `fleet/google-maps/weather/forecast/hours/response` | `apikey`, `lat`, `lng`, `params` |
| `WeatherAlerts` | GET | `/v1/publicAlerts:lookup?key={value.json.apikey}&location.latitude={value.json.lat}&location.longitude={value.json.lng}{value.json.params}` | `fleet/google-maps/weather/alerts` | `fleet/google-maps/weather/alerts/response` | `apikey`, `lat`, `lng`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode GOOGLE_WEATHER"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GoogleWeather WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://weather.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CurrentWeather
        WITH SOURCE_TOPIC "fleet/google-maps/weather/current"
        WITH DESTINATION_TOPIC "fleet/google-maps/weather/current/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/currentConditions:lookup?key={value.json.apikey}&location.latitude={value.json.lat}&location.longitude={value.json.lng}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT HourlyForecast
        WITH SOURCE_TOPIC "fleet/google-maps/weather/forecast/hours"
        WITH DESTINATION_TOPIC "fleet/google-maps/weather/forecast/hours/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast/hours:lookup?key={value.json.apikey}&location.latitude={value.json.lat}&location.longitude={value.json.lng}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT WeatherAlerts
        WITH SOURCE_TOPIC "fleet/google-maps/weather/alerts"
        WITH DESTINATION_TOPIC "fleet/google-maps/weather/alerts/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/publicAlerts:lookup?key={value.json.apikey}&location.latitude={value.json.lat}&location.longitude={value.json.lng}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `CurrentWeather` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/google-maps/weather/current/response' &
mosquitto_pub -t 'fleet/google-maps/weather/current' -m '{"apikey": "<apikey>", "lat": "<lat>", "lng": "<lng>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Grafana
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/grafana

Use a LoT REST API connector for Grafana to check health, create and list annotations from MQTT alarms, search dashboards and list Alertmanager alerts

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of the [Grafana HTTP API](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET health | `GET /api/health` | Typically **unauthenticated**; expect `"database":"ok"` |
| POST annotations from MQTT | `POST /api/annotations` | Bearer service account token; `text` required; `annotations:create` |
| GET annotations | `GET /api/annotations` | Bearer; query `from` / `to` / `limit` (epoch ms) |
| GET search | `GET /api/search` | Bearer; dashboards / folders (`type=dash-db` or `dash-folder`) |
| GET Alertmanager alerts | `GET /api/alertmanager/grafana/api/v2/alerts` | Bearer; Grafana-managed Alertmanager API v2 |

Default `BASE_ADDRESS` is `https://grafana.example.com` (replace with your OSS / Enterprise host or Grafana Cloud stack URL). Topics use `itsm/grafana/<object>/<verb>`.

> [!NOTE]
>
> Self-hosted and Grafana Cloud share the same `/api/…` path layout. Cloud stacks use a host like `https://&lt;stack&gt;.grafana.net`. Do not put a trailing slash on `BASE_ADDRESS`.

> [!NOTE]
>
> Prefer Hub secrets for the service account token. Create annotation (write) needs a token with `annotations:create`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Grafana (health, annotations, search, alerts curated slice)
# Auth: Authorization: Bearer {value.json.token} (service account)
# BASE_ADDRESS: https://grafana.example.com  (or Cloud stack URL)
# GetHealth: no Authorization header

DEFINE CONNECTOR GrafanaRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://grafana.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Gethealth
        WITH SOURCE_TOPIC "itsm/grafana/health/get"
        WITH DESTINATION_TOPIC "itsm/grafana/health/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/health"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Createannotation
        WITH SOURCE_TOPIC "itsm/grafana/annotation/create"
        WITH DESTINATION_TOPIC "itsm/grafana/annotation/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/annotations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Listannotations
        WITH SOURCE_TOPIC "itsm/grafana/annotation/list"
        WITH DESTINATION_TOPIC "itsm/grafana/annotation/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/annotations?from={value.json.from}&to={value.json.to}&limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Searchdashboards
        WITH SOURCE_TOPIC "itsm/grafana/dashboard/search"
        WITH DESTINATION_TOPIC "itsm/grafana/dashboard/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/search?query={value.json.query}&type={value.json.type}&limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Listalerts
        WITH SOURCE_TOPIC "itsm/grafana/alert/list"
        WITH DESTINATION_TOPIC "itsm/grafana/alert/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/alertmanager/grafana/api/v2/alerts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Gethealth | GET | `/api/health` | `itsm/grafana/health/get` | `itsm/grafana/health/get/response` |
| Createannotation | POST | `/api/annotations` | `itsm/grafana/annotation/create` | `itsm/grafana/annotation/create/response` |
| Listannotations | GET | `/api/annotations?from=&to=&limit=` | `itsm/grafana/annotation/list` | `itsm/grafana/annotation/list/response` |
| Searchdashboards | GET | `/api/search?query=&type=&limit=` | `itsm/grafana/dashboard/search` | `itsm/grafana/dashboard/search/response` |
| Listalerts | GET | `/api/alertmanager/grafana/api/v2/alerts` | `itsm/grafana/alert/list` | `itsm/grafana/alert/list/response` |

## Auth

**Service account token (preferred):**

1. Create a Grafana [service account](https://grafana.com/docs/grafana/latest/administration/service-accounts/) and token with roles covering annotation create/read, folder/dashboard search, and alerting read as needed.
2. Set connector `BASE_ADDRESS` to your Grafana host (no trailing slash).
3. Pass `token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.token}`
4. Store the token in Hub secrets / `GET SECRET "GRAFANA_TOKEN"`. Never commit real credentials.

**Basic auth (alternative):**

1. Use a Grafana user (or service account) password / token.
2. Configure `WITH USERNAME` / `WITH PASSWORD GET SECRET "GRAFANA_PASSWORD"` and remove Bearer headers from the events.

**Legacy API keys:** historically sent as Bearer; prefer service accounts.

**GetHealth:** omit Authorization — most installs expose `/api/health` publicly.

## Example payloads

**Health:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{}
```

**Create annotation from alarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_SERVICE_ACCOUNT_TOKEN",
  "text": "Vibration above threshold — Zone A",
  "tags": ["coreflux", "ot", "vibration"],
  "time": 1728000000000
}
```

**List annotations:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_SERVICE_ACCOUNT_TOKEN",
  "from": "1727913600000",
  "to": "1728000000000",
  "limit": "50"
}
```

**Search dashboards:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_SERVICE_ACCOUNT_TOKEN",
  "query": "plant",
  "type": "dash-db",
  "limit": "25"
}
```

**List alerts:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_SERVICE_ACCOUNT_TOKEN"
}
```

## Deploy notes

* Deploy **`GrafanaRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/grafana](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/grafana)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Grafana Loki
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/grafana-loki

Connect Coreflux LoT to Grafana Loki: push MQTT messages as log streams, run LogQL queries, and list labels, label values and series on Loki or Grafana Cloud

Technical Preview

## Overview

A client-mode connector for the [Grafana Loki HTTP API](https://grafana.com/docs/loki/latest/reference/loki-http-api/). Use it to ship broker events (alarms, state changes, machine messages) into Loki as log lines labelled with their MQTT topic, so they sit next to your other logs in Grafana, and to pull LogQL results (error counts per line, the last alarms on a machine) back onto MQTT.

| Event | Request | Notes |
| - | - | - |
| Ready | `GET /ready` | No tenant or auth. `200` `ready` |
| BuildInfo | `GET /loki/api/v1/status/buildinfo` | Loki version and revision |
| Push | `POST /loki/api/v1/push` | JSON streams body. `204` with an empty body |
| Query | `POST /loki/api/v1/query` | Instant LogQL query (form body), usually a metric query |
| QueryRange | `POST /loki/api/v1/query_range` | LogQL over a time range (form body): log lines or a metric matrix |
| Labels | `GET /loki/api/v1/labels?since={since}` | Label names seen in the window |
| LabelValues | `GET /loki/api/v1/label/{label}/values?since={since}` | Values of one label, for example every `topic` |
| Series | `POST /loki/api/v1/series` | Streams matching a selector (form body) |

Set `BASE_ADDRESS` to your Loki URL with no trailing slash, for example `http://loki.plant.local:3100` (keep `USE_SSL "false"` for plain HTTP) or `https://logs-prod-XXX.grafana.net` for Grafana Cloud (set `USE_SSL "true"`). Topics use `analytics/loki/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Tenant and auth:** every `/loki/api/v1` event sends `X-Scope-OrgID: {value.json.tenant}`. Multi-tenant Loki (`auth_enabled: true`) rejects calls without it (`401 no org id`) and keeps each tenant's data separate. Single-tenant Loki ignores the header. Loki OSS has no built-in authentication, so put it behind a gateway or reverse proxy. Grafana Cloud Logs uses Basic auth with your numeric Loki user id and a Cloud access policy token (`logs:write`, `logs:read`); set them on the connector with `WITH USERNAME` and `WITH PASSWORD GET SECRET "GRAFANA_CLOUD_LOKI_TOKEN"` so the token stays in Hub secrets and out of MQTT payloads. Never commit tokens.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR GrafanaLokiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_LOKI_HOST:3100"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Ready
        WITH SOURCE_TOPIC "analytics/loki/ready/get"
        WITH DESTINATION_TOPIC "analytics/loki/ready/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ready"
        WITH HEADERS
            ADD "Accept" "text/plain"
    ADD EVENT BuildInfo
        WITH SOURCE_TOPIC "analytics/loki/buildinfo/get"
        WITH DESTINATION_TOPIC "analytics/loki/buildinfo/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/loki/api/v1/status/buildinfo"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Push
        WITH SOURCE_TOPIC "analytics/loki/push"
        WITH DESTINATION_TOPIC "analytics/loki/push/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/loki/api/v1/push"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "X-Scope-OrgID" "{value.json.tenant}"
        WITH BODY "{value.json.body}"
    ADD EVENT Query
        WITH SOURCE_TOPIC "analytics/loki/query"
        WITH DESTINATION_TOPIC "analytics/loki/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/loki/api/v1/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "X-Scope-OrgID" "{value.json.tenant}"
        WITH BODY "query={value.json.query}&limit={value.json.limit}"
    ADD EVENT QueryRange
        WITH SOURCE_TOPIC "analytics/loki/query_range"
        WITH DESTINATION_TOPIC "analytics/loki/query_range/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/loki/api/v1/query_range"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "X-Scope-OrgID" "{value.json.tenant}"
        WITH BODY "query={value.json.query}&since={value.json.since}&limit={value.json.limit}&direction={value.json.direction}"
    ADD EVENT Labels
        WITH SOURCE_TOPIC "analytics/loki/labels/list"
        WITH DESTINATION_TOPIC "analytics/loki/labels/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/loki/api/v1/labels?since={value.json.since}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Scope-OrgID" "{value.json.tenant}"
    ADD EVENT LabelValues
        WITH SOURCE_TOPIC "analytics/loki/labels/values"
        WITH DESTINATION_TOPIC "analytics/loki/labels/values/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/loki/api/v1/label/{value.json.label}/values?since={value.json.since}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Scope-OrgID" "{value.json.tenant}"
    ADD EVENT Series
        WITH SOURCE_TOPIC "analytics/loki/series/list"
        WITH DESTINATION_TOPIC "analytics/loki/series/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/loki/api/v1/series"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "X-Scope-OrgID" "{value.json.tenant}"
        WITH BODY "match[]={value.json.match}&since={value.json.since}"
```

## MQTT examples

**Push broker messages as log lines.** Publish to `analytics/loki/push`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"tenant": "plant-porto", "body": {"streams": [{"stream": {"source": "coreflux", "topic": "plant/line1/press01/alarm", "level": "error"}, "values": [["1791158400000000000", "overtemp alarm press01", {"machine": "press01"}]]}]}}
```

Each stream is one label set; `values` holds `[timestamp, line]` pairs, where the timestamp is Unix time in **nanoseconds as a string**. An optional third element adds structured metadata (high-cardinality fields such as a machine or order id) without creating new streams. Loki answers **204** with an empty body. Keep labels few and low-cardinality (site, line, topic, level) and put values in the line or in structured metadata.

**Read recent lines.** Publish to `analytics/loki/query_range`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"tenant": "plant-porto", "query": "{source=\"coreflux\", topic=~\"plant/line1/.*\"} |= \"overtemp\"", "since": "1h", "limit": "100", "direction": "backward"}
```

Reply (tested on Loki 3.7.8):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"status":"success","data":{"resultType":"streams","result":[{"stream":{"detected_level":"error","level":"error","machine":"press01","service_name":"unknown_service","source":"coreflux","topic":"plant/line1/press01/alarm"},"values":[["1791158400000000000","overtemp alarm press01"]]}],"stats":{}}}
```

Structured metadata (`machine`) comes back as extra keys in `stream`, and `stats` (trimmed here) carries query statistics. Loki 3.x also adds `service_name` (set to `unknown_service` when the stream has no service label) and `detected_level` on ingest.

**Count alarms per level.** Publish a metric query to `analytics/loki/query` (instant vector) or `analytics/loki/query_range` (matrix):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"tenant": "plant-porto", "query": "sum by (level) (count_over_time({source=\"coreflux\"} [5m]))", "limit": "100"}
```

**List the MQTT topics Loki has seen.** Publish to `analytics/loki/labels/values`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"tenant": "plant-porto", "label": "topic", "since": "24h"}
```

`Labels` takes `{"tenant","since"}` and `Series` takes `{"tenant","match","since"}`, where `match` is a stream selector such as `{source="coreflux"}`.

## Notes

* Query events send `application/x-www-form-urlencoded` bodies, so LogQL braces, quotes and `|=` work as written. A query that contains `&`, `+` or `%` must be percent-encoded by whoever builds the payload.
* `since` accepts Loki durations (`5m`, `1h`, `24h`). Instead of `since` you can edit the template to send `start` and `end` (Unix nanoseconds or RFC 3339).
* Loki rejects lines older than `reject_old_samples_max_age` (one week by default) and, per stream, lines far out of order; send current timestamps.
* Errors: bad LogQL returns **400** with the parse error; a malformed push returns **400**; a missing tenant on multi-tenant Loki returns **401** `no org id`. Grafana Cloud returns **401** for a wrong user id or token.
* Not covered: the protobuf/snappy push format, OTLP ingest (`/otlp/v1/logs`), tail over WebSocket, index stats and volume, log deletion, and ruler / alerting APIs.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Loki HTTP API reference](https://grafana.com/docs/loki/latest/reference/loki-http-api/)
* [LogQL](https://grafana.com/docs/loki/latest/query/)
* [Loki labels best practices](https://grafana.com/docs/loki/latest/get-started/labels/bp-labels/)
* [Grafana Loki on GitHub](https://github.com/grafana/loki)


# Help Scout
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/help-scout

Connect Coreflux LoT to Help Scout Inbox API 2.0: open conversations from alarms, add notes and replies, tag, snooze or assign them, and manage customers

Technical Preview

## Overview

A client-mode connector for the [Help Scout Inbox API 2.0](https://developer.helpscout.com/mailbox-api/) (formerly the Mailbox API) that connects plant and product events to a shared support inbox. A connected machine that raises an alarm can open a conversation for the customer who owns it, the team can add internal notes while it is handled, and the conversation can be closed, reassigned, tagged or snoozed when the alarm clears. Customer profiles and conversation custom fields can be kept current from live data, and manual workflows can be run on conversations.

Help Scout now calls mailboxes "inboxes", but the API paths still use `/v2/mailboxes`. Topics use `crm/help-scout/<object>/<verb>`; each response is published on `<source topic>/response`.

## Authentication

Help Scout uses OAuth 2.0. For a broker integration the client credentials flow fits best (see [Help Scout authentication](https://developer.helpscout.com/mailbox-api/overview/authentication/)):

1. In Help Scout, open **Your Profile > My Apps** and create an app. A redirect URL is required but unused for client credentials, so any placeholder works.

2. Publish the app id and secret to `crm/help-scout/oauth/token` (event `TokenGet`):

   ```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
   {"body": {"grant_type": "client_credentials", "client_id": "<app id>", "client_secret": "<app secret>"}}
   ```

3. Read `access_token` from `crm/help-scout/oauth/token/response`. It is valid for 172800 seconds (two days). Pass it as `access_token` in every other payload; the connector sends `Authorization: Bearer <token>`. Request a new token only when a call answers 401.

The credentials must belong to an active, invited Help Scout user, or every call answers 401.

> [!WARNING]
>
> Store the app id and secret as broker secrets (for example `HELPSCOUT_APP_ID` and `HELPSCOUT_APP_SECRET`) and have a LoT action add them with `GET SECRET`. The token response topic carries a live token: restrict it with a rule, never retain it, and do not put tokens in retained messages.

## Payload fields

| Field | Used by | Notes |
| - | - | - |
| `body` | `TokenGet` and every POST / PUT / PATCH event | JSON object (or JSON Patch array for `CustomerUpdate`) sent as the request body |
| `access_token` | every event except `TokenGet` | Bearer token from `TokenGet` |
| `id` | `...Get`, updates, notes, replies, tags, fields, snooze, threads, `WorkflowRun` | Help Scout id of the inbox, conversation, customer or workflow |
| `query` | `UsersList`, `ConversationsList`, `CustomersList`, `OrganizationsList`, `ConversationsReport` | URL-encoded query string |

## Events

| Event | Method | Endpoint | Source topic | Write |
| - | - | - | - | - |
| `TokenGet` | `POST` | `/v2/oauth2/token` | `crm/help-scout/oauth/token` | |
| `CurrentUser` | `GET` | `/v2/users/me` | `crm/help-scout/users/me/get` | |
| `UsersList` | `GET` | `/v2/users?{query}` | `crm/help-scout/users/list` | |
| `MailboxesList` | `GET` | `/v2/mailboxes` | `crm/help-scout/mailboxes/list` | |
| `MailboxGet` | `GET` | `/v2/mailboxes/{id}` | `crm/help-scout/mailboxes/get` | |
| `MailboxFieldsList` | `GET` | `/v2/mailboxes/{id}/fields` | `crm/help-scout/mailboxes/fields/list` | |
| `MailboxFoldersList` | `GET` | `/v2/mailboxes/{id}/folders` | `crm/help-scout/mailboxes/folders/list` | |
| `ConversationsList` | `GET` | `/v2/conversations?{query}` | `crm/help-scout/conversations/list` | |
| `ConversationGet` | `GET` | `/v2/conversations/{id}` | `crm/help-scout/conversations/get` | |
| `ConversationCreate` | `POST` | `/v2/conversations` | `crm/help-scout/conversations/create` | yes |
| `ConversationUpdate` | `PATCH` | `/v2/conversations/{id}` | `crm/help-scout/conversations/update` | yes |
| `ThreadsList` | `GET` | `/v2/conversations/{id}/threads` | `crm/help-scout/conversations/threads/list` | |
| `NoteCreate` | `POST` | `/v2/conversations/{id}/notes` | `crm/help-scout/conversations/notes/create` | yes |
| `ReplyCreate` | `POST` | `/v2/conversations/{id}/reply` | `crm/help-scout/conversations/reply` | yes |
| `CustomerThreadCreate` | `POST` | `/v2/conversations/{id}/customer` | `crm/help-scout/conversations/customer-thread/create` | yes |
| `ConversationTagsUpdate` | `PUT` | `/v2/conversations/{id}/tags` | `crm/help-scout/conversations/tags/update` | yes |
| `ConversationFieldsUpdate` | `PUT` | `/v2/conversations/{id}/fields` | `crm/help-scout/conversations/fields/update` | yes |
| `ConversationSnooze` | `PUT` | `/v2/conversations/{id}/snooze` | `crm/help-scout/conversations/snooze/update` | yes |
| `CustomersList` | `GET` | `/v2/customers?{query}` | `crm/help-scout/customers/list` | |
| `CustomerGet` | `GET` | `/v2/customers/{id}` | `crm/help-scout/customers/get` | |
| `CustomerCreate` | `POST` | `/v2/customers` | `crm/help-scout/customers/create` | yes |
| `CustomerUpdate` | `PATCH` | `/v2/customers/{id}` | `crm/help-scout/customers/update` | yes |
| `CustomerPropertiesList` | `GET` | `/v2/customer-properties` | `crm/help-scout/customer-properties/list` | |
| `TagsList` | `GET` | `/v2/tags` | `crm/help-scout/tags/list` | |
| `OrganizationsList` | `GET` | `/v2/organizations?{query}` | `crm/help-scout/organizations/list` | |
| `WebhooksList` | `GET` | `/v2/webhooks` | `crm/help-scout/webhooks/list` | |
| `WorkflowsList` | `GET` | `/v2/workflows` | `crm/help-scout/workflows/list` | |
| `WorkflowRun` | `POST` | `/v2/workflows/{id}/run` | `crm/help-scout/workflows/run` | yes |
| `ConversationsReport` | `GET` | `/v2/reports/conversations?{query}` | `crm/help-scout/reports/conversations/get` | |

Creates answer `201 Created` with the new id in the `Resource-ID` header and an empty body; updates, tags, fields, snooze and workflow runs answer `204 No Content`. `ConversationUpdate` and `CustomerUpdate` use JSON Patch. No delete events are packaged on purpose. Writes count as two requests against the account rate limit, which depends on the plan (`X-RateLimit-Limit-Minute`, `X-RateLimit-Remaining-Minute`, `X-RateLimit-Retry-After`). The conversations report needs a Plus or Pro plan.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HelpScoutRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.helpscout.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TokenGet
        WITH SOURCE_TOPIC "crm/help-scout/oauth/token"
        WITH DESTINATION_TOPIC "crm/help-scout/oauth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/oauth2/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CurrentUser
        WITH SOURCE_TOPIC "crm/help-scout/users/me/get"
        WITH DESTINATION_TOPIC "crm/help-scout/users/me/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT UsersList
        WITH SOURCE_TOPIC "crm/help-scout/users/list"
        WITH DESTINATION_TOPIC "crm/help-scout/users/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxesList
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/list"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxGet
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/get"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxFieldsList
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/fields/list"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/fields/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes/{value.json.id}/fields"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MailboxFoldersList
        WITH SOURCE_TOPIC "crm/help-scout/mailboxes/folders/list"
        WITH DESTINATION_TOPIC "crm/help-scout/mailboxes/folders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/mailboxes/{value.json.id}/folders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConversationsList
        WITH SOURCE_TOPIC "crm/help-scout/conversations/list"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/conversations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConversationGet
        WITH SOURCE_TOPIC "crm/help-scout/conversations/get"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/conversations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ConversationCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/create"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationUpdate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/conversations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ThreadsList
        WITH SOURCE_TOPIC "crm/help-scout/conversations/threads/list"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/threads/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/threads"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT NoteCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/notes/create"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/notes/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/notes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ReplyCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/reply"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/reply/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/reply"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomerThreadCreate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/customer-thread/create"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/customer-thread/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/customer"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationTagsUpdate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/tags/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/tags/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationFieldsUpdate
        WITH SOURCE_TOPIC "crm/help-scout/conversations/fields/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/fields/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/fields"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationSnooze
        WITH SOURCE_TOPIC "crm/help-scout/conversations/snooze/update"
        WITH DESTINATION_TOPIC "crm/help-scout/conversations/snooze/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/conversations/{value.json.id}/snooze"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomersList
        WITH SOURCE_TOPIC "crm/help-scout/customers/list"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/customers?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CustomerGet
        WITH SOURCE_TOPIC "crm/help-scout/customers/get"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/customers/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CustomerCreate
        WITH SOURCE_TOPIC "crm/help-scout/customers/create"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/customers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomerUpdate
        WITH SOURCE_TOPIC "crm/help-scout/customers/update"
        WITH DESTINATION_TOPIC "crm/help-scout/customers/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/customers/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CustomerPropertiesList
        WITH SOURCE_TOPIC "crm/help-scout/customer-properties/list"
        WITH DESTINATION_TOPIC "crm/help-scout/customer-properties/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/customer-properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT TagsList
        WITH SOURCE_TOPIC "crm/help-scout/tags/list"
        WITH DESTINATION_TOPIC "crm/help-scout/tags/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT OrganizationsList
        WITH SOURCE_TOPIC "crm/help-scout/organizations/list"
        WITH DESTINATION_TOPIC "crm/help-scout/organizations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/organizations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT WebhooksList
        WITH SOURCE_TOPIC "crm/help-scout/webhooks/list"
        WITH DESTINATION_TOPIC "crm/help-scout/webhooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT WorkflowsList
        WITH SOURCE_TOPIC "crm/help-scout/workflows/list"
        WITH DESTINATION_TOPIC "crm/help-scout/workflows/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/workflows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT WorkflowRun
        WITH SOURCE_TOPIC "crm/help-scout/workflows/run"
        WITH DESTINATION_TOPIC "crm/help-scout/workflows/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/workflows/{value.json.id}/run"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationsReport
        WITH SOURCE_TOPIC "crm/help-scout/reports/conversations/get"
        WITH DESTINATION_TOPIC "crm/help-scout/reports/conversations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/reports/conversations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Examples

**Conversation from an alarm**

Get a `mailboxId` from `crm/help-scout/mailboxes/list`, then publish to `crm/help-scout/conversations/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "body": {"subject": "Press 7 overtemperature (E42)", "mailboxId": 85, "type": "email", "customer": {"email": "ops@acme.com"}, "threads": [{"type": "customer", "customer": {"email": "ops@acme.com"}, "text": "Press 7 reported E42 at 13:55"}], "tags": ["alarm", "line-4"]}}
```

Add `"assignTo": <user or team id>` to assign it, or `"imported": true` to log it without sending email.

**Note and close**

While the alarm is handled, publish to `crm/help-scout/conversations/notes/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "id": "<conversation id>", "body": {"text": "Spindle temperature back to 61 C"}}
```

When it clears, publish `{"access_token": "...", "id": "<conversation id>", "body": {"op": "replace", "path": "/status", "value": "closed"}}` to `crm/help-scout/conversations/update`.

**Open alarms in an inbox**

Publish to `crm/help-scout/conversations/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "query": "mailbox=85&status=active&tag=alarm"}
```

**Custom fields**

Read field ids with `crm/help-scout/mailboxes/fields/list` (`"id": "<mailbox id>"`), then publish to `crm/help-scout/conversations/fields/update`. The list replaces all non-system fields:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "id": "<conversation id>", "body": {"fields": [{"id": 104, "value": "E42"}]}}
```

## Receiving webhooks

Help Scout can notify the broker about conversation and customer events (for example `convo.created`, `convo.status`, `convo.assigned`). Register the webhook once in Help Scout (or with `POST /v2/webhooks`), with a 40-character secret, and receive it with a separate server-mode REST\_API connector that enables `ENABLE_SERVER`. Help Scout signs each delivery with HMAC-SHA1 in the `X-HelpScout-Signature` header; verify it before trusting the payload. `WebhooksList` shows which webhooks are configured.

## Troubleshooting

| Symptom | Cause |
| - | - |
| 400 `invalid_client` on `TokenGet` | Wrong app id or secret, or `grant_type` missing |
| 401 `invalid_token` | Token expired (two days) or missing; request a new one |
| 401 on every call with a fresh token | The app's user is not an active, invited user |
| `ConversationsReport` refused | Reporting endpoints are only available on Plus and Pro plans |
| 412 on a note or reply | The conversation has 100 threads or is locked by an age policy |
| 429 | Account rate limit; wait for `X-RateLimit-Retry-After` seconds |

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Help Scout Inbox API 2.0 reference](https://developer.helpscout.com/mailbox-api/)


# Here Browse
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-browse

LoT connector for the HERE Browse API: browse places around a coordinate from an MQTT request and publish the results, using a HERE API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Browse connector | no |
| `BaseUrl` | string | Here Browse base URL without trailing slash (e.g. [https://browse.search.hereapi.com](https://browse.search.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://browse.search.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Browse` | GET | `/v1/browse?apiKey={value.json.apikey}&at={value.json.at}{value.json.params}` | `fleet/here/places/browse` | `fleet/here/places/browse/response` | `apikey`, `at`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_BROWSE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereBrowse WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://browse.search.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Browse
        WITH SOURCE_TOPIC "fleet/here/places/browse"
        WITH DESTINATION_TOPIC "fleet/here/places/browse/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/browse?apiKey={value.json.apikey}&at={value.json.at}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `Browse` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/places/browse/response' &
mosquitto_pub -t 'fleet/here/places/browse' -m '{"apikey": "<apikey>", "at": "<at>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Discover
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-discover

LoT connector for the HERE Discover API: search for places and addresses by free text near a location from an MQTT request using a HERE API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Discover connector | no |
| `BaseUrl` | string | Here Discover base URL without trailing slash (e.g. [https://discover.search.hereapi.com](https://discover.search.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://discover.search.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Discover` | GET | `/v1/discover?apiKey={value.json.apikey}&q={value.json.q}&at={value.json.at}{value.json.params}` | `fleet/here/places/discover` | `fleet/here/places/discover/response` | `apikey`, `at`, `params`, `q` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_DISCOVER"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereDiscover WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://discover.search.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Discover
        WITH SOURCE_TOPIC "fleet/here/places/discover"
        WITH DESTINATION_TOPIC "fleet/here/places/discover/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/discover?apiKey={value.json.apikey}&q={value.json.q}&at={value.json.at}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `Discover` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/places/discover/response' &
mosquitto_pub -t 'fleet/here/places/discover' -m '{"apikey": "<apikey>", "at": "<at>", "params": "<params>", "q": "<q>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Geocode
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-geocode

LoT connector for the HERE Geocode API: convert a free text address into coordinates from an MQTT request and publish the result, using a HERE API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Geocode connector | no |
| `BaseUrl` | string | Here Geocode base URL without trailing slash (e.g. [https://geocode.search.hereapi.com](https://geocode.search.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://geocode.search.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Geocode` | GET | `/v1/geocode?apiKey={value.json.apikey}&q={value.json.q}{value.json.params}` | `fleet/here/geocode/get` | `fleet/here/geocode/get/response` | `apikey`, `params`, `q` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_GEOCODE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereGeocode WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://geocode.search.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Geocode
        WITH SOURCE_TOPIC "fleet/here/geocode/get"
        WITH DESTINATION_TOPIC "fleet/here/geocode/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/geocode?apiKey={value.json.apikey}&q={value.json.q}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `Geocode` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/geocode/get/response' &
mosquitto_pub -t 'fleet/here/geocode/get' -m '{"apikey": "<apikey>", "params": "<params>", "q": "<q>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# HERE Geocoding
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-geocoding

Client-mode REST API connector for a curated HERE Geocoding v1 slice: forward geocode a query

Technical Preview

# HERE Geocoding

Client-mode REST API connector for a curated HERE Geocoding v1 slice: forward geocode a query.

* Hub category: **Maps**.
* Base: `https://geocode.search.hereapi.com`

## Template reference

Generated from the shipped broker template `here-geocoding` (`-connectorCode HERE_GEOCODING`). It lists every event the template defines.

### Auth

The template sets no auth header. Check the event headers below.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the HERE Geocoding connector | no |
| `BaseUrl` | string | HERE Geocoding base URL without trailing slash (e.g. [https://geocode.search.hereapi.com](https://geocode.search.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://geocode.search.hereapi.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Geocode` | GET | `/v1/geocode?q={value.json.query}&apiKey={value.json.api_token}` | `maps/here/geocode` | `maps/here/geocode/response` | `api_token`, `query` |
| `Revgeocode` | GET | `/v1/revgeocode?at={value.json.at}&apiKey={value.json.api_token}` | `maps/here/revgeocode` | `maps/here/revgeocode/response` | `api_token`, `at` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_GEOCODING"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereGeocodingRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://geocode.search.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Geocode
        WITH SOURCE_TOPIC "maps/here/geocode"
        WITH DESTINATION_TOPIC "maps/here/geocode/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/geocode?q={value.json.query}&apiKey={value.json.api_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Revgeocode
        WITH SOURCE_TOPIC "maps/here/revgeocode"
        WITH DESTINATION_TOPIC "maps/here/revgeocode/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/revgeocode?at={value.json.at}&apiKey={value.json.api_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Geocode` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'maps/here/geocode/response' &
mosquitto_pub -t 'maps/here/geocode' -m '{"api_token": "<api_token>", "query": "<query>"}'
```


# Here Isoline
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-isoline

LoT connector for the HERE Isoline Routing API v8: calculate isolines by time or distance range from an origin for a transport mode, plus a version check

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Isoline connector | no |
| `BaseUrl` | string | Here Isoline base URL without trailing slash (e.g. [https://isoline.router.hereapi.com](https://isoline.router.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://isoline.router.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CalculateIsolines` | GET | `/v8/isolines?apiKey={value.json.apikey}&transportMode={value.json.transportMode}&origin={value.json.origin}&range[type]={value.json.range_type}&range[values]={value.json.range_values}{value.json.params}` | `fleet/here/isolines/calculate` | `fleet/here/isolines/calculate/response` | `apikey`, `origin`, `params`, `range_type`, `range_values`, `transportMode` |
| `IsolineVersion` | GET | `/v8/version` | `fleet/here/isolines/version` | `fleet/here/isolines/version/response` | none |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_ISOLINE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereIsoline WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://isoline.router.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CalculateIsolines
        WITH SOURCE_TOPIC "fleet/here/isolines/calculate"
        WITH DESTINATION_TOPIC "fleet/here/isolines/calculate/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/isolines?apiKey={value.json.apikey}&transportMode={value.json.transportMode}&origin={value.json.origin}&range[type]={value.json.range_type}&range[values]={value.json.range_values}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT IsolineVersion
        WITH SOURCE_TOPIC "fleet/here/isolines/version"
        WITH DESTINATION_TOPIC "fleet/here/isolines/version/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/version"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `CalculateIsolines` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/isolines/calculate/response' &
mosquitto_pub -t 'fleet/here/isolines/calculate' -m '{"apikey": "<apikey>", "origin": "<origin>", "params": "<params>", "range_type": "<range_type>", "range_values": "<range_values>", "transportMode": "<transportMode>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Lookup
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-lookup

LoT connector for the HERE Lookup API: fetch full details for a place or address by its HERE ID from an MQTT request, using a HERE API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Lookup connector | no |
| `BaseUrl` | string | Here Lookup base URL without trailing slash (e.g. [https://lookup.search.hereapi.com](https://lookup.search.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://lookup.search.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Lookup` | GET | `/v1/lookup?apiKey={value.json.apikey}&id={value.json.id}{value.json.params}` | `fleet/here/places/lookup` | `fleet/here/places/lookup/response` | `apikey`, `id`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_LOOKUP"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereLookup WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://lookup.search.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Lookup
        WITH SOURCE_TOPIC "fleet/here/places/lookup"
        WITH DESTINATION_TOPIC "fleet/here/places/lookup/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/lookup?apiKey={value.json.apikey}&id={value.json.id}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `Lookup` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/places/lookup/response' &
mosquitto_pub -t 'fleet/here/places/lookup' -m '{"apikey": "<apikey>", "id": "<id>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Matrix
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-matrix

LoT connector for the HERE Matrix Routing API v8: calculate travel time and distance matrices between many points, list matrix profiles and check the version

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Matrix connector | no |
| `BaseUrl` | string | Here Matrix base URL without trailing slash (e.g. [https://matrix.router.hereapi.com](https://matrix.router.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://matrix.router.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CalculateMatrix` | POST | `/v8/matrix?apiKey={value.json.apikey}&async=false` | `fleet/here/matrix/calculate` | `fleet/here/matrix/calculate/response` | `apikey`, `body` |
| `ListMatrixProfiles` | GET | `/v8/profiles?apiKey={value.json.apikey}` | `fleet/here/matrix/profiles/get` | `fleet/here/matrix/profiles/get/response` | `apikey` |
| `MatrixVersion` | GET | `/v8/version` | `fleet/here/matrix/version` | `fleet/here/matrix/version/response` | none |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_MATRIX"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereMatrix WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://matrix.router.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CalculateMatrix
        WITH SOURCE_TOPIC "fleet/here/matrix/calculate"
        WITH DESTINATION_TOPIC "fleet/here/matrix/calculate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v8/matrix?apiKey={value.json.apikey}&async=false"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListMatrixProfiles
        WITH SOURCE_TOPIC "fleet/here/matrix/profiles/get"
        WITH DESTINATION_TOPIC "fleet/here/matrix/profiles/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/profiles?apiKey={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT MatrixVersion
        WITH SOURCE_TOPIC "fleet/here/matrix/version"
        WITH DESTINATION_TOPIC "fleet/here/matrix/version/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/version"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `CalculateMatrix` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/matrix/calculate/response' &
mosquitto_pub -t 'fleet/here/matrix/calculate' -m '{"apikey": "<apikey>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Multi Reverse Geocode
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-multi-reverse-geocode

LoT connector for the HERE Multi Reverse Geocode API: convert a batch of coordinates into addresses in a single POST request from MQTT, using a HERE API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Multi Reverse Geocode connector | no |
| `BaseUrl` | string | Here Multi Reverse Geocode base URL without trailing slash (e.g. [https://multi-revgeocode.search.hereapi.com](https://multi-revgeocode.search.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://multi-revgeocode.search.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `MultiReverseGeocode` | POST | `/v1/multi-revgeocode?apiKey={value.json.apikey}{value.json.params}` | `fleet/here/revgeocode/multi` | `fleet/here/revgeocode/multi/response` | `apikey`, `body`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_MULTI_REVERSE_GEOCODE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereMultiReverseGeocode WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://multi-revgeocode.search.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT MultiReverseGeocode
        WITH SOURCE_TOPIC "fleet/here/revgeocode/multi"
        WITH DESTINATION_TOPIC "fleet/here/revgeocode/multi/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/multi-revgeocode?apiKey={value.json.apikey}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "text/plain; charset=UTF-8"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `MultiReverseGeocode` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/revgeocode/multi/response' &
mosquitto_pub -t 'fleet/here/revgeocode/multi' -m '{"apikey": "<apikey>", "body": {}, "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Reverse Geocode
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-reverse-geocode

LoT connector for the HERE Reverse Geocode API: convert a latitude and longitude into the nearest address from an MQTT request, using a HERE API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Reverse Geocode connector | no |
| `BaseUrl` | string | Here Reverse Geocode base URL without trailing slash (e.g. [https://revgeocode.search.hereapi.com](https://revgeocode.search.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://revgeocode.search.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ReverseGeocode` | GET | `/v1/revgeocode?apiKey={value.json.apikey}&at={value.json.at}{value.json.params}` | `fleet/here/revgeocode/get` | `fleet/here/revgeocode/get/response` | `apikey`, `at`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_REVERSE_GEOCODE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereReverseGeocode WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://revgeocode.search.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ReverseGeocode
        WITH SOURCE_TOPIC "fleet/here/revgeocode/get"
        WITH DESTINATION_TOPIC "fleet/here/revgeocode/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/revgeocode?apiKey={value.json.apikey}&at={value.json.at}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ReverseGeocode` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/revgeocode/get/response' &
mosquitto_pub -t 'fleet/here/revgeocode/get' -m '{"apikey": "<apikey>", "at": "<at>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Route Matching
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-route-matching

LoT connector for HERE Route Matching v8: match a GPS trace to road links and publish the matched route from an MQTT request, using a HERE API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Route Matching connector | no |
| `BaseUrl` | string | Here Route Matching base URL without trailing slash (e.g. [https://routematching.hereapi.com](https://routematching.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://routematching.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `MatchRouteLinks` | POST | `/v8/match/routelinks?apikey={value.json.apikey}&routeMatch=1&mode={value.json.mode}{value.json.params}` | `fleet/here/route-matching/match` | `fleet/here/route-matching/match/response` | `apikey`, `body`, `mode`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_ROUTE_MATCHING"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereRouteMatching WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://routematching.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT MatchRouteLinks
        WITH SOURCE_TOPIC "fleet/here/route-matching/match"
        WITH DESTINATION_TOPIC "fleet/here/route-matching/match/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v8/match/routelinks?apikey={value.json.apikey}&routeMatch=1&mode={value.json.mode}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "text/plain"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `MatchRouteLinks` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/route-matching/match/response' &
mosquitto_pub -t 'fleet/here/route-matching/match' -m '{"apikey": "<apikey>", "body": {}, "mode": "<mode>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Routing
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-routing

Connect Coreflux LoT to HERE Routing v8 over MQTT: calculate routes by GET or POST, fetch a route by handle, import a route and check the API version

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Routing connector | no |
| `BaseUrl` | string | Here Routing base URL without trailing slash (e.g. [https://router.hereapi.com](https://router.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://router.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CalculateRoutes` | GET | `/v8/routes?apiKey={value.json.apikey}&transportMode={value.json.transportMode}&origin={value.json.origin}&destination={value.json.destination}{value.json.params}` | `fleet/here/routes/calculate` | `fleet/here/routes/calculate/response` | `apikey`, `destination`, `origin`, `params`, `transportMode` |
| `CalculateRoutesPost` | POST | `/v8/routes?apiKey={value.json.apikey}&transportMode={value.json.transportMode}&origin={value.json.origin}&destination={value.json.destination}{value.json.params}` | `fleet/here/routes/calculate/post` | `fleet/here/routes/calculate/post/response` | `apikey`, `body`, `destination`, `origin`, `params`, `transportMode` |
| `GetRouteByHandle` | GET | `/v8/routes/{value.json.handle}?apiKey={value.json.apikey}&transportMode={value.json.transportMode}{value.json.params}` | `fleet/here/routes/handle/get` | `fleet/here/routes/handle/get/response` | `apikey`, `handle`, `params`, `transportMode` |
| `ImportRoute` | POST | `/v8/import?apiKey={value.json.apikey}&transportMode={value.json.transportMode}{value.json.params}` | `fleet/here/routes/import` | `fleet/here/routes/import/response` | `apikey`, `body`, `params`, `transportMode` |
| `RoutingVersion` | GET | `/v8/version` | `fleet/here/routes/version` | `fleet/here/routes/version/response` | none |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_ROUTING"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereRouting WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://router.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CalculateRoutes
        WITH SOURCE_TOPIC "fleet/here/routes/calculate"
        WITH DESTINATION_TOPIC "fleet/here/routes/calculate/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/routes?apiKey={value.json.apikey}&transportMode={value.json.transportMode}&origin={value.json.origin}&destination={value.json.destination}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT CalculateRoutesPost
        WITH SOURCE_TOPIC "fleet/here/routes/calculate/post"
        WITH DESTINATION_TOPIC "fleet/here/routes/calculate/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v8/routes?apiKey={value.json.apikey}&transportMode={value.json.transportMode}&origin={value.json.origin}&destination={value.json.destination}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetRouteByHandle
        WITH SOURCE_TOPIC "fleet/here/routes/handle/get"
        WITH DESTINATION_TOPIC "fleet/here/routes/handle/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/routes/{value.json.handle}?apiKey={value.json.apikey}&transportMode={value.json.transportMode}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ImportRoute
        WITH SOURCE_TOPIC "fleet/here/routes/import"
        WITH DESTINATION_TOPIC "fleet/here/routes/import/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v8/import?apiKey={value.json.apikey}&transportMode={value.json.transportMode}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RoutingVersion
        WITH SOURCE_TOPIC "fleet/here/routes/version"
        WITH DESTINATION_TOPIC "fleet/here/routes/version/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/version"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `CalculateRoutes` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/routes/calculate/response' &
mosquitto_pub -t 'fleet/here/routes/calculate' -m '{"apikey": "<apikey>", "destination": "<destination>", "origin": "<origin>", "params": "<params>", "transportMode": "<transportMode>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Tour Planning
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-tour-planning

LoT connector for HERE Tour Planning v3: solve vehicle tour problems synchronously or async, poll status, fetch the solution or cancel a problem from MQTT

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Tour Planning connector | no |
| `BaseUrl` | string | Here Tour Planning base URL without trailing slash (e.g. [https://tourplanning.hereapi.com](https://tourplanning.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://tourplanning.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `SolveTourProblem` | POST | `/v3/problems?apikey={value.json.apikey}` | `fleet/here/tours/solve` | `fleet/here/tours/solve/response` | `apikey`, `body` |
| `SubmitTourProblemAsync` | POST | `/v3/problems/async?apikey={value.json.apikey}` | `fleet/here/tours/async/submit` | `fleet/here/tours/async/submit/response` | `apikey`, `body` |
| `GetTourProblemStatus` | GET | `/v3/status/{value.json.statusid}?apikey={value.json.apikey}` | `fleet/here/tours/async/status` | `fleet/here/tours/async/status/response` | `apikey`, `statusid` |
| `GetTourSolution` | GET | `/v3/problems/{value.json.problemid}/solution?apikey={value.json.apikey}` | `fleet/here/tours/async/solution` | `fleet/here/tours/async/solution/response` | `apikey`, `problemid` |
| `CancelTourProblem` | PUT | `/v3/problems/{value.json.problemid}/cancel?apikey={value.json.apikey}` | `fleet/here/tours/async/cancel` | `fleet/here/tours/async/cancel/response` | `apikey`, `problemid` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_TOUR_PLANNING"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereTourPlanning WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://tourplanning.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SolveTourProblem
        WITH SOURCE_TOPIC "fleet/here/tours/solve"
        WITH DESTINATION_TOPIC "fleet/here/tours/solve/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/problems?apikey={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT SubmitTourProblemAsync
        WITH SOURCE_TOPIC "fleet/here/tours/async/submit"
        WITH DESTINATION_TOPIC "fleet/here/tours/async/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/problems/async?apikey={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTourProblemStatus
        WITH SOURCE_TOPIC "fleet/here/tours/async/status"
        WITH DESTINATION_TOPIC "fleet/here/tours/async/status/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/status/{value.json.statusid}?apikey={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetTourSolution
        WITH SOURCE_TOPIC "fleet/here/tours/async/solution"
        WITH DESTINATION_TOPIC "fleet/here/tours/async/solution/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/problems/{value.json.problemid}/solution?apikey={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT CancelTourProblem
        WITH SOURCE_TOPIC "fleet/here/tours/async/cancel"
        WITH DESTINATION_TOPIC "fleet/here/tours/async/cancel/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v3/problems/{value.json.problemid}/cancel?apikey={value.json.apikey}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
        WITH BODY ""
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `SolveTourProblem` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/tours/solve/response' &
mosquitto_pub -t 'fleet/here/tours/solve' -m '{"apikey": "<apikey>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Traffic
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-traffic

Connect Coreflux LoT to HERE Traffic v7 over MQTT to read real-time traffic flow, list incidents in an area and get a single incident by ID with an API key

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Traffic connector | no |
| `BaseUrl` | string | Here Traffic base URL without trailing slash (e.g. [https://data.traffic.hereapi.com](https://data.traffic.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://data.traffic.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `TrafficFlow` | GET | `/v7/flow?apiKey={value.json.apikey}&in={value.json.in}&locationReferencing={value.json.locationReferencing}{value.json.params}` | `fleet/here/traffic/flow/get` | `fleet/here/traffic/flow/get/response` | `apikey`, `in`, `locationReferencing`, `params` |
| `TrafficIncidents` | GET | `/v7/incidents?apiKey={value.json.apikey}&in={value.json.in}&locationReferencing={value.json.locationReferencing}{value.json.params}` | `fleet/here/traffic/incidents/get` | `fleet/here/traffic/incidents/get/response` | `apikey`, `in`, `locationReferencing`, `params` |
| `TrafficIncidentById` | GET | `/v7/incidents/{value.json.incidentid}?apiKey={value.json.apikey}&locationReferencing={value.json.locationReferencing}{value.json.params}` | `fleet/here/traffic/incidents/id/get` | `fleet/here/traffic/incidents/id/get/response` | `apikey`, `incidentid`, `locationReferencing`, `params` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_TRAFFIC"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereTraffic WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://data.traffic.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TrafficFlow
        WITH SOURCE_TOPIC "fleet/here/traffic/flow/get"
        WITH DESTINATION_TOPIC "fleet/here/traffic/flow/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/flow?apiKey={value.json.apikey}&in={value.json.in}&locationReferencing={value.json.locationReferencing}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT TrafficIncidents
        WITH SOURCE_TOPIC "fleet/here/traffic/incidents/get"
        WITH DESTINATION_TOPIC "fleet/here/traffic/incidents/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/incidents?apiKey={value.json.apikey}&in={value.json.in}&locationReferencing={value.json.locationReferencing}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT TrafficIncidentById
        WITH SOURCE_TOPIC "fleet/here/traffic/incidents/id/get"
        WITH DESTINATION_TOPIC "fleet/here/traffic/incidents/id/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v7/incidents/{value.json.incidentid}?apiKey={value.json.apikey}&locationReferencing={value.json.locationReferencing}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `TrafficFlow` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/traffic/flow/get/response' &
mosquitto_pub -t 'fleet/here/traffic/flow/get' -m '{"apikey": "<apikey>", "in": "<in>", "locationReferencing": "<locationReferencing>", "params": "<params>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Here Waypoints Sequence
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/here-waypoints-sequence

LoT connector for HERE Waypoints Sequence v8: find the optimal order of waypoints from a start point and transport mode, triggered from an MQTT topic

Technical Preview

## Overview

Client-mode REST API connectors for HERE Platform: geocoding and reverse geocoding, place search, truck routing with tolls, isolines, routing matrix, real-time traffic, waypoint sequencing, GPS trace route matching and Tour Planning.

This is one of the templates in the HERE Platform REST API app (`here-platform`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["API key query parameter (apiKey=, apikey= on Route Matching and Tour Planning)"]
* **secrets**: \["HERE\_API\_KEY"]
* **note**: OAuth 2.0 bearer (OAuth 1.0a signed token request to account.api.here.com) not packaged. \*Version events are public.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Here Waypoints Sequence connector | no |
| `BaseUrl` | string | Here Waypoints Sequence base URL without trailing slash (e.g. [https://wps.hereapi.com](https://wps.hereapi.com)) | yes |

`BASE_ADDRESS` default: `https://wps.hereapi.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `FindSequence` | GET | `/v8/findsequence2?apiKey={value.json.apikey}&start={value.json.start}&mode={value.json.mode}{value.json.params}` | `fleet/here/waypoints/sequence` | `fleet/here/waypoints/sequence/response` | `apikey`, `mode`, `params`, `start` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HERE_WAYPOINTS_SEQUENCE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HereWaypointsSequence WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://wps.hereapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT FindSequence
        WITH SOURCE_TOPIC "fleet/here/waypoints/sequence"
        WITH DESTINATION_TOPIC "fleet/here/waypoints/sequence/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v8/findsequence2?apiKey={value.json.apikey}&start={value.json.start}&mode={value.json.mode}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `FindSequence` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/here/waypoints/sequence/response' &
mosquitto_pub -t 'fleet/here/waypoints/sequence' -m '{"apikey": "<apikey>", "mode": "<mode>", "params": "<params>", "start": "<start>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# High Byte Config
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/high-byte-config

LoT connector for the HighByte Intelligence Hub Configuration API: read hub info, log in, export or merge projects, get config schemas and connection status

Technical Preview

## Overview

Client-mode REST API connectors for HighByte Intelligence Hub: read connection inputs and modeled instances, write MQTT values to hub outputs and call API-trigger pipelines through the REST Data Server, and check hub info, connection health and project export / merge through the Configuration API.

This is one of the templates in the HighByte Intelligence Hub REST API app (`highbyte-intelligence-hub`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the High Byte Config connector | no |
| `BaseUrl` | string | High Byte Config base URL without trailing slash (e.g. http\://YOUR\_HIGHBYTE\_HOST:45245) | yes |

`BASE_ADDRESS` default: `http://YOUR_HIGHBYTE_HOST:45245`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetInfo` | GET | `/v1/info` | `historian/highbyte-config/info/get` | `historian/highbyte-config/info/get/response` | none |
| `Login` | POST | `/login` | `historian/highbyte-config/session/create` | `historian/highbyte-config/session/create/response` | `body` |
| `ExportProject` | GET | `/v1/project/export` | `historian/highbyte-config/project/export` | `historian/highbyte-config/project/export/response` | `authorization` |
| `ImportPartialProject` | POST | `/v1/project/partial/import` | `historian/highbyte-config/project/merge` | `historian/highbyte-config/project/merge/response` | `authorization`, `body` |
| `GetConfigSchema` | GET | `/v2/schemas/{value.json.schema}` | `historian/highbyte-config/schema/get` | `historian/highbyte-config/schema/get/response` | `schema` |
| `GetConnectionStatus` | GET | `/v1/connection/status` | `historian/highbyte-config/connection-status/list` | `historian/highbyte-config/connection-status/list/response` | `authorization` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HIGH_BYTE_CONFIG"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HighByteConfig WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_HIGHBYTE_HOST:45245"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetInfo
        WITH SOURCE_TOPIC "historian/highbyte-config/info/get"
        WITH DESTINATION_TOPIC "historian/highbyte-config/info/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/info"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Login
        WITH SOURCE_TOPIC "historian/highbyte-config/session/create"
        WITH DESTINATION_TOPIC "historian/highbyte-config/session/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExportProject
        WITH SOURCE_TOPIC "historian/highbyte-config/project/export"
        WITH DESTINATION_TOPIC "historian/highbyte-config/project/export/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/project/export"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ImportPartialProject
        WITH SOURCE_TOPIC "historian/highbyte-config/project/merge"
        WITH DESTINATION_TOPIC "historian/highbyte-config/project/merge/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/project/partial/import"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetConfigSchema
        WITH SOURCE_TOPIC "historian/highbyte-config/schema/get"
        WITH DESTINATION_TOPIC "historian/highbyte-config/schema/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/schemas/{value.json.schema}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetConnectionStatus
        WITH SOURCE_TOPIC "historian/highbyte-config/connection-status/list"
        WITH DESTINATION_TOPIC "historian/highbyte-config/connection-status/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/connection/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetInfo` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/highbyte-config/info/get/response' &
mosquitto_pub -t 'historian/highbyte-config/info/get' -m '{}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# High Byte Data
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/high-byte-data

Connect Coreflux LoT to the HighByte REST Data Server: read connection inputs and modeled instances, write values to outputs and call API-trigger pipelines

Technical Preview

## Overview

Client-mode REST API connectors for HighByte Intelligence Hub: read connection inputs and modeled instances, write MQTT values to hub outputs and call API-trigger pipelines through the REST Data Server, and check hub info, connection health and project export / merge through the Configuration API.

This is one of the templates in the HighByte Intelligence Hub REST API app (`highbyte-intelligence-hub`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_key}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the High Byte Data connector | no |
| `BaseUrl` | string | High Byte Data base URL without trailing slash (e.g. http\://YOUR\_HIGHBYTE\_HOST:8885) | yes |

`BASE_ADDRESS` default: `http://YOUR_HIGHBYTE_HOST:8885`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ListConnections` | GET | `/data/v1/connections` | `historian/highbyte/connection/list` | `historian/highbyte/connection/list/response` | `api_key` |
| `ListInputs` | GET | `/data/v1/connections/{value.json.connection}/inputs` | `historian/highbyte/input/list` | `historian/highbyte/input/list/response` | `api_key`, `connection` |
| `GetInput` | GET | `/data/v1/connections/{value.json.connection}/inputs/{value.json.input}` | `historian/highbyte/input/get` | `historian/highbyte/input/get/response` | `api_key`, `connection`, `input` |
| `ReadInput` | GET | `/data/v1/connections/{value.json.connection}/inputs/{value.json.input}/value` | `historian/highbyte/input-value/get` | `historian/highbyte/input-value/get/response` | `api_key`, `connection`, `input` |
| `ReadInputWithParams` | POST | `/data/v1/connections/{value.json.connection}/inputs/{value.json.input}/value` | `historian/highbyte/input-value/read` | `historian/highbyte/input-value/read/response` | `api_key`, `body`, `connection`, `input` |
| `ListOutputs` | GET | `/data/v1/connections/{value.json.connection}/outputs` | `historian/highbyte/output/list` | `historian/highbyte/output/list/response` | `api_key`, `connection` |
| `WriteOutput` | POST | `/data/v1/connections/{value.json.connection}/outputs/{value.json.output}/value` | `historian/highbyte/output-value/write` | `historian/highbyte/output-value/write/response` | `api_key`, `body`, `connection`, `output` |
| `ListModels` | GET | `/data/v1/models` | `historian/highbyte/model/list` | `historian/highbyte/model/list/response` | `api_key` |
| `ListInstances` | GET | `/data/v1/instances` | `historian/highbyte/instance/list` | `historian/highbyte/instance/list/response` | `api_key` |
| `GetInstance` | GET | `/data/v1/instances/{value.json.instance}` | `historian/highbyte/instance/get` | `historian/highbyte/instance/get/response` | `api_key`, `instance` |
| `ReadInstance` | GET | `/data/v1/instances/{value.json.instance}/value` | `historian/highbyte/instance-value/get` | `historian/highbyte/instance-value/get/response` | `api_key`, `instance` |
| `ReadInstanceWithParams` | POST | `/data/v1/instances/{value.json.instance}/value` | `historian/highbyte/instance-value/read` | `historian/highbyte/instance-value/read/response` | `api_key`, `body`, `instance` |
| `ListPipelines` | GET | `/data/v1/pipelines` | `historian/highbyte/pipeline/list` | `historian/highbyte/pipeline/list/response` | `api_key` |
| `ListPipelineParams` | GET | `/data/v1/pipelines/params` | `historian/highbyte/pipeline-param/list` | `historian/highbyte/pipeline-param/list/response` | `api_key` |
| `GetPipelineParams` | GET | `/data/v1/pipelines/{value.json.pipeline}/params` | `historian/highbyte/pipeline-param/get` | `historian/highbyte/pipeline-param/get/response` | `api_key`, `pipeline` |
| `CallPipeline` | POST | `/data/v1/pipelines/{value.json.pipeline}/value` | `historian/highbyte/pipeline/call` | `historian/highbyte/pipeline/call/response` | `api_key`, `body`, `pipeline` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HIGH_BYTE_DATA"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HighByteData WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_HIGHBYTE_HOST:8885"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListConnections
        WITH SOURCE_TOPIC "historian/highbyte/connection/list"
        WITH DESTINATION_TOPIC "historian/highbyte/connection/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/connections"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ListInputs
        WITH SOURCE_TOPIC "historian/highbyte/input/list"
        WITH DESTINATION_TOPIC "historian/highbyte/input/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/connections/{value.json.connection}/inputs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT GetInput
        WITH SOURCE_TOPIC "historian/highbyte/input/get"
        WITH DESTINATION_TOPIC "historian/highbyte/input/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/connections/{value.json.connection}/inputs/{value.json.input}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ReadInput
        WITH SOURCE_TOPIC "historian/highbyte/input-value/get"
        WITH DESTINATION_TOPIC "historian/highbyte/input-value/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/connections/{value.json.connection}/inputs/{value.json.input}/value"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ReadInputWithParams
        WITH SOURCE_TOPIC "historian/highbyte/input-value/read"
        WITH DESTINATION_TOPIC "historian/highbyte/input-value/read/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/data/v1/connections/{value.json.connection}/inputs/{value.json.input}/value"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListOutputs
        WITH SOURCE_TOPIC "historian/highbyte/output/list"
        WITH DESTINATION_TOPIC "historian/highbyte/output/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/connections/{value.json.connection}/outputs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT WriteOutput
        WITH SOURCE_TOPIC "historian/highbyte/output-value/write"
        WITH DESTINATION_TOPIC "historian/highbyte/output-value/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/data/v1/connections/{value.json.connection}/outputs/{value.json.output}/value"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListModels
        WITH SOURCE_TOPIC "historian/highbyte/model/list"
        WITH DESTINATION_TOPIC "historian/highbyte/model/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/models"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ListInstances
        WITH SOURCE_TOPIC "historian/highbyte/instance/list"
        WITH DESTINATION_TOPIC "historian/highbyte/instance/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/instances"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT GetInstance
        WITH SOURCE_TOPIC "historian/highbyte/instance/get"
        WITH DESTINATION_TOPIC "historian/highbyte/instance/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/instances/{value.json.instance}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ReadInstance
        WITH SOURCE_TOPIC "historian/highbyte/instance-value/get"
        WITH DESTINATION_TOPIC "historian/highbyte/instance-value/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/instances/{value.json.instance}/value"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ReadInstanceWithParams
        WITH SOURCE_TOPIC "historian/highbyte/instance-value/read"
        WITH DESTINATION_TOPIC "historian/highbyte/instance-value/read/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/data/v1/instances/{value.json.instance}/value"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListPipelines
        WITH SOURCE_TOPIC "historian/highbyte/pipeline/list"
        WITH DESTINATION_TOPIC "historian/highbyte/pipeline/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/pipelines"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT ListPipelineParams
        WITH SOURCE_TOPIC "historian/highbyte/pipeline-param/list"
        WITH DESTINATION_TOPIC "historian/highbyte/pipeline-param/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/pipelines/params"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT GetPipelineParams
        WITH SOURCE_TOPIC "historian/highbyte/pipeline-param/get"
        WITH DESTINATION_TOPIC "historian/highbyte/pipeline-param/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/v1/pipelines/{value.json.pipeline}/params"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT CallPipeline
        WITH SOURCE_TOPIC "historian/highbyte/pipeline/call"
        WITH DESTINATION_TOPIC "historian/highbyte/pipeline/call/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/data/v1/pipelines/{value.json.pipeline}/value"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ListConnections` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/highbyte/connection/list/response' &
mosquitto_pub -t 'historian/highbyte/connection/list' -m '{"api_key": "<api_key>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Home Assistant
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/home-assistant

Connect Coreflux LoT to the Home Assistant REST API: read and set entity states, call services, fire events, read history, logbook and calendars from MQTT

Technical Preview

## Overview

One client-mode connector, **HomeAssistant**, for the [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest). Home Assistant is an open-source automation platform that runs on site and connects thousands of device integrations: building HVAC, lighting, energy meters, smart plugs, Zigbee and Z-Wave sensors. Everything it knows about is an **entity** with a **state** (for example `sensor.office_temperature` = `21.4`), and you act on devices by calling **services** (for example `switch.turn_off`).

Use the connector to bridge Home Assistant and the UNS: mirror plant values into Home Assistant dashboards, switch a compressor or the shop-floor lighting from a broker rule, pull building temperature history into a report, or start a Home Assistant automation from an MQTT alarm.

| Event | Request | Notes |
| - | - | - |
| GetApiStatus | `GET /api/` | `{"message": "API running."}`; keep the trailing `/` |
| GetConfig | `GET /api/config` | Version, location, time zone, units, loaded components |
| ListComponents | `GET /api/components` | Loaded integrations |
| ListEventTypes | `GET /api/events` | Event types and listener counts |
| ListServices | `GET /api/services` | Services per domain with their fields |
| ListStates | `GET /api/states` | Every entity state |
| GetState | `GET /api/states/{entity_id}` | `404` for an unknown entity |
| SetState | `POST /api/states/{entity_id}` | `{"state": ..., "attributes": {...}}`; `201` new, `200` existing |
| DeleteState | `DELETE /api/states/{entity_id}` | `{"message": "Entity removed."}` |
| CallService | `POST /api/services/{domain}/{service}` | Service data as the body; returns the changed states |
| CallServiceWithResponse | `POST /api/services/{domain}/{service}?return_response` | Adds `service_response` (for example `calendar.get_events`, `weather.get_forecasts`) |
| FireEvent | `POST /api/events/{event_type}` | Event data as the body |
| GetHistory | `GET /api/history/period?{query}` | Past day; `query` must include `filter_entity_id` |
| GetHistorySince | `GET /api/history/period/{start_time}?{query}` | From `start_time`; add `end_time` to close the window |
| GetLogbook | `GET /api/logbook/{start_time}?{query}` | Optional `entity` and `end_time` |
| RenderTemplate | `POST /api/template` | `{"template": "..."}`; reply is plain text |
| ListCalendars | `GET /api/calendars` | Calendar entities |
| GetCalendarEvents | `GET /api/calendars/{entity_id}?{query}` | `query` = `start=...&end=...` |
| GetErrorLog | `GET /api/error_log` | Plain text; admin token |
| CheckConfig | `POST /api/config/core/check_config` | `{"result": "valid"}` or the errors |
| TriggerWebhook | `POST /api/webhook/{webhook_id}` | No token; starts automations with a webhook trigger |

Replies arrive on `<topic>/response`. The WebSocket API (live event subscriptions) is not covered by this template.

## Authentication

Every event except `TriggerWebhook` sends `Authorization: {authorization}`, so pass the whole header value: `"Bearer <long-lived access token>"`. Create the token in Home Assistant under your user **Profile > Security > Long-lived access tokens**; it is shown only once and is valid for 10 years unless you delete it. Use a dedicated Home Assistant user for the broker so you can revoke it on its own; non-admin users cannot read the error log or check the configuration.

Keep the header value in a broker secret (suggested `HOME_ASSISTANT_AUTHORIZATION`) and map it in with `GET SECRET`. A missing or wrong token returns `401`.

`TriggerWebhook` needs no token: the webhook id is the secret, so pick a long random one. Webhook triggers only accept requests from the local network unless the trigger sets `local_only: false`, so run the broker on the same network as Home Assistant or change that option.

## Basic Syntax

Set `BASE_ADDRESS` to your Home Assistant URL, with no trailing slash: `http://homeassistant.local:8123` or `http://<ip>:8123` with `USE_SSL "false"`, or an HTTPS reverse proxy or Home Assistant Cloud remote URL with `USE_SSL "true"`. The REST API is part of `default_config`; on a minimal configuration add `api:` to `configuration.yaml`.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HomeAssistant WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_HA_HOST:8123"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetApiStatus
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/api/status"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/api/status/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetConfig
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/config/get"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/config/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/config"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListComponents
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/component/list"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/component/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/components"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListEventTypes
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/event-type/list"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/event-type/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListServices
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/service/list"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/service/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/services"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListStates
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/state/list"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/state/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/states"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetState
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/state/get"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/state/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/states/{value.json.entity_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT SetState
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/state/set"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/state/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/states/{value.json.entity_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteState
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/state/delete"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/state/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/api/states/{value.json.entity_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CallService
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/service/call"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/service/call/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/services/{value.json.domain}/{value.json.service}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT CallServiceWithResponse
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/service/call-with-response"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/service/call-with-response/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/services/{value.json.domain}/{value.json.service}?return_response"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT FireEvent
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/event/fire"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/event/fire/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/events/{value.json.event_type}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetHistory
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/history/get"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/history/period?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetHistorySince
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/history/get-since"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/history/get-since/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/history/period/{value.json.start_time}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetLogbook
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/logbook/get"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/logbook/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/logbook/{value.json.start_time}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT RenderTemplate
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/template/render"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/template/render/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/template"
        WITH HEADERS
            ADD "Accept" "text/plain"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListCalendars
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/calendar/list"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/calendar/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/calendars"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetCalendarEvents
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/calendar-event/list"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/calendar-event/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/calendars/{value.json.entity_id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetErrorLog
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/error-log/get"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/error-log/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/error_log"
        WITH HEADERS
            ADD "Accept" "text/plain"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CheckConfig
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/config/check"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/config/check/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/config/core/check_config"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT TriggerWebhook
        WITH SOURCE_TOPIC "cloud-iot/home-assistant/webhook/trigger"
        WITH DESTINATION_TOPIC "cloud-iot/home-assistant/webhook/trigger/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/webhook/{value.json.webhook_id}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## MQTT examples

Request bodies go under `body`, so control fields like `authorization` and `entity_id` are not sent to Home Assistant. Events with a `query` field need it; send the pre-encoded query string.

**Mirror a plant value into Home Assistant**: publish to `cloud-iot/home-assistant/state/set`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <long-lived access token>",
  "entity_id": "sensor.porto_line1_temperature",
  "body": {"state": "21.4", "attributes": {"unit_of_measurement": "°C", "device_class": "temperature", "friendly_name": "Line 1 temperature"}}
}
```

Home Assistant answers `201` the first time and `200` afterwards. The state only exists in Home Assistant's state machine (it is not a device and does not survive a restart), which is fine for dashboards and automations fed from the broker.

**Switch a device**: publish to `cloud-iot/home-assistant/service/call`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <long-lived access token>",
  "domain": "switch",
  "service": "turn_off",
  "body": {"entity_id": "switch.compressor_2"}
}
```

The reply lists the states that changed. An unknown domain or service returns `400`. Any service works the same way: `light/turn_on` with `{"entity_id": "light.hall_b", "brightness_pct": 60}`, `climate/set_temperature` with `{"entity_id": "climate.office", "temperature": 21}`, `script/turn_on`, `automation/trigger`, `notify/<target>`.

**Read the next maintenance windows**: publish to `cloud-iot/home-assistant/service/call-with-response`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <long-lived access token>",
  "domain": "calendar",
  "service": "get_events",
  "body": {"entity_id": "calendar.maintenance", "duration": {"days": 7}}
}
```

The reply carries `service_response` with the events. Use this event only for services that return data; others answer `400`.

**Read one entity**: publish `{"authorization": "...", "entity_id": "sensor.office_temperature"}` to `cloud-iot/home-assistant/state/get`.

**Pull the history of a sensor**: publish to `cloud-iot/home-assistant/history/get-since`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <long-lived access token>",
  "start_time": "2026-10-05T00:00:00+01:00",
  "query": "filter_entity_id=sensor.office_temperature,switch.compressor_2&end_time=2026-10-05T12%3A00%3A00%2B01%3A00&minimal_response&no_attributes"
}
```

Use `cloud-iot/home-assistant/history/get` with the same `query` (without `start_time`) for the past day.

**Start a Home Assistant automation**: add a webhook trigger to an automation (Settings > Automations > Trigger > Webhook) and publish to `cloud-iot/home-assistant/webhook/trigger`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "webhook_id": "coreflux-line1-alarm-7f3c9a",
  "body": {"machine": "press-07", "state": "fault"}
}
```

The automation reads the body as `trigger.json`, for example `{{ trigger.json.machine }}`. Home Assistant answers `200` with an empty body even when no automation uses the id, so check the automation trace when testing.

**Render a template**: publish `{"authorization": "...", "body": {"template": "{{ states('sensor.office_temperature') }} °C"}}` to `cloud-iot/home-assistant/template/render`; the reply is the rendered text.

## Helper actions

Mirror a line temperature into Home Assistant and switch off a compressor when the broker raises an alarm:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION HomeAssistantMirrorLineTemperature
ON TOPIC "porto/line1/temperature" DO
    SET "auth" WITH GET SECRET "HOME_ASSISTANT_AUTHORIZATION"
    SET "temp" WITH PAYLOAD
    PUBLISH TOPIC "cloud-iot/home-assistant/state/set" WITH { "authorization": {auth}, "entity_id": "sensor.porto_line1_temperature", "body": { "state": {temp}, "attributes": { "unit_of_measurement": "°C", "device_class": "temperature", "friendly_name": "Line 1 temperature" } } }

DEFINE ACTION HomeAssistantCompressorOff
ON TOPIC "porto/line1/compressor2/alarm" DO
    SET "auth" WITH GET SECRET "HOME_ASSISTANT_AUTHORIZATION"
    PUBLISH TOPIC "cloud-iot/home-assistant/service/call" WITH { "authorization": {auth}, "domain": "switch", "service": "turn_off", "body": { "entity_id": "switch.compressor_2" } }
```

Restrict who can publish to `cloud-iot/home-assistant/#` with a rule: its payloads carry the token and can switch real equipment.

## Notes

* Errors come back on the response topic: `400` for bad JSON, an unknown domain or service, a missing `filter_entity_id` or a `return_response` mismatch, `401` for a missing or wrong token, `404` for an unknown entity or calendar, and `405` for a wrong method.
* `SetState` changes Home Assistant's view of an entity, not the device. To act on a device, call a service with `CallService`.
* `query` and `end_time` values must be URL-encoded (`:` as `%3A`, `+` as `%2B`). `start_time` in the path can stay as plain ISO 8601, for example `2026-10-05T00:00:00+01:00`.
* History and logbook need the `history` and `logbook` integrations (part of `default_config`), and only cover what the recorder keeps (10 days by default).
* For a live stream of every state change, use Home Assistant's MQTT integration or its WebSocket API instead of polling `ListStates`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [ThingsBoard](/latest/lot-language/routes/rest-api-apps/thingsboard)
* [Eclipse Ditto](/latest/lot-language/routes/rest-api-apps/eclipse-ditto)
* [Eclipse hawkBit](/latest/lot-language/routes/rest-api-apps/eclipse-hawkbit)


# HTTPBin REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/httpbin

Client-mode REST API connector that calls the public HTTPBin echo API from MQTT

Technical Preview

## Overview

[HTTPBin](https://httpbin.org) is a public HTTP echo service. Use this client-mode `REST_API` connector to prove MQTT-to-HTTP wiring (methods, path placeholders, headers, and response topics) without an API key.

> [!TIP]
>
> Public `GET /get` does not need a token. The template still sends `Authorization: Bearer {value.json.api_token}` so the header pattern matches other apps. Leave `api_token` empty for demos, or drop that header.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — HTTPBin
# Generated from OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

DEFINE CONNECTOR HttpbinRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://httpbin.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Optional: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Get
        WITH SOURCE_TOPIC "integrations/httpbin/request/Get"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Get"
        WITH METHOD "GET"
        WITH ENDPOINT "/get"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Post
        WITH SOURCE_TOPIC "integrations/httpbin/request/Post"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Post"
        WITH METHOD "POST"
        WITH ENDPOINT "/post"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Put
        WITH SOURCE_TOPIC "integrations/httpbin/request/Put"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Put"
        WITH METHOD "PUT"
        WITH ENDPOINT "/put"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Delete
        WITH SOURCE_TOPIC "integrations/httpbin/request/Delete"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Delete"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/delete"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Statuscode
        WITH SOURCE_TOPIC "integrations/httpbin/request/Statuscode"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Statuscode"
        WITH METHOD "GET"
        WITH ENDPOINT "/status/{value.json.code}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Headers
        WITH SOURCE_TOPIC "integrations/httpbin/request/Headers"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Headers"
        WITH METHOD "GET"
        WITH ENDPOINT "/headers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Uuid
        WITH SOURCE_TOPIC "integrations/httpbin/request/Uuid"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Uuid"
        WITH METHOD "GET"
        WITH ENDPOINT "/uuid"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Bytes
        WITH SOURCE_TOPIC "integrations/httpbin/request/Bytes"
        WITH DESTINATION_TOPIC "integrations/httpbin/response/Bytes"
        WITH METHOD "GET"
        WITH ENDPOINT "/bytes/{value.json.n}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Get | GET | `/get` | `integrations/httpbin/request/Get` | `integrations/httpbin/response/Get` |
| Post | POST | `/post` | `integrations/httpbin/request/Post` | `integrations/httpbin/response/Post` |
| Put | PUT | `/put` | `integrations/httpbin/request/Put` | `integrations/httpbin/response/Put` |
| Delete | DELETE | `/delete` | `integrations/httpbin/request/Delete` | `integrations/httpbin/response/Delete` |
| Statuscode | GET | `/status/{value.json.code}` | `integrations/httpbin/request/Statuscode` | `integrations/httpbin/response/Statuscode` |
| Headers | GET | `/headers` | `integrations/httpbin/request/Headers` | `integrations/httpbin/response/Headers` |
| Uuid | GET | `/uuid` | `integrations/httpbin/request/Uuid` | `integrations/httpbin/response/Uuid` |
| Bytes | GET | `/bytes/{value.json.n}` | `integrations/httpbin/request/Bytes` | `integrations/httpbin/response/Bytes` |

## Auth

None required. Base address is `https://httpbin.org`. Optional Bearer token is a placeholder only. Prefer `GET SECRET` if you later point the connector at a private echo. Never commit real tokens.

## Try it

1. Add the connector on your broker (`-addConnector` with the LoT above).
2. Publish `{}` to `integrations/httpbin/request/Get`.
3. Subscribe to `integrations/httpbin/response/Get`. HTTPBin echoes the request as JSON.
4. Status check: publish `{"code":"200"}` to `integrations/httpbin/request/Statuscode`.
5. POST/PUT: publish a JSON body to `integrations/httpbin/request/Post` or `.../Put`. The connector sends it as `{payload}`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# HubSpot CRM API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/hubspot

Client-mode REST API connector for a curated HubSpot CRM v3 subset: contacts, companies, deals, and owners

Technical Preview

## Overview

A client-mode connector for a **curated eight-operation** slice of the [HubSpot CRM API](https://developers.hubspot.com/docs/api-reference/legacy/crm/objects/contacts/guide): list/create/get/update contacts, list/get companies, list deals, and list owners. It is meant for CRM / service edge bridges, not the full HubSpot surface. `BASE_ADDRESS` defaults to `https://api.hubapi.com` (official OpenAPI host). `https://api.hubspot.com` also accepts CRM calls.

> [!NOTE]
>
> HubSpot CRM requires a private app access token or OAuth Bearer token. Unauthenticated calls return HTTP 401. The legacy `api-catalog-public/v1/apis` catalog was sunset (HTTP 404); specs now live at `public/api/spec/v1/specs`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — HubSpot (CRM v3)
# Generated from curated OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes
# Auth: HubSpot private-app access token (or OAuth) as Bearer {value.json.api_token}.
# Prefer Hub secrets / GET SECRET — never commit real tokens.
# BASE_ADDRESS: https://api.hubapi.com (official). https://api.hubspot.com also accepts CRM calls.

DEFINE CONNECTOR HubSpotRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.hubapi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: private app token or OAuth access token as Bearer.
        # Prefer Hub secrets / GET SECRET upstream — never commit real tokens.
    ADD EVENT Listcontacts
        WITH SOURCE_TOPIC "integrations/hubspot/request/Listcontacts"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Listcontacts"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v3/objects/contacts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createcontact
        WITH SOURCE_TOPIC "integrations/hubspot/request/Createcontact"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Createcontact"
        WITH METHOD "POST"
        WITH ENDPOINT "/crm/v3/objects/contacts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Getcontact
        WITH SOURCE_TOPIC "integrations/hubspot/request/Getcontact"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Getcontact"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v3/objects/contacts/{value.json.contactId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Updatecontact
        WITH SOURCE_TOPIC "integrations/hubspot/request/Updatecontact"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Updatecontact"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/crm/v3/objects/contacts/{value.json.contactId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Listcompanies
        WITH SOURCE_TOPIC "integrations/hubspot/request/Listcompanies"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Listcompanies"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v3/objects/companies"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getcompany
        WITH SOURCE_TOPIC "integrations/hubspot/request/Getcompany"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Getcompany"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v3/objects/companies/{value.json.companyId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listdeals
        WITH SOURCE_TOPIC "integrations/hubspot/request/Listdeals"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Listdeals"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v3/objects/deals"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listowners
        WITH SOURCE_TOPIC "integrations/hubspot/request/Listowners"
        WITH DESTINATION_TOPIC "integrations/hubspot/response/Listowners"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v3/owners"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Listcontacts | GET | `/crm/v3/objects/contacts` | `integrations/hubspot/request/Listcontacts` | `integrations/hubspot/response/Listcontacts` |
| Createcontact | POST | `/crm/v3/objects/contacts` | `integrations/hubspot/request/Createcontact` | `integrations/hubspot/response/Createcontact` |
| Getcontact | GET | `/crm/v3/objects/contacts/{value.json.contactId}` | `integrations/hubspot/request/Getcontact` | `integrations/hubspot/response/Getcontact` |
| Updatecontact | PATCH | `/crm/v3/objects/contacts/{value.json.contactId}` | `integrations/hubspot/request/Updatecontact` | `integrations/hubspot/response/Updatecontact` |
| Listcompanies | GET | `/crm/v3/objects/companies` | `integrations/hubspot/request/Listcompanies` | `integrations/hubspot/response/Listcompanies` |
| Getcompany | GET | `/crm/v3/objects/companies/{value.json.companyId}` | `integrations/hubspot/request/Getcompany` | `integrations/hubspot/response/Getcompany` |
| Listdeals | GET | `/crm/v3/objects/deals` | `integrations/hubspot/request/Listdeals` | `integrations/hubspot/response/Listdeals` |
| Listowners | GET | `/crm/v3/owners` | `integrations/hubspot/request/Listowners` | `integrations/hubspot/response/Listowners` |

List endpoints accept HubSpot query options (`limit`, `after`, `properties`, `archived`) when you extend the `ENDPOINT` or append them in a custom variant.

## Auth

Private app or OAuth Bearer:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Accept" "application/json"
ADD "Authorization" "Bearer {value.json.api_token}"
```

**api\_token** `string` *required*

HubSpot private app access token or OAuth access token. Prefer a Hub secret. Never commit the token.

**contactId** `string`

Contact record ID. Required on Getcontact and Updatecontact.

**companyId** `string`

Company record ID. Required on Getcompany.

High-level token flow (no secrets in the template):

1. Create a HubSpot **private app** with CRM scopes (contacts, companies, deals, owners) — or use an OAuth app.
2. Copy the private app access token (or obtain an OAuth access token).
3. Publish the token as `api_token` on the MQTT request payload (or inject from Hub secret upstream).

List contacts:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_HUBSPOT_PRIVATE_APP_TOKEN"}
```

Get contact:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_HUBSPOT_PRIVATE_APP_TOKEN", "contactId": "123"}
```

Create contact (connector body is `{payload}`; include CRM `properties`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_HUBSPOT_PRIVATE_APP_TOKEN", "properties": {"email": "ops@example.com", "firstname": "Plant", "lastname": "Ops"}}
```

## Try it

1. Add the connector on your broker (`BASE_ADDRESS` already points at `https://api.hubapi.com`).
2. Publish token JSON to `integrations/hubspot/request/Listcontacts`.
3. Subscribe to `integrations/hubspot/response/Listcontacts`.
4. Contacts / companies: include `contactId` or `companyId` as needed.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Hugging Face Dedicated Endpoint
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/hugging-face-dedicated-endpoint

LoT connector for your own Hugging Face dedicated Inference Endpoint: send predictions or OpenAI-compatible chat completions from MQTT with an HF token

Technical Preview

## Overview

Client-mode REST API connectors for Hugging Face: triage alarms with OpenAI-compatible chat completions through Inference Providers, create embeddings and classify camera snapshots with HF Inference, pause, resume or scale dedicated Inference Endpoints to zero to control cost, call your own anomaly model, and search Hub models, all with a Hugging Face token.

This is one of the templates in the Hugging Face Inference Providers and Endpoints REST API app (`hugging-face-inference-providers-and-endpoints`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Hugging Face user access token as Authorization: Bearer \{value.json.hf\_token} on every event. Fine-grained token: 'Make calls to Inference Providers' (router chat / task events) + Inference Endpoints read/write (management + dedicated endpoint calls). Hub secret suggested HF\_TOKEN + GET SECRET. Public router / Hub GETs answer without a valid token. Never commit tokens.

Auth headers used by the template: `Authorization: Bearer {value.json.hf_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Hugging Face Dedicated Endpoint connector | no |
| `BaseUrl` | string | Hugging Face Dedicated Endpoint base URL without trailing slash (e.g. [https://YOUR\_ENDPOINT\_HOST.endpoints.huggingface.cloud](https://YOUR_ENDPOINT_HOST.endpoints.huggingface.cloud)) | yes |

`BASE_ADDRESS` default: `https://YOUR_ENDPOINT_HOST.endpoints.huggingface.cloud`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `DedicatedPredict` | POST | `/` | `ai/huggingface/dedicated-endpoint/predict` | `ai/huggingface/dedicated-endpoint/predict/response` | `body`, `hf_token` |
| `DedicatedChatCompletion` | POST | `/v1/chat/completions` | `ai/huggingface/dedicated-endpoint/chat` | `ai/huggingface/dedicated-endpoint/chat/response` | `body`, `hf_token` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HUGGING_FACE_DEDICATED_ENDPOINT"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HuggingFaceDedicatedEndpoint WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ENDPOINT_HOST.endpoints.huggingface.cloud"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT DedicatedPredict
        WITH SOURCE_TOPIC "ai/huggingface/dedicated-endpoint/predict"
        WITH DESTINATION_TOPIC "ai/huggingface/dedicated-endpoint/predict/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT DedicatedChatCompletion
        WITH SOURCE_TOPIC "ai/huggingface/dedicated-endpoint/chat"
        WITH DESTINATION_TOPIC "ai/huggingface/dedicated-endpoint/chat/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/chat/completions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `DedicatedPredict` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/huggingface/dedicated-endpoint/predict/response' &
mosquitto_pub -t 'ai/huggingface/dedicated-endpoint/predict' -m '{"body": {}, "hf_token": "<hf_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Hugging Face Hub
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/hugging-face-hub

LoT connector for the Hugging Face Hub API: check the token account with WhoAmI, search models by task or name and get model info from MQTT topics

Technical Preview

## Overview

Client-mode REST API connectors for Hugging Face: triage alarms with OpenAI-compatible chat completions through Inference Providers, create embeddings and classify camera snapshots with HF Inference, pause, resume or scale dedicated Inference Endpoints to zero to control cost, call your own anomaly model, and search Hub models, all with a Hugging Face token.

This is one of the templates in the Hugging Face Inference Providers and Endpoints REST API app (`hugging-face-inference-providers-and-endpoints`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Hugging Face user access token as Authorization: Bearer \{value.json.hf\_token} on every event. Fine-grained token: 'Make calls to Inference Providers' (router chat / task events) + Inference Endpoints read/write (management + dedicated endpoint calls). Hub secret suggested HF\_TOKEN + GET SECRET. Public router / Hub GETs answer without a valid token. Never commit tokens.

Auth headers used by the template: `Authorization: Bearer {value.json.hf_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Hugging Face Hub connector | no |
| `BaseUrl` | string | Hugging Face Hub base URL without trailing slash (e.g. [https://huggingface.co](https://huggingface.co)) | yes |

`BASE_ADDRESS` default: `https://huggingface.co`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `WhoAmI` | GET | `/api/whoami-v2` | `ai/huggingface/account/whoami` | `ai/huggingface/account/whoami/response` | `hf_token` |
| `SearchModels` | GET | `/api/models?search={value.json.search}&pipeline_tag={value.json.pipeline_tag}&sort={value.json.sort}&limit={value.json.limit}` | `ai/huggingface/hub-model/search` | `ai/huggingface/hub-model/search/response` | `hf_token`, `limit`, `pipeline_tag`, `search`, `sort` |
| `GetModelInfo` | GET | `/api/models/{value.json.model_id}` | `ai/huggingface/hub-model/get` | `ai/huggingface/hub-model/get/response` | `hf_token`, `model_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HUGGING_FACE_HUB"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HuggingFaceHub WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://huggingface.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT WhoAmI
        WITH SOURCE_TOPIC "ai/huggingface/account/whoami"
        WITH DESTINATION_TOPIC "ai/huggingface/account/whoami/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/whoami-v2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
    ADD EVENT SearchModels
        WITH SOURCE_TOPIC "ai/huggingface/hub-model/search"
        WITH DESTINATION_TOPIC "ai/huggingface/hub-model/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/models?search={value.json.search}&pipeline_tag={value.json.pipeline_tag}&sort={value.json.sort}&limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
    ADD EVENT GetModelInfo
        WITH SOURCE_TOPIC "ai/huggingface/hub-model/get"
        WITH DESTINATION_TOPIC "ai/huggingface/hub-model/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/models/{value.json.model_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `WhoAmI` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/huggingface/account/whoami/response' &
mosquitto_pub -t 'ai/huggingface/account/whoami' -m '{"hf_token": "<hf_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Hugging Face Inference Endpoints
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/hugging-face-inference-endpoints

Manage Hugging Face Inference Endpoints from Coreflux LoT: list, get and create endpoints, and pause, resume or scale them to zero to control cost

Technical Preview

## Overview

Client-mode REST API connectors for Hugging Face: triage alarms with OpenAI-compatible chat completions through Inference Providers, create embeddings and classify camera snapshots with HF Inference, pause, resume or scale dedicated Inference Endpoints to zero to control cost, call your own anomaly model, and search Hub models, all with a Hugging Face token.

This is one of the templates in the Hugging Face Inference Providers and Endpoints REST API app (`hugging-face-inference-providers-and-endpoints`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Hugging Face user access token as Authorization: Bearer \{value.json.hf\_token} on every event. Fine-grained token: 'Make calls to Inference Providers' (router chat / task events) + Inference Endpoints read/write (management + dedicated endpoint calls). Hub secret suggested HF\_TOKEN + GET SECRET. Public router / Hub GETs answer without a valid token. Never commit tokens.

Auth headers used by the template: `Authorization: Bearer {value.json.hf_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Hugging Face Inference Endpoints connector | no |
| `BaseUrl` | string | Hugging Face Inference Endpoints base URL without trailing slash (e.g. [https://api.endpoints.huggingface.cloud](https://api.endpoints.huggingface.cloud)) | yes |

`BASE_ADDRESS` default: `https://api.endpoints.huggingface.cloud`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ListEndpoints` | GET | `/v2/endpoint/{value.json.namespace}` | `ai/huggingface/endpoint/list` | `ai/huggingface/endpoint/list/response` | `hf_token`, `namespace` |
| `GetEndpoint` | GET | `/v2/endpoint/{value.json.namespace}/{value.json.name}` | `ai/huggingface/endpoint/get` | `ai/huggingface/endpoint/get/response` | `hf_token`, `name`, `namespace` |
| `CreateEndpoint` | POST | `/v2/endpoint/{value.json.namespace}` | `ai/huggingface/endpoint/create` | `ai/huggingface/endpoint/create/response` | `body`, `hf_token`, `namespace` |
| `PauseEndpoint` | POST | `/v2/endpoint/{value.json.namespace}/{value.json.name}/pause` | `ai/huggingface/endpoint/pause` | `ai/huggingface/endpoint/pause/response` | `hf_token`, `name`, `namespace` |
| `ResumeEndpoint` | POST | `/v2/endpoint/{value.json.namespace}/{value.json.name}/resume` | `ai/huggingface/endpoint/resume` | `ai/huggingface/endpoint/resume/response` | `hf_token`, `name`, `namespace` |
| `ScaleToZeroEndpoint` | POST | `/v2/endpoint/{value.json.namespace}/{value.json.name}/scale-to-zero` | `ai/huggingface/endpoint/scale-to-zero` | `ai/huggingface/endpoint/scale-to-zero/response` | `hf_token`, `name`, `namespace` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HUGGING_FACE_INFERENCE_ENDPOINTS"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HuggingFaceInferenceEndpoints WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.endpoints.huggingface.cloud"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListEndpoints
        WITH SOURCE_TOPIC "ai/huggingface/endpoint/list"
        WITH DESTINATION_TOPIC "ai/huggingface/endpoint/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/endpoint/{value.json.namespace}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
    ADD EVENT GetEndpoint
        WITH SOURCE_TOPIC "ai/huggingface/endpoint/get"
        WITH DESTINATION_TOPIC "ai/huggingface/endpoint/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/endpoint/{value.json.namespace}/{value.json.name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
    ADD EVENT CreateEndpoint
        WITH SOURCE_TOPIC "ai/huggingface/endpoint/create"
        WITH DESTINATION_TOPIC "ai/huggingface/endpoint/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/endpoint/{value.json.namespace}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT PauseEndpoint
        WITH SOURCE_TOPIC "ai/huggingface/endpoint/pause"
        WITH DESTINATION_TOPIC "ai/huggingface/endpoint/pause/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/endpoint/{value.json.namespace}/{value.json.name}/pause"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY ""
    ADD EVENT ResumeEndpoint
        WITH SOURCE_TOPIC "ai/huggingface/endpoint/resume"
        WITH DESTINATION_TOPIC "ai/huggingface/endpoint/resume/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/endpoint/{value.json.namespace}/{value.json.name}/resume"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY ""
    ADD EVENT ScaleToZeroEndpoint
        WITH SOURCE_TOPIC "ai/huggingface/endpoint/scale-to-zero"
        WITH DESTINATION_TOPIC "ai/huggingface/endpoint/scale-to-zero/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/endpoint/{value.json.namespace}/{value.json.name}/scale-to-zero"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY ""
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ListEndpoints` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/huggingface/endpoint/list/response' &
mosquitto_pub -t 'ai/huggingface/endpoint/list' -m '{"hf_token": "<hf_token>", "namespace": "<namespace>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Hugging Face Inference Providers
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/hugging-face-inference-providers

Connect Coreflux LoT to Hugging Face Inference Providers: OpenAI-compatible chat completions, router model lists, embeddings and image classification

Technical Preview

## Overview

Client-mode REST API connectors for Hugging Face: triage alarms with OpenAI-compatible chat completions through Inference Providers, create embeddings and classify camera snapshots with HF Inference, pause, resume or scale dedicated Inference Endpoints to zero to control cost, call your own anomaly model, and search Hub models, all with a Hugging Face token.

This is one of the templates in the Hugging Face Inference Providers and Endpoints REST API app (`hugging-face-inference-providers-and-endpoints`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Hugging Face user access token as Authorization: Bearer \{value.json.hf\_token} on every event. Fine-grained token: 'Make calls to Inference Providers' (router chat / task events) + Inference Endpoints read/write (management + dedicated endpoint calls). Hub secret suggested HF\_TOKEN + GET SECRET. Public router / Hub GETs answer without a valid token. Never commit tokens.

Auth headers used by the template: `Authorization: Bearer {value.json.hf_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Hugging Face Inference Providers connector | no |
| `BaseUrl` | string | Hugging Face Inference Providers base URL without trailing slash (e.g. [https://router.huggingface.co](https://router.huggingface.co)) | yes |

`BASE_ADDRESS` default: `https://router.huggingface.co`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ChatCompletion` | POST | `/v1/chat/completions` | `ai/huggingface/chat/complete` | `ai/huggingface/chat/complete/response` | `body`, `hf_token` |
| `ListRouterModels` | GET | `/v1/models` | `ai/huggingface/router-model/list` | `ai/huggingface/router-model/list/response` | `hf_token` |
| `GetRouterModel` | GET | `/v1/models/{value.json.model_id}` | `ai/huggingface/router-model/get` | `ai/huggingface/router-model/get/response` | `hf_token`, `model_id` |
| `FeatureExtraction` | POST | `/hf-inference/models/{value.json.model_id}/pipeline/feature-extraction` | `ai/huggingface/embeddings/create` | `ai/huggingface/embeddings/create/response` | `body`, `hf_token`, `model_id` |
| `ImageClassification` | POST | `/hf-inference/models/{value.json.model_id}` | `ai/huggingface/image/classify` | `ai/huggingface/image/classify/response` | `body`, `hf_token`, `model_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode HUGGING_FACE_INFERENCE_PROVIDERS"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR HuggingFaceInferenceProviders WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://router.huggingface.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ChatCompletion
        WITH SOURCE_TOPIC "ai/huggingface/chat/complete"
        WITH DESTINATION_TOPIC "ai/huggingface/chat/complete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/chat/completions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListRouterModels
        WITH SOURCE_TOPIC "ai/huggingface/router-model/list"
        WITH DESTINATION_TOPIC "ai/huggingface/router-model/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/models"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
    ADD EVENT GetRouterModel
        WITH SOURCE_TOPIC "ai/huggingface/router-model/get"
        WITH DESTINATION_TOPIC "ai/huggingface/router-model/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/models/{value.json.model_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
    ADD EVENT FeatureExtraction
        WITH SOURCE_TOPIC "ai/huggingface/embeddings/create"
        WITH DESTINATION_TOPIC "ai/huggingface/embeddings/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/hf-inference/models/{value.json.model_id}/pipeline/feature-extraction"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ImageClassification
        WITH SOURCE_TOPIC "ai/huggingface/image/classify"
        WITH DESTINATION_TOPIC "ai/huggingface/image/classify/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/hf-inference/models/{value.json.model_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.hf_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ChatCompletion` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/huggingface/chat/complete/response' &
mosquitto_pub -t 'ai/huggingface/chat/complete' -m '{"body": {}, "hf_token": "<hf_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# HxGN EAM (Hexagon, formerly Infor EAM)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/hxgn-eam

LoT connector for HxGN EAM (formerly Infor EAM): create work orders from alarms, add activities, comments and parts, push meter readings and update assets

Technical Preview

## Overview

HxGN EAM (Hexagon's enterprise asset management, formerly Infor EAM; newer hosts brand it Attune EAM) exposes every screen and tab as a **REST web service** under `https://<EAM host>/axis/restservices`, defined in OpenAPI 3 and browsable at `https://<EAM host>/web/swagger/index.html`. See the [HxGN EAM Rest Web Services guide](https://docs.hexagonppm.com/r/en-US/HxGN-EAM-Rest-Web-Services/12.2.1/1272545).

The **HxgnEamApi** connector maps 22 MQTT topics onto those services. Typical uses: open a work order when an alarm is raised, push runtime hours or cycle counts as asset meter readings so meter-based PM fires, set an asset out of service from the machine state, and poll released work orders back onto the broker. Each event publishes the EAM reply on `<topic>/response`.

| Event | Topic | Request (under `/axis/restservices`) | Use |
| - | - | - | - |
| `GetWorkOrderDefaults` | `cmms/hxgn-eam/work-order/defaults` | `POST /workorderdefaults` | Default values for a new work order in an organization: body \{"ORGANIZATIONID": \{"ORGANIZATIONCODE": "ORG1"}} (check: cheapest auth + tenant check) |
| `CreateWorkOrder` | `cmms/hxgn-eam/work-order/create` | `POST /workorders` | Add a work order from an alarm: body WORKORDERID (JOBNUM + ORGANIZATIONID, auto\_generated true), DESCRIPTION, STATUS, EQUIPMENTID, TYPE, DEPARTMENTID, ... |
| `ListWorkOrders` | `cmms/hxgn-eam/work-order/list` | `GET /workorders` | Get Collection: default Work Order Dataspy, RSCLROWS rows, no filters (use QueryGrid to filter by status) |
| `GetWorkOrder` | `cmms/hxgn-eam/work-order/get` | `GET /workorders/{id}` | One work order, id = "\<number>%23\<organization>" |
| `UpdateWorkOrder` | `cmms/hxgn-eam/work-order/update` | `PATCH /workorders/{id}` | Change only the fields sent, e.g. STATUS \{STATUSCODE: C}; recordid optional (must match if sent) |
| `DeleteWorkOrder` | `cmms/hxgn-eam/work-order/delete` | `DELETE /workorders/{id}` | Delete a work order by id |
| `AddWorkOrderActivity` | `cmms/hxgn-eam/work-order-activity/create` | `POST /workorders/activities` | Add an activity: body ACTIVITYID \{WORKORDERID, ACTIVITYCODE}, TRADEID, ESTIMATEDHOURS, PERSONS, ... |
| `ListWorkOrderActivities` | `cmms/hxgn-eam/work-order-activity/list` | `GET /workorders/{parentid}/activities` | Activities of a work order, parentid = "\<number>%23\<organization>" |
| `AddWorkOrderComment` | `cmms/hxgn-eam/work-order-comment/create` | `POST /workorders/comments` | Append machine context: body ENTITYCOMMENTID, COMMENTTEXT, PRINT (all required) |
| `ListWorkOrderComments` | `cmms/hxgn-eam/work-order-comment/list` | `GET /workorders/{parentid}/comments` | Comments of a work order (COMMENT array, RSCLROWS ignored) |
| `AddWorkOrderMeterReading` | `cmms/hxgn-eam/work-order-meter-reading/create` | `POST /workorders/meterreadings` | Meter reading on a work order: body TARGETEQUIPMENTID, USAGEUOMID, READINGDATE (required), WORKORDERID, ACTUALREADING |
| `AddWorkOrderPart` | `cmms/hxgn-eam/work-order-part/create` | `POST /workorders/parts` | Plan a part on a work order activity (Work Order Parts tab) |
| `ListWorkOrderParts` | `cmms/hxgn-eam/work-order-part/list` | `GET /workorders/{parentid}/parts` | Planned parts of a work order |
| `ListAssets` | `cmms/hxgn-eam/asset/list` | `GET /assets` | Get Collection of assets (equipment) from the default Asset Dataspy |
| `GetAsset` | `cmms/hxgn-eam/asset/get` | `GET /assets/{id}` | One asset, id = "\<equipment code>%23\<organization>" |
| `UpdateAsset` | `cmms/hxgn-eam/asset/update` | `PATCH /assets/{id}` | Change only the fields sent, e.g. OPERATIONALSTATUS, OUTOFSERVICE, INPRODUCTION from machine state |
| `AddAssetMeterReading` | `cmms/hxgn-eam/asset-meter-reading/create` | `POST /assets/meterreadings` | Runtime hours / cycles from MQTT: body EQUIPMENTID, UOMID, READINGTYPEID, READINGDATE, NEWVALUE (all required) |
| `ListAssetMeterReadings` | `cmms/hxgn-eam/asset-meter-reading/list` | `GET /assets/{parentid}/meterreadings` | Meter readings of an asset, parentid = "\<equipment code>%23\<organization>" |
| `AddAssetComment` | `cmms/hxgn-eam/asset-comment/create` | `POST /assets/comments` | Comment on an asset: body ENTITYCOMMENTID, COMMENTTEXT, PRINT |
| `ListParts` | `cmms/hxgn-eam/part/list` | `GET /parts` | Get Collection of parts from the default Part Dataspy |
| `GetPart` | `cmms/hxgn-eam/part/get` | `GET /parts/{id}` | One part, id = "\<part code>%23\<organization>" |
| `QueryGrid` | `cmms/hxgn-eam/grid/query` | `POST /grids` | Any EAM list view with filters and paging: body GRID \{GRID\_NAME e.g. WSJOBS, USER\_FUNCTION\_NAME, NUMBER\_OF\_ROWS\_FIRST\_RETURNED, CURSOR\_POSITION}, GRID\_TYPE \{TYPE: LIST}, DATASPY, ADDON\_FILTER / MULTIADDON\_FILTERS, ADDON\_SORT |

## Prerequisites

* An HxGN EAM tenant (HxGN SmartCloud, for example `eu1.eam.hxgnsmartcloud.com` or `us1.eam.hxgnsmartcloud.com`, or an on-premise server) and its **tenant id**.
* An EAM user with the **Connector** checkbox selected (HxGN EAM Products section of the user record). Install parameter `LGNCON` decides how that user signs in (`STD`, `LDAP` or `EXTERN`).
* A user group whose **Interface Permissions** grant Query, Insert, Update or Delete on each web service you call (Work Order, Work Order Activity, Comments, Meter Readings, Parts, Asset, Part, Grid).
* Default Dataspys that include the fields the services need (GET collections return the default Dataspy of the screen).
* Outbound HTTPS from the broker to the EAM host.

## Authentication

Every event sends three headers taken from the payload:

| Header | Payload field | Value |
| - | - | - |
| `Authorization` | `authorization` | `Basic <base64 user:password>`, or `Bearer <OIDC token>` (see the HxGN EAM OpenID Connect guide) |
| `tenant` | `tenant` | Your EAM tenant id |
| `organization` | `organization` | Default organization code of the user |

Store the `Authorization` value as a Hub secret, for example `HXGN_EAM_AUTHORIZATION`, and read it with `GET SECRET` in the action that publishes to the connector. The spec also accepts an API key in `X-API-Key`: fork the connector and replace the `Authorization` line with `ADD "X-API-Key" "{value.json.api_key}"`.

Optional EAM headers (`role`, `apiversion`, `keepsession` / `sessionid`, `clonedscreen`, `cursorposition`, `authenticationmode`) are not sent. Add them under `WITH HEADERS` in a fork if your tenant needs them, for example `ADD "role" "<role>"`.

A missing tenant returns `400` with `NoTenantException`; an unknown tenant returns `400` `Invalid Tenant ID: ...`.

## Configuration

| Setting | Value |
| - | - |
| `BASE_ADDRESS` | `https://eu1.eam.hxgnsmartcloud.com` (HxGN SmartCloud EU). Change it to `https://us1.eam.hxgnsmartcloud.com` or your own server; endpoints carry `/axis/restservices` |
| `USE_SSL` | `"true"` |
| `DEFAULT_CONTENT_TYPE` | `application/json` |
| Payload fields | `authorization`, `tenant`, `organization`, `id`, `parentid` (record keys), `body` (JSON request body) |

> [!WARNING]
>
> Record keys are `<code>#<organization>`, and the `#` **must be URL-encoded as `%23`** in `id` and `parentid`, for example `"10000%23ORG1"` for work order 10000 in ORG1 or `"PUMP-101%23ORG1"` for an asset. A raw `#` starts a URL fragment, so the organization never reaches EAM and the call fails with `404`.

* **Lists.** `ListWorkOrders`, `ListAssets` and `ListParts` take no filters: they return the screen's default Dataspy, `RSCLROWS` rows at a time. To filter (for example work orders in status `R`), use `QueryGrid` (`POST /grids`) with `GRID_NAME` `WSJOBS` and an `ADDON_FILTER`, or a Dataspy id. Grid alias names and Dataspy ids depend on your tenant; check them in the grid response.
* **Writes.** `POST` adds a record. `PATCH` changes only the fields you send; include the key block (`WORKORDERID` or `ASSETID`) as in the Swagger patch example. If you send `recordid`, it must match the stored value, or EAM answers "This record has been modified by another user". `PUT` (Sync, full replace that blanks missing fields) is not packaged.
* **Required fields.** Work orders: `WORKORDERID`, `STATUS`, `DEPARTMENTID`, `FIXED`. Asset meter readings: `EQUIPMENTID`, `UOMID`, `READINGTYPEID`, `READINGDATE`, `NEWVALUE`. Comments: `ENTITYCOMMENTID`, `COMMENTTEXT`, `PRINT`. `GetWorkOrderDefaults` returns the defaults for an organization.
* **Numbers and dates.** Quantities are `{"VALUE", "NUMOFDEC", "SIGN", "UOM"}` objects (`VALUE` 128750 with `NUMOFDEC` 2 is 1287.50). Date objects carry `YEAR` as epoch milliseconds unless install parameter `RSYRYYYY` is `YES` (EAM 12.3+).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — HxGN EAM REST Web Services (Hexagon, formerly Infor EAM; recent hosts brand it Attune EAM):
#   create work orders from alarms, read / list / patch / delete work orders, add activities, comments and planned parts,
#   push meter readings from MQTT counters (asset or work-order meter readings), read and patch assets (equipment),
#   read parts, and query any EAM grid (list view with filters, e.g. work orders in status R).
#   Credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/hxgn-eam
#
# Host: BASE_ADDRESS is the EAM application server. HxGN SmartCloud EU is https://eu1.eam.hxgnsmartcloud.com (US: us1...);
#   on-premise or older Infor-hosted tenants use their own host. Every endpoint carries /axis/restservices.
# Headers: tenant and organization are required on every call (spec), taken from {value.json.tenant} and
#   {value.json.organization}. Optional headers (role, apiversion, keepsession, sessionid, clonedscreen,
#   cursorposition, authenticationmode) are not sent; fork the route to add them (e.g. ADD "role" "<role>").
# Auth: Authorization: {value.json.authorization} carries the full header value, "Basic <base64 user:password>" for an
#   EAM user with the Connector checkbox, or "Bearer <OIDC token>" (HxGN EAM OpenID Connect guide). The spec also allows
#   an X-API-Key header: fork and replace the Authorization line with ADD "X-API-Key" "{value.json.api_key}".
#   Keep the value in Hub secrets (suggested HXGN_EAM_AUTHORIZATION) and map it into the payload with GET SECRET.
#   The user group needs Interface Permissions (Query / Insert / Update / Delete) on each web service you call.
# Ids: id / parentid are "<code>#<organization>" and the # MUST be sent URL-encoded as %23, e.g. "10000%23ORG1"
#   (work order 10000 in organization ORG1) or "PUMP-101%23ORG1" (asset). The broker does not encode path values.
# Lists: GET collections take no filters; they return the default Dataspy of the screen, RSCLROWS rows. For a filtered
#   list (for example work orders in status R) use QueryGrid (POST /grids) with GRID_NAME WSJOBS + ADDON_FILTER.
# Writes: POST adds, PATCH changes only the fields sent (recordid, if sent, must match). PUT (Sync, full replace that
#   blanks missing fields) is deliberately not packaged. Dates are {"YEAR": <epoch ms>, "MONTH", "DAY", ...} objects
#   unless install parameter RSYRYYYY = YES (EAM 12.3+).
# Responses: 200 {"Result": {"ResultData": ..., "InfoAlert", "WarningAlert"}, "ErrorAlert": null, ...};
#   400 ErrorAlert or ConfirmationAlert (e.g. "Invalid Tenant ID", validation, "record modified by another user");
#   404 unknown service / record; 500 internal error.
#
# Payload fields (control fields stay out of bodies; request bodies come from {value.json.body}):
#   authorization, tenant, organization, id, parentid, body
#     CreateWorkOrder        body = {"WORKORDERID": {"JOBNUM": "", "ORGANIZATIONID": {"ORGANIZATIONCODE": "ORG1"}, "auto_generated": true},
#                                    "DESCRIPTION": "Compressor over-temperature", "STATUS": {"STATUSCODE": "R"},
#                                    "EQUIPMENTID": {"EQUIPMENTCODE": "PUMP-101", "ORGANIZATIONID": {"ORGANIZATIONCODE": "ORG1"}},
#                                    "TYPE": {"TYPECODE": "BRKD"}, "DEPARTMENTID": {"DEPARTMENTCODE": "*"}, "FIXED": "V"}
#                            (schema-required: WORKORDERID, STATUS, DEPARTMENTID, FIXED; call GetWorkOrderDefaults for your defaults)
#     UpdateWorkOrder        id = "10000%23ORG1", body = {"WORKORDERID": {"JOBNUM": "10000", "ORGANIZATIONID": {"ORGANIZATIONCODE": "ORG1"}},
#                                                       "STATUS": {"STATUSCODE": "C"}}   (PATCH carries the key block + changed fields)
#     AddAssetMeterReading   body = {"EQUIPMENTID": {"EQUIPMENTCODE": "PUMP-101", "ORGANIZATIONID": {"ORGANIZATIONCODE": "ORG1"}},
#                                    "UOMID": {"UOMCODE": "HR"}, "READINGTYPEID": {"READINGTYPECODE": "..."},
#                                    "READINGDATE": {"YEAR": 1759658100000, "MONTH": 10, "DAY": 5, "HOUR": 10, "MINUTE": 15, "SECOND": 0,
#                                                    "SUBSECOND": 0, "TIMEZONE": "+0100", "qualifier": "OTHER"},
#                                    "NEWVALUE": {"VALUE": 128750, "NUMOFDEC": 2, "SIGN": "+", "UOM": "HR", "qualifier": "OTHER"}}
#     QueryGrid              body = {"GRID": {"GRID_NAME": "WSJOBS", "USER_FUNCTION_NAME": "WSJOBS", "NUMBER_OF_ROWS_FIRST_RETURNED": 50},
#                                    "GRID_TYPE": {"TYPE": "LIST"}, "ADDON_FILTER": {"ALIAS_NAME": "workorderstatus", "OPERATOR": "=", "VALUE": "R"},
#                                    "REQUEST_TYPE": "LIST.HEAD_DATA.STORED"}
#

DEFINE CONNECTOR HxgnEamApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://eu1.eam.hxgnsmartcloud.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetWorkOrderDefaults
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order/defaults"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order/defaults/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/workorderdefaults"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateWorkOrder
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order/create"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/workorders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListWorkOrders
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order/list"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/workorders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT GetWorkOrder
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order/get"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/workorders/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT UpdateWorkOrder
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order/update"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/axis/restservices/workorders/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteWorkOrder
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order/delete"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/axis/restservices/workorders/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT AddWorkOrderActivity
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order-activity/create"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order-activity/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/workorders/activities"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListWorkOrderActivities
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order-activity/list"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order-activity/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/workorders/{value.json.parentid}/activities"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT AddWorkOrderComment
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order-comment/create"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order-comment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/workorders/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListWorkOrderComments
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order-comment/list"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order-comment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/workorders/{value.json.parentid}/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT AddWorkOrderMeterReading
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order-meter-reading/create"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order-meter-reading/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/workorders/meterreadings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT AddWorkOrderPart
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order-part/create"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order-part/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/workorders/parts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListWorkOrderParts
        WITH SOURCE_TOPIC "cmms/hxgn-eam/work-order-part/list"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/work-order-part/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/workorders/{value.json.parentid}/parts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT ListAssets
        WITH SOURCE_TOPIC "cmms/hxgn-eam/asset/list"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/asset/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/assets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT GetAsset
        WITH SOURCE_TOPIC "cmms/hxgn-eam/asset/get"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/asset/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/assets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT UpdateAsset
        WITH SOURCE_TOPIC "cmms/hxgn-eam/asset/update"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/asset/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/axis/restservices/assets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT AddAssetMeterReading
        WITH SOURCE_TOPIC "cmms/hxgn-eam/asset-meter-reading/create"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/asset-meter-reading/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/assets/meterreadings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListAssetMeterReadings
        WITH SOURCE_TOPIC "cmms/hxgn-eam/asset-meter-reading/list"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/asset-meter-reading/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/assets/{value.json.parentid}/meterreadings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT AddAssetComment
        WITH SOURCE_TOPIC "cmms/hxgn-eam/asset-comment/create"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/asset-comment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/assets/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListParts
        WITH SOURCE_TOPIC "cmms/hxgn-eam/part/list"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/part/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/parts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT GetPart
        WITH SOURCE_TOPIC "cmms/hxgn-eam/part/get"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/part/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/axis/restservices/parts/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
    ADD EVENT QueryGrid
        WITH SOURCE_TOPIC "cmms/hxgn-eam/grid/query"
        WITH DESTINATION_TOPIC "cmms/hxgn-eam/grid/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/axis/restservices/grids"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "tenant" "{value.json.tenant}"
            ADD "organization" "{value.json.organization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

Publish directly to a connector topic:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Basic <base64 user:password>", "tenant": "YOUR_TENANT", "organization": "ORG1", "id": "10000%23ORG1"}
```

to `cmms/hxgn-eam/work-order/get`, then read `cmms/hxgn-eam/work-order/get/response`.

Actions that feed the connector from plant data:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the HxgnEamApi route (docs page). Not part of the route template.
# Secret: HXGN_EAM_AUTHORIZATION = "Basic <base64 user:password>" for an EAM user with the Connector checkbox
#   (or "Bearer <OIDC token>"). Tenant and organization are not secret; replace YOUR_TENANT and ORG1.
# Ids in paths are "<code>%23<organization>" (the # URL-encoded). Codes below (PUMP-101, BRKD, HR, TOTAL) are examples;
#   use the values configured in your EAM tenant (GetWorkOrderDefaults returns the defaults for an organization).
# Dates: EAM date objects carry YEAR as epoch milliseconds unless install parameter RSYRYYYY = YES (EAM 12.3+), so the
#   edge payload below already carries the epoch ms and the date parts.

DEFINE ACTION HxgnEamWorkOrderFromAlarm
ON TOPIC "plant/line1/alarm/raised" DO
    SET "auth" WITH GET SECRET "HXGN_EAM_AUTHORIZATION"
    SET "alarm" WITH (GET JSON "alarm" IN PAYLOAD AS STRING)
    SET "value" WITH (GET JSON "value" IN PAYLOAD AS STRING)
    SET "desc" WITH "Coreflux alarm " + {alarm} + " (value " + {value} + ")"
    PUBLISH TOPIC "cmms/hxgn-eam/work-order/create" WITH { "authorization": {auth}, "tenant": "YOUR_TENANT", "organization": "ORG1", "body": { "WORKORDERID": { "JOBNUM": "", "ORGANIZATIONID": { "ORGANIZATIONCODE": "ORG1" }, "auto_generated": true }, "DESCRIPTION": {desc}, "STATUS": { "STATUSCODE": "R" }, "EQUIPMENTID": { "EQUIPMENTCODE": "PUMP-101", "ORGANIZATIONID": { "ORGANIZATIONCODE": "ORG1" } }, "TYPE": { "TYPECODE": "BRKD" }, "DEPARTMENTID": { "DEPARTMENTCODE": "*" }, "FIXED": "V" } }

DEFINE ACTION HxgnEamRuntimeHoursReading
ON TOPIC "plant/line1/pump101/runtime" DO
    SET "auth" WITH GET SECRET "HXGN_EAM_AUTHORIZATION"
    SET "hours" WITH (GET JSON "hours" IN PAYLOAD AS INT)
    SET "ms" WITH (GET JSON "epoch_ms" IN PAYLOAD AS INT)
    SET "mo" WITH (GET JSON "month" IN PAYLOAD AS INT)
    SET "dd" WITH (GET JSON "day" IN PAYLOAD AS INT)
    SET "hh" WITH (GET JSON "hour" IN PAYLOAD AS INT)
    SET "mi" WITH (GET JSON "minute" IN PAYLOAD AS INT)
    PUBLISH TOPIC "cmms/hxgn-eam/asset-meter-reading/create" WITH { "authorization": {auth}, "tenant": "YOUR_TENANT", "organization": "ORG1", "body": { "EQUIPMENTID": { "EQUIPMENTCODE": "PUMP-101", "ORGANIZATIONID": { "ORGANIZATIONCODE": "ORG1" } }, "UOMID": { "UOMCODE": "HR" }, "READINGTYPEID": { "READINGTYPECODE": "TOTAL" }, "READINGDATE": { "YEAR": {ms}, "MONTH": {mo}, "DAY": {dd}, "HOUR": {hh}, "MINUTE": {mi}, "SECOND": 0, "SUBSECOND": 0, "TIMEZONE": "+0000", "qualifier": "OTHER" }, "NEWVALUE": { "VALUE": {hours}, "NUMOFDEC": 0, "SIGN": "+", "UOM": "HR", "qualifier": "OTHER" } } }

DEFINE ACTION HxgnEamAssetOutOfServiceFromMachineState
ON TOPIC "plant/line1/pump101/state" DO
    SET "auth" WITH GET SECRET "HXGN_EAM_AUTHORIZATION"
    SET "state" WITH PAYLOAD AS STRING
    IF {state} EQUALS "running" THEN
        PUBLISH TOPIC "cmms/hxgn-eam/asset/update" WITH { "authorization": {auth}, "tenant": "YOUR_TENANT", "organization": "ORG1", "id": "PUMP-101%23ORG1", "body": { "ASSETID": { "EQUIPMENTCODE": "PUMP-101", "ORGANIZATIONID": { "ORGANIZATIONCODE": "ORG1" } }, "OUTOFSERVICE": "false" } }
    ELSE
        PUBLISH TOPIC "cmms/hxgn-eam/asset/update" WITH { "authorization": {auth}, "tenant": "YOUR_TENANT", "organization": "ORG1", "id": "PUMP-101%23ORG1", "body": { "ASSETID": { "EQUIPMENTCODE": "PUMP-101", "ORGANIZATIONID": { "ORGANIZATIONCODE": "ORG1" } }, "OUTOFSERVICE": "true" } }

DEFINE ACTION HxgnEamPollReleasedWorkOrders
ON EVERY 15 MINUTES DO
    SET "auth" WITH GET SECRET "HXGN_EAM_AUTHORIZATION"
    PUBLISH TOPIC "cmms/hxgn-eam/grid/query" WITH { "authorization": {auth}, "tenant": "YOUR_TENANT", "organization": "ORG1", "body": { "GRID": { "GRID_NAME": "WSJOBS", "USER_FUNCTION_NAME": "WSJOBS", "NUMBER_OF_ROWS_FIRST_RETURNED": 50 }, "GRID_TYPE": { "TYPE": "LIST" }, "ADDON_FILTER": { "ALIAS_NAME": "workorderstatus", "OPERATOR": "=", "VALUE": "R" }, "REQUEST_TYPE": "LIST.HEAD_DATA.STORED" } }
```

Restrict who can publish to `cmms/hxgn-eam/#` with a rule: its payloads carry EAM credentials and can create and delete work orders.

## Responses

Every reply uses the EAM envelope: `Result.ResultData` holds the data on `200`, `Result.InfoAlert` / `WarningAlert` carry messages, and `ErrorAlert` or `ConfirmationAlert` is set on `400`. `404` means an unknown service or record, `500` an internal error. With `keepsession: true` (fork), `Result.SessionID` can be reused in a `sessionid` header.

## Notes

* The catalog listed OAuth 2.0 through the Infor ION API gateway. Current HxGN EAM tenants publish `basicAuth`, `apiKey` (`X-API-Key`) and `bearerAuth` (OIDC) in their OpenAPI files; the ION gateway only applies to legacy Infor-hosted tenants and is not packaged.
* Work order statuses, types (`BRKD`, ...), departments, UOMs and reading types are tenant codes. The values in the examples are placeholders.
* HxGN EAM has no webhook API in the REST guide. Poll with `QueryGrid` or the list events.
* SOAP web services (`/axis/services/EWSConnector`) also exist; this connector uses REST only.

## Not covered

PUT (Sync) and DELETE on child records, work order book labor, checklists, schedules, purchasing, stores, PM schedules, cases, documents and the CSV grid service. All are in the EAM Swagger and can be added to a fork.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [MaintainX](/latest/lot-language/routes/rest-api-apps/maintainx)
* [IBM Maximo Manage](/latest/lot-language/routes/rest-api-apps/ibm-maximo-manage)


# IBM Maximo Manage
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ibm-maximo-manage

LoT connector for IBM Maximo Manage: create work orders from alarms, post meter readings, query approved work orders and update assets over REST from MQTT

Technical Preview

## Overview

A client-mode connector for a **curated CMMS / EAM** slice of the [IBM Maximo Manage REST/JSON APIs](https://www.ibm.com/docs/en/maximo-manage/cd?topic=reference-maximo-manage-rest-apis) (object structures under `https://YOUR_MAXIMO_HOST/maximo`):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST mxapiwodetail (work order from alarm) | `POST /api/os/mxapiwodetail?lean=1` | Create WO (lean JSON) |
| POST mxapimeterreading (run hours, counts) | `POST /api/os/mxapimeterreading?lean=1` | Meter reading; some installs need `x-method-override: SYNC` |
| GET mxapiwodetail?oslc.where=status=APPR | `GET /api/os/mxapiwodetail?oslc.where=status="APPR"&…` | Approved work orders |
| PATCH mxapiasset/\{id} | `PATCH /api/os/mxapiasset/{id}?lean=1` | Update asset; alternate POST + `x-method-override: PATCH` |

`BASE_ADDRESS` is `https://{host}/maximo` (no trailing slash; endpoints already include `/api/os/...`). Topics use `cmms/ibm-maximo-manage/<object>/<verb>`.

> [!NOTE]
>
> Prefer Hub secrets for API keys and passwords.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — IBM Maximo Manage (curated CMMS slice)
# Auth: apikey header {value.json.apikey} (or Basic via config)
# BASE_ADDRESS: https://YOUR_MAXIMO_HOST/maximo

DEFINE CONNECTOR IbmMaximoManageRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_MAXIMO_HOST/maximo"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Createworkorder
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/create"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/os/mxapiwodetail?lean=1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "apikey" "{value.json.apikey}"
            ADD "properties" "*"
        WITH BODY "{payload}"
    ADD EVENT Createmeterreading
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapimeterreading/create"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapimeterreading/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/os/mxapimeterreading?lean=1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "apikey" "{value.json.apikey}"
            ADD "properties" "*"
        WITH BODY "{payload}"
    ADD EVENT Listapprovedworkorders
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/list_appr"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapiwodetail/list_appr/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/os/mxapiwodetail?oslc.where={value.json.oslc_where}&oslc.select={value.json.oslc_select}&lean=1&oslc.pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "apikey" "{value.json.apikey}"
    ADD EVENT Patchasset
        WITH SOURCE_TOPIC "cmms/ibm-maximo-manage/mxapiasset/patch"
        WITH DESTINATION_TOPIC "cmms/ibm-maximo-manage/mxapiasset/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/os/mxapiasset/{value.json.id}?lean=1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "apikey" "{value.json.apikey}"
            ADD "properties" "*"
        WITH BODY "{payload}"
```

## Parameters

| Parameter | Required | Description |
| - | - | - |
| `BASE_ADDRESS` | Yes | `https://{host}/maximo` — Manage host, no trailing slash |
| `apikey` (MQTT JSON) | Yes\* | Maximo API key for the `apikey` request header (\*or use Basic config) |
| `USERNAME` / `PASSWORD` | Alt | Basic/LDAP via `WITH USERNAME` + `WITH PASSWORD GET SECRET "MAXIMO_PASSWORD"` |
| `oslc_where` | For list | e.g. `status="APPR"` (URL-encode as needed by your broker) |
| `oslc_select` | For list | e.g. `*` or `wonum,status,description,assetnum` |
| `page_size` | For list | `oslc.pageSize` value |
| `id` | For PATCH | Asset REST id (e.g. ASSETUID) |
| `{payload}` | POST/PATCH | Lean JSON body for the object structure |

## Authentication

* **API key (preferred for MAS 8.8+):** header `apikey: <key>`. Do not rely on maxauth for Manage integrations.
* **Basic / LDAP:** configure USERNAME + PASSWORD (GET SECRET) on `REST_API_CONFIG`.
* Prefer Hub secrets. Never commit real credentials.

## MQTT topics

| Event | Source topic | Method |
| - | - | - |
| Create WO | `cmms/ibm-maximo-manage/mxapiwodetail/create` | POST |
| Meter reading | `cmms/ibm-maximo-manage/mxapimeterreading/create` | POST |
| List APPR WOs | `cmms/ibm-maximo-manage/mxapiwodetail/list_appr` | GET |
| Patch asset | `cmms/ibm-maximo-manage/mxapiasset/patch` | PATCH |

Responses publish on the same topic with `/response` appended.

## Example payloads

**List approved work orders:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "apikey": "YOUR_MAXIMO_API_KEY",
  "oslc_where": "status=\"APPR\"",
  "oslc_select": "*",
  "page_size": "5"
}
```

**Create work order from alarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "apikey": "YOUR_MAXIMO_API_KEY",
  "description": "IIoT alarm — high vibration Zone A",
  "siteid": "BEDFORD",
  "assetnum": "11430",
  "priority": 2,
  "worktype": "CM"
}
```

## Notes and version quirks

* Use `lean=1` so JSON bodies do not require namespaces.
* `properties: *` on writes asks Maximo to return selected fields in the create/update response.
* Native HTTP PATCH may not be enabled on every install; IBM docs often show `POST` + `x-method-override: PATCH` (+ optional `patchtype: MERGE`). Fork the Patchasset event if needed.
* Meter readings via `MXAPIMETERREADING` can require `x-method-override: SYNC` on some systems; an alternate is nested `assetmeter` updates on `MXAPIASSET`.
* Object structures must be enabled / authorized for the API user in Maximo.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [IBM Maximo REST API Guide — API keys](https://ibm-maximo-dev.github.io/maximo-restapi-documentation/authentication/apikey/)
* [Filtering with oslc.where](https://ibm-maximo-dev.github.io/maximo-restapi-documentation/query/filtering/)
* [Create and update resources](https://ibm-maximo-dev.github.io/maximo-restapi-documentation/crud/create_and_update/)


# IFS Cloud REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ifs-cloud

Client-mode REST API connector for IFS Cloud OData v4 projections (Shop Orders, Equipment, Work Orders)

Technical Preview

## Overview

Client-mode REST API connector for IFS Cloud OData v4 projections (Shop Orders, Equipment, Work Orders). `BASE_ADDRESS` defaults to `https://YOUR_IFS_HOST/main/ifsapplications/projection/v1`. Auth: **OAuth 2.0 (IFS IAM) Bearer**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

OAuth 2.0 (IFS IAM) Bearer. Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR IfsCloudRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_IFS_HOST/main/ifsapplications/projection/v1"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Authorization Bearer {value.json.access_token} — prefer Hub secrets / GET SECRET.
        # Optional Basic: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Listshoporders
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Listshoporders"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Listshoporders"
        WITH METHOD "GET"
        WITH ENDPOINT "/ShopOrderHandling.svc/ShopOrders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getshoporder
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Getshoporder"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Getshoporder"
        WITH METHOD "GET"
        WITH ENDPOINT "/ShopOrderHandling.svc/ShopOrders({value.json.OrderNo})"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Reportoperation
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Reportoperation"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Reportoperation"
        WITH METHOD "POST"
        WITH ENDPOINT "/ShopOrderHandling.svc/ShopOrders({value.json.OrderNo})/IfsApp.ShopOrderHandling.ShopOrder_ReportOperation"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/ifs-cloud/request/...`; responses on `integrations/ifs-cloud/response/...`.

## Template reference

Generated from the shipped broker template `ifs-cloud` (`-connectorCode IFS_CLOUD`). It lists every event the template defines.

### Auth

OAuth 2.0 (IFS IAM) Bearer

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the IFS Cloud connector | no |
| `BaseUrl` | string | IFS Cloud base URL without trailing slash (e.g. https\://YOUR\_IFS\_HOST/main/ifsapplications/projection/v1) | yes |

`BASE_ADDRESS` default: `https://YOUR_IFS_HOST/main/ifsapplications/projection/v1`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listshoporders` | GET | `/ShopOrderHandling.svc/ShopOrders` | `integrations/ifs-cloud/request/Listshoporders` | `integrations/ifs-cloud/response/Listshoporders` | `access_token` |
| `Getshoporder` | GET | `/ShopOrderHandling.svc/ShopOrders({value.json.OrderNo})` | `integrations/ifs-cloud/request/Getshoporder` | `integrations/ifs-cloud/response/Getshoporder` | `OrderNo`, `access_token` |
| `Reportoperation` | POST | `/ShopOrderHandling.svc/ShopOrders({value.json.OrderNo})/IfsApp.ShopOrderHandling.ShopOrder_ReportOperation` | `integrations/ifs-cloud/request/Reportoperation` | `integrations/ifs-cloud/response/Reportoperation` | `OrderNo`, `access_token`, `body` |
| `Listequipmentobjects` | GET | `/EquipmentObjectHandling.svc/EquipmentObjects` | `integrations/ifs-cloud/request/Listequipmentobjects` | `integrations/ifs-cloud/response/Listequipmentobjects` | `access_token` |
| `Getequipmentobject` | GET | `/EquipmentObjectHandling.svc/EquipmentObjects({value.json.EquipmentObjectSeq})` | `integrations/ifs-cloud/request/Getequipmentobject` | `integrations/ifs-cloud/response/Getequipmentobject` | `EquipmentObjectSeq`, `access_token` |
| `Listinventoryparts` | GET | `/InventoryPartHandling.svc/InventoryParts` | `integrations/ifs-cloud/request/Listinventoryparts` | `integrations/ifs-cloud/response/Listinventoryparts` | `access_token` |
| `Listworkorders` | GET | `/WorkOrderHandling.svc/WorkOrders` | `integrations/ifs-cloud/request/Listworkorders` | `integrations/ifs-cloud/response/Listworkorders` | `access_token` |
| `Createworkorder` | POST | `/WorkOrderHandling.svc/WorkOrders` | `integrations/ifs-cloud/request/Createworkorder` | `integrations/ifs-cloud/response/Createworkorder` | `access_token`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode IFS_CLOUD"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR IfsCloudRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_IFS_HOST/main/ifsapplications/projection/v1"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listshoporders
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Listshoporders"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Listshoporders"
        WITH METHOD "GET"
        WITH ENDPOINT "/ShopOrderHandling.svc/ShopOrders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getshoporder
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Getshoporder"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Getshoporder"
        WITH METHOD "GET"
        WITH ENDPOINT "/ShopOrderHandling.svc/ShopOrders({value.json.OrderNo})"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Reportoperation
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Reportoperation"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Reportoperation"
        WITH METHOD "POST"
        WITH ENDPOINT "/ShopOrderHandling.svc/ShopOrders({value.json.OrderNo})/IfsApp.ShopOrderHandling.ShopOrder_ReportOperation"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Listequipmentobjects
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Listequipmentobjects"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Listequipmentobjects"
        WITH METHOD "GET"
        WITH ENDPOINT "/EquipmentObjectHandling.svc/EquipmentObjects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getequipmentobject
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Getequipmentobject"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Getequipmentobject"
        WITH METHOD "GET"
        WITH ENDPOINT "/EquipmentObjectHandling.svc/EquipmentObjects({value.json.EquipmentObjectSeq})"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Listinventoryparts
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Listinventoryparts"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Listinventoryparts"
        WITH METHOD "GET"
        WITH ENDPOINT "/InventoryPartHandling.svc/InventoryParts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Listworkorders
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Listworkorders"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Listworkorders"
        WITH METHOD "GET"
        WITH ENDPOINT "/WorkOrderHandling.svc/WorkOrders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createworkorder
        WITH SOURCE_TOPIC "integrations/ifs-cloud/request/Createworkorder"
        WITH DESTINATION_TOPIC "integrations/ifs-cloud/response/Createworkorder"
        WITH METHOD "POST"
        WITH ENDPOINT "/WorkOrderHandling.svc/WorkOrders"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listshoporders` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/ifs-cloud/response/Listshoporders' &
mosquitto_pub -t 'integrations/ifs-cloud/request/Listshoporders' -m '{"access_token": "<access_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# Ignition (Inductive Automation)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ignition

Client-mode REST API connector for Ignition 8.3+ Gateway: overview/gateway-info health, tag-provider list, tags export, and WebDev tag read/write/history

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [Ignition 8.3 Gateway HTTP API](https://www.docs.inductiveautomation.com/docs/8.3/platform/gateway/openapi) under `https://{gateway}:8088`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET gateway status | `GET /data/api/v1/overview` | Health |
| (info) | `GET /data/api/v1/gateway-info` | Gateway identity / version |
| (discovery) | `GET /data/api/v1/resources/list/ignition/tag-provider` | List tag providers |
| (config export) | `GET /data/api/v1/tags/export` | Tag **configuration** export (8.3.2+); not live values |
| GET tag values | `GET /system/webdev/{project}/tags/read` | **WebDev** — live tag values |
| POST tag writes | `POST /system/webdev/{project}/tags/write` | **WebDev** |
| GET tag history | `GET /system/webdev/{project}/tags/history` | **WebDev** wrapping historian scripting |

`BASE_ADDRESS` is the gateway root (no trailing slash; endpoints start with `/`). Topics use `historian/ignition/<object>/<verb>`. Default stub port is `8088` (HTTPS often on `8043`).

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Gateway + API Key required.** There is no public Ignition sandbox. Replace `YOUR_GATEWAY` and supply an API Key (`X-Ignition-API-Token`). Prefer Hub secrets.

> [!NOTE]
>
> **WebDev for live tags.** Stock 8.3 OpenAPI is mainly configuration and status. Live tag read/write/history need a WebDev project (custom or e.g. SFLOW MCP Connector) exposing `/system/webdev/{project}/tags/*`.

> [!NOTE]
>
> Prefer Hub secrets for API tokens.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Ignition 8.3+ Gateway
# Auth: X-Ignition-API-Token: {value.json.api_token}
# BASE_ADDRESS: https://YOUR_GATEWAY:8088

DEFINE CONNECTOR IgnitionRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_GATEWAY:8088"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetGatewayOverview
        WITH SOURCE_TOPIC "historian/ignition/gateway/overview"
        WITH DESTINATION_TOPIC "historian/ignition/gateway/overview/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/api/v1/overview"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Ignition-API-Token" "{value.json.api_token}"
    ADD EVENT GetTagValues
        WITH SOURCE_TOPIC "historian/ignition/tags/read"
        WITH DESTINATION_TOPIC "historian/ignition/tags/read/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system/webdev/{value.json.project}/tags/read?paths={value.json.paths}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Ignition-API-Token" "{value.json.api_token}"
    ADD EVENT WriteTagValues
        WITH SOURCE_TOPIC "historian/ignition/tags/write"
        WITH DESTINATION_TOPIC "historian/ignition/tags/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/system/webdev/{value.json.project}/tags/write"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Ignition-API-Token" "{value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT GetTagHistory
        WITH SOURCE_TOPIC "historian/ignition/tags/history"
        WITH DESTINATION_TOPIC "historian/ignition/tags/history/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system/webdev/{value.json.project}/tags/history?paths={value.json.paths}&startTime={value.json.startTime}&endTime={value.json.endTime}&returnSize={value.json.returnSize}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Ignition-API-Token" "{value.json.api_token}"
```

The full package also includes `GetGatewayInfo`, `ListTagProviders`, and `ExportTags`.

## Parameters

| Parameter | Required | Description |
| - | - | - |
| `BASE_ADDRESS` | Yes | `https://{gateway}:8088` (or HTTPS port) — no trailing slash |
| `api_token` | Yes | API Key value for `X-Ignition-API-Token` |
| `project` | For WebDev events | WebDev project name |
| `paths` | For read/history | Comma-separated tag paths |
| `provider` / `path` | For export | Tag provider name and optional folder path |
| `startTime` / `endTime` / `returnSize` | For history | Historian query window |

## Authentication

1. Create an API Key: **Platform > Security > API Keys**.
2. Send header `X-Ignition-API-Token: <token>` on each request.
3. Pass the token in MQTT JSON as `api_token`. Prefer Hub secrets — never commit keys.
4. WebDev may also accept HTTP Basic depending on project security settings.

## MQTT topics

| Event | Source topic | Response topic |
| - | - | - |
| GetGatewayOverview | `historian/ignition/gateway/overview` | `…/response` |
| GetGatewayInfo | `historian/ignition/gateway/info` | `…/response` |
| ListTagProviders | `historian/ignition/tag-providers/list` | `…/response` |
| ExportTags | `historian/ignition/tags/export` | `…/response` |
| GetTagValues | `historian/ignition/tags/read` | `…/response` |
| WriteTagValues | `historian/ignition/tags/write` | `…/response` |
| GetTagHistory | `historian/ignition/tags/history` | `…/response` |

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [AVEVA PI Web API](/latest/lot-language/routes/rest-api-apps/aveva-pi-web-api)
* [AVEVA CONNECT data services](/latest/lot-language/routes/rest-api-apps/aveva-connect-data-services)
* Ignition OpenAPI docs: [https://www.docs.inductiveautomation.com/docs/8.3/platform/gateway/openapi](https://www.docs.inductiveautomation.com/docs/8.3/platform/gateway/openapi)
* API Keys: [https://www.docs.inductiveautomation.com/docs/8.3/platform/security/api-keys](https://www.docs.inductiveautomation.com/docs/8.3/platform/security/api-keys)


# InfluxDB
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/influxdb

Client-mode REST API connector for InfluxDB v2 write/query/health and InfluxDB 3 write_lp / query_sql — line protocol from MQTT into org/bucket or database

Technical Preview

## Overview

A client-mode connector for a **curated** slice of [InfluxDB](https://docs.influxdata.com/influxdb/v2/api/v2/) (OSS and Cloud v2) plus [InfluxDB 3](https://docs.influxdata.com/influxdb3/core/write-data/) HTTP write/query:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET health | `GET /health` | Usually unauthenticated on OSS |
| (supporting) ping | `GET /ping` | `204` + version headers |
| POST write?org=\&bucket= | `POST /api/v2/write` | **Line protocol** body — `text/plain` |
| POST query (Flux) | `POST /api/v2/query` | Flux body — `application/vnd.flux`, Accept CSV |
| (supporting) buckets / orgs | `GET /api/v2/buckets`, `GET /api/v2/orgs` | discovery |
| (v3) write\_lp | `POST /api/v3/write_lp?db=` | InfluxDB 3 line protocol |
| (v3) query\_sql | `POST /api/v3/query_sql` | JSON `{"db","q"}` |

Default `BASE_ADDRESS` is `https://YOUR_INFLUXDB_HOST` (no trailing slash). Cloud example: `https://{region}.cloud2.influxdata.com`. OSS often `http://host:8086` — set `USE_SSL "false"` when not TLS. Topics use `data/influxdb/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth scheme:** use `Authorization: Token &lt;token&gt;` — **not** Bearer. Prefer Hub secrets (`GET SECRET "INFLUXDB_TOKEN"` or `"INFLUX_TOKEN"`).

> [!NOTE]
>
> **Line protocol:** `PostWrite` and `PostWriteLpV3` send the MQTT payload as the HTTP body with `Content-Type: text/plain; charset=utf-8`. Build measurement lines upstream (Telegraf MQTT consumer, LoT action, or edge agent).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — InfluxDB v2 / v3
# Auth: Authorization: Token {value.json.api_token}
# BASE_ADDRESS: https://YOUR_INFLUXDB_HOST

DEFINE CONNECTOR InfluxdbRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INFLUXDB_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetHealth
        WITH SOURCE_TOPIC "data/influxdb/health"
        WITH DESTINATION_TOPIC "data/influxdb/health/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/health"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT PostWrite
        WITH SOURCE_TOPIC "data/influxdb/write"
        WITH DESTINATION_TOPIC "data/influxdb/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/write?org={value.json.org}&bucket={value.json.bucket}&precision={value.json.precision}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain; charset=utf-8"
            ADD "Authorization" "Token {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT PostQuery
        WITH SOURCE_TOPIC "data/influxdb/query"
        WITH DESTINATION_TOPIC "data/influxdb/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/query?org={value.json.org}"
        WITH HEADERS
            ADD "Accept" "application/csv"
            ADD "Content-Type" "application/vnd.flux"
            ADD "Authorization" "Token {value.json.api_token}"
        WITH BODY "{payload}"
```

## Auth and placeholders

| Placeholder | Meaning |
| - | - |
| `{value.json.api_token}` | InfluxDB API token → `Authorization: Token …` |
| `{value.json.org}` | v2 org name or id |
| `{value.json.bucket}` | v2 bucket name |
| `{value.json.precision}` | `ns` / `us` / `ms` / `s` |
| `{value.json.db}` | InfluxDB 3 database name |
| `{payload}` | Line protocol string (write) or Flux script / SQL JSON (query) |

## Template reference

Generated from the shipped broker template `influxdb` (`-connectorCode INFLUXDB`). It lists every event the template defines.

### Auth

Authorization: Token \{value.json.api\_token} (InfluxDB API token / operator token). Prefer GET SECRET INFLUXDB\_TOKEN or INFLUX\_TOKEN. Never commit real credentials. Not Bearer.

Auth headers used by the template: `Authorization: Token {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the InfluxDB connector | no |
| `BaseUrl` | string | InfluxDB base URL without trailing slash (e.g. https\://YOUR\_INFLUXDB\_HOST) | yes |

`BASE_ADDRESS` default: `https://YOUR_INFLUXDB_HOST`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetHealth` | GET | `/health` | `data/influxdb/health` | `data/influxdb/health/response` | none |
| `GetPing` | GET | `/ping` | `data/influxdb/ping` | `data/influxdb/ping/response` | none |
| `PostWrite` | POST | `/api/v2/write?org={value.json.org}&bucket={value.json.bucket}&precision={value.json.precision}` | `data/influxdb/write` | `data/influxdb/write/response` | `api_token`, `body`, `bucket`, `org`, `precision` |
| `PostQuery` | POST | `/api/v2/query?org={value.json.org}` | `data/influxdb/query` | `data/influxdb/query/response` | `api_token`, `body`, `org` |
| `GetBuckets` | GET | `/api/v2/buckets?org={value.json.org}` | `data/influxdb/buckets` | `data/influxdb/buckets/response` | `api_token`, `org` |
| `GetOrgs` | GET | `/api/v2/orgs` | `data/influxdb/orgs` | `data/influxdb/orgs/response` | `api_token` |
| `PostWriteLpV3` | POST | `/api/v3/write_lp?db={value.json.db}&precision={value.json.precision}` | `data/influxdb/v3/write` | `data/influxdb/v3/write/response` | `api_token`, `body`, `db`, `precision` |
| `PostQuerySqlV3` | POST | `/api/v3/query_sql` | `data/influxdb/v3/query-sql` | `data/influxdb/v3/query-sql/response` | `api_token`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode INFLUXDB"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR InfluxdbRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INFLUXDB_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetHealth
        WITH SOURCE_TOPIC "data/influxdb/health"
        WITH DESTINATION_TOPIC "data/influxdb/health/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/health"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetPing
        WITH SOURCE_TOPIC "data/influxdb/ping"
        WITH DESTINATION_TOPIC "data/influxdb/ping/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ping"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT PostWrite
        WITH SOURCE_TOPIC "data/influxdb/write"
        WITH DESTINATION_TOPIC "data/influxdb/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/write?org={value.json.org}&bucket={value.json.bucket}&precision={value.json.precision}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain; charset=utf-8"
            ADD "Authorization" "Token {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT PostQuery
        WITH SOURCE_TOPIC "data/influxdb/query"
        WITH DESTINATION_TOPIC "data/influxdb/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/query?org={value.json.org}"
        WITH HEADERS
            ADD "Accept" "application/csv"
            ADD "Content-Type" "application/vnd.flux"
            ADD "Authorization" "Token {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetBuckets
        WITH SOURCE_TOPIC "data/influxdb/buckets"
        WITH DESTINATION_TOPIC "data/influxdb/buckets/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/buckets?org={value.json.org}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Token {value.json.api_token}"
    ADD EVENT GetOrgs
        WITH SOURCE_TOPIC "data/influxdb/orgs"
        WITH DESTINATION_TOPIC "data/influxdb/orgs/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/orgs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Token {value.json.api_token}"
    ADD EVENT PostWriteLpV3
        WITH SOURCE_TOPIC "data/influxdb/v3/write"
        WITH DESTINATION_TOPIC "data/influxdb/v3/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/write_lp?db={value.json.db}&precision={value.json.precision}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain; charset=utf-8"
            ADD "Authorization" "Token {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT PostQuerySqlV3
        WITH SOURCE_TOPIC "data/influxdb/v3/query-sql"
        WITH DESTINATION_TOPIC "data/influxdb/v3/query-sql/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/query_sql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Token {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `GetHealth` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'data/influxdb/health/response' &
mosquitto_pub -t 'data/influxdb/health' -m '{}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [InfluxDB v2 API](https://docs.influxdata.com/influxdb/v2/api/v2/)
* [Write with the API](https://docs.influxdata.com/influxdb/v2/write-data/developer-tools/api/)
* [Query with the API](https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/influx-api/)
* [InfluxDB 3 write data](https://docs.influxdata.com/influxdb3/core/write-data/)


# Infor CloudSuite via ION API Gateway REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/infor-cloudsuite-via-ion-api-gateway

Client-mode REST API connector for Infor CloudSuite M3/CSI via ION API Gateway

Technical Preview

## Overview

Client-mode REST API connector for Infor CloudSuite M3/CSI via ION API Gateway. `BASE_ADDRESS` defaults to `https://mingle-ionapi.YOUR_REGION.inforcloudsuite.com/YOUR_TENANT`. Auth: **OAuth 2.0 Bearer (.ionapi service account or auth code)**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

OAuth 2.0 Bearer (.ionapi service account or auth code). Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR InforCloudsuiteViaIonApiGatewayRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://mingle-ionapi.YOUR_REGION.inforcloudsuite.com/YOUR_TENANT"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Authorization Bearer {value.json.access_token} — prefer Hub secrets / GET SECRET.
        # Optional Basic: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT M3Lstoperations
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Lstoperations"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Lstoperations"
        WITH METHOD "GET"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute/MOS070MI/LstOperations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT M3Rptoperation
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Rptoperation"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Rptoperation"
        WITH METHOD "POST"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute/PMS050MI/RptOperation"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT M3Getitem
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Getitem"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Getitem"
        WITH METHOD "GET"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute/MMS200MI/Get"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/infor-cloudsuite-via-ion-api-gateway/request/...`; responses on `integrations/infor-cloudsuite-via-ion-api-gateway/response/...`.

## Template reference

Generated from the shipped broker template `infor-cloudsuite-via-ion-api-gateway` (`-connectorCode INFOR_CLOUDSUITE_VIA_ION_API_GATEWAY`). It lists every event the template defines.

### Auth

OAuth 2.0 Bearer (.ionapi service account or auth code)

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Infor CloudSuite via ION API Gateway connector | no |
| `BaseUrl` | string | Infor CloudSuite via ION API Gateway base URL without trailing slash (e.g. [https://mingle-ionapi.YOUR\_REGION.inforcloudsuite.com/YOUR\_TENANT](https://mingle-ionapi.YOUR_REGION.inforcloudsuite.com/YOUR_TENANT)) | yes |

`BASE_ADDRESS` default: `https://mingle-ionapi.YOUR_REGION.inforcloudsuite.com/YOUR_TENANT`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `M3Lstoperations` | GET | `/M3/m3api-rest/v2/execute/MOS070MI/LstOperations` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Lstoperations` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Lstoperations` | `access_token` |
| `M3Rptoperation` | POST | `/M3/m3api-rest/v2/execute/PMS050MI/RptOperation` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Rptoperation` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Rptoperation` | `access_token`, `body` |
| `M3Getitem` | GET | `/M3/m3api-rest/v2/execute/MMS200MI/Get` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Getitem` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Getitem` | `access_token` |
| `M3Lstitems` | GET | `/M3/m3api-rest/v2/execute/MMS200MI/Lst` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Lstitems` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Lstitems` | `access_token` |
| `Csigetitems` | GET | `/CSI/IDORequestService/ido/load/Items?properties={value.json.properties}` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/Csigetitems` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/Csigetitems` | `access_token`, `mongoose_config`, `properties` |
| `Csiinvokeitems` | POST | `/CSI/IDORequestService/ido/invoke/Items?method={value.json.method}` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/Csiinvokeitems` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/Csiinvokeitems` | `access_token`, `body`, `method`, `mongoose_config` |
| `M3Execute` | POST | `/M3/m3api-rest/v2/execute` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Execute` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Execute` | `access_token`, `body` |
| `Ionlistservices` | GET | `/IONSERVICES/api/ion/service/list` | `integrations/infor-cloudsuite-via-ion-api-gateway/request/Ionlistservices` | `integrations/infor-cloudsuite-via-ion-api-gateway/response/Ionlistservices` | `access_token` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode INFOR_CLOUDSUITE_VIA_ION_API_GATEWAY"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR InforCloudsuiteViaIonApiGatewayRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://mingle-ionapi.YOUR_REGION.inforcloudsuite.com/YOUR_TENANT"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT M3Lstoperations
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Lstoperations"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Lstoperations"
        WITH METHOD "GET"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute/MOS070MI/LstOperations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT M3Rptoperation
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Rptoperation"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Rptoperation"
        WITH METHOD "POST"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute/PMS050MI/RptOperation"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT M3Getitem
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Getitem"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Getitem"
        WITH METHOD "GET"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute/MMS200MI/Get"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT M3Lstitems
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Lstitems"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Lstitems"
        WITH METHOD "GET"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute/MMS200MI/Lst"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Csigetitems
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/Csigetitems"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/Csigetitems"
        WITH METHOD "GET"
        WITH ENDPOINT "/CSI/IDORequestService/ido/load/Items?properties={value.json.properties}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Infor-MongooseConfig" "{value.json.mongoose_config}"
    ADD EVENT Csiinvokeitems
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/Csiinvokeitems"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/Csiinvokeitems"
        WITH METHOD "POST"
        WITH ENDPOINT "/CSI/IDORequestService/ido/invoke/Items?method={value.json.method}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Infor-MongooseConfig" "{value.json.mongoose_config}"
        WITH BODY "{value.json.body}"
    ADD EVENT M3Execute
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Execute"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Execute"
        WITH METHOD "POST"
        WITH ENDPOINT "/M3/m3api-rest/v2/execute"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Ionlistservices
        WITH SOURCE_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/request/Ionlistservices"
        WITH DESTINATION_TOPIC "integrations/infor-cloudsuite-via-ion-api-gateway/response/Ionlistservices"
        WITH METHOD "GET"
        WITH ENDPOINT "/IONSERVICES/api/ion/service/list"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `M3Lstoperations` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/infor-cloudsuite-via-ion-api-gateway/response/M3Lstoperations' &
mosquitto_pub -t 'integrations/infor-cloudsuite-via-ion-api-gateway/request/M3Lstoperations' -m '{"access_token": "<access_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# Intercom
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/intercom

LoT connector for the Intercom REST API: open conversations and tickets from machine alarms, reply, assign or close them, and update contacts and companies

Technical Preview

## Overview

A client-mode connector for the [Intercom REST API](https://developers.intercom.com/docs/references/introduction) that connects plant and product events to customer support. A connected machine that raises an alarm can open a conversation or a ticket for its owner, the support team can be told when it clears, and contact or company custom attributes (firmware, run hours, machines online) stay current from live data. Usage can be recorded as Intercom events so it shows on the customer's timeline.

Every event pins `Intercom-Version: 2.16`, the latest generally available version (released 2026-07-15), so a change of the app's default version in the Developer Hub does not change the connector's behaviour. Topics use `crm/intercom/<object>/<verb>`; each response is published on `<source topic>/response`.

## Authentication

Create an app in the Intercom Developer Hub and copy its access token from **Configure > Authentication** in the app (see [Intercom authentication](https://developers.intercom.com/docs/build-an-integration/learn-more/authentication)). Public apps use an OAuth access token instead; the header is the same. The connector sends `Authorization: Bearer <token>`, taken from the `access_token` field of each MQTT payload.

> [!WARNING]
>
> Do not publish the token in retained messages. Store it as a broker secret (for example `INTERCOM_ACCESS_TOKEN`) and have a LoT action add it to the payload with `GET SECRET` before publishing to the connector topic.

Workspaces hosted in Europe or Australia use a different host. Change `BASE_ADDRESS` to `https://api.eu.intercom.io` or `https://api.au.intercom.io`.

## Payload fields

| Field | Used by | Notes |
| - | - | - |
| `access_token` | every event | Intercom access token |
| `id` | `...Get`, `...Update`, reply, manage, notes, tags | Intercom id of the contact, conversation or ticket |
| `external_id` | `ContactGetByExternalId` | Your own customer id |
| `query` | `CompaniesFind`, `EventsList`, `DataAttributesList` | URL-encoded query string |
| `body` | create, update, reply and search events | JSON object sent as the request body |

## Events

| Event | Method | Endpoint | Source topic | Write |
| - | - | - | - | - |
| `CurrentAdmin` | `GET` | `/me` | `crm/intercom/me/get` | |
| `AdminsList` | `GET` | `/admins` | `crm/intercom/admins/list` | |
| `ContactsSearch` | `POST` | `/contacts/search` | `crm/intercom/contacts/search` | |
| `ContactGet` | `GET` | `/contacts/{id}` | `crm/intercom/contacts/get` | |
| `ContactGetByExternalId` | `GET` | `/contacts/find_by_external_id/{external_id}` | `crm/intercom/contacts/by-external-id/get` | |
| `ContactCreate` | `POST` | `/contacts` | `crm/intercom/contacts/create` | yes |
| `ContactUpdate` | `PUT` | `/contacts/{id}` | `crm/intercom/contacts/update` | yes |
| `CompaniesFind` | `GET` | `/companies?{query}` | `crm/intercom/companies/find` | |
| `CompanyUpsert` | `POST` | `/companies` | `crm/intercom/companies/upsert` | yes |
| `EventCreate` | `POST` | `/events` | `crm/intercom/events/create` | yes |
| `EventsList` | `GET` | `/events?{query}` | `crm/intercom/events/list` | |
| `ConversationCreate` | `POST` | `/conversations` | `crm/intercom/conversations/create` | yes |
| `ConversationsSearch` | `POST` | `/conversations/search` | `crm/intercom/conversations/search` | |
| `ConversationGet` | `GET` | `/conversations/{id}` | `crm/intercom/conversations/get` | |
| `ConversationReply` | `POST` | `/conversations/{id}/reply` | `crm/intercom/conversations/reply` | yes |
| `ConversationManage` | `POST` | `/conversations/{id}/parts` | `crm/intercom/conversations/manage` | yes |
| `ContactNoteCreate` | `POST` | `/contacts/{id}/notes` | `crm/intercom/contacts/notes/create` | yes |
| `TicketTypesList` | `GET` | `/ticket_types` | `crm/intercom/ticket-types/list` | |
| `TicketCreate` | `POST` | `/tickets` | `crm/intercom/tickets/create` | yes |
| `TicketUpdate` | `PUT` | `/tickets/{id}` | `crm/intercom/tickets/update` | yes |
| `TicketsSearch` | `POST` | `/tickets/search` | `crm/intercom/tickets/search` | |
| `TagsList` | `GET` | `/tags` | `crm/intercom/tags/list` | |
| `ContactTag` | `POST` | `/contacts/{id}/tags` | `crm/intercom/contacts/tags/add` | yes |
| `DataAttributesList` | `GET` | `/data_attributes?{query}` | `crm/intercom/data-attributes/list` | |
| `MessageCreate` | `POST` | `/messages` | `crm/intercom/messages/create` | yes |

The three `POST .../search` events only read data; Intercom uses a JSON body for search queries. No delete, merge, archive, block or redact events are packaged on purpose.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR IntercomRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.intercom.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CurrentAdmin
        WITH SOURCE_TOPIC "crm/intercom/me/get"
        WITH DESTINATION_TOPIC "crm/intercom/me/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT AdminsList
        WITH SOURCE_TOPIC "crm/intercom/admins/list"
        WITH DESTINATION_TOPIC "crm/intercom/admins/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/admins"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT ContactsSearch
        WITH SOURCE_TOPIC "crm/intercom/contacts/search"
        WITH DESTINATION_TOPIC "crm/intercom/contacts/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/contacts/search"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ContactGet
        WITH SOURCE_TOPIC "crm/intercom/contacts/get"
        WITH DESTINATION_TOPIC "crm/intercom/contacts/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/contacts/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT ContactGetByExternalId
        WITH SOURCE_TOPIC "crm/intercom/contacts/by-external-id/get"
        WITH DESTINATION_TOPIC "crm/intercom/contacts/by-external-id/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/contacts/find_by_external_id/{value.json.external_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT ContactCreate
        WITH SOURCE_TOPIC "crm/intercom/contacts/create"
        WITH DESTINATION_TOPIC "crm/intercom/contacts/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/contacts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ContactUpdate
        WITH SOURCE_TOPIC "crm/intercom/contacts/update"
        WITH DESTINATION_TOPIC "crm/intercom/contacts/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/contacts/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CompaniesFind
        WITH SOURCE_TOPIC "crm/intercom/companies/find"
        WITH DESTINATION_TOPIC "crm/intercom/companies/find/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/companies?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT CompanyUpsert
        WITH SOURCE_TOPIC "crm/intercom/companies/upsert"
        WITH DESTINATION_TOPIC "crm/intercom/companies/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/companies"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT EventCreate
        WITH SOURCE_TOPIC "crm/intercom/events/create"
        WITH DESTINATION_TOPIC "crm/intercom/events/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT EventsList
        WITH SOURCE_TOPIC "crm/intercom/events/list"
        WITH DESTINATION_TOPIC "crm/intercom/events/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/events?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT ConversationCreate
        WITH SOURCE_TOPIC "crm/intercom/conversations/create"
        WITH DESTINATION_TOPIC "crm/intercom/conversations/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/conversations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationsSearch
        WITH SOURCE_TOPIC "crm/intercom/conversations/search"
        WITH DESTINATION_TOPIC "crm/intercom/conversations/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/conversations/search"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationGet
        WITH SOURCE_TOPIC "crm/intercom/conversations/get"
        WITH DESTINATION_TOPIC "crm/intercom/conversations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/conversations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT ConversationReply
        WITH SOURCE_TOPIC "crm/intercom/conversations/reply"
        WITH DESTINATION_TOPIC "crm/intercom/conversations/reply/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/conversations/{value.json.id}/reply"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ConversationManage
        WITH SOURCE_TOPIC "crm/intercom/conversations/manage"
        WITH DESTINATION_TOPIC "crm/intercom/conversations/manage/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/conversations/{value.json.id}/parts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ContactNoteCreate
        WITH SOURCE_TOPIC "crm/intercom/contacts/notes/create"
        WITH DESTINATION_TOPIC "crm/intercom/contacts/notes/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/contacts/{value.json.id}/notes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TicketTypesList
        WITH SOURCE_TOPIC "crm/intercom/ticket-types/list"
        WITH DESTINATION_TOPIC "crm/intercom/ticket-types/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ticket_types"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT TicketCreate
        WITH SOURCE_TOPIC "crm/intercom/tickets/create"
        WITH DESTINATION_TOPIC "crm/intercom/tickets/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tickets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TicketUpdate
        WITH SOURCE_TOPIC "crm/intercom/tickets/update"
        WITH DESTINATION_TOPIC "crm/intercom/tickets/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/tickets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TicketsSearch
        WITH SOURCE_TOPIC "crm/intercom/tickets/search"
        WITH DESTINATION_TOPIC "crm/intercom/tickets/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tickets/search"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TagsList
        WITH SOURCE_TOPIC "crm/intercom/tags/list"
        WITH DESTINATION_TOPIC "crm/intercom/tags/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT ContactTag
        WITH SOURCE_TOPIC "crm/intercom/contacts/tags/add"
        WITH DESTINATION_TOPIC "crm/intercom/contacts/tags/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/contacts/{value.json.id}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DataAttributesList
        WITH SOURCE_TOPIC "crm/intercom/data-attributes/list"
        WITH DESTINATION_TOPIC "crm/intercom/data-attributes/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/data_attributes?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
    ADD EVENT MessageCreate
        WITH SOURCE_TOPIC "crm/intercom/messages/create"
        WITH DESTINATION_TOPIC "crm/intercom/messages/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Intercom-Version" "2.16"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

**Conversation from an alarm**

Publish to `crm/intercom/conversations/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from GET SECRET>", "body": {"from": {"type": "user", "id": "<contact id>"}, "body": "Press 7 reports overtemperature (E42)"}}
```

When the alarm clears, publish `{"access_token": "...", "id": "<conversation id>", "body": {"message_type": "close", "type": "admin", "admin_id": "<admin id>", "body": "Cleared by the line"}}` to `crm/intercom/conversations/manage`.

**Contact custom attributes**

Check the attribute names with `crm/intercom/data-attributes/list` (`"query": "model=contact"`), then publish to `crm/intercom/contacts/update`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from GET SECRET>", "id": "<contact id>", "body": {"custom_attributes": {"firmware": "4.2.1", "run_hours": 1820}}}
```

**Usage event**

Publish to `crm/intercom/events/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from GET SECRET>", "body": {"event_name": "machine-alarm", "created_at": 1791000000, "user_id": "cust-1042", "metadata": {"code": "E42", "line": "4"}}}
```

Intercom answers `202 Accepted` with an empty body. `created_at` is a Unix timestamp in seconds.

**Ticket for the service team**

Get a `ticket_type_id` from `crm/intercom/ticket-types/list`, then publish to `crm/intercom/tickets/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from GET SECRET>", "body": {"ticket_type_id": "<id>", "contacts": [{"id": "<contact id>"}], "ticket_attributes": {"_default_title_": "Press 7 overtemperature", "_default_description_": "E42 at 13:55"}}}
```

## Webhooks into the broker

Intercom webhooks (topics such as `conversation.user.created` or `ticket.state.updated`) are set up on the app's **Webhooks** page in the Developer Hub, not through the API. Intercom then POSTs each notification to your endpoint and signs it with an `X-Hub-Signature` header (`sha1=` plus the HMAC-SHA1 of the JSON body, keyed with the app's `client_secret` from its Basic Info page). To receive them, run a separate server-mode connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR IntercomWebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8443'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT IntercomNotification
        WITH ENDPOINT "/intercom/webhook"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "crm/intercom/webhook/events"
```

The receiver must be reachable from the internet over HTTPS. It is not part of the client template.

## Rate limits

By default an app may make 10,000 API calls per minute and a workspace 25,000, spread evenly over 10-second windows. Excess calls get `429 Too Many Requests` with `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. React to events rather than polling searches from fast timers.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [Intercom API reference](https://developers.intercom.com/docs/references/introduction)
* [Intercom OpenAPI descriptions](https://github.com/intercom/Intercom-OpenAPI)


# Jira Cloud (Software)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-cloud

Client-mode REST API connector for a curated Jira Cloud platform REST v3 slice: create issues from alarms, transitions, and enhanced JQL search

Technical Preview

## Overview

A client-mode connector for a **curated DevOps / OT** slice of the [Jira Cloud platform REST API v3](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/) under `https://YOUR_SITE.atlassian.net`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| | `GET /rest/api/3/myself` | Authenticated user |
| (discovery) | `GET /rest/api/3/project` | List projects |
| POST issue (from alarm) | `POST /rest/api/3/issue` | Requires `fields.project`, `fields.issuetype`, `fields.summary` |
| POST issue/\{key}/transitions | `POST /rest/api/3/issue/{issueIdOrKey}/transitions` | Requires `transition.id` |
| GET search?jql= | `GET /rest/api/3/search/jql` | **Enhanced** search — legacy `/rest/api/3/search` is removed (410) |

`BASE_ADDRESS` is `https://{site}.atlassian.net` (no trailing slash; endpoints already include `/rest/api/3/...`). Topics use `devops/jira-cloud/<object>/<verb>`.

> [!NOTE]
>
> Use **`/rest/api/3/search/jql`**, not `/rest/api/3/search`. Request `fields` explicitly (default returns IDs only). Paginate with `nextPageToken`. JQL must be bounded.

> [!NOTE]
>
> Catalog also mentions a server webhook for issue events. This package ships **client events only**. Register Atlassian webhooks via admin UI or Webhooks REST; inbound receive would need a separate `ENABLE_SERVER` connector.

> [!NOTE]
>
> Prefer Hub secrets for tokens and passwords.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Jira Cloud (Software) curated slice
# Auth: Bearer {value.json.access_token} (OAuth 3LO) or Basic email + API token via config
# BASE_ADDRESS: https://YOUR_SITE.atlassian.net

DEFINE CONNECTOR JiraCloudRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_SITE.atlassian.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getmyself
        WITH SOURCE_TOPIC "devops/jira-cloud/myself/get"
        WITH DESTINATION_TOPIC "devops/jira-cloud/myself/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/api/3/myself"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Listprojects
        WITH SOURCE_TOPIC "devops/jira-cloud/project/list"
        WITH DESTINATION_TOPIC "devops/jira-cloud/project/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/api/3/project"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createissue
        WITH SOURCE_TOPIC "devops/jira-cloud/issue/create"
        WITH DESTINATION_TOPIC "devops/jira-cloud/issue/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/api/3/issue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Transitionissue
        WITH SOURCE_TOPIC "devops/jira-cloud/issue/transition"
        WITH DESTINATION_TOPIC "devops/jira-cloud/issue/transition/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/api/3/issue/{value.json.issueIdOrKey}/transitions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Searchissuesjql
        WITH SOURCE_TOPIC "devops/jira-cloud/issue/search"
        WITH DESTINATION_TOPIC "devops/jira-cloud/issue/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/api/3/search/jql?jql={value.json.jql}&maxResults={value.json.maxResults}&fields={value.json.fields}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getmyself | GET | `/rest/api/3/myself` | `devops/jira-cloud/myself/get` | `devops/jira-cloud/myself/get/response` |
| Listprojects | GET | `/rest/api/3/project` | `devops/jira-cloud/project/list` | `devops/jira-cloud/project/list/response` |
| Createissue | POST | `/rest/api/3/issue` | `devops/jira-cloud/issue/create` | `devops/jira-cloud/issue/create/response` |
| Transitionissue | POST | `/rest/api/3/issue/{issueIdOrKey}/transitions` | `devops/jira-cloud/issue/transition` | `devops/jira-cloud/issue/transition/response` |
| Searchissuesjql | GET | `/rest/api/3/search/jql?jql=&maxResults=&fields=` | `devops/jira-cloud/issue/search` | `devops/jira-cloud/issue/search/response` |

## Auth

**OAuth 2.0 (3LO) Bearer — default in the template:**

1. Create an OAuth 2.0 (3LO) app in the Atlassian Developer Console with Jira scopes (classic `read:jira-work` / `write:jira-work` or equivalent granular scopes).
2. Obtain an `access_token`.
3. Set connector `BASE_ADDRESS` to `https://{site}.atlassian.net`.
4. Pass `access_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.access_token}`
5. Store the token in Hub secrets / `GET SECRET`. Never commit real credentials.

**Basic (email + API token):**

1. Create an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens) for the integration account.
2. Prefer `WITH USERNAME "you@example.com"` and `WITH PASSWORD GET SECRET "ATLASSIAN_API_TOKEN"` on `REST_API_CONFIG` (remove Bearer header lines if using config Basic).

## Example payloads

**Create issue from alarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "fields": {
    "project": { "key": "OPS" },
    "issuetype": { "name": "Bug" },
    "summary": "Line sensor fault — Zone A",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "Vibration above threshold at 2026-10-04T00:00:00Z" }
          ]
        }
      ]
    }
  }
}
```

**Transition issue:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "issueIdOrKey": "OPS-42",
  "transition": { "id": "31" }
}
```

**Search issues (enhanced JQL):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "jql": "project = OPS AND statusCategory != Done ORDER BY updated DESC",
  "maxResults": "50",
  "fields": "summary,status,assignee,updated"
}
```

## Deploy notes

* Deploy **`JiraCloudRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-cloud](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-cloud)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Jira Service Management](/latest/lot-language/routes/rest-api-apps/jira-service-management)


# Jira Service Management
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-service-management

Client-mode REST API connector for a curated Jira Service Management Cloud slice: customer requests from alarms, comments, status, and Assets CMDB object create

Technical Preview

## Overview

A client-mode connector for a **curated ITSM / OT** slice of the [Jira Service Management Cloud REST API](https://developer.atlassian.com/cloud/jira/service-desk/rest/intro/) under `https://YOUR_SITE.atlassian.net`, plus Assets object create on `https://api.atlassian.com`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| (discovery) | `GET /rest/servicedeskapi/servicedesk` | List service desks |
| POST request (create from alarm) | `POST /rest/servicedeskapi/request` | Requires `serviceDeskId`, `requestTypeId`, `requestFieldValues` |
| POST request/\{id}/comment | `POST /rest/servicedeskapi/request/{issueIdOrKey}/comment` | Public or internal comment |
| GET request/\{id}/status | `GET /rest/servicedeskapi/request/{issueIdOrKey}/status` | Status history (current first) |
| (Assets discovery) | `GET /rest/servicedeskapi/assets/workspace` | Workspace IDs on site host |
| Assets POST object/create | `POST /jsm/assets/workspace/{workspaceId}/v1/object/create` | **Host:** `https://api.atlassian.com` — switch `BASE_ADDRESS` |

`BASE_ADDRESS` for Service Desk is `https://{site}.atlassian.net` (no trailing slash; endpoints already include `/rest/servicedeskapi/...`). Topics use `itsm/jira-sm/<object>/<verb>`.

> [!NOTE]
>
> Assets object create is **not** under `/rest/servicedeskapi/`. Official Cloud path is `https://api.atlassian.com/jsm/assets/workspace/{workspaceId}/v1/object/create`. Discover `workspaceId` via `GET /rest/servicedeskapi/assets/workspace` on the site. Prefer `/jsm/assets/` over deprecated `/jsm/insight/`.

> [!NOTE]
>
> Prefer Hub secrets for tokens and passwords.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Jira Service Management (Service Desk + Assets curated slice)
# Auth: Bearer {value.json.access_token} (OAuth 3LO) or Basic email + API token via config
# BASE_ADDRESS: https://YOUR_SITE.atlassian.net
# Assets create: set BASE_ADDRESS to https://api.atlassian.com

DEFINE CONNECTOR JiraServiceManagementRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_SITE.atlassian.net"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listservicedesks
        WITH SOURCE_TOPIC "itsm/jira-sm/servicedesk/list"
        WITH DESTINATION_TOPIC "itsm/jira-sm/servicedesk/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/servicedeskapi/servicedesk"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createrequest
        WITH SOURCE_TOPIC "itsm/jira-sm/request/create"
        WITH DESTINATION_TOPIC "itsm/jira-sm/request/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/servicedeskapi/request"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Createrequestcomment
        WITH SOURCE_TOPIC "itsm/jira-sm/request/comment"
        WITH DESTINATION_TOPIC "itsm/jira-sm/request/comment/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/servicedeskapi/request/{value.json.issueIdOrKey}/comment"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getrequeststatus
        WITH SOURCE_TOPIC "itsm/jira-sm/request/status"
        WITH DESTINATION_TOPIC "itsm/jira-sm/request/status/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/servicedeskapi/request/{value.json.issueIdOrKey}/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getassetsworkspaces
        WITH SOURCE_TOPIC "itsm/jira-sm/assets/workspace"
        WITH DESTINATION_TOPIC "itsm/jira-sm/assets/workspace/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/servicedeskapi/assets/workspace"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createassetsobject
        WITH SOURCE_TOPIC "itsm/jira-sm/assets/object/create"
        WITH DESTINATION_TOPIC "itsm/jira-sm/assets/object/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jsm/assets/workspace/{value.json.workspaceId}/v1/object/create"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Listservicedesks | GET | `/rest/servicedeskapi/servicedesk` | `itsm/jira-sm/servicedesk/list` | `itsm/jira-sm/servicedesk/list/response` |
| Createrequest | POST | `/rest/servicedeskapi/request` | `itsm/jira-sm/request/create` | `itsm/jira-sm/request/create/response` |
| Createrequestcomment | POST | `/rest/servicedeskapi/request/{issueIdOrKey}/comment` | `itsm/jira-sm/request/comment` | `itsm/jira-sm/request/comment/response` |
| Getrequeststatus | GET | `/rest/servicedeskapi/request/{issueIdOrKey}/status` | `itsm/jira-sm/request/status` | `itsm/jira-sm/request/status/response` |
| Getassetsworkspaces | GET | `/rest/servicedeskapi/assets/workspace` | `itsm/jira-sm/assets/workspace` | `itsm/jira-sm/assets/workspace/response` |
| Createassetsobject | POST | `/jsm/assets/workspace/{workspaceId}/v1/object/create` | `itsm/jira-sm/assets/object/create` | `itsm/jira-sm/assets/object/create/response` |

## Auth

**OAuth 2.0 (3LO) Bearer — default in the template:**

1. Create an OAuth 2.0 (3LO) app in the Atlassian Developer Console with Service Desk / Assets scopes as needed.
2. Obtain an `access_token`.
3. Set connector `BASE_ADDRESS` to `https://{site}.atlassian.net`.
4. Pass `access_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.access_token}`
5. Store the token in Hub secrets / `GET SECRET`. Never commit real credentials.

**Basic (email + API token):**

1. Create an [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens) for the integration account.
2. Prefer `WITH USERNAME "you@example.com"` and `WITH PASSWORD GET SECRET "ATLASSIAN_API_TOKEN"` on `REST_API_CONFIG` (remove Bearer header lines if using config Basic).

## Example payloads

**Create customer request from alarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "serviceDeskId": "10",
  "requestTypeId": "25",
  "requestFieldValues": {
    "summary": "Line sensor fault — Zone A",
    "description": "Vibration above threshold at 2026-10-04T00:00:00Z"
  }
}
```

**Create comment:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "issueIdOrKey": "HELPDESK-1",
  "body": "Coreflux alarm update: vibration still elevated.",
  "public": true
}
```

**Get request status:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "issueIdOrKey": "HELPDESK-1"
}
```

**Create Assets object** (`BASE_ADDRESS` = `https://api.atlassian.com`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "workspaceId": "1060ba0e-178b-4e0e-g0h1-jedb02cccb5f",
  "objectTypeId": "250",
  "attributes": [
    {
      "objectTypeAttributeId": "2797",
      "objectAttributeValues": [{ "value": "PLC-Line-A" }]
    }
  ]
}
```

## Deploy notes

* Deploy **`JiraServiceManagementRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-service-management](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jira-service-management)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# JSONPlaceholder REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/jsonplaceholder

Client-mode REST API connector for the public JSONPlaceholder fake API (posts, users, todos)

Technical Preview

## Overview

[JSONPlaceholder](https://jsonplaceholder.typicode.com/) is a free fake REST API. Use it to exercise Coreflux `TYPE REST_API` client connectors against posts, comments, users, and todos with no API key.

> [!TIP]
>
> `GET /posts/1` and `GET /users/1` return HTTP 200. `POST /posts` returns HTTP 201 with a fake id. Nothing is stored.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — JSONPlaceholder
# Generated from OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

DEFINE CONNECTOR JsonplaceholderRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://jsonplaceholder.typicode.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Optional: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Listposts
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Listposts"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Listposts"
        WITH METHOD "GET"
        WITH ENDPOINT "/posts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createpost
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Createpost"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Createpost"
        WITH METHOD "POST"
        WITH ENDPOINT "/posts"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Getpost
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Getpost"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Getpost"
        WITH METHOD "GET"
        WITH ENDPOINT "/posts/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getpostcomments
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Getpostcomments"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Getpostcomments"
        WITH METHOD "GET"
        WITH ENDPOINT "/posts/{value.json.id}/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listusers
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Listusers"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Listusers"
        WITH METHOD "GET"
        WITH ENDPOINT "/users"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getuser
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Getuser"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Getuser"
        WITH METHOD "GET"
        WITH ENDPOINT "/users/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listtodos
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Listtodos"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Listtodos"
        WITH METHOD "GET"
        WITH ENDPOINT "/todos"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listcomments
        WITH SOURCE_TOPIC "integrations/jsonplaceholder/request/Listcomments"
        WITH DESTINATION_TOPIC "integrations/jsonplaceholder/response/Listcomments"
        WITH METHOD "GET"
        WITH ENDPOINT "/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Listposts | GET | `/posts` | `integrations/jsonplaceholder/request/Listposts` | `integrations/jsonplaceholder/response/Listposts` |
| Createpost | POST | `/posts` | `integrations/jsonplaceholder/request/Createpost` | `integrations/jsonplaceholder/response/Createpost` |
| Getpost | GET | `/posts/{value.json.id}` | `integrations/jsonplaceholder/request/Getpost` | `integrations/jsonplaceholder/response/Getpost` |
| Getpostcomments | GET | `/posts/{value.json.id}/comments` | `integrations/jsonplaceholder/request/Getpostcomments` | `integrations/jsonplaceholder/response/Getpostcomments` |
| Listusers | GET | `/users` | `integrations/jsonplaceholder/request/Listusers` | `integrations/jsonplaceholder/response/Listusers` |
| Getuser | GET | `/users/{value.json.id}` | `integrations/jsonplaceholder/request/Getuser` | `integrations/jsonplaceholder/response/Getuser` |
| Listtodos | GET | `/todos` | `integrations/jsonplaceholder/request/Listtodos` | `integrations/jsonplaceholder/response/Listtodos` |
| Listcomments | GET | `/comments` | `integrations/jsonplaceholder/request/Listcomments` | `integrations/jsonplaceholder/response/Listcomments` |

## Auth

No credentials. The template still includes `Authorization: Bearer {value.json.api_token}`. Omit the token for demos. If you retarget `BASE_ADDRESS` to a private clone, load the secret with `GET SECRET` upstream. Never commit tokens.

## Try it

1. Add the connector on your broker.
2. Publish `{"id": 1}` to `integrations/jsonplaceholder/request/Getpost`.
3. Subscribe to `integrations/jsonplaceholder/response/Getpost`.
4. Create: publish a JSON body such as `{"title":"coreflux","body":"demo","userId":1}` to `integrations/jsonplaceholder/request/Createpost` (the connector forwards `{payload}`).
5. Users: publish `{"id": 1}` to `integrations/jsonplaceholder/request/Getuser`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Kepware Config
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/kepware-config

LoT connector for the Kepware Server Configuration API: read about and status, list channels, devices and tags, create, update or delete tags, read event log

Technical Preview

## Overview

Client-mode REST API connectors for PTC Kepware Server (KEPServerEX, ThingWorx Kepware Server, Kepware Edge): read server about and health, list channels, devices, tag groups and tags, create, update and delete tags through the Configuration API, read the event log, and browse, read and write live tag values through the IoT Gateway REST server.

This is one of the templates in the Kepware (PTC KEPServerEX, ThingWorx Kepware Server, Kepware+) REST API app (`kepware`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Kepware Config connector | no |
| `BaseUrl` | string | Kepware Config base URL without trailing slash (e.g. http\://YOUR\_KEPWARE\_HOST:57412) | yes |

`BASE_ADDRESS` default: `http://YOUR_KEPWARE_HOST:57412`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetAbout` | GET | `/config/v1/about` | `historian/kepware/about/get` | `historian/kepware/about/get/response` | `authorization` |
| `GetStatus` | GET | `/config/v1/status` | `historian/kepware/status/get` | `historian/kepware/status/get/response` | `authorization` |
| `GetProject` | GET | `/config/v1/project` | `historian/kepware/project/get` | `historian/kepware/project/get/response` | `authorization` |
| `ListChannels` | GET | `/config/v1/project/channels` | `historian/kepware/channel/list` | `historian/kepware/channel/list/response` | `authorization` |
| `GetChannel` | GET | `/config/v1/project/channels/{value.json.channel}` | `historian/kepware/channel/get` | `historian/kepware/channel/get/response` | `authorization`, `channel` |
| `ListDevices` | GET | `/config/v1/project/channels/{value.json.channel}/devices` | `historian/kepware/device/list` | `historian/kepware/device/list/response` | `authorization`, `channel` |
| `GetDevice` | GET | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}` | `historian/kepware/device/get` | `historian/kepware/device/get/response` | `authorization`, `channel`, `device` |
| `ListTags` | GET | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags` | `historian/kepware/tag/list` | `historian/kepware/tag/list/response` | `authorization`, `channel`, `device` |
| `GetTag` | GET | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags/{value.json.tag}` | `historian/kepware/tag/get` | `historian/kepware/tag/get/response` | `authorization`, `channel`, `device`, `tag` |
| `CreateTags` | POST | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags` | `historian/kepware/tag/create` | `historian/kepware/tag/create/response` | `authorization`, `body`, `channel`, `device` |
| `UpdateTag` | PUT | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags/{value.json.tag}` | `historian/kepware/tag/update` | `historian/kepware/tag/update/response` | `authorization`, `body`, `channel`, `device`, `tag` |
| `DeleteTag` | DELETE | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags/{value.json.tag}` | `historian/kepware/tag/delete` | `historian/kepware/tag/delete/response` | `authorization`, `channel`, `device`, `tag` |
| `ListTagGroups` | GET | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tag_groups` | `historian/kepware/tag-group/list` | `historian/kepware/tag-group/list/response` | `authorization`, `channel`, `device` |
| `ListGroupTags` | GET | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tag_groups/{value.json.group}/tags` | `historian/kepware/group-tag/list` | `historian/kepware/group-tag/list/response` | `authorization`, `channel`, `device`, `group` |
| `CreateGroupTags` | POST | `/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tag_groups/{value.json.group}/tags` | `historian/kepware/group-tag/create` | `historian/kepware/group-tag/create/response` | `authorization`, `body`, `channel`, `device`, `group` |
| `GetEventLog` | GET | `/config/v1/event_log?{value.json.query}` | `historian/kepware/event-log/get` | `historian/kepware/event-log/get/response` | `authorization`, `query` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode KEPWARE_CONFIG"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR KepwareConfig WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_KEPWARE_HOST:57412"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetAbout
        WITH SOURCE_TOPIC "historian/kepware/about/get"
        WITH DESTINATION_TOPIC "historian/kepware/about/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/about"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetStatus
        WITH SOURCE_TOPIC "historian/kepware/status/get"
        WITH DESTINATION_TOPIC "historian/kepware/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetProject
        WITH SOURCE_TOPIC "historian/kepware/project/get"
        WITH DESTINATION_TOPIC "historian/kepware/project/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListChannels
        WITH SOURCE_TOPIC "historian/kepware/channel/list"
        WITH DESTINATION_TOPIC "historian/kepware/channel/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetChannel
        WITH SOURCE_TOPIC "historian/kepware/channel/get"
        WITH DESTINATION_TOPIC "historian/kepware/channel/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "historian/kepware/device/list"
        WITH DESTINATION_TOPIC "historian/kepware/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "historian/kepware/device/get"
        WITH DESTINATION_TOPIC "historian/kepware/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListTags
        WITH SOURCE_TOPIC "historian/kepware/tag/list"
        WITH DESTINATION_TOPIC "historian/kepware/tag/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetTag
        WITH SOURCE_TOPIC "historian/kepware/tag/get"
        WITH DESTINATION_TOPIC "historian/kepware/tag/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags/{value.json.tag}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateTags
        WITH SOURCE_TOPIC "historian/kepware/tag/create"
        WITH DESTINATION_TOPIC "historian/kepware/tag/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateTag
        WITH SOURCE_TOPIC "historian/kepware/tag/update"
        WITH DESTINATION_TOPIC "historian/kepware/tag/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags/{value.json.tag}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteTag
        WITH SOURCE_TOPIC "historian/kepware/tag/delete"
        WITH DESTINATION_TOPIC "historian/kepware/tag/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tags/{value.json.tag}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListTagGroups
        WITH SOURCE_TOPIC "historian/kepware/tag-group/list"
        WITH DESTINATION_TOPIC "historian/kepware/tag-group/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tag_groups"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListGroupTags
        WITH SOURCE_TOPIC "historian/kepware/group-tag/list"
        WITH DESTINATION_TOPIC "historian/kepware/group-tag/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tag_groups/{value.json.group}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateGroupTags
        WITH SOURCE_TOPIC "historian/kepware/group-tag/create"
        WITH DESTINATION_TOPIC "historian/kepware/group-tag/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/config/v1/project/channels/{value.json.channel}/devices/{value.json.device}/tag_groups/{value.json.group}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetEventLog
        WITH SOURCE_TOPIC "historian/kepware/event-log/get"
        WITH DESTINATION_TOPIC "historian/kepware/event-log/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/config/v1/event_log?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetAbout` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/kepware/about/get/response' &
mosquitto_pub -t 'historian/kepware/about/get' -m '{"authorization": "<authorization>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Kepware Iot Gateway
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/kepware-iot-gateway

Connect Coreflux LoT to the Kepware IoT Gateway REST server to browse tags, read one or many live tag values and write tag values from MQTT topics

Technical Preview

## Overview

Client-mode REST API connectors for PTC Kepware Server (KEPServerEX, ThingWorx Kepware Server, Kepware Edge): read server about and health, list channels, devices, tag groups and tags, create, update and delete tags through the Configuration API, read the event log, and browse, read and write live tag values through the IoT Gateway REST server.

This is one of the templates in the Kepware (PTC KEPServerEX, ThingWorx Kepware Server, Kepware+) REST API app (`kepware`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Kepware Iot Gateway connector | no |
| `BaseUrl` | string | Kepware Iot Gateway base URL without trailing slash (e.g. https\://YOUR\_KEPWARE\_HOST:39320) | yes |

`BASE_ADDRESS` default: `https://YOUR_KEPWARE_HOST:39320`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `IotgwBrowse` | GET | `/iotgateway/browse` | `historian/kepware/iotgw-tag/browse` | `historian/kepware/iotgw-tag/browse/response` | `authorization` |
| `IotgwRead` | GET | `/iotgateway/read?ids={value.json.ids}` | `historian/kepware/iotgw-value/get` | `historian/kepware/iotgw-value/get/response` | `authorization`, `ids` |
| `IotgwReadMany` | POST | `/iotgateway/read` | `historian/kepware/iotgw-value/read` | `historian/kepware/iotgw-value/read/response` | `authorization`, `body` |
| `IotgwWrite` | POST | `/iotgateway/write` | `historian/kepware/iotgw-value/write` | `historian/kepware/iotgw-value/write/response` | `authorization`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode KEPWARE_IOT_GATEWAY"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR KepwareIotGateway WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_KEPWARE_HOST:39320"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT IotgwBrowse
        WITH SOURCE_TOPIC "historian/kepware/iotgw-tag/browse"
        WITH DESTINATION_TOPIC "historian/kepware/iotgw-tag/browse/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/iotgateway/browse"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT IotgwRead
        WITH SOURCE_TOPIC "historian/kepware/iotgw-value/get"
        WITH DESTINATION_TOPIC "historian/kepware/iotgw-value/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/iotgateway/read?ids={value.json.ids}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT IotgwReadMany
        WITH SOURCE_TOPIC "historian/kepware/iotgw-value/read"
        WITH DESTINATION_TOPIC "historian/kepware/iotgw-value/read/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/iotgateway/read"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT IotgwWrite
        WITH SOURCE_TOPIC "historian/kepware/iotgw-value/write"
        WITH DESTINATION_TOPIC "historian/kepware/iotgw-value/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/iotgateway/write"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `IotgwBrowse` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/kepware/iotgw-tag/browse/response' &
mosquitto_pub -t 'historian/kepware/iotgw-tag/browse' -m '{"authorization": "<authorization>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Limble CMMS
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/limble-cmms

LoT connector for Limble CMMS API v2: create work orders from alarms, push meter values into asset fields, handle work requests, and receive Limble webhooks

Technical Preview

## Overview

[Limble CMMS](https://limblecmms.com/) is a cloud maintenance system for work orders, preventive maintenance (PMs), work requests, assets, parts and purchasing. This connector lets the broker open a work order when an alarm fires, feed run hours, cycle counts and sensor values into asset fields that drive meter-based and threshold PMs, and log machine events on the asset, so maintenance sees what the plant sees without manual entry.

The template has two connectors:

* **LimbleCmmsApi** (`LimbleCmmsRestApi.lot`), a client connector on `https://api.limblecmms.com` with 31 events: 13 writes and 18 reads. It has no `DELETE` events.
* **LimbleCmmsWebhookReceiver** (`cmms_limble-cmms_webhook.lot`), an optional server connector on port `9010` that receives Limble webhooks and publishes them on MQTT.

> [!NOTE]
>
> Limble serves a machine-readable OpenAPI 3.1 spec without authentication at `https://api.limblecmms.com/openapi.json`, and publishes the same reference as [Postman docs](https://apidocs.limblecmms.com/). The events were picked by hand from it (the API has more than 200 operations), and every method and path was checked against it.

## Events

| Event | Topic | Request | Kind | What it does |
| - | - | - | - | - |
| `GetMe` | `cmms/limble/me/get` | `GET /v2/me` | Read | Auth check: customerName and customerPlan of the account the API keys belong to |
| `ListLocations` | `cmms/limble/location/list` | `GET /v2/locations?{query}` | Read | Locations (plants, sites): locationID, name, regionID, timezone, weeklyOperationHours, workRequestPortal; filters locations, name, regions; limit / page |
| `ListUsers` | `cmms/limble/user/list` | `GET /v2/users?{query}` | Read | Users (assignees for tasks: userID, teams per location); filters users, name, roles, teams; cursor / limit |
| `ListTeams` | `cmms/limble/team/list` | `GET /v2/teams?{query}` | Read | Teams (assignmentType team): teamID, name, locationID |
| `ListStatuses` | `cmms/limble/status/list` | `GET /v2/statuses?{query}` | Read | Custom task statuses (statusID, name) for UpdateTask statusID and the ListTasks statusIDs filter |
| `ListPriorities` | `cmms/limble/priority/list` | `GET /v2/priorities?{query}` | Read | Priorities (priorityID, name, priorityLevel, isDefault); CreateTask priority must be one of the priorityLevel values |
| `ListAssets` | `cmms/limble/asset/list` | `GET /v2/assets?{query}` | Read | Assets: assetID, name, locationID, parentAssetID, hoursPerWeek, meta links to fields and tasks; filters assets, name, locations, parentAssetID, start / end (last edited, unix s); limit / page or orderBy / cursor |
| `UpdateAsset` | `cmms/limble/asset/update` | `PATCH /v2/assets/{id}` | Write | Update an asset's top level info: body `{name, hoursPerWeek (-1 = location default), parentAssetID, startedOn unix s, geoLocation}`. Empty 200 on success |
| `ListAssetFields` | `cmms/limble/asset-field/list` | `GET /v2/assets/fields?{query}` | Read | Asset field values (meters are Number fields): valueID, fieldID, assetID, field, value, fieldType; filters assets, fields, values, name, locations; find the valueID to write |
| `UpdateAssetFieldValue` | `cmms/limble/asset-field/update` | `PATCH /v2/assets/fields/{id}` | Write | Meter reading: write one asset field value by valueID (not assetID): body `{value}` typed like the field (number for Number). Adds a field history entry; unit-based and threshold PMs on that field can create tasks |
| `BatchUpdateAssetFields` | `cmms/limble/asset-field/batch-update` | `POST /v2/assets/fields/batch/update` | Write | Several meter values in one call: body array of 2-100 `{valueID, value}` (Text, Date, Number, Currency only); reply success false + updates\[] with reasons if any row fails. Batch limit 20 calls/hour |
| `AttachAssetField` | `cmms/limble/asset-field/attach` | `PUT /v2/assets/{id}/fields` | Write | Attach an existing (suggested) field, e.g. a run hours meter, to an asset: body `{locationID, fieldID}`; then write it with UpdateAssetFieldValue |
| `ListAssetFieldHistory` | `cmms/limble/asset-field-history/list` | `GET /v2/assets/fields/history?{query}` | Read | History of asset field values (meter trend): fieldID, value, valueID, dateUpdated; filters assets, fields, start / end |
| `ListAssetLogs` | `cmms/limble/asset-log/list` | `GET /v2/assets/{id}/logs?{query}` | Read | Log entries of one asset; filters logs, users, logEntry, start / end; limit / page |
| `CreateAssetLog` | `cmms/limble/asset-log/create` | `POST /v2/assets/{id}/logs` | Write | Manual asset log entry, e.g. a machine state change: body `{logEntry (required), userID?}`; 201 `{logID}` |
| `ListTasks` | `cmms/limble/task/list` | `GET /v2/tasks?{query}` | Read | Tasks: query status=0 (open) / 1 (complete), type 1 PM / 2 unplanned WO / 4 planned WO / 6 WR, statusIDs (custom), assets, locations, users, teams, meta1-3, tag, start / end, completedStart / completedEnd (unix s); limit / page or orderBy / cursor |
| `CreateTask` | `cmms/limble/task/create` | `POST /v2/tasks` | Write | Work order from an alarm: body `{name, locationID, due (unix s), type 1 / 2 / 4 / 6 required; assetID, description, priority (a priorityLevel), assignment + assignmentType user / team / multi, templateID, meta1-3, requestName ...}`; 201 `{taskID}` |
| `UpdateTask` | `cmms/limble/task/update` | `PATCH /v2/tasks/{id}` | Write | Update a task: body `{status 1 close / 0 reopen (close needs assignment + assignmentType), statusID (custom, not 1 / 2), priority 0-6, due, name, description, asset, meta1-3 ...}`. Empty 200 on success |
| `ListTaskComments` | `cmms/limble/task-comment/list` | `GET /v2/tasks/{id}/comments?{query}` | Read | Comments of one task (commentID, comment, timestamp, userID) |
| `AddTaskComment` | `cmms/limble/task-comment/create` | `POST /v2/tasks/{id}/comments` | Write | Add a comment with live context: body `{comment (required), showExternalUsers (default true)}` |
| `ListTaskInstructions` | `cmms/limble/task-instruction/list` | `GET /v2/tasks/{id}/instructions?{query}` | Read | Checklist instructions of one task (instructionID, instruction, type, response) |
| `ListTaskLabor` | `cmms/limble/task-labor/list` | `GET /v2/tasks/labor?{query}` | Read | Labor entries (timeSpent seconds, userID, dateLogged); filters tasks, users, locations, start / end |
| `ListWorkRequestSubmissions` | `cmms/limble/work-request/list` | `GET /v2/work-requests/work-request-submissions?{query}` | Read | Work request submissions (workRequestSubmissionId, status Pending / Approved / Rejected); filters locationIDs, statuses (CSV), workRequestIDs, createdDateStart / End, search, orderBy |
| `CreateWorkRequestSubmission` | `cmms/limble/work-request/create` | `POST /v2/work-requests/work-request-submissions` | Write | Raise a work request for review instead of a direct task: body `{locationID, dueDateUnit days / hours required; assetID, priorityID, requesterName, requestTitle, requestDescription, parts, timeUnix}` |
| `ApproveWorkRequestSubmission` | `cmms/limble/work-request/approve` | `POST /v2/work-requests/work-request-submissions/{id}/approve` | Write | Approve a pending submission; Limble generates a task from it (body `{}`) |
| `DeclineWorkRequestSubmission` | `cmms/limble/work-request/decline` | `POST /v2/work-requests/work-request-submissions/{id}/decline` | Write | Decline a pending submission: body `{declineReason?, additionalNotes?}` |
| `ListParts` | `cmms/limble/part/list` | `GET /v2/parts?{query}` | Read | Spare parts and stock (partID, number, name, generalStock, minQtyStatus, minQtyThreshold); filters parts, locations, name, numbers |
| `ListPartsUsage` | `cmms/limble/part-usage/list` | `GET /v2/parts/usage?{query}` | Read | Parts used on tasks (partID, taskID, usedCount, usedPrice, usedOn); filters parts, tasks, start / end |
| `ListWebhooks` | `cmms/limble/webhook/list` | `GET /v2/webhooks?{query}` | Read | Registered webhooks (webhookID, endpoint, type, enabled 0 / 1); filters webhooks, endpoint, type, enabled |
| `CreateWebhook` | `cmms/limble/webhook/create` | `POST /v2/webhooks` | Write | Register a webhook: body `{endpoint (required), type (required) asset / assetField / location / part / po / poItem / task / instruction, enabled 1 / 0}`; 201 `{webhookID}`. One type per webhook; receive with LimbleCmmsWebhookReceiver |
| `UpdateWebhook` | `cmms/limble/webhook/update` | `PATCH /v2/webhooks/{id}` | Write | Update a webhook, e.g. body `{enabled: 1}` to re-enable one Limble disabled after failed retries; also endpoint, type |

Replies arrive on the same topic with `/response` appended.

## Prerequisites

* A Limble account and API keys. A **Super Administrator** creates them under **Settings > Configuration > API Settings > Generate API Keys**. The client secret is shown only once.
* The API host of your account's region. The connector uses the default host; for other regions change `BASE_ADDRESS`:

| Limble account | API host |
| - | - |
| Default | `https://api.limblecmms.com` |
| Canada | `https://ca-api.limblecmms.com` |
| Australia | `https://au-api.limblecmms.com` |
| Europe | `https://eu-api.limblecmms.com` |
| 21 CFR Part 11 | `https://21cfr-api.limblecmms.com` |

* Outbound HTTPS from the broker to that host.
* For webhooks only: a public HTTPS URL that forwards to the broker's port `9010`.

## Authentication

> [!WARNING]
>
> The API keys act for the whole Limble account. Store `base64("<client id>:<client secret>")` in the Hub secret `LIMBLE_BASIC_AUTH`, read it with `GET SECRET`, and never put the keys or their base64 in a connector file or a retained topic.

Limble uses **HTTP Basic** authentication with the API Client ID and Client Secret. Every event sends `Authorization: Basic {value.json.basic_auth}`, so each payload carries the base64 string in `basic_auth`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_auth": "<base64 of client_id:client_secret (Hub secret LIMBLE_BASIC_AUTH)>"
}
```

`GetMe` (`GET /v2/me`) returns `customerName` and `customerPlan`. Use it to check the keys.

Answers seen from the real API without valid keys: no `Authorization` header returns `401` `{"error":401,"success":false,"msg":"No Credentials Provided"}`; wrong keys return `403` `{"error":403,"success":false,"msg":"Invalid credentials."}`.

## Payload conventions

* `basic_auth`: base64 of `client_id:client_secret`.
* `id`: the numeric Limble ID in the path: `taskID`, `assetID`, `valueID` (an asset field value, not the asset), `webhookID` or `workRequestSubmissionID`.
* `query`: the whole query string for list events, already URL-encoded, or `""` for none. For example `status=0&type=2,4&locations=205&limit=100&page=1` for open work orders.
* `body`: the JSON request body, sent unchanged on `POST`, `PATCH` and `PUT` events.

All dates are **Unix time in seconds**. Lists come back as JSON arrays. Creates answer `201` with the new ID (for example `{"taskID": 8261}`); `PATCH` and `PUT` answer an empty `200`.

Task types are `1` PM, `2` unplanned work order, `4` planned work order and `6` work request. The `status` filter on `ListTasks` is `0` (incomplete) or `1` (complete); custom statuses such as "In Progress" filter with `statusIDs`.

Create a work order from an alarm (`priority` must be one of the `priorityLevel` values from `ListPriorities`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_auth": "<base64 of client_id:client_secret (Hub secret LIMBLE_BASIC_AUTH)>",
  "body": {
    "name": "Line 1 compressor over-temperature",
    "locationID": "<location id>",
    "type": 2,
    "due": 1791381600,
    "assetID": "<asset id>",
    "description": "Alarm TT-101 = 92.4 C at 2026-10-06T06:15:00Z (Coreflux)",
    "priority": 3,
    "meta1": "TT-101"
  }
}
```

Close it (closing needs `assignment` and `assignmentType`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_auth": "<base64 of client_id:client_secret (Hub secret LIMBLE_BASIC_AUTH)>",
  "id": "<task id>",
  "body": {
    "status": 1,
    "assignment": "<user id>",
    "assignmentType": "user"
  }
}
```

## Meter readings

Limble keeps meters as **asset fields** (Number fields such as "Hours Ran"). PMs set to "Every X number of units" or to a threshold on that field create tasks when a new value arrives. To push a reading:

1. Find the field's `valueID` with `ListAssetFields` (`query`: `assets=<assetID>`). If the asset does not have the field yet, attach it with `AttachAssetField`.
2. Write the value with `UpdateAssetFieldValue`, using the `valueID` as `id`. The value must match the field type (a number for a Number field). Each write adds an entry to the field history (`ListAssetFieldHistory`).

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_auth": "<base64 of client_id:client_secret (Hub secret LIMBLE_BASIC_AUTH)>",
  "id": "<asset field valueID>",
  "body": {
    "value": 1287.5
  }
}
```

To write 2 to 100 values in one call, use `BatchUpdateAssetFields` (Text, Date, Number and Currency fields only, 20 calls per hour). It returns `{"success": false, "updates": [...]}` with a reason per row if any row fails, so check the body as well as the HTTP status.

## Webhook receiver

Deploy `cmms_limble-cmms_webhook.lot` only if you want Limble to push changes to the broker. It opens HTTP port `9010`.

| Event | Request | Published on | What it receives |
| - | - | - | - |
| `WebhookTasks` | `POST /limble/webhook/tasks` | `cmms/limble/webhook-task/received` | Task webhooks (type task: CREATED, COMPLETE, CHANGED DUE DATE, CHANGED ASSIGNMENT, ADDED COMMENT TO TASK, ...): body `{taskID, status, category, user}` |
| `WebhookAssets` | `POST /limble/webhook/assets` | `cmms/limble/webhook-asset/received` | Asset and asset field webhooks (types asset, assetField): body `{assetID / valueID, status, category, user}` |
| `WebhookParts` | `POST /limble/webhook/parts` | `cmms/limble/webhook-part/received` | Part webhooks (type part: CREATED, QUANTITY INCREASED, QUANTITY DECREASED, PRICE UPDATED, ...): body `{partID, status, category, user}` |
| `WebhookEvents` | `POST /limble/webhook/events` | `cmms/limble/webhook-event/received` | Any other Limble webhook (types location, po, poItem, instruction). Filter on body.category in a LoT action |

Each webhook in Limble has one type (`asset`, `assetField`, `location`, `part`, `po`, `poItem`, `task` or `instruction`). Register one per type with `CreateWebhook` (or in **Settings > Configuration > API Settings**), using the public URL of the matching path:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_auth": "<base64 of client_id:client_secret (Hub secret LIMBLE_BASIC_AUTH)>",
  "body": {
    "endpoint": "https://<public host>/limble/webhook/tasks",
    "type": "task",
    "enabled": 1
  }
}
```

Limble posts a short JSON body such as `{"taskID": 8203, "status": "COMPLETE", "category": "task", "user": "..."}`. Read the full object back with `ListTasks` (`query`: `tasks=8203`) or the matching list event. Limble needs at least one active API key for webhooks to work. Your endpoint must answer within 10 seconds; Limble retries after 10 minutes, 1, 2 and 4 hours and then disables the webhook. Send `UpdateWebhook` with `{"enabled": 1}` to turn it back on.

> [!WARNING]
>
> Limble signs each delivery with `signature`, `timestamp` and `token` headers: `signature` is HMAC-SHA256 of `timestamp + token`, keyed with the hex SHA-256 of the account's **oldest** API key. The receiver connector does not check the signature and does not authenticate callers. Put a reverse proxy with a public TLS certificate in front of port `9010` and verify the signature there, or at least use a hard-to-guess path.

## Connector

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Limble CMMS API v2 (beta): create work orders (tasks) from alarms, find open tasks by
#   completed status / type / custom status, close tasks and add comments, raise / approve / decline work requests,
#   push meter readings into asset fields (single or batch; unit-based and threshold PMs fire from them), log asset
#   events, read assets, field history, locations, parts, users, teams, statuses and priorities, and register webhooks
#   (received by the companion route in cmms_limble-cmms_webhook.lot).
#   served without auth) and the public Postman docs https://apidocs.limblecmms.com (cached in
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/limble-cmms
#
# Host: Limble cloud, default region https://api.limblecmms.com (endpoints carry /v2). Limble documents one API host
#   per account region / type. To use another one, fork and change BASE_ADDRESS:
#     Canada https://ca-api.limblecmms.com | Australia https://au-api.limblecmms.com |
#     Europe https://eu-api.limblecmms.com | 21 CFR Part 11 https://21cfr-api.limblecmms.com
#   Keys only work on the host of the account's region.
# Auth: HTTP Basic with the account's API Client ID and Client Secret (Settings > Configuration > API Settings >
#   Generate API Keys, as a Super Administrator; the secret is shown once). Every event sends
#   Authorization: Basic {value.json.basic_auth}, where basic_auth is base64("<client id>:<client secret>"). Keep that
#   string in the Hub secret LIMBLE_BASIC_AUTH and read it with GET SECRET. The keys act for the whole account.
#   Live (2026-10-06): no Authorization -> 401 {"error":401,"success":false,"msg":"No Credentials Provided"}; wrong keys
#   -> 403 {"error":403,"success":false,"msg":"Invalid credentials."}. Auth runs before routing, for every path.
# Payload fields (control fields stay out of bodies; request bodies come from {value.json.body}):
#   basic_auth, id, query, body
#   id is the numeric Limble ID in the path: taskID, assetID, valueID (asset field value, NOT the asset), webhookID or
#   workRequestSubmissionID. query is the whole pre-encoded query string, "" for none, for example
#   status=0&type=2,4&locations=<id>&limit=100&page=1 (tasks: status 0 = incomplete, 1 = complete; type 1 PM,
#   2 unplanned WO, 4 planned WO, 6 work request). All dates are Unix time in SECONDS.
#     CreateTask             body = {"name": "...", "locationID": 205, "type": 2, "due": 1791381600, "assetID": 10836, "priority": 3}
#     UpdateTask             id = <taskID>, body = {"status": 1, "assignment": 341, "assignmentType": "user"}   (close)
#     UpdateAssetFieldValue  id = <valueID>, body = {"value": 1287.5}   (meter reading; type must match the field)
#     BatchUpdateAssetFields body = [{"valueID": 46456, "value": "1287.5"}, {"valueID": 46457, "value": "71.8"}]   (2-100 rows)
#     CreateWebhook          body = {"endpoint": "https://<public host>/limble/webhook/tasks", "type": "task", "enabled": 1}
# Replies: lists are JSON arrays; POST creates answer 201 with the new ID ({"taskID": 8261}) and a Location header;
#   PATCH / PUT answer an empty 200. Errors: 400 validation, 401 / 403 auth, 404 unknown ID, 409 conflict, 422 limit
#   above the endpoint maximum, 429 rate limit (GET 4000/h, PATCH 2000/h, POST and PUT 1000/h, batch 20/h).
#

DEFINE CONNECTOR LimbleCmmsApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.limblecmms.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Auth check: customerName and customerPlan of the account the API keys belong to
    ADD EVENT GetMe
        WITH SOURCE_TOPIC "cmms/limble/me/get"
        WITH DESTINATION_TOPIC "cmms/limble/me/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Locations (plants, sites): locationID, name, regionID, timezone, weeklyOperationHours, workRequestPortal; filters locations, name, regions; limit / page
    ADD EVENT ListLocations
        WITH SOURCE_TOPIC "cmms/limble/location/list"
        WITH DESTINATION_TOPIC "cmms/limble/location/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/locations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Users (assignees for tasks: userID, teams per location); filters users, name, roles, teams; cursor / limit
    ADD EVENT ListUsers
        WITH SOURCE_TOPIC "cmms/limble/user/list"
        WITH DESTINATION_TOPIC "cmms/limble/user/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Teams (assignmentType team): teamID, name, locationID
    ADD EVENT ListTeams
        WITH SOURCE_TOPIC "cmms/limble/team/list"
        WITH DESTINATION_TOPIC "cmms/limble/team/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/teams?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Custom task statuses (statusID, name) for UpdateTask statusID and the ListTasks statusIDs filter
    ADD EVENT ListStatuses
        WITH SOURCE_TOPIC "cmms/limble/status/list"
        WITH DESTINATION_TOPIC "cmms/limble/status/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/statuses?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Priorities (priorityID, name, priorityLevel, isDefault); CreateTask priority must be one of the priorityLevel values
    ADD EVENT ListPriorities
        WITH SOURCE_TOPIC "cmms/limble/priority/list"
        WITH DESTINATION_TOPIC "cmms/limble/priority/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/priorities?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Assets: assetID, name, locationID, parentAssetID, hoursPerWeek, meta links to fields and tasks; filters assets, name, locations, parentAssetID, start / end (last edited, unix s); limit / page or orderBy / cursor
    ADD EVENT ListAssets
        WITH SOURCE_TOPIC "cmms/limble/asset/list"
        WITH DESTINATION_TOPIC "cmms/limble/asset/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/assets?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # WRITE: Update an asset's top level info: body {name, hoursPerWeek (-1 = location default), parentAssetID, startedOn unix s, geoLocation}. Empty 200 on success
    ADD EVENT UpdateAsset
        WITH SOURCE_TOPIC "cmms/limble/asset/update"
        WITH DESTINATION_TOPIC "cmms/limble/asset/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/assets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Asset field values (meters are Number fields): valueID, fieldID, assetID, field, value, fieldType; filters assets, fields, values, name, locations; find the valueID to write
    ADD EVENT ListAssetFields
        WITH SOURCE_TOPIC "cmms/limble/asset-field/list"
        WITH DESTINATION_TOPIC "cmms/limble/asset-field/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/assets/fields?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # WRITE: Meter reading: write one asset field value by valueID (not assetID): body {value} typed like the field (number for Number). Adds a field history entry; unit-based and threshold PMs on that field can create tasks
    ADD EVENT UpdateAssetFieldValue
        WITH SOURCE_TOPIC "cmms/limble/asset-field/update"
        WITH DESTINATION_TOPIC "cmms/limble/asset-field/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/assets/fields/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Several meter values in one call: body array of 2-100 {valueID, value} (Text, Date, Number, Currency only); reply success false + updates[] with reasons if any row fails. Batch limit 20 calls/hour
    ADD EVENT BatchUpdateAssetFields
        WITH SOURCE_TOPIC "cmms/limble/asset-field/batch-update"
        WITH DESTINATION_TOPIC "cmms/limble/asset-field/batch-update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/assets/fields/batch/update"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Attach an existing (suggested) field, e.g. a run hours meter, to an asset: body {locationID, fieldID}; then write it with UpdateAssetFieldValue
    ADD EVENT AttachAssetField
        WITH SOURCE_TOPIC "cmms/limble/asset-field/attach"
        WITH DESTINATION_TOPIC "cmms/limble/asset-field/attach/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/assets/{value.json.id}/fields"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # History of asset field values (meter trend): fieldID, value, valueID, dateUpdated; filters assets, fields, start / end
    ADD EVENT ListAssetFieldHistory
        WITH SOURCE_TOPIC "cmms/limble/asset-field-history/list"
        WITH DESTINATION_TOPIC "cmms/limble/asset-field-history/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/assets/fields/history?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Log entries of one asset; filters logs, users, logEntry, start / end; limit / page
    ADD EVENT ListAssetLogs
        WITH SOURCE_TOPIC "cmms/limble/asset-log/list"
        WITH DESTINATION_TOPIC "cmms/limble/asset-log/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/assets/{value.json.id}/logs?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # WRITE: Manual asset log entry, e.g. a machine state change: body {logEntry (required), userID?}; 201 {logID}
    ADD EVENT CreateAssetLog
        WITH SOURCE_TOPIC "cmms/limble/asset-log/create"
        WITH DESTINATION_TOPIC "cmms/limble/asset-log/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/assets/{value.json.id}/logs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Tasks: query status=0 (open) | 1 (complete), type 1 PM | 2 unplanned WO | 4 planned WO | 6 WR, statusIDs (custom), assets, locations, users, teams, meta1-3, tag, start / end, completedStart / completedEnd (unix s); limit / page or orderBy / cursor
    ADD EVENT ListTasks
        WITH SOURCE_TOPIC "cmms/limble/task/list"
        WITH DESTINATION_TOPIC "cmms/limble/task/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/tasks?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # WRITE: Work order from an alarm: body {name, locationID, due (unix s), type 1 | 2 | 4 | 6 required; assetID, description, priority (a priorityLevel), assignment + assignmentType user | team | multi, templateID, meta1-3, requestName ...}; 201 {taskID}
    ADD EVENT CreateTask
        WITH SOURCE_TOPIC "cmms/limble/task/create"
        WITH DESTINATION_TOPIC "cmms/limble/task/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/tasks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Update a task: body {status 1 close | 0 reopen (close needs assignment + assignmentType), statusID (custom, not 1 / 2), priority 0-6, due, name, description, asset, meta1-3 ...}. Empty 200 on success
    ADD EVENT UpdateTask
        WITH SOURCE_TOPIC "cmms/limble/task/update"
        WITH DESTINATION_TOPIC "cmms/limble/task/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/tasks/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Comments of one task (commentID, comment, timestamp, userID)
    ADD EVENT ListTaskComments
        WITH SOURCE_TOPIC "cmms/limble/task-comment/list"
        WITH DESTINATION_TOPIC "cmms/limble/task-comment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/tasks/{value.json.id}/comments?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # WRITE: Add a comment with live context: body {comment (required), showExternalUsers (default true)}
    ADD EVENT AddTaskComment
        WITH SOURCE_TOPIC "cmms/limble/task-comment/create"
        WITH DESTINATION_TOPIC "cmms/limble/task-comment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/tasks/{value.json.id}/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Checklist instructions of one task (instructionID, instruction, type, response)
    ADD EVENT ListTaskInstructions
        WITH SOURCE_TOPIC "cmms/limble/task-instruction/list"
        WITH DESTINATION_TOPIC "cmms/limble/task-instruction/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/tasks/{value.json.id}/instructions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Labor entries (timeSpent seconds, userID, dateLogged); filters tasks, users, locations, start / end
    ADD EVENT ListTaskLabor
        WITH SOURCE_TOPIC "cmms/limble/task-labor/list"
        WITH DESTINATION_TOPIC "cmms/limble/task-labor/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/tasks/labor?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Work request submissions (workRequestSubmissionId, status Pending | Approved | Rejected); filters locationIDs, statuses (CSV), workRequestIDs, createdDateStart / End, search, orderBy
    ADD EVENT ListWorkRequestSubmissions
        WITH SOURCE_TOPIC "cmms/limble/work-request/list"
        WITH DESTINATION_TOPIC "cmms/limble/work-request/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/work-requests/work-request-submissions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # WRITE: Raise a work request for review instead of a direct task: body {locationID, dueDateUnit days | hours required; assetID, priorityID, requesterName, requestTitle, requestDescription, parts, timeUnix}
    ADD EVENT CreateWorkRequestSubmission
        WITH SOURCE_TOPIC "cmms/limble/work-request/create"
        WITH DESTINATION_TOPIC "cmms/limble/work-request/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/work-requests/work-request-submissions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Approve a pending submission; Limble generates a task from it (body {})
    ADD EVENT ApproveWorkRequestSubmission
        WITH SOURCE_TOPIC "cmms/limble/work-request/approve"
        WITH DESTINATION_TOPIC "cmms/limble/work-request/approve/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/work-requests/work-request-submissions/{value.json.id}/approve"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Decline a pending submission: body {declineReason?, additionalNotes?}
    ADD EVENT DeclineWorkRequestSubmission
        WITH SOURCE_TOPIC "cmms/limble/work-request/decline"
        WITH DESTINATION_TOPIC "cmms/limble/work-request/decline/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/work-requests/work-request-submissions/{value.json.id}/decline"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Spare parts and stock (partID, number, name, generalStock, minQtyStatus, minQtyThreshold); filters parts, locations, name, numbers
    ADD EVENT ListParts
        WITH SOURCE_TOPIC "cmms/limble/part/list"
        WITH DESTINATION_TOPIC "cmms/limble/part/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/parts?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Parts used on tasks (partID, taskID, usedCount, usedPrice, usedOn); filters parts, tasks, start / end
    ADD EVENT ListPartsUsage
        WITH SOURCE_TOPIC "cmms/limble/part-usage/list"
        WITH DESTINATION_TOPIC "cmms/limble/part-usage/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/parts/usage?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # Registered webhooks (webhookID, endpoint, type, enabled 0 | 1); filters webhooks, endpoint, type, enabled
    ADD EVENT ListWebhooks
        WITH SOURCE_TOPIC "cmms/limble/webhook/list"
        WITH DESTINATION_TOPIC "cmms/limble/webhook/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/webhooks?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
    # WRITE: Register a webhook: body {endpoint (required), type (required) asset | assetField | location | part | po | poItem | task | instruction, enabled 1 | 0}; 201 {webhookID}. One type per webhook; receive with LimbleCmmsWebhookReceiver
    ADD EVENT CreateWebhook
        WITH SOURCE_TOPIC "cmms/limble/webhook/create"
        WITH DESTINATION_TOPIC "cmms/limble/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Update a webhook, e.g. body {enabled: 1} to re-enable one Limble disabled after failed retries; also endpoint, type
    ADD EVENT UpdateWebhook
        WITH SOURCE_TOPIC "cmms/limble/webhook/update"
        WITH DESTINATION_TOPIC "cmms/limble/webhook/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v2/webhooks/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Webhook receiver (optional):

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Limble CMMS webhook receiver — REST_API route (server mode, beta, companion of LimbleCmmsRestApi.lot)
#   Receives Limble webhooks (Settings > Configuration > API Settings, or CreateWebhook) and publishes the JSON body on
#   MQTT, so task, asset, asset field and part changes reach the broker without polling. Opt-in: deploying it opens an
#   HTTP port.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/limble-cmms
#
# Limble needs a public URL. Put a reverse proxy or tunnel with a public TLS certificate in front of SERVER_PORT.
#   Limble posts a small JSON body {<object>ID, status, category, user} (for example {"taskID": 8203, "status":
#   "COMPLETE", "category": "task", "user": "..."}); read the full object back with ListTasks / ListAssets /
#   ListAssetFields / ListParts. Limble signs every delivery with signature, timestamp and token headers:
#   signature = HMAC-SHA256(key = hex SHA-256 of the account's OLDEST Limble API key, message = timestamp + token).
#   This route does not verify that signature or authenticate callers: verify it in the proxy, or use a hard-to-guess
#   path segment. Answer within 10 s; Limble retries after 10 min, 1 h, 2 h and 4 h, then disables the webhook
#   (re-enable with UpdateWebhook {"enabled": 1}). Webhooks need at least one active Limble API key on the account.
#   One webhook has one type: register task -> /tasks, asset and assetField -> /assets, part -> /parts,
#   location / po / poItem / instruction -> /events.

DEFINE CONNECTOR LimbleCmmsWebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9010'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Task webhooks (type task: CREATED, COMPLETE, CHANGED DUE DATE, CHANGED ASSIGNMENT, ADDED COMMENT TO TASK, ...): body {taskID, status, category, user}
    ADD EVENT WebhookTasks
        WITH ENDPOINT "/limble/webhook/tasks"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/limble/webhook-task/received"
    # Asset and asset field webhooks (types asset, assetField): body {assetID | valueID, status, category, user}
    ADD EVENT WebhookAssets
        WITH ENDPOINT "/limble/webhook/assets"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/limble/webhook-asset/received"
    # Part webhooks (type part: CREATED, QUANTITY INCREASED, QUANTITY DECREASED, PRICE UPDATED, ...): body {partID, status, category, user}
    ADD EVENT WebhookParts
        WITH ENDPOINT "/limble/webhook/parts"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/limble/webhook-part/received"
    # Any other Limble webhook (types location, po, poItem, instruction). Filter on body.category in a LoT action
    ADD EVENT WebhookEvents
        WITH ENDPOINT "/limble/webhook/events"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/limble/webhook-event/received"
```

## Example actions

These actions check the keys every hour, open a work order when a compressor alarm is raised, push run hours into a meter field, log machine state changes on the asset, and poll open work orders.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the LimbleCmmsApi route (docs page). Not part of the route template.
# Secret: LIMBLE_BASIC_AUTH = base64("<client id>:<client secret>") from Limble Settings > Configuration > API Settings.
#   IDs (location, asset, asset field valueID, user) come from location/list, asset/list and asset-field/list;
#   replace the <...> placeholders below with the numeric IDs.

DEFINE ACTION LimbleAuthCheck
ON EVERY 1 HOUR DO
    SET "auth" WITH GET SECRET "LIMBLE_BASIC_AUTH"
    PUBLISH TOPIC "cmms/limble/me/get" WITH { "basic_auth": {auth} }

DEFINE ACTION LimbleWorkOrderFromAlarm
ON TOPIC "porto/line1/compressor/alarm/raised" DO
    SET "auth" WITH GET SECRET "LIMBLE_BASIC_AUTH"
    SET "alarm" WITH (GET JSON "alarm" IN PAYLOAD AS STRING)
    SET "value" WITH (GET JSON "value" IN PAYLOAD AS STRING)
    SET "now" WITH TIMESTAMP "UNIX"
    SET "due" WITH ({now} + 86400)
    SET "name" WITH "Line 1 compressor alarm " + {alarm}
    SET "desc" WITH "Coreflux alarm " + {alarm} + " (value " + {value} + ")"
    PUBLISH TOPIC "cmms/limble/task/create" WITH { "basic_auth": {auth}, "body": { "name": {name}, "description": {desc}, "locationID": "<location id>", "assetID": "<asset id>", "type": 2, "due": {due}, "priority": 3, "meta1": {alarm} } }

DEFINE ACTION LimbleRunHoursMeter
ON TOPIC "porto/line1/press01/run-hours" DO
    SET "auth" WITH GET SECRET "LIMBLE_BASIC_AUTH"
    SET "hours" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "cmms/limble/asset-field/update" WITH { "basic_auth": {auth}, "id": "<run hours valueID>", "body": { "value": {hours} } }

DEFINE ACTION LimbleAssetLogFromMachineState
ON TOPIC "porto/line1/press01/state" DO
    SET "auth" WITH GET SECRET "LIMBLE_BASIC_AUTH"
    SET "state" WITH PAYLOAD AS STRING
    SET "entry" WITH "Press 01 state " + {state} + " (Coreflux)"
    PUBLISH TOPIC "cmms/limble/asset-log/create" WITH { "basic_auth": {auth}, "id": "<asset id>", "body": { "logEntry": {entry} } }

DEFINE ACTION LimblePollOpenWorkOrders
ON EVERY 15 MINUTES DO
    SET "auth" WITH GET SECRET "LIMBLE_BASIC_AUTH"
    PUBLISH TOPIC "cmms/limble/task/list" WITH { "basic_auth": {auth}, "query": "status=0&type=2,4&locations=<location id>&limit=100&page=1" }
```

## Notes

* The catalog hint `PATCH assets/{id}/fields` does not exist in the Limble API. Meter values are written per field value with `PATCH /v2/assets/fields/{valueID}`; `PUT /v2/assets/{assetID}/fields` only attaches a field to an asset.
* `UpdateTask` cannot set `statusID` to `1` (Open) or `2` (Complete); use `status` `0` / `1` for that. Its `priority` accepts `0` to `6` (`6` is "On Hold").
* Limble's reference also lists `name`, `locationID`, `due`, `type` and `templateID` as query parameters of `POST /v2/tasks`. Its description and example send them in a JSON body, which is what the connector does.
* Pagination uses `limit` + `page` (the reply has `Next-Page` / `Last-Page` headers) or `orderBy` + `cursor`, never both. A `limit` above the endpoint maximum returns `422`. Limble plans to deprecate cursor paging on tasks and assets.
* Rate limits per account: GET 4000 per hour (360 per minute), PATCH 2000 per hour, POST and PUT 1000 per hour, batch requests 20 per hour. Every reply carries `X-RateLimit-*` headers; over the limit you get `429`. Poll lists every few minutes, not per message.
* `api.limblecmms.com` sits behind Cloudflare, which rejects some client signatures (the Python `urllib` default user agent gets `403 error code: 1010`). Requests with no user agent, or a normal one, pass.
* Writes start Limble's own follow-ups: assignment notifications, meter and threshold PMs, workflow automations and webhooks.
* Errors come back on the response topic as `{"error": <code>, "success": false, "msg": "..."}`: `400` validation, `401` / `403` auth, `404` unknown ID, `409` conflict, `422` limit too high, `429` rate limit.

## Not covered

Deletes, images and files, creating assets, locations, parts, vendors, users, roles and teams, task instructions and invoices, purchase orders, bills, budgets and general ledgers, suggested field definitions and dropdown options, regions, tags, units of measure, and user capacity. All are in the Limble API and can be added to a fork.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Limble API v2 reference](https://apidocs.limblecmms.com/)
* [Limble OpenAPI spec](https://api.limblecmms.com/openapi.json)
* [Limble: linking readings to assets](https://help.limblecmms.com/en/articles/2971834-linking-readings-to-assets)
* [Limble: PM scheduling options](https://help.limblecmms.com/en/articles/6989116-pm-scheduling-options)


# Litmus Edge
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/litmus-edge

Connect Coreflux LoT to Litmus Edge: get OAuth2 tokens, list DeviceHub devices and tags, create, update or delete tags, and start or stop devices and flows

Technical Preview

## Overview

Litmus Edge is an industrial edge data platform: it connects PLCs and other devices through DeviceHub, stores tag data locally, runs Node-RED flows and analytics, and forwards data through integrations. The **LitmusEdge** connector lets a Coreflux broker manage and query an edge over its REST and GraphQL API (`https://<edge>/...`, the same address as the web UI).

Each event publishes the edge's reply on `<topic>/response`.

| Event | Topic | Request | Notes |
| - | - | - | - |
| GetAccessToken | `historian/litmus-edge/auth-token/create` | `POST /auth/v3/oauth/token` | OAuth2 client credentials; returns access\_token and expires\_in |
| GetDeviceHubVersion | `historian/litmus-edge/devicehub-version/get` | `GET /devicehub/version` | DeviceHub version and git revision (liveness probe) |
| GetDeviceManagementVersion | `historian/litmus-edge/dm-version/get` | `GET /dm/version` | Device Management service version |
| ListDevices | `historian/litmus-edge/device/list` | `POST /devicehub/v2` (query ListDevices) | Every DeviceHub device (ID, Name, DriverID, params) |
| StartDevices | `historian/litmus-edge/device/start` | `POST /devicehub/v2` (mutation StartDevices) | Start polling one or more devices (idempotent) |
| StopDevices | `historian/litmus-edge/device/stop` | `POST /devicehub/v2` (mutation StopDevices) | Stop polling one or more devices |
| SetDeviceDataStorage | `historian/litmus-edge/device-storage/update` | `PUT /stats/devices/{device_id}` | Enable or disable persistence of a device's tags (body ID, name, retentionHours, saveAll) |
| ListAllTags | `historian/litmus-edge/tag/list` | `POST /devicehub/v2` (query ListRegistersFromAllDevices) | Tags across all devices (Limit / SkipCount / TagPattern) |
| ListDeviceTags | `historian/litmus-edge/device-tag/list` | `POST /devicehub/v2` (query ListRegisters) | Tags of one device (DeviceID, Limit / SkipCount) |
| CreateTags | `historian/litmus-edge/tag/create` | `POST /devicehub/v2` (mutation CreateRegisters) | Create one or more tags on a device |
| UpdateTags | `historian/litmus-edge/tag/update` | `POST /devicehub/v2` (mutation UpdateRegisters) | Replace tag configuration by ID |
| DeleteTags | `historian/litmus-edge/tag/delete` | `POST /devicehub/v2` (mutation DeleteRegisters) | Delete tags by ID (unknown IDs are ignored) |
| GetTsdbInfo | `historian/litmus-edge/tsdb/get` | `GET /stats/tsdb` | Time-series DB state (is\_enabled) and source |
| ListFlows | `historian/litmus-edge/flow/list` | `GET /flows-manager/flows` | Node-RED flow instances (id, name, tabs) |
| StartFlow | `historian/litmus-edge/flow/start` | `PUT /flows-manager/flows/{flow_id}/start` | Start a flow instance (204) |
| StopFlow | `historian/litmus-edge/flow/stop` | `PUT /flows-manager/flows/{flow_id}/stop` | Stop a flow instance (204) |
| ListIntegrations | `historian/litmus-edge/integration/list` | `GET /cc/instances` | Integration (cloud / MQTT / Kafka ...) instances |

DeviceHub is GraphQL: every DeviceHub event posts to `/devicehub/v2`, and you send the GraphQL document in the payload as `body` (`{"query": "...", "variables": {...}}`). The event name tells you which query or mutation it is meant for.

> [!NOTE]
>
> **Live tag values and tag writes are not REST in Litmus Edge.** Litmus documents tag writes only on the edge's NATS bus (`devicehub.write.<device>.<tag>`), and live values stream on `devicehub.alias.<device>.<tag>`. To move live data between Litmus Edge and Coreflux, use a Litmus Edge MQTT integration pointed at this broker. Use this connector for configuration and control.

## Prerequisites

1. Litmus Edge 4.0.x, reachable from the broker host on HTTPS (port 443 on an appliance or VM; a Docker install usually publishes it on host port 8443).
2. An OAuth2 client (client ID and secret) or a REST API token from **System** > **Access Control** > **Tokens**, with permission for DeviceHub, DataHub and Flows Manager.
3. The edge certificate is self-signed by default. Install the edge CA on the broker host (download it from **System** > **Network** > **Certificates**), or replace it with a trusted certificate.
4. Store the credentials in Hub secrets, for example `LITMUS_CLIENT_ID` and `LITMUS_CLIENT_SECRET`, or `LITMUS_API_TOKEN`.

## Authentication

Every event except `GetAccessToken` takes the full `Authorization` header value in the payload as `authorization`:

* **OAuth2 client credentials:** publish `{"client_id": "...", "client_secret": "..."}` to `historian/litmus-edge/auth-token/create`. The reply holds `access_token` and `expires_in`. Send `"authorization": "Bearer <access_token>"`.
* **REST API token:** send `"authorization": "Basic <base64 of token:>"` (the token is the username, the password is empty).

> [!WARNING]
>
> Token lifetime depends on the edge. Litmus reports `expires_in` values as short as 300 seconds, so refresh the token on a timer shorter than `expires_in` (the example below refreshes every 4 minutes).

## Configuration

Replace `YOUR_LITMUS_EDGE_HOST` in `BASE_ADDRESS` with the edge address, for example `https://10.0.0.20` or `https://10.0.0.20:8443` for Docker.

## Examples

List devices:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/litmus-edge/device/list
{ "authorization": "Bearer <token>", "body": { "query": "query ListDevices { ListDevices { ID Name DriverID } }" } }
// historian/litmus-edge/device/list/response
{ "data": { "ListDevices": [{ "ID": "41FBD12E-...", "Name": "Line1 PLC", "DriverID": "2AF1FA08-..." }] } }
```

List the tags of one device:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/litmus-edge/device-tag/list
{ "authorization": "Bearer <token>",
  "body": { "query": "query ListRegisters($input: ListRegistersRequest!) { ListRegisters(input: $input) { Registers { ID TagName ValueType } TotalCount Last } }",
            "variables": { "input": { "DeviceID": "<device uuid>", "Limit": 100, "SkipCount": 0 } } } }
```

Create a tag:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/litmus-edge/tag/create
{ "authorization": "Bearer <token>",
  "body": { "query": "mutation CreateRegisters($input: CreateRegistersRequest!) { CreateRegisters(input: $input) { ID TagName } }",
            "variables": { "input": { "Registers": [{ "DeviceID": "<device uuid>", "Name": "40001", "TagName": "Line1Temperature", "ValueType": "float64",
                                                  "Properties": [{ "Key": "pollingInterval", "Value": "1000" }] }] } } } }
```

Stop and start a device:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/litmus-edge/device/stop (or device/start with StartDevices)
{ "authorization": "Bearer <token>",
  "body": { "query": "mutation StopDevices($input: StopDevicesRequest!) { StopDevices(input: $input) }",
            "variables": { "input": { "IDs": ["<device uuid>"] } } } }
```

Restart a Node-RED flow instance:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/litmus-edge/flow/start
{ "authorization": "Bearer <token>", "flow_id": 1 }
// reply: HTTP 204, empty body
```

Register properties (`Name`, `Properties` keys) depend on the device's driver; Litmus lists them per driver in its DeviceHub register reference.

### Example actions

Keep GraphQL documents in a retained topic (for example `config/litmus-edge/list-devices` holding `{"query": "query ListDevices { ListDevices { ID Name DriverID } }"}`) and read them with `GET TOPIC`, so the GraphQL text never sits inside a LoT JSON literal.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION LitmusRefreshToken
ON EVERY 4 MINUTES DO
    SET "cid" WITH GET SECRET "LITMUS_CLIENT_ID"
    SET "csecret" WITH GET SECRET "LITMUS_CLIENT_SECRET"
    PUBLISH TOPIC "historian/litmus-edge/auth-token/create" WITH { "client_id": {cid}, "client_secret": {csecret} }

DEFINE ACTION LitmusKeepToken
ON TOPIC "historian/litmus-edge/auth-token/create/response" DO
    SET "token" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "internal/litmus-edge/authorization" WITH "Bearer " + {token}

DEFINE ACTION LitmusListDevices
ON EVERY 1 HOUR DO
    SET "auth" WITH GET TOPIC "internal/litmus-edge/authorization"
    SET "gql" WITH GET TOPIC "config/litmus-edge/list-devices"
    PUBLISH TOPIC "historian/litmus-edge/device/list" WITH { "authorization": {auth}, "body": {gql} }

DEFINE ACTION LitmusHealthCheck
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET TOPIC "internal/litmus-edge/authorization"
    PUBLISH TOPIC "historian/litmus-edge/devicehub-version/get" WITH { "authorization": {auth} }

DEFINE ACTION LitmusRestartFlowOnAlarm
ON TOPIC "plant/line1/flow-restart" DO
    SET "auth" WITH GET TOPIC "internal/litmus-edge/authorization"
    SET "flow" WITH PAYLOAD AS INT
    PUBLISH TOPIC "historian/litmus-edge/flow/start" WITH { "authorization": {auth}, "flow_id": {flow} }
```

## Responses and errors

| Case | Answer |
| - | - |
| Wrong client ID or secret on `GetAccessToken` | `401` |
| Missing, wrong or expired token on REST endpoints | `401` |
| GraphQL errors (bad input, unknown device, no permission) | HTTP `200` with an `errors` array; check `errors[].extensions.code` (`UNAUTHENTICATED`, `FORBIDDEN`, `BAD_USER_INPUT`, `NOT_FOUND`) |
| `StartFlow`, `StopFlow` | `204`, empty body |
| `DeleteTags` with unknown IDs | Ignored, no error |

Always check the `errors` key in DeviceHub responses, not only the HTTP status.

## Not covered

* Tag value writes and live values (NATS bus only, see the note above). Use a Litmus Edge MQTT integration.
* DeviceHub subscriptions (`RegisterStatus`, `DeviceConnectionStatus`), which need a GraphQL websocket.
* Browse, asset discovery, digital twins, analytics, applications, OPC UA server, system administration (network, backups, certificates, RBAC) and Litmus Edge Manager (LEM) fleet APIs.
* Litmus Edge 3.16.x endpoints.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app catalog](/latest/lot-language/routes/rest-api-apps/index)
* [Litmus Edge API reference](https://api.litmus.io/le/)
* [Litmus API portal: your first API call](https://docs.litmus.io/api-docs/first-api-call)


# Looker
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/looker

LoT connector for the Looker API 4.0: run queries and Looks onto MQTT, trigger scheduled plans when a shift closes, render dashboards and expire datagroups

Technical Preview

## Overview

A client-mode connector for the [Looker API 4.0](https://docs.cloud.google.com/looker/docs/reference/looker-api/latest). Use it to put Looker results on MQTT, such as OEE per line, scrap by shift or open maintenance orders for an andon board or HMI, and to let plant events drive Looker: run a scheduled plan once when a shift or batch closes, render a dashboard to PDF, or expire a datagroup cache after new data lands in the warehouse.

The connector `LookerRestApi` in `LookerRestApi.lot` has 44 events (30 GET, 11 POST, 2 PATCH, 1 PUT). Five are writes: `ScheduledPlanRunOnceById`, `ScheduledPlanRunOnce`, `ScheduledPlanCreate`, `ScheduledPlanUpdate` and `DatagroupUpdate`. There are no DELETE events.

Set `BASE_ADDRESS` to your Looker URL with no trailing slash and no `/api`, for example `https://acme.cloud.looker.com` or a Looker (Google Cloud core) instance URL ending in `looker.app`. Every endpoint already starts with `/api/4.0`. Some older self-hosted instances serve the API on port 19999 (`https://acme.looker.com:19999`). Topics use `analytics/looker/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** a Looker admin creates an API key (client ID and client secret) on a user in **Admin > Users > Edit Keys**. The `Login` event posts `client_id` and `client_secret` as a form to `/api/4.0/login` and gets back an `access_token` that lasts about an hour. Every other event except `Versions` sends `Authorization: token <access_token>` (the word `token` is required). The token acts as that user, so give the API user a role with only the models and permissions the broker needs. Keep `LOOKER_CLIENT_ID`, `LOOKER_CLIENT_SECRET` and the current token in broker secrets, read them with `GET SECRET` in the action that builds the payload, never retain topics that carry them, and restrict `analytics/looker/auth/#` with ACLs.

## Events

| Event | Request | Source topic | Notes |
| - | - | - | - |
| Versions | `GET /api/4.0/versions` | `analytics/looker/versions/get` | No authentication: API versions, Looker release and web\_server\_url. Payload: any JSON, for example an empty object. |
| Login | `POST /api/4.0/login` | `analytics/looker/auth/login` | Get an API access token (expires\_in about 3600 s). |
| Me | `GET /api/4.0/user?{value.json.query}` | `analytics/looker/user/me` | The API user behind the token. |
| Session | `GET /api/4.0/session` | `analytics/looker/session/get` | Current API session (workspace\_id: production or dev). |
| QueryRunInline | `POST /api/4.0/queries/run/{value.json.result_format}?{value.json.query}` | `analytics/looker/queries/run_inline` | Run an inline query and publish the result (catalog event). result\_format json, json\_detail, json\_bi, csv, txt, md, sql. |
| QueryCreate | `POST /api/4.0/queries?{value.json.query}` | `analytics/looker/queries/create` | Create an immutable query object (returns id and slug; reuse with QueryRun). |
| QueryGet | `GET /api/4.0/queries/{value.json.query_id}?{value.json.query}` | `analytics/looker/queries/get` | A saved query definition. |
| QueryRun | `GET /api/4.0/queries/{value.json.query_id}/run/{value.json.result_format}?{value.json.query}` | `analytics/looker/queries/run` | Run a saved query by id. result\_format json, csv, ... |
| QueryTaskCreate | `POST /api/4.0/query_tasks?{value.json.query}` | `analytics/looker/query_tasks/create` | Start an async query (long queries). |
| QueryTaskGet | `GET /api/4.0/query_tasks/{value.json.query_task_id}` | `analytics/looker/query_tasks/get` | Async query task status. |
| QueryTaskResults | `GET /api/4.0/query_tasks/multi_results?query_task_ids={value.json.query_task_ids}` | `analytics/looker/query_tasks/results` | Results of one or more async query tasks. query\_task\_ids: comma-separated ids. |
| RunningQueriesList | `GET /api/4.0/running_queries` | `analytics/looker/running_queries/list` | Queries running now (admin / see\_queries). |
| LooksSearch | `GET /api/4.0/looks/search?{value.json.query}` | `analytics/looker/looks/search` | Search Looks (saved reports). |
| LookGet | `GET /api/4.0/looks/{value.json.look_id}?{value.json.query}` | `analytics/looker/looks/get` | A Look with its query. |
| LookRun | `GET /api/4.0/looks/{value.json.look_id}/run/{value.json.result_format}?{value.json.query}` | `analytics/looker/looks/run` | Run a Look and publish its rows (catalog event). result\_format json, csv, txt, ... |
| DashboardsSearch | `GET /api/4.0/dashboards/search?{value.json.query}` | `analytics/looker/dashboards/search` | Search dashboards. |
| DashboardGet | `GET /api/4.0/dashboards/{value.json.dashboard_id}?{value.json.query}` | `analytics/looker/dashboards/get` | A dashboard (tiles, filters). |
| DashboardElements | `GET /api/4.0/dashboards/{value.json.dashboard_id}/dashboard_elements?{value.json.query}` | `analytics/looker/dashboards/elements` | Dashboard tiles with their query ids (run them with QueryRun). |
| ScheduledPlansList | `GET /api/4.0/scheduled_plans?{value.json.query}` | `analytics/looker/scheduled_plans/list` | Scheduled plans. |
| ScheduledPlanGet | `GET /api/4.0/scheduled_plans/{value.json.scheduled_plan_id}?{value.json.query}` | `analytics/looker/scheduled_plans/get` | One scheduled plan. |
| ScheduledPlansForLook | `GET /api/4.0/scheduled_plans/look/{value.json.look_id}?{value.json.query}` | `analytics/looker/scheduled_plans/for_look` | Scheduled plans of a Look. |
| ScheduledPlansForDashboard | `GET /api/4.0/scheduled_plans/dashboard/{value.json.dashboard_id}?{value.json.query}` | `analytics/looker/scheduled_plans/for_dashboard` | Scheduled plans of a dashboard. |
| ScheduledPlanRunOnceById | `POST /api/4.0/scheduled_plans/{value.json.scheduled_plan_id}/run_once` | `analytics/looker/scheduled_plans/run_once_by_id` | Write, sends deliveries. Run an existing schedule now, e.g. when a shift closes (catalog event). |
| ScheduledPlanRunOnce | `POST /api/4.0/scheduled_plans/run_once` | `analytics/looker/scheduled_plans/run_once` | Write, sends deliveries. Run an ad-hoc schedule now without saving it. |
| ScheduledPlanCreate | `POST /api/4.0/scheduled_plans` | `analytics/looker/scheduled_plans/create` | Write. Create a schedule. |
| ScheduledPlanUpdate | `PATCH /api/4.0/scheduled_plans/{value.json.scheduled_plan_id}` | `analytics/looker/scheduled_plans/update` | Write. Change or pause a schedule (no delete event: set enabled false). |
| LookmlModelsList | `GET /api/4.0/lookml_models?{value.json.query}` | `analytics/looker/models/list` | LookML models and their explores. |
| LookmlModelGet | `GET /api/4.0/lookml_models/{value.json.lookml_model_name}?{value.json.query}` | `analytics/looker/models/get` | One LookML model. |
| ExploreGet | `GET /api/4.0/lookml_models/{value.json.lookml_model_name}/explores/{value.json.explore_name}?{value.json.query}` | `analytics/looker/models/explore` | An explore with its dimensions and measures (field names for inline queries). |
| SqlQueryCreate | `POST /api/4.0/sql_queries` | `analytics/looker/sql_queries/create` | Create a SQL Runner query (returns slug). |
| SqlQueryRun | `POST /api/4.0/sql_queries/{value.json.slug}/run/{value.json.result_format}` | `analytics/looker/sql_queries/run` | Run a SQL Runner query by slug. result\_format json, json\_detail, csv, txt. |
| LookRenderTaskCreate | `POST /api/4.0/render_tasks/looks/{value.json.look_id}/{value.json.result_format}?width={value.json.width}&height={value.json.height}` | `analytics/looker/render_tasks/look` | Start rendering a Look as png or jpg (width / height in px). Poll RenderTaskGet, then RenderTaskResults. |
| DashboardRenderTaskCreate | `POST /api/4.0/render_tasks/dashboards/{value.json.dashboard_id}/{value.json.result_format}?width={value.json.width}&height={value.json.height}` | `analytics/looker/render_tasks/dashboard` | Start rendering a dashboard as pdf, png or jpg. |
| RenderTaskGet | `GET /api/4.0/render_tasks/{value.json.render_task_id}` | `analytics/looker/render_tasks/get` | Render task status (success when done). |
| RenderTaskResults | `GET /api/4.0/render_tasks/{value.json.render_task_id}/results` | `analytics/looker/render_tasks/results` | Rendered file (binary pdf / png / jpg). The broker publishes the body as received. |
| FoldersSearch | `GET /api/4.0/folders/search?{value.json.query}` | `analytics/looker/folders/search` | Search folders. |
| FolderLooks | `GET /api/4.0/folders/{value.json.folder_id}/looks?{value.json.query}` | `analytics/looker/folders/looks` | Looks in a folder. |
| FolderDashboards | `GET /api/4.0/folders/{value.json.folder_id}/dashboards?{value.json.query}` | `analytics/looker/folders/dashboards` | Dashboards in a folder. |
| AlertsSearch | `GET /api/4.0/alerts/search?{value.json.query}` | `analytics/looker/alerts/search` | Search alerts (threshold conditions on dashboard tiles). |
| AlertGet | `GET /api/4.0/alerts/{value.json.alert_id}` | `analytics/looker/alerts/get` | One alert (comparison\_type, threshold, destinations). |
| DatagroupsList | `GET /api/4.0/datagroups` | `analytics/looker/datagroups/list` | Datagroups (cache and PDT trigger state). |
| DatagroupUpdate | `PATCH /api/4.0/datagroups/{value.json.datagroup_id}` | `analytics/looker/datagroups/update` | Write. Expire the cache of a datagroup after new plant data lands, e.g. |
| ConnectionsList | `GET /api/4.0/connections?{value.json.query}` | `analytics/looker/connections/list` | Database connections. |
| ConnectionTest | `PUT /api/4.0/connections/{value.json.connection_name}/test?{value.json.query}` | `analytics/looker/connections/test` | Test a database connection (no change). |

Payload fields are JSON on the source topic: ids (`query_id`, `look_id`, `dashboard_id`, `scheduled_plan_id`, `query_task_id`, `render_task_id`, `folder_id`, `alert_id`, `datagroup_id`, `connection_name`, `lookml_model_name`, `explore_name`, `slug`), `result_format` (`json`, `json_detail`, `csv`, `txt`, `md`, `sql`, or `png` / `jpg` / `pdf` for renders), `query` (a URL query string without `?`, or `""`), `width` and `height` for renders, `body` (a JSON object) for POST and PATCH events, and `form` for `Login`.

## Basic Syntax

An excerpt of the template (the full file has all 44 events and comments):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LookerRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_LOOKER_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Versions
        WITH SOURCE_TOPIC "analytics/looker/versions/get"
        WITH DESTINATION_TOPIC "analytics/looker/versions/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/4.0/versions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT Login
        WITH SOURCE_TOPIC "analytics/looker/auth/login"
        WITH DESTINATION_TOPIC "analytics/looker/auth/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/4.0/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    ADD EVENT QueryRunInline
        WITH SOURCE_TOPIC "analytics/looker/queries/run_inline"
        WITH DESTINATION_TOPIC "analytics/looker/queries/run_inline/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/4.0/queries/run/{value.json.result_format}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "token {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT LookRun
        WITH SOURCE_TOPIC "analytics/looker/looks/run"
        WITH DESTINATION_TOPIC "analytics/looker/looks/run/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/4.0/looks/{value.json.look_id}/run/{value.json.result_format}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "token {value.json.access_token}"
    ADD EVENT ScheduledPlanRunOnceById
        WITH SOURCE_TOPIC "analytics/looker/scheduled_plans/run_once_by_id"
        WITH DESTINATION_TOPIC "analytics/looker/scheduled_plans/run_once_by_id/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/4.0/scheduled_plans/{value.json.scheduled_plan_id}/run_once"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "token {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

Log in and keep the token in a secret-backed action (the response carries `access_token`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"form": "client_id=<LOOKER_CLIENT_ID>&client_secret=<LOOKER_CLIENT_SECRET>"}
```

Publish to `analytics/looker/auth/login`. Then run an inline query and get the rows as JSON on `analytics/looker/queries/run_inline/response`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "result_format": "json", "query": "limit=100&apply_formatting=false&cache=true", "body": {"model": "plant_ops", "view": "oee", "fields": ["oee.line", "oee.availability", "oee.performance"], "filters": {"oee.date": "today"}, "sorts": ["oee.line"], "limit": "100", "query_timezone": "Europe/Lisbon"}}
```

Run a saved Look on `analytics/looker/looks/run`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "look_id": "42", "result_format": "json", "query": "limit=100&apply_formatting=true"}
```

Send a shift report now from an existing schedule on `analytics/looker/scheduled_plans/run_once_by_id` (this delivers email or other destinations):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "scheduled_plan_id": "15", "body": {"scheduled_plan_destination": [{"type": "email", "format": "csv", "address": "shift-lead@example.com"}]}}
```

Expire a datagroup cache after a batch of plant data lands, on `analytics/looker/datagroups/update`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "datagroup_id": "11", "body": {"stale_before": 1791190800}}
```

Render a dashboard: publish to `analytics/looker/render_tasks/dashboard`, poll `analytics/looker/render_tasks/get` until `status` is `success`, then read the file from `analytics/looker/render_tasks/results/response`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "dashboard_id": "7", "result_format": "pdf", "width": "1280", "height": "1600", "body": {"dashboard_style": "tiled", "dashboard_filters": "Line=Line 2"}}
```

## Notes

* Long queries: use `QueryTaskCreate` and poll `QueryTaskResults` instead of waiting on `QueryRunInline`; `RunningQueriesList` shows what is running.
* Field names for inline queries come from `ExploreGet` (dimensions and measures of an explore). Dashboard tiles carry a `query_id` (`DashboardElements`) that `QueryRun` can run directly.
* `SqlQueryCreate` and `SqlQueryRun` need the `use_sql_runner` permission. `RenderTaskResults` returns a binary file, published as received.
* Not packaged on purpose: every DELETE (Looks, dashboards, schedules, alerts, logout, killing queries; pause a schedule with `ScheduledPlanUpdate` and `{"enabled": false}` instead), user and content administration, LookML project and git operations, and embed SSO. A scheduled plan with a webhook destination can POST to a separate server-mode connector.
* Requests are limited per instance; keep polling intervals coarse and prefer `cache=true`.


# Losant
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/losant

Client-mode REST API connector for a curated Losant slice: list devices and report device state

Technical Preview

# Losant

Client-mode REST API connector for a curated Losant slice: list devices and report device state.

* Hub category: **Cloud IoT**.
* Base: `https://api.losant.com`

## Template reference

Generated from the shipped broker template `losant` (`-connectorCode LOSANT`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Losant connector | no |
| `BaseUrl` | string | Losant base URL without trailing slash (e.g. [https://api.losant.com](https://api.losant.com)) | yes |

`BASE_ADDRESS` default: `https://api.losant.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listdevices` | GET | `/applications/{value.json.application_id}/devices` | `iot/losant/devices/list` | `iot/losant/devices/list/response` | `api_token`, `application_id` |
| `Reportdevicestate` | POST | `/applications/{value.json.application_id}/devices/{value.json.device_id}/state` | `iot/losant/devices/state` | `iot/losant/devices/state/response` | `api_token`, `application_id`, `body`, `device_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode LOSANT"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LosantRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.losant.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listdevices
        WITH SOURCE_TOPIC "iot/losant/devices/list"
        WITH DESTINATION_TOPIC "iot/losant/devices/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/applications/{value.json.application_id}/devices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Reportdevicestate
        WITH SOURCE_TOPIC "iot/losant/devices/state"
        WITH DESTINATION_TOPIC "iot/losant/devices/state/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/applications/{value.json.application_id}/devices/{value.json.device_id}/state"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listdevices` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'iot/losant/devices/list/response' &
mosquitto_pub -t 'iot/losant/devices/list' -m '{"api_token": "<api_token>", "application_id": "<application_id>"}'
```


# MachineMetrics
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/machinemetrics

Connect Coreflux LoT to MachineMetrics: read machine state, alarms and downtime over GraphQL, pull OEE and quality reports, and manage breaks and holidays

Technical Preview

## Overview

One client-mode connector, **MachineMetrics**, for the MachineMetrics cloud APIs at `https://api.machinemetrics.com`. MachineMetrics collects data from CNC and other shop-floor machines and turns it into machine state, alarms, downtime, part counts and OEE. This connector brings that data into your Unified Namespace and keeps planned breaks and holidays in sync.

The API has two parts:

* **GraphQL** (`POST /graphql`, read-only): live machine data such as current execution state, active alarms, open downtime annotations, part counts and any other object in the published schema.
* **REST**: production and quality report rollups (OEE, good and rejected parts, cycle time, downtime) with optional CSV download, scheduled time per machine, and the work schedule events API for breaks and holidays.

| Event | Request | Notes |
| - | - | - |
| GraphqlQuery | `POST /graphql` | Any GraphQL query; body `{"query": "...", "variables": {...}}` |
| MachinesCurrentState | `POST /graphql` | Topic preset for a `machines { currentStates }` query |
| MachinesCurrentAlarms | `POST /graphql` | Topic preset for a `machines { currentAlarms }` query |
| MachinesActiveDowntime | `POST /graphql` | Topic preset for machines with an open downtime annotation |
| CreateProductionReport | `POST /reports/production` | Metric rollups (OEE, parts, downtime, ...) for a day range, grouped by machine, shift, operator, ... |
| CreateQualityReport | `POST /reports/quality` | Reject count rollups for a time range |
| GetCsvToken | `GET /user-token` | Short-lived JWT for the CSV downloads |
| GetProductionCsv | `GET /csv/production/{resource_id}?{query}` | CSV of a production report run with `"csv": true`; `query` = `token=<jwt>` |
| GetQualityCsv | `GET /csv/quality/{resource_id}?{query}` | CSV of a quality report; `query` = `token=<jwt>` |
| GetMachineScheduledTime | `GET /machines/{machine_ref}/scheduled-time?{query}` | Scheduled time in a window; `startAt` and `endAt` required |
| ListWorkScheduleEvents | `GET /work-schedules/events?{query}` | Break and holiday definitions |
| GetWorkScheduleEvent | `GET /work-schedules/events/{event_ref}?{query}` | One definition |
| CreateWorkScheduleEvent | `POST /work-schedules/events` | New break, holiday or custom holiday |
| UpdateWorkScheduleEvent | `PUT /work-schedules/events/{event_ref}` | Partial update |
| ArchiveWorkScheduleEvent | `DELETE /work-schedules/events/{event_ref}` | Soft delete; also archives its assignments |
| BulkCreateWorkScheduleEventAssignments | `POST /work-schedules/events/{event_ref}/assignments` | Apply one event to many work schedules |
| ListWorkScheduleEventAssignments | `GET /work-schedules/{work_schedule_ref}/events?{query}` | Assignments on one work schedule |
| GetWorkScheduleEventAssignment | `GET /work-schedules/{work_schedule_ref}/events/{assignment_ref}?{query}` | One assignment |
| CreateWorkScheduleEventAssignment | `POST /work-schedules/{work_schedule_ref}/events` | Assign an event with recurrence rules |
| UpdateWorkScheduleEventAssignment | `PUT /work-schedules/{work_schedule_ref}/events/{assignment_ref}` | Change recurrence |
| ArchiveWorkScheduleEventAssignment | `DELETE /work-schedules/{work_schedule_ref}/events/{assignment_ref}` | Soft delete |
| CreateWorkScheduleEventInstances | `POST /work-schedules/{work_schedule_ref}/event-instances` | One-off instances, for one machine or all machines on the schedule |
| ListMachinesEventInstances | `GET /work-schedules/event-instances/machines?{query}` | Instances for many machines; window up to 31 days |
| ListMachineEventInstances | `GET /work-schedules/event-instances/machines/{machine_ref}?{query}` | Instances for one machine |

Topics are `mes/machinemetrics/<object>/<verb>`; every reply goes to `<topic>/response`.

The three `Machines...` events send the same request as `GraphqlQuery`. They exist so state, alarms and downtime replies land on their own topics; the query you put in `body` decides what comes back.

## Authentication

Every event except the two CSV downloads sends `Authorization: Bearer {api_token}`. Create the key in MachineMetrics under **Settings → API Keys** (`https://app.machinemetrics.com/app/settings/api-keys`). A key belongs to the company it was created in and is shown only once.

Choose the scopes when you create the key:

| Scope | Needed for |
| - | - |
| `reporting` | All GraphQL queries, the production and quality reports, work schedule reads |
| `user` | Work schedule writes (create, update, archive) |

Use a separate key for each integration and give it only the scopes it needs. Keep it in a broker secret (suggested `MACHINEMETRICS_API_TOKEN`) and map it in with `GET SECRET`. A missing or wrong key returns `401` with `AuthenticationError`, and a key without the scope returns `403`.

The CSV downloads authenticate differently: call `GetCsvToken` for a JWT, then pass it as `token=<jwt>` in `query`.

## Basic Syntax

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MachineMetrics WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.machinemetrics.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT MachinesCurrentState
        WITH SOURCE_TOPIC "mes/machinemetrics/machine-state/get"
        WITH DESTINATION_TOPIC "mes/machinemetrics/machine-state/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateProductionReport
        WITH SOURCE_TOPIC "mes/machinemetrics/production-report/create"
        WITH DESTINATION_TOPIC "mes/machinemetrics/production-report/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/reports/production"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

The full template, with all 24 events, is `MachinemetricsRestApi.lot` in the REST API app. GovCloud tenants set `BASE_ADDRESS` to `https://api.machinemetrics-us-gov.com`.

## MQTT examples

Request bodies go under `body`, so control fields like `api_token`, `machine_ref` and `query` are not sent to MachineMetrics.

**Current execution state of every machine**: publish to `mes/machinemetrics/machine-state/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<MachineMetrics API key>",
  "body": {
    "query": "{ machines { machineRef name currentStates(where: {metricKey: {_eq: \"MasterExecution\"}}) { metricKey value startAt } } }"
  }
}
```

The reply is `{"data": {"machines": [...]}}`, one entry per machine with its `MasterExecution` state (for example `ACTIVE`) and when that state started. Leave out the `where` filter to get every current state metric.

**Active alarms**: publish to `mes/machinemetrics/machine-alarm/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<MachineMetrics API key>",
  "body": {
    "query": "{ machines(where: {currentAlarms: {metricKey: {_eq: \"system\"}, label: {_nin: [\"NORMAL\", \"UNAVAILABLE\"]}}}) { name currentAlarms(where: {metricKey: {_eq: \"system\"}, label: {_nin: [\"NORMAL\", \"UNAVAILABLE\"]}}) { nativeCode label startAt } } }"
  }
}
```

**Machines in downtime right now**: publish to `mes/machinemetrics/machine-downtime/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<MachineMetrics API key>",
  "body": {
    "query": "{ machines(where: {annotations: {endAt: {_is_null: true}}}) { name annotations(where: {endAt: {_is_null: true}}) { startAt annotationType { name } } } }"
  }
}
```

**Yesterday's OEE and good parts per machine**: publish to `mes/machinemetrics/production-report/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<MachineMetrics API key>",
  "body": {
    "startDay": "2026-10-04",
    "endDay": "2026-10-04",
    "data": [{ "metric": "oee" }, { "metric": "goodParts" }, { "metric": "downtime" }],
    "groupBy": [{ "group": "machine" }],
    "flatten": true
  }
}
```

Other metrics include `totalParts`, `rejectedParts`, `timeInCycle`, `timeInCut`, `setupTime` and `utilizationRate`; other groups include `day`, `shift`, `operator` and `jobOperation`. Add `"csv": true` and the reply carries `csv.url`; download it with `GetCsvToken` and `GetProductionCsv`, using the id at the end of that URL as `resource_id`.

**Scheduled time for one machine**: publish to `mes/machinemetrics/machine-scheduled-time/get`. The query string must be URL-encoded:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<MachineMetrics API key>",
  "machine_ref": 1234,
  "query": "startAt=2026-10-05T00:00:00Z&endAt=2026-10-05T08:00:00Z"
}
```

Send `"query": ""` on GET events when you do not need options.

**Add a plant holiday**: publish to `mes/machinemetrics/work-schedule-event/create` with a key that has the `user` scope:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "<MachineMetrics API key>",
  "body": { "name": "Plant shutdown", "eventType": "custom-holiday", "customHolidayDate": "2026-12-24" }
}
```

Then assign it to work schedules with `work-schedule-event/assign` (`event_ref` plus `{"workScheduleRefs": [...], "startRRule": {...}}`).

## Helper actions

Keep the key in a broker secret, poll machine state every minute, and request a day's OEE from any topic:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION MachineMetricsPollMachineState
ON EVERY 1 MINUTE DO
    SET "token" WITH GET SECRET "MACHINEMETRICS_API_TOKEN"
    PUBLISH TOPIC "mes/machinemetrics/machine-state/get" WITH { "api_token": {token}, "body": { "query": "{ machines { machineRef name currentStates { metricKey value startAt } } }" } }

DEFINE ACTION MachineMetricsOeeForDay
ON TOPIC "porto/reports/machinemetrics/oee" DO
    SET "token" WITH GET SECRET "MACHINEMETRICS_API_TOKEN"
    SET "day" WITH GET JSON "day" IN PAYLOAD AS STRING
    PUBLISH TOPIC "mes/machinemetrics/production-report/create" WITH { "api_token": {token}, "body": { "startDay": {day}, "endDay": {day}, "data": [ { "metric": "oee" }, { "metric": "goodParts" }, { "metric": "downtime" } ], "groupBy": [ { "group": "machine" } ], "flatten": true } }
```

Restrict who can publish to `mes/machinemetrics/#` with a rule: its payloads carry the API key, and the work schedule events change planned production time.

## Notes

* The GraphQL API is read-only. Limits: 1000 operations per minute per company, query depth 5, at most 5 object nodes, 10 seconds per query. GraphQL errors come back as `200` with an `errors` array, so check the reply body.
* Times are UTC. Report `startDay` / `endDay` are dates (`YYYY-MM-DD`); `startAt` / `endAt` are ISO 8601 date-times.
* `machineRef`, `workScheduleRef` and the other refs are MachineMetrics integer ids. Get machine refs from a `machines { machineRef name }` query.
* Not covered by this connector: `POST /jobs/import` (multipart CSV upload), MachineMetrics webhooks (MachineMetrics calls your URL when a workflow fires, for example on categorized downtime; receive them with a server-mode connector or another HTTP endpoint), and edge data collection (MTConnect, MQTT and adapter scripts run on the MachineMetrics edge device, not through this API).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Rockwell Plex Smart Manufacturing Platform](/latest/lot-language/routes/rest-api-apps/rockwell-plex-smart-manufacturing-platform)
* [Siemens Opcenter Execution](/latest/lot-language/routes/rest-api-apps/siemens-opcenter-execution)


# Mailgun
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/mailgun

LoT connector for the Mailgun API: send email from plant events, track delivery with events, logs and metrics, manage suppressions, mailing lists and webhooks

Technical Preview

## Overview

A client-mode connector for the [Mailgun API](https://documentation.mailgun.com/docs/mailgun/api-reference/) (Mailgun by Sinch) that sends email from plant data and keeps track of what happened to it. Typical uses are shift reports, alarm digests, maintenance and quality notices, and audit copies, tagged per plant or line so you can filter delivery events and metrics later. The connector also reads and adds suppressions (bounces, unsubscribes, complaints), manages mailing lists for each plant or team, and registers Mailgun webhooks that post delivery events back to a Coreflux server connector.

One connector carries 33 events (21 GET, 9 POST, 3 PUT; 9 writes, no DELETE). Topics use `messaging/mailgun/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. In the Mailgun dashboard, copy your primary account API key (Account Settings, API Keys), or create a domain sending key on the domain's settings page. A sending key can only call `MessageSend`; every other event needs the account key.
2. Use a verified sending domain such as `mg.example.com`. EU domains change `BASE_ADDRESS` to `https://api.eu.mailgun.net`, because a domain lives in one region only.
3. Keep the key in a broker secret (for example `MAILGUN_API_KEY`) and build the header value in a LoT action with `GET SECRET`. Never retain topics that carry it.

## Authentication

Mailgun uses HTTP Basic auth with the literal username `api` and the API key as the password. The connector sends `Authorization: Basic <value>` and takes the value from the payload field `basic_auth`, which is base64 of `api:<key>`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<base64 of api:YOUR_API_KEY>", "domain": "mg.example.com"}
```

## Form and JSON bodies

Sending a message, resending a stored message, creating or updating a webhook and adding or updating a list member take form fields. Pass them URL-encoded in `form`; the connector sends them as `application/x-www-form-urlencoded`. Mailgun options use prefixes such as `o:tag`, `o:testmode`, `h:Reply-To` and `v:asset`, so encode the colon as `%3A`. Suppression adds and the analytics queries (`LogsQuery`, `MetricsQuery`, `UsageMetricsQuery`) take JSON in `body`.

> [!WARNING]
>
> Mailgun documents its send endpoint with `multipart/form-data`. This template sends URL-encoded form fields, which carry the same text fields; confirm with `o:testmode=yes` on your account before relying on it. Attachments and inline images need multipart and are not packaged.

## Examples

Email maintenance when a press overheats (`messaging/mailgun/messages/send`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<base64>", "domain": "mg.example.com", "form": "from=Coreflux%20Porto%20%3Calerts%40mg.example.com%3E&to=maintenance%40example.com&subject=Press%207%20overtemperature&text=Press%207%20at%2094%20C%20on%20line%202&o%3Atag=plant-porto&v%3Aasset=press7"}
```

Mailgun answers with the queued message id, for example `{"id": "<20261005...@mg.example.com>", "message": "Queued. Thank you."}`.

Find failed deliveries from the last day (`messaging/mailgun/events/list`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<base64>", "domain": "mg.example.com", "query": "event=failed&limit=25"}
```

Check whether a technician's address bounced before you rely on it (`messaging/mailgun/bounces/get`; a 404 means it is not suppressed):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<base64>", "domain": "mg.example.com", "address": "tech@example.com"}
```

Send permanent failures to a Coreflux server connector (`messaging/mailgun/webhooks/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<base64>", "domain": "mg.example.com", "form": "id=permanent_fail&url=https%3A%2F%2Fbroker.example.com%2Fmailgun%2Fevents"}
```

Values in `query` and `form` are sent as given, so URL-encode them. Email addresses in path fields (`address`, `list`, `member`) are used as they are.

## Events

| Event | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - |
| `DomainsList` | `GET` | `/v4/domains?{value.json.query}` | `messaging/mailgun/domains/list` | | Smoke: sending domains on the account with state (active, unverified). query e.g. limit=100\&state=active (or empty). |
| `DomainGet` | `GET` | `/v4/domains/{value.json.domain}` | `messaging/mailgun/domains/get` | | One domain with its DNS sending and receiving records and their validity. |
| `DomainVerify` | `PUT` | `/v4/domains/{value.json.domain}/verify` | `messaging/mailgun/domains/verify` | Yes | Re-check the domain's DNS records now (no body). Returns the domain and record validity. |
| `DomainTrackingGet` | `GET` | `/v3/domains/{value.json.domain}/tracking` | `messaging/mailgun/domains/tracking/get` | | Open, click and unsubscribe tracking settings for the domain. |
| `SendingQueuesGet` | `GET` | `/v3/domains/{value.json.domain}/sending_queues` | `messaging/mailgun/domains/sending-queues/get` | | Scheduled and regular sending queue status for the domain (is mail being held back). |
| `MessageSend` | `POST` | `/v3/{value.json.domain}/messages` | `messaging/mailgun/messages/send` | Yes | Catalog 'POST messages'. form (URL-encoded): from, to (repeat or comma-separate), subject and one of text, html or template; optional cc, bcc, o:tag (repeatable, e.g. plant-porto), o:testmode=yes (accepted but not delivered), o:deliverytime (RFC 2822), h:Reply-To, v:asset=press7 (custom variable, echoed in events and webhooks), t:variables (JSON for templates). Options o:/h:/v:/t: max 16 KB total. Returns \{"id":"\<[...@mg.example.com](mailto:...@mg.example.com)>","message":"Queued. Thank you."}. Attachments need multipart and are not packaged. |
| `StoredMessageGet` | `GET` | `/v3/domains/{value.json.domain}/messages/{value.json.storage_key}` | `messaging/mailgun/messages/stored/get` | | A stored message (kept about 3 days) by storage key from an event or webhook (storage.key). |
| `StoredMessageResend` | `POST` | `/v3/domains/{value.json.domain}/messages/{value.json.storage_key}` | `messaging/mailgun/messages/stored/resend` | Yes | Resend a stored message to new recipients. form: to=shift-lead%40example.com. |
| `EventsList` | `GET` | `/v3/{value.json.domain}/events?{value.json.query}` | `messaging/mailgun/events/list` | | Catalog 'GET events'. Delivery events (accepted, delivered, failed, opened, clicked, unsubscribed, complained, stored), kept 3+ days. query e.g. event=failed\&limit=25\&begin=Mon%2C%2005%20Oct%202026%2000%3A00%3A00%20%2B0000\&ascending=yes, or message-id=\<id> or recipient=ops%40example.com. Page with paging.next URL parameters. |
| `LogsQuery` | `POST` | `/v1/analytics/logs` | `messaging/mailgun/analytics/logs/query` | | Account-wide event logs (the newer replacement for domain events). body: \{"duration":"1d","events":\["failed","delivered"],"filter":\{"AND":\[\{"attribute":"domain","comparator":"=","values":\[\{"label":"mg.example.com","value":"mg.example.com"}]}]},"pagination":\{"limit":25}}. Read-only POST. |
| `MetricsQuery` | `POST` | `/v1/analytics/metrics` | `messaging/mailgun/analytics/metrics/query` | | Sending metrics (replaces the deprecated v3 stats). body: \{"resolution":"day","duration":"7d","dimensions":\["time"],"metrics":\["sent\_count","delivered\_count","failed\_count","opened\_count"],"filter":\{"AND":\[\{"attribute":"domain","comparator":"=","values":\[\{"label":"mg.example.com","value":"mg.example.com"}]}]},"include\_aggregates":true}. Read-only POST. |
| `UsageMetricsQuery` | `POST` | `/v1/analytics/usage/metrics` | `messaging/mailgun/analytics/usage/query` | | Account usage (processed, email validation, inbox placement counts). body: \{"resolution":"month","duration":"3M","metrics":\["processed\_count"]}. Read-only POST. |
| `BouncesList` | `GET` | `/v3/{value.json.domain}/bounces?{value.json.query}` | `messaging/mailgun/bounces/list` | | Suppressed bounced addresses. query e.g. limit=100 (page with paging URLs). |
| `BounceGet` | `GET` | `/v3/{value.json.domain}/bounces/{value.json.address}` | `messaging/mailgun/bounces/get` | | Is this address on the bounce list (404 means no)? Check before alerting a contact. |
| `BouncesAdd` | `POST` | `/v3/{value.json.domain}/bounces` | `messaging/mailgun/bounces/add` | Yes | body (JSON array, up to 1000): \[\{"address":"[old-tech@example.com](mailto:old-tech@example.com)","code":"550","error":"Mailbox removed"}]. |
| `UnsubscribesList` | `GET` | `/v3/{value.json.domain}/unsubscribes?{value.json.query}` | `messaging/mailgun/unsubscribes/list` | | Unsubscribed addresses. query e.g. limit=100. |
| `UnsubscribeGet` | `GET` | `/v3/{value.json.domain}/unsubscribes/{value.json.address}` | `messaging/mailgun/unsubscribes/get` | | Unsubscribe record for one address (tags it applies to); 404 if none. |
| `UnsubscribesAdd` | `POST` | `/v3/{value.json.domain}/unsubscribes` | `messaging/mailgun/unsubscribes/add` | Yes | body (JSON array): \[\{"address":"[visitor@example.com](mailto:visitor@example.com)","tags":\["plant-tours"]}] (tags omitted = all mail). |
| `ComplaintsList` | `GET` | `/v3/{value.json.domain}/complaints?{value.json.query}` | `messaging/mailgun/complaints/list` | | Spam complaints. query e.g. limit=100. |
| `ComplaintGet` | `GET` | `/v3/{value.json.domain}/complaints/{value.json.address}` | `messaging/mailgun/complaints/get` | | Complaint record for one address; 404 if none. |
| `WebhooksList` | `GET` | `/v3/domains/{value.json.domain}/webhooks` | `messaging/mailgun/webhooks/list` | | Domain webhooks by event type (accepted, delivered, permanent\_fail, temporary\_fail, opened, clicked, unsubscribed, complained). |
| `WebhookGet` | `GET` | `/v3/domains/{value.json.domain}/webhooks/{value.json.webhook}` | `messaging/mailgun/webhooks/get` | | URLs for one webhook type. webhook e.g. permanent\_fail. |
| `WebhookCreate` | `POST` | `/v3/domains/{value.json.domain}/webhooks` | `messaging/mailgun/webhooks/create` | Yes | Catalog 'server connector for webhook': point a webhook type at a Coreflux ENABLE\_SERVER REST\_API connector. form: id=permanent\_fail\&url=https%3A%2F%2Fbroker.example.com%2Fmailgun%2Fevents (up to 3 url fields). |
| `WebhookUpdate` | `PUT` | `/v3/domains/{value.json.domain}/webhooks/{value.json.webhook}` | `messaging/mailgun/webhooks/update` | Yes | Replace the URLs of one webhook type. form: url=https%3A%2F%2Fbroker.example.com%2Fmailgun%2Fevents. |
| `TemplatesList` | `GET` | `/v3/{value.json.domain}/templates?{value.json.query}` | `messaging/mailgun/templates/list` | | Stored templates on the domain. query e.g. limit=50. |
| `TemplateGet` | `GET` | `/v3/{value.json.domain}/templates/{value.json.template}?{value.json.query}` | `messaging/mailgun/templates/get` | | One template. query active=yes includes the active version content (or empty). |
| `MailingListsList` | `GET` | `/v3/lists/pages?{value.json.query}` | `messaging/mailgun/lists/list` | | Mailing lists on the account. query e.g. limit=100. |
| `MailingListGet` | `GET` | `/v3/lists/{value.json.list}` | `messaging/mailgun/lists/get` | | One mailing list. list = list address, e.g. [porto-shift-leads@mg.example.com](mailto:porto-shift-leads@mg.example.com). |
| `ListMembersList` | `GET` | `/v3/lists/{value.json.list}/members/pages?{value.json.query}` | `messaging/mailgun/lists/members/list` | | Members of a list. query e.g. subscribed=yes\&limit=100. |
| `ListMemberAdd` | `POST` | `/v3/lists/{value.json.list}/members` | `messaging/mailgun/lists/members/add` | Yes | form: address=tech%40example.com\&name=Ana%20Silva\&vars=%7B%22line%22%3A%222%22%7D\&subscribed=yes\&upsert=yes. |
| `ListMemberUpdate` | `PUT` | `/v3/lists/{value.json.list}/members/{value.json.member}` | `messaging/mailgun/lists/members/update` | Yes | form: subscribed=no (or name, vars). member = member email address. |
| `RoutesList` | `GET` | `/v3/routes?{value.json.query}` | `messaging/mailgun/routes/list` | | Inbound connectors (forward incoming mail, e.g. to a Coreflux server connector). query e.g. limit=100\&skip=0. |
| `RouteMatch` | `GET` | `/v3/routes/match?{value.json.query}` | `messaging/mailgun/routes/match` | | Which inbound connector matches an address. query: address=maintenance%40mg.example.com. |

## Limits

Send options (`o:`, `h:`, `v:` and `t:` fields) are limited to 16 KB per message. Events and stored messages are kept for at least 3 days (longer on paid plans). Mailgun rate-limits per account and answers `429` when you send too fast; sandbox domains can only send to authorized recipients. The v3 stats and tag endpoints are deprecated, so this template uses the `/v1/analytics` metrics and logs API instead.

## Not packaged

* All DELETE endpoints (domains, webhooks, suppressions, templates, lists, members, connectors) on purpose.
* Attachments, inline images and MIME sending (`messages.mime`), which need multipart.
* Domain creation and DNS, DKIM keys, IP pools and dedicated IPs, subaccounts, API keys, SMTP credentials, users, alerts, template and connector creation, bulk member uploads and suppression imports.
* Deprecated v3 stats, tags and aggregates; email validation and inbox placement (separate Mailgun Optimize API).
* The incoming webhook direction: Mailgun webhooks post event JSON to a separate `ENABLE_SERVER` REST\_API connector, which should check Mailgun's HMAC signature with the webhook signing key.


# MaintainX
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/maintainx

Client-mode REST API connector for a curated MaintainX v1 slice: list and create work orders

Technical Preview

# MaintainX

Client-mode REST API connector for a curated MaintainX v1 slice: list and create work orders.

* Hub category: **Field service**.
* Base: `https://api.getmaintainx.com`

## Template reference

Generated from the shipped broker template `maintainx` (`-connectorCode MAINTAINX`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the MaintainX connector | no |
| `BaseUrl` | string | MaintainX base URL without trailing slash (e.g. [https://api.getmaintainx.com](https://api.getmaintainx.com)) | yes |

`BASE_ADDRESS` default: `https://api.getmaintainx.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listworkorders` | GET | `/v1/workorders` | `cmms/maintainx/workorders/list` | `cmms/maintainx/workorders/list/response` | `api_token` |
| `Createworkorder` | POST | `/v1/workorders` | `cmms/maintainx/workorders/create` | `cmms/maintainx/workorders/create/response` | `api_token`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode MAINTAINX"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MaintainXRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.getmaintainx.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listworkorders
        WITH SOURCE_TOPIC "cmms/maintainx/workorders/list"
        WITH DESTINATION_TOPIC "cmms/maintainx/workorders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/workorders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createworkorder
        WITH SOURCE_TOPIC "cmms/maintainx/workorders/create"
        WITH DESTINATION_TOPIC "cmms/maintainx/workorders/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/workorders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listworkorders` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'cmms/maintainx/workorders/list/response' &
mosquitto_pub -t 'cmms/maintainx/workorders/list' -m '{"api_token": "<api_token>"}'
```


# Mapbox
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/mapbox

Client-mode REST API connector for a curated Mapbox slice: forward geocoding and driving directions

Technical Preview

# Mapbox

Client-mode REST API connector for a curated Mapbox slice: forward geocoding and driving directions.

* Hub category: **Maps**.
* Base: `https://api.mapbox.com`

## Template reference

Generated from the shipped broker template `mapbox` (`-connectorCode MAPBOX`). It lists every event the template defines.

### Auth

The template sets no auth header. Check the event headers below.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Mapbox connector | no |
| `BaseUrl` | string | Mapbox base URL without trailing slash (e.g. [https://api.mapbox.com](https://api.mapbox.com)) | yes |

`BASE_ADDRESS` default: `https://api.mapbox.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Geocode` | GET | `/geocoding/v5/mapbox.places/{value.json.search_text}.json?access_token={value.json.api_token}` | `maps/mapbox/geocode` | `maps/mapbox/geocode/response` | `api_token`, `search_text` |
| `Directions` | GET | `/directions/v5/mapbox/driving/{value.json.coordinates}?access_token={value.json.api_token}` | `maps/mapbox/directions` | `maps/mapbox/directions/response` | `api_token`, `coordinates` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode MAPBOX"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MapboxRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.mapbox.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Geocode
        WITH SOURCE_TOPIC "maps/mapbox/geocode"
        WITH DESTINATION_TOPIC "maps/mapbox/geocode/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/geocoding/v5/mapbox.places/{value.json.search_text}.json?access_token={value.json.api_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Directions
        WITH SOURCE_TOPIC "maps/mapbox/directions"
        WITH DESTINATION_TOPIC "maps/mapbox/directions/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/directions/v5/mapbox/driving/{value.json.coordinates}?access_token={value.json.api_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Geocode` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'maps/mapbox/geocode/response' &
mosquitto_pub -t 'maps/mapbox/geocode' -m '{"api_token": "<api_token>", "search_text": "<search_text>"}'
```


# Mattermost
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/mattermost

Client-mode REST API connector for a curated Mattermost API v4 slice: create posts, execute incoming webhooks, plus users/me check, system ping, and get channel

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Mattermost API v4](https://docs.mattermost.com/api/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST posts | `POST /api/v4/posts` | Bearer PAT; body `channel_id` + `message` |
| POST webhook URL | `POST /hooks/{hook_id}` | Incoming webhook; path credentials; JSON `text` |
| GET users/me | `GET /api/v4/users/me` | PAT credential check |
| GET system/ping | `GET /api/v4/system/ping` | Liveness (often unauthenticated) |
| GET channels/\{id} | `GET /api/v4/channels/{channel_id}` | Channel lookup |

Default `BASE_ADDRESS` is `https://YOUR_MATTERMOST_HOST` (site origin — **not** including `/api/v4`). Topics use `messaging/mattermost/<object>/<verb>`.

Outgoing webhooks and slash commands that Mattermost POSTs to your infrastructure need a companion `ENABLE_SERVER` connector (document only here).

> [!NOTE]
>
> REST v4 methods send `Authorization: Bearer {token}` (personal access token). Incoming webhook execute uses **only** the hook id in the path — do not send a Bearer header on that event. Prefer Hub secrets (`MATTERMOST_TOKEN`, and site origin via `MATTERMOST_BASE_URL` / `MATTERMOST_HOST`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Mattermost API v4
# Auth: Bearer {value.json.token} on REST; webhook path credentials on Executeincomingwebhook
# BASE_ADDRESS: https://YOUR_MATTERMOST_HOST

DEFINE CONNECTOR MattermostRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_MATTERMOST_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getusersme
        WITH SOURCE_TOPIC "messaging/mattermost/user/get-me"
        WITH DESTINATION_TOPIC "messaging/mattermost/user/get-me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Systemping
        WITH SOURCE_TOPIC "messaging/mattermost/system/ping"
        WITH DESTINATION_TOPIC "messaging/mattermost/system/ping/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/system/ping"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Createpost
        WITH SOURCE_TOPIC "messaging/mattermost/post/create"
        WITH DESTINATION_TOPIC "messaging/mattermost/post/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v4/posts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Executeincomingwebhook
        WITH SOURCE_TOPIC "messaging/mattermost/webhook/incoming"
        WITH DESTINATION_TOPIC "messaging/mattermost/webhook/incoming/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/hooks/{value.json.hook_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getchannel
        WITH SOURCE_TOPIC "messaging/mattermost/channel/get"
        WITH DESTINATION_TOPIC "messaging/mattermost/channel/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v4/channels/{value.json.channel_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getusersme | GET | `/api/v4/users/me` | `messaging/mattermost/user/get-me` | `messaging/mattermost/user/get-me/response` |
| Systemping | GET | `/api/v4/system/ping` | `messaging/mattermost/system/ping` | `messaging/mattermost/system/ping/response` |
| Createpost | POST | `/api/v4/posts` | `messaging/mattermost/post/create` | `messaging/mattermost/post/create/response` |
| Executeincomingwebhook | POST | `/hooks/{hook_id}` | `messaging/mattermost/webhook/incoming` | `messaging/mattermost/webhook/incoming/response` |
| Getchannel | GET | `/api/v4/channels/{channel_id}` | `messaging/mattermost/channel/get` | `messaging/mattermost/channel/get/response` |

## Auth

1. On your Mattermost server, create a **personal access token** for a lab user with `create_post` (and related) permissions. Copy the token once.
2. Set connector `BASE_ADDRESS` to the **site origin** (e.g. `https://mattermost.example.com`) — do **not** append `/api/v4`.
3. For REST events, pass `token` on the MQTT payload so `Authorization: Bearer {value.json.token}` resolves.
4. For incoming webhooks, create an Incoming Webhook in Mattermost Integrations and pass `hook_id` (the id segment after `/hooks/`); do **not** send a Bearer header on Executeincomingwebhook.
5. Store secrets in Hub / `GET SECRET "MATTERMOST_TOKEN"`. Optional site URL secrets: `MATTERMOST_BASE_URL` or `MATTERMOST_HOST`. Never commit real credentials.
6. Successful `GET /api/v4/users/me` returns **HTTP 200** with a user JSON object. `POST /api/v4/posts` returns **201**. Incoming webhook execute typically returns **200** with body `ok`.

## Example payloads

**getUsersMe:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_MATTERMOST_PERSONAL_ACCESS_TOKEN"
}
```

**createPost:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_MATTERMOST_PERSONAL_ACCESS_TOKEN",
  "channel_id": "CHANNEL_ID",
  "message": "Coreflux alarm: vibration above threshold — Zone A"
}
```

**executeIncomingWebhook:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "hook_id": "YOUR_INCOMING_WEBHOOK_ID",
  "text": "#### Coreflux alert\nLine 3 stopped",
  "channel": "town-square",
  "username": "coreflux-bot"
}
```

**systemPing:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{}
```

**getChannel:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_MATTERMOST_PERSONAL_ACCESS_TOKEN",
  "channel_id": "CHANNEL_ID"
}
```

## Deploy notes

* Deployable file: `MattermostRestApi.lot` — **no** `ADD METADATA`.
* Hub sidecar: `hub-metadata.lot` with `WITH STATUS "beta"`, `WITH CATEGORY "REST API Routes"`, and `WITH DOCLINK` to this page.

## References

* [Mattermost API](https://docs.mattermost.com/api/)
* [API reference / authentication](https://docs.mattermost.com/api/reference/mattermost-api)
* [Incoming webhooks](https://docs.mattermost.com/developers/integrate/webhooks/incoming/)
* [OpenAPI source](https://github.com/mattermost/mattermost/tree/master/api/v4/source)
* [REST API Connectors (base)](/latest/lot-language/routes/rest-api-routes)


# Memfault
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/memfault

Connect Coreflux LoT to the Memfault REST API: manage devices and cohorts, create and deploy releases, triage crash issues, and receive issue webhooks

Technical Preview

## Overview

[Memfault](https://memfault.com) is a device reliability platform for MCU, Linux and Android fleets: it collects crashes, metrics and logs from devices through the Memfault SDKs and runs OTA updates by cohort. These connectors connect the Coreflux broker to the Memfault [REST API](https://docs.memfault.com/api), so plant logic can check a device's health and release, move devices between cohorts, roll out firmware and react to new crash issues over MQTT.

* **MemfaultRestApi** (`MemfaultRestApi.lot`) is a client connector on `https://api.memfault.com` with 32 events.
* **MemfaultWebhookReceiver** (`cloud-iot_memfault_webhook.lot`, opt-in, server mode) receives Memfault issue and alert webhooks, so new or regressed issues reach MQTT without polling.

The events follow Memfault's published [OpenAPI definition](https://docs.memfault.com/openapi/memfault-api.yaml).

## Authentication

> [!WARNING]
>
> An Organization Auth Token has project-manager access to every project in the organization, and a user API key acts as that user. Keep the credential in a Hub secret, map it in with `GET SECRET`, and never publish it on a topic other clients can read.

Every event takes `"authorization"` in its MQTT payload and sends it as the whole `Authorization` header, so you can use either Memfault credential:

| Credential | Where to create it | `authorization` value |
| - | - | - |
| Organization Auth Token (recommended) | **Admin → Organization Auth Tokens** (organization admins). The only option when the organization enforces SSO. | `Bearer oat_...` |
| User API key | **Project Settings → User API Key**. Stops working when the user leaves the organization. | `Basic <base64 of email:api_key>` |

1. Store the full value as the secret `MEMFAULT_AUTHORIZATION`.
2. Every project event also takes `"organization_slug"` and `"project_slug"`, as shown in the Memfault app URL.
3. `GetLatestReleaseForDevice` is the device-side check and sends `"project_key"` in the `Memfault-Project-Key` header instead. Project keys aren't secret, but they let anyone send data into the project.

A missing or wrong credential returns `401` with `{"error": {"message": "Unauthorized", "http_code": 401, "type": "UnauthorizedError", "code": 1004}}`.

## Payload conventions

* Path ids (`device_serial`, `cohort_slug`, `release_version`, `deployment_id`, `issue_id`, `task_id`, `software_type_slug`, `version`) go at the top level of the MQTT payload.
* Events marked `?{query}` take the query string already URL-encoded, for example `page=1&per_page=100` (default 20, max 100) or `status=open&sort=-created_date`. Timestamps in filters must be ISO 8601 with `Z`. Send `"query": ""` when there is nothing to add.
* Request bodies come from `"body"` and are sent as JSON.

## Projects and tasks

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetMe | `GET /auth/me` | `cloud-iot/memfault/me/get` | Credential check (user API key, Basic): the logged-in user and their organizations; with an org token use ListProjects instead |
| ListProjects | `GET /api/v0/organizations/{organization_slug}/projects?{query}` | `cloud-iot/memfault/project/list` | Credential check (org token or user key): projects in the organization; query page=1\&per\_page=100 \| sort=-created\_date (send "" for none) |
| GetProject | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}` | `cloud-iot/memfault/project/get` | One project by slug: name, slug, platform, os, count\_devices (the response also carries the project key) |
| GetTaskStatus | `GET /api/v0/queue/{task_id}` | `cloud-iot/memfault/task/get` | Status of an asynchronous task, e.g. \{"status": "SUCCESS"} |

## Devices

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListDevices | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/devices?{query}` | `cloud-iot/memfault/device/list` | Devices in the project (paged, max 100 per page); query page=1\&per\_page=100 \| sort=-created\_date (send "" for none) |
| GetDevice | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/devices/{device_serial}` | `cloud-iot/memfault/device/get` | Catalog: one device by serial: cohort, hardware\_version, last\_seen, last\_seen\_release, latest\_install, latest\_trace |
| CreateDevice | `POST /api/v0/organizations/{organization_slug}/projects/{project_slug}/devices` | `cloud-iot/memfault/device/create` | **Write.** Create a device; body \{"device\_serial": "ABCD1234", "hardware\_version": "proto"} (409 if it already exists) |
| UpdateDevice | `PATCH /api/v0/organizations/{organization_slug}/projects/{project_slug}/devices/{device_serial}` | `cloud-iot/memfault/device/update` | **Write.** Update a device, e.g. move it to a cohort; body \{"cohort": "beta"} (cohort slug) |
| GetDeviceAttributes | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/devices/{device_serial}/attributes?{query}` | `cloud-iot/memfault/device-attributes/get` | Device attributes; query q=line\_\* filters by string\_key (wildcard \*), send "" for all |

## Cohorts

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListCohorts | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/cohorts?{query}` | `cloud-iot/memfault/cohort/list` | Cohorts in the project (paged); send query "" for none |
| GetCohort | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/cohorts/{cohort_slug}` | `cloud-iot/memfault/cohort/get` | One cohort: name, slug, count\_devices, last\_deployment |
| CreateCohort | `POST /api/v0/organizations/{organization_slug}/projects/{project_slug}/cohorts` | `cloud-iot/memfault/cohort/create` | **Write.** Create a cohort; body \{"name": "Beta", "slug": "beta"} (409 if it already exists) |
| UpdateCohort | `PATCH /api/v0/organizations/{organization_slug}/projects/{project_slug}/cohorts/{cohort_slug}` | `cloud-iot/memfault/cohort/update` | **Write.** Update a cohort; body \{"name": "Beta line 1"} (fields from the Cohort schema) |
| ListCohortDevices | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/cohorts/{cohort_slug}/devices?{query}` | `cloud-iot/memfault/cohort-device/list` | Devices in one cohort (paged); query page=1\&per\_page=100 (send "" for none) |
| MoveDevicesToCohort | `PATCH /api/v0/organizations/{organization_slug}/projects/{project_slug}/cohorts/{cohort_slug}/devices` | `cloud-iot/memfault/cohort-device/move` | **Write.** Bulk: move devices to the cohort (removes them from their previous cohort, async, 202); request body shape is not in the published spec, for one device prefer UpdateDevice |

## OTA: releases and deployments

A **release** is a firmware version with its payloads. A **deployment** activates a release for one **cohort**, and the devices in that cohort pick it up the next time they ask for the latest release. A `staged_rollout` deployment only offers it to a share of the cohort.

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListReleases | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/releases?{query}` | `cloud-iot/memfault/release/list` | Releases in the project (paged); query page=1\&per\_page=20 \| sort=-created\_date (send "" for none) |
| GetRelease | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/releases/{release_version}` | `cloud-iot/memfault/release/get` | One release by version: artifacts, count\_devices, min\_version, notes, revision |
| CreateRelease | `POST /api/v0/organizations/{organization_slug}/projects/{project_slug}/releases` | `cloud-iot/memfault/release/create` | **Write.** Create a release record; body \{"version": "1.2.0", "revision": "g31cffde", "notes": "Line 1 fix"} (fields from the Release schema; binaries go through the CLI upload flow) |
| UpdateRelease | `PATCH /api/v0/organizations/{organization_slug}/projects/{project_slug}/releases/{release_version}` | `cloud-iot/memfault/release/update` | **Write.** Update a release; body \{"notes": "Line 1 fix"} (fields from the Release schema) |
| GetLatestReleaseForDevice | `GET /api/v0/releases/latest?{query}` | `cloud-iot/memfault/release-latest/get` | Device-side check (Memfault-Project-Key, not secret): latest release a device should install; query hardware\_version=evt\&software\_type=main\&current\_version=1.0.0\&device\_serial=ABCD1234; 204 = up to date; 100 calls per device per day |
| ListDeployments | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/deployments?{query}` | `cloud-iot/memfault/deployment/list` | Deployments (paged); query cohort=beta\&release=1.2.0 (send "" for none) |
| GetDeployment | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/deployments/{deployment_id}` | `cloud-iot/memfault/deployment/get` | One deployment: cohort, release, status, type, rollout\_percent, deployer |
| CreateDeployment | `POST /api/v0/organizations/{organization_slug}/projects/{project_slug}/deployments` | `cloud-iot/memfault/deployment/create` | **Write.** Catalog: deploy a release to a cohort (devices in the cohort start updating); body \{"type": "normal", "release": "1.2.0", "cohort": "beta"} or \{"type": "staged\_rollout", "release": "1.2.0", "cohort": "beta", "rollout\_percent": 10} |
| UpdateDeployment | `PATCH /api/v0/organizations/{organization_slug}/projects/{project_slug}/deployments/{deployment_id}` | `cloud-iot/memfault/deployment/update` | **Write.** Update a deployment, e.g. widen a staged rollout; body \{"rollout\_percent": 50} (fields from the Deployment schema) |
| ListSoftwareTypes | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/software_types?{query}` | `cloud-iot/memfault/software-type/list` | Software types (firmware components) in the project; send query "" for none |
| GetSoftwareType | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/software_types/{software_type_slug}` | `cloud-iot/memfault/software-type/get` | One software type |
| ListSoftwareVersions | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/software_types/{software_type_slug}/software_versions?{query}` | `cloud-iot/memfault/software-version/list` | Software versions of one software type (paged); send query "" for none |
| GetSoftwareVersion | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/software_types/{software_type_slug}/software_versions/{version}` | `cloud-iot/memfault/software-version/get` | One software version (also tells whether a version exists before deploying) |

## Issues

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListIssues | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/issues?{query}` | `cloud-iot/memfault/issue/list` | Issues (crash / trace groups, paged); query status=open\&cohort=beta\&sort=-created\_date (send "" for none) |
| GetIssue | `GET /api/v0/organizations/{organization_slug}/projects/{project_slug}/issues/{issue_id}` | `cloud-iot/memfault/issue/get` | One issue: title, reason, status, device\_count, trace\_count, first / last release, last\_trace stack |
| UpdateIssue | `PATCH /api/v0/organizations/{organization_slug}/projects/{project_slug}/issues/{issue_id}` | `cloud-iot/memfault/issue/update` | **Write.** Set the issue state; body \{"status": "open"} (spec example; UI states are Unresolved, Resolved, Muted, the API strings for resolve / mute are unconfirmed) |

## Webhook receiver

Deploy `cloud-iot_memfault_webhook.lot` only if you want Memfault to push notifications to the broker. It opens HTTP port `9004`. Put a reverse proxy or tunnel with a public TLS certificate in front of it, and have it verify the `X-Signature-SHA256` header (HMAC-SHA256 of the raw body with the target's signing secret), because the connector itself doesn't.

1. In Memfault, open **Settings → Notifications → External Targets** and add a [Webhook](https://docs.memfault.com/docs/platform/webhooks) target with the public URL `https://<public host>/memfault/webhook/issues`. Keep the signing secret it shows for your proxy.
2. Add a second target for `https://<public host>/memfault/webhook/alerts` and pick it in your [alerts](https://docs.memfault.com/docs/platform/alerts).
3. Use the target's test notification to check the path: it arrives with `"type": "test_notification.dispatched"`.

| Path | Topic | Memfault event types |
| - | - | - |
| `POST /memfault/webhook/issues` | `cloud-iot/memfault/webhook-issue/received` | `issue.created`, `issue.reopened`, `issue.regressed`, `issue.resolved`, `issue_comment.created` |
| `POST /memfault/webhook/alerts` | `cloud-iot/memfault/webhook-alert/received` | `device_threshold_alert.summary`, `device_threshold_alert.incident_started`, `device_threshold_alert.incident_ended`, `fleet_threshold_alert.triggered` |

The body is `{"type": "<event type>", "project": {"id": "...", "slug": "..."}, ...}`. The `Memfault-Delivery` header stays the same on retries, so your proxy can use it to drop duplicates. Memfault marks generic webhooks as experimental, so payload fields beyond `type` and `project` may change.

## Golioth chunk forwarding

If your devices connect through [Golioth](/latest/lot-language/routes/rest-api-apps/golioth), Golioth forwards their Memfault chunks itself with the `memfault` pipeline destination and the project key. Nothing extra runs on the broker. This connector then reads the resulting devices, issues and releases from Memfault. Chunk upload (`chunks.memfault.com`) isn't packaged, because chunks are binary.

## Examples

Read one device:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <MEMFAULT_ORG_TOKEN>", "organization_slug": "coreflux", "project_slug": "porto-line-1", "device_serial": "ABCD1234"}
```

Move a device to the `beta` cohort:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <MEMFAULT_ORG_TOKEN>", "organization_slug": "coreflux", "project_slug": "porto-line-1", "device_serial": "ABCD1234", "body": {"cohort": "beta"}}
```

Deploy release `1.2.0` to 10% of the `beta` cohort:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <MEMFAULT_ORG_TOKEN>", "organization_slug": "coreflux", "project_slug": "porto-line-1", "body": {"type": "staged_rollout", "release": "1.2.0", "cohort": "beta", "rollout_percent": 10}}
```

Check which release a device would get:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"project_key": "<MEMFAULT_PROJECT_KEY>", "query": "hardware_version=evt&software_type=main&current_version=1.1.0&device_serial=ABCD1234"}
```

LoT actions that wire these events to plant topics:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION MemfaultDeployToCohort
ON TOPIC "porto/ota/memfault/deploy" DO
    SET "auth" WITH GET SECRET "MEMFAULT_AUTHORIZATION"
    SET "org" WITH GET SECRET "MEMFAULT_ORG_SLUG"
    SET "proj" WITH GET SECRET "MEMFAULT_PROJECT_SLUG"
    SET "rel" WITH GET JSON "release" IN PAYLOAD AS STRING
    SET "coh" WITH GET JSON "cohort" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/memfault/deployment/create" WITH { "authorization": {auth}, "organization_slug": {org}, "project_slug": {proj}, "body": { "type": "normal", "release": {rel}, "cohort": {coh} } }

DEFINE ACTION MemfaultPollOpenIssues
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET SECRET "MEMFAULT_AUTHORIZATION"
    SET "org" WITH GET SECRET "MEMFAULT_ORG_SLUG"
    SET "proj" WITH GET SECRET "MEMFAULT_PROJECT_SLUG"
    PUBLISH TOPIC "cloud-iot/memfault/issue/list" WITH { "authorization": {auth}, "organization_slug": {org}, "project_slug": {proj}, "query": "status=open&sort=-created_date&per_page=20" }

DEFINE ACTION MemfaultWebhookToPlant
ON TOPIC "cloud-iot/memfault/webhook-issue/received" DO
    SET "kind" WITH (GET JSON "type" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "plant/memfault/issues/" + {kind} WITH PAYLOAD
```

## Writes

11 events change data in Memfault, and each one is marked **Write** above. `CreateDeployment`, `UpdateDeployment`, `UpdateDevice` and `MoveDevicesToCohort` decide which firmware devices in the field install, so test them on a lab cohort first. No `DELETE` operation is packaged, so this connector can't deactivate a deployment or delete devices, cohorts, releases or issues.

> [!NOTE]
>
> Memfault's published spec has no request schemas for most writes. The `CreateDevice`, `UpdateDevice`, `CreateCohort` and `CreateDeployment` bodies above come from the Memfault docs and CLI. Check the other bodies (`CreateRelease`, `UpdateRelease`, `UpdateCohort`, `UpdateDeployment`, `UpdateDeviceAttributes`, `MoveDevicesToCohort`, and the `UpdateIssue` values for resolved or muted) against your project before you rely on them.

## Not packaged

User API key management, project create, update and delete, project and client keys, data uploads (chunks, events, traces, coredumps, bug reports, symbols and release artifacts on the `chunks`, `ingress` and `files` hosts), software type and version create, installs (listed in the spec, but the live API returns `404` for them), SBOMs, nRF Cloud bulk device creation and every `DELETE` are left out of this template.


# Mender
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/mender

LoT connector for Mender OTA updates: list, tag and group devices, accept pending devices, deploy releases to devices or groups, track or abort rollouts

Technical Preview

## Overview

One client-mode connector, **Mender**, for the [Mender](https://mender.io) Management APIs on hosted Mender (`https://hosted.mender.io`). Mender is an open-source over-the-air (OTA) update manager for Linux edge devices. The connector covers four of its services, all behind the same token:

* **Device inventory**: list, read and search devices, tag them and put them in groups;
* **Device authentication**: list pending devices and accept or reject them;
* **Deployments**: list releases, start a deployment to devices or to a group, read its statistics and abort it;
* **Mender Connect**: ask an online device to check for an update or re-send its inventory right now.

Use it to drive gateway updates from the plant floor: tag each gateway with its UNS location, accept a newly installed gateway when commissioning finishes, roll a release out to one line only when that line reports it is idle, and abort a rollout when an alarm fires.

| Event | Request | Notes |
| - | - | - |
| Login | `POST /v1/useradm/auth/login` | Basic `email:password`; returns a JWT as text |
| ListDevices | `GET /v1/inventory/devices?{query}` | Pass the query string in `query`, for example `group=line-1&per_page=50` |
| GetDevice | `GET /v1/inventory/devices/{device_id}` | All inventory, identity and tag attributes |
| SearchDevices | `POST /v2/inventory/filters/search` | Filter by any inventory attribute |
| AddDeviceTags | `PATCH /v1/inventory/devices/{device_id}/tags` | Body is a JSON array of `{name, value}` |
| AssignDeviceGroup | `PUT /v1/inventory/devices/{device_id}/group` | Body `{"group": "line-1"}`; returns `204` |
| ListGroups | `GET /v1/inventory/groups` | |
| ListGroupDevices | `GET /v1/inventory/groups/{group}/devices` | Device ids in one group |
| InventoryStatistics | `GET /v2/inventory/statistics` | Device counts by status |
| ListAuthDevices | `GET /v2/devauth/devices?{query}` | `query` such as `status=pending` |
| GetAuthDevice | `GET /v2/devauth/devices/{device_id}` | Identity data and auth sets (`auth_id`) |
| SetAuthStatus | `PUT /v2/devauth/devices/{device_id}/auth/{auth_id}/status` | Accept or reject a device; returns `204` |
| CountDevices | `GET /v2/devauth/devices/count?status={status}` | Always pass `status` |
| ListReleases | `GET /v2/deployments/deployments/releases?{query}` | `query` such as `per_page=20&name=press-fw` |
| ListDeployments | `GET /v2/deployments/deployments?{query}` | `query` such as `status=inprogress` |
| CreateDeployment | `POST /v1/deployments/deployments` | Deploy an artifact to a list of device ids; returns `201` |
| CreateGroupDeployment | `POST /v1/deployments/deployments/group/{group}` | Deploy to every device in a group; returns `201` |
| GetDeployment | `GET /v1/deployments/deployments/{deployment_id}` | |
| GetDeploymentStatistics | `GET /v1/deployments/deployments/{deployment_id}/statistics` | Per-status device counts |
| AbortDeployment | `PUT /v1/deployments/deployments/{deployment_id}/status` | Body `{"status": "aborted"}`; returns `204` |
| ListDeviceDeployments | `GET /v1/deployments/deployments/devices/{device_id}` | Deployment history of one device |
| CheckUpdate | `POST /v1/deviceconnect/devices/{device_id}/check-update` | Device checks for an update now (Mender Connect); `202` |
| SendInventory | `POST /v1/deviceconnect/devices/{device_id}/send-inventory` | Device re-sends its inventory now (Mender Connect); `202` |

All paths start with `/api/management`. Topics use `cloud-iot/mender/<object>/<verb>`; replies land on `<topic>/response`. For hosted Mender in the EU, change `BASE_ADDRESS` to `https://eu.hosted.mender.io`. For a self-hosted Mender Server, use your own server address.

> [!WARNING]
>
> Never commit a token. Store it as a broker secret (for example `MENDER_TOKEN`) and map it into payloads with `GET SECRET`. A Personal Access Token has every permission of the user who created it, including starting deployments to your whole fleet. Use a user with a restricted role where your plan allows it, and protect the `cloud-iot/mender/#` topics with a rule.

## Authentication

Every event except `Login` sends `Authorization: Bearer <token>`. Use a **Personal Access Token**: create it on the **My profile** page of the Mender UI, or call `POST /api/management/v1/useradm/settings/tokens` as described in [Using the APIs](https://docs.mender.io/server-integration/using-the-apis). Tokens last up to one year, and Mender revokes them when your plan or add-ons change.

Pass the token as `token` on every payload. A missing, expired or invalid token returns `401`.

`Login` exchanges `email:password` for a user JWT that expires after about a week. Pass `basic_auth` as the Base64 of `email:password`; the response is the JWT as plain text. Prefer a Personal Access Token on a broker: no password is stored, and accounts with two-factor authentication cannot use Basic login.

## Basic Syntax

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Mender WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://hosted.mender.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Login
        WITH SOURCE_TOPIC "cloud-iot/mender/auth/login"
        WITH DESTINATION_TOPIC "cloud-iot/mender/auth/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/management/v1/useradm/auth/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_auth}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "cloud-iot/mender/device/list"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v1/inventory/devices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "cloud-iot/mender/device/get"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v1/inventory/devices/{value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT SearchDevices
        WITH SOURCE_TOPIC "cloud-iot/mender/device/search"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/management/v2/inventory/filters/search"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT AddDeviceTags
        WITH SOURCE_TOPIC "cloud-iot/mender/device-tags/add"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device-tags/add/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/management/v1/inventory/devices/{value.json.device_id}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT AssignDeviceGroup
        WITH SOURCE_TOPIC "cloud-iot/mender/device-group/assign"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device-group/assign/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/management/v1/inventory/devices/{value.json.device_id}/group"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListGroups
        WITH SOURCE_TOPIC "cloud-iot/mender/group/list"
        WITH DESTINATION_TOPIC "cloud-iot/mender/group/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v1/inventory/groups"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListGroupDevices
        WITH SOURCE_TOPIC "cloud-iot/mender/group/devices"
        WITH DESTINATION_TOPIC "cloud-iot/mender/group/devices/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v1/inventory/groups/{value.json.group}/devices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT InventoryStatistics
        WITH SOURCE_TOPIC "cloud-iot/mender/inventory/statistics"
        WITH DESTINATION_TOPIC "cloud-iot/mender/inventory/statistics/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v2/inventory/statistics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListAuthDevices
        WITH SOURCE_TOPIC "cloud-iot/mender/auth-device/list"
        WITH DESTINATION_TOPIC "cloud-iot/mender/auth-device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v2/devauth/devices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetAuthDevice
        WITH SOURCE_TOPIC "cloud-iot/mender/auth-device/get"
        WITH DESTINATION_TOPIC "cloud-iot/mender/auth-device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v2/devauth/devices/{value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT SetAuthStatus
        WITH SOURCE_TOPIC "cloud-iot/mender/auth-device/set-status"
        WITH DESTINATION_TOPIC "cloud-iot/mender/auth-device/set-status/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/management/v2/devauth/devices/{value.json.device_id}/auth/{value.json.auth_id}/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CountDevices
        WITH SOURCE_TOPIC "cloud-iot/mender/auth-device/count"
        WITH DESTINATION_TOPIC "cloud-iot/mender/auth-device/count/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v2/devauth/devices/count?status={value.json.status}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListReleases
        WITH SOURCE_TOPIC "cloud-iot/mender/release/list"
        WITH DESTINATION_TOPIC "cloud-iot/mender/release/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v2/deployments/deployments/releases?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListDeployments
        WITH SOURCE_TOPIC "cloud-iot/mender/deployment/list"
        WITH DESTINATION_TOPIC "cloud-iot/mender/deployment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v2/deployments/deployments?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT CreateDeployment
        WITH SOURCE_TOPIC "cloud-iot/mender/deployment/create"
        WITH DESTINATION_TOPIC "cloud-iot/mender/deployment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/management/v1/deployments/deployments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateGroupDeployment
        WITH SOURCE_TOPIC "cloud-iot/mender/deployment/create-group"
        WITH DESTINATION_TOPIC "cloud-iot/mender/deployment/create-group/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/management/v1/deployments/deployments/group/{value.json.group}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDeployment
        WITH SOURCE_TOPIC "cloud-iot/mender/deployment/get"
        WITH DESTINATION_TOPIC "cloud-iot/mender/deployment/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v1/deployments/deployments/{value.json.deployment_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetDeploymentStatistics
        WITH SOURCE_TOPIC "cloud-iot/mender/deployment/statistics"
        WITH DESTINATION_TOPIC "cloud-iot/mender/deployment/statistics/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v1/deployments/deployments/{value.json.deployment_id}/statistics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT AbortDeployment
        WITH SOURCE_TOPIC "cloud-iot/mender/deployment/abort"
        WITH DESTINATION_TOPIC "cloud-iot/mender/deployment/abort/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/management/v1/deployments/deployments/{value.json.deployment_id}/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDeviceDeployments
        WITH SOURCE_TOPIC "cloud-iot/mender/device-deployment/list"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device-deployment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/management/v1/deployments/deployments/devices/{value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT CheckUpdate
        WITH SOURCE_TOPIC "cloud-iot/mender/device/check-update"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device/check-update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/management/v1/deviceconnect/devices/{value.json.device_id}/check-update"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY ""
    ADD EVENT SendInventory
        WITH SOURCE_TOPIC "cloud-iot/mender/device/send-inventory"
        WITH DESTINATION_TOPIC "cloud-iot/mender/device/send-inventory/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/management/v1/deviceconnect/devices/{value.json.device_id}/send-inventory"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY ""
```

## MQTT examples

Request bodies go under `body`, so control fields like `token`, `device_id` and `group` are not sent to Mender.

**Accept a new gateway**: list pending devices by publishing to `cloud-iot/mender/auth-device/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<Mender token>",
  "query": "status=pending"
}
```

Each device in the reply has an `id` and an `auth_sets` list. Accept it on `cloud-iot/mender/auth-device/set-status`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<Mender token>",
  "device_id": "<device id>",
  "auth_id": "<auth set id>",
  "body": {"status": "accepted"}
}
```

**Tag a device with its UNS location and put it in a group**: publish to `cloud-iot/mender/device-tags/add`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<Mender token>",
  "device_id": "<device id>",
  "body": [{"name": "uns_path", "value": "porto/line1/press-07"}, {"name": "line", "value": "line-1"}]
}
```

Then `{"token": "<token>", "device_id": "<device id>", "body": {"group": "line-1"}}` on `cloud-iot/mender/device-group/assign`. A device belongs to one group at a time.

**Find devices by inventory attribute**: publish to `cloud-iot/mender/device/search`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<Mender token>",
  "body": {
    "page": 1,
    "per_page": 20,
    "filters": [{"scope": "inventory", "attribute": "device_type", "type": "$eq", "value": "raspberrypi4"}]
  }
}
```

**Roll a release out to one line**: publish to `cloud-iot/mender/deployment/create-group`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<Mender token>",
  "group": "line-1",
  "body": {"name": "line-1 press-fw 2.4.1", "artifact_name": "press-fw-2.4.1"}
}
```

Mender returns `201` and puts the new deployment id in the `Location` header; `ListDeployments` with `"query": "status=inprogress"` also returns it. To deploy to specific devices instead, use `cloud-iot/mender/deployment/create` with `"devices": ["<device id>", ...]` in the body. Get artifact names from `cloud-iot/mender/release/list`.

**Track and abort a rollout**: publish `{"token": "<token>", "deployment_id": "<id>"}` to `cloud-iot/mender/deployment/statistics` for per-status device counts (`pending`, `downloading`, `installing`, `success`, `failure` and more). To stop it, publish `{"token": "<token>", "deployment_id": "<id>", "body": {"status": "aborted"}}` to `cloud-iot/mender/deployment/abort`.

**Ask a device to check now**: publish `{"token": "<token>", "device_id": "<device id>"}` to `cloud-iot/mender/device/check-update` or `cloud-iot/mender/device/send-inventory`. These need Mender Connect running on the device and return `202`; the device has to be online.

## Helper actions

Keep the token in a broker secret, watch for new gateways on a timer, and let operators or line logic trigger rollouts and tags with small payloads:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION MenderPollPendingDevices
ON EVERY 10 MINUTES DO
    SET "token" WITH GET SECRET "MENDER_TOKEN"
    PUBLISH TOPIC "cloud-iot/mender/auth-device/list" WITH { "token": {token}, "query": "status=pending&per_page=50" }

DEFINE ACTION MenderDeployToGroupOnRequest
ON TOPIC "ops/mender/deploy-group" DO
    SET "token" WITH GET SECRET "MENDER_TOKEN"
    SET "group" WITH GET JSON "group" IN PAYLOAD AS STRING
    SET "artifact" WITH GET JSON "artifact" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/mender/deployment/create-group" WITH { "token": {token}, "group": {group}, "body": { "name": {artifact}, "artifact_name": {artifact} } }

DEFINE ACTION MenderTagDeviceOnRequest
ON TOPIC "ops/mender/tag-device" DO
    SET "token" WITH GET SECRET "MENDER_TOKEN"
    SET "device" WITH GET JSON "device_id" IN PAYLOAD AS STRING
    SET "uns" WITH GET JSON "uns_path" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/mender/device-tags/add" WITH { "token": {token}, "device_id": {device}, "body": [ { "name": "uns_path", "value": {uns} } ] }
```

`MenderPollPendingDevices` publishes the pending device list to `cloud-iot/mender/auth-device/list/response` every ten minutes. `MenderDeployToGroupOnRequest` uses the artifact name as the deployment name. Restrict who can publish to `ops/mender/#` and read `cloud-iot/mender/#` with a rule: these topics can push software to devices and their payloads carry the token.

## Notes

* Errors come back on the response topic: `401` for a missing or invalid token, `403` when your plan or role does not allow the call, `404` for an unknown device, group or deployment, `400` or `422` for a bad body or an artifact that does not exist, `409` when a deployment has no target devices or a device is not connected, and `429` when rate limited.
* `CountDevices` always sends `status=`, so pass one of `accepted`, `pending`, `rejected`, `preauthorized` or `noauth`. The `query` field on list events must be URL-encoded.
* Device ids are Mender's own ids, not your device serial numbers. Find them with `SearchDevices` or `ListDevices`.
* Artifact upload, device decommissioning, configuration (`deviceconfig`), remote terminal and file transfer, and user management are not part of this template. Upload artifacts with `mender-cli` or the UI.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [balena](/latest/lot-language/routes/rest-api-apps/balena)
* [AWS IoT Core](/latest/lot-language/routes/rest-api-apps/aws-iot-core)


# Metabase
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/metabase

Connect Coreflux LoT to the Metabase REST API: run saved questions or native SQL queries and publish rows on MQTT, and list databases, cards and dashboards

Technical Preview

## Overview

A client-mode connector for the [Metabase REST API](https://www.metabase.com/docs/latest/api). Use it to push the result of a saved question (OEE per line, scrap by shift, open work orders) onto MQTT for an HMI, andon board or edge display, or to run a short SQL query against any database connected to Metabase when a broker event arrives.

| Event | Request | Notes |
| - | - | - |
| Health | `GET /api/health` | No auth. `200` `{"status":"ok"}` |
| GetCurrentUser | `GET /api/user/current` | Checks the API key |
| ListDatabases | `GET /api/database` | Database ids for DatasetQuery |
| ListCards | `GET /api/card?f={filter}` | Saved questions, models and metrics (`f`: `all`, `mine`, `bookmarked`, `archived`) |
| GetCard | `GET /api/card/{card_id}` | Query definition and template tags |
| QueryCard | `POST /api/card/{card_id}/query` | Full result: `status`, `row_count`, `data.cols`, `data.rows` |
| QueryCardJson | `POST /api/card/{card_id}/query/json` | Rows as a JSON array of objects, ready for a display |
| DatasetQuery | `POST /api/dataset` | Ad-hoc native SQL or MBQL query |
| ListDashboards | `GET /api/dashboard?f={filter}` | `f`: `all`, `mine`, `archived` |
| GetDashboard | `GET /api/dashboard/{dashboard_id}` | Dashboard cards and parameters |

Set `BASE_ADDRESS` to your Metabase URL with no trailing slash and no `/api`, for example `https://metabase.example.com` or `https://yourcompany.metabaseapp.com` on Metabase Cloud. Topics use `analytics/metabase/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** create an API key in **Admin settings > Settings > Authentication > API keys** (Metabase 49 or later) and send it on the `x-api-key` header. The key is assigned to a group and has only that group's data and collection permissions, so create a group with access to just the questions and databases the broker needs. Keep the key in Hub secrets (suggested name `METABASE_API_KEY`) and never commit it into the `.lot`. Older versions, or setups without API keys, can sign in with `POST /api/session` (`{"username","password"}`) and send the returned `id` on `X-Metabase-Session` instead (edit the header in the template).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MetabaseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_METABASE_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Health
        WITH SOURCE_TOPIC "analytics/metabase/health/get"
        WITH DESTINATION_TOPIC "analytics/metabase/health/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/health"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT GetCurrentUser
        WITH SOURCE_TOPIC "analytics/metabase/user/current"
        WITH DESTINATION_TOPIC "analytics/metabase/user/current/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/user/current"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT ListDatabases
        WITH SOURCE_TOPIC "analytics/metabase/databases/list"
        WITH DESTINATION_TOPIC "analytics/metabase/databases/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/database"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT ListCards
        WITH SOURCE_TOPIC "analytics/metabase/cards/list"
        WITH DESTINATION_TOPIC "analytics/metabase/cards/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/card?f={value.json.filter}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT GetCard
        WITH SOURCE_TOPIC "analytics/metabase/cards/get"
        WITH DESTINATION_TOPIC "analytics/metabase/cards/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/card/{value.json.card_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT QueryCard
        WITH SOURCE_TOPIC "analytics/metabase/cards/query"
        WITH DESTINATION_TOPIC "analytics/metabase/cards/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/card/{value.json.card_id}/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT QueryCardJson
        WITH SOURCE_TOPIC "analytics/metabase/cards/query/json"
        WITH DESTINATION_TOPIC "analytics/metabase/cards/query/json/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/card/{value.json.card_id}/query/json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DatasetQuery
        WITH SOURCE_TOPIC "analytics/metabase/dataset/query"
        WITH DESTINATION_TOPIC "analytics/metabase/dataset/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/dataset"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDashboards
        WITH SOURCE_TOPIC "analytics/metabase/dashboards/list"
        WITH DESTINATION_TOPIC "analytics/metabase/dashboards/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/dashboard?f={value.json.filter}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
    ADD EVENT GetDashboard
        WITH SOURCE_TOPIC "analytics/metabase/dashboards/get"
        WITH DESTINATION_TOPIC "analytics/metabase/dashboards/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/dashboard/{value.json.dashboard_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "x-api-key" "{value.json.api_key}"
```

## MQTT examples

Every authenticated event reads `api_key` from the payload. Query events send `body` as the JSON request body, so the key is never forwarded to Metabase in the body.

**Health check** — publish anything to `analytics/metabase/health/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{}
```

Reply on `analytics/metabase/health/get/response`: `{"status":"ok"}`.

**Run a saved question for a display** — publish to `analytics/metabase/cards/query/json`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "YOUR_METABASE_API_KEY", "card_id": "40", "body": {"parameters": [], "format_rows": false}}
```

Reply (tested on v0.63.19.1 with a question on the Sample Database):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
{"category":"Doohickey","orders":3976,"revenue":297270.99},
{"category":"Gadget","orders":4939,"revenue":406621.25},
{"category":"Gizmo","orders":4784,"revenue":383061.95},
{"category":"Widget","orders":5061,"revenue":423667.5}
]
```

To filter a question that has a field filter or variable, pass parameters, for example `{"type": "category", "target": ["variable", ["template-tag", "line"]], "value": "A"}`. `format_rows: true` returns values formatted as in the Metabase UI (dates, currency).

**Full result with column metadata** — publish the same payload to `analytics/metabase/cards/query`. Metabase answers **202** with `{"status":"completed","row_count":4,"data":{"cols":[...],"rows":[["Doohickey",3976,297270.99], ...]}}`.

**Ad-hoc SQL** — publish to `analytics/metabase/dataset/query`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "YOUR_METABASE_API_KEY", "body": {"database": 1, "type": "native", "native": {"query": "SELECT CATEGORY, COUNT(*) AS N FROM PRODUCTS GROUP BY CATEGORY"}}}
```

Reply: **202** with `"status":"completed"` and `data.rows`. A failing query returns **400** with `"status":"failed"` and the database error in `error` (older Metabase versions answer **202** with `"status":"failed"`, so check `status`).

**List saved questions** — publish to `analytics/metabase/cards/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "YOUR_METABASE_API_KEY", "filter": "all"}
```

## Feeding a display

A small action can republish the latest JSON rows on a retained topic for an HMI. Use `PUBLISH TOPIC ... RETAIN`, not `KEEP TOPIC`: `KEEP TOPIC` stores the value inside the broker only, so the HMI would never receive it.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION MetabaseOrdersToDisplay
ON TOPIC "analytics/metabase/cards/query/json/response" DO
    PUBLISH TOPIC "display/metabase/orders/rows" WITH PAYLOAD RETAIN
```

Trigger the question on a schedule with another action that publishes the request payload to `analytics/metabase/cards/query/json` (build it with `GET SECRET "METABASE_API_KEY"` rather than hard-coding the key). Restrict who can read `analytics/metabase/#` with a rule, because request payloads carry the API key.

## Alerts and webhooks (companion, not packaged)

Metabase alerts and dashboard subscriptions can send to a [webhook](https://www.metabase.com/docs/latest/configuring-metabase/webhooks) destination (Admin settings > Notification channels > Webhook). Receiving them on the broker needs a separate `ENABLE_SERVER` REST API connector that accepts a `POST` on a reachable HTTPS address and publishes the alert payload to MQTT. That companion connector is not part of this template.

## Notes

* `/api/card/{id}/query/json` is an export endpoint. It returns all rows up to the download row limit, while `/api/card/{id}/query` and `/api/dataset` cap results at 2,000 rows. Keep display questions small and aggregated.
* Unknown card ids return **404** `Not found.`; a missing or wrong API key returns **401** `Unauthenticated`.
* Native SQL through `/api/dataset` needs native query permission on that database for the key's group.
* Not covered: CSV / XLSX exports (`/query/csv`, `/query/xlsx`), creating or editing questions and dashboards, pivot queries, embedding and public links.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Metabase API documentation](https://www.metabase.com/docs/latest/api)
* [Metabase API keys](https://www.metabase.com/docs/latest/people-and-groups/api-keys)
* [Metabase webhooks](https://www.metabase.com/docs/latest/configuring-metabase/webhooks)
* [Metabase on GitHub](https://github.com/metabase/metabase)


# Microsoft Power BI
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/microsoft-power-bi

Client-mode REST API connector for Power BI push-dataset PostRows, dataset refresh, and real-time streaming push URL — MQTT into Power BI tiles

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [Power BI REST API](https://learn.microsoft.com/en-us/rest/api/power-bi/) focused on IIoT / edge telemetry into dashboards:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST datasets/\{id}/tables/\{t}/rows | `POST /v1.0/myorg/datasets/{id}/tables/{t}/rows` | Authenticated push dataset; body `{"rows":[...]}` |
| POST datasets/\{id}/refreshes | `POST /v1.0/myorg/datasets/{id}/refreshes` | Trigger refresh; optional `notifyOption`; expect **202** |
| POST streaming push URL | `POST /beta/myorg/datasets/{id}/rows?key=` | Classic real-time streaming; **no** Bearer; body JSON **array** |
| (supporting) push\_path | `POST {push_path}` | Path+query from a full push URL under same host |
| (supporting) GET datasets | `GET /v1.0/myorg/datasets` | List My workspace datasets |
| (supporting) GET refreshes | `GET /v1.0/myorg/datasets/{id}/refreshes?$top=` | Refresh history |
| (supporting) DELETE rows | `DELETE /v1.0/myorg/datasets/{id}/tables/{t}/rows` | Clear push-dataset table |

Default `BASE_ADDRESS` is `https://api.powerbi.com` (no trailing slash). Topics use `analytics/powerbi/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth (v1.0):** `Authorization: Bearer &lt;Entra access token&gt;`. Prefer Hub secrets (`GET SECRET "POWER_BI_ACCESS_TOKEN"` / `"AZURE_AD_ACCESS_TOKEN"`). Service principals need workspace access and Power BI API permissions (e.g. `Dataset.ReadWrite.All` / `.default`).

> [!NOTE]
>
> **Streaming push URL:** the Power BI service issues a full URL with an embedded `key` query param. Keep `BASE_ADDRESS` as `https://api.powerbi.com` and use `PostStreamingPush` (`dataset_id` + `push_key`) or `PostStreamingPushPath` (`push_path` = path+query). Do **not** send a Bearer header on those events.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Microsoft Power BI
# Auth: Authorization Bearer {value.json.api_token} (v1.0); streaming push key needs none
# BASE_ADDRESS: https://api.powerbi.com

DEFINE CONNECTOR MicrosoftPowerBiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.powerbi.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostRows
        WITH SOURCE_TOPIC "analytics/powerbi/datasets/rows/post"
        WITH DESTINATION_TOPIC "analytics/powerbi/datasets/rows/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1.0/myorg/datasets/{value.json.dataset_id}/tables/{value.json.table_name}/rows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT RefreshDataset
        WITH SOURCE_TOPIC "analytics/powerbi/datasets/refreshes/post"
        WITH DESTINATION_TOPIC "analytics/powerbi/datasets/refreshes/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1.0/myorg/datasets/{value.json.dataset_id}/refreshes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT PostStreamingPush
        WITH SOURCE_TOPIC "analytics/powerbi/streaming/rows/post"
        WITH DESTINATION_TOPIC "analytics/powerbi/streaming/rows/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/beta/myorg/datasets/{value.json.dataset_id}/rows?key={value.json.push_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
```

## Topics

| Event | Source topic | Destination topic |
| - | - | - |
| PostRows | `analytics/powerbi/datasets/rows/post` | `…/response` |
| RefreshDataset | `analytics/powerbi/datasets/refreshes/post` | `…/response` |
| PostStreamingPush | `analytics/powerbi/streaming/rows/post` | `…/response` |
| PostStreamingPushPath | `analytics/powerbi/streaming/push-url/post` | `…/response` |
| GetDatasets | `analytics/powerbi/datasets/list` | `…/response` |
| GetRefreshHistory | `analytics/powerbi/datasets/refreshes/list` | `…/response` |
| DeleteRows | `analytics/powerbi/datasets/rows/delete` | `…/response` |

## Configuration

1. Set `BASE_ADDRESS` to `https://api.powerbi.com`.
2. Store an Entra access token in Hub secrets; map into MQTT `api_token` for v1.0 events.
3. For push datasets: create the dataset/table schema via the Power BI API, then PostRows / DeleteRows.
4. For real-time streaming: create a streaming dataset in the Power BI service, copy the push URL, and use `dataset_id` + `push_key` (or `push_path`).
5. For import datasets: use RefreshDataset (push PostRows does not apply).

## References

* [Power BI REST API](https://learn.microsoft.com/en-us/rest/api/power-bi/)
* [Push datasets — PostRows](https://learn.microsoft.com/en-us/rest/api/power-bi/push-datasets/datasets-post-rows)
* [Refresh dataset](https://learn.microsoft.com/en-us/rest/api/power-bi/datasets/refresh-dataset)
* [Get refresh history](https://learn.microsoft.com/en-us/rest/api/power-bi/datasets/get-refresh-history)
* [Real-time streaming in Power BI](https://learn.microsoft.com/en-us/power-bi/connect-data/service-real-time-streaming)
* [Embed with service principal](https://learn.microsoft.com/en-us/power-bi/developer/embedded/embed-service-principal)


# Microsoft Teams
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/microsoft-teams

Client-mode REST API connector for a curated Microsoft Teams slice: Graph channel and chat messages plus Workflows Incoming Webhook Adaptive Cards

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of [Microsoft Graph Teams](https://learn.microsoft.com/en-us/graph/api/channel-post-messages) and [Workflows Incoming Webhooks](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST teams/\{id}/channels/\{id}/messages | `POST /teams/{team-id}/channels/{channel-id}/messages` | **Host:** `https://graph.microsoft.com/v1.0` — Bearer Entra token |
| POST Adaptive Card to webhook URL | `POST {webhook_path}` | **Host:** operator Workflows / Power Automate origin — no Authorization |
| POST chats/\{id}/messages | `POST /chats/{chat-id}/messages` | **Host:** Graph v1.0 — Bearer Entra token |

Default `BASE_ADDRESS` is `https://graph.microsoft.com/v1.0`. Topics use `messaging/microsoft-teams/<object>/<verb>`.

> [!NOTE]
>
> Workflows Incoming Webhooks are **not** on `graph.microsoft.com`. When calling `Postwebhookadaptivecard`, set connector `BASE_ADDRESS` to the webhook origin (scheme + host + port) and put path + query in `webhook_path`. Auth for the webhook is embedded in the URL; do not send an Authorization header.

> [!NOTE]
>
> Prefer Hub secrets for Entra access tokens. Channel/chat send usually needs a **delegated** token (`ChannelMessage.Send`, `Chat.ReadWrite`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Microsoft Teams (Graph + Workflows webhook)
# Auth Graph: Bearer {value.json.access_token}
# Auth Webhook: none (URL embeds signature)
# BASE_ADDRESS Graph: https://graph.microsoft.com/v1.0
# Webhook: set BASE_ADDRESS to webhook origin

DEFINE CONNECTOR MicrosoftTeamsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://graph.microsoft.com/v1.0"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Postchannelmessage
        WITH SOURCE_TOPIC "messaging/microsoft-teams/channel/message"
        WITH DESTINATION_TOPIC "messaging/microsoft-teams/channel/message/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/teams/{value.json.team_id}/channels/{value.json.channel_id}/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Postchatmessage
        WITH SOURCE_TOPIC "messaging/microsoft-teams/chat/message"
        WITH DESTINATION_TOPIC "messaging/microsoft-teams/chat/message/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/chats/{value.json.chat_id}/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Postwebhookadaptivecard
        WITH SOURCE_TOPIC "messaging/microsoft-teams/webhook/adaptive-card"
        WITH DESTINATION_TOPIC "messaging/microsoft-teams/webhook/adaptive-card/response"
        WITH METHOD "POST"
        WITH ENDPOINT "{value.json.webhook_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Postchannelmessage | POST | `/teams/{team_id}/channels/{channel_id}/messages` | `messaging/microsoft-teams/channel/message` | `messaging/microsoft-teams/channel/message/response` |
| Postchatmessage | POST | `/chats/{chat_id}/messages` | `messaging/microsoft-teams/chat/message` | `messaging/microsoft-teams/chat/message/response` |
| Postwebhookadaptivecard | POST | `{webhook_path}` | `messaging/microsoft-teams/webhook/adaptive-card` | `messaging/microsoft-teams/webhook/adaptive-card/response` |

## Auth

**Microsoft Graph (channel / chat):**

1. Register an Entra ID app (or use an existing one) and obtain an access token for `https://graph.microsoft.com`.
2. Prefer **delegated** permissions: `ChannelMessage.Send`, `Chat.ReadWrite` / `ChatMessage.Send`.
3. Set connector `BASE_ADDRESS` to `https://graph.microsoft.com/v1.0`.
4. Pass `access_token` on the MQTT request payload so headers resolve: `Authorization: Bearer {value.json.access_token}`.
5. Store the token in Hub secrets / `GET SECRET "TEAMS_GRAPH_TOKEN"`. Never commit real credentials.
6. Successful send returns **HTTP 201**.

**Workflows Incoming Webhook (Adaptive Card):**

1. In Teams, create a Workflow from a webhook template (or Power Automate "When a Teams webhook request is received").
2. Copy the HTTP POST URL. Split into origin → `BASE_ADDRESS` and path+query → `webhook_path`.
3. POST an Adaptive Card wrapper (`type: message`, `attachments[].contentType: application/vnd.microsoft.card.adaptive`).
4. No Authorization header. Expect **HTTP 200/202** depending on the connector.

## Example payloads

**Channel message:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "team_id": "TEAM_GUID",
  "channel_id": "CHANNEL_ID",
  "body": { "content": "Hello from Coreflux" }
}
```

**Chat message:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "chat_id": "CHAT_ID",
  "body": { "content": "Operator ack" }
}
```

**Webhook Adaptive Card** (`BASE_ADDRESS` = webhook origin):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "webhook_path": "/workflows/.../triggers/manual/paths/invoke?api-version=2016-06-01&sp=...&sv=1.0&sig=...",
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [{ "type": "TextBlock", "text": "Coreflux alarm", "weight": "Bolder" }]
      }
    }
  ]
}
```

## Deploy notes

* Deploy **`MicrosoftTeamsRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/microsoft-teams](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/microsoft-teams)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# MinIO
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/minio

Client-mode REST API connector for MinIO S3-compatible storage: PutObject, GetObject, HeadObject, ListBuckets, and PUT to a presigned URL

Technical Preview

## Overview

A client-mode connector for a **curated IIoT object-storage** slice of the [MinIO S3-compatible API](https://min.io/docs/minio/linux/developers/API.html) under path-style `https://play.min.io` (or your self-hosted host):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| | `GET /` | ListBuckets for the signing identity |
| PUT object (snapshot, CSV rollup) | `PUT /{bucket}/{key}` | SigV4 headers required |
| GET object | `GET /{bucket}/{key}` | SigV4 headers required |
| (optional) HeadObject | `HEAD /{bucket}/{key}` | Metadata without body |
| PUT to presigned URL | `PUT {presigned_path}` | No Authorization; switch BASE to URL origin |
| Bucket notifications → MQTT | — | Docs-only; configure MinIO to publish to Coreflux MQTT; future `ENABLE_SERVER` for HTTP notify |

`BASE_ADDRESS` defaults to `https://play.min.io` (no trailing slash; path-style). For self-hosted MinIO use `https://minio.example.com:9000` (or your TLS origin). Topics use `storage/minio/<object>/<verb>`.

> [!NOTE]
>
> **play.min.io** is MinIO's public playground. Access keys published in MinIO SDK docs are open; treat all play data as world-readable. Prefer self-hosted for production.

> [!NOTE]
>
> **Path-style vs virtual-hosted:** MinIO usually expects path-style (`/{bucket}/{key}`), which this template uses. If virtual-hosted is enabled, set `BASE_ADDRESS` to `https://{bucket}.your-host` and use endpoints like `/{key}`.

> [!NOTE]
>
> **Presigned PUT:** set `BASE_ADDRESS` to the presigned URL origin only, put path+query in `presigned_path`, and omit SigV4 headers — the query string carries the signature. Ideal for edge devices that must not hold access keys.

> [!NOTE]
>
> **Bucket notifications:** MinIO can publish object events directly to MQTT (point at your Coreflux broker). That fan-out is configured on the MinIO side and is not part of this client connector. Receiving HTTP notification POSTs would need a separate `ENABLE_SERVER` REST\_API (not packaged).

> [!NOTE]
>
> **Admin API** (`/minio/admin/…`, `mc admin`) is out of scope for this template — keep ops Admin calls outside the object-storage connector.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — MinIO curated S3-compatible slice
# Auth: SigV4 via {value.json.authorization}, {value.json.x_amz_date},
#       {value.json.x_amz_content_sha256} — or PutPresigned (no Authorization)
# BASE_ADDRESS: https://play.min.io (path-style); swap for self-hosted

DEFINE CONNECTOR MinioRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://play.min.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/octet-stream"
    ADD EVENT Listbuckets
        WITH SOURCE_TOPIC "storage/minio/buckets/list"
        WITH DESTINATION_TOPIC "storage/minio/buckets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Putobject
        WITH SOURCE_TOPIC "storage/minio/object/put"
        WITH DESTINATION_TOPIC "storage/minio/object/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT Getobject
        WITH SOURCE_TOPIC "storage/minio/object/get"
        WITH DESTINATION_TOPIC "storage/minio/object/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Headobject
        WITH SOURCE_TOPIC "storage/minio/object/head"
        WITH DESTINATION_TOPIC "storage/minio/object/head/response"
        WITH METHOD "HEAD"
        WITH ENDPOINT "/{value.json.bucket}/{value.json.key}"
        WITH HEADERS
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT Putpresigned
        WITH SOURCE_TOPIC "storage/minio/object/put-presigned"
        WITH DESTINATION_TOPIC "storage/minio/object/put-presigned/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "{value.json.presigned_path}"
        WITH HEADERS
            ADD "Content-Type" "{value.json.content_type}"
        WITH BODY "{payload}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `MinioRestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://play.min.io` (path-style default; swap for self-hosted) |
| Topic prefix | `storage/minio/...` |
| Default Content-Type | `application/octet-stream` |
| SigV4 region | commonly `us-east-1` (service `s3`) |
| Hub status | Technical preview (`WITH STATUS "beta"`) |

## Authentication

### AWS Signature Version 4

MinIO uses the same SigV4 scheme as S3 — **not** `Authorization: Bearer …`. Sign each request with [SigV4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) (service `s3`) and pass:

| MQTT JSON field | HTTP header |
| - | - |
| `authorization` | `Authorization` (`AWS4-HMAC-SHA256 Credential=…`) |
| `x_amz_date` | `x-amz-date` |
| `x_amz_content_sha256` | `x-amz-content-sha256` |

Use Hub secrets for `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` (or AWS-named equivalents) in an upstream signing helper. Never commit real keys.

### Presigned URLs (recommended for edge)

Generate a time-limited PUT or GET URL with `mc`, the AWS CLI, or a MinIO SDK. For PutPresigned:

1. Point `BASE_ADDRESS` at the URL origin.
2. Put path + query into `presigned_path`.
3. Omit Authorization — do not re-sign on the broker.

## MQTT topics

| Event | Request topic | Response topic |
| - | - | - |
| ListBuckets | `storage/minio/buckets/list` | `…/response` |
| PutObject | `storage/minio/object/put` | `…/response` |
| GetObject | `storage/minio/object/get` | `…/response` |
| HeadObject | `storage/minio/object/head` | `…/response` |
| PutPresigned | `storage/minio/object/put-presigned` | `…/response` |

## Example payloads

**ListBuckets (after signing):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "AWS4-HMAC-SHA256 Credential=AKIA.../20261004/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=...",
  "x_amz_date": "20261004T040000Z",
  "x_amz_content_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
```

**PutObject CSV rollup:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "bucket": "my-iiot-rollups",
  "key": "line-a/2026-10-04/rollup.csv",
  "content_type": "text/csv",
  "authorization": "AWS4-HMAC-SHA256 Credential=...",
  "x_amz_date": "20261004T040100Z",
  "x_amz_content_sha256": "<sha256 of body>",
  "payload": "ts,device,temp\n2026-10-04T04:01:00Z,sensor-01,72.5\n"
}
```

**PutPresigned:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "presigned_path": "/my-iiot-rollups/line-a/snapshot.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
  "content_type": "application/json",
  "payload": "{\"device\":\"sensor-01\",\"temp\":72.5}"
}
```

## References

* [MinIO API](https://min.io/docs/minio/linux/developers/API.html)
* [MinIO Python SDK (play.min.io)](https://docs.min.io/aistor/developers/sdk/python/)
* [MinIO bucket notifications](https://min.io/docs/minio/linux/administration/monitoring/publish-events-to-mqtt.html)
* [Authenticating Requests (SigV4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html)
* [Amazon S3 connector (same surface)](/latest/lot-language/routes/rest-api-apps/amazon-s3)
* [Coreflux REST API Connectors](/latest/lot-language/routes/rest-api-routes)

## Package status


# Mistral AI
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/mistral-ai

LoT connector for the Mistral AI API: chat completions for alarm triage, embeddings, OCR, moderation and model listing from MQTT, with an EU endpoint option

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [Mistral AI API](https://docs.mistral.ai/api), which uses OpenAI-compatible request shapes. Use it for IIoT / edge alarm text, operator notes and scanned shop-floor documents:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST chat/completions | `POST /v1/chat/completions` | Chat Completions (e.g. `mistral-small-latest`); optional `response_format` `json_object` / `json_schema` |
| POST embeddings | `POST /v1/embeddings` | Create embeddings (`mistral-embed`) |
| (supporting) POST fim/completions | `POST /v1/fim/completions` | Fill-in-the-middle code completion (`codestral-latest`) |
| (supporting) POST moderations | `POST /v1/moderations` | Moderate raw text (`mistral-moderation-latest`) |
| (supporting) POST chat/moderations | `POST /v1/chat/moderations` | Moderate a conversation |
| (supporting) POST ocr | `POST /v1/ocr` | Document AI OCR on a PDF / image URL or base64 data URL (`mistral-ocr-latest`) |
| (supporting) GET models | `GET /v1/models` | List models (checks the token) |
| (supporting) GET model | `GET /v1/models/{model_id}` | Retrieve one model |

Default `BASE_ADDRESS` is `https://api.mistral.ai` (no trailing slash). Topics use `ai/mistral-ai/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** `Authorization: Bearer &lt;Mistral API key&gt;`. Prefer Hub secrets (`GET SECRET "MISTRAL_API_KEY"`) mapped into MQTT `api_token`. Never commit real keys.

> [!NOTE]
>
> **Request body:** Mistral rejects unknown fields in request bodies. The connector sends `{value.json.body}` as the JSON body, so publish `{"api_token": "...", "body": { ... }}`. The body has the same shape as the [OpenAI](/latest/lot-language/routes/rest-api-apps/openai) chat and embeddings requests.

## EU data residency

* `api.mistral.ai` is Mistral's **global** endpoint. Mistral does not commit to an inference location for it.
* For inference processed in the EU, set `BASE_ADDRESS` to `https://api.eu.mistral.ai` (data centers in EU and EFTA countries). `https://api.us.mistral.ai` is the US option.
* Regional inference costs 1.1× list price, serves only models hosted in that region and does not offer Agents, Batch or Files. Call `GetModels` on the regional host before you send production traffic.
* Account data such as API keys, billing and usage analytics is not regional. See [Regional inference](https://docs.mistral.ai/inference/regional-inference) and the [Mistral Help Center](https://help.mistral.ai/en/articles/347629-where-do-you-store-my-data-or-my-organization-s-data).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Mistral AI
# Auth: Authorization Bearer {value.json.api_token}
# BASE_ADDRESS: https://api.mistral.ai  (EU inference: https://api.eu.mistral.ai)

DEFINE CONNECTOR MistralAiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.mistral.ai"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostChatCompletions
        WITH SOURCE_TOPIC "ai/mistral-ai/chat/completions/post"
        WITH DESTINATION_TOPIC "ai/mistral-ai/chat/completions/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/chat/completions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT PostEmbeddings
        WITH SOURCE_TOPIC "ai/mistral-ai/embeddings/post"
        WITH DESTINATION_TOPIC "ai/mistral-ai/embeddings/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/embeddings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

## Topics

| Event | Source topic | Destination topic |
| - | - | - |
| PostChatCompletions | `ai/mistral-ai/chat/completions/post` | `…/response` |
| PostEmbeddings | `ai/mistral-ai/embeddings/post` | `…/response` |
| PostFimCompletions | `ai/mistral-ai/fim/completions/post` | `…/response` |
| PostModerations | `ai/mistral-ai/moderations/post` | `…/response` |
| PostChatModerations | `ai/mistral-ai/chat/moderations/post` | `…/response` |
| PostOcr | `ai/mistral-ai/ocr/post` | `…/response` |
| GetModels | `ai/mistral-ai/models/list` | `…/response` |
| GetModel | `ai/mistral-ai/models/get` | `…/response` |

## Example Payloads

Alarm triage on `ai/mistral-ai/chat/completions/post`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_MISTRAL_API_KEY",
  "body": {
    "model": "mistral-small-latest",
    "messages": [
      { "role": "system", "content": "You classify industrial alarms as JSON with severity, category and summary." },
      { "role": "user", "content": "High temperature on press-01" }
    ],
    "response_format": { "type": "json_object" },
    "max_tokens": 200
  }
}
```

Embeddings on `ai/mistral-ai/embeddings/post`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_MISTRAL_API_KEY",
  "body": { "model": "mistral-embed", "input": ["pump vibration alarm"] }
}
```

OCR of a delivery note on `ai/mistral-ai/ocr/post`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_token": "YOUR_MISTRAL_API_KEY",
  "body": {
    "model": "mistral-ocr-latest",
    "document": { "type": "document_url", "document_url": "https://example.com/delivery-note.pdf" },
    "table_format": "markdown"
  }
}
```

Model lookup on `ai/mistral-ai/models/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "api_token": "YOUR_MISTRAL_API_KEY", "model_id": "mistral-small-latest" }
```

## Configuration

1. Set `BASE_ADDRESS` to `https://api.mistral.ai`, or to `https://api.eu.mistral.ai` when inference must stay in the EU.
2. Store a Mistral API key in Hub secrets (`MISTRAL_API_KEY`); map it into MQTT `api_token`.
3. For alarm classification: publish to `ai/mistral-ai/chat/completions/post` with `response_format` `json_object` or `json_schema`.
4. For semantic search / similarity: publish to `ai/mistral-ai/embeddings/post` with `mistral-embed`.
5. For scanned documents or camera snapshots: publish to `ai/mistral-ai/ocr/post` with a `document_url` or an `image_url` data URL.
6. Keep `"stream": false` (the default). Streamed replies are not split into MQTT messages.
7. Use `GetModels` as a cheap credential check before production workloads.

## References

* [Mistral AI API reference](https://docs.mistral.ai/api)
* [Chat Completions](https://docs.mistral.ai/api/endpoint/chat)
* [Embeddings](https://docs.mistral.ai/api/endpoint/embeddings)
* [FIM](https://docs.mistral.ai/api/endpoint/fim)
* [Classifiers (moderation)](https://docs.mistral.ai/api/endpoint/classifiers)
* [OCR](https://docs.mistral.ai/api/endpoint/ocr)
* [Models](https://docs.mistral.ai/api/endpoint/models)
* [Regional inference](https://docs.mistral.ai/inference/regional-inference)
* [Official OpenAPI](https://docs.mistral.ai/openapi.yaml)


# monday.com
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/monday-com

Client-mode REST API connector for monday.com GraphQL API v2: me check, create_item, change_multiple_column_values, items_page query, and create_webhook

Technical Preview

## Overview

A client-mode connector for a **curated work-management** slice of the [monday.com GraphQL API](https://developer.monday.com/api-reference/docs/getting-started) (single `POST /v2` endpoint):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST create\_item | `POST /v2` mutation `create_item` | Create board item from alarm / MQTT |
| POST change\_multiple\_column\_values | `POST /v2` mutation | Update column values (JSON string) |
| POST items\_page | `POST /v2` query `boards { items_page }` | Page / list board items |
| me | `POST /v2` query `me` | Credential check → `data.me.id` |
| POST create\_webhook | `POST /v2` mutation `create_webhook` | Register monday → HTTPS target |

Default `BASE_ADDRESS` is `https://api.monday.com`. Topics use `devops/monday-com/<object>/<verb>`.

> [!NOTE]
>
> Auth is the **raw personal API V2 token** in `Authorization` (**no** `Bearer ` prefix). Prefer Hub secret `MONDAY_API_TOKEN` (aliases `MONDAY_ACCESS_TOKEN`, `MONDAY_TOKEN`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — monday.com GraphQL API v2
# Auth: Authorization {value.json.access_token} (raw token, no Bearer)
# BASE_ADDRESS: https://api.monday.com

DEFINE CONNECTOR MondayComRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.monday.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Me
        WITH SOURCE_TOPIC "devops/monday-com/me/get"
        WITH DESTINATION_TOPIC "devops/monday-com/me/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.access_token}"
            ADD "API-Version" "2024-10"
        WITH BODY "{payload}"
    ADD EVENT Createitem
        WITH SOURCE_TOPIC "devops/monday-com/item/create"
        WITH DESTINATION_TOPIC "devops/monday-com/item/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.access_token}"
            ADD "API-Version" "2024-10"
        WITH BODY "{payload}"
    ADD EVENT Changemultiplecolumnvalues
        WITH SOURCE_TOPIC "devops/monday-com/item/columns"
        WITH DESTINATION_TOPIC "devops/monday-com/item/columns/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.access_token}"
            ADD "API-Version" "2024-10"
        WITH BODY "{payload}"
    ADD EVENT Itemspage
        WITH SOURCE_TOPIC "devops/monday-com/item/page"
        WITH DESTINATION_TOPIC "devops/monday-com/item/page/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.access_token}"
            ADD "API-Version" "2024-10"
        WITH BODY "{payload}"
    ADD EVENT Createwebhook
        WITH SOURCE_TOPIC "devops/monday-com/webhook/create"
        WITH DESTINATION_TOPIC "devops/monday-com/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.access_token}"
            ADD "API-Version" "2024-10"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Me | POST | `/v2` | `devops/monday-com/me/get` | `devops/monday-com/me/get/response` |
| Createitem | POST | `/v2` | `devops/monday-com/item/create` | `devops/monday-com/item/create/response` |
| Changemultiplecolumnvalues | POST | `/v2` | `devops/monday-com/item/columns` | `devops/monday-com/item/columns/response` |
| Itemspage | POST | `/v2` | `devops/monday-com/item/page` | `devops/monday-com/item/page/response` |
| Createwebhook | POST | `/v2` | `devops/monday-com/webhook/create` | `devops/monday-com/webhook/create/response` |

## Authentication

Personal API V2 tokens from monday Developer Center → **API token**. Pass as `Authorization: <token>` with **no** `Bearer ` prefix. Prefer Hub / `GET SECRET "MONDAY_API_TOKEN"`.

Optional `API-Version` header pins the monday API version (template uses `2024-10`).

## Live test

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -sS -X POST https://api.monday.com/v2 \
  -H "Authorization: $MONDAY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "API-Version: 2024-10" \
  -d '{"query":"query { me { id name email } }"}'
```

Expect **HTTP 200** and `data.me.id`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Asana](/latest/lot-language/routes/rest-api-apps/asana)
* [monday.com API — Getting started](https://developer.monday.com/api-reference/docs/getting-started)
* [Authentication](https://developer.monday.com/api-reference/docs/authentication)


# My Dhl Express
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/my-dhl-express

LoT connector for the DHL Express MyDHL API: get rates and landed cost, create shipments and labels, book pickups, track shipments and get proof of delivery

Technical Preview

## Overview

Client-mode REST API connectors for the DHL API Developer Portal: Shipment Tracking Unified (every DHL division) with Tracking Push subscriptions, Location Finder service points, DHL Express MyDHL API (rates, landed cost, shipments and labels, pickups, tracking, proof of delivery, paperless trade uploads) and Post & Parcel Germany (Parcel DE Shipping, Pickup and Returns with OAuth); purchases marked; companion server connector for DHL Tracking Push webhooks.

This is one of the templates in the DHL API Developer Portal REST API app (`dhl-api-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Per product: DhlApi + DhlLocationFinder header DHL-API-Key (developer.dhl.com app key); MyDhlExpress HTTP Basic MyDHL username:password (from DHL Express, not the portal key) + x-version 3.3.3 + Message-Reference; DhlParcelDeAuth OAuth 2.0 password grant (form grant\_type=password, username, password = GKP system user, client\_id = API key, client\_secret = API secret; reply access\_token Bearer, expires\_in 1799, no refresh token); DhlParcelDe Authorization: Bearer only (bearer + dhl-api-key together -> 401). Every event sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: Basic {value.json.basic}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the My Dhl Express connector | no |
| `BaseUrl` | string | My Dhl Express base URL without trailing slash (e.g. [https://express.api.dhl.com](https://express.api.dhl.com)) | yes |

`BASE_ADDRESS` default: `https://express.api.dhl.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ExpressGetRates` | GET | `/mydhlapi/rates?{value.json.query}` | `fleet/dhl/express-rate/get` | `fleet/dhl/express-rate/get/response` | `basic`, `message_ref`, `query` |
| `ExpressGetRatesMultiPiece` | POST | `/mydhlapi/rates` | `fleet/dhl/express-rate-multi/get` | `fleet/dhl/express-rate-multi/get/response` | `basic`, `body`, `message_ref` |
| `ExpressGetProducts` | GET | `/mydhlapi/products?{value.json.query}` | `fleet/dhl/express-product/get` | `fleet/dhl/express-product/get/response` | `basic`, `message_ref`, `query` |
| `ExpressValidateAddress` | GET | `/mydhlapi/address-validate?{value.json.query}` | `fleet/dhl/express-address/validate` | `fleet/dhl/express-address/validate/response` | `basic`, `message_ref`, `query` |
| `ExpressGetLandedCost` | POST | `/mydhlapi/landed-cost` | `fleet/dhl/express-landed-cost/get` | `fleet/dhl/express-landed-cost/get/response` | `basic`, `body`, `message_ref` |
| `ExpressValidateShipment` | POST | `/mydhlapi/shipments?validateDataOnly=true` | `fleet/dhl/express-shipment/validate` | `fleet/dhl/express-shipment/validate/response` | `basic`, `body`, `message_ref` |
| `ExpressCreateShipment` | POST | `/mydhlapi/shipments` | `fleet/dhl/express-shipment/create` | `fleet/dhl/express-shipment/create/response` | `basic`, `body`, `message_ref` |
| `ExpressAddShipmentPiece` | PATCH | `/mydhlapi/shipments/{value.json.id}/add-piece` | `fleet/dhl/express-shipment-piece/create` | `fleet/dhl/express-shipment-piece/create/response` | `basic`, `body`, `id`, `message_ref` |
| `ExpressTrackShipment` | GET | `/mydhlapi/shipments/{value.json.id}/tracking?{value.json.query}` | `fleet/dhl/express-tracking/get` | `fleet/dhl/express-tracking/get/response` | `basic`, `id`, `message_ref`, `query` |
| `ExpressTrackShipments` | GET | `/mydhlapi/tracking?{value.json.query}` | `fleet/dhl/express-tracking-multi/get` | `fleet/dhl/express-tracking-multi/get/response` | `basic`, `message_ref`, `query` |
| `ExpressGetProofOfDelivery` | GET | `/mydhlapi/shipments/{value.json.id}/proof-of-delivery?{value.json.query}` | `fleet/dhl/express-proof-of-delivery/get` | `fleet/dhl/express-proof-of-delivery/get/response` | `basic`, `id`, `message_ref`, `query` |
| `ExpressGetShipmentImage` | GET | `/mydhlapi/shipments/{value.json.id}/get-image?{value.json.query}` | `fleet/dhl/express-shipment-image/get` | `fleet/dhl/express-shipment-image/get/response` | `basic`, `id`, `message_ref`, `query` |
| `ExpressUploadShipmentImage` | PATCH | `/mydhlapi/shipments/{value.json.id}/upload-image` | `fleet/dhl/express-shipment-image/upload` | `fleet/dhl/express-shipment-image/upload/response` | `basic`, `body`, `id` |
| `ExpressUploadShipmentInvoiceData` | PATCH | `/mydhlapi/shipments/{value.json.id}/upload-invoice-data` | `fleet/dhl/express-shipment-invoice/upload` | `fleet/dhl/express-shipment-invoice/upload/response` | `basic`, `body`, `id`, `message_ref` |
| `ExpressUploadInvoiceData` | POST | `/mydhlapi/invoices/upload-invoice-data` | `fleet/dhl/express-invoice/upload` | `fleet/dhl/express-invoice/upload/response` | `basic`, `body`, `message_ref` |
| `ExpressCreatePickup` | POST | `/mydhlapi/pickups` | `fleet/dhl/express-pickup/create` | `fleet/dhl/express-pickup/create/response` | `basic`, `body`, `message_ref` |
| `ExpressUpdatePickup` | PATCH | `/mydhlapi/pickups/{value.json.id}` | `fleet/dhl/express-pickup/update` | `fleet/dhl/express-pickup/update/response` | `basic`, `body`, `id`, `message_ref` |
| `ExpressCancelPickup` | DELETE | `/mydhlapi/pickups/{value.json.id}?{value.json.query}` | `fleet/dhl/express-pickup/cancel` | `fleet/dhl/express-pickup/cancel/response` | `basic`, `id`, `message_ref`, `query` |
| `ExpressAllocateIdentifiers` | GET | `/mydhlapi/identifiers?{value.json.query}` | `fleet/dhl/express-identifier/create` | `fleet/dhl/express-identifier/create/response` | `basic`, `message_ref`, `query` |
| `ExpressFindServicePoints` | GET | `/mydhlapi/servicepoints?{value.json.query}` | `fleet/dhl/express-service-point/search` | `fleet/dhl/express-service-point/search/response` | `basic`, `query` |
| `ExpressGetReferenceData` | GET | `/mydhlapi/reference-data?{value.json.query}` | `fleet/dhl/express-reference-data/get` | `fleet/dhl/express-reference-data/get/response` | `basic`, `message_ref`, `query` |
| `ExpressEarlyShipmentScreening` | POST | `/mydhlapi/early-shipment-screening` | `fleet/dhl/express-screening/create` | `fleet/dhl/express-screening/create/response` | `basic`, `body`, `message_ref` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode MY_DHL_EXPRESS"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MyDhlExpress WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://express.api.dhl.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ExpressGetRates
        WITH SOURCE_TOPIC "fleet/dhl/express-rate/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-rate/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/rates?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressGetRatesMultiPiece
        WITH SOURCE_TOPIC "fleet/dhl/express-rate-multi/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-rate-multi/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mydhlapi/rates"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressGetProducts
        WITH SOURCE_TOPIC "fleet/dhl/express-product/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-product/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/products?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressValidateAddress
        WITH SOURCE_TOPIC "fleet/dhl/express-address/validate"
        WITH DESTINATION_TOPIC "fleet/dhl/express-address/validate/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/address-validate?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressGetLandedCost
        WITH SOURCE_TOPIC "fleet/dhl/express-landed-cost/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-landed-cost/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mydhlapi/landed-cost"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressValidateShipment
        WITH SOURCE_TOPIC "fleet/dhl/express-shipment/validate"
        WITH DESTINATION_TOPIC "fleet/dhl/express-shipment/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mydhlapi/shipments?validateDataOnly=true"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressCreateShipment
        WITH SOURCE_TOPIC "fleet/dhl/express-shipment/create"
        WITH DESTINATION_TOPIC "fleet/dhl/express-shipment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mydhlapi/shipments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressAddShipmentPiece
        WITH SOURCE_TOPIC "fleet/dhl/express-shipment-piece/create"
        WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-piece/create/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/add-piece"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressTrackShipment
        WITH SOURCE_TOPIC "fleet/dhl/express-tracking/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-tracking/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/tracking?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressTrackShipments
        WITH SOURCE_TOPIC "fleet/dhl/express-tracking-multi/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-tracking-multi/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/tracking?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressGetProofOfDelivery
        WITH SOURCE_TOPIC "fleet/dhl/express-proof-of-delivery/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-proof-of-delivery/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/proof-of-delivery?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressGetShipmentImage
        WITH SOURCE_TOPIC "fleet/dhl/express-shipment-image/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-image/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/get-image?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressUploadShipmentImage
        WITH SOURCE_TOPIC "fleet/dhl/express-shipment-image/upload"
        WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-image/upload/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/upload-image"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressUploadShipmentInvoiceData
        WITH SOURCE_TOPIC "fleet/dhl/express-shipment-invoice/upload"
        WITH DESTINATION_TOPIC "fleet/dhl/express-shipment-invoice/upload/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/mydhlapi/shipments/{value.json.id}/upload-invoice-data"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressUploadInvoiceData
        WITH SOURCE_TOPIC "fleet/dhl/express-invoice/upload"
        WITH DESTINATION_TOPIC "fleet/dhl/express-invoice/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mydhlapi/invoices/upload-invoice-data"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressCreatePickup
        WITH SOURCE_TOPIC "fleet/dhl/express-pickup/create"
        WITH DESTINATION_TOPIC "fleet/dhl/express-pickup/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mydhlapi/pickups"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressUpdatePickup
        WITH SOURCE_TOPIC "fleet/dhl/express-pickup/update"
        WITH DESTINATION_TOPIC "fleet/dhl/express-pickup/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/mydhlapi/pickups/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExpressCancelPickup
        WITH SOURCE_TOPIC "fleet/dhl/express-pickup/cancel"
        WITH DESTINATION_TOPIC "fleet/dhl/express-pickup/cancel/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/mydhlapi/pickups/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressAllocateIdentifiers
        WITH SOURCE_TOPIC "fleet/dhl/express-identifier/create"
        WITH DESTINATION_TOPIC "fleet/dhl/express-identifier/create/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/identifiers?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressFindServicePoints
        WITH SOURCE_TOPIC "fleet/dhl/express-service-point/search"
        WITH DESTINATION_TOPIC "fleet/dhl/express-service-point/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/servicepoints?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
    ADD EVENT ExpressGetReferenceData
        WITH SOURCE_TOPIC "fleet/dhl/express-reference-data/get"
        WITH DESTINATION_TOPIC "fleet/dhl/express-reference-data/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/mydhlapi/reference-data?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "x-version" "3.3.3"
            ADD "Message-Reference" "{value.json.message_ref}"
    ADD EVENT ExpressEarlyShipmentScreening
        WITH SOURCE_TOPIC "fleet/dhl/express-screening/create"
        WITH DESTINATION_TOPIC "fleet/dhl/express-screening/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mydhlapi/early-shipment-screening"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Message-Reference" "{value.json.message_ref}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ExpressGetRates` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/dhl/express-rate/get/response' &
mosquitto_pub -t 'fleet/dhl/express-rate/get' -m '{"basic": "<basic>", "message_ref": "<message_ref>", "query": "<query>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# N3uron
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/n3uron

Connect Coreflux LoT to the N3uron REST API Server: read and write tags, browse the model, pull raw or aggregated Historian data, and list or ack alarms

Technical Preview

## Overview

A client-mode connector for the [N3uron REST API Server](https://docs.n3uron.com/docs/rest-api-server-calls) module. Use it to mirror N3uron tags into your MQTT namespace, push setpoints from the broker back into N3uron, pull hourly energy or other aggregates from the N3uron Historian, and surface active alarms on an andon board or shift report.

| Event | Request | Notes |
| - | - | - |
| GetSystemStatus | `GET /system?cmd=status` | Node status: N3uron version, node name, tag counts, errors, host CPU / RAM / disk usage, uptime |
| GetErrorCount | `GET /system?cmd=errorCount` | `0` when healthy; cheap auth check |
| GetRedundancyStatus | `GET /redundancy?cmd=status` | Redundancy mode: enabled, standby, primary / backup |
| ListModuleInstances | `GET /module?cmd=getInstances` | Module instances running on the node (Historian, OpcUaClient, MqttClient, RestApiServer...) |
| GetModuleDetails | `GET /module?cmd=details` | Run state, uptime and memory of the instanced modules |
| ListLinks | `GET /link?cmd=get` | Links to other N3uron nodes (edge to central) and their status |
| BrowseTags | `GET /tag?cmd=browse&path={path}` | Groups and tags under a path (navigate the data model) |
| ReadTags | `GET /tag?cmd=read&path={path}` | Single tag: `{status, data}`; group (`/*`): `{tags: {...}}` |
| ReadTagsFiltered | `GET /tag?cmd=read&path={path}&options.filter={filter}&options.recurrent={recurrent}` | Current values under a group, regex-filtered on the tag path, optionally including subgroups |
| GetTagDetails | `GET /tag?cmd=details&path={path}` | Full tag details: value plus config (type, engineering units, client access, source, history, alarms) |
| GetTagViews | `GET /tag?cmd=getViews` | Tag views defined on the node |
| GetTagHistory | `GET /tag?cmd=history&path={path}&start={start}&end={end}&options.mode={mode}` | Rows `[ts, value, quality, status]`; needs Historian |
| GetTagHistoryAggregated | `GET /tag?cmd=history&path={path}&start={start}&end={end}&options.mode=aggregated&options.method={method}&options.interval={interval}` | `method`: first, last, min, max, avg, delta, stddev |
| GetHistoryMany | `GET /tag?cmd=historyMany&paths={paths}&start={start}&end={end}&options.mode={mode}` | History for several tags in one call (comma-separated paths); response keyed by tag path |
| GetHistoryFiltered | `GET /tag?cmd=historyFilter&path={path}&start={start}&end={end}&options.filter={filter}&options.recurrent={recurrent}&options.mode={mode}` | History for every tag under a group whose path matches a regex |
| ListAlarms | `GET /alarm?cmd=get&path={path}&options.recurrent={recurrent}` | Alarms under a path with priority, status (0 cleared+acked .. 3 active+unacked), value and ack info |
| ListActiveUnackedAlarms | `GET /alarm?cmd=get&path={path}&options.recurrent=true&options.filter.status=3&options.filter.minPriority={minPriority}` | `status=3`, `minPriority` 1 to 4 |
| CountAlarms | `GET /alarm?cmd=count&path={path}&options.recurrent={recurrent}` | Number of alarms under a path |
| GetAlarmHistory | `GET /alarm?cmd=history&path={path}&start={start}&end={end}` | Alarm events of one alarm between start and end |
| WriteTag | `POST /tag?cmd=write` | Body `{"path","value"}`; empty `200` |
| WriteManyTags | `POST /tag?cmd=writeMany` | Body `{"paths": "a,b", "values": [..]}` |
| AckAlarms | `POST /alarm?cmd=ack` | Body `{"paths", "msg"}` |

Set `BASE_ADDRESS` to the N3uron node that runs the RestApiServer module, for example `https://edge01.example.com:3443` (HTTPS, default port 3443). For a plain HTTP lab setup use `http://<host>:3003` and set `USE_SSL "false"`. The API lives at the server root, so there is no `/api` prefix. Topics use `historian/n3uron/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** in N3uron, open the RestApiServer module's **Access** settings. **Token authentication** issues an API key that you send as `Bearer <token>`; **Role authentication** accepts a N3uron user and password as HTTP Basic. Grant `GET` or `GET/POST` per API group (Tag, Alarm, System, Module, Link) and add a tag filter (Include, path `/`, regex `.*`, or narrower); the filter is mandatory. Publish the full header value as `authorization` in every payload, keep it in a Hub secret (suggested name `N3URON_AUTHORIZATION`), and never commit it into the `.lot`. A missing or wrong value returns `401`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR N3uronApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_N3URON_HOST:3443"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Node status: N3uron version, node name, tag counts, errors, host CPU / RAM / disk usage, uptime
    ADD EVENT GetSystemStatus
        WITH SOURCE_TOPIC "historian/n3uron/system/status/get"
        WITH DESTINATION_TOPIC "historian/n3uron/system/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system?cmd=status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Number of configuration errors on the node (0 = healthy); cheap health and auth check
    ADD EVENT GetErrorCount
        WITH SOURCE_TOPIC "historian/n3uron/system/error-count/get"
        WITH DESTINATION_TOPIC "historian/n3uron/system/error-count/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system?cmd=errorCount"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Redundancy mode: enabled, standby, primary / backup
    ADD EVENT GetRedundancyStatus
        WITH SOURCE_TOPIC "historian/n3uron/redundancy/status/get"
        WITH DESTINATION_TOPIC "historian/n3uron/redundancy/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/redundancy?cmd=status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Module instances running on the node (Historian, OpcUaClient, MqttClient, RestApiServer...)
    ADD EVENT ListModuleInstances
        WITH SOURCE_TOPIC "historian/n3uron/modules/instances/get"
        WITH DESTINATION_TOPIC "historian/n3uron/modules/instances/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/module?cmd=getInstances"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Run state, uptime and memory of the instanced modules
    ADD EVENT GetModuleDetails
        WITH SOURCE_TOPIC "historian/n3uron/modules/details/get"
        WITH DESTINATION_TOPIC "historian/n3uron/modules/details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/module?cmd=details"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Links to other N3uron nodes (edge to central) and their status
    ADD EVENT ListLinks
        WITH SOURCE_TOPIC "historian/n3uron/links/get"
        WITH DESTINATION_TOPIC "historian/n3uron/links/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/link?cmd=get"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Groups and tags under a path (navigate the data model)
    ADD EVENT BrowseTags
        WITH SOURCE_TOPIC "historian/n3uron/tags/browse"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/browse/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=browse&path={value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Current value, quality and timestamp of one tag, or every tag in a group (path ends with /*)
    ADD EVENT ReadTags
        WITH SOURCE_TOPIC "historian/n3uron/tags/read"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/read/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=read&path={value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Current values under a group, regex-filtered on the tag path, optionally including subgroups
    ADD EVENT ReadTagsFiltered
        WITH SOURCE_TOPIC "historian/n3uron/tags/read-filtered"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/read-filtered/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=read&path={value.json.path}&options.filter={value.json.filter}&options.recurrent={value.json.recurrent}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Full tag details: value plus config (type, engineering units, client access, source, history, alarms)
    ADD EVENT GetTagDetails
        WITH SOURCE_TOPIC "historian/n3uron/tags/details/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=details&path={value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Tag views defined on the node
    ADD EVENT GetTagViews
        WITH SOURCE_TOPIC "historian/n3uron/tags/views/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/views/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=getViews"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Historian samples for one tag between start and end (ISO or epoch ms); mode raw, filter or delta; rows are [ts, value, quality, status]
    ADD EVENT GetTagHistory
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=history&path={value.json.path}&start={value.json.start}&end={value.json.end}&options.mode={value.json.mode}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Aggregated history (first, last, min, max, avg, delta, stddev) per interval in ms; for example hourly energy
    ADD EVENT GetTagHistoryAggregated
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/aggregated/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/aggregated/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=history&path={value.json.path}&start={value.json.start}&end={value.json.end}&options.mode=aggregated&options.method={value.json.method}&options.interval={value.json.interval}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # History for several tags in one call (comma-separated paths); response keyed by tag path
    ADD EVENT GetHistoryMany
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/many/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/many/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=historyMany&paths={value.json.paths}&start={value.json.start}&end={value.json.end}&options.mode={value.json.mode}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # History for every tag under a group whose path matches a regex
    ADD EVENT GetHistoryFiltered
        WITH SOURCE_TOPIC "historian/n3uron/tag-history/filtered/get"
        WITH DESTINATION_TOPIC "historian/n3uron/tag-history/filtered/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/tag?cmd=historyFilter&path={value.json.path}&start={value.json.start}&end={value.json.end}&options.filter={value.json.filter}&options.recurrent={value.json.recurrent}&options.mode={value.json.mode}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Alarms under a path with priority, status (0 cleared+acked .. 3 active+unacked), value and ack info
    ADD EVENT ListAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=get&path={value.json.path}&options.recurrent={value.json.recurrent}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Active and unacknowledged alarms at or above a priority (1 low .. 4 critical), for andon or shift handover
    ADD EVENT ListActiveUnackedAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/active-unacked/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/active-unacked/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=get&path={value.json.path}&options.recurrent=true&options.filter.status=3&options.filter.minPriority={value.json.minPriority}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Number of alarms under a path
    ADD EVENT CountAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/count/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/count/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=count&path={value.json.path}&options.recurrent={value.json.recurrent}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Alarm events of one alarm between start and end
    ADD EVENT GetAlarmHistory
        WITH SOURCE_TOPIC "historian/n3uron/alarm-history/get"
        WITH DESTINATION_TOPIC "historian/n3uron/alarm-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/alarm?cmd=history&path={value.json.path}&start={value.json.start}&end={value.json.end}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # WRITE: Write one tag value (type must match the tag: number, boolean or string); empty 200 on success
    ADD EVENT WriteTag
        WITH SOURCE_TOPIC "historian/n3uron/tag/write"
        WITH DESTINATION_TOPIC "historian/n3uron/tag/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tag?cmd=write"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    # WRITE: Write several tags in one call (comma-separated paths, values array in the same order)
    ADD EVENT WriteManyTags
        WITH SOURCE_TOPIC "historian/n3uron/tags/write-many"
        WITH DESTINATION_TOPIC "historian/n3uron/tags/write-many/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tag?cmd=writeMany"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    # WRITE: Acknowledge one or more alarms (paths: single, comma-separated or JSON array) with an optional message
    ADD EVENT AckAlarms
        WITH SOURCE_TOPIC "historian/n3uron/alarms/ack"
        WITH DESTINATION_TOPIC "historian/n3uron/alarms/ack/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/alarm?cmd=ack"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
```

## Payloads

GET parameters go into the URL as they are, so URL-encode tag paths or filters that contain spaces or special characters. `start` and `end` take an ISO string or a Unix epoch timestamp in milliseconds. POST events send the payload field `request` unchanged as the JSON body; a successful write or acknowledgement returns an empty `200`, and errors return `400` with a plain-text reason such as `Tag not found: /X`.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <token>", "path": "/LINE1/PRESS01/*"}
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <token>", "request": {"path": "/LINE1/PRESS01/SETPOINT", "value": 555}}
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <token>", "path": "/LINE1/METER01/ACTIVE_ENERGY", "start": "2026-10-05T00:00:00.000Z", "end": "2026-10-06T00:00:00.000Z", "method": "delta", "interval": "3600000"}
```

## Example actions

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION N3uronHealthPoll
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    PUBLISH TOPIC "historian/n3uron/system/error-count/get" WITH { "authorization": {auth} }

DEFINE ACTION N3uronReadPressTags
ON EVERY 10 SECONDS DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    PUBLISH TOPIC "historian/n3uron/tags/read" WITH { "authorization": {auth}, "path": "/LINE1/PRESS01/*" }

DEFINE ACTION N3uronSetpointFromUns
ON TOPIC "porto/line1/press01/setpoint/set" DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    SET "sp" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "historian/n3uron/tag/write" WITH { "authorization": {auth}, "request": { "path": "/LINE1/PRESS01/SETPOINT", "value": {sp} } }

DEFINE ACTION N3uronShiftAlarms
ON EVERY 1 HOUR DO
    SET "auth" WITH GET SECRET "N3URON_AUTHORIZATION"
    PUBLISH TOPIC "historian/n3uron/alarms/active-unacked/get" WITH { "authorization": {auth}, "path": "/LINE1/", "minPriority": "3" }
```

## Limits and notes

* History and alarm history need a Historian module and history enabled on the tag or alarm; otherwise N3uron answers `400` (`Historization disabled for the target tag`).
* Configuration, restart, backup, license, certificate and subscription calls are left out on purpose. Manage those from the N3uron WebUI.
* Writes must match the tag type (number, boolean or string) and the tag must allow client writes (`clientAccess` `RW`).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)


# Oracle NetSuite (SuiteTalk REST)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/netsuite

Client-mode REST API connector for a curated NetSuite SuiteTalk slice: inventoryItem, inventoryadjustment, workOrder, workOrderCompletion transform, and SuiteQL

Technical Preview

## Overview

A client-mode connector for a **curated inventory and manufacturing** slice of [NetSuite SuiteTalk REST Web Services](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_1559132836.html) under `/services/rest` (record/v1 + query/v1):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET inventoryItem | `record/v1/inventoryItem/{id}` | Inventory item by internal ID (`expandSubResources=true`) |
| POST inventoryAdjustment | `record/v1/inventoryadjustment` | Official record ID is lowercase `inventoryadjustment` |
| GET workOrder | `record/v1/workOrder/{id}` | Work order by internal ID |
| POST workOrderCompletion | `record/v1/workOrder/{id}/!transform/workOrderCompletion` | Official create path is a WIP transform (not a bare POST collection) |
| POST suiteql query | `query/v1/suiteql` | Requires header `Prefer: transient` |

`BASE_ADDRESS` is the SuiteTalk REST root (`https://{account}.suitetalk.api.netsuite.com/services/rest`). Topics use `erp/netsuite/<object>/<verb>`.

> [!NOTE]
>
> NetSuite REST APIs require a real account ID and an OAuth 2.0 Bearer token (or TBA). Prefer Hub secrets for tokens. Pull per-record OpenAPI with `GET .../record/v1/metadata-catalog/{recordType}` and `Accept: application/swagger+json`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Oracle NetSuite SuiteTalk REST (curated inventory / work order / SuiteQL slice)
# Auth: Bearer {value.json.access_token} (OAuth 2.0 M2M or auth code)
# BASE_ADDRESS: https://YOUR_ACCOUNT.suitetalk.api.netsuite.com/services/rest

DEFINE CONNECTOR NetSuiteRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ACCOUNT.suitetalk.api.netsuite.com/services/rest"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getinventoryitem
        WITH SOURCE_TOPIC "erp/netsuite/inventory-item/get"
        WITH DESTINATION_TOPIC "erp/netsuite/inventory-item/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/record/v1/inventoryItem/{value.json.id}?expandSubResources=true"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createinventoryadjustment
        WITH SOURCE_TOPIC "erp/netsuite/inventory-adjustment/create"
        WITH DESTINATION_TOPIC "erp/netsuite/inventory-adjustment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/record/v1/inventoryadjustment"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getworkorder
        WITH SOURCE_TOPIC "erp/netsuite/work-order/get"
        WITH DESTINATION_TOPIC "erp/netsuite/work-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/record/v1/workOrder/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createworkordercompletion
        WITH SOURCE_TOPIC "erp/netsuite/work-order-completion/create"
        WITH DESTINATION_TOPIC "erp/netsuite/work-order-completion/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/record/v1/workOrder/{value.json.id}/!transform/workOrderCompletion"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Executesuiteql
        WITH SOURCE_TOPIC "erp/netsuite/suiteql/query"
        WITH DESTINATION_TOPIC "erp/netsuite/suiteql/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/query/v1/suiteql?limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Prefer" "transient"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getinventoryitem | GET | `/record/v1/inventoryItem/{id}` | `erp/netsuite/inventory-item/get` | `erp/netsuite/inventory-item/get/response` |
| Createinventoryadjustment | POST | `/record/v1/inventoryadjustment` | `erp/netsuite/inventory-adjustment/create` | `erp/netsuite/inventory-adjustment/create/response` |
| Getworkorder | GET | `/record/v1/workOrder/{id}` | `erp/netsuite/work-order/get` | `erp/netsuite/work-order/get/response` |
| Createworkordercompletion | POST | `/record/v1/workOrder/{id}/!transform/workOrderCompletion` | `erp/netsuite/work-order-completion/create` | `erp/netsuite/work-order-completion/create/response` |
| Executesuiteql | POST | `/query/v1/suiteql` | `erp/netsuite/suiteql/query` | `erp/netsuite/suiteql/query/response` |

## Auth

**Option A — OAuth 2.0 Bearer (default in the template):**

Pass the access token on the MQTT request payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_NETSUITE_ACCESS_TOKEN", "id": "20"}
```

The connector sends `Authorization: Bearer {value.json.access_token}`. Obtain the token via OAuth 2.0 client credentials (M2M) or authorization code against `https://{account}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token`.

**Option B — Token-Based Auth (OAuth 1.0a):**

Supported by NetSuite REST Web Services but not modeled in this client-mode header set. Use a broker-side TBA signer or an upstream action if you need TBA.

Prefer Hub secrets / `GET SECRET`. Never commit real credentials.

## Example MQTT payloads

**GET inventory item**

Topic: `erp/netsuite/inventory-item/get`

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_TOKEN", "id": "20"}
```

**POST inventory adjustment**

Topic: `erp/netsuite/inventory-adjustment/create`

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_TOKEN",
  "account": {"id": "1"},
  "adjLocation": {"id": "1"},
  "subsidiary": {"id": "1"},
  "inventory": {
    "items": [
      {
        "adjustQtyBy": 5.0,
        "item": {"id": "20"},
        "line": 1,
        "location": {"id": "1"}
      }
    ]
  }
}
```

**GET work order**

Topic: `erp/netsuite/work-order/get`

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_TOKEN", "id": "4"}
```

**POST work order completion (transform)**

Topic: `erp/netsuite/work-order-completion/create`

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_TOKEN",
  "id": "4",
  "startOperation": {"refName": "10"},
  "endOperation": {"refName": "20"}
}
```

**POST SuiteQL**

Topic: `erp/netsuite/suiteql/query`

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_TOKEN",
  "limit": 10,
  "offset": 0,
  "q": "SELECT id, itemid FROM item WHERE itemtype = 'InvtPart' FETCH FIRST 10 ROWS ONLY"
}
```

The SuiteQL event already sends `Prefer: transient`. Body should include at least `{"q": "..."}` (optional `params` for bound parameters).

## Deploy notes

1. Replace `YOUR_ACCOUNT` in `BASE_ADDRESS`.
2. Deploy only `NetSuiteRestApi.lot` with `-addConnector` (no `ADD METADATA` in that file).
3. Use `hub-metadata.lot` + `icon.png` for Hub template listing (`WITH STATUS "beta"`).

## References

* [NetSuite REST Web Services](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/book_1559132836.html)
* [Inventory Item](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_161522936052.html)
* [Inventory Adjustment](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_0817101055.html)
* [Work Order](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_47212826771.html)
* [Work Order Completion](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_94213635853.html)
* [Executing SuiteQL Queries Through REST Web Services](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157909186990.html)
* [OAuth 2.0 Authorization Header Examples](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_158332610742.html)


# New Relic
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/new-relic

LoT connector for New Relic: send metrics, events and logs from MQTT, run NRQL queries through NerdGraph and list applications, with an alert webhook option

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of the [New Relic APIs](https://docs.newrelic.com/docs/apis/intro-apis/introduction-new-relic-apis/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST metric payload | `POST /metric/v1` | **Host:** `https://metric-api.newrelic.com` — Metric API; license `Api-Key`; expect **202** |
| POST events | `POST /v1/accounts/events` | **Host:** `https://insights-collector.newrelic.com` — Event API; license `Api-Key`; expect **200** |
| POST logs (source\_hint) | `POST /log/v1` | **Host:** `https://log-api.newrelic.com` — Log API; license `Api-Key`; expect **202** |
| POST NRQL via NerdGraph | `POST /graphql` | **Host:** `https://api.newrelic.com` — user `Api-Key`; GraphQL body with NRQL |
| GET applications | `GET /v2/applications.json` | Same API host — REST API v2; user `Api-Key` |
| Alert webhook (inbound) | ENABLE\_SERVER companion | Not a client event — configure Alerts webhook → broker HTTP/MQTT |

Default `BASE_ADDRESS` is `https://metric-api.newrelic.com` (US Metric API). Topics use `itsm/new-relic/<object>/<verb>`.

> [!NOTE]
>
> Metric, Event, Log, and NerdGraph/REST use **different hosts**. Switch connector `BASE_ADDRESS` (or deploy copies) before calling non-Metric events. EU accounts use `metric-api.eu.newrelic.com`, `insights-collector.eu01.nr-data.net`, `log-api.eu.newrelic.com`, `api.eu.newrelic.com`.

> [!NOTE]
>
> Prefer Hub secrets for license and user API keys.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — New Relic (Metric/Event/Log + NerdGraph + REST v2)
# Auth: Api-Key={value.json.api_key} (license for ingest; user key for NerdGraph/REST)
# BASE_ADDRESS Metric: https://metric-api.newrelic.com
# Event: set BASE to https://insights-collector.newrelic.com
# Log: set BASE to https://log-api.newrelic.com
# NerdGraph/REST: set BASE to https://api.newrelic.com

DEFINE CONNECTOR NewRelicRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://metric-api.newrelic.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Submitmetrics
        WITH SOURCE_TOPIC "itsm/new-relic/metric/submit"
        WITH DESTINATION_TOPIC "itsm/new-relic/metric/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/metric/v1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Api-Key" "{value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Submitevents
        WITH SOURCE_TOPIC "itsm/new-relic/event/submit"
        WITH DESTINATION_TOPIC "itsm/new-relic/event/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/accounts/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Api-Key" "{value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Submitlogs
        WITH SOURCE_TOPIC "itsm/new-relic/log/submit"
        WITH DESTINATION_TOPIC "itsm/new-relic/log/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/log/v1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Api-Key" "{value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Nerdgraphnrql
        WITH SOURCE_TOPIC "itsm/new-relic/nerdgraph/nrql"
        WITH DESTINATION_TOPIC "itsm/new-relic/nerdgraph/nrql/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Api-Key" "{value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Listapplications
        WITH SOURCE_TOPIC "itsm/new-relic/application/list"
        WITH DESTINATION_TOPIC "itsm/new-relic/application/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/applications.json?filter[name]={value.json.filter_name}&page={value.json.page}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Api-Key" "{value.json.api_key}"
```

## Authentication

| Surface | Header | Key type |
| - | - | - |
| Metric / Event / Log | `Api-Key: {value.json.api_key}` | License / ingest key |
| NerdGraph / REST v2 | `Api-Key: {value.json.api_key}` | User API key |

Store keys in Hub secrets (`NEW_RELIC_LICENSE_KEY`, `NEW_RELIC_USER_KEY`) and resolve via `GET SECRET` — never commit credentials.

## MQTT examples

**Metrics** (BASE = Metric API host) — publish a JSON **array** of metric batches as the payload body the connector forwards:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "metrics": [
      {
        "name": "coreflux.plant.vibration_rms",
        "type": "gauge",
        "value": 12.4,
        "timestamp": 1728000000000,
        "attributes": {"line": "a", "source": "coreflux"}
      }
    ]
  }
]
```

Include `api_key` in the MQTT JSON envelope if the connector substitutes `{value.json.api_key}` from the same message. Expect **HTTP 202**.

**Events** (BASE = insights-collector) — JSON array of events with required `eventType`. Expect **HTTP 200**.

**NerdGraph NRQL** (BASE = `https://api.newrelic.com`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_USER_KEY",
  "query": "{ actor { account(id: YOUR_ACCOUNT_ID) { nrql(query: \"SELECT count(*) FROM Transaction SINCE 1 hour ago\") { results } } } }"
}
```

## Alert webhook (companion)

Configure a New Relic Alerts [webhook notification](https://docs.newrelic.com/docs/alerts/get-notified/notification-integrations/#webhook) to POST to a Coreflux broker HTTP endpoint. That inbound path belongs in a separate `ENABLE_SERVER` `TYPE REST_API` connector (or MQTT bridge) — not in this client template.

## Live test status

## Official references

* [Metric API](https://docs.newrelic.com/docs/data-apis/ingest-apis/metric-api/report-metrics-metric-api/)
* [Event API](https://docs.newrelic.com/docs/data-apis/ingest-apis/event-api/introduction-event-api/)
* [Log API](https://docs.newrelic.com/docs/logs/log-api/introduction-log-api/)
* [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/)
* [REST API v2](https://docs.newrelic.com/docs/apis/rest-api-v2/get-started/introduction-new-relic-rest-api-v2/)
* [Alerts webhook](https://docs.newrelic.com/docs/alerts/get-notified/notification-integrations/#webhook)


# Nextcloud
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/nextcloud

Connect Coreflux LoT to self-hosted Nextcloud: upload shift reports as files via WebDAV, download configs, share files, send notifications and Talk messages

Technical Preview

## Overview

Client-mode connector for a self-hosted [Nextcloud](https://nextcloud.com) server that moves plant files and messages between the broker and Nextcloud. A typical flow writes a shift report, batch record or alarm snapshot as a JSON or CSV file into a plant folder (the folder is created on the fly), writes today's setpoint table over yesterday's while Nextcloud keeps the old one as a version, reads a recipe back when a line changes over, comments on a batch record when QA releases it, shares a weekly report with a public link that expires, and sends an alarm to the maintenance team as a Nextcloud notification or a message in a Talk conversation. New files can be picked up from the activity stream or with a webhook listener that calls the broker.

The template file `NextcloudRestApi.lot` holds one connector, `NextcloudRestApi`, with 43 events (29 GET, 9 POST, 5 PUT; 13 writes, no delete). Files go through WebDAV (`/remote.php/dav/files/...`), everything else through the OCS API (`/ocs/v2.php/...`) of the server and its apps: provisioning, sharing, notifications, activity, user status, calendar (dav), Talk (spreed) and webhook listeners. Topics use `storage/nextcloud/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. Point the connector at your server: replace `BASE_ADDRESS` (`https://nextcloud.example.com` in the template) with your Nextcloud address, including the web root if Nextcloud does not run at the domain root (for example `https://cloud.example.com` or `https://example.com/nextcloud`), without a trailing slash. Keep this value as `NEXTCLOUD_BASE_URL` in your deployment notes. For plain HTTP on a plant LAN use `http://...` and set `USE_SSL "false"`. The host name must be in the server's `trusted_domains`.
2. Create a dedicated account for the broker, for example `plant-bot`, and give it a storage quota. Share the plant folders with it, or let it own them.
3. Log in as that account and create an app password under **Personal settings > Security > Devices & sessions > Create new app password**. Use the app password, never the login password: accounts with two-factor authentication refuse login passwords, and you can revoke an app password on its own.
4. Admin-only events (`UsersList`, `GroupsList`, `GroupUsersList`, `AdminNotificationSend` and the webhook events) need an app password of an administrator. Group sub-admins can list the users and groups they manage. Webhook listeners can also be delegated to a group through the **Webhooks** admin privilege.
5. Talk events need the **Talk** app, webhook events the **Webhook listeners** app (Nextcloud 30 and later, shipped but check that it is enabled), and activity events the **Activity** app.
6. Keep `NEXTCLOUD_USER`, `NEXTCLOUD_APP_PASSWORD` and the derived `NEXTCLOUD_BASIC_AUTH` (see below) in broker secrets and inject them with `GET SECRET`.

## Authentication

Every event except `StatusGet` sends `Authorization: Basic <credentials>`, built from the `basic_auth` field of the payload. `basic_auth` is the Base64 of `<NEXTCLOUD_USER>:<NEXTCLOUD_APP_PASSWORD>`, for example `plant-bot:Ab12C-dE34f-...`. Store that value as the secret `NEXTCLOUD_BASIC_AUTH`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "BASE64_OF_USER_COLON_APP_PASSWORD"}
```

OCS events also send `OCS-APIRequest: true` (without it Nextcloud answers `412 CSRF check failed`) and ask for JSON with `?format=json`. OCS answers in an envelope: the result is in `ocs.data`, the status in `ocs.meta`.

As an alternative, the connector can carry the credentials itself with `WITH USERNAME` and `WITH PASSWORD` in `REST_API_CONFIG`. In that case, remove the `Authorization` header lines from the events.

> [!WARNING]
>
> `basic_auth` grants full access to the account's files. Never retain topics that carry it, restrict `storage/nextcloud/#` with ACLs, and give the broker its own account instead of a personal one. Nextcloud's brute-force protection slows down and then blocks (`429`) the broker's IP address after repeated wrong passwords, also for correct requests. Fix the secret first, then reset the block with `occ security:bruteforce:reset <ip>`.

## Payloads

| Field | Used by | Content |
| - | - | - |
| `basic_auth` | every event except `StatusGet` | Base64 of `user:app-password` |
| `user` | `FileUpload`, `FileVersionUpload`, `FileDownload` | Nextcloud user id in the WebDAV path, usually the broker account |
| `path` | `FileUpload`, `FileVersionUpload`, `FileDownload` | File path below the user's root, URL-encoded per segment (a space is `%20`), no leading slash, for example `Plant/Line2/2026-10-05-shift-A.json` |
| `content` | `FileUpload`, `FileVersionUpload` | File content as a string (JSON text, CSV, plain text) |
| `user_id`, `group_id`, `share_id`, `notification_id`, `file_id`, `provider_id`, `filter`, `room_token`, `webhook_id` | events with that id in the path | Ids as strings. `file_id` is the numeric file id, `room_token` the Talk conversation token (4 to 30 lowercase letters and digits). |
| `query` | events whose endpoint ends with `&{value.json.query}` | URL query string without `?`, for example `search=operator&limit=50`, or `""` |
| `body` | POST and PUT OCS events, `FileCommentCreate` | JSON request body |

Send `query` as an empty string when you need no parameters; the request then ends with `&`, which Nextcloud ignores.

## Uploading files

`FileUpload` writes a new file with WebDAV `PUT`. It sends `If-None-Match: *`, so an existing file is never overwritten: Nextcloud answers `412 Precondition Failed` instead. It also sends `X-NC-WebDAV-Auto-Mkcol: 1`, so Nextcloud 32 and later create missing parent folders. Older servers answer `404` or `409` when the folder does not exist yet; create it by hand once.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "user": "plant-bot", "path": "Plant/Line2/2026-10-05-shift-A.json", "content": "{\"line\":\"2\",\"shift\":\"A\",\"oee\":0.87,\"scrap\":14,\"operator\":\"Jo\u00e3o\"}"}
```

Nextcloud answers `201 Created` with an empty body. The new file id is in the `OC-FileId` response header (`00000091oc...`: the number before the instance suffix is the file id). Use `Search` (provider `files`) or `ActivityList` to find file ids later.

`FileVersionUpload` writes a file whether it exists or not (`201` for a new file, `204` when it replaced one). With the Versions app, the previous content stays in the file's version history, so writing today's setpoint table over yesterday's keeps yesterday's as a version. `FileDownload` returns the raw file content. Keep files to text, CSV or JSON that fits an MQTT message.

Build the payload in a LoT action:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION NextcloudShiftReportUpload
ON TOPIC "plant/line2/shift/report" DO
    SET "auth" WITH GET SECRET "NEXTCLOUD_BASIC_AUTH"
    SET "user" WITH GET SECRET "NEXTCLOUD_USER"
    SET "path" WITH GET JSON "path" IN PAYLOAD AS STRING
    SET "content" WITH GET JSON "content" IN PAYLOAD AS STRING
    PUBLISH TOPIC "storage/nextcloud/files/upload" WITH { "basic_auth": {auth}, "user": {user}, "path": {path}, "content": {content} }
```

## Examples

Health check without credentials (`storage/nextcloud/status/get`), for example from a timer:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{}
```

The answer carries `installed`, `maintenance`, `needsDbUpgrade` and `versionstring`.

Read a recipe back on changeover (`storage/nextcloud/files/download`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "user": "plant-bot", "path": "Plant/Line2/recipes/PX-200.json"}
```

List the sub-folders of the plant folder (`storage/nextcloud/folders/tree/get`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "query": "path=/Plant&depth=2"}
```

Find files by name (`storage/nextcloud/search/query`); each entry carries the path in `subline` and the file id in `attributes.fileId`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "provider_id": "files", "query": "term=shift-A&limit=20"}
```

Share a shift report with a public, read-only link that expires (`storage/nextcloud/shares/create`); the answer carries `url`, `token` and `id`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "body": {"path": "/Plant/Line2/2026-10-05-shift-A.json", "shareType": 3, "permissions": 1, "expireDate": "2026-10-31", "label": "Shift A report"}}
```

`shareType` is `0` for a user, `1` for a group, `3` for a public link and `4` for email; `permissions` adds up `1` read, `2` update, `4` create, `8` delete and `16` share. End a link early with `ShareUpdate` and an `expireDate` of today instead of deleting it.

Comment on a batch record when QA releases it (`storage/nextcloud/files/comments/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "file_id": "91", "body": {"actorType": "users", "verb": "comment", "message": "Batch 1005-A released by QA", "objectType": "files"}}
```

Send an alarm to a user's Nextcloud notifications, which also reach the desktop and mobile apps (`storage/nextcloud/notifications/admin/send`, admin only):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "user_id": "operator1", "body": {"subject": "Line 2: spindle temperature high", "message": "TT-201 92 C (limit 85 C) at 14:05"}}
```

Post an alarm into a Talk conversation (`storage/nextcloud/talk/messages/send`). Create the conversation once with `TalkRoomCreate` (`{"roomType": 2, "roomName": "Line 2 alarms"}`), add people with `TalkParticipantAdd`, and keep its `token`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "room_token": "abcd1234", "body": {"message": "Line 2: TT-201 92 C (limit 85 C)", "silent": false}}
```

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION NextcloudAlarmToTalk
ON TOPIC "plant/line2/alarms" DO
    SET "auth" WITH GET SECRET "NEXTCLOUD_BASIC_AUTH"
    SET "text" WITH GET JSON "text" IN PAYLOAD AS STRING
    PUBLISH TOPIC "storage/nextcloud/talk/messages/send" WITH { "basic_auth": {auth}, "room_token": "abcd1234", "body": { "message": {text} } }
```

Show that a line account is busy (`storage/nextcloud/user-status/set`, then `storage/nextcloud/user-status/message/set`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "body": {"statusType": "dnd"}}
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "body": {"message": "Line 2 in maintenance until 16:00", "clearAt": null}}
```

Pick up new files without a public endpoint by polling the activity stream (`storage/nextcloud/activity/list`): ask for `filter` `files` with `query` `since=<last activity_id>&sort=asc&limit=50`, store the `X-Activity-Last-Given` id (or the last `activity_id`), and treat `304` as nothing new. Use `filter` `filter` with `object_type=files&object_id=<id>` for the history of one file.

Or let Nextcloud call the broker when a file is created in the plant folder (`storage/nextcloud/webhooks/create`, admin only). The `uri` is a broker REST\_API server connector that Nextcloud can reach; `authData` sets a header the receiver checks:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"basic_auth": "<NEXTCLOUD_BASIC_AUTH>", "body": {"httpMethod": "POST", "uri": "https://broker.example.com/nextcloud/webhooks", "event": "OCP\\Files\\Events\\Node\\NodeCreatedEvent", "eventFilter": {"event.node.path": "/^\\/plant-bot\\/files\\/Plant\\//"}, "authMethod": "header", "authData": {"X-Webhook-Token": "<secret>"}}}
```

Nextcloud sends webhooks from background jobs, so deliveries depend on its cron and can lag behind.

## Events

| Event | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - |
| `StatusGet` | `GET` | `/status.php` | `storage/nextcloud/status/get` | | Smoke and health check without credentials: installed, maintenance, needsDbUpgrade, version, productname. Send `{}` (no basic\_auth needed). |
| `CapabilitiesGet` | `GET` | `/ocs/v2.php/cloud/capabilities?format=json` | `storage/nextcloud/capabilities/get` | | Server version and what the instance supports (files versioning, sharing defaults and enforced expiry, notifications, user\_status, spreed/Talk features, webhook\_listeners). Works without login too; with basic\_auth it adds user-specific capabilities. |
| `UserMe` | `GET` | `/ocs/v2.php/cloud/user?format=json` | `storage/nextcloud/users/me/get` | | Smoke: the user behind the app password (id, display-name, email, groups, quota.used / quota.free / quota.relative, language). |
| `UsersList` | `GET` | `/ocs/v2.php/cloud/users?format=json&{value.json.query}` | `storage/nextcloud/users/list` | | User ids (admin or group sub-admin only). query e.g. search=operator\&limit=50\&offset=0 (or empty). |
| `UserGet` | `GET` | `/ocs/v2.php/cloud/users/{value.json.user_id}?format=json` | `storage/nextcloud/users/get` | | One user: display name, email, groups, enabled, last login and quota (watch the storage quota of a plant account). Admins see everyone, users only themselves. |
| `GroupsList` | `GET` | `/ocs/v2.php/cloud/groups?format=json&{value.json.query}` | `storage/nextcloud/groups/list` | | Group ids (admin or sub-admin). query e.g. search=line\&limit=50 (or empty). |
| `GroupUsersList` | `GET` | `/ocs/v2.php/cloud/groups/{value.json.group_id}/users?format=json` | `storage/nextcloud/groups/users/list` | | Members of a group, e.g. who is on the line-2 maintenance team (admin or sub-admin of that group). |
| `FileUpload` | `PUT` | `/remote.php/dav/files/{value.json.user}/{value.json.path}` | `storage/nextcloud/files/upload` | Yes | Catalog 'PUT file via WebDAV'. Create a new file (JSON / CSV / text shift report, batch record, alarm snapshot) from an MQTT payload. Sends If-None-Match: \* so an existing file is never overwritten (412 Precondition Failed instead) and X-NC-WebDAV-Auto-Mkcol: 1 so missing parent folders are created (Nextcloud 32+; older servers answer 404/409 if the folder is missing). path is relative to the user's root, URL-encoded per segment, no leading slash. 201 Created, file id in the OC-FileId response header, empty body. |
| `FileVersionUpload` | `PUT` | `/remote.php/dav/files/{value.json.user}/{value.json.path}` | `storage/nextcloud/files/versions/upload` | Yes | Write a file whether or not it exists (e.g. today's setpoint table over yesterday's). With the Versions app the previous content stays in the file's version history. Also creates missing parent folders (X-NC-WebDAV-Auto-Mkcol: 1). 201 if new, 204 if replaced. |
| `FileDownload` | `GET` | `/remote.php/dav/files/{value.json.user}/{value.json.path}` | `storage/nextcloud/files/download` | | Read a file back (recipe, config, setpoint table) on changeover. Returns the raw content; keep to text / JSON that fits an MQTT message. 404 if missing. |
| `FolderTreeGet` | `GET` | `/ocs/v2.php/apps/files/api/v1/folder-tree?format=json&{value.json.query}` | `storage/nextcloud/folders/tree/get` | | Sub-folders of a folder (id, basename, children) without WebDAV PROPFIND. query e.g. path=/Plant\&depth=2 (folders only; list files with Search provider files or with Activity). |
| `FileDirectLinkCreate` | `POST` | `/ocs/v2.php/apps/dav/api/v1/direct?format=json` | `storage/nextcloud/files/direct-link/create` | | Temporary direct download URL for a file id (no login needed to fetch it), e.g. to hand a report to an HMI or a printer. body: `{"fileId":91,"expirationTime":3600}` (seconds; server default 8 hours, max 24 hours). Creates no content (read-only POST). Treat the returned URL as a secret. |
| `FileCommentCreate` | `POST` | `/remote.php/dav/comments/files/{value.json.file_id}` | `storage/nextcloud/files/comments/create` | Yes | Comment on a file (e.g. 'Batch 1005-A released by QA', shown in the file's Activity / Comments sidebar). file\_id is the numeric file id (OC-FileId without the instance suffix, or fileId from Search / Activity). body: `{"actorType":"users","verb":"comment","message":"...","objectType":"files"}`. 201, comment URL in Content-Location. |
| `SearchProvidersList` | `GET` | `/ocs/v2.php/search/providers?format=json` | `storage/nextcloud/search/providers/list` | | Unified search providers on this instance (files, talk-message, comments, calendar, ...). |
| `Search` | `GET` | `/ocs/v2.php/search/providers/{value.json.provider_id}/search?format=json&{value.json.query}` | `storage/nextcloud/search/query` | | Unified search in one provider, e.g. provider\_id files with query term=shift-A\&limit=20 (entries carry title, subline (path), resourceUrl and attributes.fileId); talk-message or comments work the same. Page with cursor=`<cursor>`. |
| `SharesList` | `GET` | `/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json&{value.json.query}` | `storage/nextcloud/shares/list` | | Shares created by the user. query e.g. path=/Plant/Line2/2026-10-05-shift-A.json\&reshares=true, or subfiles=true\&path=/Plant (or empty). |
| `ShareGet` | `GET` | `/ocs/v2.php/apps/files_sharing/api/v1/shares/{value.json.share_id}?format=json` | `storage/nextcloud/shares/get` | | One share (url, token, permissions, expiration, share\_with). |
| `ShareCreate` | `POST` | `/ocs/v2.php/apps/files_sharing/api/v1/shares?format=json` | `storage/nextcloud/shares/create` | Yes | Catalog 'POST OCS share link'. Share a file or folder. Public link: `{"path":"/Plant/Line2/2026-10-05-shift-A.json","shareType":3,"permissions":1,"expireDate":"2026-10-31","label":"Shift A report"}` (shareType 3 = public link, 0 = user, 1 = group, 4 = email; permissions 1 read, 2 update, 4 create, 8 delete, 16 share, 31 all; add password for protected links). The response carries url and token. |
| `ShareUpdate` | `PUT` | `/ocs/v2.php/apps/files_sharing/api/v1/shares/{value.json.share_id}?format=json` | `storage/nextcloud/shares/update` | Yes | Change a share: permissions, password, expireDate (end a link early instead of deleting it), note, label. body e.g. `{"expireDate":"2026-10-07","note":"Superseded by shift B"}`. |
| `SharesPendingList` | `GET` | `/ocs/v2.php/apps/files_sharing/api/v1/shares/pending?format=json` | `storage/nextcloud/shares/pending/list` | | Shares offered to the user that are not accepted yet. |
| `ShareesSearch` | `GET` | `/ocs/v2.php/apps/files_sharing/api/v1/sharees?format=json&{value.json.query}` | `storage/nextcloud/sharees/search` | | Find users, groups or emails to share with. query e.g. search=operator\&itemType=file\&perPage=20. |
| `NotificationsList` | `GET` | `/ocs/v2.php/apps/notifications/api/v2/notifications?format=json` | `storage/nextcloud/notifications/list` | | The user's notifications (share offers, mentions, admin notifications, app updates). 204 when there are none. |
| `NotificationGet` | `GET` | `/ocs/v2.php/apps/notifications/api/v2/notifications/{value.json.notification_id}?format=json` | `storage/nextcloud/notifications/get` | | One notification by id. |
| `AdminNotificationSend` | `POST` | `/ocs/v2.php/apps/notifications/api/v3/admin_notifications/{value.json.user_id}?format=json` | `storage/nextcloud/notifications/admin/send` | Yes | Push an alarm or shift note to a user's Nextcloud notifications (web, desktop and mobile apps). Admin app password only. body: `{"subject":"Line 2: spindle temperature high","message":"TT-201 92 C (limit 85 C) at 14:05"}` (subject up to 255, message up to 4000 characters). v3 API; older servers use v2 with shortMessage / longMessage. |
| `ActivityList` | `GET` | `/ocs/v2.php/apps/activity/api/v2/activity/{value.json.filter}?format=json&{value.json.query}` | `storage/nextcloud/activity/list` | | Activity stream (file created / changed / shared / commented) to pick up new files without a public endpoint. filter all, self, by, files, files\_sharing, files\_favorites or filter (one object: query object\_type=files\&object\_id=91). query e.g. since=`<last activity_id>`\&limit=50\&sort=asc. 304 when nothing is new; the X-Activity-Last-Given header holds the id to continue from. |
| `ActivityFiltersList` | `GET` | `/ocs/v2.php/apps/activity/api/v2/activity/filters?format=json` | `storage/nextcloud/activity/filters/list` | | Available activity filters (id, name, priority). |
| `UserStatusGet` | `GET` | `/ocs/v2.php/apps/user_status/api/v1/user_status?format=json` | `storage/nextcloud/user-status/get` | | Own status (status online / away / dnd / invisible / offline, message, icon, clearAt). |
| `UserStatusSet` | `PUT` | `/ocs/v2.php/apps/user_status/api/v1/user_status/status?format=json` | `storage/nextcloud/user-status/set` | Yes | Set the account's status, e.g. a line or kiosk account goes dnd while the machine runs a batch. body: `{"statusType":"dnd"}` (online, away, dnd, invisible, offline). |
| `UserStatusMessageSet` | `PUT` | `/ocs/v2.php/apps/user_status/api/v1/user_status/message/custom?format=json` | `storage/nextcloud/user-status/message/set` | Yes | Set a custom status message, e.g. `{"statusIcon":"<one emoji>","message":"Line 2 in maintenance until 16:00","clearAt":1791298800}` (clearAt Unix seconds, or null). |
| `UserStatusesList` | `GET` | `/ocs/v2.php/apps/user_status/api/v1/statuses?format=json&{value.json.query}` | `storage/nextcloud/user-status/list` | | Statuses of all users who set one (who is online on shift). query e.g. limit=100\&offset=0 (or empty). |
| `UserStatusOfUserGet` | `GET` | `/ocs/v2.php/apps/user_status/api/v1/statuses/{value.json.user_id}?format=json` | `storage/nextcloud/user-status/user/get` | | Status of one user (404 if the user never set one). |
| `UpcomingEventsList` | `GET` | `/ocs/v2.php/apps/dav/api/v1/events/upcoming?format=json&{value.json.query}` | `storage/nextcloud/calendar/upcoming/list` | | Upcoming events of the user's calendars (planned maintenance, shift changes, audits). query e.g. location=Line%202 (or empty). |
| `TalkRoomsList` | `GET` | `/ocs/v2.php/apps/spreed/api/v4/room?format=json&{value.json.query}` | `storage/nextcloud/talk/rooms/list` | | Talk conversations of the user (token, name, type, unreadMessages, lastActivity). query e.g. noStatusUpdate=1\&includeLastMessage=false (or empty). Needs the Talk app. |
| `TalkRoomGet` | `GET` | `/ocs/v2.php/apps/spreed/api/v4/room/{value.json.room_token}?format=json` | `storage/nextcloud/talk/rooms/get` | | One conversation by token. |
| `TalkRoomCreate` | `POST` | `/ocs/v2.php/apps/spreed/api/v4/room?format=json` | `storage/nextcloud/talk/rooms/create` | Yes | Create a conversation, e.g. one per line for alarms. body: `{"roomType":2,"roomName":"Line 2 alarms"}` (2 = group, 3 = public; 1 = one-to-one with invite). Returns the room token. |
| `TalkParticipantAdd` | `POST` | `/ocs/v2.php/apps/spreed/api/v4/room/{value.json.room_token}/participants?format=json` | `storage/nextcloud/talk/participants/add` | Yes | Add a user, group or team to a conversation (moderator rights needed). body: `{"newParticipant":"operator1","source":"users"}` (source users, groups, circles, emails, ...). |
| `TalkParticipantsList` | `GET` | `/ocs/v2.php/apps/spreed/api/v4/room/{value.json.room_token}/participants?format=json` | `storage/nextcloud/talk/participants/list` | | Participants of a conversation (actorId, displayName, participantType, inCall). |
| `TalkMessageSend` | `POST` | `/ocs/v2.php/apps/spreed/api/v1/chat/{value.json.room_token}?format=json` | `storage/nextcloud/talk/messages/send` | Yes | Catalog 'POST Talk message'. Post an alarm or shift note into a conversation. body: `{"message":"Line 2: TT-201 92 C (limit 85 C)","referenceId":"<sha256 hex of your alarm id, 64 chars>","silent":false}` (message up to 32000 characters; Markdown; referenceId lets you find the message again). 201 with the message. |
| `TalkMessagesList` | `GET` | `/ocs/v2.php/apps/spreed/api/v1/chat/{value.json.room_token}?format=json&lookIntoFuture=0&{value.json.query}` | `storage/nextcloud/talk/messages/list` | | Recent messages of a conversation (e.g. acknowledgements typed by operators). lookIntoFuture=0 is fixed (history, no long poll). query e.g. limit=20\&setReadMarker=0\&markNotificationsAsRead=0 (or empty); page back with lastKnownMessageId=`<id>`. |
| `WebhooksList` | `GET` | `/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks?format=json` | `storage/nextcloud/webhooks/list` | | Registered webhook listeners (admin; Nextcloud 30+ with webhook\_listeners enabled). |
| `WebhookGet` | `GET` | `/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks/{value.json.webhook_id}?format=json` | `storage/nextcloud/webhooks/get` | | One webhook listener by id. |
| `WebhookCreate` | `POST` | `/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks?format=json` | `storage/nextcloud/webhooks/create` | Yes | Have Nextcloud call a broker REST\_API server connector when files change. Admin only. body: `{"httpMethod":"POST","uri":"https://broker.example.com/nextcloud/webhooks","event":"OCP\Files\Events\Node\NodeCreatedEvent","eventFilter":{"event.node.path":"/^\/plant-bot\/files\/Plant\//"},"authMethod":"header","authData":{"X-Webhook-Token":"<secret>"}}`. Deliveries run from background jobs (cron). |
| `WebhookUpdate` | `POST` | `/ocs/v2.php/apps/webhook_listeners/api/v1/webhooks/{value.json.webhook_id}?format=json` | `storage/nextcloud/webhooks/update` | Yes | Replace a webhook listener (same body as WebhookCreate; httpMethod, uri and event are required), e.g. listen to NodeWrittenEvent too or point it at a new broker. |

## Limits

* WebDAV `PUT` has no size limit of its own, but the web server and PHP limits apply (`upload_max_filesize`, `post_max_size`, proxy body size). Keep MQTT payloads small. Larger files need chunked uploads, which are not packaged.
* `X-NC-WebDAV-Auto-Mkcol` needs Nextcloud 32 or later. Admin notifications use the v3 API: `subject` up to 255 characters, `message` up to 4000. Talk messages are limited to 32000 characters.
* Nextcloud's brute-force protection delays and then blocks (`429`) an IP address after repeated failed logins. In the local test it blocked the client after 11 wrong passwords.
* Shares can have an enforced maximum expiry and password policy (see `CapabilitiesGet`, `files_sharing`). A share that breaks the policy answers `400` or `403`.
* `FolderTreeGet` lists folders only, and `Search` only matches names. File listings with sizes and dates need WebDAV `PROPFIND`, which is not a REST\_API method.

## Not packaged

* Delete events on purpose: files, folders, shares, notifications, Talk conversations and participants, status messages and webhook listeners.
* WebDAV methods that REST\_API does not offer (it supports `GET`, `POST`, `PUT`, `DELETE` and `PATCH`): `PROPFIND` (folder listing and file properties), `MKCOL` (create folder; `FileUpload` creates parents instead), `MOVE` and `COPY` (rename, archive, copy), `PROPPATCH` (favorites, tags), `REPORT` and `SEARCH` (filtered listings, comment lists), and the `MOVE`-based trash and version restore.
* Chunked uploads (v2) and bulk upload, public share (`/public.php`) uploads, folder downloads as ZIP or TAR, previews and thumbnails.
* User and group administration (create, edit, disable, wipe), app passwords and login flow, app config, Talk calls, polls, bots and breakout rooms, calendar and contacts writes (CalDAV and CardDAV), Deck, Forms and Tables.
* The webhook receiver. A receiver would be a separate `ENABLE_SERVER` REST\_API connector that checks the `authData` header.


# Node Red Admin
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/node-red-admin

LoT connector for the Node-RED Admin API: read and deploy flows, start or stop flows, read or delete context, and install or manage node modules from MQTT

Technical Preview

## Overview

Client-mode REST API connectors for Node-RED and FlowFuse: read and deploy Node-RED flows through the Admin API, start and stop flows, read context, manage node modules, send MQTT data to your own HTTP In endpoints, and manage FlowFuse teams, applications, hosted instances, snapshots and devices from MQTT.

This is one of the templates in the Node-RED (Admin API, HTTP In nodes) and FlowFuse REST API app (`node-red-and-flowfuse`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Auth headers used by the template: `Authorization: Bearer {value.json.token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Node Red Admin connector | no |
| `BaseUrl` | string | Node Red Admin base URL without trailing slash (e.g. http\://YOUR\_NODE\_RED\_HOST:1880) | yes |

`BASE_ADDRESS` default: `http://YOUR_NODE_RED_HOST:1880`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetAuthScheme` | GET | `/auth/login` | `historian/node-red/auth-scheme/get` | `historian/node-red/auth-scheme/get/response` | none |
| `CreateToken` | POST | `/auth/token` | `historian/node-red/token/create` | `historian/node-red/token/create/response` | `body` |
| `RevokeToken` | POST | `/auth/revoke` | `historian/node-red/token/delete` | `historian/node-red/token/delete/response` | `body`, `token` |
| `GetSettings` | GET | `/settings` | `historian/node-red/settings/get` | `historian/node-red/settings/get/response` | `token` |
| `GetDiagnostics` | GET | `/diagnostics` | `historian/node-red/diagnostics/get` | `historian/node-red/diagnostics/get/response` | `token` |
| `GetFlows` | GET | `/flows` | `historian/node-red/flows/get` | `historian/node-red/flows/get/response` | `token` |
| `DeployFlows` | POST | `/flows` | `historian/node-red/flows/deploy` | `historian/node-red/flows/deploy/response` | `body`, `deploymentType`, `token` |
| `ReloadFlows` | POST | `/flows` | `historian/node-red/flows/reload` | `historian/node-red/flows/reload/response` | `token` |
| `GetFlowsState` | GET | `/flows/state` | `historian/node-red/flows-state/get` | `historian/node-red/flows-state/get/response` | `token` |
| `SetFlowsState` | POST | `/flows/state` | `historian/node-red/flows-state/update` | `historian/node-red/flows-state/update/response` | `body`, `token` |
| `AddFlow` | POST | `/flow` | `historian/node-red/flow/create` | `historian/node-red/flow/create/response` | `body`, `token` |
| `GetFlow` | GET | `/flow/{value.json.id}` | `historian/node-red/flow/get` | `historian/node-red/flow/get/response` | `id`, `token` |
| `UpdateFlow` | PUT | `/flow/{value.json.id}` | `historian/node-red/flow/update` | `historian/node-red/flow/update/response` | `body`, `id`, `token` |
| `DeleteFlow` | DELETE | `/flow/{value.json.id}` | `historian/node-red/flow/delete` | `historian/node-red/flow/delete/response` | `id`, `token` |
| `ListNodes` | GET | `/nodes` | `historian/node-red/node/list` | `historian/node-red/node/list/response` | `token` |
| `GetNodeModule` | GET | `/nodes/{value.json.module}` | `historian/node-red/node-module/get` | `historian/node-red/node-module/get/response` | `module`, `token` |
| `InstallNodeModule` | POST | `/nodes` | `historian/node-red/node-module/create` | `historian/node-red/node-module/create/response` | `body`, `token` |
| `SetNodeModuleState` | PUT | `/nodes/{value.json.module}` | `historian/node-red/node-module/update` | `historian/node-red/node-module/update/response` | `body`, `module`, `token` |
| `RemoveNodeModule` | DELETE | `/nodes/{value.json.module}` | `historian/node-red/node-module/delete` | `historian/node-red/node-module/delete/response` | `module`, `token` |
| `GetContext` | GET | `/context/{value.json.path}` | `historian/node-red/context/get` | `historian/node-red/context/get/response` | `path`, `token` |
| `DeleteContext` | DELETE | `/context/{value.json.path}` | `historian/node-red/context/delete` | `historian/node-red/context/delete/response` | `path`, `token` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode NODE_RED_ADMIN"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR NodeRedAdmin WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_NODE_RED_HOST:1880"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetAuthScheme
        WITH SOURCE_TOPIC "historian/node-red/auth-scheme/get"
        WITH DESTINATION_TOPIC "historian/node-red/auth-scheme/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/auth/login"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT CreateToken
        WITH SOURCE_TOPIC "historian/node-red/token/create"
        WITH DESTINATION_TOPIC "historian/node-red/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/auth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RevokeToken
        WITH SOURCE_TOPIC "historian/node-red/token/delete"
        WITH DESTINATION_TOPIC "historian/node-red/token/delete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/auth/revoke"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetSettings
        WITH SOURCE_TOPIC "historian/node-red/settings/get"
        WITH DESTINATION_TOPIC "historian/node-red/settings/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/settings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetDiagnostics
        WITH SOURCE_TOPIC "historian/node-red/diagnostics/get"
        WITH DESTINATION_TOPIC "historian/node-red/diagnostics/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/diagnostics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetFlows
        WITH SOURCE_TOPIC "historian/node-red/flows/get"
        WITH DESTINATION_TOPIC "historian/node-red/flows/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/flows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "Node-RED-API-Version" "v2"
    ADD EVENT DeployFlows
        WITH SOURCE_TOPIC "historian/node-red/flows/deploy"
        WITH DESTINATION_TOPIC "historian/node-red/flows/deploy/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/flows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "Node-RED-API-Version" "v2"
            ADD "Node-RED-Deployment-Type" "{value.json.deploymentType}"
        WITH BODY "{value.json.body}"
    ADD EVENT ReloadFlows
        WITH SOURCE_TOPIC "historian/node-red/flows/reload"
        WITH DESTINATION_TOPIC "historian/node-red/flows/reload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/flows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "Node-RED-API-Version" "v2"
            ADD "Node-RED-Deployment-Type" "reload"
        WITH BODY "{}"
    ADD EVENT GetFlowsState
        WITH SOURCE_TOPIC "historian/node-red/flows-state/get"
        WITH DESTINATION_TOPIC "historian/node-red/flows-state/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/flows/state"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT SetFlowsState
        WITH SOURCE_TOPIC "historian/node-red/flows-state/update"
        WITH DESTINATION_TOPIC "historian/node-red/flows-state/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/flows/state"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT AddFlow
        WITH SOURCE_TOPIC "historian/node-red/flow/create"
        WITH DESTINATION_TOPIC "historian/node-red/flow/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/flow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetFlow
        WITH SOURCE_TOPIC "historian/node-red/flow/get"
        WITH DESTINATION_TOPIC "historian/node-red/flow/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/flow/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT UpdateFlow
        WITH SOURCE_TOPIC "historian/node-red/flow/update"
        WITH DESTINATION_TOPIC "historian/node-red/flow/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/flow/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteFlow
        WITH SOURCE_TOPIC "historian/node-red/flow/delete"
        WITH DESTINATION_TOPIC "historian/node-red/flow/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/flow/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ListNodes
        WITH SOURCE_TOPIC "historian/node-red/node/list"
        WITH DESTINATION_TOPIC "historian/node-red/node/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/nodes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetNodeModule
        WITH SOURCE_TOPIC "historian/node-red/node-module/get"
        WITH DESTINATION_TOPIC "historian/node-red/node-module/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/nodes/{value.json.module}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT InstallNodeModule
        WITH SOURCE_TOPIC "historian/node-red/node-module/create"
        WITH DESTINATION_TOPIC "historian/node-red/node-module/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/nodes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT SetNodeModuleState
        WITH SOURCE_TOPIC "historian/node-red/node-module/update"
        WITH DESTINATION_TOPIC "historian/node-red/node-module/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/nodes/{value.json.module}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT RemoveNodeModule
        WITH SOURCE_TOPIC "historian/node-red/node-module/delete"
        WITH DESTINATION_TOPIC "historian/node-red/node-module/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/nodes/{value.json.module}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetContext
        WITH SOURCE_TOPIC "historian/node-red/context/get"
        WITH DESTINATION_TOPIC "historian/node-red/context/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/context/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT DeleteContext
        WITH SOURCE_TOPIC "historian/node-red/context/delete"
        WITH DESTINATION_TOPIC "historian/node-red/context/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/context/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetAuthScheme` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/node-red/auth-scheme/get/response' &
mosquitto_pub -t 'historian/node-red/auth-scheme/get' -m '{}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Node Red Http In
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/node-red-http-in

LoT connector for Node-RED HTTP In endpoints: send MQTT data as GET, POST, PUT and DELETE requests to your flows, with optional Bearer or Basic auth

Technical Preview

## Overview

Client-mode REST API connectors for Node-RED and FlowFuse: read and deploy Node-RED flows through the Admin API, start and stop flows, read context, manage node modules, send MQTT data to your own HTTP In endpoints, and manage FlowFuse teams, applications, hosted instances, snapshots and devices from MQTT.

This is one of the templates in the Node-RED (Admin API, HTTP In nodes) and FlowFuse REST API app (`node-red-and-flowfuse`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Auth headers used by the template: `Authorization: Basic {value.json.basic}`, `Authorization: Bearer {value.json.token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Node Red Http In connector | no |
| `BaseUrl` | string | Node Red Http In base URL without trailing slash (e.g. http\://YOUR\_NODE\_RED\_HOST:1880) | yes |

`BASE_ADDRESS` default: `http://YOUR_NODE_RED_HOST:1880`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `HttpInPost` | POST | `/{value.json.path}` | `historian/node-red-http/endpoint/post` | `historian/node-red-http/endpoint/post/response` | `body`, `path` |
| `HttpInGet` | GET | `/{value.json.path}` | `historian/node-red-http/endpoint/get` | `historian/node-red-http/endpoint/get/response` | `path` |
| `HttpInPut` | PUT | `/{value.json.path}` | `historian/node-red-http/endpoint/put` | `historian/node-red-http/endpoint/put/response` | `body`, `path` |
| `HttpInPostBearer` | POST | `/{value.json.path}` | `historian/node-red-http/secure-endpoint/post` | `historian/node-red-http/secure-endpoint/post/response` | `body`, `path`, `token` |
| `HttpInGetBearer` | GET | `/{value.json.path}` | `historian/node-red-http/secure-endpoint/get` | `historian/node-red-http/secure-endpoint/get/response` | `path`, `token` |
| `HttpInPostBasic` | POST | `/{value.json.path}` | `historian/node-red-http/basic-endpoint/post` | `historian/node-red-http/basic-endpoint/post/response` | `basic`, `body`, `path` |
| `HttpInGetBasic` | GET | `/{value.json.path}` | `historian/node-red-http/basic-endpoint/get` | `historian/node-red-http/basic-endpoint/get/response` | `basic`, `path` |
| `HttpInDelete` | DELETE | `/{value.json.path}` | `historian/node-red-http/endpoint/delete` | `historian/node-red-http/endpoint/delete/response` | `path` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode NODE_RED_HTTP_IN"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR NodeRedHttpIn WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_NODE_RED_HOST:1880"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT HttpInPost
        WITH SOURCE_TOPIC "historian/node-red-http/endpoint/post"
        WITH DESTINATION_TOPIC "historian/node-red-http/endpoint/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT HttpInGet
        WITH SOURCE_TOPIC "historian/node-red-http/endpoint/get"
        WITH DESTINATION_TOPIC "historian/node-red-http/endpoint/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT HttpInPut
        WITH SOURCE_TOPIC "historian/node-red-http/endpoint/put"
        WITH DESTINATION_TOPIC "historian/node-red-http/endpoint/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT HttpInPostBearer
        WITH SOURCE_TOPIC "historian/node-red-http/secure-endpoint/post"
        WITH DESTINATION_TOPIC "historian/node-red-http/secure-endpoint/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{value.json.body}"
    ADD EVENT HttpInGetBearer
        WITH SOURCE_TOPIC "historian/node-red-http/secure-endpoint/get"
        WITH DESTINATION_TOPIC "historian/node-red-http/secure-endpoint/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT HttpInPostBasic
        WITH SOURCE_TOPIC "historian/node-red-http/basic-endpoint/post"
        WITH DESTINATION_TOPIC "historian/node-red-http/basic-endpoint/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic}"
        WITH BODY "{value.json.body}"
    ADD EVENT HttpInGetBasic
        WITH SOURCE_TOPIC "historian/node-red-http/basic-endpoint/get"
        WITH DESTINATION_TOPIC "historian/node-red-http/basic-endpoint/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic}"
    ADD EVENT HttpInDelete
        WITH SOURCE_TOPIC "historian/node-red-http/endpoint/delete"
        WITH DESTINATION_TOPIC "historian/node-red-http/endpoint/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `HttpInPost` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/node-red-http/endpoint/post/response' &
mosquitto_pub -t 'historian/node-red-http/endpoint/post' -m '{"body": {}, "path": "<path>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Notion
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/notion

Client-mode REST API connector for a curated Notion slice: create/update pages, query databases, users/me check, retrieve database, and search

Technical Preview

## Overview

A client-mode connector for a **curated work-management / documentation** slice of the [Notion REST API](https://developers.notion.com/reference/intro):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST pages | `POST /v1/pages` | Create page / database row (device log) |
| PATCH pages/\{id} | `PATCH /v1/pages/{page_id}` | Update page properties |
| POST databases/\{id}/query | `POST /v1/databases/{database_id}/query` | Query / filter / sort rows |
| GET users/me | `GET /v1/users/me` | Credential check → `id` |
| GET databases/\{id} | `GET /v1/databases/{database_id}` | Retrieve database |
| POST search | `POST /v1/search` | Search shared pages/databases |

Default `BASE_ADDRESS` is `https://api.notion.com`. Topics use `devops/notion/<object>/<verb>`.

Every request must include **`Notion-Version: 2022-06-28`**. This template pins that version so catalog `POST /v1/databases/{id}/query` remains valid; Notion deprecates that path under API versions `2025-09-03` and later (databases → data sources).

> [!NOTE]
>
> Auth is **Bearer** integration secret, OAuth 2.0 access token, or PAT (`Authorization: Bearer …`). Prefer Hub secret `NOTION_API_TOKEN` (aliases `NOTION_TOKEN`, `NOTION_INTEGRATION_TOKEN`, `NOTION_ACCESS_TOKEN`). Share target databases/pages with the integration or Notion returns HTTP 404.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Notion REST API
# Auth: Bearer {value.json.access_token}
# BASE_ADDRESS: https://api.notion.com
# Notion-Version: 2022-06-28

DEFINE CONNECTOR NotionRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.notion.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuserme
        WITH SOURCE_TOPIC "devops/notion/user/me"
        WITH DESTINATION_TOPIC "devops/notion/user/me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
    ADD EVENT Createpage
        WITH SOURCE_TOPIC "devops/notion/page/create"
        WITH DESTINATION_TOPIC "devops/notion/page/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/pages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
    ADD EVENT Updatepage
        WITH SOURCE_TOPIC "devops/notion/page/update"
        WITH DESTINATION_TOPIC "devops/notion/page/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/v1/pages/{value.json.page_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
    ADD EVENT Querydatabase
        WITH SOURCE_TOPIC "devops/notion/database/query"
        WITH DESTINATION_TOPIC "devops/notion/database/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/databases/{value.json.database_id}/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
    ADD EVENT Getdatabase
        WITH SOURCE_TOPIC "devops/notion/database/get"
        WITH DESTINATION_TOPIC "devops/notion/database/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/databases/{value.json.database_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
    ADD EVENT Search
        WITH SOURCE_TOPIC "devops/notion/search"
        WITH DESTINATION_TOPIC "devops/notion/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/search"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Notion-Version" "2022-06-28"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuserme | GET | `/v1/users/me` | `devops/notion/user/me` | `devops/notion/user/me/response` |
| Createpage | POST | `/v1/pages` | `devops/notion/page/create` | `devops/notion/page/create/response` |
| Updatepage | PATCH | `/v1/pages/{page_id}` | `devops/notion/page/update` | `devops/notion/page/update/response` |
| Querydatabase | POST | `/v1/databases/{database_id}/query` | `devops/notion/database/query` | `devops/notion/database/query/response` |
| Getdatabase | GET | `/v1/databases/{database_id}` | `devops/notion/database/get` | `devops/notion/database/get/response` |
| Search | POST | `/v1/search` | `devops/notion/search` | `devops/notion/search/response` |

## Auth

1. Create an [internal integration](https://www.notion.so/my-integrations) (or use OAuth / PAT) and copy the secret.
2. Set connector `BASE_ADDRESS` to `https://api.notion.com`.
3. Pass `access_token` on MQTT JSON payloads so the Bearer header resolves. For path params, also pass `page_id` / `database_id`.
4. Store secrets in Hub / `GET SECRET "NOTION_API_TOKEN"` (aliases `NOTION_TOKEN`, `NOTION_INTEGRATION_TOKEN`, `NOTION_ACCESS_TOKEN`). Never commit real credentials.
5. Share databases/pages with the connection via Notion **Add connections**.
6. A successful check: `GET /v1/users/me` with `Notion-Version: 2022-06-28` → **HTTP 200** with `id`. Invalid tokens → **HTTP 401**.

## Example payloads

**getUserMe:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_NOTION_API_TOKEN"
}
```

**createPage (device-log row):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "parent": { "database_id": "YOUR_DATABASE_ID" },
  "properties": {
    "Name": {
      "title": [{ "text": { "content": "Coreflux alarm — Zone A" } }]
    }
  }
}
```

**updatePage:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "page_id": "YOUR_PAGE_ID",
  "properties": {
    "Status": { "select": { "name": "Acknowledged" } }
  }
}
```

**queryDatabase:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "database_id": "YOUR_DATABASE_ID",
  "page_size": 10
}
```

## Deploy notes

* Deploy `NotionRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/notion](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/notion)

## Sources

* [Notion API introduction](https://developers.notion.com/reference/intro)
* [Create a page](https://developers.notion.com/reference/create-a-page)
* [Update page](https://developers.notion.com/reference/patch-page)
* [Query a database](https://developers.notion.com/reference/post-database-query)
* [Retrieve a database](https://developers.notion.com/reference/retrieve-a-database)
* [Retrieve your token's bot user](https://developers.notion.com/reference/get-self)
* [Search](https://developers.notion.com/reference/post-search)
* [Versioning](https://developers.notion.com/reference/versioning)


# ntfy
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ntfy

Client-mode REST API connector for ntfy: publish plain-text or JSON notifications with Priority/Tags/Actions, poll cached JSON, and health

Technical Preview

## Overview

A client-mode connector for a **curated publish/subscribe** slice of [ntfy](https://docs.ntfy.sh/):

| Catalog connector event | Entity / path | Notes | |
| - | - | - | - |
| PUT / POST `{topic}` | \`PUT | POST /\` | Plain-text body; `Title`, `Priority`, `Tags` headers |
| POST with action buttons | `POST /` JSON or `Actions` header | `http` actions can callback a Coreflux REST server connector | |
| GET `{topic}/json` | `GET /{topic}/json?poll=1` | Poll cached messages (not a long-lived stream in this package) | |
| GET health | `GET /v1/health` | Public; no auth | |

Default `BASE_ADDRESS` is `https://ntfy.sh` (replace with your self-hosted origin). Topics use `messaging/ntfy/<object>/<verb>`.

> [!NOTE]
>
> Public **ntfy.sh** topics allow **anonymous** publish/subscribe. Self-hosted servers may enforce ACLs with Bearer tokens or Basic auth — pass `Authorization` via `{value.json.token}` / `{value.json.basic_b64}` placeholders and Hub secrets. Prefer hard-to-guess topic names; treat the topic as a shared secret on public hosts.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — ntfy
# Auth: none on public topics; optional Bearer {value.json.token} for ACLs
# BASE_ADDRESS: https://ntfy.sh

DEFINE CONNECTOR NtfyRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://ntfy.sh"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "text/plain"
    ADD EVENT Publishmessage
        WITH SOURCE_TOPIC "messaging/ntfy/message/publish"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/publish/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.topic}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain"
            ADD "Title" "{value.json.title}"
            ADD "Priority" "{value.json.priority}"
            ADD "Tags" "{value.json.tags}"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Publishwithheaders
        WITH SOURCE_TOPIC "messaging/ntfy/message/publish-headers"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/publish-headers/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.topic}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain"
            ADD "Title" "{value.json.title}"
            ADD "Priority" "{value.json.priority}"
            ADD "Tags" "{value.json.tags}"
            ADD "Actions" "{value.json.actions}"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Publishjson
        WITH SOURCE_TOPIC "messaging/ntfy/message/publish-json"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/publish-json/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Getcached
        WITH SOURCE_TOPIC "messaging/ntfy/message/get-cached"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/get-cached/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.topic}/json?poll=1&since={value.json.since}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Getlatest
        WITH SOURCE_TOPIC "messaging/ntfy/message/get-latest"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/get-latest/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.topic}/json?poll=1&since=latest"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Health
        WITH SOURCE_TOPIC "messaging/ntfy/health/get"
        WITH DESTINATION_TOPIC "messaging/ntfy/health/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/health"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Publishmessage | PUT | `/{topic}` | `messaging/ntfy/message/publish` | `messaging/ntfy/message/publish/response` |
| Publishwithheaders | POST | `/{topic}` | `messaging/ntfy/message/publish-headers` | `messaging/ntfy/message/publish-headers/response` |
| Publishjson | POST | `/` | `messaging/ntfy/message/publish-json` | `messaging/ntfy/message/publish-json/response` |
| Getcached | GET | `/{topic}/json?poll=1&since=` | `messaging/ntfy/message/get-cached` | `messaging/ntfy/message/get-cached/response` |
| Getlatest | GET | `/{topic}/json?poll=1&since=latest` | `messaging/ntfy/message/get-latest` | `messaging/ntfy/message/get-latest/response` |
| Health | GET | `/v1/health` | `messaging/ntfy/health/get` | `messaging/ntfy/health/get/response` |

## Auth

1. For **public ntfy.sh** topics: no credentials. Pick a hard-to-guess topic (`[-_A-Za-z0-9]`, ≤64 chars).
2. Set connector `BASE_ADDRESS` to `https://ntfy.sh` or your self-hosted URL.
3. For **self-hosted ACLs**, pass `token` (Bearer) or `basic_b64` on the MQTT payload; store secrets with Hub / `GET SECRET "NTFY_TOKEN"`.
4. Successful publish returns **HTTP 200** with a JSON message object. Health returns **HTTP 200** and `{"healthy":true}`.

## Example payloads

**PublishMessage** (path/header placeholders on MQTT JSON; HTTP body is plain text via `{payload}`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "topic": "coreflux-alerts-lab",
  "title": "Zone A vibration",
  "priority": "high",
  "tags": "warning,rotating_light",
  "token": ""
}
```

HTTP body example: `Coreflux alarm: vibration above threshold — Zone A`

**PublishJson** (full JSON body including actions that HTTP-callback a Coreflux REST server):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "topic": "coreflux-alerts-lab",
  "message": "Garage door open > 15 min. Close it?",
  "title": "Facility alert",
  "priority": 4,
  "tags": ["warning", "door"],
  "actions": [
    {
      "action": "http",
      "label": "Ack in Coreflux",
      "url": "https://your-coreflux-rest.example/routes/ack",
      "method": "POST",
      "body": "{\"alarm\":\"door-open\"}"
    }
  ]
}
```

**GetLatest:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "topic": "coreflux-alerts-lab",
  "token": ""
}
```

**Health:** empty payload / no placeholders required.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [ntfy publish](https://docs.ntfy.sh/publish/)
* [ntfy subscribe API](https://docs.ntfy.sh/subscribe/api/)
* [ntfy access control](https://docs.ntfy.sh/config/#access-control)
* [Action buttons](https://docs.ntfy.sh/publish/#action-buttons)


# OCPI 2.2.1 (EV charging roaming)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ocpi-2-2-1

LoT connector for OCPI 2.2.1 as a CPO: push Locations, EVSE status, Sessions, CDRs and Tariffs to an eMSP or Hub, plus token authorization and credentials

Technical Preview

## Overview

**OCPI** (Open Charge Point Interface, maintained by the EVRoaming Foundation) is the open protocol EV charging networks use to share charge point data, sessions, billing records and tariffs. A **CPO** (charge point operator) runs the chargers; an **eMSP** (e-mobility service provider) owns the driver tokens and apps; a **Hub** (Gireve, Hubject's OCPI gateway, e-clearing.net and others) can sit in between.

The **Ocpi221Peer** connector puts a Coreflux broker on the **CPO side**. Chargers already speak OCPP or publish state over MQTT; LoT actions turn that state into OCPI calls to your roaming partner: EVSE status changes become `PATCH` on the eMSP's Locations receiver, a session start becomes `PUT /sessions`, a finished charge becomes `POST /cdrs`, and an RFID swipe can be checked in real time with `AuthorizeToken`. Each event publishes the peer's reply on `<topic>/response`.

| Event | Topic | Request | Use |
| - | - | - | - |
| `GetVersions` | `energy/ocpi/versions/list` | `GET /ocpi/emsp/versions` | Supported OCPI versions and their details URLs (Token A works here during registration) |
| `GetVersionDetails` | `energy/ocpi/version/details` | `GET /ocpi/emsp/2.2.1` | Module endpoint list for 2.2.1 (identifier, role SENDER/RECEIVER, url) — use it to set PREFIX |
| `GetCredentials` | `energy/ocpi/credentials/get` | `GET …/credentials` | Peer credentials object (token, url, roles with business details) |
| `RegisterCredentials` | `energy/ocpi/credentials/register` | `POST …/credentials` | WRITE: registration — send our credentials (Token B, versions url, roles); reply carries Token C |
| `UpdateCredentials` | `energy/ocpi/credentials/update` | `PUT …/credentials` | WRITE: rotate our token / url / roles; reply carries a new token for us |
| `DeleteCredentials` | `energy/ocpi/credentials/delete` | `DELETE …/credentials` | WRITE: unregister — our credentials on the peer become invalid |
| `GetLocation` | `energy/ocpi/location/get` | `GET …/locations/{country_code}/{party_id}/{location_id}` | Receiver GET: the peer's copy of our Location (validation) |
| `GetEvse` | `energy/ocpi/evse/get` | `GET …/locations/{country_code}/{party_id}/{location_id}/{evse_uid}` | Receiver GET: the peer's copy of one EVSE |
| `GetConnector` | `energy/ocpi/connector/get` | `GET …/locations/{country_code}/{party_id}/{location_id}/{evse_uid}/{connector_id}` | Receiver GET: the peer's copy of one Connector |
| `PutLocation` | `energy/ocpi/location/put` | `PUT …/locations/{country_code}/{party_id}/{location_id}` | WRITE: push a full Location object (new or replace) |
| `PutEvse` | `energy/ocpi/evse/put` | `PUT …/locations/{country_code}/{party_id}/{location_id}/{evse_uid}` | WRITE: push a full EVSE object |
| `PatchLocation` | `energy/ocpi/location/patch` | `PATCH …/locations/{country_code}/{party_id}/{location_id}` | WRITE: partial Location update (must include last\_updated) |
| `PatchEvseStatus` | `energy/ocpi/evse/status` | `PATCH …/locations/{country_code}/{party_id}/{location_id}/{evse_uid}` | WRITE: charger state -> EVSE status, body \{"status":"CHARGING","last\_updated":"..."} |
| `PatchConnector` | `energy/ocpi/connector/patch` | `PATCH …/locations/{country_code}/{party_id}/{location_id}/{evse_uid}/{connector_id}` | WRITE: partial Connector update (tariff\_ids, max power, last\_updated) |
| `GetSession` | `energy/ocpi/session/get` | `GET …/sessions/{country_code}/{party_id}/{session_id}` | Receiver GET: the peer's copy of a Session |
| `PutSession` | `energy/ocpi/session/put` | `PUT …/sessions/{country_code}/{party_id}/{session_id}` | WRITE: create or replace a Session (start of charging) |
| `PatchSession` | `energy/ocpi/session/patch` | `PATCH …/sessions/{country_code}/{party_id}/{session_id}` | WRITE: update kwh / status / charging\_periods / total\_cost during charging |
| `PostCdr` | `energy/ocpi/cdr/post` | `POST …/cdrs` | WRITE: send the final CDR; the peer returns the CDR URL in the Location header |
| `GetCdr` | `energy/ocpi/cdr/get` | `GET …/cdrs/{cdr_id}` | Receiver GET: CDR by the id path the eMSP returned (URL is eMSP-defined; spec example /cdrs/1234) |
| `GetTariff` | `energy/ocpi/tariff/get` | `GET …/tariffs/{country_code}/{party_id}/{tariff_id}` | Receiver GET: the peer's copy of a Tariff |
| `PutTariff` | `energy/ocpi/tariff/put` | `PUT …/tariffs/{country_code}/{party_id}/{tariff_id}` | WRITE: push a full Tariff object |
| `DeleteTariff` | `energy/ocpi/tariff/delete` | `DELETE …/tariffs/{country_code}/{party_id}/{tariff_id}` | WRITE: remove a Tariff from the peer |
| `ListTokens` | `energy/ocpi/tokens/list` | `GET …/tokens?{query}` | Sender GET list: eMSP tokens (query date\_from, date\_to, offset, limit; paginated via Link header) |
| `AuthorizeToken` | `energy/ocpi/token/authorize` | `POST …/tokens/{token_uid}/authorize?type={type}` | Real-time authorization of an RFID / app token at a charger; body LocationReferences (optional) -> AuthorizationInfo |

`…` stands for the module URL prefix, `/ocpi/emsp/2.2.1` in the template. 13 events change state on the peer and are marked `# WRITE` in the `.lot` file.

## Base URL and module URLs

OCPI does not fix URLs: each party publishes them. You get the **versions URL** and a **Token A** from your partner offline, then:

1. `GetVersions` lists supported versions with their details URLs.
2. `GetVersionDetails` returns the 2.2.1 module list: `identifier` (`credentials`, `locations`, `sessions`, `cdrs`, `tariffs`, `tokens`, …), `role` (`SENDER` or `RECEIVER`) and `url`.

The template uses the spec's own example layout: `BASE_ADDRESS` `https://ocpi-peer.example.com`, versions at `/ocpi/emsp/versions`, modules under `/ocpi/emsp/2.2.1/<module>`. If your partner's URLs differ, change `VERSIONS`, `DETAILS` and `PREFIX` in `gen_route.py` and regenerate, or edit the `WITH ENDPOINT` lines. Use the **RECEIVER** URLs for locations, sessions, CDRs and tariffs, and the **SENDER** URL for tokens.

## Authentication

Every request carries `Authorization: Token <encoded token>`. Since OCPI 2.2-d2 the token must be **Base64-encoded** (UTF-8 bytes, RFC 4648). Many older 2.1.1 / 2.2 peers still expect the raw token, so check with your partner.

| Step | Token | Events |
| - | - | - |
| Discovery | Token A (offline, from the peer) | `GetVersions`, `GetVersionDetails` |
| Registration | Token A | `RegisterCredentials` with our Token B, versions URL and roles; the reply holds **Token C** |
| Normal operation | Token C | everything else |

Keep the current value (`Token <base64>`) in Hub secret `OCPI_AUTHORIZATION`. `UpdateCredentials` rotates tokens; `DeleteCredentials` unregisters.

## Required headers

Every OCPI request must carry `X-Request-ID` and `X-Correlation-ID` (use a fresh UUID per request). The connector maps them from the payload fields `request_id` and `correlation_id`. The `OCPI-to-country-code` / `OCPI-to-party-id` / `OCPI-from-*` routing headers are only needed when you go through a Hub and are not in the template; add them to the events your Hub requires.

## Request payload

Publish JSON on the event's source topic:

| Field | Events | Meaning |
| - | - | - |
| `authorization` | all | `Token <base64>` |
| `request_id`, `correlation_id` | all | UUIDs for `X-Request-ID` / `X-Correlation-ID` |
| `country_code`, `party_id` | locations, sessions, tariffs | Your CPO country code and party id (client-owned objects) |
| `location_id`, `evse_uid`, `connector_id` | locations | Object path |
| `session_id`, `tariff_id`, `cdr_id` | sessions, tariffs, CDRs | Object id (`cdr_id` is the path the eMSP returned in `Location`) |
| `token_uid`, `type` | `AuthorizeToken` | Token uid and type (`RFID`, `APP_USER`, `AD_HOC_USER`, `OTHER`) |
| `query` | `ListTokens` | e.g. `date_from=2026-10-01T00:00:00Z&offset=0&limit=100` |
| `body` | POST / PUT / PATCH | OCPI JSON object as a string |

Example on `energy/ocpi/evse/status`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization":"Token <base64>","request_id":"7f0c…","correlation_id":"1b2e…","country_code":"PT","party_id":"CFX","location_id":"LOC1","evse_uid":"PT*CFX*E1","body":"{\"status\":\"CHARGING\",\"last_updated\":\"2026-10-05T14:45:00Z\"}"}
```

Replies use the OCPI envelope `{"data": …, "status_code": 1000, "status_message": "Success", "timestamp": "…"}`. `1000` is success, `2xxx` are client errors (`2001` invalid parameters, `2003` unknown location, `2004` unknown token) and `3xxx` server errors. Unknown objects on receiver `GET` and on `AuthorizeToken` return HTTP `404`.

## Example actions

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the Ocpi221Peer route (docs page). Not part of the route template.
# Secret: OCPI_AUTHORIZATION = "Token <base64(Token C)>" (Token A only for versions + registration).
# Inline JSON object literals are not supported when publishing to a topic, so the request payload is a COLLAPSED
#   model sent with PUBLISH MODEL. The body field is the OCPI JSON object as a string. Use fresh UUIDs for
#   request_id / correlation_id in production (static values shown here for readability).

DEFINE MODEL OcpiVersionsRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "request_id"
    ADD STRING "correlation_id"

DEFINE MODEL OcpiEvseStatusRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "request_id"
    ADD STRING "correlation_id"
    ADD STRING "country_code"
    ADD STRING "party_id"
    ADD STRING "location_id"
    ADD STRING "evse_uid"
    ADD STRING "body"

DEFINE ACTION OcpiVersionDetailsDaily
ON EVERY 1 DAY DO
    PUBLISH MODEL OcpiVersionsRequest TO "energy/ocpi/version/details" WITH
        authorization = (GET SECRET "OCPI_AUTHORIZATION")
        request_id = "cfx-version-details"
        correlation_id = "cfx-version-details"

DEFINE ACTION OcpiChargerStatusToEmsp
ON TOPIC "chargers/+/evse/status" DO
    PUBLISH MODEL OcpiEvseStatusRequest TO "energy/ocpi/evse/status" WITH
        authorization = (GET SECRET "OCPI_AUTHORIZATION")
        request_id = "cfx-evse-status"
        correlation_id = "cfx-evse-status"
        country_code = "PT"
        party_id = "CFX"
        location_id = "LOC1"
        evse_uid = (TOPIC POSITION 2)
        body = PAYLOAD
```

`OcpiChargerStatusToEmsp` expects the charger to publish an OCPI-shaped patch such as `{"status":"AVAILABLE","last_updated":"…"}` on `chargers/<evse_uid>/evse/status`; map your charger's own status values to OCPI `Status` (`AVAILABLE`, `BLOCKED`, `CHARGING`, `INOPERATIVE`, `OUTOFORDER`, `PLANNED`, `REMOVED`, `RESERVED`, `UNKNOWN`) first if they differ.

## Writes

`RegisterCredentials`, `UpdateCredentials`, `DeleteCredentials`, `PutLocation`, `PutEvse`, `PatchLocation`, `PatchEvseStatus`, `PatchConnector`, `PutSession`, `PatchSession`, `PostCdr`, `PutTariff` and `DeleteTariff` change your partner's data and can affect billing. Restrict which MQTT clients may publish to those topics with broker rules. Every `PATCH` body must include `last_updated`. Locations cannot be deleted in OCPI: `PATCH` the status to `REMOVED` instead.

## Not packaged

* CPO receiver interfaces the partner calls on you: **Commands** (`START_SESSION`, `STOP_SESSION`, `RESERVE_NOW`, `UNLOCK_CONNECTOR`, …), **ChargingProfiles**, Tokens push, and Credentials from the peer. These need REST API server mode.
* Async callbacks to an arbitrary `response_url`, and **HubClientInfo**.
* eMSP-role pulls (sender `GET` lists of Locations, Sessions, CDRs, Tariffs from a CPO). A second connector with `/ocpi/cpo/2.2.1` paths would cover that.
* **OCPP** (charger to CPO back office) uses WebSocket, not REST, and is out of scope.

## Sources

* [OCPI 2.2.1 specification (GitHub, release-2.2.1-bugfixes)](https://github.com/ocpi/ocpi/tree/release-2.2.1-bugfixes): `mod_locations`, `mod_sessions`, `mod_cdrs`, `mod_tariffs`, `mod_tokens`, `credentials`, `version_information_endpoint`, `transport_and_format`
* [EVRoaming Foundation](https://evroaming.org/)
* OCPI does not publish an official OpenAPI file.


# Odoo
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/odoo

Client-mode REST API connector for a curated Odoo External JSON-2 slice: manufacturing orders, stock quants, and maintenance requests

Technical Preview

## Overview

A client-mode connector for a **curated manufacturing / inventory / maintenance** slice of the [Odoo External JSON-2 API](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html) under `https://YOUR_ODOO_HOST/json/2/`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| (connectivity) | `GET /web/version` | Unauthenticated; replaces legacy `common.version` |
| search\_read on mrp.production | `POST /json/2/mrp.production/search_read` | Manufacturing app required |
| button\_mark\_done | `POST /json/2/mrp.production/button_mark_done` | Pass `ids` of MOs |
| create on stock.quant adjustments | `POST /json/2/stock.quant/create` | Prefer `context.inventory_mode`; Inventory app |
| create on maintenance.request | `POST /json/2/maintenance.request/create` | Maintenance app required |

`BASE_ADDRESS` is the Odoo host root (no trailing slash). Topics use `erp/odoo/<object>/<verb>`.

> [!NOTE]
>
> This template targets **External JSON-2** (Odoo 19+): `POST /json/2/{model}/{method}` with a Bearer API key. Legacy `/jsonrpc` and `/xmlrpc/2` (`authenticate` + `execute_kw`) are deprecated and scheduled for removal (target Odoo 22). Use JSON-2 for new integrations.

> [!NOTE]
>
> Odoo Online external API access requires a **Custom** plan. Replace `YOUR_ODOO_HOST`, pass a user API key, and set `X-Odoo-Database` when the host serves multiple databases. Prefer Hub secrets for keys.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Odoo (External JSON-2 API slice)
# Auth: Bearer {value.json.api_key}
# BASE_ADDRESS: https://YOUR_ODOO_HOST

DEFINE CONNECTOR OdooRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ODOO_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getwebversion
        WITH SOURCE_TOPIC "erp/odoo/web/version/get"
        WITH DESTINATION_TOPIC "erp/odoo/web/version/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/web/version"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Searchreadmrpproduction
        WITH SOURCE_TOPIC "erp/odoo/mrp-production/search-read"
        WITH DESTINATION_TOPIC "erp/odoo/mrp-production/search-read/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/json/2/mrp.production/search_read"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.api_key}"
            ADD "X-Odoo-Database" "{value.json.database}"
        WITH BODY "{payload}"
    ADD EVENT Buttonmarkdonemrpproduction
        WITH SOURCE_TOPIC "erp/odoo/mrp-production/button-mark-done"
        WITH DESTINATION_TOPIC "erp/odoo/mrp-production/button-mark-done/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/json/2/mrp.production/button_mark_done"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.api_key}"
            ADD "X-Odoo-Database" "{value.json.database}"
        WITH BODY "{payload}"
    ADD EVENT Createstockquant
        WITH SOURCE_TOPIC "erp/odoo/stock-quant/create"
        WITH DESTINATION_TOPIC "erp/odoo/stock-quant/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/json/2/stock.quant/create"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.api_key}"
            ADD "X-Odoo-Database" "{value.json.database}"
        WITH BODY "{payload}"
    ADD EVENT Createmaintenancerequest
        WITH SOURCE_TOPIC "erp/odoo/maintenance-request/create"
        WITH DESTINATION_TOPIC "erp/odoo/maintenance-request/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/json/2/maintenance.request/create"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json; charset=utf-8"
            ADD "Authorization" "Bearer {value.json.api_key}"
            ADD "X-Odoo-Database" "{value.json.database}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getwebversion | GET | `/web/version` | `erp/odoo/web/version/get` | `erp/odoo/web/version/get/response` |
| Searchreadmrpproduction | POST | `/json/2/mrp.production/search_read` | `erp/odoo/mrp-production/search-read` | `erp/odoo/mrp-production/search-read/response` |
| Buttonmarkdonemrpproduction | POST | `/json/2/mrp.production/button_mark_done` | `erp/odoo/mrp-production/button-mark-done` | `erp/odoo/mrp-production/button-mark-done/response` |
| Createstockquant | POST | `/json/2/stock.quant/create` | `erp/odoo/stock-quant/create` | `erp/odoo/stock-quant/create/response` |
| Createmaintenancerequest | POST | `/json/2/maintenance.request/create` | `erp/odoo/maintenance-request/create` | `erp/odoo/maintenance-request/create/response` |

## Auth

**Bearer API key (JSON-2) — default in the template:**

1. In Odoo: **Preferences → Account Security → New API Key**. Copy the key once; store it in Hub secrets.
2. Pass the key (and database when required) on the MQTT request payload so headers resolve:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "YOUR_ODOO_API_KEY", "database": "YOUR_DB"}
```

The connector sends `Authorization: Bearer {value.json.api_key}` and `X-Odoo-Database: {value.json.database}`. Prefer Hub secrets / `GET SECRET`. Never commit real keys.

**Legacy JSON-RPC / XML-RPC (not in this template):** `authenticate(db, login, password)` then `execute_kw(db, uid, password, model, method, args, kwargs)`. Password may be an API key on some deployments. Prefer migrating to JSON-2.

## Example bodies

**search\_read manufacturing orders:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "context": {"lang": "en_US"},
  "domain": [["state", "=", "confirmed"]],
  "fields": ["name", "product_id", "product_qty", "state", "date_start"],
  "limit": 10
}
```

**button\_mark\_done:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"ids": [42]}
```

**stock.quant create (inventory adjustment path):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "context": {"inventory_mode": true},
  "vals_list": [
    {"product_id": 1, "location_id": 8, "inventory_quantity": 100.0}
  ]
}
```

**maintenance.request create:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "vals_list": [
    {
      "name": "Line sensor fault",
      "maintenance_type": "corrective",
      "description": "Raised from IIoT alert"
    }
  ]
}
```

Exact `create` argument names follow your Odoo version ORM (`vals_list` vs single `vals`). Discover models/methods on the database `/doc` page when available.

## Deploy

1. Copy `OdooRestApi.lot` (no `ADD METADATA`).
2. Replace `YOUR_ODOO_HOST` in `BASE_ADDRESS`.
3. `-addConnector` on the broker (or Hub deploy).
4. Publish JSON to a request topic; subscribe to the matching `/response` topic.

Hub catalog metadata (icon, description, `STATUS "beta"`) is in `hub-metadata.lot` for Hub / `-listTemplates` only.

## References

* [External JSON-2 API — Odoo 19.0](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html)
* [External RPC API — Odoo 19.0](https://www.odoo.com/documentation/19.0/developer/reference/external_rpc_api.html)
* [odoo/odoo on GitHub](https://github.com/odoo/odoo)
* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)


# Okta
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/okta

Client-mode REST API connector for a curated Okta Users API slice: list users and create a user

Technical Preview

# Okta

Client-mode REST API connector for a curated Okta Users API slice: list users and create a user.

* Hub category: **Identity**.
* Base: `https://tenant.okta.com`

## Template reference

Generated from the shipped broker template `okta` (`-connectorCode OKTA`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: SSWS {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Okta connector | no |
| `BaseUrl` | string | Okta base URL without trailing slash (e.g. [https://tenant.okta.com](https://tenant.okta.com)) | yes |

`BASE_ADDRESS` default: `https://tenant.okta.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listusers` | GET | `/api/v1/users` | `identity/okta/users/list` | `identity/okta/users/list/response` | `api_token` |
| `Createuser` | POST | `/api/v1/users` | `identity/okta/users/create` | `identity/okta/users/create/response` | `api_token`, `body` |
| `Getuser` | GET | `/api/v1/users/{value.json.user_id}` | `identity/okta/users/get` | `identity/okta/users/get/response` | `api_token`, `user_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode OKTA"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OktaRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://tenant.okta.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listusers
        WITH SOURCE_TOPIC "identity/okta/users/list"
        WITH DESTINATION_TOPIC "identity/okta/users/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/users"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "SSWS {value.json.api_token}"
    ADD EVENT Createuser
        WITH SOURCE_TOPIC "identity/okta/users/create"
        WITH DESTINATION_TOPIC "identity/okta/users/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/users"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "SSWS {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getuser
        WITH SOURCE_TOPIC "identity/okta/users/get"
        WITH DESTINATION_TOPIC "identity/okta/users/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/users/{value.json.user_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "SSWS {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listusers` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'identity/okta/users/list/response' &
mosquitto_pub -t 'identity/okta/users/list' -m '{"api_token": "<api_token>"}'
```


# Ollama (local models)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ollama

Client-mode REST API connector for local Ollama generate, chat, embed, and tags — MQTT into edge LLMs with no cloud and no API key by default

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [Ollama API](https://docs.ollama.com/api) focused on IIoT / edge alarm text into **local** LLMs (no cloud):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST generate | `POST /api/generate` | Edge classification / structured JSON; set `"stream": false` |
| POST chat | `POST /api/chat` | Chat with messages; `"stream": false` for MQTT one-shot |
| POST embed | `POST /api/embed` | Embeddings (supersedes legacy `/api/embeddings`) |
| GET tags | `GET /api/tags` | Health + local model list |
| (supporting) GET models | `GET /v1/models` | OpenAI-compatible model list |
| (supporting) POST chat/completions | `POST /v1/chat/completions` | OpenAI-compatible chat |

Default `BASE_ADDRESS` is `http://127.0.0.1:11434` with `USE_SSL "false"` (no trailing slash). For an HTTPS reverse proxy, set `USE_SSL "true"` and point `BASE_ADDRESS` at `https://your-host`. Topics use `ai/ollama/<object>/<verb>`. `REQUEST_TIMEOUT` is `120` for cold model load + inference.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** none required for local Ollama. A reverse proxy may require `Authorization: Bearer &lt;token&gt;` — add that header and map Hub secrets into MQTT `api_token` if needed.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Ollama (local models)
# Auth: none by default; reverse proxy may add Bearer
# BASE_ADDRESS: http://127.0.0.1:11434 (USE_SSL false)

DEFINE CONNECTOR OllamaRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://127.0.0.1:11434"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostGenerate
        WITH SOURCE_TOPIC "ai/ollama/generate/post"
        WITH DESTINATION_TOPIC "ai/ollama/generate/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/generate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT PostChat
        WITH SOURCE_TOPIC "ai/ollama/chat/post"
        WITH DESTINATION_TOPIC "ai/ollama/chat/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/chat"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT PostEmbed
        WITH SOURCE_TOPIC "ai/ollama/embed/post"
        WITH DESTINATION_TOPIC "ai/ollama/embed/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/embed"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT GetTags
        WITH SOURCE_TOPIC "ai/ollama/tags/list"
        WITH DESTINATION_TOPIC "ai/ollama/tags/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Topics

| Event | Source topic | Destination topic |
| - | - | - |
| PostGenerate | `ai/ollama/generate/post` | `…/response` |
| PostChat | `ai/ollama/chat/post` | `…/response` |
| PostEmbed | `ai/ollama/embed/post` | `…/response` |
| GetTags | `ai/ollama/tags/list` | `…/response` |
| GetModels | `ai/ollama/models/list` | `…/response` |
| PostChatCompletions | `ai/ollama/chat/completions/post` | `…/response` |

## Configuration

1. Run Ollama locally (e.g. `docker run -d -p 11434:11434 ollama/ollama`) and pull a model (`ollama pull tinyllama`).
2. Set `BASE_ADDRESS` to `http://127.0.0.1:11434` (or your LAN/Docker host). Keep `USE_SSL "false"` for plain HTTP; use HTTPS + `USE_SSL "true"` behind a reverse proxy.
3. For edge alarm classification: publish to `ai/ollama/generate/post` with `"stream": false` and optional `"format": "json"` / JSON schema.
4. For chat-style prompts: publish to `ai/ollama/chat/post` with a `messages` array and `"stream": false`.
5. Use `GetTags` as a a cheap health and model-list check before production workloads.
6. Optional OpenAI-shaped clients can use `GetModels` / `PostChatCompletions` under `/v1/...`.

## References

* [Ollama API](https://docs.ollama.com/api)
* [API reference (GitHub)](https://github.com/ollama/ollama/blob/main/docs/api.md)
* [OpenAI compatibility](https://docs.ollama.com/api/openai-compatibility)
* [Model library](https://ollama.com/library)


# Open-Meteo REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/open-meteo

Client-mode REST API connector for free weather forecast and solar radiation (Open-Meteo Forecast API)

Technical Preview

## Overview

Client-mode REST API connector for free weather forecast and solar radiation (Open-Meteo Forecast API). `BASE_ADDRESS` defaults to `https://api.open-meteo.com`. Auth: **None for non-commercial (optional apikey query for commercial)**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

None for non-commercial (optional apikey query for commercial). Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR OpenMeteoRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.open-meteo.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Optional: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Getforecasthourlysolar
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getforecasthourlysolar"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getforecasthourlysolar"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m,shortwave_radiation&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getcurrentweather
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getcurrentweather"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getcurrentweather"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&current=temperature_2m,wind_speed_10m,weather_code&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecasthourlyweather
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getforecasthourlyweather"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getforecasthourlyweather"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m,relative_humidity_2m,precipitation,wind_speed_10m&forecast_days={value.json.forecast_days}&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecastdaily
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getforecastdaily"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getforecastdaily"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&daily=temperature_2m_max,temperature_2m_min,precipitation_sum,shortwave_radiation_sum&forecast_days={value.json.forecast_days}&timezone={value.json.timezone}"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/open-meteo/request/...`; responses on `integrations/open-meteo/response/...`.

## Template reference

Generated from the shipped broker template `open-meteo` (`-connectorCode OPEN_METEO`). It lists every event the template defines.

### Auth

None for non-commercial (optional apikey query for commercial)

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Open-Meteo connector | no |
| `BaseUrl` | string | Open-Meteo base URL without trailing slash (e.g. [https://api.open-meteo.com](https://api.open-meteo.com)) | yes |

`BASE_ADDRESS` default: `https://api.open-meteo.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Getforecasthourlysolar` | GET | `/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m,shortwave_radiation&timezone={value.json.timezone}` | `integrations/open-meteo/request/Getforecasthourlysolar` | `integrations/open-meteo/response/Getforecasthourlysolar` | `latitude`, `longitude`, `timezone` |
| `Getcurrentweather` | GET | `/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&current=temperature_2m,wind_speed_10m,weather_code&timezone={value.json.timezone}` | `integrations/open-meteo/request/Getcurrentweather` | `integrations/open-meteo/response/Getcurrentweather` | `latitude`, `longitude`, `timezone` |
| `Getforecasthourlyweather` | GET | `/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m,relative_humidity_2m,precipitation,wind_speed_10m&forecast_days={value.json.forecast_days}&timezone={value.json.timezone}` | `integrations/open-meteo/request/Getforecasthourlyweather` | `integrations/open-meteo/response/Getforecasthourlyweather` | `forecast_days`, `latitude`, `longitude`, `timezone` |
| `Getforecastdaily` | GET | `/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&daily=temperature_2m_max,temperature_2m_min,precipitation_sum,shortwave_radiation_sum&forecast_days={value.json.forecast_days}&timezone={value.json.timezone}` | `integrations/open-meteo/request/Getforecastdaily` | `integrations/open-meteo/response/Getforecastdaily` | `forecast_days`, `latitude`, `longitude`, `timezone` |
| `Getsolarradiation` | GET | `/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=shortwave_radiation,direct_radiation,diffuse_radiation,direct_normal_irradiance&timezone={value.json.timezone}` | `integrations/open-meteo/request/Getsolarradiation` | `integrations/open-meteo/response/Getsolarradiation` | `latitude`, `longitude`, `timezone` |
| `Getforecastbymodel` | GET | `/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m&models={value.json.models}&timezone={value.json.timezone}` | `integrations/open-meteo/request/Getforecastbymodel` | `integrations/open-meteo/response/Getforecastbymodel` | `latitude`, `longitude`, `models`, `timezone` |
| `Getelevation` | GET | `/v1/elevation?latitude={value.json.latitude}&longitude={value.json.longitude}` | `integrations/open-meteo/request/Getelevation` | `integrations/open-meteo/response/Getelevation` | `latitude`, `longitude` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode OPEN_METEO"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OpenMeteoRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.open-meteo.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getforecasthourlysolar
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getforecasthourlysolar"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getforecasthourlysolar"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m,shortwave_radiation&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getcurrentweather
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getcurrentweather"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getcurrentweather"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&current=temperature_2m,wind_speed_10m,weather_code&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecasthourlyweather
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getforecasthourlyweather"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getforecasthourlyweather"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m,relative_humidity_2m,precipitation,wind_speed_10m&forecast_days={value.json.forecast_days}&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecastdaily
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getforecastdaily"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getforecastdaily"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&daily=temperature_2m_max,temperature_2m_min,precipitation_sum,shortwave_radiation_sum&forecast_days={value.json.forecast_days}&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getsolarradiation
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getsolarradiation"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getsolarradiation"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=shortwave_radiation,direct_radiation,diffuse_radiation,direct_normal_irradiance&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecastbymodel
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getforecastbymodel"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getforecastbymodel"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/forecast?latitude={value.json.latitude}&longitude={value.json.longitude}&hourly=temperature_2m&models={value.json.models}&timezone={value.json.timezone}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getelevation
        WITH SOURCE_TOPIC "integrations/open-meteo/request/Getelevation"
        WITH DESTINATION_TOPIC "integrations/open-meteo/response/Getelevation"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/elevation?latitude={value.json.latitude}&longitude={value.json.longitude}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Getforecasthourlysolar` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/open-meteo/response/Getforecasthourlysolar' &
mosquitto_pub -t 'integrations/open-meteo/request/Getforecasthourlysolar' -m '{"latitude": "<latitude>", "longitude": "<longitude>", "timezone": "<timezone>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# OpenADR 3.0 (demand response)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/openadr-3-0

LoT connector for OpenADR 3.0 demand response: get VTN OAuth tokens, read programs and events, send reports, manage subscriptions and register VENs

Technical Preview

## Overview

**OpenADR 3** is the OpenADR Alliance standard for demand response and dynamic pricing over a REST API. A utility or aggregator runs a **VTN** (Virtual Top Node). Sites and devices connect to it as **VENs** (Virtual End Nodes): they read **programs** and **events** (price signals, load-shed requests, import / export capacity limits, GHG signals) and send **reports** (measured usage, baselines, status) back. A **business logic** (BL) client on the utility side creates the events.

The **OpenAdr3Vtn** connector maps 26 MQTT topics onto the OpenADR 3.0.1 API: one token request, 12 read events and 13 write events. With it, a Coreflux broker can act as the VEN for a plant or building: it picks up DR events on MQTT, hands them to the controls that shed or shift load, and reports the measured response to the utility. Each event publishes the VTN reply on `<topic>/response`.

| Event | Topic | Request | Use |
| - | - | - | - |
| `FetchToken` | `energy/openadr/auth/token` | `POST /auth/token` | OAuth 2.0 client credentials -> access\_token (Bearer), expires\_in; form body grant\_type=client\_credentials\&client\_id=\&client\_secret=\&scope= |
| `ListPrograms` | `energy/openadr/program/list` | `GET /programs?{query}` | DR programs the client may read (programName, intervalPeriod, payloadDescriptors, targets); query targetType=\&targetValues=\&skip=\&limit= |
| `GetProgram` | `energy/openadr/program/get` | `GET /programs/{id}` | One program by id |
| `ListEvents` | `energy/openadr/event/list` | `GET /events?{query}` | DR events: intervals with payloads (PRICE, SIMPLE, IMPORT\_CAPACITY\_LIMIT, GHG ...), priority, targets; query programID=\&targetType=\&targetValues=\&skip=\&limit= |
| `GetEvent` | `energy/openadr/event/get` | `GET /events/{id}` | One event by id |
| `CreateEvent` | `energy/openadr/event/create` | `POST /events` | WRITE (business logic, write\_events): publish a DR event to the targeted VENs; body \{programID, intervals, ...} |
| `UpdateEvent` | `energy/openadr/event/update` | `PUT /events/{id}` | WRITE (business logic): replace an event (full object) |
| `DeleteEvent` | `energy/openadr/event/delete` | `DELETE /events/{id}` | WRITE (business logic): delete (cancel) an event |
| `ListReports` | `energy/openadr/report/list` | `GET /reports?{query}` | Reports; query programID=\&eventID=\&clientName=\&skip=\&limit= |
| `GetReport` | `energy/openadr/report/get` | `GET /reports/{id}` | One report by id |
| `CreateReport` | `energy/openadr/report/create` | `POST /reports` | WRITE (VEN, write\_reports): telemetry back to the VTN; body \{programID, eventID, clientName, resources\[\{resourceName, intervals}]} |
| `UpdateReport` | `energy/openadr/report/update` | `PUT /reports/{id}` | WRITE (VEN): replace a report (full object) |
| `DeleteReport` | `energy/openadr/report/delete` | `DELETE /reports/{id}` | WRITE (VEN): delete a report |
| `ListSubscriptions` | `energy/openadr/subscription/list` | `GET /subscriptions?{query}` | Subscriptions; query programID=\&clientName=\&targetType=\&targetValues=\&objects=\&skip=\&limit= |
| `GetSubscription` | `energy/openadr/subscription/get` | `GET /subscriptions/{id}` | One subscription by id |
| `CreateSubscription` | `energy/openadr/subscription/create` | `POST /subscriptions` | WRITE: register a webhook; body \{clientName, programID, objectOperations\[\{objects, operations, callbackUrl, bearerToken}]} |
| `UpdateSubscription` | `energy/openadr/subscription/update` | `PUT /subscriptions/{id}` | WRITE: replace a subscription (full object) |
| `DeleteSubscription` | `energy/openadr/subscription/delete` | `DELETE /subscriptions/{id}` | WRITE: delete a subscription |
| `ListVens` | `energy/openadr/ven/list` | `GET /vens?{query}` | VENs visible to the client (venName, attributes, targets); query venName=\&targetType=\&targetValues=\&skip=\&limit= |
| `GetVen` | `energy/openadr/ven/get` | `GET /vens/{id}` | One VEN by id |
| `CreateVen` | `energy/openadr/ven/create` | `POST /vens` | WRITE (write\_vens): register a VEN; body \{venName, attributes, targets} |
| `UpdateVen` | `energy/openadr/ven/update` | `PUT /vens/{id}` | WRITE: replace a VEN (full object) |
| `ListResources` | `energy/openadr/resource/list` | `GET /vens/{ven_id}/resources?{query}` | Resources (meters, batteries, chargers) of a VEN; query resourceName=\&targetType=\&targetValues=\&skip=\&limit= |
| `GetResource` | `energy/openadr/resource/get` | `GET /vens/{ven_id}/resources/{id}` | One resource of a VEN |
| `CreateResource` | `energy/openadr/resource/create` | `POST /vens/{ven_id}/resources` | WRITE (write\_vens): add a resource to a VEN; body \{resourceName, venID, attributes, targets} |
| `UpdateResource` | `energy/openadr/resource/update` | `PUT /vens/{ven_id}/resources/{id}` | WRITE: replace a resource (full object) |

All endpoints carry the base path `/openadr3/3.0.1` (left out in the table).

> [!WARNING]
>
> **Write events change VTN state.** `CreateEvent`, `UpdateEvent` and `DeleteEvent` need the business-logic role (`write_events`): a new event is a demand-response instruction to every targeted VEN. Reports, subscriptions and VEN / resource registration are VEN writes. Restrict who can publish to these topics with a rule. This connector leaves out program administration and VEN / resource deletion.

## Prerequisites

* Access to a **VTN**: the URL from your utility, aggregator or DR program, or your own VTN (for example the open-source [openleadr-rs](https://github.com/OpenLEADR/openleadr-rs) VTN).
* **Client credentials** (`client_id`, `client_secret`) for a VEN client, and a business-logic client if you create events. The VTN operator issues them.
* The VTN **base path**. The OpenADR 3.0.1 specification uses `/openadr3/3.0.1`. Some VTNs serve the API at a different path or at the root. Change the endpoints if yours does.
* Outbound HTTPS from the broker to the VTN.

## Authentication

OpenADR 3 uses **OAuth 2.0 client credentials**. `FetchToken` posts a form body to `auth/token` and gets back `{"access_token": "...", "token_type": "Bearer", "expires_in": 3600}`. Every other event sends `Authorization: {value.json.authorization}` with the value `Bearer <access_token>`.

| Secret | Value |
| - | - |
| `OPENADR_TOKEN_REQUEST` | `grant_type=client_credentials&client_id=<id>&client_secret=<secret>` (add `&scope=read_all` when the VTN wants a scope) |
| `OPENADR_AUTHORIZATION` | `Bearer <access_token>`, refreshed before `expires_in` runs out |

The specification calls `auth/token` a convenience endpoint that a commercial VTN may leave out. In that case, get the token from the utility's authorization server and store it in `OPENADR_AUTHORIZATION`.

Scopes: `read_all` (VENs and BL), `write_programs` and `write_events` (BL), `write_reports` (VENs), `write_subscriptions` and `write_vens` (VENs and BL).

| Response | Meaning |
| - | - |
| `400` `{"error": "invalid_client"}` | Wrong client id or secret on `auth/token` |
| `403` problem JSON | Missing or invalid token, or the token's scope does not allow the call |
| `404` problem JSON | Unknown object id |
| `409` problem JSON | The object already exists (for example a duplicate `venName`) |

## Configuration

| Setting | Value |
| - | - |
| `BASE_ADDRESS` | Your VTN host, such as `https://vtn.utility.example` (placeholder `https://vtn.example.com`) |
| `USE_SSL` | `"true"` |
| `DEFAULT_CONTENT_TYPE` | `application/json` (`auth/token` sends `application/x-www-form-urlencoded`) |
| Payload fields | `authorization`, `id` (object id), `ven_id` (resource events), `query` (pre-encoded query string, `""` for none), `body` (JSON object; a form string for `auth/token`) |

Query parameters (3.0.1):

| Event | Parameters |
| - | - |
| `ListPrograms` | `targetType`, `targetValues`, `skip`, `limit` |
| `ListEvents` | `programID`, `targetType`, `targetValues`, `skip`, `limit` |
| `ListReports` | `programID`, `eventID`, `clientName`, `skip`, `limit` |
| `ListSubscriptions` | `programID`, `clientName`, `targetType`, `targetValues`, `objects`, `skip`, `limit` |
| `ListVens` | `venName`, `targetType`, `targetValues`, `skip`, `limit` |
| `ListResources` | `resourceName`, `targetType`, `targetValues`, `skip`, `limit` |

An event carries `intervals`, and each interval has `payloads` such as `{"type": "PRICE", "values": [0.17]}` or `{"type": "IMPORT_CAPACITY_LIMIT", "values": [50]}`. `intervalPeriod` sets the start and duration (ISO 8601, for example `PT1H`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — OpenADR 3.0 (3.0.1) demand response, VEN / business-logic client of a VTN:
#   get an OAuth 2.0 client-credentials token, read DR programs and events (price, load shed, GHG and other
#   signals), read, create, update and delete reports (telemetry / baselines back to the utility), manage
#   subscriptions (webhook callbacks), and read / register VENs and their resources; plus (marked WRITE,
#   business-logic role only) create, update and delete events.
#   github.com/grid-coordination/openadr3-specification, upstream oadr3-org/specification a35682b; Apache 2.0),
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/openadr-3-0
#
# VTN: every utility / aggregator runs its own VTN. BASE_ADDRESS is a placeholder: set it to your VTN host and
#   change /openadr3/3.0.1 in the endpoints if your VTN uses another base path (the spec server is
#   http://localhost:8081/openadr3/3.0.1; openleadr-rs serves the API at its root).
# Auth: Authorization: {value.json.authorization} = "Bearer <access_token>" on every call except auth/token.
#   Tokens come from OAuth 2.0 client credentials. The VTN may host POST {base}/auth/token (FetchToken, form
#   body grant_type=client_credentials&client_id=...&client_secret=...&scope=...) or point to an external
#   authorization server (then fetch the token there). Scopes: read_all, write_programs, write_events
#   (business logic), write_reports (VEN), write_subscriptions, write_vens. Keep client id / secret in Hub secrets
#   (suggested OPENADR_CLIENT_ID, OPENADR_CLIENT_SECRET) and the current token in OPENADR_AUTHORIZATION.
#   Errors: 400 / 403 / 404 / 409 / 500 as application/problem+json {type, title, status, detail}.
# Queries: list events with ?{value.json.query} take a pre-encoded query string ("" for none):
#     programs        targetType=&targetValues=&skip=&limit=
#     events          programID=&targetType=&targetValues=&skip=&limit=
#     reports         programID=&eventID=&clientName=&skip=&limit=
#     subscriptions   programID=&clientName=&targetType=&targetValues=&objects=&skip=&limit=
#     vens            venName=&targetType=&targetValues=&skip=&limit=
#     resources       resourceName=&targetType=&targetValues=&skip=&limit=
# Writes (marked WRITE below): reports, subscriptions, VEN / resource registration (VEN role) and events
#   (business-logic role: a new event is a demand-response instruction to every targeted VEN). Not packaged:
#   program create / update / delete, VEN and resource delete.
# Webhooks: POST subscription/create with objectOperations[].callbackUrl pointing to a Coreflux REST_API server
#   route (ENABLE_SERVER) to get pushed notifications; the VTN POSTs {objectType, operation, object} to it.
#
# Payload fields: authorization, id (object id), ven_id (resources), query, body (JSON object; form string for
#   auth/token)
#     FetchToken     body = "grant_type=client_credentials&client_id=ven_client_99&client_secret=<secret>"
#     ListEvents     query = "programID=0&limit=50"
#     CreateReport   body = {"programID": "0", "eventID": "0", "clientName": "VEN-999", "resources": [...]}

DEFINE CONNECTOR OpenAdr3Vtn WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://vtn.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT FetchToken
        WITH SOURCE_TOPIC "energy/openadr/auth/token"
        WITH DESTINATION_TOPIC "energy/openadr/auth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openadr3/3.0.1/auth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.body}"
    ADD EVENT ListPrograms
        WITH SOURCE_TOPIC "energy/openadr/program/list"
        WITH DESTINATION_TOPIC "energy/openadr/program/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/programs?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetProgram
        WITH SOURCE_TOPIC "energy/openadr/program/get"
        WITH DESTINATION_TOPIC "energy/openadr/program/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/programs/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListEvents
        WITH SOURCE_TOPIC "energy/openadr/event/list"
        WITH DESTINATION_TOPIC "energy/openadr/event/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/events?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetEvent
        WITH SOURCE_TOPIC "energy/openadr/event/get"
        WITH DESTINATION_TOPIC "energy/openadr/event/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/events/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: CreateEvent changes VTN state. Restrict who can publish to energy/openadr/event/create.
    ADD EVENT CreateEvent
        WITH SOURCE_TOPIC "energy/openadr/event/create"
        WITH DESTINATION_TOPIC "energy/openadr/event/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openadr3/3.0.1/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: UpdateEvent changes VTN state. Restrict who can publish to energy/openadr/event/update.
    ADD EVENT UpdateEvent
        WITH SOURCE_TOPIC "energy/openadr/event/update"
        WITH DESTINATION_TOPIC "energy/openadr/event/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/openadr3/3.0.1/events/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: DeleteEvent changes VTN state. Restrict who can publish to energy/openadr/event/delete.
    ADD EVENT DeleteEvent
        WITH SOURCE_TOPIC "energy/openadr/event/delete"
        WITH DESTINATION_TOPIC "energy/openadr/event/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/openadr3/3.0.1/events/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListReports
        WITH SOURCE_TOPIC "energy/openadr/report/list"
        WITH DESTINATION_TOPIC "energy/openadr/report/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/reports?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetReport
        WITH SOURCE_TOPIC "energy/openadr/report/get"
        WITH DESTINATION_TOPIC "energy/openadr/report/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/reports/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: CreateReport changes VTN state. Restrict who can publish to energy/openadr/report/create.
    ADD EVENT CreateReport
        WITH SOURCE_TOPIC "energy/openadr/report/create"
        WITH DESTINATION_TOPIC "energy/openadr/report/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openadr3/3.0.1/reports"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: UpdateReport changes VTN state. Restrict who can publish to energy/openadr/report/update.
    ADD EVENT UpdateReport
        WITH SOURCE_TOPIC "energy/openadr/report/update"
        WITH DESTINATION_TOPIC "energy/openadr/report/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/openadr3/3.0.1/reports/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: DeleteReport changes VTN state. Restrict who can publish to energy/openadr/report/delete.
    ADD EVENT DeleteReport
        WITH SOURCE_TOPIC "energy/openadr/report/delete"
        WITH DESTINATION_TOPIC "energy/openadr/report/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/openadr3/3.0.1/reports/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListSubscriptions
        WITH SOURCE_TOPIC "energy/openadr/subscription/list"
        WITH DESTINATION_TOPIC "energy/openadr/subscription/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/subscriptions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSubscription
        WITH SOURCE_TOPIC "energy/openadr/subscription/get"
        WITH DESTINATION_TOPIC "energy/openadr/subscription/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/subscriptions/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: CreateSubscription changes VTN state. Restrict who can publish to energy/openadr/subscription/create.
    ADD EVENT CreateSubscription
        WITH SOURCE_TOPIC "energy/openadr/subscription/create"
        WITH DESTINATION_TOPIC "energy/openadr/subscription/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openadr3/3.0.1/subscriptions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: UpdateSubscription changes VTN state. Restrict who can publish to energy/openadr/subscription/update.
    ADD EVENT UpdateSubscription
        WITH SOURCE_TOPIC "energy/openadr/subscription/update"
        WITH DESTINATION_TOPIC "energy/openadr/subscription/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/openadr3/3.0.1/subscriptions/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: DeleteSubscription changes VTN state. Restrict who can publish to energy/openadr/subscription/delete.
    ADD EVENT DeleteSubscription
        WITH SOURCE_TOPIC "energy/openadr/subscription/delete"
        WITH DESTINATION_TOPIC "energy/openadr/subscription/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/openadr3/3.0.1/subscriptions/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListVens
        WITH SOURCE_TOPIC "energy/openadr/ven/list"
        WITH DESTINATION_TOPIC "energy/openadr/ven/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/vens?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetVen
        WITH SOURCE_TOPIC "energy/openadr/ven/get"
        WITH DESTINATION_TOPIC "energy/openadr/ven/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/vens/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: CreateVen changes VTN state. Restrict who can publish to energy/openadr/ven/create.
    ADD EVENT CreateVen
        WITH SOURCE_TOPIC "energy/openadr/ven/create"
        WITH DESTINATION_TOPIC "energy/openadr/ven/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openadr3/3.0.1/vens"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: UpdateVen changes VTN state. Restrict who can publish to energy/openadr/ven/update.
    ADD EVENT UpdateVen
        WITH SOURCE_TOPIC "energy/openadr/ven/update"
        WITH DESTINATION_TOPIC "energy/openadr/ven/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/openadr3/3.0.1/vens/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListResources
        WITH SOURCE_TOPIC "energy/openadr/resource/list"
        WITH DESTINATION_TOPIC "energy/openadr/resource/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/vens/{value.json.ven_id}/resources?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetResource
        WITH SOURCE_TOPIC "energy/openadr/resource/get"
        WITH DESTINATION_TOPIC "energy/openadr/resource/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/openadr3/3.0.1/vens/{value.json.ven_id}/resources/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: CreateResource changes VTN state. Restrict who can publish to energy/openadr/resource/create.
    ADD EVENT CreateResource
        WITH SOURCE_TOPIC "energy/openadr/resource/create"
        WITH DESTINATION_TOPIC "energy/openadr/resource/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/openadr3/3.0.1/vens/{value.json.ven_id}/resources"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: UpdateResource changes VTN state. Restrict who can publish to energy/openadr/resource/update.
    ADD EVENT UpdateResource
        WITH SOURCE_TOPIC "energy/openadr/resource/update"
        WITH DESTINATION_TOPIC "energy/openadr/resource/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/openadr3/3.0.1/vens/{value.json.ven_id}/resources/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

Get a token: publish

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"body": "grant_type=client_credentials&client_id=ven_client_99&client_secret=<secret>"}
```

to `energy/openadr/auth/token` and read `access_token` from `energy/openadr/auth/token/response`.

Read the events of one program: publish

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <access_token>", "query": "programID=0&limit=50"}
```

to `energy/openadr/event/list`.

Report measured usage for an event: publish

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <access_token>", "body": {"programID": "0", "eventID": "12", "clientName": "porto-plant", "resources": [{"resourceName": "main-meter", "intervals": [{"id": 0, "payloads": [{"type": "USAGE", "values": [412.5]}]}]}]}}
```

to `energy/openadr/report/create`.

Actions that keep a token and poll events:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the OpenAdr3Vtn route (docs page). Not part of the route template.
# Secrets: OPENADR_TOKEN_REQUEST = "grant_type=client_credentials&client_id=<id>&client_secret=<secret>" (form body
#   for auth/token) and OPENADR_AUTHORIZATION = "Bearer <access_token>" (current token; refresh it before expires_in).
# Program id "0" is a placeholder. Use an id from program/list.
# Inline JSON object literals are not supported when publishing to a topic, so the request payload is a COLLAPSED
#   model sent with PUBLISH MODEL.

DEFINE MODEL OpenAdrRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "id"
    ADD STRING "query"

DEFINE MODEL OpenAdrTokenRequest COLLAPSED
    ADD STRING "body"

DEFINE ACTION OpenAdrTokenHourly
ON EVERY 1 HOUR DO
    PUBLISH MODEL OpenAdrTokenRequest TO "energy/openadr/auth/token" WITH
        body = (GET SECRET "OPENADR_TOKEN_REQUEST")

DEFINE ACTION OpenAdrEventsEvery5Minutes
ON EVERY 5 MINUTES DO
    PUBLISH MODEL OpenAdrRequest TO "energy/openadr/event/list" WITH
        authorization = (GET SECRET "OPENADR_AUTHORIZATION")
        id = ""
        query = "programID=0&limit=50"

DEFINE ACTION OpenAdrProgramsDaily
ON EVERY 1 DAY DO
    PUBLISH MODEL OpenAdrRequest TO "energy/openadr/program/list" WITH
        authorization = (GET SECRET "OPENADR_AUTHORIZATION")
        id = ""
        query = "limit=50"
```

Restrict who can publish to `energy/openadr/#` with a rule, because these payloads carry the client secret and token.

## Notifications (webhooks)

Instead of polling, create a subscription with `subscription/create`. Its `objectOperations[].callbackUrl` points to a Coreflux REST API **server** connector (`ENABLE_SERVER`), and the VTN posts `{"objectType", "operation", "object"}` to it whenever an event, program or report changes. OpenADR 3.1 also lets a VTN publish these notifications to an MQTT broker, which fits a Coreflux broker directly.

## Notes

* **Versions:** this connector follows OpenADR **3.0.1**. OpenADR 3.1.0 (August 2025) keeps the same objects but uses a `targets` query parameter, moves resources to a top-level `/resources` path, and adds `auth/server` and MQTT notifiers. Check which version your VTN runs.
* **Spec source:** the OpenAPI document is published by the OpenADR Alliance (Apache 2.0). A public copy is on [GitHub](https://github.com/grid-coordination/openadr3-specification).
* **Polling:** DR events are usually published hours or a day ahead. Polling `event/list` every 5 minutes is plenty; subscriptions remove the need to poll.


# OpenAI
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/openai

Client-mode REST API connector for OpenAI Responses, Embeddings, and Chat Completions — MQTT into LLM alarm classification and embeddings

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [OpenAI API](https://developers.openai.com/api/reference/) focused on IIoT / edge alarm text into LLMs:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST responses | `POST /v1/responses` | Responses API — classify alarm text; JSON schema / structured output |
| POST embeddings | `POST /v1/embeddings` | Create embeddings (e.g. `text-embedding-3-small`) |
| POST chat/completions | `POST /v1/chat/completions` | Chat Completions; optional `response_format` |
| (supporting) GET models | `GET /v1/models` | List models (checks the token) |
| (supporting) GET model | `GET /v1/models/{model}` | Retrieve one model |

Default `BASE_ADDRESS` is `https://api.openai.com` (no trailing slash). Topics use `ai/openai/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** `Authorization: Bearer &lt;OpenAI API key&gt;`. Prefer Hub secrets (`GET SECRET "OPENAI_API_KEY"`) mapped into MQTT `api_token`. Never commit real `sk-...` keys.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — OpenAI
# Auth: Authorization Bearer {value.json.api_token}
# BASE_ADDRESS: https://api.openai.com

DEFINE CONNECTOR OpenAiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.openai.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PostResponses
        WITH SOURCE_TOPIC "ai/openai/responses/post"
        WITH DESTINATION_TOPIC "ai/openai/responses/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/responses"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT PostEmbeddings
        WITH SOURCE_TOPIC "ai/openai/embeddings/post"
        WITH DESTINATION_TOPIC "ai/openai/embeddings/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/embeddings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT PostChatCompletions
        WITH SOURCE_TOPIC "ai/openai/chat/completions/post"
        WITH DESTINATION_TOPIC "ai/openai/chat/completions/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/chat/completions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
```

## Topics

| Event | Source topic | Destination topic |
| - | - | - |
| PostResponses | `ai/openai/responses/post` | `…/response` |
| PostEmbeddings | `ai/openai/embeddings/post` | `…/response` |
| PostChatCompletions | `ai/openai/chat/completions/post` | `…/response` |
| GetModels | `ai/openai/models/list` | `…/response` |
| GetModel | `ai/openai/models/get` | `…/response` |

## Configuration

1. Set `BASE_ADDRESS` to `https://api.openai.com`.
2. Store an OpenAI API key in Hub secrets (`OPENAI_API_KEY`); map into MQTT `api_token`.
3. For alarm classification: publish to `ai/openai/responses/post` with a Responses body using `text.format` JSON schema (or use Chat Completions with `response_format`).
4. For semantic search / similarity: publish to `ai/openai/embeddings/post` with a tiny `input` string and an embeddings model.
5. Use `GetModels` as a cheap credential check before production workloads.

## References

* [OpenAI API reference](https://developers.openai.com/api/reference/)
* [Responses](https://developers.openai.com/api/reference/resources/responses)
* [Embeddings](https://developers.openai.com/api/reference/resources/embeddings)
* [Chat Completions](https://developers.openai.com/api/reference/resources/chat)
* [Models](https://developers.openai.com/api/reference/resources/models)
* [Official OpenAPI](https://github.com/openai/openai-openapi)


# OpenAQ
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/openaq

Client-mode REST API connector for a curated OpenAQ v3 slice: list locations and read latest measurements

Technical Preview

# OpenAQ

Client-mode REST API connector for a curated OpenAQ v3 slice: list locations and read latest measurements.

* Hub category: **Public data**.
* Base: `https://api.openaq.org`

## Template reference

Generated from the shipped broker template `openaq` (`-connectorCode OPENAQ`). It lists every event the template defines.

### Auth

Auth headers used by the template: `X-API-Key: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the OpenAQ connector | no |
| `BaseUrl` | string | OpenAQ base URL without trailing slash (e.g. [https://api.openaq.org](https://api.openaq.org)) | yes |

`BASE_ADDRESS` default: `https://api.openaq.org`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listlocations` | GET | `/v3/locations` | `public/openaq/locations/list` | `public/openaq/locations/list/response` | `api_token` |
| `Getlatest` | GET | `/v3/locations/{value.json.location_id}/latest` | `public/openaq/locations/latest` | `public/openaq/locations/latest/response` | `api_token`, `location_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode OPENAQ"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OpenAqRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.openaq.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listlocations
        WITH SOURCE_TOPIC "public/openaq/locations/list"
        WITH DESTINATION_TOPIC "public/openaq/locations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/locations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "Bearer {value.json.api_token}"
    ADD EVENT Getlatest
        WITH SOURCE_TOPIC "public/openaq/locations/latest"
        WITH DESTINATION_TOPIC "public/openaq/locations/latest/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/locations/{value.json.location_id}/latest"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listlocations` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'public/openaq/locations/list/response' &
mosquitto_pub -t 'public/openaq/locations/list' -m '{"api_token": "<api_token>"}'
```


# OpenEI
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/openei

Client-mode REST API connector for a curated OpenEI Utility Rates slice: look up rates for an address

Technical Preview

# OpenEI

Client-mode REST API connector for a curated OpenEI Utility Rates slice: look up rates for an address.

* Hub category: **Energy**.
* Base: `https://api.openei.org`

## Template reference

Generated from the shipped broker template `openei` (`-connectorCode OPENEI`). It lists every event the template defines.

### Auth

The template sets no auth header. Check the event headers below.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the OpenEI connector | no |
| `BaseUrl` | string | OpenEI base URL without trailing slash (e.g. [https://api.openei.org](https://api.openei.org)) | yes |

`BASE_ADDRESS` default: `https://api.openei.org`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Getrates` | GET | `/utility_rates?version=8&format=json&api_key={value.json.api_token}&address={value.json.address}` | `energy/openei/rates` | `energy/openei/rates/response` | `address`, `api_token` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode OPENEI"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OpenEiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.openei.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getrates
        WITH SOURCE_TOPIC "energy/openei/rates"
        WITH DESTINATION_TOPIC "energy/openei/rates/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/utility_rates?version=8&format=json&api_key={value.json.api_token}&address={value.json.address}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Getrates` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/openei/rates/response' &
mosquitto_pub -t 'energy/openei/rates' -m '{"address": "<address>", "api_token": "<api_token>"}'
```


# OpenWeatherMap REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/openweathermap

Client-mode REST API connector for current weather, forecast, geocoding, air pollution, and One Call

Technical Preview

## Overview

[OpenWeatherMap](https://openweathermap.org/api) supplies current conditions, a 5-day forecast, geocoding, air pollution, and One Call 3.0. This connector is the expanded form of the weather client example on [REST API Connectors](/latest/lot-language/routes/rest-api-routes): `BASE_ADDRESS` is `https://api.openweathermap.org` and the key travels as the `appid` query parameter.

> [!NOTE]
>
> A call without a valid `appid` returns HTTP 401 (`Invalid API key`). Create a free key in the OpenWeatherMap dashboard and pass it only at runtime.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — OpenWeatherMap
# Generated from OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

DEFINE CONNECTOR OpenweathermapRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.openweathermap.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: pass appid (API key) as query via {value.json.appid} — never hard-code keys.
        # Prefer publishing appid from MQTT JSON, or document GET SECRET for ops that load secrets upstream.
    ADD EVENT Getcurrentweatherbycity
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getcurrentweatherbycity"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getcurrentweatherbycity"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/weather?q={value.json.q}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getcurrentweatherbycoords
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getcurrentweatherbycoords"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getcurrentweatherbycoords"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/weather?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecast5Daybycity
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getforecast5Daybycity"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getforecast5Daybycity"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/forecast?q={value.json.q}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getforecast5Daybycoords
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getforecast5Daybycoords"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getforecast5Daybycoords"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/forecast?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Geocodedirect
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Geocodedirect"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Geocodedirect"
        WITH METHOD "GET"
        WITH ENDPOINT "/geo/1.0/direct?q={value.json.q}&limit={value.json.limit}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Geocodereverse
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Geocodereverse"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Geocodereverse"
        WITH METHOD "GET"
        WITH ENDPOINT "/geo/1.0/reverse?lat={value.json.lat}&lon={value.json.lon}&limit={value.json.limit}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getairpollution
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getairpollution"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getairpollution"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/2.5/air_pollution?lat={value.json.lat}&lon={value.json.lon}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getonecall
        WITH SOURCE_TOPIC "integrations/openweathermap/request/Getonecall"
        WITH DESTINATION_TOPIC "integrations/openweathermap/response/Getonecall"
        WITH METHOD "GET"
        WITH ENDPOINT "/data/3.0/onecall?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getcurrentweatherbycity | GET | `/data/2.5/weather?q={value.json.q}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getcurrentweatherbycity` | `integrations/openweathermap/response/Getcurrentweatherbycity` |
| Getcurrentweatherbycoords | GET | `/data/2.5/weather?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getcurrentweatherbycoords` | `integrations/openweathermap/response/Getcurrentweatherbycoords` |
| Getforecast5Daybycity | GET | `/data/2.5/forecast?q={value.json.q}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getforecast5Daybycity` | `integrations/openweathermap/response/Getforecast5Daybycity` |
| Getforecast5Daybycoords | GET | `/data/2.5/forecast?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getforecast5Daybycoords` | `integrations/openweathermap/response/Getforecast5Daybycoords` |
| Geocodedirect | GET | `/geo/1.0/direct?q={value.json.q}&limit={value.json.limit}&appid={value.json.appid}` | `integrations/openweathermap/request/Geocodedirect` | `integrations/openweathermap/response/Geocodedirect` |
| Geocodereverse | GET | `/geo/1.0/reverse?lat={value.json.lat}&lon={value.json.lon}&limit={value.json.limit}&appid={value.json.appid}` | `integrations/openweathermap/request/Geocodereverse` | `integrations/openweathermap/response/Geocodereverse` |
| Getairpollution | GET | `/data/2.5/air_pollution?lat={value.json.lat}&lon={value.json.lon}&appid={value.json.appid}` | `integrations/openweathermap/request/Getairpollution` | `integrations/openweathermap/response/Getairpollution` |
| Getonecall | GET | `/data/3.0/onecall?lat={value.json.lat}&lon={value.json.lon}&units={value.json.units}&appid={value.json.appid}` | `integrations/openweathermap/request/Getonecall` | `integrations/openweathermap/response/Getonecall` |

## Auth

OpenWeatherMap uses the **`appid` query parameter**, not a Bearer header.

**appid** `string` *required*

API key. Publish it on the MQTT JSON payload as `appid` (`{value.json.appid}`). Load it from a Hub secret. Never commit the key.

**q** `string`

City name for city endpoints, for example `London`.

**units** `string`

`metric`, `imperial`, or `standard`.

Example payload for current weather by city:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"q": "London", "units": "metric", "appid": "YOUR_OPENWEATHERMAP_KEY"}
```

## Try it

1. Add the connector on your broker.
2. Publish the JSON above to `integrations/openweathermap/request/Getcurrentweatherbycity`.
3. Subscribe to `integrations/openweathermap/response/Getcurrentweatherbycity`.
4. Coordinates: publish `lat`, `lon`, `units`, and `appid` to `integrations/openweathermap/request/Getcurrentweatherbycoords`.

> [!NOTE]
>
> A probe of `GET /data/2.5/weather?q=London` with an invalid `appid` returned HTTP 401. That does not replace a call with a real key.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Opsgenie
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/opsgenie

Client-mode REST API connector for a curated Opsgenie Alerts v2 slice: create, get, acknowledge, and close alerts

Technical Preview

# Opsgenie

Client-mode REST API connector for a curated Opsgenie Alerts v2 slice: create, get, acknowledge, and close alerts.

* Hub category: **Monitoring**.
* Base: `https://api.opsgenie.com`

## Template reference

Generated from the shipped broker template `opsgenie` (`-connectorCode OPSGENIE`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: GenieKey {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Opsgenie connector | no |
| `BaseUrl` | string | Opsgenie base URL without trailing slash (e.g. [https://api.opsgenie.com](https://api.opsgenie.com)) | yes |

`BASE_ADDRESS` default: `https://api.opsgenie.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Createalert` | POST | `/v2/alerts` | `monitoring/opsgenie/alerts/create` | `monitoring/opsgenie/alerts/create/response` | `api_token`, `body` |
| `Getalert` | GET | `/v2/alerts/{value.json.alert_id}` | `monitoring/opsgenie/alerts/get` | `monitoring/opsgenie/alerts/get/response` | `alert_id`, `api_token` |
| `Acknowledgealert` | POST | `/v2/alerts/{value.json.alert_id}/acknowledge` | `monitoring/opsgenie/alerts/acknowledge` | `monitoring/opsgenie/alerts/acknowledge/response` | `alert_id`, `api_token`, `body` |
| `Closealert` | POST | `/v2/alerts/{value.json.alert_id}/close` | `monitoring/opsgenie/alerts/close` | `monitoring/opsgenie/alerts/close/response` | `alert_id`, `api_token`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode OPSGENIE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OpsgenieRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.opsgenie.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Createalert
        WITH SOURCE_TOPIC "monitoring/opsgenie/alerts/create"
        WITH DESTINATION_TOPIC "monitoring/opsgenie/alerts/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/alerts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "GenieKey {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getalert
        WITH SOURCE_TOPIC "monitoring/opsgenie/alerts/get"
        WITH DESTINATION_TOPIC "monitoring/opsgenie/alerts/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/alerts/{value.json.alert_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "GenieKey {value.json.api_token}"
    ADD EVENT Acknowledgealert
        WITH SOURCE_TOPIC "monitoring/opsgenie/alerts/acknowledge"
        WITH DESTINATION_TOPIC "monitoring/opsgenie/alerts/acknowledge/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/alerts/{value.json.alert_id}/acknowledge"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "GenieKey {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Closealert
        WITH SOURCE_TOPIC "monitoring/opsgenie/alerts/close"
        WITH DESTINATION_TOPIC "monitoring/opsgenie/alerts/close/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/alerts/{value.json.alert_id}/close"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "GenieKey {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Createalert` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'monitoring/opsgenie/alerts/create/response' &
mosquitto_pub -t 'monitoring/opsgenie/alerts/create' -m '{"api_token": "<api_token>", "body": {}}'
```


# Oracle E-Business Suite (Integrated SOA Gateway)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/oracle-e-business-suite

LoT connector for Oracle E-Business Suite 12.2 via Integrated SOA Gateway: inventory transactions, WIP jobs, quality results and concurrent programs

Technical Preview

## Overview

[Oracle E-Business Suite](https://www.oracle.com/applications/ebusiness/) (EBS) runs inventory, manufacturing (Work in Process) and quality for many plants. Release 12.2 exposes its interfaces as REST services through **Integrated SOA Gateway (ISG)**. Connecting it to the broker lets the shop floor post material transactions as they happen, create or update discrete jobs from a line controller, read work orders, record inspection results against a collection plan, and check which interface rows failed and why.

ISG has no fixed public API. Your integration administrator picks an interface in the **Integration Repository**, gives it a **service alias**, chooses the HTTP methods and deploys it. Each deployed service gets a URL `https://<host>:<port>/webservices/rest/<alias>/<resource>/` and its own WADL. This template covers the interfaces plants use most and leaves the alias as a payload field.

The template has one client-mode connector, `OracleEbsIsg`, with 17 events under `erp/oracle-ebs/`. Each event publishes the reply on `<topic>/response`. Seven events write (POST or PUT).

| Event | Topic | Method | Use |
| - | - | - | - |
| `Login` | `erp/oracle-ebs/auth/login` | GET | Log in with HTTP Basic; returns `accessTokenName` and `accessToken` (fields: `basic`) |
| `InitializeSession` | `erp/oracle-ebs/auth/initialize` | POST | Optional: set responsibility, security group and organization for the session (XML body) (fields: `body`, `cookie`) |
| `Logout` | `erp/oracle-ebs/auth/logout` | GET | End the EBS session behind the cookie (fields: `cookie`) |
| `GetServiceWadl` | `erp/oracle-ebs/service/wadl/get` | GET | WADL of a deployed service: resources, methods and XSD links (fields: `alias`, `cookie`) |
| `GetRestInterface` | `erp/oracle-ebs/service/interface/get` | GET | REST Service Locator: details of a deployed interface by internal name (fields: `alias`, `cookie`, `irepclass`) |
| `InventoryTransactionsCreate` | `erp/oracle-ebs/inventory/transactions/create` | POST | **Write.** Insert material transactions into `MTL_TRANSACTIONS_INTERFACE` (fields: `alias`, `body`, `cookie`) |
| `InventoryTransactionsGet` | `erp/oracle-ebs/inventory/transactions/get` | GET | Read material transaction interface rows, for example failed rows with their errors (fields: `alias`, `cookie`, `query`) |
| `InventoryTransactionsUpdate` | `erp/oracle-ebs/inventory/transactions/update` | PUT | **Write.** Update interface rows that match a filter, for example to resubmit fixed rows (fields: `alias`, `body`, `cookie`) |
| `InventoryTransactionLotsCreate` | `erp/oracle-ebs/inventory/transaction-lots/create` | POST | **Write.** Insert lot rows into `MTL_TRANSACTION_LOTS_INTERFACE` (fields: `alias`, `body`, `cookie`) |
| `WipJobRequestsCreate` | `erp/oracle-ebs/wip/job-requests/create` | POST | **Write.** Request new or updated discrete jobs in `WIP_JOB_SCHEDULE_INTERFACE` (fields: `alias`, `body`, `cookie`) |
| `WipJobRequestsGet` | `erp/oracle-ebs/wip/job-requests/get` | GET | Read job request load status (`PROCESS_PHASE`, `PROCESS_STATUS`) (fields: `alias`, `cookie`, `query`) |
| `WipWorkOrdersGet` | `erp/oracle-ebs/wip/work-orders/get` | GET | Read work orders through the open interface view your administrator deployed (fields: `alias`, `cookie`, `query`, `view`) |
| `QualityResultsCreate` | `erp/oracle-ebs/quality/results/create` | POST | **Write.** Insert quality results for a collection plan into `QA_RESULTS_INTERFACE` (fields: `alias`, `body`, `cookie`) |
| `QualityResultsGet` | `erp/oracle-ebs/quality/results/get` | GET | Read quality import rows and their `PROCESS_STATUS` (fields: `alias`, `cookie`, `query`) |
| `ConcurrentProgramSubmit` | `erp/oracle-ebs/concurrent-program/submit` | POST | **Write.** Run an interface's concurrent program (`SUBMIT_CP_` + program internal name) (fields: `alias`, `body`, `cookie`, `method`) |
| `ServicePost` | `erp/oracle-ebs/service/post` | POST | **Write (may write).** POST to any deployed method, for example a PL/SQL public API (fields: `alias`, `body`, `cookie`, `method`) |
| `ServiceGet` | `erp/oracle-ebs/service/get` | GET | GET any deployed method that supports GET (fields: `alias`, `cookie`, `method`, `params`) |

## Prerequisites

* Oracle E-Business Suite 12.2 with the ISG REST service infrastructure configured (on 12.2 this includes the `$FND_TOP/patch/115/bin/ISGRestSetup.pl` setup script), reachable over HTTPS from the broker.
* The interfaces you need deployed as REST services from the Integration Repository (Integrated SOA Gateway responsibility, Integration Repository, REST Web Service tab):
  * Open interfaces (inbound tables support GET, POST, PUT and DELETE): the Material Transactions Interface (`MTL_TRANSACTIONS_INTERFACE`, lots in `MTL_TRANSACTION_LOTS_INTERFACE`), the WIP Job Schedule Interface (`WIP_JOB_SCHEDULE_INTERFACE`) and the Quality Results Interface (`QA_RESULTS_INTERFACE`). Each table appears as a resource; the interface's concurrent program appears as `SUBMIT_CP_<program internal name>` (POST only).
  * An open interface view (GET only) for reading work orders, if your administrator has one deployed.
  * Optionally the REST Service Locator Java Bean Service (`oracle.apps.fnd.rep.ws.service.EbsRestLocator`) to look up deployed services.
* Both **HTTP Basic** and **Token Based** authentication selected as REST security on those services, and a security grant on each method for the EBS user the broker logs in as.
* Profile option **FND: Authn Service Token Scope** set to **Header and Body** so the login response carries the token in the body (Oracle Doc ID 2938671.1).
* The alias of each deployed service. Open its WADL (`/webservices/rest/<alias>/?WADL`) to see the exact resource names and payload element names.

## Connection and security

Store the login as a broker secret and pass it with `GET SECRET`:

| Secret | Value |
| - | - |
| `EBS_BASIC_AUTH` | `Basic ` + base64 of `user:password` for the EBS user |

1. Publish `{"basic":"Basic ..."}` to `erp/oracle-ebs/auth/login`. ISG answers on `erp/oracle-ebs/auth/login/response` with `data.accessTokenName`, `data.accessToken` (the EBS session ID, also sent as `Set-Cookie`), `data.ebsVersion` and `data.userName`.
2. Pass `"cookie":"<accessTokenName>=<accessToken>"` on every other event. ISG checks the session instead of the password.
3. Optionally publish to `erp/oracle-ebs/auth/initialize` once per session to set the responsibility, security group and organization. Without it, send the context in each request (see Payload).
4. Publish to `erp/oracle-ebs/auth/logout` to end the session. The reply has `accessToken` `-1`.

If token-based security is not enabled on a service, replace the `Cookie` header on its event with `ADD "Authorization" "{value.json.basic}"` and send the Basic value instead.

## Payload

Every service event takes `cookie` and `alias`. Values go into the URL as they are, so URL-encode them first.

* **Application context.** Many EBS APIs need a responsibility and an organization. In POST and PUT bodies put a `RESTHeader` object (`Responsibility`, `RespApplication`, `SecurityGroup`, `NLSLanguage`, `Org_Id`). On GET use the query parameters `ctx_responsibility`, `ctx_respapplication`, `ctx_securitygroup`, `ctx_nlslanguage` and `ctx_orgid`. With token-based security, context sent once is reused by later calls on the same token.
* **`query`** (GET on open interface tables and views): `select=COL1,COL2`, `filter=COL==value;COL2=le=100` (`;` is AND; operators include `==`, `=le=`, `=gt=`), `sort`, and `offset` / `limit` for paging. Pass `""` for no query.
* **`body`** (POST / PUT): a JSON string. For an open interface table the root element is `<TABLE>_Input` with `RESTHeader` and `InputParameters`, and each row is a `<TABLE>_REC` object. PUT updates rows that match a `Filter` inside an `Update` object. For PL/SQL services the root is `<METHOD>_Input`. Take the element names from the service's WADL and XSD.
* **`method`**, **`view`**, **`irepclass`**, **`params`**: the resource segment of the URL where the event leaves it open, for example `SUBMIT_CP_<program>` on `ConcurrentProgramSubmit`, the deployed view name on `WipWorkOrdersGet`, `PLSQL:FND_PROFILE` on `GetRestInterface`.

Material transaction (a row the Inventory Transaction Manager picks up when `PROCESS_FLAG` is 1, `LOCK_FLAG` is 2 and `TRANSACTION_MODE` is 3):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"cookie":"<accessTokenName>=<accessToken>","alias":"<inventory alias>","body":"{\"MTL_TRANSACTIONS_INTERFACE_Input\":{\"RESTHeader\":{\"Responsibility\":\"<responsibility key>\",\"RespApplication\":\"INV\",\"SecurityGroup\":\"STANDARD\",\"NLSLanguage\":\"AMERICAN\",\"Org_Id\":\"<org id>\"},\"InputParameters\":{\"MTL_TRANSACTIONS_INTERFACE_REC\":{\"SOURCE_CODE\":\"COREFLUX\",\"SOURCE_LINE_ID\":\"1\",\"SOURCE_HEADER_ID\":\"1\",\"PROCESS_FLAG\":\"1\",\"LOCK_FLAG\":\"2\",\"TRANSACTION_MODE\":\"3\",\"ORGANIZATION_ID\":\"<org id>\",\"ITEM_SEGMENT1\":\"<item>\",\"TRANSACTION_QUANTITY\":\"-1\",\"TRANSACTION_UOM\":\"<uom>\",\"TRANSACTION_DATE\":\"2026-10-05\",\"SUBINVENTORY_CODE\":\"<subinventory>\",\"TRANSACTION_TYPE_ID\":\"<transaction type id>\"}}}}"}
```

Failed inventory rows:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"cookie":"<accessTokenName>=<accessToken>","alias":"<inventory alias>","query":"filter=PROCESS_FLAG==3&select=TRANSACTION_INTERFACE_ID,SOURCE_CODE,ERROR_CODE,ERROR_EXPLANATION&limit=50"}
```

Job requests use `WIP_JOB_SCHEDULE_INTERFACE` columns such as `GROUP_ID`, `LOAD_TYPE`, `ORGANIZATION_CODE`, `JOB_NAME`, `START_QUANTITY`, `STATUS_TYPE`, `FIRST_UNIT_START_DATE` and `LAST_UNIT_COMPLETION_DATE`; WIP Mass Load reports `PROCESS_PHASE` and `PROCESS_STATUS`. Quality rows use `QA_RESULTS_INTERFACE` columns such as `ORGANIZATION_CODE`, `PLAN_NAME`, `INSERT_TYPE` (1 insert, 2 update with `MATCHING_ELEMENTS`), `PROCESS_STATUS`, `SOURCE_CODE` and the plan's `CHARACTERx` columns.

## Pacing and errors

* Faults come back as `ISGServiceFault` with `Code`, `Message`, `Resolution` and `ServiceDetails`. Open interface writes return `OutputParameters.Summary` (`SuccessCount`, `ErrorCount`) and a `Status` and `Message` for each row.
* Interface rows are only staged. The Inventory Transaction Manager, WIP Mass Load and Collection Import move them to base tables later, so read the interface back (`PROCESS_FLAG`, `PROCESS_STATUS`, `ERROR_EXPLANATION`) before you treat a transaction as posted.
* Open interface GETs page with `offset` and `limit` (the documented sample response reports `Limit` 200). Keep `limit` small and poll on a coarse schedule.
* Long ISG calls can hit web tier timeouts. The template uses a 120-second request timeout.

## Example actions

These log in every 20 minutes, keep the session cookie on a topic, and read failed inventory interface rows every hour.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the Oracle E-Business Suite routes (docs page). Not part of the route template.
# Secret: EBS_BASIC_AUTH = "Basic <base64 of user:password>" for an EBS user with grants on the deployed REST methods.
#   The login response carries data.accessTokenName and data.accessToken; the cookie is "<accessTokenName>=<accessToken>".
#   Inline JSON object literals are not supported when publishing to a topic, so requests use COLLAPSED models sent
#   with PUBLISH MODEL. "invtxn" is an example alias: use the alias your administrator gave the inventory interface.

DEFINE MODEL EbsLoginRequest COLLAPSED
    ADD STRING "basic"

DEFINE MODEL EbsQueryRequest COLLAPSED
    ADD STRING "cookie"
    ADD STRING "alias"
    ADD STRING "query"

DEFINE ACTION EbsLoginEvery20Minutes
ON EVERY 20 MINUTES DO
    PUBLISH MODEL EbsLoginRequest TO "erp/oracle-ebs/auth/login" WITH
        basic = (GET SECRET "EBS_BASIC_AUTH")

DEFINE ACTION EbsKeepCookie
ON TOPIC "erp/oracle-ebs/auth/login/response" DO
    SET "name" WITH GET JSON "data.accessTokenName" IN PAYLOAD AS STRING
    SET "token" WITH GET JSON "data.accessToken" IN PAYLOAD AS STRING
    KEEP TOPIC "erp/oracle-ebs/state/cookie" WITH {name} + "=" + {token}

DEFINE ACTION EbsFailedInventoryTransactionsEveryHour
ON EVERY 1 HOUR DO
    SET "cookie" WITH GET TOPIC "erp/oracle-ebs/state/cookie" AS STRING
    PUBLISH MODEL EbsQueryRequest TO "erp/oracle-ebs/inventory/transactions/get" WITH
        cookie = {cookie}
        alias = "invtxn"
        query = "filter=PROCESS_FLAG==3&select=TRANSACTION_INTERFACE_ID,SOURCE_CODE,ERROR_CODE,ERROR_EXPLANATION&limit=50"
```

## Connector template

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Oracle E-Business Suite 12.2 (Integrated SOA Gateway REST services) for plants:
#   post inventory material transactions (+ lots) through the Material Transactions Interface, create / update
#   discrete jobs through the WIP Job Schedule (Work Order) Interface, read work orders through a deployed Interface
#   View, import quality results through the Quality Results (Collection Import) Interface, read back interface rows
#   and their errors, submit the associated concurrent programs, and call any other deployed ISG REST service.
#   Guide 12.2 (E20927: REST messages, WADL, PL/SQL / Java Bean / Open Interface REST services), Implementation Guide
#   (E20925: REST security, deploying REST services), User's Guide (E20923: Integration Repository), Mobile Apps
#   Developer's Guide (E69284: login / initialize / logout services), Oracle eTRM 12.2 table definitions (via etrm.live).
#   interface from the Integration Repository by your integration administrator and described by its own WADL, so
#   events are hand-curated from the documented URL patterns.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/oracle-e-business-suite
#
# One route, topic prefix erp/oracle-ebs/:
#   OracleEbsIsg  https://ebs.example.com  (your EBS web entry point, add :port; all paths start /webservices/rest/)
# URLs: /webservices/rest/<service alias>/<resource>/ . The alias is chosen when the interface is deployed (REST Web
#   Service tab, Integration Repository); the resource is the method name for PL/SQL / Java services, the table or
#   view name for open interfaces, and SUBMIT_CP_<concurrent program internal name> for the interface's program.
#   Pass the alias in every payload ("alias"). The WADL for a deployed service is /webservices/rest/<alias>/?WADL.
# Auth: HTTP Basic or token-based (both must be selected as REST security when the service is deployed).
#   GET /webservices/rest/login with "Authorization: Basic base64(user:password)" returns accessTokenName +
#   accessToken (EBS session id, also in Set-Cookie). Send "Cookie: <accessTokenName>=<accessToken>" on later
#   calls (payload field "cookie"); /webservices/rest/logout ends the session. Keep the Basic value in broker secret
#   EBS_BASIC_AUTH and pass it with GET SECRET. EBS 12.2 needs profile "FND: Authn Service Token Scope" = Header and
#   Body for the token in the login body (Oracle Doc ID 2938671.1). The user needs a grant on each deployed method.
# App context: pass Responsibility / RespApplication / SecurityGroup / NLSLanguage / Org_Id in "RESTHeader" in POST /
#   PUT bodies, as ctx_responsibility / ctx_respapplication / ctx_securitygroup / ctx_nlslanguage / ctx_orgid query
#   parameters on GET, or once per session with POST /webservices/rest/initialize.
# Open interface GET query: select=COL1,COL2&filter=COL==value;COL2=le=100&sort=...&offset=0&limit=200 (URL-encoded).
# Errors: JSON / XML ISGServiceFault {Code, Message, Resolution, ServiceDetails}; per-row Status / Message in
#   OutputParameters.Result.Output for open interface writes.
# Writes (# WRITE): rows inserted / updated in interface tables are only staged until the interface program
#   (Inventory Transaction Manager, WIP Mass Load, Collection Import Manager) moves them to base tables.
# Not packaged: DELETE on interface tables, SOAP services, business events, XML Gateway, Oracle Integration EBS adapter.
#
# Payload fields (JSON on the source topic): cookie on every event except Login; alias on every service event;
#   query (URL-encoded GET query, or "" for none); body (JSON string) on POST / PUT; method / view / irepclass /
#   params where the endpoint names them.
#     Login                        {"basic":"Basic <base64 user:password>"}
#     InventoryTransactionsCreate  {"cookie":"demo=...","alias":"invtxn","body":"{\"MTL_TRANSACTIONS_INTERFACE_Input\":{...}}"}
#     InventoryTransactionsGet     {"cookie":"demo=...","alias":"invtxn","query":"filter=PROCESS_FLAG==3&select=TRANSACTION_INTERFACE_ID,ERROR_CODE,ERROR_EXPLANATION&limit=50"}
#     WipWorkOrdersGet             {"cookie":"demo=...","alias":"wipjobs","view":"<deployed interface view>","query":"filter=ORGANIZATION_ID==207&limit=50"}
#     ConcurrentProgramSubmit      {"cookie":"demo=...","alias":"wipjobs","method":"SUBMIT_CP_<program>","body":"{...}"}

DEFINE CONNECTOR OracleEbsIsg WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://ebs.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Replace with your EBS web entry point (https://<host>:<port>). Long ISG calls may need a higher timeout.
    # AOL security Login service: HTTP Basic login. Returns data.accessTokenName + data.accessToken (EBS session id, also in Set-Cookie). Build cookie = accessTokenName=accessToken.
    ADD EVENT Login
        WITH SOURCE_TOPIC "erp/oracle-ebs/auth/login"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/auth/login/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.basic}"
    # AOL security Initialize service: Optional. Sets responsibility / security group / org context for the session. body (XML): <data><resp><key>..</key><applKey>..</applKey></resp><securityGroup><key>STANDARD</key></securityGroup><org><id>..</id></org></data>
    ADD EVENT InitializeSession
        WITH SOURCE_TOPIC "erp/oracle-ebs/auth/initialize"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/auth/initialize/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webservices/rest/initialize"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/xml"
        WITH BODY "{value.json.body}"
    # AOL security Logout service: Invalidates the EBS session behind the cookie (response accessToken -1).
    ADD EVENT Logout
        WITH SOURCE_TOPIC "erp/oracle-ebs/auth/logout"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/auth/logout/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/logout"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
    # Deployed REST service: WADL of a deployed service (resources, methods, XSD links). Use it to check paths and payload element names.
    ADD EVENT GetServiceWadl
        WITH SOURCE_TOPIC "erp/oracle-ebs/service/wadl/get"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/service/wadl/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/?WADL"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
    # REST Service Locator (Java Bean Service oracle.apps.fnd.rep.ws.service.EbsRestLocator): Details of a deployed REST interface by internal name, for example PLSQL:FND_PROFILE. Needs the locator deployed (doc alias servicelocator).
    ADD EVENT GetRestInterface
        WITH SOURCE_TOPIC "erp/oracle-ebs/service/interface/get"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/service/interface/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/getRestInterface/{value.json.irepclass}/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
    # Open interface: Material Transactions Interface (MTL_TRANSACTIONS_INTERFACE): WRITE: insert material transactions (issues, receipts, transfers, WIP completions). Rows with PROCESS_FLAG 1, LOCK_FLAG 2, TRANSACTION_MODE 3 are picked up by the Inventory Transaction Manager.
    ADD EVENT InventoryTransactionsCreate
        WITH SOURCE_TOPIC "erp/oracle-ebs/inventory/transactions/create"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/inventory/transactions/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/MTL_TRANSACTIONS_INTERFACE/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Open interface: Material Transactions Interface (MTL_TRANSACTIONS_INTERFACE): Read interface rows not yet processed or failed (PROCESS_FLAG 3 + ERROR_CODE / ERROR_EXPLANATION). query: select / filter / sort / offset / limit.
    ADD EVENT InventoryTransactionsGet
        WITH SOURCE_TOPIC "erp/oracle-ebs/inventory/transactions/get"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/inventory/transactions/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/MTL_TRANSACTIONS_INTERFACE/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
    # Open interface: Material Transactions Interface (MTL_TRANSACTIONS_INTERFACE): WRITE: update interface rows by Filter, for example reset failed rows to PROCESS_FLAG 1 / LOCK_FLAG 2 after fixing data.
    ADD EVENT InventoryTransactionsUpdate
        WITH SOURCE_TOPIC "erp/oracle-ebs/inventory/transactions/update"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/inventory/transactions/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/MTL_TRANSACTIONS_INTERFACE/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Open interface: Material Transactions Interface lots (MTL_TRANSACTION_LOTS_INTERFACE): WRITE: lot rows for lot-controlled items, linked by TRANSACTION_INTERFACE_ID. Only if the table is a method of your deployed inventory interface.
    ADD EVENT InventoryTransactionLotsCreate
        WITH SOURCE_TOPIC "erp/oracle-ebs/inventory/transaction-lots/create"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/inventory/transaction-lots/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/MTL_TRANSACTION_LOTS_INTERFACE/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Open interface: WIP Job Schedule (Work Order) Interface (WIP_JOB_SCHEDULE_INTERFACE): WRITE: requests to create or update discrete jobs / repetitive schedules (LOAD_TYPE, GROUP_ID, JOB_NAME, START_QUANTITY, dates). WIP Mass Load processes them.
    ADD EVENT WipJobRequestsCreate
        WITH SOURCE_TOPIC "erp/oracle-ebs/wip/job-requests/create"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/wip/job-requests/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/WIP_JOB_SCHEDULE_INTERFACE/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Open interface: WIP Job Schedule (Work Order) Interface (WIP_JOB_SCHEDULE_INTERFACE): Read load status of job requests (PROCESS_PHASE, PROCESS_STATUS, WIP_ENTITY_ID) by GROUP_ID / JOB_NAME.
    ADD EVENT WipJobRequestsGet
        WITH SOURCE_TOPIC "erp/oracle-ebs/wip/job-requests/get"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/wip/job-requests/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/WIP_JOB_SCHEDULE_INTERFACE/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
    # Open interface view (GET only): Read work orders through the Interface View your administrator deployed (view = the view name shown as the resource in its WADL). query: select / filter / sort / offset / limit.
    ADD EVENT WipWorkOrdersGet
        WITH SOURCE_TOPIC "erp/oracle-ebs/wip/work-orders/get"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/wip/work-orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/{value.json.view}/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
    # Open interface: Quality Results Interface (QA_RESULTS_INTERFACE, collection import): WRITE: quality results for a collection plan (ORGANIZATION_CODE, PLAN_NAME, INSERT_TYPE 1 insert / 2 update + MATCHING_ELEMENTS, CHARACTERx values). Collection Import moves them to QA_RESULTS.
    ADD EVENT QualityResultsCreate
        WITH SOURCE_TOPIC "erp/oracle-ebs/quality/results/create"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/quality/results/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/QA_RESULTS_INTERFACE/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Open interface: Quality Results Interface (QA_RESULTS_INTERFACE, collection import): Read import status of quality rows (PROCESS_STATUS, GROUP_ID) by PLAN_NAME / SOURCE_CODE.
    ADD EVENT QualityResultsGet
        WITH SOURCE_TOPIC "erp/oracle-ebs/quality/results/get"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/quality/results/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/QA_RESULTS_INTERFACE/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
    # Open interface / concurrent program REST service: WRITE: run the interface's concurrent program (method SUBMIT_CP_<program internal name>, POST only), for example the import program of a deployed open interface.
    ADD EVENT ConcurrentProgramSubmit
        WITH SOURCE_TOPIC "erp/oracle-ebs/concurrent-program/submit"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/concurrent-program/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/{value.json.method}/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Any deployed PL/SQL, Java Bean, Application Module or Business Service Object REST service: WRITE (may write): POST {<METHOD>_Input:{RESTHeader:{...},InputParameters:{...}}} to a deployed method, for example a PL/SQL public API.
    ADD EVENT ServicePost
        WITH SOURCE_TOPIC "erp/oracle-ebs/service/post"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/service/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/{value.json.method}/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Any deployed REST service with a GET method: GET a deployed method. params: path variables + query, for example PLSQL:FND_PROFILE/ or ?ctx_orgid=204&offset=0&limit=5.
    ADD EVENT ServiceGet
        WITH SOURCE_TOPIC "erp/oracle-ebs/service/get"
        WITH DESTINATION_TOPIC "erp/oracle-ebs/service/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/webservices/rest/{value.json.alias}/{value.json.method}/{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Cookie" "{value.json.cookie}"
```

## Not packaged

* DELETE on interface tables, SOAP services, business events, XML Gateway messages and the Oracle Integration (OIC) E-Business Suite adapter.
* Fixed paths for PL/SQL public APIs: deploy the API you need and call it with `ServicePost` / `ServiceGet`.


# Oracle Fusion Cloud ERP and SCM
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/oracle-fusion-erp

LoT connector for Oracle Fusion Cloud SCM: manufacturing work orders, operation completions, on-hand inventory balances and maintenance work orders

Technical Preview

## Overview

A client-mode connector for a **curated manufacturing, inventory, and maintenance** slice of [Oracle Fusion Cloud SCM REST APIs](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/index.html) under `/fscmRestApi/resources/latest` (or a fixed version such as `11.13.18.05`):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET workOrders | `workOrders` | Manufacturing work orders |
| POST workOrderOperationTransactions (completion) | `operationTransactions` | Official resource name; dispatch-state / completion |
| GET inventoryOnhandBalances | `inventoryOnhandBalances` | On-hand by org / subinventory / locator |
| POST maintenanceWorkOrders | `maintenanceWorkOrders` | Create maintenance work orders |

`BASE_ADDRESS` is the Fusion SCM resources root (`https://{server}.fa.{region}.oraclecloud.com/fscmRestApi/resources/latest`). Topics use `erp/oracle-fusion-erp/<object>/<verb>`.

> [!NOTE]
>
> Fusion REST APIs require a real tenant and either Basic credentials or an OAuth / JWT Bearer token. Prefer Hub secrets for passwords and tokens. Append `/describe?metadata-format=openapi` on a resource to pull tenant OpenAPI.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Oracle Fusion Cloud ERP and SCM (curated MFG / inventory / maintenance slice)
# Auth: Bearer {value.json.access_token} OR Basic WITH USERNAME / WITH PASSWORD GET SECRET
# BASE_ADDRESS: https://YOUR_SERVER.fa.YOUR_REGION.oraclecloud.com/fscmRestApi/resources/latest

DEFINE CONNECTOR OracleFusionErpRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_SERVER.fa.YOUR_REGION.oraclecloud.com/fscmRestApi/resources/latest"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getworkorders
        WITH SOURCE_TOPIC "erp/oracle-fusion-erp/work-orders/get"
        WITH DESTINATION_TOPIC "erp/oracle-fusion-erp/work-orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/workOrders?limit={value.json.limit}&onlyData=true&fields=WorkOrderId,WorkOrderNumber,OrganizationCode,WorkOrderStatusCode,ItemNumber,PlannedStartQuantity,PlannedStartDate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/vnd.oracle.adf.resourceitem+json"
            ADD "REST-Framework-Version" "4"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createworkorderoperationtransaction
        WITH SOURCE_TOPIC "erp/oracle-fusion-erp/operation-transactions/create"
        WITH DESTINATION_TOPIC "erp/oracle-fusion-erp/operation-transactions/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/operationTransactions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/vnd.oracle.adf.resourceitem+json"
            ADD "REST-Framework-Version" "4"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getinventoryonhandbalances
        WITH SOURCE_TOPIC "erp/oracle-fusion-erp/inventory-onhand/get"
        WITH DESTINATION_TOPIC "erp/oracle-fusion-erp/inventory-onhand/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/inventoryOnhandBalances?limit={value.json.limit}&onlyData=true&fields=OrganizationCode,ItemNumber,SubinventoryCode,PrimaryQuantity"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/vnd.oracle.adf.resourceitem+json"
            ADD "REST-Framework-Version" "4"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createmaintenanceworkorder
        WITH SOURCE_TOPIC "erp/oracle-fusion-erp/maintenance-work-orders/create"
        WITH DESTINATION_TOPIC "erp/oracle-fusion-erp/maintenance-work-orders/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/maintenanceWorkOrders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/vnd.oracle.adf.resourceitem+json"
            ADD "REST-Framework-Version" "4"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getworkorders | GET | `/workOrders` | `erp/oracle-fusion-erp/work-orders/get` | `erp/oracle-fusion-erp/work-orders/get/response` |
| Createworkorderoperationtransaction | POST | `/operationTransactions` | `erp/oracle-fusion-erp/operation-transactions/create` | `erp/oracle-fusion-erp/operation-transactions/create/response` |
| Getinventoryonhandbalances | GET | `/inventoryOnhandBalances` | `erp/oracle-fusion-erp/inventory-onhand/get` | `erp/oracle-fusion-erp/inventory-onhand/get/response` |
| Createmaintenanceworkorder | POST | `/maintenanceWorkOrders` | `erp/oracle-fusion-erp/maintenance-work-orders/create` | `erp/oracle-fusion-erp/maintenance-work-orders/create/response` |

## Auth

**Option A — OAuth / JWT Bearer (default in the template):**

Pass the access token on the MQTT request payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_FUSION_ACCESS_TOKEN", "limit": 10}
```

The connector sends `Authorization: Bearer {value.json.access_token}`. Obtain the token via OCI IAM JWT user assertion for Fusion Applications, or Fusion's token-relay endpoint after SSO.

**Option B — Basic over SSL:**

In `REST_API_CONFIG`, uncomment:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH USERNAME "YOUR_FUSION_USER"
WITH PASSWORD GET SECRET "ORACLE_FUSION_PASSWORD"
```

Prefer Hub secrets / `GET SECRET`. Never commit real passwords or tokens.

## Example requests

### List manufacturing work orders

Publish to `erp/oracle-fusion-erp/work-orders/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_FUSION_ACCESS_TOKEN", "limit": 10}
```

### Report operation completion

Publish to `erp/oracle-fusion-erp/operation-transactions/create` with a body shaped from your tenant `/operationTransactions/describe`. Minimal illustrative shape:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_FUSION_ACCESS_TOKEN",
  "payload": {
    "SourceSystemCode": "EXTERNAL",
    "OperationTransactionDetail": [
      {
        "SourceSystemCode": "EXTERNAL",
        "OrganizationCode": "M1",
        "WorkOrderNumber": "WO-PLACEHOLDER",
        "WoOperationSequenceNumber": 10,
        "FromDispatchState": "READY",
        "ToDispatchState": "COMPLETE",
        "TransactionDate": "2026-10-03T12:00:00+00:00",
        "TransactionQuantity": 1
      }
    ]
  }
}
```

### Inventory on-hand

Publish to `erp/oracle-fusion-erp/inventory-onhand/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_FUSION_ACCESS_TOKEN", "limit": 25}
```

### Create maintenance work order

Publish to `erp/oracle-fusion-erp/maintenance-work-orders/create` with a body from `/maintenanceWorkOrders/describe`.

## Configuration notes

| Setting | Value |
| - | - |
| `BASE_ADDRESS` | `https://{server}.fa.{region}.oraclecloud.com/fscmRestApi/resources/latest` |
| SSL | Required (`USE_SSL true`) |
| Content-Type | `application/vnd.oracle.adf.resourceitem+json` (ADF REST) |
| Version alias | `latest` or fixed `11.13.18.05` |
| Status | Technical preview |

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Oracle Fusion Cloud SCM REST API](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/26b/fasrp/index.html)
* [Applications Common Quick Start (auth)](https://docs.oracle.com/en/cloud/saas/applications-common/26c/farca/Quick_Start.html)


# Oracle JD Edwards EnterpriseOne
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/oracle-jd-edwards

Client-mode REST API connector for the JD Edwards EnterpriseOne AIS Server: token login and validation plus Orchestrator calls and data service queries

Technical Preview

## Overview

Client-mode REST API connector for the JD Edwards EnterpriseOne AIS Server: token login and validation plus Orchestrator calls and data service queries. `BASE_ADDRESS` defaults to `https://YOUR_AIS_SERVER:PORT`. Topics use `erp/jd-edwards/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `JdeLogin` | `POST /jderest/v3/orchestrator/jde-login` | `erp/jd-edwards/auth/login` |
| `JdeValidateSession` | `GET /jderest/v3/orchestrator/jde-validate-session` | `erp/jd-edwards/auth/validate` |
| `JdeLogout` | `POST /jderest/v3/orchestrator/jde-logout` | `erp/jd-edwards/auth/logout` |
| `OrchestrationRun` | `POST /jderest/v3/orchestrator/{value.json.orchestration}` | `erp/jd-edwards/orchestration/run` |
| `OrchestrationGet` | `GET /jderest/v3/orchestrator/{value.json.orchestration}?{value.json.query}` | `erp/jd-edwards/orchestration/get` |
| `DataServiceQuery` | `POST /jderest/v2/dataservice` | `erp/jd-edwards/dataservice/query` |

## Authentication

AIS token. JdeLogin sends HTTP Basic (Authorization: \{value.json.authorization}, i.e. "Basic base64(user:password)") with optional jde-AIS-Auth-Environment / -Role / -Device headers and returns userInfo.token. All other events send that token as jde-AIS-Auth: \{value.json.ais\_token}. Tools 9.2.4+ for header authentication.

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* The AIS Server is customer-hosted (on-premises or OCI); replace BASE\_ADDRESS with your AIS URL. Orchestrations are built by the customer in Orchestrator Studio, so the orchestration name and its inputs are site-specific.
* If the token was requested with jde-AIS-Auth-Device, every later call must send the same device; add the header in a fork if you use it.
* Call JdeLogout when done; AIS sessions also hold an HTML Server session until timeout.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OracleJdEdwardsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_AIS_SERVER:PORT"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT JdeLogin
        WITH SOURCE_TOPIC "erp/jd-edwards/auth/login"
        WITH DESTINATION_TOPIC "erp/jd-edwards/auth/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jderest/v3/orchestrator/jde-login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "jde-AIS-Auth-Environment" "{value.json.environment}"
            ADD "jde-AIS-Auth-Role" "{value.json.role}"
        WITH BODY ""
    ADD EVENT JdeValidateSession
        WITH SOURCE_TOPIC "erp/jd-edwards/auth/validate"
        WITH DESTINATION_TOPIC "erp/jd-edwards/auth/validate/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jderest/v3/orchestrator/jde-validate-session"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "jde-AIS-Auth" "{value.json.ais_token}"
    ADD EVENT JdeLogout
        WITH SOURCE_TOPIC "erp/jd-edwards/auth/logout"
        WITH DESTINATION_TOPIC "erp/jd-edwards/auth/logout/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jderest/v3/orchestrator/jde-logout"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "jde-AIS-Auth" "{value.json.ais_token}"
        WITH BODY ""
    ADD EVENT OrchestrationRun
        WITH SOURCE_TOPIC "erp/jd-edwards/orchestration/run"
        WITH DESTINATION_TOPIC "erp/jd-edwards/orchestration/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jderest/v3/orchestrator/{value.json.orchestration}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "jde-AIS-Auth" "{value.json.ais_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT OrchestrationGet
        WITH SOURCE_TOPIC "erp/jd-edwards/orchestration/get"
        WITH DESTINATION_TOPIC "erp/jd-edwards/orchestration/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jderest/v3/orchestrator/{value.json.orchestration}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "jde-AIS-Auth" "{value.json.ais_token}"
    ADD EVENT DataServiceQuery
        WITH SOURCE_TOPIC "erp/jd-edwards/dataservice/query"
        WITH DESTINATION_TOPIC "erp/jd-edwards/dataservice/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jderest/v2/dataservice"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "jde-AIS-Auth" "{value.json.ais_token}"
        WITH BODY "{value.json.body}"
```

## Sources

* [https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/index.html](https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/index.html)
* [https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/Authentication.html](https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/Authentication.html)
* [https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/api-orchestrator-service.html](https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/api-orchestrator-service.html)
* [https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/op-v3-orchestrator-jde-login-post.html](https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/op-v3-orchestrator-jde-login-post.html)
* [https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/op-v3-orchestrator-orchestration-post.html](https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/op-v3-orchestrator-orchestration-post.html)
* [https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/op-v2-dataservice-post.html](https://docs.oracle.com/en/applications/jd-edwards/cross-product/9.2/rest-api/op-v2-dataservice-post.html)


# Osm Nominatim
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/osm-nominatim

LoT connector for OpenStreetMap Nominatim with no API key: search and structured geocoding, reverse geocoding, OSM ID lookup and server status

Technical Preview

## Overview

Client-mode REST API connectors for OpenStreetMap with no API key: Nominatim geocoding, reverse geocoding and OSM lookup, and OSRM routing, nearest road, duration matrix, GPS map matching and trip ordering, on the public servers or self-hosted.

This is one of the templates in the OpenStreetMap: Nominatim and OSRM (self-hostable) REST API app (`openstreetmap-nominatim-and-osrm`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["none"]
* **secrets**: \[]
* **note**: Nominatim usage policy: max 1 req/s, identifying User-Agent, no bulk geocoding, ODbL attribution

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Osm Nominatim connector | no |
| `BaseUrl` | string | Osm Nominatim base URL without trailing slash (e.g. [https://nominatim.openstreetmap.org](https://nominatim.openstreetmap.org)) | yes |

`BASE_ADDRESS` default: `https://nominatim.openstreetmap.org`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `NominatimSearch` | GET | `/search?format=jsonv2&q={value.json.q}{value.json.params}` | `fleet/osm/nominatim/search/get` | `fleet/osm/nominatim/search/get/response` | `params`, `q` |
| `NominatimStructured` | GET | `/search?format=jsonv2&street={value.json.street}&city={value.json.city}&postalcode={value.json.postalcode}&country={value.json.country}{value.json.params}` | `fleet/osm/nominatim/structured/get` | `fleet/osm/nominatim/structured/get/response` | `city`, `country`, `params`, `postalcode`, `street` |
| `NominatimReverse` | GET | `/reverse?format=jsonv2&lat={value.json.lat}&lon={value.json.lon}{value.json.params}` | `fleet/osm/nominatim/reverse/get` | `fleet/osm/nominatim/reverse/get/response` | `lat`, `lon`, `params` |
| `NominatimLookup` | GET | `/lookup?format=jsonv2&osm_ids={value.json.osm_ids}{value.json.params}` | `fleet/osm/nominatim/lookup/get` | `fleet/osm/nominatim/lookup/get/response` | `osm_ids`, `params` |
| `NominatimStatus` | GET | `/status?format=json` | `fleet/osm/nominatim/status/get` | `fleet/osm/nominatim/status/get/response` | none |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode OSM_NOMINATIM"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OsmNominatim WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://nominatim.openstreetmap.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT NominatimSearch
        WITH SOURCE_TOPIC "fleet/osm/nominatim/search/get"
        WITH DESTINATION_TOPIC "fleet/osm/nominatim/search/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/search?format=jsonv2&q={value.json.q}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT NominatimStructured
        WITH SOURCE_TOPIC "fleet/osm/nominatim/structured/get"
        WITH DESTINATION_TOPIC "fleet/osm/nominatim/structured/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/search?format=jsonv2&street={value.json.street}&city={value.json.city}&postalcode={value.json.postalcode}&country={value.json.country}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT NominatimReverse
        WITH SOURCE_TOPIC "fleet/osm/nominatim/reverse/get"
        WITH DESTINATION_TOPIC "fleet/osm/nominatim/reverse/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/reverse?format=jsonv2&lat={value.json.lat}&lon={value.json.lon}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT NominatimLookup
        WITH SOURCE_TOPIC "fleet/osm/nominatim/lookup/get"
        WITH DESTINATION_TOPIC "fleet/osm/nominatim/lookup/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/lookup?format=jsonv2&osm_ids={value.json.osm_ids}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT NominatimStatus
        WITH SOURCE_TOPIC "fleet/osm/nominatim/status/get"
        WITH DESTINATION_TOPIC "fleet/osm/nominatim/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/status?format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `NominatimSearch` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/osm/nominatim/search/get/response' &
mosquitto_pub -t 'fleet/osm/nominatim/search/get' -m '{"params": "<params>", "q": "<q>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Osm Osrm
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/osm-osrm

LoT connector for the OSRM routing engine with no API key: routes, nearest road, duration matrices, GPS map matching and trip ordering

Technical Preview

## Overview

Client-mode REST API connectors for OpenStreetMap with no API key: Nominatim geocoding, reverse geocoding and OSM lookup, and OSRM routing, nearest road, duration matrix, GPS map matching and trip ordering, on the public servers or self-hosted.

This is one of the templates in the OpenStreetMap: Nominatim and OSRM (self-hostable) REST API app (`openstreetmap-nominatim-and-osrm`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["none"]
* **secrets**: \[]
* **note**: Nominatim usage policy: max 1 req/s, identifying User-Agent, no bulk geocoding, ODbL attribution

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Osm Osrm connector | no |
| `BaseUrl` | string | Osm Osrm base URL without trailing slash (e.g. [https://router.project-osrm.org](https://router.project-osrm.org)) | yes |

`BASE_ADDRESS` default: `https://router.project-osrm.org`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `OsrmRoute` | GET | `/route/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}` | `fleet/osm/osrm/route/get` | `fleet/osm/osrm/route/get/response` | `coordinates`, `params`, `profile` |
| `OsrmNearest` | GET | `/nearest/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}` | `fleet/osm/osrm/nearest/get` | `fleet/osm/osrm/nearest/get/response` | `coordinates`, `params`, `profile` |
| `OsrmTable` | GET | `/table/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}` | `fleet/osm/osrm/table/get` | `fleet/osm/osrm/table/get/response` | `coordinates`, `params`, `profile` |
| `OsrmMatch` | GET | `/match/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}` | `fleet/osm/osrm/match/get` | `fleet/osm/osrm/match/get/response` | `coordinates`, `params`, `profile` |
| `OsrmTrip` | GET | `/trip/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}` | `fleet/osm/osrm/trip/get` | `fleet/osm/osrm/trip/get/response` | `coordinates`, `params`, `profile` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode OSM_OSRM"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OsmOsrm WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://router.project-osrm.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT OsrmRoute
        WITH SOURCE_TOPIC "fleet/osm/osrm/route/get"
        WITH DESTINATION_TOPIC "fleet/osm/osrm/route/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/route/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT OsrmNearest
        WITH SOURCE_TOPIC "fleet/osm/osrm/nearest/get"
        WITH DESTINATION_TOPIC "fleet/osm/osrm/nearest/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/nearest/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT OsrmTable
        WITH SOURCE_TOPIC "fleet/osm/osrm/table/get"
        WITH DESTINATION_TOPIC "fleet/osm/osrm/table/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/table/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT OsrmMatch
        WITH SOURCE_TOPIC "fleet/osm/osrm/match/get"
        WITH DESTINATION_TOPIC "fleet/osm/osrm/match/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/match/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT OsrmTrip
        WITH SOURCE_TOPIC "fleet/osm/osrm/trip/get"
        WITH DESTINATION_TOPIC "fleet/osm/osrm/trip/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/trip/v1/{value.json.profile}/{value.json.coordinates}?generate_hints=false{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `OsrmRoute` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/osm/osrm/route/get/response' &
mosquitto_pub -t 'fleet/osm/osrm/route/get' -m '{"coordinates": "<coordinates>", "params": "<params>", "profile": "<profile>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# PagerDuty
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/pagerduty

Client-mode REST API connector for a curated PagerDuty slice: Events API v2 trigger/resolve from alarms, list incidents by status, and add incident notes

Technical Preview

## Overview

A client-mode connector for a **curated ITSM / alerting** slice of [PagerDuty Events API v2](https://docs.pagerduty.com/developer/events-api-v2-overview) and the [REST API](https://docs.pagerduty.com/developer/api/reference/rest/incidents):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST v2/enqueue trigger | `POST /v2/enqueue` | **Host:** `https://events.pagerduty.com` — `event_action=trigger` + `routing_key` in body |
| POST v2/enqueue resolve | `POST /v2/enqueue` | Same host/path; `event_action=resolve` + `dedup_key` |
| GET incidents?statuses\[]= | `GET /incidents?statuses[]={status}` | **Host:** `https://api.pagerduty.com` — Token or OAuth |
| POST incidents/\{id}/notes | `POST /incidents/{id}/notes` | Requires `From` header (user email) |

Default `BASE_ADDRESS` is `https://api.pagerduty.com`. Topics use `itsm/pagerduty/<object>/<verb>`.

> [!NOTE]
>
> Events enqueue is **not** on `api.pagerduty.com`. Official path is `https://events.pagerduty.com/v2/enqueue`. When calling `Enqueuetrigger` / `Enqueueresolve`, set connector `BASE_ADDRESS` to `https://events.pagerduty.com` (or deploy a second connector copy). Auth for Events is the `routing_key` field in the JSON body, not an Authorization header.

> [!NOTE]
>
> Prefer Hub secrets for API tokens and routing keys.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — PagerDuty (Events API v2 + REST curated slice)
# Auth REST: Token token={value.json.token} (or Bearer access_token)
# Auth Events: routing_key in JSON body
# BASE_ADDRESS REST: https://api.pagerduty.com
# Events: set BASE_ADDRESS to https://events.pagerduty.com

DEFINE CONNECTOR PagerDutyRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.pagerduty.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Enqueuetrigger
        WITH SOURCE_TOPIC "itsm/pagerduty/event/trigger"
        WITH DESTINATION_TOPIC "itsm/pagerduty/event/trigger/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/enqueue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Enqueueresolve
        WITH SOURCE_TOPIC "itsm/pagerduty/event/resolve"
        WITH DESTINATION_TOPIC "itsm/pagerduty/event/resolve/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/enqueue"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Listincidents
        WITH SOURCE_TOPIC "itsm/pagerduty/incident/list"
        WITH DESTINATION_TOPIC "itsm/pagerduty/incident/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/incidents?statuses[]={value.json.status}&limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/vnd.pagerduty+json;version=2"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Token token={value.json.token}"
    ADD EVENT Createincidentnote
        WITH SOURCE_TOPIC "itsm/pagerduty/incident/note"
        WITH DESTINATION_TOPIC "itsm/pagerduty/incident/note/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/incidents/{value.json.id}/notes"
        WITH HEADERS
            ADD "Accept" "application/vnd.pagerduty+json;version=2"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Token token={value.json.token}"
            ADD "From" "{value.json.from_email}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Enqueuetrigger | POST | `/v2/enqueue` | `itsm/pagerduty/event/trigger` | `itsm/pagerduty/event/trigger/response` |
| Enqueueresolve | POST | `/v2/enqueue` | `itsm/pagerduty/event/resolve` | `itsm/pagerduty/event/resolve/response` |
| Listincidents | GET | `/incidents?statuses[]={status}&limit={limit}` | `itsm/pagerduty/incident/list` | `itsm/pagerduty/incident/list/response` |
| Createincidentnote | POST | `/incidents/{id}/notes` | `itsm/pagerduty/incident/note` | `itsm/pagerduty/incident/note/response` |

## Auth

**Events API v2 (trigger / resolve):**

1. Create an Events API v2 integration on a PagerDuty service; copy the Integration Key.
2. Set connector `BASE_ADDRESS` to `https://events.pagerduty.com`.
3. Put `routing_key` in the MQTT JSON body (with `event_action`, and for resolve a `dedup_key`). No Authorization header.
4. Prefer Hub secrets / `GET SECRET "PAGERDUTY_ROUTING_KEY"`. Never commit real keys.
5. Successful enqueue returns **HTTP 202**.

**REST API token (list / notes) — default in the template:**

1. Create a PagerDuty [API token](https://docs.pagerduty.com/developer/authentication) (account or user).
2. Set connector `BASE_ADDRESS` to `https://api.pagerduty.com`.
3. Pass `token` on the MQTT request payload so headers resolve:
   * `Authorization: Token token={value.json.token}`
4. Use `Accept: application/vnd.pagerduty+json;version=2`.
5. For notes, also pass `from_email` → `From` header (valid account user email).
6. Store the token in Hub secrets / `GET SECRET "PAGERDUTY_API_TOKEN"`. Never commit real credentials.

**OAuth 2.0 (REST alternative):**

1. Obtain an OAuth access token with `incidents.read` / `incidents.write` as needed.
2. Change the Authorization header to `Bearer {value.json.access_token}`.

## Example payloads

**Trigger from alarm** (`BASE_ADDRESS` = `https://events.pagerduty.com`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "routing_key": "YOUR_EVENTS_INTEGRATION_KEY",
  "event_action": "trigger",
  "dedup_key": "line-a/vibration",
  "payload": {
    "summary": "Vibration above threshold — Zone A",
    "severity": "critical",
    "source": "coreflux-broker",
    "component": "plc-line-a",
    "custom_details": { "rms_mm_s": 12.4 }
  },
  "client": "Coreflux"
}
```

**Resolve:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "routing_key": "YOUR_EVENTS_INTEGRATION_KEY",
  "event_action": "resolve",
  "dedup_key": "line-a/vibration"
}
```

**List incidents:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_API_TOKEN",
  "status": "triggered",
  "limit": "25"
}
```

**Create note:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_API_TOKEN",
  "id": "PT4KHLK",
  "from_email": "oncall@example.com",
  "note": {
    "content": "Coreflux: vibration cleared after fan restart."
  }
}
```

## Deploy notes

* Deploy **`PagerDutyRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/pagerduty](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/pagerduty)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Particle
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/particle

LoT connector for Particle Device Cloud: read variables, call functions, publish events, read device vitals and locations, and manage webhooks and Ledger

Technical Preview

## Overview

Client-mode connector for the [Particle Device Cloud API](https://docs.particle.io/reference/cloud-apis/api/). Particle devices (Photon 2, Argon, Boron, B-SoM, M-SoM, Tracker) expose **cloud variables** that you read and **cloud functions** that you call, publish and subscribe to **events**, and keep shared JSON state in **Ledger**. Fleets are grouped in **products**; cellular devices come with Particle **SIMs**.

* **ParticleRestApi** (`https://api.particle.io`) lets the Coreflux broker read a machine value from a device, call a function to change a setpoint, broadcast an event to devices, check device vitals and SIM data usage, follow trackers on a map, and push setpoints to devices through a Cloud to Device ledger.
* **ParticleWebhookReceiver** (`cloud-iot_particle_webhook.lot`, opt-in, server mode) receives Particle webhooks so device events reach MQTT without polling.

| Event | Request | Notes |
| - | - | - |
| GetAccessTokenInfo | `GET /v1/access_tokens/current` | Expiry, client and scopes of the token, a good token check |
| ListDevices | `GET /v1/devices` | Devices the token can access |
| GetDevice | `GET /v1/devices/{device_id}` | `online`, `last_heard`, the variables and functions the firmware exposes |
| GetVariable | `GET /v1/devices/{device_id}/{variable_name}?{query}` | **Catalog.** Read a `Particle.variable`; `format=raw` returns only the value |
| CallFunction | `POST /v1/devices/{device_id}/{function_name}` | **Catalog.** Call a `Particle.function` with `{"arg": "..."}` (max 63 characters) |
| PingDevice | `PUT /v1/devices/{device_id}/ping` | Is the device online? (PUT without a body) |
| UpdateDevice | `PUT /v1/devices/{device_id}` | Rename, notes, `signal` (rainbow LED) or `firmware_updates_forced` |
| GetDeviceVitals | `GET /v1/diagnostics/{device_id}/last` | Last vitals: signal, battery, memory, cloud connection |
| GetDeviceVitalsHistory | `GET /v1/diagnostics/{device_id}?{query}` | `start_date`, `end_date` (ISO 8601) |
| RefreshDeviceVitals | `POST /v1/diagnostics/{device_id}/update` | Ask the device to send fresh vitals (202) |
| PublishEvent | `POST /v1/devices/events` | **Catalog.** Cloud event to your devices and integrations: `name`, `data`, `ttl` |
| ListProducts | `GET /v1/user/products` | Products you are a team member of |
| GetProduct | `GET /v1/products/{product_id}` | Product by id or slug |
| ListProductDevices | `GET /v1/products/{product_id}/devices?{query}` | `deviceId`, `groups`, `deviceName`, `serialNumber`, `sortAttr`, `sortDir`, `quarantined`, `page`, `perPage` |
| GetProductDevice | `GET /v1/products/{product_id}/devices/{device_id}` | Groups, firmware lock, development flag |
| GetProductVariable | `GET /v1/products/{product_id}/devices/{device_id}/{variable_name}?{query}` | Product endpoint form (required for product API users) |
| CallProductFunction | `POST /v1/products/{product_id}/devices/{device_id}/{function_name}` | Product endpoint form |
| PublishProductEvent | `POST /v1/products/{product_id}/events` | Product event stream; `as_device_id` publishes as a product device |
| ListProductLocations | `GET /v1/products/{product_id}/locations?{query}` | Asset tracking: `date_range`, `rect_bl`, `rect_tr`, `device_id`, `device_name`, `groups`, `page`, `per_page` |
| GetProductDeviceLocation | `GET /v1/products/{product_id}/locations/{device_id}?{query}` | Location history of one device |
| GetProductOnlineMetrics | `GET /v1/products/{product_id}/metrics/online?{query}` | Online device counts per bucket (fleet health) |
| ListProductFirmware | `GET /v1/products/{product_id}/firmware` | Product firmware versions |
| ListSims | `GET /v1/sims?{query}` | `iccid`, `deviceId`, `deviceName`, `page`, `perPage` |
| GetSim | `GET /v1/sims/{iccid}` | SIM status and limits |
| GetSimDataUsage | `GET /v1/sims/{iccid}/data_usage` | Daily MB used this billing period |
| GetSimStatus | `GET /v1/sims/{iccid}/status` | Cellular network status (may answer 202 first) |
| ListIntegrations | `GET /v1/integrations` | Webhooks and other integrations |
| GetIntegration | `GET /v1/integrations/{integration_id}` | One integration with recent logs |
| CreateWebhook | `POST /v1/integrations` | Webhook to any URL, for example the broker receiver |
| TestIntegration | `POST /v1/integrations/{integration_id}/test` | Sends a test event to the target |
| ListProductIntegrations | `GET /v1/products/{product_id}/integrations` | Integrations of a product |
| CreateProductWebhook | `POST /v1/products/{product_id}/integrations` | Webhook for every device in the product |
| ListLedgers | `GET /v1/ledgers?{query}` | Ledger definitions (`page`, `perPage`, `archived`) |
| GetLedger | `GET /v1/ledgers/{ledger_name}` | One ledger definition |
| ListLedgerInstances | `GET /v1/ledgers/{ledger_name}/instances?{query}` | Instances of a ledger |
| GetLedgerInstance | `GET /v1/ledgers/{ledger_name}/instances/{scope_value}` | Read an instance (JSON) |
| SetLedgerInstance | `PUT /v1/ledgers/{ledger_name}/instances/{scope_value}?{query}` | Write an instance; `set_mode=Replace` or `Merge` |
| ListLedgerInstanceVersions | `GET /v1/ledgers/{ledger_name}/instances/{scope_value}/versions?{query}` | `replaced_before`, `replaced_after` |
| GetProductLedgerInstance | `GET /v1/products/{product_id}/ledgers/{ledger_name}/instances/{scope_value}` | Product endpoint form |
| SetProductLedgerInstance | `PUT /v1/products/{product_id}/ledgers/{ledger_name}/instances/{scope_value}?{query}` | Product endpoint form |
| GetOrgLedgerInstance | `GET /v1/orgs/{org_id}/ledgers/{ledger_name}/instances/{scope_value}` | Organization ledger |
| SetOrgLedgerInstance | `PUT /v1/orgs/{org_id}/ledgers/{ledger_name}/instances/{scope_value}?{query}` | Organization ledger |

Topics are `cloud-iot/particle/<object>/<verb>` and every reply goes to `<topic>/response`. There are no DELETE events. `product_id` takes the product id or slug, `org_id` the organization id or slug.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

## Authentication

Every event sends `Authorization: Bearer {access_token}`.

* A **user token** is the quickest start: `particle token create` (valid 90 days unless you pass `--expires-in`). It can do anything your account can.
* For unattended plant use, create a **product or organization API user** with only the scopes its events need, for example `devices:list`, `devices.variable:get`, `devices.function:call`, `events:send`, `integrations:create`, `ledger.instances:get` and `ledger.instances:set`. An API user has one token at a time and must use the product (`/v1/products/...`) or organization (`/v1/orgs/...`) events.

Keep the token in a broker secret (suggested `PARTICLE_ACCESS_TOKEN`, plus `PARTICLE_DEVICE_ID` / `PARTICLE_PRODUCT_ID`) and map it in with `GET SECRET`. Particle still accepts a token in the query string or a form body, but both are deprecated; this template uses the header only.

A missing token returns `400 {"error": "invalid_request", "error_description": "The access token was not found"}`, a wrong or expired one `401 {"error": "invalid_token", ...}`. Particle checks the token before it looks at the path, so a 400 / 401 does not tell you whether the path exists.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ParticleRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.particle.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetVariable
        WITH SOURCE_TOPIC "cloud-iot/particle/device-variable/get"
        WITH DESTINATION_TOPIC "cloud-iot/particle/device-variable/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/devices/{value.json.device_id}/{value.json.variable_name}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CallFunction
        WITH SOURCE_TOPIC "cloud-iot/particle/device-function/call"
        WITH DESTINATION_TOPIC "cloud-iot/particle/device-function/call/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/devices/{value.json.device_id}/{value.json.function_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PublishEvent
        WITH SOURCE_TOPIC "cloud-iot/particle/event/publish"
        WITH DESTINATION_TOPIC "cloud-iot/particle/event/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/devices/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

The full template, with all 42 events, is `ParticleRestApi.lot` in the REST API app.

## MQTT examples

The connector sends only `{value.json.body}` as the request body. Keep `access_token`, `device_id`, `product_id`, `org_id`, `variable_name`, `function_name`, `ledger_name`, `scope_value`, `iccid`, `integration_id` and `query` at the top level of the MQTT payload. Device ids are the 24-character hex ids shown in the Particle console. Send `"query": ""` when you do not need query parameters.

**Read a cloud variable**: publish to `cloud-iot/particle/device-variable/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Particle access token>",
  "device_id": "0123456789abcdef01234567",
  "variable_name": "temperature",
  "query": ""
}
```

Particle answers `{"name": "temperature", "result": 21.4, "coreInfo": {...}}`; with `"query": "format=raw"` only `21.4`. The device must be online: an offline device answers `404`, a variable the firmware does not expose `400`.

**Call a cloud function**: publish to `cloud-iot/particle/device-function/call`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Particle access token>",
  "device_id": "0123456789abcdef01234567",
  "function_name": "setSpeed",
  "body": { "arg": "1200" }
}
```

The reply carries the integer the firmware function returns: `{"id": "...", "connected": true, "return_value": 1200}`. The argument is a string of at most 63 characters.

**Publish an event to devices**: publish to `cloud-iot/particle/event/publish`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Particle access token>",
  "body": { "name": "coreflux/line-porto-1/shift", "data": "{\"shift\":\"B\",\"target\":1200}", "ttl": 60 }
}
```

Devices receive it with `Particle.subscribe("coreflux/line-porto-1/", handler)`. For a product fleet use `cloud-iot/particle/product-event/publish` with `"product_id"`.

**Push setpoints through Ledger**: publish to `cloud-iot/particle/ledger-instance/set`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Particle access token>",
  "ledger_name": "line-setpoints",
  "scope_value": "0123456789abcdef01234567",
  "query": "set_mode=Merge",
  "body": { "instance": { "data": { "speed_rpm": 1200, "recipe": "R-42" } } }
}
```

A Cloud to Device ledger syncs to the device as soon as it is online, so the setpoint arrives even if the device is asleep now. `set_mode=Replace` (the default) overwrites the instance, `Merge` updates only the keys you send. Use the `product-ledger-instance` or `org-ledger-instance` events for product or organization ledgers.

**Fleet checks**: `cloud-iot/particle/product-device/list` with `"query": "groups=porto-1&perPage=100"`, `cloud-iot/particle/device-vitals/get` for signal and battery, `cloud-iot/particle/sim-data-usage/get` with `"iccid"`, and `cloud-iot/particle/product-location/list` with `"query": "per_page=100"` for tracker positions.

## Receive Particle events (webhook receiver)

Polling variables costs a data operation per call. To get device events pushed to MQTT, deploy the companion file `cloud-iot_particle_webhook.lot`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ParticleWebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9001'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT WebhookTelemetry
        WITH ENDPOINT "/particle/webhook/telemetry"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cloud-iot/particle/webhook-telemetry/received"
    ADD EVENT WebhookEvents
        WITH ENDPOINT "/particle/webhook/events"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cloud-iot/particle/webhook-event/received"
```

Then create a Particle webhook that points at it, for example by publishing to `cloud-iot/particle/webhook/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<Particle access token>",
  "body": {
    "integration_type": "Webhook",
    "event": "telemetry",
    "url": "https://broker.example.com/particle/webhook/telemetry",
    "requestType": "POST",
    "noDefaults": true,
    "json": {
      "event": "{{{PARTICLE_EVENT_NAME}}}",
      "data": "{{{PARTICLE_EVENT_VALUE}}}",
      "coreid": "{{{PARTICLE_DEVICE_ID}}}",
      "published_at": "{{{PARTICLE_PUBLISHED_AT}}}"
    },
    "headers": { "Authorization": "Bearer <receiver secret>" }
  }
}
```

Every `Particle.publish("telemetry", ...)` from your devices now arrives on `cloud-iot/particle/webhook-telemetry/received`. `cloud-iot/particle/integration/test` sends a test delivery.

1. Deploying the receiver opens HTTP port `9001` on the broker.
2. Particle delivers from its cloud to a public URL. Put a reverse proxy or tunnel with a public TLS certificate in front of port `9001` and forward `/particle/webhook/...`.
3. Accept only Particle. The connector does not check secrets itself: let the proxy check the `Authorization` header you set on the webhook (or Basic `auth`, or a Particle cloud secret inserted with `{{{SECRET_NAME}}}`).
4. Use the **JSON** request format. The default Web Form format arrives URL-encoded.
5. Answer fast: Particle waits 20 seconds and throttles a webhook whose target fails or times out too often.
6. `data` is the string the device published (often JSON text): parse it in a LoT action. Retries can repeat a delivery, so deduplicate on `coreid` + `published_at`.

## Helper actions

Call a function from a plant setpoint topic, poll a variable every minute, and connector webhook telemetry per device, with the token and device id kept in broker secrets:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ParticleSetLineSpeed
ON TOPIC "porto/line-1/speed/set" DO
    SET "tok" WITH GET SECRET "PARTICLE_ACCESS_TOKEN"
    SET "dev" WITH GET SECRET "PARTICLE_DEVICE_ID"
    SET "rpm" WITH GET JSON "rpm" IN PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/particle/device-function/call" WITH { "access_token": {tok}, "device_id": {dev}, "function_name": "setSpeed", "body": { "arg": {rpm} } }

DEFINE ACTION ParticlePollTemperature
ON EVERY 1 MINUTE DO
    SET "tok" WITH GET SECRET "PARTICLE_ACCESS_TOKEN"
    SET "dev" WITH GET SECRET "PARTICLE_DEVICE_ID"
    PUBLISH TOPIC "cloud-iot/particle/device-variable/get" WITH { "access_token": {tok}, "device_id": {dev}, "variable_name": "temperature", "query": "" }

DEFINE ACTION ParticleWebhookToPlant
ON TOPIC "cloud-iot/particle/webhook-telemetry/received" DO
    SET "dev" WITH (GET JSON "coreid" IN PAYLOAD AS STRING)
    SET "data" WITH (GET JSON "data" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "plant/particle/" + {dev} + "/telemetry" WITH {data}
```

Restrict who can publish to `cloud-iot/particle/#` with a rule: its payloads carry the token, and the function, event and ledger events change how devices in the field behave.

## Notes

* **Rate limits:** 10,000 API requests every 5 minutes per public IP address; a `429` means slow down (retrying at once does not help). The serial-number lookup and the event streams have stricter limits. Polling many variables quickly hits the limit and costs data operations on cellular devices; prefer events plus the webhook receiver.
* **Errors** come back on the response topic: `400` (bad request, or the variable / function is not exposed), `401` (token invalid or expired), `403` (token not allowed for this device or product), `404` (device offline or unknown), `408` (the device did not answer in time), `429`, `5xx`.
* **Ledger:** names are lowercase letters, digits and dashes, up to 32 characters. Device-synced ledgers hold up to 16 KB of JSON, cloud-only ledgers up to 1 MB. Device to Cloud and Cloud to Device ledgers need Device OS 6.1.0 or later. The API reference lists the set body as `{"data": ...}`; the official JavaScript SDK sends `{"instance": {"data": ...}}` with `set_mode`. This template passes the body through unchanged, so either form can be sent.
* **Not packaged:** Server-Sent Event streams (`GET /v1/devices/events/...`, product and organization streams) because a REST\_API connector cannot hold a stream open (use the webhook receiver instead), every DELETE (unclaim, remove from product, delete ledger instance, delete integration), firmware flashing and compiling, claiming and importing devices, SIM activation, customers, groups, Logic functions, environment variables, cloud secrets and OAuth clients.
* Only the global host `https://api.particle.io` is documented (TLS 1.2 or later).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Losant](/latest/lot-language/routes/rest-api-apps/losant)
* [balena](/latest/lot-language/routes/rest-api-apps/balena)


# Pipedrive
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/pipedrive

LoT connector for Pipedrive CRM: open and move deals, log activities and notes from plant alarms, update organizations, search persons and create leads

Technical Preview

## Overview

A client-mode connector for the [Pipedrive API](https://developers.pipedrive.com/docs/api/v1) that turns plant events into sales and service follow-ups. A machine alarm can open a deal or an activity, add a note, and close the activity when the alarm clears. Counters from the installed base can be written to organization custom fields.

The connector uses API v2 (`/api/v2/...`) for deals, activities, organizations, persons, pipelines, stages and deal fields, and v1 (`/v1/...`) only for notes, leads, webhooks and the current user, which have no v2 version yet. Topics use `crm/pipedrive/<object>/<verb>`; each response is published on `<source topic>/response`.

## Authentication

Create a personal API token in Pipedrive under **Settings > Personal preferences > API**. The connector sends it in the `x-api-token` header, taken from the `api_token` field of each MQTT payload.

> [!WARNING]
>
> Do not publish the token in retained messages. Store it as a broker secret (for example `PIPEDRIVE_API_TOKEN`) and have a LoT action add it to the payload with `GET SECRET` before publishing to the connector topic.

For a Marketplace (OAuth) app, change the header to `Authorization: Bearer <access_token>` and set `BASE_ADDRESS` to the `api_domain` returned by `https://oauth.pipedrive.com/oauth/token` (for example `https://yourcompany.pipedrive.com`).

## Payload fields

| Field | Used by | Notes |
| - | - | - |
| `api_token` | every event | Pipedrive API token |
| `id` | `...Get`, `...Update` | Numeric id of the deal, activity or organization |
| `query` | list and search events | URL-encoded query string; send `""` for none. Search needs `term=` (at least 2 characters) |
| `body` | create and update events | JSON object sent as the request body |

## Events

| Event | Method | Endpoint | Source topic | Write |
| - | - | - | - | - |
| `CurrentUser` | `GET` | `/v1/users/me` | `crm/pipedrive/users/me/get` | |
| `DealsList` | `GET` | `/api/v2/deals?{query}` | `crm/pipedrive/deals/list` | |
| `DealGet` | `GET` | `/api/v2/deals/{id}` | `crm/pipedrive/deals/get` | |
| `DealsSearch` | `GET` | `/api/v2/deals/search?{query}` | `crm/pipedrive/deals/search` | |
| `DealCreate` | `POST` | `/api/v2/deals` | `crm/pipedrive/deals/create` | yes |
| `DealUpdate` | `PATCH` | `/api/v2/deals/{id}` | `crm/pipedrive/deals/update` | yes |
| `ActivitiesList` | `GET` | `/api/v2/activities?{query}` | `crm/pipedrive/activities/list` | |
| `ActivityCreate` | `POST` | `/api/v2/activities` | `crm/pipedrive/activities/create` | yes |
| `ActivityUpdate` | `PATCH` | `/api/v2/activities/{id}` | `crm/pipedrive/activities/update` | yes |
| `OrganizationsList` | `GET` | `/api/v2/organizations?{query}` | `crm/pipedrive/organizations/list` | |
| `OrganizationGet` | `GET` | `/api/v2/organizations/{id}` | `crm/pipedrive/organizations/get` | |
| `OrganizationCreate` | `POST` | `/api/v2/organizations` | `crm/pipedrive/organizations/create` | yes |
| `OrganizationUpdate` | `PATCH` | `/api/v2/organizations/{id}` | `crm/pipedrive/organizations/update` | yes |
| `PersonsSearch` | `GET` | `/api/v2/persons/search?{query}` | `crm/pipedrive/persons/search` | |
| `PersonCreate` | `POST` | `/api/v2/persons` | `crm/pipedrive/persons/create` | yes |
| `PipelinesList` | `GET` | `/api/v2/pipelines?{query}` | `crm/pipedrive/pipelines/list` | |
| `StagesList` | `GET` | `/api/v2/stages?{query}` | `crm/pipedrive/stages/list` | |
| `DealFieldsList` | `GET` | `/api/v2/dealFields?{query}` | `crm/pipedrive/dealfields/list` | |
| `NoteCreate` | `POST` | `/v1/notes` | `crm/pipedrive/notes/create` | yes |
| `LeadCreate` | `POST` | `/v1/leads` | `crm/pipedrive/leads/create` | yes |
| `WebhooksList` | `GET` | `/v1/webhooks` | `crm/pipedrive/webhooks/list` | |
| `WebhookCreate` | `POST` | `/v1/webhooks` | `crm/pipedrive/webhooks/create` | yes |

`OrganizationUpdate` covers the catalog's `PUT organizations/{id}`: in API v2 updates use `PATCH`, and v1 organization endpoints are no longer in Pipedrive's v1 spec. No `DELETE` events are included on purpose.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PipedriveRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.pipedrive.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CurrentUser
        WITH SOURCE_TOPIC "crm/pipedrive/users/me/get"
        WITH DESTINATION_TOPIC "crm/pipedrive/users/me/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealsList
        WITH SOURCE_TOPIC "crm/pipedrive/deals/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/deals?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealGet
        WITH SOURCE_TOPIC "crm/pipedrive/deals/get"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/deals/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealsSearch
        WITH SOURCE_TOPIC "crm/pipedrive/deals/search"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/deals/search?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealCreate
        WITH SOURCE_TOPIC "crm/pipedrive/deals/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/deals"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DealUpdate
        WITH SOURCE_TOPIC "crm/pipedrive/deals/update"
        WITH DESTINATION_TOPIC "crm/pipedrive/deals/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/v2/deals/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ActivitiesList
        WITH SOURCE_TOPIC "crm/pipedrive/activities/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/activities/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/activities?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT ActivityCreate
        WITH SOURCE_TOPIC "crm/pipedrive/activities/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/activities/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/activities"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ActivityUpdate
        WITH SOURCE_TOPIC "crm/pipedrive/activities/update"
        WITH DESTINATION_TOPIC "crm/pipedrive/activities/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/v2/activities/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT OrganizationsList
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/organizations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT OrganizationGet
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/get"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/organizations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT OrganizationCreate
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/organizations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT OrganizationUpdate
        WITH SOURCE_TOPIC "crm/pipedrive/organizations/update"
        WITH DESTINATION_TOPIC "crm/pipedrive/organizations/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/v2/organizations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PersonsSearch
        WITH SOURCE_TOPIC "crm/pipedrive/persons/search"
        WITH DESTINATION_TOPIC "crm/pipedrive/persons/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/persons/search?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT PersonCreate
        WITH SOURCE_TOPIC "crm/pipedrive/persons/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/persons/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/persons"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PipelinesList
        WITH SOURCE_TOPIC "crm/pipedrive/pipelines/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/pipelines/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/pipelines?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT StagesList
        WITH SOURCE_TOPIC "crm/pipedrive/stages/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/stages/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/stages?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT DealFieldsList
        WITH SOURCE_TOPIC "crm/pipedrive/dealfields/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/dealfields/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/dealFields?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT NoteCreate
        WITH SOURCE_TOPIC "crm/pipedrive/notes/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/notes/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/notes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT LeadCreate
        WITH SOURCE_TOPIC "crm/pipedrive/leads/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/leads/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/leads"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT WebhooksList
        WITH SOURCE_TOPIC "crm/pipedrive/webhooks/list"
        WITH DESTINATION_TOPIC "crm/pipedrive/webhooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
    ADD EVENT WebhookCreate
        WITH SOURCE_TOPIC "crm/pipedrive/webhooks/create"
        WITH DESTINATION_TOPIC "crm/pipedrive/webhooks/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/webhooks"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "x-api-token" "{value.json.api_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

**Activity from an alarm**

Publish to `crm/pipedrive/activities/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "<from GET SECRET>", "body": {"subject": "Check press 7 overtemperature", "type": "task", "due_date": "2026-10-06", "deal_id": 42}}
```

When the alarm clears, publish `{"api_token": "...", "id": <activity id>, "body": {"done": true}}` to `crm/pipedrive/activities/update`.

**Open deals in a pipeline**

Publish to `crm/pipedrive/deals/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "<from GET SECRET>", "query": "status=open&pipeline_id=1&limit=50"}
```

v2 lists page with a cursor: pass `cursor=<additional_data.next_cursor>` in `query` for the next page.

**Organization custom field**

Get the field key from Pipedrive's organization fields (`GET /api/v2/organizationFields`, not packaged as an event), then publish to `crm/pipedrive/organizations/update`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "<from GET SECRET>", "id": 7, "body": {"custom_fields": {"<field key>": 1280}}}
```

## Webhooks into the broker

`WebhookCreate` registers a Pipedrive webhook (`version` `"2.0"`, `event_action` such as `create` / `change` / `delete` / `*`, `event_object` such as `deal` / `activity` / `organization`). Pipedrive then POSTs each change to `subscription_url`. To receive it, run a separate server-mode connector and protect it with the webhook's `http_auth_user` / `http_auth_password`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PipedriveWebhookReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8443'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PipedriveChange
        WITH ENDPOINT "/pipedrive/webhook"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "crm/pipedrive/webhook/events"
```

The receiver must be reachable from the internet over HTTPS. It is not part of the client template.

## Rate limits

Pipedrive gives each company a daily token budget, and every call spends tokens (the OpenAPI `x-token-cost`: 1 for a GET by id, 5 to 10 for lists, 20 for search, 5 for v2 writes, 10 for v1 writes). Short burst limits also apply, and excess calls get `429`. Responses carry `X-RateLimit-*` and `X-Daily-RateLimit-Token-*` headers. Avoid polling lists from fast timers; react to events or use webhooks instead.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [Pipedrive API reference](https://developers.pipedrive.com/docs/api/v1)


# Postman Echo REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/postman-echo

Client-mode REST API connector that calls the public Postman Echo API from MQTT

Technical Preview

## Overview

[Postman Echo](https://postman-echo.com/) is a public HTTP echo service. Use this client-mode `REST_API` connector to prove MQTT-to-HTTP wiring (methods, path placeholders, headers, cookies, status codes, and response topics) without an API key.

> [!TIP]
>
> Public `GET /get` does not need a token. The template still sends `Authorization: Bearer {value.json.api_token}` so the header pattern matches other apps. Leave `api_token` empty for demos, or drop that header.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Postman Echo
# Generated from OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

DEFINE CONNECTOR PostmanEchoRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://postman-echo.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Optional: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Get
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Get"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Get"
        WITH METHOD "GET"
        WITH ENDPOINT "/get"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Post
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Post"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Post"
        WITH METHOD "POST"
        WITH ENDPOINT "/post"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Put
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Put"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Put"
        WITH METHOD "PUT"
        WITH ENDPOINT "/put"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Delete
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Delete"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Delete"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/delete"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Headers
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Headers"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Headers"
        WITH METHOD "GET"
        WITH ENDPOINT "/headers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Statuscode
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Statuscode"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Statuscode"
        WITH METHOD "GET"
        WITH ENDPOINT "/status/{value.json.code}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Timenow
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Timenow"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Timenow"
        WITH METHOD "GET"
        WITH ENDPOINT "/time/now"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Cookies
        WITH SOURCE_TOPIC "integrations/postman-echo/request/Cookies"
        WITH DESTINATION_TOPIC "integrations/postman-echo/response/Cookies"
        WITH METHOD "GET"
        WITH ENDPOINT "/cookies"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Get | GET | `/get` | `integrations/postman-echo/request/Get` | `integrations/postman-echo/response/Get` |
| Post | POST | `/post` | `integrations/postman-echo/request/Post` | `integrations/postman-echo/response/Post` |
| Put | PUT | `/put` | `integrations/postman-echo/request/Put` | `integrations/postman-echo/response/Put` |
| Delete | DELETE | `/delete` | `integrations/postman-echo/request/Delete` | `integrations/postman-echo/response/Delete` |
| Headers | GET | `/headers` | `integrations/postman-echo/request/Headers` | `integrations/postman-echo/response/Headers` |
| Statuscode | GET | `/status/{value.json.code}` | `integrations/postman-echo/request/Statuscode` | `integrations/postman-echo/response/Statuscode` |
| Timenow | GET | `/time/now` | `integrations/postman-echo/request/Timenow` | `integrations/postman-echo/response/Timenow` |
| Cookies | GET | `/cookies` | `integrations/postman-echo/request/Cookies` | `integrations/postman-echo/response/Cookies` |

## Auth

None required. Base address is `https://postman-echo.com`. Optional Bearer token is a placeholder only. Prefer `GET SECRET` if you later point the connector at a private echo. Never commit real tokens.

## Try it

1. Add the connector on your broker (`-addConnector` with the LoT above).
2. Publish `{}` to `integrations/postman-echo/request/Get`.
3. Subscribe to `integrations/postman-echo/response/Get`. Postman Echo echoes the request as JSON.
4. Status check: publish `{"code":"200"}` to `integrations/postman-echo/request/Statuscode`.
5. POST/PUT: publish a JSON body to `integrations/postman-echo/request/Post` or `.../Put`. The connector sends it as `{payload}`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Project Haystack
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/project-haystack

LoT connector for the Project Haystack HTTP API: read points, hisRead and hisWrite history, pointWrite, watches, nav, defs and invokeAction over JSON grids

Technical Preview

## Overview

**Project Haystack** is the industry standard for semantic tagging of equipment, points and histories in buildings and industrial sites. Compliant servers (SkyFoundry **SkySpark**, J2 Innovations **FIN Framework**, open-source **Haxall**, Tridium Niagara with **nhaystack**, **Haystack Connect**, and others) expose the same HTTP API: ops such as `read`, `hisRead`, `hisWrite`, `pointWrite` and `watchSub` exchange **grids** encoded as Zinc, JSON or Trio.

The **ProjectHaystackApi** connector maps 15 MQTT topics onto that standard ops set (4 meta GETs, 11 POSTs including 3 writes). A Coreflux broker can discover tagged points (`point and temp`), pull or push histories, command writable setpoints through the priority array, and poll watches for live `curVal` changes. Each event publishes the server reply on `<topic>/response`.

| Event | Topic | Request | Use | | | | |
| - | - | - | - | - | - | - | - |
| `About` | `energy/haystack/about/get` | `GET /about` | Server / project about grid (haystackVersion, tz, serverName, productName, ...); empty request | | | | |
| `ListOps` | `energy/haystack/ops/list` | `GET /ops` | Op defs available on this server (standard + vendor extensions) | | | | |
| `ListFiletypes` | `energy/haystack/filetypes/list` | `GET /filetypes` | Supported MIME encodings (text/zinc, application/json, text/trio, text/csv, ...) | | | | |
| `ListLibs` | `energy/haystack/libs/list` | `GET /libs` | Lib defs in the current namespace | | | | |
| `Close` | `energy/haystack/auth/close` | `POST /close` | Invalidate the bearer authToken and close the SCRAM session; body empty grid | | | | |
| `Read` | `energy/haystack/read` | `POST /read` | Entities by filter (rows: filter, optional limit) or by id (rows of id refs); e.g. filter=point and temp | | | | |
| `Nav` | `energy/haystack/nav` | `POST /nav` | Navigation tree children; body row navId (null/omit for root) | | | | |
| `Defs` | `energy/haystack/defs` | `POST /defs` | Def dicts; empty grid for all, or filter/limit row | | | | |
| `HisRead` | `energy/haystack/his/read` | `POST /hisRead` | Historized samples: single (row id+range) or batch (meta.range + id rows); range today | yesterday | \{date} | \{date},\{date} | \{dateTime},\{dateTime} |
| `HisWrite` | `energy/haystack/his/write` | `POST /hisWrite` | WRITE: WRITE: post history samples; single (meta.id + ts/val rows) or batch (v0/v1 cols with id in col meta) | | | | |
| `PointWrite` | `energy/haystack/point/write` | `POST /pointWrite` | WRITE: WRITE: read priority array (row id only) or write a level (id, level 1-17, val or null to auto, optional who/duration) | | | | |
| `WatchSub` | `energy/haystack/watch/sub` | `POST /watchSub` | Create watch (meta watchDis, optional lease) or add ids to existing (meta watchId); response meta.watchId | | | | |
| `WatchPoll` | `energy/haystack/watch/poll` | `POST /watchPoll` | Poll changes for watchId (meta); add refresh Marker for full refresh | | | | |
| `WatchUnsub` | `energy/haystack/watch/unsub` | `POST /watchUnsub` | Remove ids from a watch, or close it (meta watchId + close Marker) | | | | |
| `InvokeAction` | `energy/haystack/action/invoke` | `POST /invokeAction` | WRITE: WRITE: invoke a user action; meta id + action name, row = args | | | | |

Endpoints are relative to `BASE_ADDRESS`, which **already includes** the project or service path (see below).

## Base URL (hosts differ)

Set `WITH BASE_ADDRESS` to your server root **including** the project / service segment. Ops are then `/about`, `/read`, `/hisRead`, …:

| Product | Typical base |
| - | - |
| SkySpark / FIN / Haxall | `https://{host}/api/{project}` e.g. `https://skyspark.example.com/api/demo` |
| nhaystack (Niagara) | `https://{host}/{service}` e.g. `https://niagara.example.com/haystack` |
| Generic / Haystack Connect | `https://{host}/haystack` |

The placeholder in the template is `https://haystack.example.com/api/demo`. Trailing slash is optional.

## Authentication

Haystack uses a pluggable HTTP auth protocol. Compliant servers must support **SCRAM with SHA-256**:

1. Client sends a hello (username) to a protected URI.
2. Server answers `401` with `WWW-Authenticate: SCRAM ...`.
3. After the SCRAM exchange the server returns `authToken` in `Authentication-Info`.
4. Subsequent calls send `Authorization: BEARER authToken=<token>`.

On **nhaystack**, operators often enable `HTTPBasicScheme` and send `Authorization: Basic <base64(user:pass)>` over HTTPS instead.

The multi-step SCRAM hello is **not** a connector event (the REST\_API client does one HTTP call per MQTT publish). Obtain a token with a Haystack client library ([phable](https://phable.dev/), haystack-java, pyhaystack, …) or a small helper script, store the current header value in Hub secret `HAYSTACK_AUTHORIZATION`, and map it with `GET SECRET`. Call `Close` to invalidate the token when done.

Every event sends `Authorization: {value.json.authorization}`.

## Formats (JSON grids)

The connector uses `Accept` / `Content-Type: application/json` (Haystack JSON grids with `"_kind":"grid"`). Zinc (`text/zinc`) is the HTTP API default; Trio and CSV are also standardized. Change the headers if your tooling prefers Zinc.

Request errors that the server can parse still return **HTTP 200** with an **error grid** (`meta.err` Marker + `dis`). Always check for `err` in the reply before treating rows as data.

## Request payload

| Field | Used by | Example |
| - | - | - |
| `authorization` | all events | `(GET SECRET "HAYSTACK_AUTHORIZATION")` → `BEARER authToken=…` or `Basic …` |
| `body` | all POST events | Haystack JSON grid (string or object the broker serializes) |

### Example grids

Empty grid (Close, Nav root, Defs all):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"_kind":"grid","meta":{"ver":"3.0"},"cols":[{"name":"empty"}],"rows":[]}
```

Read by filter:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"_kind":"grid","meta":{"ver":"3.0"},"cols":[{"name":"filter"},{"name":"limit"}],"rows":[{"filter":"point and temp","limit":100}]}
```

HisRead today:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"_kind":"grid","meta":{"ver":"3.0"},"cols":[{"name":"id"},{"name":"range"}],"rows":[{"id":{"_kind":"ref","val":"zoneTemp"},"range":"today"}]}
```

PointWrite level 16:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"_kind":"grid","meta":{"ver":"3.0"},"cols":[{"name":"id"},{"name":"level"},{"name":"val"},{"name":"who"}],"rows":[{"id":{"_kind":"ref","val":"sp"},"level":16,"val":{"_kind":"number","val":21,"unit":"°C"},"who":"Coreflux"}]}
```

## Example actions

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the ProjectHaystackApi route (docs page). Not part of the route template.
# Secret: HAYSTACK_AUTHORIZATION = "BEARER authToken=<token>" after SCRAM hello (or "Basic <base64>" on nhaystack).
# Inline JSON object literals are not supported when publishing to a topic, so the request payload is a COLLAPSED
#   model sent with PUBLISH MODEL. For POST ops the body field is the Haystack JSON grid as a string.

DEFINE MODEL HaystackGetRequest COLLAPSED
    ADD STRING "authorization"

DEFINE MODEL HaystackGridRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "body"

DEFINE ACTION HaystackAboutHourly
ON EVERY 1 HOUR DO
    PUBLISH MODEL HaystackGetRequest TO "energy/haystack/about/get" WITH
        authorization = (GET SECRET "HAYSTACK_AUTHORIZATION")

DEFINE ACTION HaystackReadPointsEvery5Minutes
ON EVERY 5 MINUTES DO
    PUBLISH MODEL HaystackGridRequest TO "energy/haystack/read" WITH
        authorization = (GET SECRET "HAYSTACK_AUTHORIZATION")
        body = "{\"_kind\":\"grid\",\"meta\":{\"ver\":\"3.0\"},\"cols\":[{\"name\":\"filter\"},{\"name\":\"limit\"}],\"rows\":[{\"filter\":\"point and temp\",\"limit\":100}]}"

DEFINE ACTION HaystackHisReadDaily
ON EVERY 1 DAY DO
    PUBLISH MODEL HaystackGridRequest TO "energy/haystack/his/read" WITH
        authorization = (GET SECRET "HAYSTACK_AUTHORIZATION")
        body = "{\"_kind\":\"grid\",\"meta\":{\"ver\":\"3.0\"},\"cols\":[{\"name\":\"id\"},{\"name\":\"range\"}],\"rows\":[{\"id\":{\"_kind\":\"ref\",\"val\":\"zoneTemp\"},\"range\":\"today\"}]}"
```

## Writes

`HisWrite`, `PointWrite` (when the body includes `level`) and `InvokeAction` change server state. Restrict which MQTT clients may publish to `energy/haystack/his/write`, `energy/haystack/point/write` and `energy/haystack/action/invoke`. `PointWrite` with an id-only body only **reads** the priority array.

## Watches

1. `WatchSub` with `watchDis` (+ optional `lease`) and id rows → response `meta.watchId`.
2. Poll with `WatchPoll` (`meta.watchId`; add `refresh` Marker for a full refresh).
3. `WatchUnsub` with `close` Marker (or remove individual ids).

Lease expiry on the server closes the watch if you stop polling.

## Not packaged

SkySpark / Haxall extensions such as `eval` and `commit`, other vendor ops beyond the [standard Ops chapter](https://project-haystack.org/doc/docHaystack/Ops), and the SCRAM hello handshake as a connector event.

## Sources

* [Ops](https://project-haystack.org/doc/docHaystack/Ops) · [HTTP API](https://project-haystack.org/doc/docHaystack/HttpApi) · [Authentication](https://project-haystack.org/doc/docHaystack/Auth) · [Ops appendix](https://project-haystack.org/doc/appendix/ops)
* Project Haystack does not publish an official OpenAPI file.


# Prometheus, Alertmanager and Pushgateway
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/prometheus-alertmanager-and-pushgateway

LoT connector for Prometheus, Alertmanager and Pushgateway: run PromQL instant and range queries, list scrape targets, push metrics and list alerts

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of the [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/), [Pushgateway](https://prometheus.io/docs/instrumenting/pushing/), and [Alertmanager API](https://prometheus.io/docs/alerting/latest/management_api/):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET query | `GET /api/v1/query?query=` | PromQL instant query; typically **no auth** |
| GET query\_range | `GET /api/v1/query_range` | PromQL range (`start` / `end` / `step`) |
| GET targets | `GET /api/v1/targets` | Scrape target discovery |
| POST Pushgateway metrics | `POST /metrics/job/{job}` | text/plain OpenMetrics / Prometheus exposition; **BASE = Pushgateway :9091** |
| GET Alertmanager alerts | `GET /api/v2/alerts` | Alertmanager API v2; **BASE = Alertmanager :9093** |

Default `BASE_ADDRESS` is `http://prometheus.example.com:9090` (replace with your Prometheus host). Topics use `itsm/prometheus/<object>/<verb>`.

> [!NOTE]
>
> Prometheus, Alertmanager, and Pushgateway are usually separate hosts/ports (`:9090` / `:9093` / `:9091`). Point `BASE_ADDRESS` at the matching host for each event, or deploy separate connector copies. For HTTPS reverse proxies set `WITH USE_SSL "true"`. Do not put a trailing slash on `BASE_ADDRESS`.

> [!NOTE]
>
> Prefer Hub secrets when a reverse proxy requires Basic or Bearer.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Prometheus / Alertmanager / Pushgateway curated slice
# Auth: none by default; optional Bearer/Basic via reverse proxy
# BASE_ADDRESS: http://prometheus.example.com:9090
# PushMetrics → Pushgateway :9091; ListAlerts → Alertmanager :9093

DEFINE CONNECTOR PrometheusRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://prometheus.example.com:9090"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Queryinstant
        WITH SOURCE_TOPIC "itsm/prometheus/query/instant"
        WITH DESTINATION_TOPIC "itsm/prometheus/query/instant/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/query?query={value.json.query}&time={value.json.time}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Queryrange
        WITH SOURCE_TOPIC "itsm/prometheus/query/range"
        WITH DESTINATION_TOPIC "itsm/prometheus/query/range/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/query_range?query={value.json.query}&start={value.json.start}&end={value.json.end}&step={value.json.step}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Listtargets
        WITH SOURCE_TOPIC "itsm/prometheus/targets/list"
        WITH DESTINATION_TOPIC "itsm/prometheus/targets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/targets"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Pushmetrics
        WITH SOURCE_TOPIC "itsm/prometheus/pushgateway/push"
        WITH DESTINATION_TOPIC "itsm/prometheus/pushgateway/push/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/metrics/job/{value.json.job}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain"
        WITH BODY "{payload}"
    ADD EVENT Listalerts
        WITH SOURCE_TOPIC "itsm/prometheus/alertmanager/alerts/list"
        WITH DESTINATION_TOPIC "itsm/prometheus/alertmanager/alerts/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/alerts"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Queryinstant | GET | `/api/v1/query?query=&time=` | `itsm/prometheus/query/instant` | `itsm/prometheus/query/instant/response` |
| Queryrange | GET | `/api/v1/query_range?query=&start=&end=&step=` | `itsm/prometheus/query/range` | `itsm/prometheus/query/range/response` |
| Listtargets | GET | `/api/v1/targets` | `itsm/prometheus/targets/list` | `itsm/prometheus/targets/list/response` |
| Pushmetrics | POST | `/metrics/job/{job}` | `itsm/prometheus/pushgateway/push` | `itsm/prometheus/pushgateway/push/response` |
| Listalerts | GET | `/api/v2/alerts` | `itsm/prometheus/alertmanager/alerts/list` | `itsm/prometheus/alertmanager/alerts/list/response` |

## Auth

**None (default):**

1. Most Prometheus installs expose `/api/v1/*` without auth on private networks.
2. Leave Authorization headers off for Queryinstant / Queryrange / Listtargets.

**Bearer via reverse proxy (optional):**

1. Terminate TLS + auth in nginx / Traefik / similar in front of Prometheus / Alertmanager / Pushgateway.
2. Pass `token` on the MQTT request payload:
   * `Authorization: Bearer {value.json.token}`
3. Store the token in Hub secrets / `GET SECRET "PROMETHEUS_TOKEN"`. Never commit real credentials.

**Basic via reverse proxy (optional):**

1. Configure `WITH USERNAME` / `WITH PASSWORD GET SECRET "PROMETHEUS_PASSWORD"` on `REST_API_CONFIG`.
2. Remove any Bearer headers from events.

## Install

1. Copy `PrometheusRestApi.lot` into your broker examples / connectors folder (no `ADD METADATA` in the deployable file).
2. Set `BASE_ADDRESS` to your Prometheus URL (use `https://…` and `WITH USE_SSL "true"` when TLS terminates on the API host or proxy).
3. `-addConnector` the file (or paste into Hub).
4. For Pushgateway and Alertmanager, either change BASE and re-deploy, or keep separate connector copies with the matching BASE.
5. Subscribe to the `/response` topics; publish JSON to the request topics.

Hub template listing uses `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink) — keep that file separate from the deployable connector.

## Example payloads

**Instant query**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "query": "up", "time": "" }
```

**Range query**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "query": "rate(http_requests_total[5m])",
  "start": "2026-10-04T00:00:00Z",
  "end": "2026-10-04T01:00:00Z",
  "step": "1m"
}
```

**List targets**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{}
```

**Pushgateway push** — MQTT JSON must supply `job`; body `{payload}` is raw text/plain exposition (example metrics body):

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# TYPE coreflux_temperature gauge
coreflux_temperature{instance="factory"} 1
```

**List Alertmanager alerts** (BASE = Alertmanager)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{}
```

## Complementary surfaces (not client events here)

| Surface | Role |
| - | - |
| Alertmanager webhook receiver | Inbound: Alertmanager `webhook_config` POSTs alert payloads to a Coreflux REST\_API **server** connector or HTTP ingress |
| Remote write | Prometheus remote\_write (protobuf/snappy) — different protocol; not this JSON/text HTTP slice |
| OpenMetrics | Exposition format used by Pushgateway bodies and scrapes |

## References

* [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/)
* [Pushing metrics (Pushgateway)](https://prometheus.io/docs/instrumenting/pushing/)
* [Alertmanager HTTP API](https://prometheus.io/docs/alerting/latest/management_api/)
* [Alertmanager configuration (webhooks)](https://prometheus.io/docs/alerting/latest/configuration/)
* [Remote write spec](https://prometheus.io/docs/specs/remote_write_spec/)
* [OpenMetrics](https://github.com/OpenObservability/OpenMetrics)
* Public demos: [demo.promlabs.com](https://demo.promlabs.com), [prometheus.demo.prometheus.io](https://prometheus.demo.prometheus.io)


# PTC Windchill (Windchill REST Services)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ptc-windchill

LoT connector for PTC Windchill REST Services: read parts, BOMs, CAD drawings, documents and change notices, and raise problem reports from quality events

Technical Preview

## Overview

[PTC Windchill](https://www.ptc.com/en/products/windchill) is the PLM system that owns parts, BOMs, CAD documents, drawings and change processes for many manufacturers. This connector lets shop-floor logic on MQTT look up a part and its released structure, build a kitting list from the multi-level components report, fetch part attachments and drawings for a work instruction screen, watch change notices, and raise a problem report or variance from a quality event, without custom code.

**PtcWindchillApi** (`PtcWindchillRestApi.lot`) is one client connector on `https://YOUR_WINDCHILL_SERVER` with 17 events: 1 CSRF token call, 14 reads and 2 writes. No event updates, deletes, revises or checks out anything.

> [!NOTE]
>
> Windchill REST Services (WRS) is an OData v4 API under `/Windchill/servlet/odata/<Domain>/`. This template uses the Product Management (`ProdMgmt`), Document Management (`DocMgmt`), Change Management (`ChangeMgmt`) and common (`PTC`) domains. Every server publishes its own `$metadata` per domain (for example `/Windchill/servlet/odata/ProdMgmt/$metadata`), which also lists your custom types and soft attributes. The events follow PTC's public [Windchill REST Services 2.7 guide](https://support.ptc.com/help/windchill_rest_services/r2.7/en/windchill_rest_services/examples_lp_prodmgmt.html). To add another entity set or action, copy an event and change the path.

## Server host

Windchill is installed per customer, or runs as Windchill+ (SaaS). Replace `YOUR_WINDCHILL_SERVER` with your Windchill web server host, with no trailing slash, and add the port when it does not use 443. To pin a domain version, insert it after `odata/` (for example `/Windchill/servlet/odata/v5/ProdMgmt/`); without a version the server uses its default.

## Authentication

> [!WARNING]
>
> WRS calls act as the Windchill user behind the credentials. Keep them in Hub secrets, map them in with `GET SECRET`, and never publish the authorization value or the CSRF nonce on a topic other clients can read.

* **HTTP Basic (default).** Windchill relies on web server authentication. Store the full header value, `Basic <base64 of user:password>`, as the secret `WINDCHILL_AUTHORIZATION` and send it as `"authorization"` in every payload.
* **OAuth 2.0.** When Windchill is set up as an OAuth resource server (client credentials for machine clients), send `"authorization": "Bearer <access token>"` and change every endpoint prefix from `/Windchill/servlet/odata/` to `/Windchill/oauth/servlet/odata/` ([WRS OAuth authorization](https://support.ptc.com/help/windchill_rest_services/r2.7/en/windchill_rest_services/oauth_for_wrs.html)). Getting the token from your authorization server is outside this connector.
* **CSRF nonce.** Every `POST` needs the header `CSRF_NONCE`. Publish on `mes/ptc-windchill/csrf-token/get`, read `NonceValue` from the reply and send it as `"nonce"`. The nonce belongs to the server session, so refresh it when POST calls start failing.

## Payload conventions

* `id` is a Windchill object ID, for example `OR:wt.part.WTPart:191559` (find it with `QueryParts` by number).
* `filter` is an OData `$filter` expression, **URL-encoded** because the broker puts it straight into the URL: `Number%20eq%20'0000000007'` or `startswith(Number,'00')`. Set the request header `PTC-WildcardSearch: true` (add it to the event) to use `*` wildcards.
* `request` is the JSON body sent unchanged on `POST` events.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "filter": "Number%20eq%20'0000000007'",
  "top": "10"
}
```

## Events

| Event | Method | Path (after `/Windchill/servlet/odata/`) | Topic | What it does |
| - | - | - | - | - |
| `GetCsrfToken` | GET | `PTC/GetCSRFToken()` | `mes/ptc-windchill/csrf-token/get` | CSRF nonce (NonceKey CSRF\_NONCE, NonceValue). Send NonceValue as nonce on every POST event |
| `QueryParts` | GET | `ProdMgmt/Parts?$filter={value.json.filter}&$top={value.json.top}` | `mes/ptc-windchill/parts/query` | Parts by OData $filter (URL-encoded, for example Number eq '...' or startswith(Number,'00')) and $top |
| `GetPart` | GET | `ProdMgmt/Parts('{value.json.id}')?$expand=Uses` | `mes/ptc-windchill/part/get` | One part by OID with its part usage links (Uses) |
| `GetPartStructure` | POST | `ProdMgmt/Parts('{value.json.id}')/PTC.ProdMgmt.GetPartStructure?$expand=Components($levels=max)` | `mes/ptc-windchill/part-structure/get` | Multi-level BOM (part structure) of a part with inline NavigationCriteria (config spec, view, plant filters); send \{} for the default filter |
| `GetComponentsReport` | POST | `ProdMgmt/Parts('{value.json.id}')/PTC.ProdMgmt.GetMultiLevelComponentsReport?$select=Quantity,Unit,Name,Number&$expand=Part($select=Identity,Name)` | `mes/ptc-windchill/components-report/get` | Consolidated multi-level components list (quantity, unit) for kitting and material staging; replaces deprecated GetPartsList |
| `GetPartAttachments` | GET | `ProdMgmt/Parts('{value.json.id}')/Attachments` | `mes/ptc-windchill/part-attachments/get` | Attachments (secondary content: file name, format, download URL) of a part, for work instruction display |
| `GetPartCadDocuments` | GET | `ProdMgmt/Parts('{value.json.id}')/PartDocAssociations?$expand=RelatedCADDoc($select=Identity)` | `mes/ptc-windchill/part-cad-documents/get` | CAD documents and drawings associated with a part |
| `QueryDocuments` | GET | `DocMgmt/Documents?$filter={value.json.filter}&$top={value.json.top}` | `mes/ptc-windchill/documents/query` | Documents by OData \$filter (URL-encoded), for example work instructions by number prefix |
| `GetDocumentStructure` | GET | `DocMgmt/Documents('{value.json.id}')/DocUsageLinks?$expand=DocUsedBy,DocUses` | `mes/ptc-windchill/document-structure/get` | Document structure (usage links to parent and child documents) |
| `ListProblemReports` | GET | `ChangeMgmt/ProblemReports` | `mes/ptc-windchill/problem-reports/list` | All problem reports visible to the user |
| `GetProblemReport` | GET | `ChangeMgmt/ProblemReports('{value.json.id}')` | `mes/ptc-windchill/problem-report/get` | One problem report by OID (state, priority, category) |
| `GetProblemReportAffectedObjects` | GET | `ChangeMgmt/ProblemReports('{value.json.id}')/CIAffectLinks?$expand=AffectedObjects` | `mes/ptc-windchill/problem-report-affected/get` | Affected parts / documents of a problem report |
| `CreateProblemReport` | POST | `ChangeMgmt/ProblemReports` | `mes/ptc-windchill/problem-report/create` | Write. problem report from a quality event, optionally with affected parts ([Changeables@odata.bind](mailto:Changeables@odata.bind)) in the product context |
| `CreateVariance` | POST | `ChangeMgmt/Variances` | `mes/ptc-windchill/variance/create` | Write. variance (deviation / waiver) request, for example to run a lot with an approved deviation |
| `ListChangeRequests` | GET | `ChangeMgmt/ChangeRequests?$expand=AffectedObjects` | `mes/ptc-windchill/change-requests/list` | Change requests with their affected objects |
| `ListChangeNotices` | GET | `ChangeMgmt/ChangeNotices` | `mes/ptc-windchill/change-notices/list` | Change notices (released engineering changes) to flag BOM / routing updates on the shop floor |
| `GetChangeNotice` | GET | `ChangeMgmt/ChangeNotices('{value.json.id}')` | `mes/ptc-windchill/change-notice/get` | One change notice by OID |

Replies arrive on `<topic>/response`.

### Part structure and kitting list

`GetPartStructure` returns the multi-level BOM; `GetComponentsReport` returns one consolidated line per component with total quantity and unit, which suits kitting and line-side staging. Both take a `NavigationCriteria` body (config spec, view, plant filters). Send `{}` to use the default filter, or the ID of a saved filter: `{"NavigationCriteria": {"ID": "OR:wt.filter.NavigationCriteria:..."}}`.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "id": "OR:wt.part.WTPart:191559",
  "nonce": "<NonceValue from GetCsrfToken>",
  "request": {
    "NavigationCriteria": {
      "ApplicableType": "PTC.ProdMgmt.Part",
      "ApplyToTopLevelObject": true,
      "Centricity": false,
      "ConfigSpecs": [
        {
          "@odata.type": "#PTC.NavCriteria.WTPartStandardConfigSpec",
          "WorkingIncluded": false,
          "View": "Manufacturing"
        }
      ],
      "Filters": [],
      "HideUnresolvedDependents": false,
      "UseDefaultForUnresolved": false
    }
  }
}
```

### Problem report from a quality event

`CreateProblemReport` creates a standalone problem report in a product or library context. Add affected parts with `Changeables@odata.bind`. Category, priority and life cycle values depend on your Change Management setup.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <base64 user:password>",
  "nonce": "<NonceValue from GetCsrfToken>",
  "request": {
    "Name": "Press 01 dimensional NOK",
    "Description": "Bore diameter out of tolerance on 3 of 20 parts (station 03)",
    "Category": {
      "Value": "DESIGN_ISSUE"
    },
    "IssuePriority": {
      "Value": "HIGH"
    },
    "Context@odata.bind": "Containers('OR:wt.pdmlink.PDMLinkProduct:122008')",
    "Changeables@odata.bind": [
      "Changeables('OR:wt.part.WTPart:122556')"
    ]
  }
}
```

## Connector

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — PTC Windchill (beta): read parts, part structures (multi-level BOM), consolidated
#   component lists, attachments and CAD / drawing associations, query documents, read problem reports, change requests
#   and change notices, and from a quality event create a problem report (with affected parts) or a variance, over
#   Windchill REST Services (WRS, OData v4) at /Windchill/servlet/odata/.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ptc-windchill
#
# Host: Windchill is installed per customer (or Windchill+ SaaS). Replace YOUR_WINDCHILL_SERVER with the Windchill web
#   server host (add :port when it does not share 443).
# Auth: HTTP Basic by default: publish "authorization": "Basic <base64 user:password>". OAuth 2.0 sites (Windchill as
#   resource server, client credentials) send "Bearer <token>" and must call /Windchill/oauth/servlet/odata/ instead:
#   replace the endpoint prefix. Keep credentials in Hub secrets.
# CSRF: POST events need "nonce": NonceValue from GetCsrfToken (header CSRF_NONCE). The nonce belongs to the session.
# Payloads: OIDs go in "id" (for example "OR:wt.part.WTPart:191559"); $filter values must be URL-encoded; "request" is
#   the JSON body sent unchanged.
#     QueryParts  {"authorization": "Basic ...", "filter": "Number%20eq%20'0000000007'", "top": "10"}
#

DEFINE CONNECTOR PtcWindchillApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_WINDCHILL_SERVER"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # CSRF nonce (NonceKey CSRF_NONCE, NonceValue). Send NonceValue as nonce on every POST event
    ADD EVENT GetCsrfToken
        WITH SOURCE_TOPIC "mes/ptc-windchill/csrf-token/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/csrf-token/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/PTC/GetCSRFToken()"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Parts by OData $filter (URL-encoded, for example Number eq '...' or startswith(Number,'00')) and $top
    ADD EVENT QueryParts
        WITH SOURCE_TOPIC "mes/ptc-windchill/parts/query"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/parts/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ProdMgmt/Parts?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # One part by OID with its part usage links (Uses)
    ADD EVENT GetPart
        WITH SOURCE_TOPIC "mes/ptc-windchill/part/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/part/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ProdMgmt/Parts('{value.json.id}')?$expand=Uses"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Multi-level BOM (part structure) of a part with inline NavigationCriteria (config spec, view, plant filters); send {} for the default filter
    ADD EVENT GetPartStructure
        WITH SOURCE_TOPIC "mes/ptc-windchill/part-structure/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/part-structure/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/Windchill/servlet/odata/ProdMgmt/Parts('{value.json.id}')/PTC.ProdMgmt.GetPartStructure?$expand=Components($levels=max)"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "CSRF_NONCE" "{value.json.nonce}"
        WITH BODY "{value.json.request}"
    # Consolidated multi-level components list (quantity, unit) for kitting and material staging; replaces deprecated GetPartsList
    ADD EVENT GetComponentsReport
        WITH SOURCE_TOPIC "mes/ptc-windchill/components-report/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/components-report/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/Windchill/servlet/odata/ProdMgmt/Parts('{value.json.id}')/PTC.ProdMgmt.GetMultiLevelComponentsReport?$select=Quantity,Unit,Name,Number&$expand=Part($select=Identity,Name)"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "CSRF_NONCE" "{value.json.nonce}"
        WITH BODY "{value.json.request}"
    # Attachments (secondary content: file name, format, download URL) of a part, for work instruction display
    ADD EVENT GetPartAttachments
        WITH SOURCE_TOPIC "mes/ptc-windchill/part-attachments/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/part-attachments/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ProdMgmt/Parts('{value.json.id}')/Attachments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # CAD documents and drawings associated with a part
    ADD EVENT GetPartCadDocuments
        WITH SOURCE_TOPIC "mes/ptc-windchill/part-cad-documents/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/part-cad-documents/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ProdMgmt/Parts('{value.json.id}')/PartDocAssociations?$expand=RelatedCADDoc($select=Identity)"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Documents by OData $filter (URL-encoded), for example work instructions by number prefix
    ADD EVENT QueryDocuments
        WITH SOURCE_TOPIC "mes/ptc-windchill/documents/query"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/documents/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/DocMgmt/Documents?$filter={value.json.filter}&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Document structure (usage links to parent and child documents)
    ADD EVENT GetDocumentStructure
        WITH SOURCE_TOPIC "mes/ptc-windchill/document-structure/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/document-structure/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/DocMgmt/Documents('{value.json.id}')/DocUsageLinks?$expand=DocUsedBy,DocUses"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # All problem reports visible to the user
    ADD EVENT ListProblemReports
        WITH SOURCE_TOPIC "mes/ptc-windchill/problem-reports/list"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/problem-reports/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/ProblemReports"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # One problem report by OID (state, priority, category)
    ADD EVENT GetProblemReport
        WITH SOURCE_TOPIC "mes/ptc-windchill/problem-report/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/problem-report/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/ProblemReports('{value.json.id}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Affected parts / documents of a problem report
    ADD EVENT GetProblemReportAffectedObjects
        WITH SOURCE_TOPIC "mes/ptc-windchill/problem-report-affected/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/problem-report-affected/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/ProblemReports('{value.json.id}')/CIAffectLinks?$expand=AffectedObjects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # WRITE: problem report from a quality event, optionally with affected parts (Changeables@odata.bind) in the product context
    ADD EVENT CreateProblemReport
        WITH SOURCE_TOPIC "mes/ptc-windchill/problem-report/create"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/problem-report/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/ProblemReports"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "CSRF_NONCE" "{value.json.nonce}"
        WITH BODY "{value.json.request}"
    # WRITE: variance (deviation / waiver) request, for example to run a lot with an approved deviation
    ADD EVENT CreateVariance
        WITH SOURCE_TOPIC "mes/ptc-windchill/variance/create"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/variance/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/Variances"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "CSRF_NONCE" "{value.json.nonce}"
        WITH BODY "{value.json.request}"
    # Change requests with their affected objects
    ADD EVENT ListChangeRequests
        WITH SOURCE_TOPIC "mes/ptc-windchill/change-requests/list"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/change-requests/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/ChangeRequests?$expand=AffectedObjects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # Change notices (released engineering changes) to flag BOM / routing updates on the shop floor
    ADD EVENT ListChangeNotices
        WITH SOURCE_TOPIC "mes/ptc-windchill/change-notices/list"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/change-notices/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/ChangeNotices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    # One change notice by OID
    ADD EVENT GetChangeNotice
        WITH SOURCE_TOPIC "mes/ptc-windchill/change-notice/get"
        WITH DESTINATION_TOPIC "mes/ptc-windchill/change-notice/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Windchill/servlet/odata/ChangeMgmt/ChangeNotices('{value.json.id}')"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

## Example actions

These actions refresh the CSRF nonce, look up a part by number from a station, request a kitting list when an order is released, and turn a press quality event into a problem report. Set `internal/ptc-windchill/product-context` to the product container OID (for example `OR:wt.pdmlink.PDMLinkProduct:122008`) first.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION WcCsrfRefresh
ON EVERY 20 MINUTES DO
    SET "auth" WITH GET SECRET "WINDCHILL_AUTHORIZATION"
    PUBLISH TOPIC "mes/ptc-windchill/csrf-token/get" WITH { "authorization": {auth} }

DEFINE ACTION WcKeepNonce
ON TOPIC "mes/ptc-windchill/csrf-token/get/response" DO
    SET "nonce" WITH (GET JSON "NonceValue" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/ptc-windchill/nonce" WITH {nonce}

DEFINE ACTION WcPartLookup
ON TOPIC "porto/line1/station03/work-instruction/part-number" DO
    SET "auth" WITH GET SECRET "WINDCHILL_AUTHORIZATION"
    SET "pn" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "mes/ptc-windchill/parts/query" WITH { "authorization": {auth}, "filter": "Number%20eq%20'" + {pn} + "'", "top": "1" }

DEFINE ACTION WcKittingList
ON TOPIC "porto/line1/order/released/part-oid" DO
    SET "auth" WITH GET SECRET "WINDCHILL_AUTHORIZATION"
    SET "nonce" WITH GET TOPIC "internal/ptc-windchill/nonce" AS STRING
    SET "oid" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "mes/ptc-windchill/components-report/get" WITH { "authorization": {auth}, "nonce": {nonce}, "id": {oid}, "request": {} }

DEFINE ACTION WcQualityEventToProblemReport
ON TOPIC "porto/line1/press01/quality-event" DO
    SET "auth" WITH GET SECRET "WINDCHILL_AUTHORIZATION"
    SET "nonce" WITH GET TOPIC "internal/ptc-windchill/nonce" AS STRING
    SET "ctx" WITH GET TOPIC "internal/ptc-windchill/product-context" AS STRING
    SET "title" WITH (GET JSON "title" IN PAYLOAD AS STRING)
    SET "detail" WITH (GET JSON "detail" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "mes/ptc-windchill/problem-report/create" WITH { "authorization": {auth}, "nonce": {nonce}, "request": { "Name": {title}, "Description": {detail}, "Category": { "Value": "OTHER" }, "IssuePriority": { "Value": "HIGH" }, "Context@odata.bind": "Containers('" + {ctx} + "')" } }
```

## Not included

* Updates, check out / check in, revise and delete operations (by policy for a shop-floor template).
* Content upload (three-stage upload to the file vault) and `DownloadContentAsZip` (returns a ZIP stream, not JSON). Use the download URL from `GetPartAttachments` instead.
* Deprecated `GetBOM` and `GetPartsList` actions (replaced by `GetPartStructure` and `GetMultiLevelComponentsReport`).
* Webhooks: Windchill has no generic outbound webhook. Poll `ListChangeNotices`, or push events with Windchill's own event and workflow tooling.

## Status

See also the [REST API connectors](/latest/lot-language/routes/rest-api-routes) base page and the [REST API apps catalog](/latest/lot-language/routes/rest-api-apps/index).


# PurpleAir
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/purpleair

Client-mode REST API connector for a curated PurpleAir v1 slice: list sensors and read one sensor

Technical Preview

# PurpleAir

Client-mode REST API connector for a curated PurpleAir v1 slice: list sensors and read one sensor.

* Hub category: **Public data**.
* Base: `https://api.purpleair.com`

## Template reference

Generated from the shipped broker template `purpleair` (`-connectorCode PURPLEAIR`). It lists every event the template defines.

### Auth

Auth headers used by the template: `X-API-Key: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the PurpleAir connector | no |
| `BaseUrl` | string | PurpleAir base URL without trailing slash (e.g. [https://api.purpleair.com](https://api.purpleair.com)) | yes |

`BASE_ADDRESS` default: `https://api.purpleair.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listsensors` | GET | `/v1/sensors?fields=name,humidity,temperature,pm2.5` | `public/purpleair/sensors/list` | `public/purpleair/sensors/list/response` | `api_token` |
| `Getsensor` | GET | `/v1/sensors/{value.json.sensor_index}` | `public/purpleair/sensors/get` | `public/purpleair/sensors/get/response` | `api_token`, `sensor_index` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode PURPLEAIR"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PurpleAirRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.purpleair.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listsensors
        WITH SOURCE_TOPIC "public/purpleair/sensors/list"
        WITH DESTINATION_TOPIC "public/purpleair/sensors/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/sensors?fields=name,humidity,temperature,pm2.5"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "Bearer {value.json.api_token}"
    ADD EVENT Getsensor
        WITH SOURCE_TOPIC "public/purpleair/sensors/get"
        WITH DESTINATION_TOPIC "public/purpleair/sensors/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/sensors/{value.json.sensor_index}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listsensors` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'public/purpleair/sensors/list/response' &
mosquitto_pub -t 'public/purpleair/sensors/list' -m '{"api_token": "<api_token>"}'
```


# Pushover
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/pushover

LoT connector for the Pushover Message API: send notifications including emergency priority, validate user keys, poll receipts and update glances

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Pushover Message API](https://pushover.net/api):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST messages.json | `POST /messages.json` | Push alert; `priority=2` + `retry`/`expire` for critical alarms |
| GET receipts/\{id}.json | `GET /receipts/{receipt_id}.json` | Poll emergency acknowledgement |
| POST glances.json | `POST /glances.json` | Live KPI text/count on glances widgets |
| POST users/validate.json | `POST /users/validate.json` | Credential check → `status: 1` + devices |
| GET sounds.json | `GET /sounds.json` | Built-in (+ custom) sound list |

Default `BASE_ADDRESS` is `https://api.pushover.net/1`. Topics use `messaging/pushover/<object>/<verb>`.

> [!NOTE]
>
> Auth is **not** OAuth: include application `token` (APP\_TOKEN) and recipient `user` (USER\_KEY) in the JSON body for POSTs, or `token` as a query parameter for GETs. Prefer Hub secrets `PUSHOVER_API_TOKEN` (alias `PUSHOVER_APP_TOKEN`) and `PUSHOVER_USER_KEY`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Pushover Message API v1
# Auth: token + user in JSON body / query (no Authorization header)
# BASE_ADDRESS: https://api.pushover.net/1

DEFINE CONNECTOR PushoverRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.pushover.net/1"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Sendmessage
        WITH SOURCE_TOPIC "messaging/pushover/message/send"
        WITH DESTINATION_TOPIC "messaging/pushover/message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/messages.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Validateuser
        WITH SOURCE_TOPIC "messaging/pushover/user/validate"
        WITH DESTINATION_TOPIC "messaging/pushover/user/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/users/validate.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getreceipt
        WITH SOURCE_TOPIC "messaging/pushover/receipt/get"
        WITH DESTINATION_TOPIC "messaging/pushover/receipt/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/receipts/{value.json.receipt_id}.json?token={value.json.token}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Listsounds
        WITH SOURCE_TOPIC "messaging/pushover/sound/list"
        WITH DESTINATION_TOPIC "messaging/pushover/sound/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sounds.json?token={value.json.token}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Updateglance
        WITH SOURCE_TOPIC "messaging/pushover/glance/update"
        WITH DESTINATION_TOPIC "messaging/pushover/glance/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/glances.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Sendmessage | POST | `/messages.json` | `messaging/pushover/message/send` | `messaging/pushover/message/send/response` |
| Validateuser | POST | `/users/validate.json` | `messaging/pushover/user/validate` | `messaging/pushover/user/validate/response` |
| Getreceipt | GET | `/receipts/{receipt_id}.json` | `messaging/pushover/receipt/get` | `messaging/pushover/receipt/get/response` |
| Listsounds | GET | `/sounds.json` | `messaging/pushover/sound/list` | `messaging/pushover/sound/list/response` |
| Updateglance | POST | `/glances.json` | `messaging/pushover/glance/update` | `messaging/pushover/glance/update/response` |

## Auth

1. [Register an application](https://pushover.net/apps/build) to get an API token (`APP_TOKEN`). Copy your user key from the [Pushover dashboard](https://pushover.net/).
2. Set connector `BASE_ADDRESS` to `https://api.pushover.net/1`.
3. Pass `token` and `user` on MQTT JSON payloads for POSTs. For GETs, pass `token` (and `receipt_id` for Getreceipt) so query/path placeholders resolve.
4. Store secrets in Hub / `GET SECRET "PUSHOVER_API_TOKEN"` and `GET SECRET "PUSHOVER_USER_KEY"`. Never commit real credentials.
5. Successful validate/send returns **HTTP 200** with `status: 1`. Emergency (`priority: 2`) responses include a `receipt` for polling.

## Example payloads

**validateUser:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_PUSHOVER_API_TOKEN",
  "user": "YOUR_PUSHOVER_USER_KEY"
}
```

**sendMessage (high priority):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_PUSHOVER_API_TOKEN",
  "user": "YOUR_PUSHOVER_USER_KEY",
  "title": "Coreflux alarm — Zone A",
  "message": "RMS exceeded limit on Zone A",
  "priority": 1,
  "sound": "siren"
}
```

**sendMessage (emergency / priority 2):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_PUSHOVER_API_TOKEN",
  "user": "YOUR_PUSHOVER_USER_KEY",
  "title": "CRITICAL — Zone A trip",
  "message": "Emergency stop engaged. Acknowledge required.",
  "priority": 2,
  "retry": 60,
  "expire": 1800,
  "sound": "persistent"
}
```

**listSounds:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_PUSHOVER_API_TOKEN"
}
```

**getReceipt:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_PUSHOVER_API_TOKEN",
  "receipt_id": "YOUR_30_CHAR_RECEIPT"
}
```

**updateGlance:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_PUSHOVER_API_TOKEN",
  "user": "YOUR_PUSHOVER_USER_KEY",
  "title": "Zone A",
  "text": "vibration_rms",
  "subtext": "12.4",
  "count": 3,
  "percent": 82
}
```

## Install

1. The template ships with the broker. List it with `-listTemplates` or fetch it from the Hub catalog.
2. Deploy with `-addConnector` from `PushoverRestApi.lot` (not `hub-metadata.lot`).

## See also

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# QAD Adaptive ERP
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/qad-adaptive-erp

LoT connector for QAD Adaptive ERP: read items, inventory, work orders, BOMs, routings and orders, and call Business Document and Service REST APIs

Technical Preview

## Overview

[QAD Adaptive ERP](https://www.qad.com/) (QAD Adaptive Applications) runs items, inventory, production, purchasing, sales and quality for many manufacturers. It is built on the **QAD Enterprise Platform (QEP)**, which serves REST APIs under the web application context, usually `/clouderp`. Connecting QAD to the broker lets the shop floor read work orders, on-hand inventory, BOMs and routings when a line needs them, check supplier and item certifications, and report production through the business services your environment exposes.

QAD has no single public API catalog. The platform has three kinds of REST API:

* **Business components** (`api/qracore/be/<URI>`): read a record by its domain and key fields. QAD names each component with a URI such as `urn:be:com.qad.base.item.IItem`.
* **Business documents**: complete documents with Query REST APIs (filtering, sorting, paging). Each environment documents its own under **Business Document API Documentation** (Swagger).
* **Business services**: non-CRUD methods exposed as REST with GET (query parameters) or POST (body). Each environment lists them under **Business Service API Documentation**.

The template has one client-mode connector, `QadAdaptiveErp`, with 36 events under `erp/qad/`. Each event publishes the reply on `<topic>/response`. 4 events write (business document submits and business service POSTs). The business component events only read, and there is no DELETE event.

| Event | Topic | Method | Use |
| - | - | - | - |
| `GetToken` | `erp/qad/auth/token` | POST | Get an access token (OAuth 2 password grant with your Client ID) (fields: `form`) |
| `RefreshToken` | `erp/qad/auth/token/refresh` | POST | Get a new access token with the refresh token (fields: `form`) |
| `GetEsignatureToken` | `erp/qad/auth/esignature-token` | POST | Get an e-signature token for the `*Esig` writes (fields: `authorization`, `body`) |
| `GetApps` | `erp/qad/platform/apps/get` | GET | Apps installed in the environment, for example query appURI=urn:app:com.qad.base (fields: `authorization`, `query`) |
| `ListWorkspaces` | `erp/qad/platform/workspaces/list` | GET | Domains / workspaces the API user can open (reply key qad-qracore: key, name, description, default) (path from a third-party client, not in QAD's guides) (fields: `authorization`) |
| `GetBusinessComponent` | `erp/qad/be/get` | GET | Read any business component by URI (`urn:be:<name>`) (fields: `authorization`, `beUri`, `query`) |
| `GetSite` | `erp/qad/sites/get` | GET | Read a site (`urn:be:com.qad.base.item.ISite`) (fields: `authorization`, `query`) |
| `GetItem` | `erp/qad/items/get` | GET | Read an item (item master) (`urn:be:com.qad.base.item.IItem`) (fields: `authorization`, `query`) |
| `GetItemSite` | `erp/qad/item-sites/get` | GET | Read item-site planning / inventory data (`urn:be:com.qad.base.item.IItemSite`) (fields: `authorization`, `query`) |
| `GetInventoryDetail` | `erp/qad/inventory/detail/get` | GET | Read inventory detail (on hand by site / location / lot / reference) (`urn:be:com.qad.inventory.inv.IInventoryDetail`) (fields: `authorization`, `query`) |
| `GetLocation` | `erp/qad/inventory/locations/get` | GET | Read a location master record (`urn:be:com.qad.inventory.inv.ILocationMaster`) (fields: `authorization`, `query`) |
| `GetLot` | `erp/qad/inventory/lots/get` | GET | Read a lot master record (`urn:be:com.qad.inventory.inv.ILotMaster`) (fields: `authorization`, `query`) |
| `GetInventoryTransactionHistory` | `erp/qad/inventory/transactions/history/get` | GET | Read inventory transaction history (`urn:be:com.qad.transhist.transaction.IInventoryTransHist`) (fields: `authorization`, `query`) |
| `GetWorkOrder` | `erp/qad/production/work-orders/get` | GET | Read a work order (header, status, quantities) (`urn:be:com.qad.pushproduction.workorder.IWorkOrderMaster`) (fields: `authorization`, `query`) |
| `GetWorkOrderRouting` | `erp/qad/production/work-order-routings/get` | GET | Read work order routing operations (`urn:be:com.qad.pushproduction.workorder.IWorkOrderRouting`) (fields: `authorization`, `query`) |
| `GetWorkOrderDetail` | `erp/qad/production/work-order-details/get` | GET | Read work order component requirements (`urn:be:com.qad.pushproduction.workorder.IWorkOrderDetail`) (fields: `authorization`, `query`) |
| `GetOperationHistory` | `erp/qad/production/operation-history/get` | GET | Read operation transaction history (labor, run, scrap reporting) (`urn:be:com.qad.transhist.transaction.IOperationTransHist`) (fields: `authorization`, `query`) |
| `GetBom` | `erp/qad/engineering/boms/get` | GET | Read a product structure (BOM) (`urn:be:com.qad.engineering.productstructure.IBom`) (fields: `authorization`, `query`) |
| `GetRoutingOperation` | `erp/qad/engineering/routing-operations/get` | GET | Read routing operations (`urn:be:com.qad.engineering.routing.IRoutingOperation`) (fields: `authorization`, `query`) |
| `GetProductionLine` | `erp/qad/engineering/production-lines/get` | GET | Read a production line (`urn:be:com.qad.engineering.setup.IProductionLine`) (fields: `authorization`, `query`) |
| `GetPurchaseOrder` | `erp/qad/purchasing/purchase-orders/get` | GET | Read a purchase order (`urn:be:com.qad.purchasing.purchaseorders.IPurchaseOrder`) (fields: `authorization`, `query`) |
| `GetPurchaseReceiptHistory` | `erp/qad/purchasing/receipts/history/get` | GET | Read purchase receipt history (`urn:be:com.qad.purchasing.receipts.IPurchaseReceiptHistory`) (fields: `authorization`, `query`) |
| `GetSalesOrder` | `erp/qad/sales/sales-orders/get` | GET | Read a sales order (`urn:be:com.qad.sales.salesorder.ISalesOrder`) (fields: `authorization`, `query`) |
| `GetShipper` | `erp/qad/logistics/shippers/get` | GET | Read a shipper header (`urn:be:com.qad.logistics.shipping.IShipperHeader`) (fields: `authorization`, `query`) |
| `GetSupplier` | `erp/qad/suppliers/get` | GET | Read a supplier (`urn:be:com.qad.base.supplier.ISupplier`) (fields: `authorization`, `query`) |
| `GetSupplierCertification` | `erp/qad/quality/supplier-certifications/get` | GET | Read a supplier certification (`urn:be:com.qad.base.supplier.ISupplierCertification`) (fields: `authorization`, `query`) |
| `GetItemCertification` | `erp/qad/quality/item-certifications/get` | GET | Read an item certification (`urn:be:com.qad.base.supplier.IItemCertification`) (fields: `authorization`, `query`) |
| `GetReasonCode` | `erp/qad/codes/reason-codes/get` | GET | Read a reason code (downtime, scrap, rework, ...) (`urn:be:com.qad.base.codes.IReasonCode`) (fields: `authorization`, `query`) |
| `GetInstalledBaseItem` | `erp/qad/service/installed-base/get` | GET | Read an installed base item (equipment at a customer) (`urn:be:com.qad.service.installedbase.IInstalledBaseItem`) (fields: `authorization`, `query`) |
| `BrowseQuery` | `erp/qad/browse/query` | GET | Multi-record read through a browse (path from a third-party client, not in QAD's guides) (fields: `authorization`, `browseId`, `query`) |
| `BusinessDocumentQuery` | `erp/qad/business-document/query` | GET | Query REST API of a business document (filtering, sorting, paging, partial data) (fields: `authorization`, `path`, `query`) |
| `BusinessDocumentSubmit` | `erp/qad/business-document/submit` | POST | **Write.** Send a complete business document (fields: `authorization`, `body`, `path`) |
| `BusinessDocumentSubmitEsig` | `erp/qad/business-document/submit-esig` | POST | **Write.** Same as BusinessDocumentSubmit with X-QAD-Esig-Token from GetEsignatureToken, for components with an active e-signature configuration (fields: `authorization`, `body`, `esig_token`, `path`) |
| `BusinessServiceGet` | `erp/qad/business-service/get` | GET | Call a business service (non-CRUD method exposed as REST) (fields: `authorization`, `path`, `query`) |
| `BusinessServicePost` | `erp/qad/business-service/post` | POST | **Write (may write).** Call a business service whose HTTP Method Type is POST, for example a production or inventory transaction service (fields: `authorization`, `body`, `path`) |
| `BusinessServicePostEsig` | `erp/qad/business-service/post-esig` | POST | **Write (may write).** Same as BusinessServicePost with X-QAD-Esig-Token (fields: `authorization`, `body`, `esig_token`, `path`) |

## Prerequisites

* A QAD Adaptive ERP environment (QAD cloud or on-premises) reachable over HTTPS from the broker. Note its host and web application context: `/clouderp` on QAD cloud; some on-premises installs use `/qad-central`.
* A **Client ID** for the broker, generated in **Client IDs** (Adaptive UX) or **Client ID Maintenance** (36.3.12). Use one Client ID per integration.
* An API user who can sign in with a password (not single sign-on only), with the **webui\_user** role, **Read** on each business component or browse you call, and **Execute** on each business service (Role Permissions > Not In Menu > Integration > External Business Services).
* The domain code you work in, and the key field names of each component (Business Components > Fields, or the component's Swagger).
* For business documents and business services: the REST path and body schema from **Business Document API Documentation** or **Business Service API Documentation** in your environment.

## Connection and security

QAD's API authentication is OAuth 2 (password grant) or HTTP Basic. QAD recommends OAuth 2. Store the credentials as broker secrets and build the token form with `GET SECRET`:

| Secret | Value |
| - | - |
| `QAD_CLIENT_ID` | The Client ID generated for Coreflux |
| `QAD_USERNAME` | The API user |
| `QAD_PASSWORD` | The API user's password, URL-encoded (it goes into a form body) |

`GetToken` posts `client_id=<Client ID>&grant_type=password&username=<user>&password=<password>` as `application/x-www-form-urlencoded` to `/clouderp/oauth/token`. No client secret is sent. The reply carries `access_token` and `refresh_token`. Send `"authorization": "Bearer <access_token>"` on every other event. A Basic value (`Basic <base64 user:password>`) also works in the same field, but QAD discourages it.

When a component has an active **e-signature** configuration, a write without a token fails with `APIModeRequiredException` or `ESignatureRequiredException`. Call `GetEsignatureToken` with `{"password", "reasonCode", "remarks"}` and use the `*Esig` events, which send the token in the `X-QAD-Esig-Token` header.

If your environment uses `/qad-central` (or another context), replace `/clouderp/` in every endpoint before you deploy, and change `BASE_ADDRESS` to your host.

## Payload

Publish JSON on the event's source topic. The broker fills the `{value.json.<field>}` placeholders:

* `authorization`: on every event except `GetToken` and `RefreshToken`.
* `query`: URL-encoded query string, for example `domainCode=<domain>&itemCode=<item>`. Use `""` for none.
* `form`: the URL-encoded token form on `GetToken` and `RefreshToken`.
* `body`: JSON on POST events.
* `path`: the REST path from the API documentation screen (starts with `/clouderp/api/...`) on the business document and business service events.
* `beUri`: the business component URI on `GetBusinessComponent`.
* `browseId`: the browse URI (`urn:browse:<type>:<id>`) on `BrowseQuery`.
* `esig_token`: the e-signature token on the `*Esig` events.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Bearer <token>", "query": "domainCode=<domain>&itemCode=<item>"}
```

Values are not URL-encoded by the connector, so encode `query` and `form` before you publish.

## Pacing and errors

QAD publishes no rate limit or token lifetime. Read `expires_in` from the token reply and refresh before it runs out. Business document queries support paging; ask for small pages from the shop floor.

Errors come back with the HTTP status and QAD's envelope:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"submitResult": {"success": false, "errors": [{"severity": 1, "code": "401", "message": "Unauthorized. "}]}, "data": null}
```

A bad or expired bearer returns 401 with `{"error": "invalid_token"}`. A token request with an unknown Client ID returns 401 `The client is not authenticated.`

## Example actions

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the QadAdaptiveErp route (docs page). Not part of the route template.
# Secrets: QAD_CLIENT_ID (a Client ID generated in Client IDs / Client ID Maintenance 36.3.12 for this integration),
#   QAD_USERNAME and QAD_PASSWORD (an API user with the webui_user role and Read on the components used; store the
#   password URL-encoded because it goes into a form body). QAD does not publish the token lifetime, so the token
#   action runs every 10 minutes; lengthen it to just under the expires_in your environment returns.
#   The bearer value is kept on internal/qad/authorization. Replace the <...> placeholders (domain, key fields, path).

DEFINE ACTION QadGetToken
ON EVERY 10 MINUTES DO
    SET "cid" WITH GET SECRET "QAD_CLIENT_ID"
    SET "user" WITH GET SECRET "QAD_USERNAME"
    SET "pwd" WITH GET SECRET "QAD_PASSWORD"
    SET "form" WITH "client_id=" + {cid} + "&grant_type=password&username=" + {user} + "&password=" + {pwd}
    PUBLISH TOPIC "erp/qad/auth/token" WITH { "form": {form} }

DEFINE ACTION QadKeepToken
ON TOPIC "erp/qad/auth/token/response" DO
    SET "tok" WITH (GET JSON "access_token" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/qad/authorization" WITH "Bearer " + {tok}

DEFINE ACTION QadItemOnRequest
ON TOPIC "plant/line1/item/request" DO
    SET "auth" WITH GET TOPIC "internal/qad/authorization" AS STRING
    SET "item" WITH PAYLOAD AS STRING
    SET "q" WITH "domainCode=<domain>&itemCode=" + {item}
    PUBLISH TOPIC "erp/qad/items/get" WITH { "authorization": {auth}, "query": {q} }

DEFINE ACTION QadWorkOrderEvery5Minutes
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET TOPIC "internal/qad/authorization" AS STRING
    PUBLISH TOPIC "erp/qad/production/work-orders/get" WITH { "authorization": {auth}, "query": "domainCode=<domain>&<work order key field>=<value>" }

DEFINE ACTION QadReportProductionFromLine
ON TOPIC "plant/line1/counter/good" DO
    SET "auth" WITH GET TOPIC "internal/qad/authorization" AS STRING
    SET "qty" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "erp/qad/business-service/post" WITH { "authorization": {auth}, "path": "<REST URL Path of your production reporting business service>", "body": { "domainCode": "<domain>", "quantity": {qty} } }
```

## Connector template

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — QAD Adaptive ERP (QAD Adaptive Applications on the QAD Enterprise Platform, cloud or
#   on-premises) for plants: OAuth 2 token (password grant) from the platform, read business components (sites, items,
#   item-sites, inventory detail, locations, lots, work orders with routing and component lines, BOMs, routings,
#   production lines, purchase orders, receipts, sales orders, shippers, inventory and operation transaction history,
#   supplier / item certifications, reason codes, installed base), run browse queries, and call the Business Document
#   and Business Service REST APIs your environment publishes (with an e-signature token when a component needs it).
#   (connect.qad.com/web/documentlibrary, no login): QAD Enterprise Platform Developer Guide 2020 (QEP_DG_v2020: URI
#   formats, api/qracore/be/<business component URI>?domainCode=..&<key>=.. reads, api/qracore/apps, API auth = OAuth2
#   and HTTP Basic), QAD Security Administration Guides 2024 QAE + QAD Adaptive 2026 (API Authentication: POST
#   /clouderp/oauth/token password grant with client_id, Client IDs), 2020 QAE (business component URIs, from its
#   field security appendix) and the AI_Docs Security Admin Guide (e-signature API mode: POST /api/qracore/esignature/token -> X-QAD-Esig-Token header, submitResult error envelope),
#   QAD Online Help Foundation (Business Document / Business Service API Documentation screens: per-environment
#   Swagger / OpenAPI, Business Service HTTP method GET or POST with QUERY or BODY parameters), QAD Adaptive release
#   documentlibrary.qad.com (online help + Swagger guides) sits behind a Cloudflare Turnstile challenge and the real
#   per-document Swagger lives inside each QAD environment (Development > Business Document API Documentation), so
#   there is no public OpenAPI. Business document / business service paths are payload fields copied from that screen.
#   The browse query path api/qracore/browses?browseId=..&filters=..&fields=..&pageSize=.. and api/webshell/workspaces
#   are NOT in QAD's public guides: they come from a public QAD client (github.com/frantm05/QMA) and are marked as such.
#  
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/qad-adaptive-erp
#
# One route, topic prefix erp/qad/:
#   QadAdaptiveErp  https://qad.example.com  (your QAD Adaptive host). Every path starts with the web app context
#   /clouderp (QAD's documented example, used by QAD cloud). Some on-premises installs serve the same app as
#   /qad-central (QAD Implementation Guide examples): replace "/clouderp/" with "/qad-central/" in every endpoint then.
# Auth (QAD Security Administration Guide, "API Authentication"): OAuth 2 or HTTP Basic.
#   GetToken: POST /clouderp/oauth/token, application/x-www-form-urlencoded
#     client_id=<Client ID>&grant_type=password&username=<user>&password=<password>  (no client secret in the request)
#   -> access_token (+ refresh_token). Send "authorization":"Bearer <access_token>" on every other event. HTTP Basic
#   ("Basic <base64 user:password>") also works in the same field but QAD discourages it (re-authenticates every call).
#   Client IDs are generated in Client IDs (Adaptive UX) / Client ID Maintenance 36.3.12 — use one per integration.
#   The API user needs the webui_user role plus Read on each business component / browse and Execute on each business
#   service (Role Permissions > Not In Menu > Integration > External Business Services).
# E-signature: if a component has an active e-signature configuration, writes fail with APIModeRequiredException /
#   ESignatureRequiredException. Get a token with GetEsignatureToken {"password","reasonCode","remarks"} and use the
#   *Esig write events, which add header X-QAD-Esig-Token.
# Scope: most components are domain-scoped; pass domainCode (and site / entity where the component is site- or
#   entity-scoped) plus the key fields in "query", for example domainCode=<domain>&itemCode=<item> (the DG shows domainCode + key-field
#   query parameters; check each component's key field names in Business Components > Fields or its Swagger).
# Errors: HTTP status + {"submitResult":{"success":false,"errors":[{"severity","code","message","messageType",...}]},
#   "data":null}. 401 without or with a bad token (Spring OAuth "invalid_token" for a bad bearer).
# Writes (# WRITE): business documents and business services only. QAD's public guides do not document create / update
#   / delete verbs on api/qracore/be, so this template does not write through it, and has no DELETE event.
# Not packaged: QXtend (SOAP), Business Events (published to an event streaming platform, not HTTP callbacks), QAD
#   Integration Platform (Boomi) flows, analytics / composer admin APIs, Java extension framework.
#
# Payload fields (JSON on the source topic): authorization on every event except GetToken / RefreshToken;
#   query = URL-encoded query string ("" for none); body = JSON string on POST; path = the REST path from the Business
#   Document / Business Service API Documentation screen (starts /clouderp/api/...); beUri on GetBusinessComponent;
#   browseId on BrowseQuery; esig_token on the *Esig events; form on the token events.
#     GetToken               {"form":"client_id=<client id>&grant_type=password&username=<user>&password=<password>"}
#     GetItem                {"authorization":"Bearer <token>","query":"domainCode=<domain>&itemCode=<item>"}
#     GetWorkOrder           {"authorization":"Bearer <token>","query":"domainCode=<domain>&<key field>=<value>"}  (key field names: see the component in Business Components > Fields or its Swagger)
#     BrowseQuery            {"authorization":"Bearer <token>","browseId":"urn:browse:mfg:<browse>","query":"filters=..&fields=..&pageSize=100"}
#     BusinessServicePost    {"authorization":"Bearer <token>","path":"/clouderp/api/<from the screen>","body":"{...}"}

DEFINE CONNECTOR QadAdaptiveErp WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://qad.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Replace with your QAD Adaptive host (https://<host>[:port]). Paths start /clouderp (or /qad-central on some on-premises installs).
    # OAuth 2 token endpoint (Security Administration Guide, API Authentication): Password grant: form client_id=<Client ID>&grant_type=password&username=..&password=.. (client secret not sent). Returns access_token, refresh_token, expires_in.
    ADD EVENT GetToken
        WITH SOURCE_TOPIC "erp/qad/auth/token"
        WITH DESTINATION_TOPIC "erp/qad/auth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/clouderp/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    # OAuth 2 token endpoint, refresh_token grant (RFC 6749 section 6; the guide says the password flow issues access and refresh tokens): form client_id=<Client ID>&grant_type=refresh_token&refresh_token=<refresh_token>.
    ADD EVENT RefreshToken
        WITH SOURCE_TOPIC "erp/qad/auth/token/refresh"
        WITH DESTINATION_TOPIC "erp/qad/auth/token/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/clouderp/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    # E-signature API mode (Security Administration Guide, Electronic Signatures): body {"password":..,"reasonCode":..,"remarks":..} for the current user. Returns a base64 token for header X-QAD-Esig-Token on the *Esig writes.
    ADD EVENT GetEsignatureToken
        WITH SOURCE_TOPIC "erp/qad/auth/esignature-token"
        WITH DESTINATION_TOPIC "erp/qad/auth/esignature-token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/clouderp/api/qracore/esignature/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Platform apps (QEP Developer Guide 2020: api/qracore/apps?appURI={appURI}): Apps installed in the environment, for example query appURI=urn:app:com.qad.base. Good connectivity / token check.
    ADD EVENT GetApps
        WITH SOURCE_TOPIC "erp/qad/platform/apps/get"
        WITH DESTINATION_TOPIC "erp/qad/platform/apps/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/apps?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Web shell workspaces (NOT in QAD's public guides; observed in public QAD client github.com/frantm05/QMA): Domains / workspaces the API user can open (reply key qad-qracore: key, name, description, default). Gives the domainCode values.
    ADD EVENT ListWorkspaces
        WITH SOURCE_TOPIC "erp/qad/platform/workspaces/list"
        WITH DESTINATION_TOPIC "erp/qad/platform/workspaces/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/webshell/workspaces"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Any business component (QEP Developer Guide 2020): GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). beUri: urn:be:<name>, for example urn:be:com.qad.base.item.IItem; query: domainCode + key fields.
    ADD EVENT GetBusinessComponent
        WITH SOURCE_TOPIC "erp/qad/be/get"
        WITH DESTINATION_TOPIC "erp/qad/be/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/{value.json.beUri}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component ISite (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a site. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetSite
        WITH SOURCE_TOPIC "erp/qad/sites/get"
        WITH DESTINATION_TOPIC "erp/qad/sites/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.base.item.ISite?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IItem (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read an item (item master). GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetItem
        WITH SOURCE_TOPIC "erp/qad/items/get"
        WITH DESTINATION_TOPIC "erp/qad/items/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.base.item.IItem?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IItemSite (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read item-site planning / inventory data. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetItemSite
        WITH SOURCE_TOPIC "erp/qad/item-sites/get"
        WITH DESTINATION_TOPIC "erp/qad/item-sites/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.base.item.IItemSite?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IInventoryDetail (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read inventory detail (on hand by site / location / lot / reference). GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetInventoryDetail
        WITH SOURCE_TOPIC "erp/qad/inventory/detail/get"
        WITH DESTINATION_TOPIC "erp/qad/inventory/detail/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.inventory.inv.IInventoryDetail?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component ILocationMaster (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a location master record. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetLocation
        WITH SOURCE_TOPIC "erp/qad/inventory/locations/get"
        WITH DESTINATION_TOPIC "erp/qad/inventory/locations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.inventory.inv.ILocationMaster?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component ILotMaster (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a lot master record. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetLot
        WITH SOURCE_TOPIC "erp/qad/inventory/lots/get"
        WITH DESTINATION_TOPIC "erp/qad/inventory/lots/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.inventory.inv.ILotMaster?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IInventoryTransHist (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read inventory transaction history. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetInventoryTransactionHistory
        WITH SOURCE_TOPIC "erp/qad/inventory/transactions/history/get"
        WITH DESTINATION_TOPIC "erp/qad/inventory/transactions/history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.transhist.transaction.IInventoryTransHist?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IWorkOrderMaster (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a work order (header, status, quantities). GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetWorkOrder
        WITH SOURCE_TOPIC "erp/qad/production/work-orders/get"
        WITH DESTINATION_TOPIC "erp/qad/production/work-orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.pushproduction.workorder.IWorkOrderMaster?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IWorkOrderRouting (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read work order routing operations. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetWorkOrderRouting
        WITH SOURCE_TOPIC "erp/qad/production/work-order-routings/get"
        WITH DESTINATION_TOPIC "erp/qad/production/work-order-routings/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.pushproduction.workorder.IWorkOrderRouting?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IWorkOrderDetail (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read work order component requirements. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetWorkOrderDetail
        WITH SOURCE_TOPIC "erp/qad/production/work-order-details/get"
        WITH DESTINATION_TOPIC "erp/qad/production/work-order-details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.pushproduction.workorder.IWorkOrderDetail?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IOperationTransHist (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read operation transaction history (labor, run, scrap reporting). GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetOperationHistory
        WITH SOURCE_TOPIC "erp/qad/production/operation-history/get"
        WITH DESTINATION_TOPIC "erp/qad/production/operation-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.transhist.transaction.IOperationTransHist?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IBom (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a product structure (BOM). GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetBom
        WITH SOURCE_TOPIC "erp/qad/engineering/boms/get"
        WITH DESTINATION_TOPIC "erp/qad/engineering/boms/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.engineering.productstructure.IBom?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IRoutingOperation (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read routing operations. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetRoutingOperation
        WITH SOURCE_TOPIC "erp/qad/engineering/routing-operations/get"
        WITH DESTINATION_TOPIC "erp/qad/engineering/routing-operations/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.engineering.routing.IRoutingOperation?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IProductionLine (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a production line. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetProductionLine
        WITH SOURCE_TOPIC "erp/qad/engineering/production-lines/get"
        WITH DESTINATION_TOPIC "erp/qad/engineering/production-lines/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.engineering.setup.IProductionLine?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IPurchaseOrder (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a purchase order. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetPurchaseOrder
        WITH SOURCE_TOPIC "erp/qad/purchasing/purchase-orders/get"
        WITH DESTINATION_TOPIC "erp/qad/purchasing/purchase-orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.purchasing.purchaseorders.IPurchaseOrder?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IPurchaseReceiptHistory (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read purchase receipt history. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetPurchaseReceiptHistory
        WITH SOURCE_TOPIC "erp/qad/purchasing/receipts/history/get"
        WITH DESTINATION_TOPIC "erp/qad/purchasing/receipts/history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.purchasing.receipts.IPurchaseReceiptHistory?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component ISalesOrder (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a sales order. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetSalesOrder
        WITH SOURCE_TOPIC "erp/qad/sales/sales-orders/get"
        WITH DESTINATION_TOPIC "erp/qad/sales/sales-orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.sales.salesorder.ISalesOrder?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IShipperHeader (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a shipper header. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetShipper
        WITH SOURCE_TOPIC "erp/qad/logistics/shippers/get"
        WITH DESTINATION_TOPIC "erp/qad/logistics/shippers/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.logistics.shipping.IShipperHeader?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component ISupplier (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a supplier. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetSupplier
        WITH SOURCE_TOPIC "erp/qad/suppliers/get"
        WITH DESTINATION_TOPIC "erp/qad/suppliers/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.base.supplier.ISupplier?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component ISupplierCertification (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a supplier certification. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetSupplierCertification
        WITH SOURCE_TOPIC "erp/qad/quality/supplier-certifications/get"
        WITH DESTINATION_TOPIC "erp/qad/quality/supplier-certifications/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.base.supplier.ISupplierCertification?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IItemCertification (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read an item certification. GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetItemCertification
        WITH SOURCE_TOPIC "erp/qad/quality/item-certifications/get"
        WITH DESTINATION_TOPIC "erp/qad/quality/item-certifications/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.base.supplier.IItemCertification?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IReasonCode (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read a reason code (downtime, scrap, rework, ...). GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetReasonCode
        WITH SOURCE_TOPIC "erp/qad/codes/reason-codes/get"
        WITH DESTINATION_TOPIC "erp/qad/codes/reason-codes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.base.codes.IReasonCode?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business component IInstalledBaseItem (URI from QAD Security Administration Guide 2020 QAE (field security appendix)): Read an installed base item (equipment at a customer). GET QEP Developer Guide 2020: api/qracore/be/<business component URI>?domainCode=..&<key>=.. (doHttpGet examples). query: domainCode + key fields (URL-encoded); reply data holds the record(s).
    ADD EVENT GetInstalledBaseItem
        WITH SOURCE_TOPIC "erp/qad/service/installed-base/get"
        WITH DESTINATION_TOPIC "erp/qad/service/installed-base/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/be/urn:be:com.qad.service.installedbase.IInstalledBaseItem?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Browse query (browse URIs urn:browse:<type>:<id> are in the QEP Developer Guide; this REST path is NOT in QAD's public guides, observed in public QAD client github.com/frantm05/QMA): Multi-record read through a browse. query: filters=<table.field> EQ '<value>' (URL-encoded), fields=<table.field,...>, pageSize=<n>. Reply data is the row list.
    ADD EVENT BrowseQuery
        WITH SOURCE_TOPIC "erp/qad/browse/query"
        WITH DESTINATION_TOPIC "erp/qad/browse/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/clouderp/api/qracore/browses?browseId={value.json.browseId}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # Business Document API (Online Help Foundation: Business Document API Documentation; per-environment Swagger / OpenAPI): Query REST API of a business document (filtering, sorting, paging, partial data). path = API URL from the Business Document API Documentation screen.
    ADD EVENT BusinessDocumentQuery
        WITH SOURCE_TOPIC "erp/qad/business-document/query"
        WITH DESTINATION_TOPIC "erp/qad/business-document/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "{value.json.path}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # WRITE Business Document API (Online Help Foundation; inbound integration of a whole document, e.g. sales order header + lines): WRITE: send a complete business document. Check the method and body schema in your environment's Swagger before use.
    ADD EVENT BusinessDocumentSubmit
        WITH SOURCE_TOPIC "erp/qad/business-document/submit"
        WITH DESTINATION_TOPIC "erp/qad/business-document/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE Business Document API + e-signature API mode (Security Administration Guide): WRITE: same as BusinessDocumentSubmit with X-QAD-Esig-Token from GetEsignatureToken, for components with an active e-signature configuration.
    ADD EVENT BusinessDocumentSubmitEsig
        WITH SOURCE_TOPIC "erp/qad/business-document/submit-esig"
        WITH DESTINATION_TOPIC "erp/qad/business-document/submit-esig/response"
        WITH METHOD "POST"
        WITH ENDPOINT "{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-QAD-Esig-Token" "{value.json.esig_token}"
        WITH BODY "{value.json.body}"
    # Business Service API, HTTP method GET + QUERY parameters (Online Help Foundation: Business Services panel): Call a business service (non-CRUD method exposed as REST) whose HTTP Method Type is GET. path = REST URL Path from the Business Service API Documentation screen.
    ADD EVENT BusinessServiceGet
        WITH SOURCE_TOPIC "erp/qad/business-service/get"
        WITH DESTINATION_TOPIC "erp/qad/business-service/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "{value.json.path}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
    # WRITE Business Service API, HTTP method POST + BODY parameters (Online Help Foundation: Business Services panel): WRITE (may write): call a business service whose HTTP Method Type is POST, for example a production or inventory transaction service.
    ADD EVENT BusinessServicePost
        WITH SOURCE_TOPIC "erp/qad/business-service/post"
        WITH DESTINATION_TOPIC "erp/qad/business-service/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE Business Service API + e-signature API mode (Security Administration Guide): WRITE (may write): same as BusinessServicePost with X-QAD-Esig-Token.
    ADD EVENT BusinessServicePostEsig
        WITH SOURCE_TOPIC "erp/qad/business-service/post-esig"
        WITH DESTINATION_TOPIC "erp/qad/business-service/post-esig/response"
        WITH METHOD "POST"
        WITH ENDPOINT "{value.json.path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
            ADD "X-QAD-Esig-Token" "{value.json.esig_token}"
        WITH BODY "{value.json.body}"
```

## Not packaged

* Create, update or delete through `api/qracore/be` (not in QAD's public guides), and any DELETE event.
* QXtend (SOAP) inbound and outbound.
* Business Events: QAD publishes them to an event streaming platform through the Integration Platform, not to HTTP callbacks, so there is no receiver connector.
* QAD Integration Platform flows, analytics and composer admin APIs, and the Java extension framework.
* Fixed events for single business documents or business services: their paths and schemas differ per environment, so use the generic events with the path from your API documentation screen.


# QAD Redzone
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/qad-redzone

LoT connector for the QAD Redzone API v2: OAuth tokens, locations, start and stop runs, shifts, maintenance actions, data sheets, assets and event polling

Technical Preview

## Overview

Client-mode REST API connector for the QAD Redzone public API v2: OAuth token and locations plus runs and shifts and maintenance actions and data sheets and event polling. `BASE_ADDRESS` defaults to `https://api.rz-ops.com`. Topics use `mes/redzone/<object>/<verb>`.

| Event | Request | Source topic |
| - | - | - |
| `OAuthToken` | `POST /public/v2/oauth/token` | `mes/redzone/oauth/token/create` |
| `LocationsList` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations?limit={value.json.limit}&offset={value.json.offset}` | `mes/redzone/locations/list` |
| `RunsList` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs?limit={value.json.limit}&offset={value.json.offset}&started-after={value.json.startedAfter}` | `mes/redzone/runs/list` |
| `RunGet` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs/{value.json.runId}` | `mes/redzone/runs/get` |
| `CurrentRunsAtLocation` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/runs/current?limit={value.json.limit}&offset={value.json.offset}` | `mes/redzone/locations/runs/current` |
| `CurrentShiftAtLocation` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/shifts/current` | `mes/redzone/locations/shifts/current` |
| `RunStart` | `POST /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs/start` | `mes/redzone/runs/start` |
| `RunStop` | `POST /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs/{value.json.runId}/stop` | `mes/redzone/runs/stop` |
| `ScheduledRunsList` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/scheduled-runs?limit={value.json.limit}&offset={value.json.offset}` | `mes/redzone/locations/scheduled-runs/list` |
| `ScheduledRunCreate` | `POST /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/scheduled-runs` | `mes/redzone/locations/scheduled-runs/create` |
| `MaintenanceActionsList` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/maintenance/actions?limit={value.json.limit}&offset={value.json.offset}` | `mes/redzone/maintenance/actions/list` |
| `MaintenanceActionCommentCreate` | `POST /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/maintenance/actions/{value.json.maintenanceActionId}/comments` | `mes/redzone/maintenance/actions/comments/create` |
| `CompletedDataSheetsList` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/completed-data-sheets?limit={value.json.limit}&offset={value.json.offset}` | `mes/redzone/data-sheets/completed/list` |
| `AssetsList` | `GET /public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/assets?limit={value.json.limit}&offset={value.json.offset}` | `mes/redzone/assets/list` |
| `EventsList` | `GET /public/v2/organizations/{value.json.organizationId}/events?limit={value.json.limit}&visibility-timeout={value.json.visibilityTimeout}` | `mes/redzone/events/list` |

## Authentication

OAuth 2.0 client credentials. POST /public/v2/oauth/token with \{"client\_id","client\_secret"} (JSON) returns an access token; send it as Authorization: Bearer \{value.json.access\_token}. Client ID and secret are issued by Redzone to the customer organization. Runs, shifts, data sheets and problem types need the enterprise-integration entitlement; maintenance actions also need reliability-integration (x-entitlements in the OpenAPI spec).

> [!WARNING]
>
> Keep credentials in broker secrets and never retain topics that carry tokens or client secrets.

## Notes

* The Redzone OpenAPI spec (REDZONE PUBLIC API 2.0.0) is public at [https://api.rz-ops.com/public/v2/openapi.json](https://api.rz-ops.com/public/v2/openapi.json); the Developer Hub UI itself is not public.
* API credentials (client\_id / client\_secret) are issued by Redzone to the customer. Nothing in the public material requires a QAD partner agreement, but endpoints tagged x-entitlements enterprise-integration (runs, shifts, data sheets, problem types) and reliability-integration (maintenance actions) need those Redzone add-ons on the customer contract.
* OAuthToken is the only event whose body carries a credential (client\_id / client\_secret in the token request), the same pattern as the Box OAuthToken event. Never retain mes/redzone/oauth/# and restrict it with ACLs.
* List endpoints require limit (1..100) and offset (>= 0) query values; pass them on every list payload.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR QadRedzoneRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.rz-ops.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT OAuthToken
        WITH SOURCE_TOPIC "mes/redzone/oauth/token/create"
        WITH DESTINATION_TOPIC "mes/redzone/oauth/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/v2/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT LocationsList
        WITH SOURCE_TOPIC "mes/redzone/locations/list"
        WITH DESTINATION_TOPIC "mes/redzone/locations/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations?limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RunsList
        WITH SOURCE_TOPIC "mes/redzone/runs/list"
        WITH DESTINATION_TOPIC "mes/redzone/runs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs?limit={value.json.limit}&offset={value.json.offset}&started-after={value.json.startedAfter}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RunGet
        WITH SOURCE_TOPIC "mes/redzone/runs/get"
        WITH DESTINATION_TOPIC "mes/redzone/runs/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs/{value.json.runId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CurrentRunsAtLocation
        WITH SOURCE_TOPIC "mes/redzone/locations/runs/current"
        WITH DESTINATION_TOPIC "mes/redzone/locations/runs/current/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/runs/current?limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CurrentShiftAtLocation
        WITH SOURCE_TOPIC "mes/redzone/locations/shifts/current"
        WITH DESTINATION_TOPIC "mes/redzone/locations/shifts/current/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/shifts/current"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT RunStart
        WITH SOURCE_TOPIC "mes/redzone/runs/start"
        WITH DESTINATION_TOPIC "mes/redzone/runs/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs/start"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT RunStop
        WITH SOURCE_TOPIC "mes/redzone/runs/stop"
        WITH DESTINATION_TOPIC "mes/redzone/runs/stop/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/runs/{value.json.runId}/stop"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY ""
    ADD EVENT ScheduledRunsList
        WITH SOURCE_TOPIC "mes/redzone/locations/scheduled-runs/list"
        WITH DESTINATION_TOPIC "mes/redzone/locations/scheduled-runs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/scheduled-runs?limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ScheduledRunCreate
        WITH SOURCE_TOPIC "mes/redzone/locations/scheduled-runs/create"
        WITH DESTINATION_TOPIC "mes/redzone/locations/scheduled-runs/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/locations/{value.json.locationId}/scheduled-runs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT MaintenanceActionsList
        WITH SOURCE_TOPIC "mes/redzone/maintenance/actions/list"
        WITH DESTINATION_TOPIC "mes/redzone/maintenance/actions/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/maintenance/actions?limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT MaintenanceActionCommentCreate
        WITH SOURCE_TOPIC "mes/redzone/maintenance/actions/comments/create"
        WITH DESTINATION_TOPIC "mes/redzone/maintenance/actions/comments/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/maintenance/actions/{value.json.maintenanceActionId}/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CompletedDataSheetsList
        WITH SOURCE_TOPIC "mes/redzone/data-sheets/completed/list"
        WITH DESTINATION_TOPIC "mes/redzone/data-sheets/completed/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/completed-data-sheets?limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT AssetsList
        WITH SOURCE_TOPIC "mes/redzone/assets/list"
        WITH DESTINATION_TOPIC "mes/redzone/assets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/enterprises/{value.json.enterpriseId}/assets?limit={value.json.limit}&offset={value.json.offset}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EventsList
        WITH SOURCE_TOPIC "mes/redzone/events/list"
        WITH DESTINATION_TOPIC "mes/redzone/events/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/v2/organizations/{value.json.organizationId}/events?limit={value.json.limit}&visibility-timeout={value.json.visibilityTimeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Sources

* [https://api.rz-ops.com/public/v2/openapi.json](https://api.rz-ops.com/public/v2/openapi.json)
* [https://www.rzsoftware.com/product/integrations](https://www.rzsoftware.com/product/integrations)
* [https://help.boomi.com/docs/Atomsphere/Integration/Connectors/int-QAD\_Redzone\_connection](https://help.boomi.com/docs/Atomsphere/Integration/Connectors/int-QAD_Redzone_connection)


# Qlik Cloud
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/qlik-cloud

LoT connector for Qlik Cloud Analytics: reload apps on shift or batch close, upload CSV data files, schedule reloads, run automations and register webhooks

Technical Preview

## Overview

A client-mode connector for the [Qlik Cloud REST APIs](https://qlik.dev/apis/rest/). Use it to let plant events drive Qlik: reload an app when a shift, batch or ETL job closes, upload a CSV rollup (shift totals, OEE per line) as a data file the app loads, schedule or pause reload tasks, and run a Qlik Automate automation. It also puts Qlik state on MQTT: reload status and logs, data model metadata, items, spaces and audit events.

The connector `QlikCloudRestApi` in `QlikCloudRestApi.lot` has 44 events (7 POST, 34 GET, 2 PUT, 1 PATCH). Nine are writes: `ReloadCreate`, `ReloadCancel`, `ReloadTaskCreate`, `ReloadTaskUpdate`, `DataFileUpload`, `DataFileReplace`, `AutomationRunCreate`, `WebhookCreate` and `WebhookUpdate`. There are no DELETE events.

Set `BASE_ADDRESS` to your tenant URL with no trailing slash, for example `https://acme.eu.qlikcloud.com` (a tenant alias hostname also works). Every endpoint already starts with `/api/v1`, except `/oauth/token`. Topics use `analytics/qlik-cloud/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** every event except `OAuthToken` sends `Authorization: Bearer <access_token>`. The token is either an API key (a tenant admin enables API keys and gives the user the Developer role, then the user creates a key under **Profile settings > API keys**) or an OAuth machine-to-machine token: publish `{"body":{"client_id":"...","client_secret":"...","grant_type":"client_credentials"}}` to `analytics/qlik-cloud/auth/token` and use the returned `access_token` until `expires_in` runs out. The key or token acts as its user, so give it only the spaces and roles the broker needs. Keep `QLIK_API_KEY` (or `QLIK_CLIENT_ID` and `QLIK_CLIENT_SECRET`) in broker secrets, read them with `GET SECRET` in the action that builds the payload, never retain topics that carry them, and restrict `analytics/qlik-cloud/auth/#` with ACLs.

## Events

| Event | Request | Source topic | Notes |
| - | - | - | - |
| OAuthToken | `POST /oauth/token` | `analytics/qlik-cloud/auth/token` | Get an access token for an OAuth machine-to-machine client (lifetime in expires\_in). No Authorization header. |
| UsersMe | `GET /api/v1/users/me` | `analytics/qlik-cloud/users/me` | Smoke: the user behind the API key or token (id, name, tenantId, roles). |
| TenantsMe | `GET /api/v1/tenants/me` | `analytics/qlik-cloud/tenants/me` | The tenant behind the key (id, name, hostnames, datacenter). |
| UsersList | `GET /api/v1/users?{value.json.query}` | `analytics/qlik-cloud/users/list` | Users in the tenant. |
| ReloadsList | `GET /api/v1/reloads?{value.json.query}` | `analytics/qlik-cloud/reloads/list` | Reload history of an app. |
| ReloadCreate | `POST /api/v1/reloads` | `analytics/qlik-cloud/reloads/create` | Write, starts a reload. Reload an app when a shift, batch or ETL job closes (catalog event). |
| ReloadGet | `GET /api/v1/reloads/{value.json.reload_id}` | `analytics/qlik-cloud/reloads/get` | One reload: status QUEUED, RELOADING, SUCCEEDED, FAILED, CANCELED (catalog event), duration and log. |
| ReloadCancel | `POST /api/v1/reloads/{value.json.reload_id}/actions/cancel` | `analytics/qlik-cloud/reloads/cancel` | Write. Cancel a queued or running reload (no body). |
| ReloadTasksList | `GET /api/v1/reload-tasks?{value.json.query}` | `analytics/qlik-cloud/reload_tasks/list` | Scheduled reload tasks. |
| ReloadTaskGet | `GET /api/v1/reload-tasks/{value.json.task_id}` | `analytics/qlik-cloud/reload_tasks/get` | One reload task (recurrence, state, next run). |
| ReloadTaskCreate | `POST /api/v1/reload-tasks` | `analytics/qlik-cloud/reload_tasks/create` | Write. Schedule reloads. |
| ReloadTaskUpdate | `PUT /api/v1/reload-tasks/{value.json.task_id}` | `analytics/qlik-cloud/reload_tasks/update` | Write. Replace or pause a reload task (no delete event: set state Disabled). |
| AppGet | `GET /api/v1/apps/{value.json.app_id}` | `analytics/qlik-cloud/apps/get` | App attributes (name, owner, space, lastReloadTime). |
| AppDataMetadata | `GET /api/v1/apps/{value.json.app_id}/data/metadata` | `analytics/qlik-cloud/apps/data_metadata` | Data model metadata: tables, fields, row counts, static byte size, reload\_meta. |
| AppDataLineage | `GET /api/v1/apps/{value.json.app_id}/data/lineage` | `analytics/qlik-cloud/apps/data_lineage` | Data sources the app loads from (lineage). |
| AppReloadLogs | `GET /api/v1/apps/{value.json.app_id}/reloads/logs` | `analytics/qlik-cloud/apps/reload_logs` | Reload log list for an app. |
| AppReloadLog | `GET /api/v1/apps/{value.json.app_id}/reloads/logs/{value.json.reload_id}` | `analytics/qlik-cloud/apps/reload_log` | One reload log as plain text (the script output). The broker publishes the body as received. |
| AppReloadMetadata | `GET /api/v1/apps/{value.json.app_id}/reloads/metadata/{value.json.reload_id}?{value.json.query}` | `analytics/qlik-cloud/apps/reload_metadata` | Metadata of one reload (duration, peak memory, rows per table). |
| ItemsList | `GET /api/v1/items?{value.json.query}` | `analytics/qlik-cloud/items/list` | Search apps and other items. |
| ItemGet | `GET /api/v1/items/{value.json.item_id}` | `analytics/qlik-cloud/items/get` | One item (resourceId is the app id for apps). |
| SpacesList | `GET /api/v1/spaces?{value.json.query}` | `analytics/qlik-cloud/spaces/list` | Spaces. |
| SpaceGet | `GET /api/v1/spaces/{value.json.space_id}` | `analytics/qlik-cloud/spaces/get` | One space. |
| DataFilesList | `GET /api/v1/data-files?{value.json.query}` | `analytics/qlik-cloud/data_files/list` | Data files in the personal or a space data connection. |
| DataFileGet | `GET /api/v1/data-files/{value.json.data_file_id}` | `analytics/qlik-cloud/data_files/get` | One data file (name, size, modifiedDate). |
| DataFileUpload | `POST /api/v1/data-files` | `analytics/qlik-cloud/data_files/upload` | Write. Catalog 'POST data-files': upload a CSV rollup (shift totals, OEE per line) for apps to load. |
| DataFileReplace | `PUT /api/v1/data-files/{value.json.data_file_id}` | `analytics/qlik-cloud/data_files/replace` | Write. Replace the content of an existing data file (same multipart shape, Json part may carry the name). Then ReloadCreate. |
| DataFilesQuotas | `GET /api/v1/data-files/quotas` | `analytics/qlik-cloud/data_files/quotas` | Data file quotas (max file size, space used). |
| DataFilesConnections | `GET /api/v1/data-files/connections?{value.json.query}` | `analytics/qlik-cloud/data_files/connections` | Data-file connections per space (use connectionId in DataFileUpload). |
| DataConnectionsList | `GET /api/v1/data-connections` | `analytics/qlik-cloud/data_connections/list` | Data connections visible to the user (the spec documents no query parameters). |
| AutomationsList | `GET /api/v1/automations?{value.json.query}` | `analytics/qlik-cloud/automations/list` | Qlik Automate automations. |
| AutomationGet | `GET /api/v1/automations/{value.json.automation_id}` | `analytics/qlik-cloud/automations/get` | One automation. |
| AutomationRunCreate | `POST /api/v1/automations/{value.json.automation_id}/runs` | `analytics/qlik-cloud/automations/run` | Write, runs the automation. Run an automation from a plant event. |
| AutomationRunsList | `GET /api/v1/automations/{value.json.automation_id}/runs?{value.json.query}` | `analytics/qlik-cloud/automations/runs` | Runs of an automation. |
| AutomationRunGet | `GET /api/v1/automations/{value.json.automation_id}/runs/{value.json.run_id}` | `analytics/qlik-cloud/automations/run_get` | One automation run (status, title, timestamps). |
| WebhooksList | `GET /api/v1/webhooks?{value.json.query}` | `analytics/qlik-cloud/webhooks/list` | Webhooks. |
| WebhookGet | `GET /api/v1/webhooks/{value.json.webhook_id}` | `analytics/qlik-cloud/webhooks/get` | One webhook. |
| WebhookEventTypes | `GET /api/v1/webhooks/event-types` | `analytics/qlik-cloud/webhooks/event_types` | Event types a webhook can subscribe to (for example com.qlik.v1.reload.finished). |
| WebhookCreate | `POST /api/v1/webhooks` | `analytics/qlik-cloud/webhooks/create` | Write. Send Qlik events (reload finished, app published) to a broker ENABLE\_SERVER connector. |
| WebhookUpdate | `PATCH /api/v1/webhooks/{value.json.webhook_id}` | `analytics/qlik-cloud/webhooks/update` | Write. JSON Patch a webhook (no delete event: disable it). |
| WebhookDeliveries | `GET /api/v1/webhooks/{value.json.webhook_id}/deliveries?{value.json.query}` | `analytics/qlik-cloud/webhooks/deliveries` | Delivery attempts of a webhook (status, response code). |
| AuditsList | `GET /api/v1/audits?{value.json.query}` | `analytics/qlik-cloud/audits/list` | Audit events (tenant admin). |
| AuditGet | `GET /api/v1/audits/{value.json.audit_id}` | `analytics/qlik-cloud/audits/get` | One audit event. |
| LicensesOverview | `GET /api/v1/licenses/overview` | `analytics/qlik-cloud/licenses/overview` | License overview (tenant admin). |
| LicensesConsumption | `GET /api/v1/licenses/consumption?{value.json.query}` | `analytics/qlik-cloud/licenses/consumption` | License consumption records (tenant admin). |

Payload fields are JSON on the source topic: ids (`app_id`, `reload_id`, `task_id`, `item_id`, `space_id`, `data_file_id`, `automation_id`, `run_id`, `webhook_id`, `audit_id`), `query` (a URL query string without `?`, or `""`; `ReloadsList` needs `appId=...`), `body` (JSON for POST, PUT and PATCH events; a JSON Patch array for `WebhookUpdate`), `multipart` for data file uploads, and `access_token`.

## Basic Syntax

An excerpt of the template (the full file has all 44 events and comments):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR QlikCloudRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_TENANT.YOUR_REGION.qlikcloud.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT UsersMe
        WITH SOURCE_TOPIC "analytics/qlik-cloud/users/me"
        WITH DESTINATION_TOPIC "analytics/qlik-cloud/users/me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ReloadCreate
        WITH SOURCE_TOPIC "analytics/qlik-cloud/reloads/create"
        WITH DESTINATION_TOPIC "analytics/qlik-cloud/reloads/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/reloads"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ReloadGet
        WITH SOURCE_TOPIC "analytics/qlik-cloud/reloads/get"
        WITH DESTINATION_TOPIC "analytics/qlik-cloud/reloads/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1/reloads/{value.json.reload_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT DataFileUpload
        WITH SOURCE_TOPIC "analytics/qlik-cloud/data_files/upload"
        WITH DESTINATION_TOPIC "analytics/qlik-cloud/data_files/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1/data-files"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "multipart/form-data; boundary=CorefluxQlikBoundary"
        WITH BODY "{value.json.multipart}"
```

## Examples

### Reload an app when a shift closes

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION QlikReloadOnShiftClose
ON TOPIC "plant/line2/shift/closed" DO
    SET "key" WITH GET SECRET "QLIK_API_KEY"
    PUBLISH TOPIC "analytics/qlik-cloud/reloads/create" WITH { "access_token": {key}, "body": { "appId": "116dbfae-7fb9-4983-8e23-5ccd8c508722", "partial": false, "variables": { "vLine": "Line 2" } } }
```

The response on `analytics/qlik-cloud/reloads/create/response` carries the reload `id` and `status` `QUEUED`. Publish `{"access_token":"...","reload_id":"<id>"}` to `analytics/qlik-cloud/reloads/get` to follow it to `SUCCEEDED` or `FAILED`.

### Upload a CSV rollup as a data file

`DataFileUpload` sends `multipart` unchanged with `Content-Type: multipart/form-data; boundary=CorefluxQlikBoundary`. Build the body with CRLF line endings: a `Json` part with the file name, then a `File` part with the CSV.

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
--CorefluxQlikBoundary
Content-Disposition: form-data; name="Json"
Content-Type: application/json

{"name":"plant/oee-2026-10-05.csv"}
--CorefluxQlikBoundary
Content-Disposition: form-data; name="File"; filename="oee-2026-10-05.csv"
Content-Type: text/csv

line,shift,good,scrap,oee
Line 1,A,4210,37,0.81
--CorefluxQlikBoundary--
```

A 201 response returns the file `id`. If the name already exists Qlik answers 409; publish to `analytics/qlik-cloud/data_files/replace` with `data_file_id` instead, then reload the app.

### Get Qlik events back on MQTT

`WebhookCreate` registers a webhook that posts Qlik events, such as `com.qlik.v1.reload.finished`, to a URL you choose. Point it at a separate REST API connector with `ENABLE_SERVER` on the broker. Pause it later with `WebhookUpdate` and `[{"op":"replace","path":"/enabled","value":false}]`.

## Not packaged

* DELETE operations (apps, data files, reload tasks, webhooks, spaces, users), on purpose. Pause reload tasks with `state` `Disabled` and webhooks with `enabled` false.
* App import, export and publish; space, user, API key and tenant administration.
* The Qlik associative engine (QIX), which uses WebSockets, not REST.
* The webhook receiver itself (use a separate `ENABLE_SERVER` connector).


# QuestDB
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/questdb

Client-mode REST API connector for QuestDB: ILP over HTTP writes, SQL queries via /exec, CSV export via /exp, and /ping health

Technical Preview

## Overview

A client-mode connector for the [QuestDB HTTP REST API](https://questdb.com/docs/reference/api/rest/) that streams MQTT telemetry into QuestDB tables and runs SQL from MQTT:

| Catalog connector event | Endpoint | Notes |
| - | - | - |
| POST write (ILP) | `POST /write?precision=` | [ILP over HTTP](https://questdb.com/docs/reference/api/ilp/overview/), `text/plain` line protocol body, `204` on success. Tables and columns auto-create. |
| GET exec | `GET /exec?query=` | SQL (SELECT, INSERT, CREATE TABLE) returning JSON `columns` + `dataset` |
| GET exp | `GET /exp?query=` | SQL result as CSV |
| GET ping | `GET /ping` | Health check, `204` |

Default `BASE_ADDRESS` is `http://YOUR_QUESTDB_HOST:9000` (QuestDB's HTTP port). Topics use `data/questdb/<object>/<verb>`.

> [!NOTE]
>
> **CSV import (`/imp`) is not a client event.** QuestDB only accepts `multipart/form-data` uploads on `/imp`; a raw body returns `400 Non-multipart POST not supported`. Use ILP `/write` for streaming rows, or `/exec` with `INSERT INTO …` for small batches.

## Auth

QuestDB open source has no HTTP auth by default. When you enable `http.user` / `http.password` (OSS) or RBAC (QuestDB Enterprise), pass the full header value in `authorization`, such as `Basic base64(user:pass)` or `Bearer <REST token>`. Send an empty string when the server has no auth. Keep the value in a Hub secret such as `QUESTDB_AUTH` and never commit it.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR QuestdbRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_QUESTDB_HOST:9000"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Ping
        WITH SOURCE_TOPIC "data/questdb/ping"
        WITH DESTINATION_TOPIC "data/questdb/ping/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ping"
        WITH HEADERS
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ExecQuery
        WITH SOURCE_TOPIC "data/questdb/query/exec"
        WITH DESTINATION_TOPIC "data/questdb/query/exec/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/exec?query={value.json.query}&count=true"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT WriteIlp
        WITH SOURCE_TOPIC "data/questdb/ilp/write"
        WITH DESTINATION_TOPIC "data/questdb/ilp/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/write?precision={value.json.precision}"
        WITH HEADERS
            ADD "Content-Type" "text/plain; charset=utf-8"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT ExportCsv
        WITH SOURCE_TOPIC "data/questdb/query/export"
        WITH DESTINATION_TOPIC "data/questdb/query/export/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/exp?query={value.json.query}"
        WITH HEADERS
            ADD "Accept" "text/csv"
            ADD "Authorization" "{value.json.authorization}"
```

## Example MQTT payloads

**Write telemetry (topic `data/questdb/ilp/write`).** JSON fields fill the query placeholders; the body is line protocol:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "authorization": "", "precision": "ms" }
```

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
site_readings,site=porto value=21.5 1791234567890
```

**SQL query (topic `data/questdb/query/exec`).** URL-encode the SQL before publishing:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "authorization": "", "query": "SELECT%20site,value%20FROM%20site_readings%20LIMIT%2010" }
```

The response topic receives QuestDB's JSON, for example `{"columns":[…],"dataset":[["porto",21.5]],"count":1}`.

**CSV export (topic `data/questdb/query/export`)** takes the same payload as `exec`. **Health (topic `data/questdb/ping`)** takes `{ "authorization": "" }`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [InfluxDB](/latest/lot-language/routes/rest-api-apps/influxdb)


# QuickBooks Online
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/quickbooks-online

LoT connector for QuickBooks Online: create invoices from production events, adjust inventory quantities, query items and customers, and refresh OAuth tokens

Technical Preview

## Overview

A client-mode connector for the [QuickBooks Online Accounting API](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account) (v3). Use it to close the loop between the shop floor and accounting: bill a customer when a batch ships, write scrap or consumption back as an inventory quantity adjustment, and read item stock levels or recent changes into MQTT.

The file holds two connectors. `QuickBooksOnlineRestApi` talks to the accounting API, and `QuickBooksOnlineOAuth` refreshes the OAuth access token on Intuit's token host.

| Event | Request | Notes |
| - | - | - |
| GetCompanyInfo | `GET /v3/company/{realm}/companyinfo/{realm}` | Smoke and realm check |
| Query | `GET /v3/company/{realm}/query?query=` | SQL-like query, URL-encoded (for example `select * from Item`) |
| ReadItem | `GET /v3/company/{realm}/item/{id}` | `QtyOnHand` for inventory items |
| CreateItem | `POST /v3/company/{realm}/item` | Create, or sparse update with `Id` and `SyncToken` |
| CreateInventoryAdjustment | `POST /v3/company/{realm}/inventoryadjustment` | Item quantity adjustment (`QtyDiff`) |
| CreateInvoice | `POST /v3/company/{realm}/invoice` | `CustomerRef` and `Line[]` |
| ReadInvoice | `GET /v3/company/{realm}/invoice/{id}` | |
| SendInvoice | `POST /v3/company/{realm}/invoice/{id}/send?sendTo=` | Emails the invoice; empty body |
| ReadCustomer | `GET /v3/company/{realm}/customer/{id}` | |
| CreateCustomer | `POST /v3/company/{realm}/customer` | `DisplayName` must be unique |
| ChangeDataCapture | `GET /v3/company/{realm}/cdc?entities=&changedSince=` | Changes in the last 30 days |
| Batch | `POST /v3/company/{realm}/batch` | Up to 30 operations per call |
| ProfitAndLossReport | `GET /v3/company/{realm}/reports/ProfitAndLoss?start_date=&end_date=` | |
| RefreshToken | `POST /oauth2/v1/tokens/bearer` (on `oauth.platform.intuit.com`) | New access token and refresh token |

Every accounting call adds `minorversion=75`. Since August 2025 QuickBooks ignores minor versions 1 to 74 and answers as 75, so the template pins the current base.

Set `BASE_ADDRESS` to `https://quickbooks.api.intuit.com` for real companies or `https://sandbox-quickbooks.api.intuit.com` for sandbox companies. Topics use `finance/quickbooks/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** QuickBooks Online uses OAuth 2.0 authorization code with the `com.intuit.quickbooks.accounting` scope. Do the one-time consent outside the broker (the Intuit [OAuth 2.0 Playground](https://developer.intuit.com/app/developer/playground) or your own app) to get a refresh token and the company's `realmId`. After that the broker can stay connected on its own: publish to the RefreshToken event to get a fresh access token (valid 60 minutes) and send it as `access_token` with `realm_id` on every accounting call. Keep the client id, client secret and refresh token in Hub secrets (suggested names `QBO_CLIENT_ID`, `QBO_CLIENT_SECRET`, `QBO_REFRESH_TOKEN`, `QBO_REALM_ID`). Never commit them into the `.lot`.

> [!WARNING]
>
> The refresh token **rotates**. The token response can return a new `refresh_token`, and the old one stops working soon after. Always store the latest value. A refresh token that is not used for about 100 days expires, and the user has to reconnect.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR QuickBooksOnlineRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://quickbooks.api.intuit.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Sandbox: https://sandbox-quickbooks.api.intuit.com. Auth: Bearer {value.json.access_token}; realm {value.json.realm_id}. Never commit tokens.
    ADD EVENT GetCompanyInfo
        WITH SOURCE_TOPIC "finance/quickbooks/company/info/get"
        WITH DESTINATION_TOPIC "finance/quickbooks/company/info/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/companyinfo/{value.json.realm_id}?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Query
        WITH SOURCE_TOPIC "finance/quickbooks/query"
        WITH DESTINATION_TOPIC "finance/quickbooks/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/query?query={value.json.query}&minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ReadItem
        WITH SOURCE_TOPIC "finance/quickbooks/item/get"
        WITH DESTINATION_TOPIC "finance/quickbooks/item/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/item/{value.json.item_id}?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateItem
        WITH SOURCE_TOPIC "finance/quickbooks/item/create"
        WITH DESTINATION_TOPIC "finance/quickbooks/item/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/item?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateInventoryAdjustment
        WITH SOURCE_TOPIC "finance/quickbooks/inventoryadjustment/create"
        WITH DESTINATION_TOPIC "finance/quickbooks/inventoryadjustment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/inventoryadjustment?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateInvoice
        WITH SOURCE_TOPIC "finance/quickbooks/invoice/create"
        WITH DESTINATION_TOPIC "finance/quickbooks/invoice/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/invoice?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ReadInvoice
        WITH SOURCE_TOPIC "finance/quickbooks/invoice/get"
        WITH DESTINATION_TOPIC "finance/quickbooks/invoice/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/invoice/{value.json.invoice_id}?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT SendInvoice
        WITH SOURCE_TOPIC "finance/quickbooks/invoice/send"
        WITH DESTINATION_TOPIC "finance/quickbooks/invoice/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/invoice/{value.json.invoice_id}/send?sendTo={value.json.send_to}&minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/octet-stream"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY ""
    ADD EVENT ReadCustomer
        WITH SOURCE_TOPIC "finance/quickbooks/customer/get"
        WITH DESTINATION_TOPIC "finance/quickbooks/customer/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/customer/{value.json.customer_id}?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT CreateCustomer
        WITH SOURCE_TOPIC "finance/quickbooks/customer/create"
        WITH DESTINATION_TOPIC "finance/quickbooks/customer/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/customer?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ChangeDataCapture
        WITH SOURCE_TOPIC "finance/quickbooks/cdc/get"
        WITH DESTINATION_TOPIC "finance/quickbooks/cdc/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/cdc?entities={value.json.entities}&changedSince={value.json.changed_since}&minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Batch
        WITH SOURCE_TOPIC "finance/quickbooks/batch"
        WITH DESTINATION_TOPIC "finance/quickbooks/batch/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/batch?minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ProfitAndLossReport
        WITH SOURCE_TOPIC "finance/quickbooks/reports/profitandloss/get"
        WITH DESTINATION_TOPIC "finance/quickbooks/reports/profitandloss/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/company/{value.json.realm_id}/reports/ProfitAndLoss?start_date={value.json.start_date}&end_date={value.json.end_date}&minorversion=75"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"

# OAuth 2.0 token refresh (different host). basic_auth = base64("<client_id>:<client_secret>") from Hub secrets.
# Reply: {"access_token":"...","expires_in":3600,"refresh_token":"...","x_refresh_token_expires_in":...,"token_type":"bearer"}.
# Store the returned refresh_token every time (it rotates). Errors: 400 invalid_grant (refresh token expired/revoked), 401 invalid_client.
DEFINE CONNECTOR QuickBooksOnlineOAuth WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://oauth.platform.intuit.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/x-www-form-urlencoded"
    ADD EVENT RefreshToken
        WITH SOURCE_TOPIC "finance/quickbooks/oauth/refresh"
        WITH DESTINATION_TOPIC "finance/quickbooks/oauth/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth2/v1/tokens/bearer"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Basic {value.json.basic_auth}"
        WITH BODY "grant_type=refresh_token&refresh_token={value.json.refresh_token}"
```

## MQTT examples

Control fields (`access_token`, `realm_id`, ids, `query`, dates) only fill the URL and headers. Only `body` is sent as the request body.

**RefreshToken** (`finance/quickbooks/oauth/refresh`). `basic_auth` is the Base64 of `client_id:client_secret`. Expect **200**:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "basic_auth": "<base64 client_id:client_secret>", "refresh_token": "<latest refresh token>" }
```

Response:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "token_type": "bearer", "access_token": "eyJlbmMiOi...", "expires_in": 3600, "refresh_token": "AB11...", "x_refresh_token_expires_in": 8726400 }
```

**Query** (`finance/quickbooks/query`). The query is placed in the URL, so URL-encode it. This asks for inventory items:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access token>",
  "realm_id": "9341455000000001",
  "query": "select%20*%20from%20Item%20where%20Type%20%3D%20%27Inventory%27%20MAXRESULTS%20100"
}
```

Response (trimmed):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "QueryResponse": { "Item": [ { "Id": "11", "Name": "Pump Seal Kit", "Type": "Inventory", "TrackQtyOnHand": true, "QtyOnHand": 10, "SyncToken": "0" } ], "startPosition": 1, "maxResults": 1 } }
```

**CreateInventoryAdjustment** (`finance/quickbooks/inventoryadjustment/create`). Writes scrap back to stock: two units off item 11, posted to the adjustment account 91. Expect **200** with the new `InventoryAdjustment`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access token>",
  "realm_id": "9341455000000001",
  "body": {
    "AdjustAccountRef": { "value": "91" },
    "TxnDate": "2026-10-05",
    "Line": [
      { "DetailType": "ItemAdjustmentLineDetail", "ItemAdjustmentLineDetail": { "ItemRef": { "value": "11" }, "QtyDiff": -2 } }
    ]
  }
}
```

Use a positive `QtyDiff` to add stock. Inventory adjustments need QuickBooks Online Plus or Advanced with quantity tracking turned on, and the item must be an `Inventory` item.

**CreateInvoice** (`finance/quickbooks/invoice/create`), expect **200** with the new `Invoice` (`Id`, `DocNumber`, `TotalAmt`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access token>",
  "realm_id": "9341455000000001",
  "body": {
    "CustomerRef": { "value": "58" },
    "Line": [
      { "DetailType": "SalesItemLineDetail", "Amount": 150.0, "SalesItemLineDetail": { "ItemRef": { "value": "11" }, "Qty": 2, "UnitPrice": 75.0 } }
    ]
  }
}
```

**SendInvoice** (`finance/quickbooks/invoice/send`) takes `invoice_id` and a URL-encoded `send_to` address, for example `"send_to": "ap%40customer.example"`. The body is empty.

**Updates.** QuickBooks updates are sparse `POST`s to the create endpoint. Send the entity's `Id`, its current `SyncToken` and `"sparse": true` together with the fields to change. An old `SyncToken` returns **400** with code `5010`; read the entity again and retry.

## Keeping the token

A small action can keep the latest tokens when the refresh reply arrives:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION QuickBooksKeepToken
ON TOPIC "finance/quickbooks/oauth/refresh/response" DO
    SET "access" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    SET "refresh" WITH GET JSON "refresh_token" IN PAYLOAD AS STRING
    KEEP TOPIC "finance/quickbooks/session/access_token" WITH {access}
    KEEP TOPIC "finance/quickbooks/session/refresh_token" WITH {refresh}
```

Refresh before the access token expires (for example every 50 minutes), or when a call returns **401** with code `3200`. Restrict who can read the `finance/quickbooks/#` topics with a rule, because these payloads carry tokens and client credentials.

## Webhooks (companion, not packaged)

QuickBooks [webhooks](https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks) can `POST` entity-change notifications (for example Invoice, Item or Payment created or updated) to an HTTPS URL. Each request carries an `intuit-signature` header, an HMAC-SHA256 of the body with your app's verifier token, which the receiver should check. Receiving them needs a separate `ENABLE_SERVER` REST API connector on a publicly reachable HTTPS address. That companion connector is not part of this template. Change data capture (`ChangeDataCapture`) is the polling alternative.

## Notes

* Limits: 500 requests per minute and 10 concurrent requests per company and app; a batch holds at most 30 operations, with 40 batch calls per minute. Above that QuickBooks answers **429**.
* A query returns at most 1000 rows. Page with `STARTPOSITION` and `MAXRESULTS`, for example `select * from Item STARTPOSITION 1001 MAXRESULTS 1000`.
* Common errors: **401** code `3200` (expired or invalid token), **403** code `3100` (the app is not connected to that `realm_id`), **400** `ValidationFault` with codes such as `2500` (invalid reference), `6000` (business rule), `6240` (duplicate name), `5010` (stale `SyncToken`).
* Sandbox and production use different hosts and different companies. A sandbox token does not work on `quickbooks.api.intuit.com`.
* Not covered: invoice PDF download (binary), attachments (multipart upload), the Payments and Payroll APIs, and token revoke (`POST https://developer.api.intuit.com/v2/oauth2/tokens/revoke`).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [QuickBooks Online Accounting API reference](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/invoice)
* [InventoryAdjustment entity](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/all-entities/inventoryadjustment)
* [OAuth 2.0 for QuickBooks Online](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0)
* [Minor versions](https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api/minor-versions)
* [QuickBooks Online Accounting API Postman collection](https://www.postman.com/intuit-developer/intuit-developer-quickbooks-online-accounting-api/overview)


# Ren Data Hub
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ren-data-hub

LoT connector for Portuguese grid open data with no API key: E-REDES consumption and production datasets and REN DataHub balances and market prices

Technical Preview

## Overview

Client-mode REST API connectors for Portuguese grid open data with no API key: E-REDES distribution datasets (15-minute national consumption and production, consumption forecast, consumption by municipality) and REN DataHub electricity and gas balances, production by source and market prices.

This is one of the templates in the E-REDES and REN open data (Portugal) REST API app (`e-redes-and-ren-open-data`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["none"]
* **secrets**: \[]
* **note**: Both keyless. E-REDES optional portal API key (Authorization: Apikey ...) for higher quota; not wired by default.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Ren Data Hub connector | no |
| `BaseUrl` | string | Ren Data Hub base URL without trailing slash (e.g. [https://servicebus.ren.pt](https://servicebus.ren.pt)) | yes |

`BASE_ADDRESS` default: `https://servicebus.ren.pt`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `RenElectricityBalanceDaily` | GET | `/datahubapi/electricity/ElectricityConsumptionSupplyDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/electricity/balance-daily/get` | `energy/pt/ren/electricity/balance-daily/get/response` | `culture`, `date` |
| `RenElectricityProductionDaily` | GET | `/datahubapi/electricity/ElectricityProductionBreakdownDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/electricity/production-daily/get` | `energy/pt/ren/electricity/production-daily/get/response` | `culture`, `date` |
| `RenElectricityBalanceMonthly` | GET | `/datahubapi/electricity/ElectricityConsumptionSupplyMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/electricity/balance-monthly/get` | `energy/pt/ren/electricity/balance-monthly/get/response` | `culture`, `month`, `year` |
| `RenElectricityInstalledPowerMonthly` | GET | `/datahubapi/electricity/ElectricityInstalledPowerMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/electricity/installed-power-monthly/get` | `energy/pt/ren/electricity/installed-power-monthly/get/response` | `culture`, `month`, `year` |
| `RenElectricityConsumptionYearly` | GET | `/datahubapi/electricity/ElectricityConsumptionVariationYearly?culture={value.json.culture}&year={value.json.year}` | `energy/pt/ren/electricity/consumption-yearly/get` | `energy/pt/ren/electricity/consumption-yearly/get/response` | `culture`, `year` |
| `RenElectricityPricesDaily` | GET | `/datahubapi/electricity/ElectricityMarketPricesDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/electricity/prices-daily/get` | `energy/pt/ren/electricity/prices-daily/get/response` | `culture`, `date` |
| `RenElectricityPricesMonthly` | GET | `/datahubapi/electricity/ElectricityMarketPricesMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/electricity/prices-monthly/get` | `energy/pt/ren/electricity/prices-monthly/get/response` | `culture`, `month`, `year` |
| `RenGasBalanceDaily` | GET | `/datahubapi/gas/GasConsumptionSupplyDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/gas/balance-daily/get` | `energy/pt/ren/gas/balance-daily/get/response` | `culture`, `date` |
| `RenGasConsumptionBreakdownDaily` | GET | `/datahubapi/gas/GasConsumptionBreakdownDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/gas/consumption-breakdown-daily/get` | `energy/pt/ren/gas/consumption-breakdown-daily/get/response` | `culture`, `date` |
| `RenGasRntgBalanceDaily` | GET | `/datahubapi/gas/GasRNTGBalanceDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/gas/rntg-balance-daily/get` | `energy/pt/ren/gas/rntg-balance-daily/get/response` | `culture`, `date` |
| `RenGasLngTerminalDaily` | GET | `/datahubapi/gas/GasLNGTerminalBalanceDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/gas/lng-terminal-daily/get` | `energy/pt/ren/gas/lng-terminal-daily/get/response` | `culture`, `date` |
| `RenGasStorageDaily` | GET | `/datahubapi/gas/GasUndergroundStorageBalanceDaily?culture={value.json.culture}&date={value.json.date}` | `energy/pt/ren/gas/storage-daily/get` | `energy/pt/ren/gas/storage-daily/get/response` | `culture`, `date` |
| `RenGasBalanceMonthly` | GET | `/datahubapi/gas/GasConsumptionSupplyMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/gas/balance-monthly/get` | `energy/pt/ren/gas/balance-monthly/get/response` | `culture`, `month`, `year` |
| `RenGasRntgBalanceMonthly` | GET | `/datahubapi/gas/GasRNTGBalanceMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/gas/rntg-balance-monthly/get` | `energy/pt/ren/gas/rntg-balance-monthly/get/response` | `culture`, `month`, `year` |
| `RenGasLngTerminalMonthly` | GET | `/datahubapi/gas/GasLNGTerminalBalanceMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/gas/lng-terminal-monthly/get` | `energy/pt/ren/gas/lng-terminal-monthly/get/response` | `culture`, `month`, `year` |
| `RenGasStorageMonthly` | GET | `/datahubapi/gas/GasUndergroundStorageBalanceMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/gas/storage-monthly/get` | `energy/pt/ren/gas/storage-monthly/get/response` | `culture`, `month`, `year` |
| `RenGasSupplyBreakdownMonthly` | GET | `/datahubapi/gas/GasBreakdownOfSupplyMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/gas/supply-breakdown-monthly/get` | `energy/pt/ren/gas/supply-breakdown-monthly/get/response` | `culture`, `month`, `year` |
| `RenGasConsumptionYearly` | GET | `/datahubapi/gas/GasConsumptionVariationYearly?culture={value.json.culture}&year={value.json.year}` | `energy/pt/ren/gas/consumption-yearly/get` | `energy/pt/ren/gas/consumption-yearly/get/response` | `culture`, `year` |
| `RenGasPricesDaily` | GET | `/datahubapi/gas/GasMarketPricesDaily?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/gas/prices-daily/get` | `energy/pt/ren/gas/prices-daily/get/response` | `culture`, `month`, `year` |
| `RenGasPricesMonthly` | GET | `/datahubapi/gas/GasMarketPricesMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}` | `energy/pt/ren/gas/prices-monthly/get` | `energy/pt/ren/gas/prices-monthly/get/response` | `culture`, `month`, `year` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode REN_DATA_HUB"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR RenDataHub WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://servicebus.ren.pt"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT RenElectricityBalanceDaily
        WITH SOURCE_TOPIC "energy/pt/ren/electricity/balance-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/electricity/balance-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/electricity/ElectricityConsumptionSupplyDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenElectricityProductionDaily
        WITH SOURCE_TOPIC "energy/pt/ren/electricity/production-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/electricity/production-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/electricity/ElectricityProductionBreakdownDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenElectricityBalanceMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/electricity/balance-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/electricity/balance-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/electricity/ElectricityConsumptionSupplyMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenElectricityInstalledPowerMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/electricity/installed-power-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/electricity/installed-power-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/electricity/ElectricityInstalledPowerMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenElectricityConsumptionYearly
        WITH SOURCE_TOPIC "energy/pt/ren/electricity/consumption-yearly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/electricity/consumption-yearly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/electricity/ElectricityConsumptionVariationYearly?culture={value.json.culture}&year={value.json.year}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenElectricityPricesDaily
        WITH SOURCE_TOPIC "energy/pt/ren/electricity/prices-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/electricity/prices-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/electricity/ElectricityMarketPricesDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenElectricityPricesMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/electricity/prices-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/electricity/prices-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/electricity/ElectricityMarketPricesMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasBalanceDaily
        WITH SOURCE_TOPIC "energy/pt/ren/gas/balance-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/balance-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasConsumptionSupplyDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasConsumptionBreakdownDaily
        WITH SOURCE_TOPIC "energy/pt/ren/gas/consumption-breakdown-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/consumption-breakdown-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasConsumptionBreakdownDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasRntgBalanceDaily
        WITH SOURCE_TOPIC "energy/pt/ren/gas/rntg-balance-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/rntg-balance-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasRNTGBalanceDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasLngTerminalDaily
        WITH SOURCE_TOPIC "energy/pt/ren/gas/lng-terminal-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/lng-terminal-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasLNGTerminalBalanceDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasStorageDaily
        WITH SOURCE_TOPIC "energy/pt/ren/gas/storage-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/storage-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasUndergroundStorageBalanceDaily?culture={value.json.culture}&date={value.json.date}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasBalanceMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/gas/balance-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/balance-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasConsumptionSupplyMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasRntgBalanceMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/gas/rntg-balance-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/rntg-balance-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasRNTGBalanceMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasLngTerminalMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/gas/lng-terminal-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/lng-terminal-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasLNGTerminalBalanceMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasStorageMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/gas/storage-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/storage-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasUndergroundStorageBalanceMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasSupplyBreakdownMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/gas/supply-breakdown-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/supply-breakdown-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasBreakdownOfSupplyMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasConsumptionYearly
        WITH SOURCE_TOPIC "energy/pt/ren/gas/consumption-yearly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/consumption-yearly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasConsumptionVariationYearly?culture={value.json.culture}&year={value.json.year}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasPricesDaily
        WITH SOURCE_TOPIC "energy/pt/ren/gas/prices-daily/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/prices-daily/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasMarketPricesDaily?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT RenGasPricesMonthly
        WITH SOURCE_TOPIC "energy/pt/ren/gas/prices-monthly/get"
        WITH DESTINATION_TOPIC "energy/pt/ren/gas/prices-monthly/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/datahubapi/gas/GasMarketPricesMonthly?culture={value.json.culture}&year={value.json.year}&month={value.json.month}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `RenElectricityBalanceDaily` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/pt/ren/electricity/balance-daily/get/response' &
mosquitto_pub -t 'energy/pt/ren/electricity/balance-daily/get' -m '{"culture": "<culture>", "date": "<date>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Rhize Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/rhize-api

LoT connector for the Rhize ISA-95 data hub GraphQL API: record job responses and equipment actuals, query material lots and KPIs, and start BPMN workflows

Technical Preview

## Overview

Client-mode REST API connector for Rhize, the ISA-95 manufacturing data hub: record job responses and equipment actuals from production topics, add and update equipment, query equipment, job responses, material lots, data sources, KPIs and the audit log, and start BPMN workflows, through the Rhize GraphQL API with Keycloak tokens.

This is one of the templates in the Rhize (ISA-95 manufacturing data hub) REST API app (`rhize`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Keycloak OpenID Connect. RhizeAuth GetAccessToken (client\_credentials) or GetPasswordToken (password grant) returns a JWT (docs example expires\_in 28800); publish authorization 'Bearer \<access\_token>' on every RhizeApi event. Hub secrets RHIZE\_REALM, RHIZE\_CLIENT\_ID, RHIZE\_CLIENT\_SECRET (+ RHIZE\_USERNAME / RHIZE\_PASSWORD for the password grant).

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Rhize Api connector | no |
| `BaseUrl` | string | Rhize Api base URL without trailing slash (e.g. https\://YOUR\_RHIZE\_HOST) | yes |

`BASE_ADDRESS` default: `https://YOUR_RHIZE_HOST`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `QueryEquipment` | POST | `/graphql` | `historian/rhize/equipment/query` | `historian/rhize/equipment/query/response` | `authorization`, `request` |
| `GetEquipment` | POST | `/graphql` | `historian/rhize/equipment/get` | `historian/rhize/equipment/get/response` | `authorization`, `request` |
| `AggregateEquipment` | POST | `/graphql` | `historian/rhize/equipment/aggregate` | `historian/rhize/equipment/aggregate/response` | `authorization`, `request` |
| `AddEquipment` | POST | `/graphql` | `historian/rhize/equipment/add` | `historian/rhize/equipment/add/response` | `authorization`, `request` |
| `UpdateEquipmentVersion` | POST | `/graphql` | `historian/rhize/equipment-version/update` | `historian/rhize/equipment-version/update/response` | `authorization`, `request` |
| `QueryJobResponse` | POST | `/graphql` | `historian/rhize/job-response/query` | `historian/rhize/job-response/query/response` | `authorization`, `request` |
| `AddJobResponse` | POST | `/graphql` | `historian/rhize/job-response/add` | `historian/rhize/job-response/add/response` | `authorization`, `request` |
| `AddEquipmentActual` | POST | `/graphql` | `historian/rhize/equipment-actual/add` | `historian/rhize/equipment-actual/add/response` | `authorization`, `request` |
| `QueryMaterialLot` | POST | `/graphql` | `historian/rhize/material-lot/query` | `historian/rhize/material-lot/query/response` | `authorization`, `request` |
| `QueryDataSource` | POST | `/graphql` | `historian/rhize/data-source/query` | `historian/rhize/data-source/query/response` | `authorization`, `request` |
| `QueryKpi` | POST | `/graphql` | `historian/rhize/kpi/query` | `historian/rhize/kpi/query/response` | `authorization`, `request` |
| `QueryAuditLog` | POST | `/graphql` | `historian/rhize/audit-log/query` | `historian/rhize/audit-log/query/response` | `authorization`, `request` |
| `StartWorkflow` | POST | `/graphql` | `historian/rhize/workflow/start` | `historian/rhize/workflow/start/response` | `authorization`, `request` |
| `RunWorkflowSync` | POST | `/graphql` | `historian/rhize/workflow/run` | `historian/rhize/workflow/run/response` | `authorization`, `request` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode RHIZE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR RhizeApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_RHIZE_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT QueryEquipment
        WITH SOURCE_TOPIC "historian/rhize/equipment/query"
        WITH DESTINATION_TOPIC "historian/rhize/equipment/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT GetEquipment
        WITH SOURCE_TOPIC "historian/rhize/equipment/get"
        WITH DESTINATION_TOPIC "historian/rhize/equipment/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT AggregateEquipment
        WITH SOURCE_TOPIC "historian/rhize/equipment/aggregate"
        WITH DESTINATION_TOPIC "historian/rhize/equipment/aggregate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT AddEquipment
        WITH SOURCE_TOPIC "historian/rhize/equipment/add"
        WITH DESTINATION_TOPIC "historian/rhize/equipment/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT UpdateEquipmentVersion
        WITH SOURCE_TOPIC "historian/rhize/equipment-version/update"
        WITH DESTINATION_TOPIC "historian/rhize/equipment-version/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT QueryJobResponse
        WITH SOURCE_TOPIC "historian/rhize/job-response/query"
        WITH DESTINATION_TOPIC "historian/rhize/job-response/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT AddJobResponse
        WITH SOURCE_TOPIC "historian/rhize/job-response/add"
        WITH DESTINATION_TOPIC "historian/rhize/job-response/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT AddEquipmentActual
        WITH SOURCE_TOPIC "historian/rhize/equipment-actual/add"
        WITH DESTINATION_TOPIC "historian/rhize/equipment-actual/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT QueryMaterialLot
        WITH SOURCE_TOPIC "historian/rhize/material-lot/query"
        WITH DESTINATION_TOPIC "historian/rhize/material-lot/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT QueryDataSource
        WITH SOURCE_TOPIC "historian/rhize/data-source/query"
        WITH DESTINATION_TOPIC "historian/rhize/data-source/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT QueryKpi
        WITH SOURCE_TOPIC "historian/rhize/kpi/query"
        WITH DESTINATION_TOPIC "historian/rhize/kpi/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT QueryAuditLog
        WITH SOURCE_TOPIC "historian/rhize/audit-log/query"
        WITH DESTINATION_TOPIC "historian/rhize/audit-log/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT StartWorkflow
        WITH SOURCE_TOPIC "historian/rhize/workflow/start"
        WITH DESTINATION_TOPIC "historian/rhize/workflow/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT RunWorkflowSync
        WITH SOURCE_TOPIC "historian/rhize/workflow/run"
        WITH DESTINATION_TOPIC "historian/rhize/workflow/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/graphql"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `QueryEquipment` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'historian/rhize/equipment/query/response' &
mosquitto_pub -t 'historian/rhize/equipment/query' -m '{"authorization": "<authorization>", "request": "<request>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Rockwell Plex Smart Manufacturing Platform
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/rockwell-plex-smart-manufacturing-platform

LoT connector for Rockwell Plex: read workcenters, downtime, production, jobs and parts, and post workcenter status, production, checksheets and scrap

Technical Preview

## Overview

One client-mode connector, **RockwellPlex**, for the Plex Connect REST APIs of the Rockwell Automation Plex Smart Manufacturing Platform (Plex MES, ERP and quality). It covers what a broker typically exchanges with Plex on a discrete production line.

Read workcenter definitions and their live setup, the status and downtime history, production and scrap records, batches, scheduled jobs, parts, inventory containers, equipment and quality control plans into your Unified Namespace. In the other direction, a PLC state change on the broker can set a workcenter's status in Plex (downtime), set up the next job, record batch production, add a checksheet with measurements, or scrap a container.

| Event | Request | Notes |
| - | - | - |
| ListWorkcenters | `GET /production/v1/production-definitions/workcenters?{query}` | Filter by `workcenterCode`, `name`, `workcenterGroup`, `buildingId`, `plcName`, `ipAddress` |
| GetWorkcenter | `GET /production/v1/production-definitions/workcenters/{workcenter_id}` | One workcenter definition |
| GetWorkcenterSetup | `GET /production/v1/control/workcenters/{workcenter_id}` | Live setup: current job, part, status |
| ListWorkcenterStatuses | `GET /production/v1/production-definitions/workcenter-statuses?{query}` | Status ids for `SetWorkcenterStatus` |
| ListWorkcenterEvents | `GET /production/v1/production-definitions/workcenter-events?{query}` | Event (reason) ids |
| ListWorkcenterStatusEntries | `GET /production/v1/production-history/workcenter-status-entries?{query}` | Status and downtime history; `beginDate`, `endDate` required |
| ListProductionEntries | `GET /production/v1/production-history/production-entries?{query}` | Production records; `beginDate`, `endDate` required |
| ListProductionEntriesSummary | `GET /production/v1/production-history/production-entries-summary?{query}` | Summarised production |
| ListScrapEntries | `GET /production/v1/production-history/scrap-entries?{query}` | Scrap records; `beginDate`, `endDate` required |
| ListBatches | `GET /production/v1/control/workcenters/{workcenter_id}/batches?{query}` | Batches on a workcenter |
| GetNextBatch | `GET /production/v1/control/workcenters/{workcenter_id}/next-batch?{query}` | Next batch to produce |
| ListJobs | `GET /scheduling/v1/jobs?{query}` | Filter by `jobStatuses`, `partId`, `buildingId`, due dates |
| GetJob | `GET /scheduling/v1/jobs/{job_id}` | One job |
| ListJobOperations | `GET /scheduling/v1/jobs/{job_id}/operations?{query}` | Operations of a job; ids for `SetupJob` |
| ListParts | `GET /mdm/v2/parts?{query}` | Part master data |
| ListContainers | `GET /inventory/v1/inventory-tracking/containers?{query}` | Inventory containers |
| ListEquipment | `GET /maintenance/v1/equipment?{query}` | Equipment records |
| ListControlPlans | `GET /quality/v1/control-plans?{query}` | Quality control plans |
| GetChecksheet | `GET /quality/v1/checksheets/{checksheet_id}` | One checksheet |
| SetWorkcenterStatus | `POST /production/v1/control/workcenters/{workcenter_id}/status` | Downtime or running status |
| SetupJob | `POST /production/v1/control/workcenters/{workcenter_id}/setup-job` | Set up a job operation on a workcenter |
| RecordBatchProduction | `POST /production/v1/control/workcenters/{workcenter_id}/record-batch-production` | Record produced quantity for a batch |
| CreateChecksheet | `POST /quality/v1/checksheets` | Add a checksheet with measurements (`201`) |
| ScrapContainer | `POST /inventory/v1/inventory-control/containers/{serial_no}/scrap` | Scrap quantity from a container (`204`) |

Topics are `mes/rockwell-plex-smart-manufacturing-platform/<object>/<verb>`; every reply goes to `<topic>/response`.

## Authentication

Every event sends `X-Plex-Connect-Api-Key: {api_key}`. The key is the Consumer Key of an app you create under **My Apps** in the [Plex Developer Portal](https://developers.plex.com/), subscribed to the API products this connector uses: Production Operations Management, Job Scheduling, Parts, Inventory Operations Management, Equipment, Control Plans and Checksheet. Access to the portal requires Plex IAM, which your Plex Champion arranges through a support case.

Keep the key in a broker secret (suggested `PLEX_CONNECT_API_KEY`) and map it in with `GET SECRET`. Requests run against the key's default tenant (PCN). To work with another PCN, add `ADD "X-Plex-Connect-Tenant-Id" "{value.json.tenant_id}"` under `WITH HEADERS` and send `tenant_id` in the payload.

Plex has a test tier at `https://test.connect.plex.com`, and test and production keys must be different. A missing or wrong key, including a production key used on the test tier, returns `401` with `REQUEST_NOT_AUTHENTICATED`. An app that is not subscribed to an API product gets `403`.

## Basic Syntax

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR RockwellPlex WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://connect.plex.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListProductionEntries
        WITH SOURCE_TOPIC "mes/rockwell-plex-smart-manufacturing-platform/production-entry/list"
        WITH DESTINATION_TOPIC "mes/rockwell-plex-smart-manufacturing-platform/production-entry/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/production/v1/production-history/production-entries?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Plex-Connect-Api-Key" "{value.json.api_key}"
    ADD EVENT SetWorkcenterStatus
        WITH SOURCE_TOPIC "mes/rockwell-plex-smart-manufacturing-platform/workcenter-status/set"
        WITH DESTINATION_TOPIC "mes/rockwell-plex-smart-manufacturing-platform/workcenter-status/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/production/v1/control/workcenters/{value.json.workcenter_id}/status"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Plex-Connect-Api-Key" "{value.json.api_key}"
        WITH BODY "{value.json.body}"
```

Use `https://test.connect.plex.com` as `BASE_ADDRESS` while you develop. The full template, with all 24 events, is `RockwellPlexSmartManufacturingPlatformRestApi.lot` in the REST API app.

## MQTT examples

Request bodies go under `body`, so control fields like `api_key`, `workcenter_id` and `query` are not sent to Plex. Ids are Plex GUIDs.

**Find a workcenter by code**: publish to `mes/rockwell-plex-smart-manufacturing-platform/workcenter/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<Plex Consumer Key>",
  "query": "workcenterCode=PRESS-01"
}
```

**Read this shift's production**: publish to `mes/rockwell-plex-smart-manufacturing-platform/production-entry/list`. Plex requires `beginDate` and `endDate`, and the query must be URL-encoded:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<Plex Consumer Key>",
  "query": "beginDate=2026-10-05T06:00:00Z&endDate=2026-10-05T14:00:00Z&workcenterId=<workcenter uuid>"
}
```

Send `"query": ""` on list events when you do not need filters.

**Put a workcenter into downtime**: look up the status id with `workcenter-status/list`, then publish to `mes/rockwell-plex-smart-manufacturing-platform/workcenter-status/set`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<Plex Consumer Key>",
  "workcenter_id": "<workcenter uuid>",
  "body": { "workcenterStatusId": "<status uuid>", "workcenterEventId": "<optional reason uuid>" }
}
```

**Record batch production**: publish to `mes/rockwell-plex-smart-manufacturing-platform/batch-production/record` with `"body": { "batchId": "<batch uuid>", "quantity": 12 }`. Get the batch id from `batch/next` or `batch/list`.

**Scrap from a container**: publish to `mes/rockwell-plex-smart-manufacturing-platform/container/scrap` with `"serial_no": "<container serial>"` and `"body": { "scrapReason": "<reason>", "quantity": 1 }`. Plex answers `204` with an empty body.

## Helper actions

Keep the key in a broker secret, read a workcenter's live setup every minute, and turn a PLC status change into a Plex workcenter status:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PlexPollWorkcenterStatus
ON EVERY 1 MINUTE DO
    SET "key" WITH GET SECRET "PLEX_CONNECT_API_KEY"
    PUBLISH TOPIC "mes/rockwell-plex-smart-manufacturing-platform/workcenter-setup/get" WITH { "api_key": {key}, "workcenter_id": "<workcenter uuid>" }

DEFINE ACTION PlexDowntimeFromLine
ON TOPIC "porto/line1/press01/plex-status" DO
    SET "key" WITH GET SECRET "PLEX_CONNECT_API_KEY"
    SET "status" WITH GET JSON "workcenterStatusId" IN PAYLOAD AS STRING
    PUBLISH TOPIC "mes/rockwell-plex-smart-manufacturing-platform/workcenter-status/set" WITH { "api_key": {key}, "workcenter_id": "<workcenter uuid>", "body": { "workcenterStatusId": {status} } }
```

Restrict who can publish to `mes/rockwell-plex-smart-manufacturing-platform/#` with a rule: its payloads carry the API key, and the POST events change production records.

## Notes

* Errors come back on the response topic: `401 REQUEST_NOT_AUTHENTICATED` for a missing or wrong key, `403` when the app is not subscribed to that API product, `404` for an unknown id, `400` with the failing fields for a validation error, and `429` when you hit Plex rate limits.
* Plex history endpoints need a date range. Keep ranges short (one shift) and page by time to stay inside rate limits.
* Status and event ids differ per tenant. Read `workcenter-status/list` and `workcenter-event/list` once and keep the ids in a model or broker configuration.
* `CreateChecksheet` needs `operationId`, `inspectionMode` and `measurements`; take the field names from the control plan (`control-plan/list`) and the Checksheet API in the Plex portal.
* Plex publishes many more APIs (sales orders, purchasing, EDI, accounting, digital work instructions, Plex APM). Add events for them the same way: one `ADD EVENT` per operation, with the path from the Developer Portal.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Siemens Opcenter Execution](/latest/lot-language/routes/rest-api-apps/siemens-opcenter-execution)
* [SAP Digital Manufacturing](/latest/lot-language/routes/rest-api-apps/sap-digital-manufacturing)


# Salesforce
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/salesforce

Client-mode REST API connector for a curated Salesforce REST API v62.0 slice: Cases from alarms, Asset telemetry, SOQL, Platform Events, and Composite

Technical Preview

## Overview

A client-mode connector for a **curated CRM / Field Service / IIoT bridge** slice of the [Salesforce REST API](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/) under `https://YOUR_INSTANCE.my.salesforce.com/services/data/v62.0/`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| (discovery) | `GET /services/data/v62.0/sobjects` | Global sObject catalog; a good first call |
| GET SOQL query?q= | `GET /services/data/v62.0/query?q=` | URL-encode the SOQL string |
| POST Case from alarm | `POST /services/data/v62.0/sobjects/Case` | Map IIoT alerts → Case |
| PATCH Asset with telemetry | `PATCH /services/data/v62.0/sobjects/Asset/{id}` | Update status / custom fields |
| POST Platform Event | `POST /services/data/v62.0/sobjects/{Event__e}` | `eventName` must end with `__e` |
| (batch) | `POST /services/data/v62.0/composite` | Multi-request in one round-trip |

`BASE_ADDRESS` is the org **instance URL** from the OAuth token response (no trailing slash). Topics use `crm/salesforce/<object>/<verb>`.

> [!NOTE]
>
> Use the `instance_url` returned with the access token (for example `https://mycompany.my.salesforce.com`). `login.salesforce.com` and `test.salesforce.com` are for OAuth token exchange only — calling `/services/data/` on the login host returns `URL_NOT_RESET`.

> [!NOTE]
>
> API version is pinned to **v62.0**. Bump the path version in the `.lot` when you standardize on a newer org API version. Bulk 2.0 and Pub/Sub (gRPC) are out of scope for this REST\_API client template. Prefer Hub secrets for tokens.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Salesforce (REST API v62.0 curated slice)
# Auth: Bearer {value.json.access_token}
# BASE_ADDRESS: https://YOUR_INSTANCE.my.salesforce.com

DEFINE CONNECTOR SalesforceRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.my.salesforce.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listsobjects
        WITH SOURCE_TOPIC "crm/salesforce/sobjects/list"
        WITH DESTINATION_TOPIC "crm/salesforce/sobjects/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v62.0/sobjects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Querysoql
        WITH SOURCE_TOPIC "crm/salesforce/query/soql"
        WITH DESTINATION_TOPIC "crm/salesforce/query/soql/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v62.0/query?q={value.json.q}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createcase
        WITH SOURCE_TOPIC "crm/salesforce/case/create"
        WITH DESTINATION_TOPIC "crm/salesforce/case/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/data/v62.0/sobjects/Case"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Patchasset
        WITH SOURCE_TOPIC "crm/salesforce/asset/patch"
        WITH DESTINATION_TOPIC "crm/salesforce/asset/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/services/data/v62.0/sobjects/Asset/{value.json.assetId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Createplatformevent
        WITH SOURCE_TOPIC "crm/salesforce/platform-event/create"
        WITH DESTINATION_TOPIC "crm/salesforce/platform-event/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/data/v62.0/sobjects/{value.json.eventName}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Composite
        WITH SOURCE_TOPIC "crm/salesforce/composite/post"
        WITH DESTINATION_TOPIC "crm/salesforce/composite/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/data/v62.0/composite"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Listsobjects | GET | `/services/data/v62.0/sobjects` | `crm/salesforce/sobjects/list` | `crm/salesforce/sobjects/list/response` |
| Querysoql | GET | `/services/data/v62.0/query?q={q}` | `crm/salesforce/query/soql` | `crm/salesforce/query/soql/response` |
| Createcase | POST | `/services/data/v62.0/sobjects/Case` | `crm/salesforce/case/create` | `crm/salesforce/case/create/response` |
| Patchasset | PATCH | `/services/data/v62.0/sobjects/Asset/{assetId}` | `crm/salesforce/asset/patch` | `crm/salesforce/asset/patch/response` |
| Createplatformevent | POST | `/services/data/v62.0/sobjects/{eventName}` | `crm/salesforce/platform-event/create` | `crm/salesforce/platform-event/create/response` |
| Composite | POST | `/services/data/v62.0/composite` | `crm/salesforce/composite/post` | `crm/salesforce/composite/post/response` |

## Auth

**OAuth 2.0 Bearer access token — default in the template:**

1. In Salesforce Setup, create a **Connected App** with the OAuth scopes your integration needs (at least API access).
2. Obtain an `access_token` (authorization code, JWT bearer, or client credentials where the org enables it).
3. Set connector `BASE_ADDRESS` to the token response `instance_url` (My Domain host).
4. Pass `access_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.access_token}`
5. Store the token in Hub secrets / `GET SECRET`. Never commit real credentials.

## Example payloads

**List sObjects:** include `access_token` on the MQTT JSON root used for header substitution.

**SOQL:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "q": "SELECT+Id,+Subject,+Status+FROM+Case+LIMIT+10"
}
```

**Create Case:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "Subject": "Line sensor fault — Zone A",
  "Description": "Vibration above threshold",
  "Origin": "IoT",
  "Priority": "High",
  "Status": "New"
}
```

**PATCH Asset:** path uses `assetId`; body is the field map.

**Platform Event:** set `eventName` to the API name ending in `__e` (for example `DeviceAlert__e`); body is the event field map.

## Deploy notes

* Deploy **`SalesforceRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/salesforce](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/salesforce)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Samsara REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/samsara

Client-mode REST API connector for Samsara fleet vehicle stats, assets, and alerts

Technical Preview

## Overview

Client-mode REST API connector for Samsara fleet vehicle stats, assets, and alerts. `BASE_ADDRESS` defaults to `https://api.samsara.com`. Auth: **Bearer API token**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

Bearer API token. Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR SamsaraRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.samsara.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Authorization Bearer {value.json.api_token} — prefer Hub secrets / GET SECRET.
        # Optional Basic: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Listvehicles
        WITH SOURCE_TOPIC "integrations/samsara/request/Listvehicles"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Listvehicles"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/vehicles"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getvehiclestats
        WITH SOURCE_TOPIC "integrations/samsara/request/Getvehiclestats"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Getvehiclestats"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/vehicles/stats?types={value.json.types}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getvehiclestatsfeed
        WITH SOURCE_TOPIC "integrations/samsara/request/Getvehiclestatsfeed"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Getvehiclestatsfeed"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/vehicles/stats/feed?types={value.json.types}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getvehicle
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/samsara/request/...`; responses on `integrations/samsara/response/...`.

## Template reference

Generated from the shipped broker template `samsara` (`-connectorCode SAMSARA`). It lists every event the template defines.

### Auth

Bearer API token

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Samsara connector | no |
| `BaseUrl` | string | Samsara base URL without trailing slash (e.g. [https://api.samsara.com](https://api.samsara.com)) | yes |

`BASE_ADDRESS` default: `https://api.samsara.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listvehicles` | GET | `/fleet/vehicles` | `integrations/samsara/request/Listvehicles` | `integrations/samsara/response/Listvehicles` | `api_token` |
| `Getvehiclestats` | GET | `/fleet/vehicles/stats?types={value.json.types}` | `integrations/samsara/request/Getvehiclestats` | `integrations/samsara/response/Getvehiclestats` | `api_token`, `types` |
| `Getvehiclestatsfeed` | GET | `/fleet/vehicles/stats/feed?types={value.json.types}` | `integrations/samsara/request/Getvehiclestatsfeed` | `integrations/samsara/response/Getvehiclestatsfeed` | `api_token`, `types` |
| `Getvehicle` | GET | `/fleet/vehicles/{value.json.id}` | `integrations/samsara/request/Getvehicle` | `integrations/samsara/response/Getvehicle` | `api_token`, `id` |
| `Listindustrialassets` | GET | `/industrial/assets` | `integrations/samsara/request/Listindustrialassets` | `integrations/samsara/response/Listindustrialassets` | `api_token` |
| `Listdrivers` | GET | `/fleet/drivers` | `integrations/samsara/request/Listdrivers` | `integrations/samsara/response/Listdrivers` | `api_token` |
| `Listequipment` | GET | `/fleet/equipment` | `integrations/samsara/request/Listequipment` | `integrations/samsara/response/Listequipment` | `api_token` |
| `Listaddresses` | GET | `/addresses` | `integrations/samsara/request/Listaddresses` | `integrations/samsara/response/Listaddresses` | `api_token` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SAMSARA"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SamsaraRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.samsara.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listvehicles
        WITH SOURCE_TOPIC "integrations/samsara/request/Listvehicles"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Listvehicles"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/vehicles"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getvehiclestats
        WITH SOURCE_TOPIC "integrations/samsara/request/Getvehiclestats"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Getvehiclestats"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/vehicles/stats?types={value.json.types}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getvehiclestatsfeed
        WITH SOURCE_TOPIC "integrations/samsara/request/Getvehiclestatsfeed"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Getvehiclestatsfeed"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/vehicles/stats/feed?types={value.json.types}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getvehicle
        WITH SOURCE_TOPIC "integrations/samsara/request/Getvehicle"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Getvehicle"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/vehicles/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listindustrialassets
        WITH SOURCE_TOPIC "integrations/samsara/request/Listindustrialassets"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Listindustrialassets"
        WITH METHOD "GET"
        WITH ENDPOINT "/industrial/assets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listdrivers
        WITH SOURCE_TOPIC "integrations/samsara/request/Listdrivers"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Listdrivers"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/drivers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listequipment
        WITH SOURCE_TOPIC "integrations/samsara/request/Listequipment"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Listequipment"
        WITH METHOD "GET"
        WITH ENDPOINT "/fleet/equipment"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listaddresses
        WITH SOURCE_TOPIC "integrations/samsara/request/Listaddresses"
        WITH DESTINATION_TOPIC "integrations/samsara/response/Listaddresses"
        WITH METHOD "GET"
        WITH ENDPOINT "/addresses"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listvehicles` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/samsara/response/Listvehicles' &
mosquitto_pub -t 'integrations/samsara/request/Listvehicles' -m '{"api_token": "<api_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# Sap Ariba Open Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-ariba-open-api

LoT connector for SAP Ariba: purchase orders on SAP Business Network, supplier catalog items, procurement reporting, and requisition and invoice approvals

Technical Preview

## Overview

Client-mode REST API connectors for SAP Ariba: purchase orders and line items on SAP Business Network for suppliers and buyers, supplier catalog items, Operational Reporting for Procurement, and Document Approval for requisitions and invoices.

This is one of the templates in the SAP Ariba REST API app (`sap-ariba`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["OAuth 2.0 client credentials at /v2/oauth/token with Basic base64(clientId:clientSecret)", "apiKey header (application key) + Authorization: Bearer \<access\_token> on every gateway call", "X-ARIBA-NETWORK-ID header (ANID) on SAP Business Network APIs", "realm query parameter on realm APIs"]
* **secrets**: \["ARIBA\_OAUTH\_BASIC", "ARIBA\_API\_KEY", "ARIBA\_ANID"]
* **note**: One Developer Portal application per API; key and token must come from the same application.

Auth headers used by the template: `Authorization: Bearer {value.json.token}`, `apiKey: {value.json.apikey}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Sap Ariba Open Api connector | no |
| `BaseUrl` | string | Sap Ariba Open Api base URL without trailing slash (e.g. [https://openapi.ariba.com](https://openapi.ariba.com)) | yes |

`BASE_ADDRESS` default: `https://openapi.ariba.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `SupplierOrders` | GET | `/api/purchase-orders-supplier/v1/prod/orders?{value.json.query}` | `erp/sap-ariba/supplier/orders/get` | `erp/sap-ariba/supplier/orders/get/response` | `anid`, `apikey`, `query`, `token` |
| `SupplierOrderItems` | GET | `/api/purchase-orders-supplier/v1/prod/items?{value.json.query}` | `erp/sap-ariba/supplier/order-items/get` | `erp/sap-ariba/supplier/order-items/get/response` | `anid`, `apikey`, `query`, `token` |
| `BuyerOrders` | GET | `/api/purchase-orders/v1/prod/orders?{value.json.query}` | `erp/sap-ariba/buyer/orders/get` | `erp/sap-ariba/buyer/orders/get/response` | `anid`, `apikey`, `query`, `token` |
| `BuyerOrderItems` | GET | `/api/purchase-orders/v1/prod/items?{value.json.query}` | `erp/sap-ariba/buyer/order-items/get` | `erp/sap-ariba/buyer/order-items/get/response` | `anid`, `apikey`, `query`, `token` |
| `CatalogSubscriptions` | GET | `/api/catalogcontent/v1/prod/catalogs?realm={value.json.realm}&date={value.json.date}{value.json.params}` | `erp/sap-ariba/catalog/subscriptions/get` | `erp/sap-ariba/catalog/subscriptions/get/response` | `apikey`, `date`, `params`, `realm`, `token` |
| `CatalogItems` | GET | `/api/catalogcontent/v1/prod/catalogname/{value.json.catalogname}/supplierid/{value.json.supplierid}/items?realm={value.json.realm}{value.json.params}` | `erp/sap-ariba/catalog/items/get` | `erp/sap-ariba/catalog/items/get/response` | `apikey`, `catalogname`, `params`, `realm`, `supplierid`, `token` |
| `CatalogItemSchema` | GET | `/api/catalogcontent/v1/prod/items/schema?realm={value.json.realm}` | `erp/sap-ariba/catalog/items/schema/get` | `erp/sap-ariba/catalog/items/schema/get/response` | `apikey`, `realm`, `token` |
| `ReportingViewTemplates` | GET | `/api/procurement-reporting-view/v2/prod/viewTemplates?realm={value.json.realm}{value.json.params}` | `erp/sap-ariba/reporting/view-templates/get` | `erp/sap-ariba/reporting/view-templates/get/response` | `apikey`, `params`, `realm`, `token` |
| `ReportingView` | GET | `/api/procurement-reporting-details/v2/prod/views/{value.json.template}?realm={value.json.realm}{value.json.params}` | `erp/sap-ariba/reporting/view/get` | `erp/sap-ariba/reporting/view/get/response` | `apikey`, `params`, `realm`, `template`, `token` |
| `ReportingViewCount` | GET | `/api/procurement-reporting-details/v2/prod/views/{value.json.template}/count?realm={value.json.realm}{value.json.params}` | `erp/sap-ariba/reporting/view/count` | `erp/sap-ariba/reporting/view/count/response` | `apikey`, `params`, `realm`, `template`, `token` |
| `ReportingJobSubmit` | POST | `/api/procurement-reporting-job/v2/prod/jobs?realm={value.json.realm}` | `erp/sap-ariba/reporting/jobs/submit` | `erp/sap-ariba/reporting/jobs/submit/response` | `apikey`, `body`, `realm`, `token` |
| `ReportingJobStatus` | GET | `/api/procurement-reporting-jobresult/v2/prod/jobs/{value.json.jobid}?realm={value.json.realm}` | `erp/sap-ariba/reporting/jobs/status/get` | `erp/sap-ariba/reporting/jobs/status/get/response` | `apikey`, `jobid`, `realm`, `token` |
| `ApprovalChanges` | GET | `/api/approval/v1/prod/changes?realm={value.json.realm}{value.json.params}` | `erp/sap-ariba/approval/changes/get` | `erp/sap-ariba/approval/changes/get/response` | `apikey`, `params`, `realm`, `token` |
| `PendingApprovables` | GET | `/api/approval/v1/prod/pendingApprovables?realm={value.json.realm}{value.json.params}` | `erp/sap-ariba/approval/pending/get` | `erp/sap-ariba/approval/pending/get/response` | `apikey`, `params`, `realm`, `token` |
| `GetApprovable` | GET | `/api/approval/v1/prod/{value.json.approvabletype}/{value.json.approvableid}?realm={value.json.realm}` | `erp/sap-ariba/approval/approvable/get` | `erp/sap-ariba/approval/approvable/get/response` | `apikey`, `approvableid`, `approvabletype`, `realm`, `token` |
| `SetApprovableState` | PATCH | `/api/approval/v1/prod/{value.json.approvabletype}/{value.json.approvableid}?realm={value.json.realm}&user={value.json.user}&passwordadapter={value.json.passwordadapter}` | `erp/sap-ariba/approval/approvable/set` | `erp/sap-ariba/approval/approvable/set/response` | `apikey`, `approvableid`, `approvabletype`, `body`, `passwordadapter`, `realm`, `token`, `user` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SAP_ARIBA"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SapAribaOpenApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://openapi.ariba.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SupplierOrders
        WITH SOURCE_TOPIC "erp/sap-ariba/supplier/orders/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/supplier/orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/purchase-orders-supplier/v1/prod/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "X-ARIBA-NETWORK-ID" "{value.json.anid}"
    ADD EVENT SupplierOrderItems
        WITH SOURCE_TOPIC "erp/sap-ariba/supplier/order-items/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/supplier/order-items/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/purchase-orders-supplier/v1/prod/items?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "X-ARIBA-NETWORK-ID" "{value.json.anid}"
    ADD EVENT BuyerOrders
        WITH SOURCE_TOPIC "erp/sap-ariba/buyer/orders/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/buyer/orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/purchase-orders/v1/prod/orders?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "X-ARIBA-NETWORK-ID" "{value.json.anid}"
    ADD EVENT BuyerOrderItems
        WITH SOURCE_TOPIC "erp/sap-ariba/buyer/order-items/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/buyer/order-items/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/purchase-orders/v1/prod/items?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "X-ARIBA-NETWORK-ID" "{value.json.anid}"
    ADD EVENT CatalogSubscriptions
        WITH SOURCE_TOPIC "erp/sap-ariba/catalog/subscriptions/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/catalog/subscriptions/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/catalogcontent/v1/prod/catalogs?realm={value.json.realm}&date={value.json.date}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT CatalogItems
        WITH SOURCE_TOPIC "erp/sap-ariba/catalog/items/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/catalog/items/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/catalogcontent/v1/prod/catalogname/{value.json.catalogname}/supplierid/{value.json.supplierid}/items?realm={value.json.realm}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT CatalogItemSchema
        WITH SOURCE_TOPIC "erp/sap-ariba/catalog/items/schema/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/catalog/items/schema/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/catalogcontent/v1/prod/items/schema?realm={value.json.realm}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ReportingViewTemplates
        WITH SOURCE_TOPIC "erp/sap-ariba/reporting/view-templates/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/reporting/view-templates/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/procurement-reporting-view/v2/prod/viewTemplates?realm={value.json.realm}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ReportingView
        WITH SOURCE_TOPIC "erp/sap-ariba/reporting/view/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/reporting/view/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/procurement-reporting-details/v2/prod/views/{value.json.template}?realm={value.json.realm}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ReportingViewCount
        WITH SOURCE_TOPIC "erp/sap-ariba/reporting/view/count"
        WITH DESTINATION_TOPIC "erp/sap-ariba/reporting/view/count/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/procurement-reporting-details/v2/prod/views/{value.json.template}/count?realm={value.json.realm}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ReportingJobSubmit
        WITH SOURCE_TOPIC "erp/sap-ariba/reporting/jobs/submit"
        WITH DESTINATION_TOPIC "erp/sap-ariba/reporting/jobs/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/procurement-reporting-job/v2/prod/jobs?realm={value.json.realm}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ReportingJobStatus
        WITH SOURCE_TOPIC "erp/sap-ariba/reporting/jobs/status/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/reporting/jobs/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/procurement-reporting-jobresult/v2/prod/jobs/{value.json.jobid}?realm={value.json.realm}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT ApprovalChanges
        WITH SOURCE_TOPIC "erp/sap-ariba/approval/changes/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/approval/changes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/approval/v1/prod/changes?realm={value.json.realm}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT PendingApprovables
        WITH SOURCE_TOPIC "erp/sap-ariba/approval/pending/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/approval/pending/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/approval/v1/prod/pendingApprovables?realm={value.json.realm}{value.json.params}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT GetApprovable
        WITH SOURCE_TOPIC "erp/sap-ariba/approval/approvable/get"
        WITH DESTINATION_TOPIC "erp/sap-ariba/approval/approvable/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/approval/v1/prod/{value.json.approvabletype}/{value.json.approvableid}?realm={value.json.realm}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT SetApprovableState
        WITH SOURCE_TOPIC "erp/sap-ariba/approval/approvable/set"
        WITH DESTINATION_TOPIC "erp/sap-ariba/approval/approvable/set/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/approval/v1/prod/{value.json.approvabletype}/{value.json.approvableid}?realm={value.json.realm}&user={value.json.user}&passwordadapter={value.json.passwordadapter}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "apiKey" "{value.json.apikey}"
            ADD "Authorization" "Bearer {value.json.token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `SupplierOrders` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'erp/sap-ariba/supplier/orders/get/response' &
mosquitto_pub -t 'erp/sap-ariba/supplier/orders/get' -m '{"anid": "<anid>", "apikey": "<apikey>", "query": "<query>", "token": "<token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# SAP Business One Service Layer
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-b1

LoT connector for the SAP Business One Service Layer: read items and warehouse stock, business partners, and post receipts from production

Technical Preview

## Overview

A client-mode connector for a **curated inventory and master-data** slice of [SAP Business One Service Layer](https://help.sap.com/doc/056f69366b5345a386bb8149f1700c19/10.0/en-US/Service%20Layer%20API%20Reference.html) OData v4 (`/b1s/v2`):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET Items and warehouse stock | `Items`, `Items('{ItemCode}')` + `$expand=ItemWarehouseInfoCollection` | QuantityOnStock + per-warehouse collection |
| POST ProductionOrders receipt | `InventoryGenEntries` | Receipt from production: `DocumentLines.BaseType = 202` |
| GET BusinessPartners | `BusinessPartners` | Customers / vendors |
| Session | `Login`, `Logout` | `B1SESSION` (+ `ROUTEID`) cookie |

`BASE_ADDRESS` is the Service Layer root (`https://{host}:50000/b1s/v2`). Topics use `erp/sap-b1/<object>/<verb>`.

> [!NOTE]
>
> Service Layer requires a real company database and a session from `POST /Login`. Prefer Hub secrets for CompanyDB / UserName / Password.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — SAP Business One Service Layer (curated Items / stock / BP / receipt slice)
# Auth: Session login POST /Login → SessionId / Set-Cookie B1SESSION (+ ROUTEID).
# BASE_ADDRESS: https://YOUR_HOST:50000/b1s/v2

DEFINE CONNECTOR SapB1RestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_HOST:50000/b1s/v2"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Login
        WITH SOURCE_TOPIC "erp/sap-b1/session/login"
        WITH DESTINATION_TOPIC "erp/sap-b1/session/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/Login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Logout
        WITH SOURCE_TOPIC "erp/sap-b1/session/logout"
        WITH DESTINATION_TOPIC "erp/sap-b1/session/logout/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Logout"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Cookie" "B1SESSION={value.json.B1SESSION}; ROUTEID={value.json.ROUTEID}"
    ADD EVENT Getitems
        WITH SOURCE_TOPIC "erp/sap-b1/items/get"
        WITH DESTINATION_TOPIC "erp/sap-b1/items/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Items?$select=ItemCode,ItemName,QuantityOnStock&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Cookie" "B1SESSION={value.json.B1SESSION}; ROUTEID={value.json.ROUTEID}"
    ADD EVENT Getitemwarehousestock
        WITH SOURCE_TOPIC "erp/sap-b1/items/warehouse-stock/get"
        WITH DESTINATION_TOPIC "erp/sap-b1/items/warehouse-stock/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/Items('{value.json.ItemCode}')?$select=ItemCode,ItemName,QuantityOnStock&$expand=ItemWarehouseInfoCollection"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Cookie" "B1SESSION={value.json.B1SESSION}; ROUTEID={value.json.ROUTEID}"
    ADD EVENT Getbusinesspartners
        WITH SOURCE_TOPIC "erp/sap-b1/business-partners/get"
        WITH DESTINATION_TOPIC "erp/sap-b1/business-partners/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/BusinessPartners?$select=CardCode,CardName,CardType&$top={value.json.top}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Cookie" "B1SESSION={value.json.B1SESSION}; ROUTEID={value.json.ROUTEID}"
    ADD EVENT Createinventorygenentry
        WITH SOURCE_TOPIC "erp/sap-b1/inventory-gen-entry/create"
        WITH DESTINATION_TOPIC "erp/sap-b1/inventory-gen-entry/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/InventoryGenEntries"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "B1SESSION={value.json.B1SESSION}; ROUTEID={value.json.ROUTEID}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Login | POST | `/Login` | `erp/sap-b1/session/login` | `erp/sap-b1/session/login/response` |
| Logout | GET | `/Logout` | `erp/sap-b1/session/logout` | `erp/sap-b1/session/logout/response` |
| Getitems | GET | `/Items` | `erp/sap-b1/items/get` | `erp/sap-b1/items/get/response` |
| Getitemwarehousestock | GET | `/Items('{ItemCode}')` + expand | `erp/sap-b1/items/warehouse-stock/get` | `erp/sap-b1/items/warehouse-stock/get/response` |
| Getbusinesspartners | GET | `/BusinessPartners` | `erp/sap-b1/business-partners/get` | `erp/sap-b1/business-partners/get/response` |
| Createinventorygenentry | POST | `/InventoryGenEntries` | `erp/sap-b1/inventory-gen-entry/create` | `erp/sap-b1/inventory-gen-entry/create/response` |

## Auth

Session login (required before data calls):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"CompanyDB": "YOUR_COMPANY_DB", "UserName": "YOUR_B1_USER", "Password": "YOUR_B1_PASSWORD"}
```

Cookie on later events:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Cookie" "B1SESSION={value.json.B1SESSION}; ROUTEID={value.json.ROUTEID}"
```

**CompanyDB** `string` *required*

Company database name for Login. Prefer a Hub secret. Never commit the password or live DB name into git.

**UserName** `string` *required*

SAP Business One user for Login.

**Password** `string` *required*

Password for Login. Prefer Hub `GET SECRET`. Never commit.

**B1SESSION** `string` *required*

Session id from Login response (`SessionId` / `B1SESSION` cookie). Required on all events after Login.

**ROUTEID** `string` *required*

Load-balancer cookie from Set-Cookie (often `.node1`). Use the value your Service Layer returns.

**ItemCode** `string`

Item key for Getitemwarehousestock.

**top** `integer`

OData `$top` for list GETs (Items / BusinessPartners).

High-level setup (no secrets in the template):

1. Point `BASE_ADDRESS` at `https://{host}:50000/b1s/v2` (TLS; trust the SL certificate in the lab).
2. Login with CompanyDB / UserName / Password (Hub secrets).
3. Copy `SessionId` → `B1SESSION` and `ROUTEID` into subsequent MQTT payloads.
4. Call GET Items / BusinessPartners; for receipt from production POST InventoryGenEntries with `BaseType: 202`.
5. Logout.

Login payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"CompanyDB": "YOUR_COMPANY_DB", "UserName": "YOUR_B1_USER", "Password": "YOUR_B1_PASSWORD"}
```

GET Items (after login):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"B1SESSION": "YOUR_SESSION_ID", "ROUTEID": ".node1", "top": "10"}
```

POST receipt from production (connector body is `{payload}` — include Cookie fields in the same JSON envelope your broker expects, or set Cookie via header placeholders):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "B1SESSION": "YOUR_SESSION_ID",
  "ROUTEID": ".node1",
  "DocDate": "2026-10-03",
  "Comments": "Receipt from production via Coreflux",
  "DocumentLines": [
    {
      "BaseType": 202,
      "BaseEntry": 1,
      "BaseLine": 0,
      "Quantity": 10,
      "WarehouseCode": "01"
    }
  ]
}
```

## Try it

1. Replace `YOUR_HOST` in `BASE_ADDRESS` and add the connector on your broker.
2. Publish login JSON to `erp/sap-b1/session/login`.
3. Subscribe to `erp/sap-b1/session/login/response`, then GET Items or BusinessPartners with `B1SESSION` / `ROUTEID`.
4. Optionally POST InventoryGenEntries for a known production order (`BaseType` 202).
5. Logout.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)
* [Service Layer API Reference](https://help.sap.com/doc/056f69366b5345a386bb8149f1700c19/10.0/en-US/Service%20Layer%20API%20Reference.html)
* [Working with SAP Business One Service Layer (PDF)](https://help.sap.com/doc/fc2f5477516c404c8bf9ad1315a17238/10.0/en-US/Working_with_SAP_Business_One_Service_Layer.pdf)


# SAP Digital Manufacturing
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-digital-manufacturing

LoT connector for SAP Digital Manufacturing: start and complete SFCs, log nonconformances, post quantity confirmations and read production orders

Technical Preview

## Overview

A client-mode connector for a **curated MES / shop-floor** slice of [SAP Digital Manufacturing](https://api.sap.com/package/SAPDigitalManufacturingCloud) (Digital Manufacturing Cloud) public REST APIs on the Business Accelerator Hub:

| Catalog connector event | API | Path |
| - | - | - |
| POST sfc/v1/sfcs/start | `sapdme_sfc` | `POST /sfc/v1/sfcs/start` |
| POST sfc/v1/sfcs/complete | `sapdme_sfc` | `POST /sfc/v1/sfcs/complete` |
| POST nonconformance | `sapdme_nonconformance` | `POST /nonconformance/v1/log` |
| POST quantityConfirmation | `sapdme_quantityConfirmation` | `POST /quantityConfirmation/v1/confirm` |
| GET order/v1/orders | `sapdme_order` | `GET /order/v1/orders?plant=&order=` |
| list plants | `sapdme_plant` | `GET /plant/v1/plants` |
| SFC detail | `sapdme_sfc` | `GET /sfc/v1/sfcdetail?plant=&sfc=` |

`BASE_ADDRESS` is the public API host root (`https://api.{regionHost}.dmc.cloud.sap`, no trailing slash). Example placeholder uses `eu20`. Topics use `mes/sap-digital-manufacturing/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** OAuth 2.0 **client credentials** from a BTP service key on the SAP Digital Manufacturing subaccount. Exchange at `{url}/oauth/token`, then pass `Authorization: Bearer {value.json.access_token}` on every MQTT payload. Prefer Hub secrets — never commit real tokens. `public-api-endpoint` from the service key must match `BASE_ADDRESS`.

> [!NOTE]
>
> This template has **not** been verified against a live authenticated DMC tenant.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — SAP Digital Manufacturing (curated MES slice)
# Auth: Bearer {value.json.access_token} from BTP OAuth client credentials
# BASE_ADDRESS: https://api.eu20.dmc.cloud.sap  → substitute {regionHost}

DEFINE CONNECTOR SapDigitalManufacturingRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.eu20.dmc.cloud.sap"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listplants
        WITH SOURCE_TOPIC "mes/sap-digital-manufacturing/plant/list"
        WITH DESTINATION_TOPIC "mes/sap-digital-manufacturing/plant/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/plant/v1/plants"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Startsfc
        WITH SOURCE_TOPIC "mes/sap-digital-manufacturing/sfc/start"
        WITH DESTINATION_TOPIC "mes/sap-digital-manufacturing/sfc/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sfc/v1/sfcs/start"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Completesfc
        WITH SOURCE_TOPIC "mes/sap-digital-manufacturing/sfc/complete"
        WITH DESTINATION_TOPIC "mes/sap-digital-manufacturing/sfc/complete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sfc/v1/sfcs/complete"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Lognonconformance
        WITH SOURCE_TOPIC "mes/sap-digital-manufacturing/nonconformance/log"
        WITH DESTINATION_TOPIC "mes/sap-digital-manufacturing/nonconformance/log/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/nonconformance/v1/log"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Quantityconfirmation
        WITH SOURCE_TOPIC "mes/sap-digital-manufacturing/quantity-confirmation/confirm"
        WITH DESTINATION_TOPIC "mes/sap-digital-manufacturing/quantity-confirmation/confirm/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/quantityConfirmation/v1/confirm"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getorder
        WITH SOURCE_TOPIC "mes/sap-digital-manufacturing/order/get"
        WITH DESTINATION_TOPIC "mes/sap-digital-manufacturing/order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/order/v1/orders?plant={value.json.plant}&order={value.json.order}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Events

| Event | MQTT request topic | Method | Endpoint |
| - | - | - | - |
| Listplants | `mes/sap-digital-manufacturing/plant/list` | GET | `/plant/v1/plants` |
| Getsfcdetail | `mes/sap-digital-manufacturing/sfc/get` | GET | `/sfc/v1/sfcdetail?plant=&sfc=` |
| Startsfc | `mes/sap-digital-manufacturing/sfc/start` | POST | `/sfc/v1/sfcs/start` |
| Completesfc | `mes/sap-digital-manufacturing/sfc/complete` | POST | `/sfc/v1/sfcs/complete` |
| Lognonconformance | `mes/sap-digital-manufacturing/nonconformance/log` | POST | `/nonconformance/v1/log` |
| Quantityconfirmation | `mes/sap-digital-manufacturing/quantity-confirmation/confirm` | POST | `/quantityConfirmation/v1/confirm` |
| Getorder | `mes/sap-digital-manufacturing/order/get` | GET | `/order/v1/orders?plant=&order=` |

Each request topic has a matching `/response` destination. POST bodies use `{payload}` (full MQTT JSON body forwarded to DMC). Include `access_token` in the JSON for Bearer auth.

### Example MQTT payloads

**GET plants:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "access_token": "YOUR_BTP_ACCESS_TOKEN" }
```

**Start SFC:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_BTP_ACCESS_TOKEN",
  "plant": "P001",
  "operation": "10",
  "resource": "RES01",
  "sfcs": ["SFC0001"]
}
```

**GET order:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_BTP_ACCESS_TOKEN",
  "plant": "P001",
  "order": "1000123"
}
```

## Configuration

| Setting | Value |
| - | - |
| `BASE_ADDRESS` | `https://api.{regionHost}.dmc.cloud.sap` (example `eu20`; no trailing slash) |
| Auth | BTP OAuth 2.0 client credentials → Bearer `access_token` |
| Token URL | `https://{subdomain}.authentication.{region}.hana.ondemand.com/oauth/token` |
| Content-Type | `application/json` |
| SSL | required (`USE_SSL true`) |

Region hosts commonly include `eu10`, `eu20`, `us10`, `us20`, and matching `test.*` hosts. Use the `public-api-endpoint` from your DM service key.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)
* [SAP Business Accelerator Hub — Digital Manufacturing](https://api.sap.com/package/SAPDigitalManufacturingCloud)
* [SAP Help — APIs for SAP Digital Manufacturing](https://help.sap.com/docs/sap-digital-manufacturing)


# SAP Field Service Management
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-field-service-management

LoT connector for SAP Field Service Management: create service calls and activities from alarms, update equipment run hours and run CoreSQL queries

Technical Preview

## Overview

[SAP Field Service Management](https://www.sap.com/products/scm/field-service-management.html) (now documented as **SAP Field Service and Asset Management**) plans and runs field service: **service calls** (tickets), **activities** (the jobs technicians do) and **equipment** at customer sites. This connector lets the broker open a service call and an activity when a machine raises an alarm, put run hours and other machine data on the equipment, and close the loop with business actions, so planners and technicians see what the machine sees.

The template has two connectors:

* **SapFsmApi** (`SapFieldServiceManagementRestApi.lot`), a client connector on your cluster host with 24 events: 13 writes, 10 reads and 1 token event. It has no `DELETE` or `PUT` events; cancel actions are business actions, not deletes.
* **SapFsmBusinessRuleReceiver** (`cmms_sap_fsm_webhook.lot`), an optional server connector on port `9012` that receives calls from a Business Rule **Webhook** action and publishes them on MQTT.

> [!NOTE]
>
> SAP publishes the FSM API specs on the SAP Business Accelerator Hub, which needs an SAP login, so the events were picked by hand from the SAP Help Portal ([Data API v4](https://help.sap.com/docs/SAP_FIELD_SERVICE_MANAGEMENT/fsm_data_api/data-api-introduction.html), [Data Model](https://help.sap.com/docs/SAP_FIELD_SERVICE_MANAGEMENT/fsm_data_model/servicecalldto_v27.html), [Query API](https://help.sap.com/docs/SAP_FIELD_SERVICE_MANAGEMENT/fsm_query_api/query-api-intro.html), [Service API](https://help.sap.com/docs/SAP_FIELD_SERVICE_MANAGEMENT/fsm_service_api/supported-requests.html), [OAuth](https://help.sap.com/docs/SAP_FIELD_SERVICE_MANAGEMENT/fsm_access_api/get-access-token.html)) and the [SAP/fsm-sdk](https://github.com/SAP/fsm-sdk) source.

## Events

| Event | Topic | Request | Kind | What it does |
| - | - | - | - | - |
| `GetToken` | `cmms/sapfsm/token/create` | `POST /api/oauth2/v2/token` | Auth | Get an OAuth 2.0 access token (client credentials, HTTP Basic with the FSM OAuth client id:secret). Reply access\_token, token\_type, expires\_in; send access\_token on every other event |
| `ListServiceCalls` | `cmms/sapfsm/service-call/list` | `GET /api/data/v4/ServiceCall?dtos=ServiceCall.27&page={page}&pageSize={page_size}` | Read | Service calls, paged (default 20 per page, keep pageSize at 1000 or less). Reply data\[].serviceCall plus currentPage / lastPage |
| `FindServiceCalls` | `cmms/sapfsm/service-call/find` | `GET /api/data/v4/ServiceCall?dtos=ServiceCall.27&query={query}&pageSize={page_size}` | Read | Service calls matching a URL-encoded Data API query condition, e.g. lastChanged>=\<epoch ms> for incremental polls |
| `GetServiceCall` | `cmms/sapfsm/service-call/get` | `GET /api/data/v4/ServiceCall/{id}?dtos=ServiceCall.27` | Read | One service call by cloud id |
| `GetServiceCallByExternalId` | `cmms/sapfsm/service-call/get-by-external-id` | `GET /api/data/v4/ServiceCall/externalId/{external_id}?dtos=ServiceCall.27` | Read | One service call by your externalId (e.g. the alarm id) |
| `CreateServiceCall` | `cmms/sapfsm/service-call/create` | `POST /api/data/v4/ServiceCall?dtos=ServiceCall.27` | Write | Create a service call from an alarm; reply 201 \{data:\[\{serviceCall:\{id, code, lastChanged...}}]} |
| `UpdateServiceCall` | `cmms/sapfsm/service-call/update` | `PATCH /api/data/v4/ServiceCall/{id}?dtos=ServiceCall.27&forceUpdate={force_update}` | Write | Patch service call fields; send the current lastChanged (optimistic lock) or force\_update true. Reply 201 |
| `UpsertServiceCallByExternalId` | `cmms/sapfsm/service-call/upsert` | `PATCH /api/data/v4/ServiceCall/externalId/{external_id}?dtos=ServiceCall.27` | Write | Create or update the service call keyed by your externalId (one service call per alarm id; creating needs all mandatory fields) |
| `FindActivities` | `cmms/sapfsm/activity/find` | `GET /api/data/v4/Activity?dtos=Activity.43&query={query}&pageSize={page_size}` | Read | Activities matching a URL-encoded Data API query condition |
| `GetActivity` | `cmms/sapfsm/activity/get` | `GET /api/data/v4/Activity/{id}?dtos=Activity.43` | Read | One activity by cloud id (status, executionStage, responsibles, object -> service call) |
| `CreateActivity` | `cmms/sapfsm/activity/create` | `POST /api/data/v4/Activity?dtos=Activity.43` | Write | Create an activity under a service call (object = \{objectId, objectType SERVICECALL}) |
| `UpdateActivity` | `cmms/sapfsm/activity/update` | `PATCH /api/data/v4/Activity/{id}?dtos=Activity.43&forceUpdate={force_update}` | Write | Patch activity fields (send lastChanged or force\_update true). Use the Service Management actions to change planning state |
| `FindEquipment` | `cmms/sapfsm/equipment/find` | `GET /api/data/v4/Equipment?dtos=Equipment.24&query={query}&pageSize={page_size}` | Read | Equipment matching a URL-encoded query condition (e.g. serialNumber='...') |
| `GetEquipment` | `cmms/sapfsm/equipment/get` | `GET /api/data/v4/Equipment/{id}?dtos=Equipment.24` | Read | One equipment by cloud id (read lastChanged before a PATCH) |
| `GetEquipmentByExternalId` | `cmms/sapfsm/equipment/get-by-external-id` | `GET /api/data/v4/Equipment/externalId/{external_id}?dtos=Equipment.24` | Read | One equipment by externalId (usually the S/4HANA or ERP equipment number) |
| `UpdateEquipment` | `cmms/sapfsm/equipment/update` | `PATCH /api/data/v4/Equipment/{id}?dtos=Equipment.24&forceUpdate={force_update}` | Write | Patch equipment with machine data (remarks, status, UDF values). force\_update true skips the lastChanged lock |
| `UpsertEquipmentByExternalId` | `cmms/sapfsm/equipment/upsert` | `PATCH /api/data/v4/Equipment/externalId/{external_id}?dtos=Equipment.24` | Write | Patch equipment by externalId, e.g. a run-hours UDF referenced by its UDF meta externalId |
| `Query` | `cmms/sapfsm/query/run` | `POST /api/query/v1?dtos={dtos}&page={page}&pageSize={page_size}` | Read | Read-only CoreSQL query (POST with \{"query": ...}); dtos lists every DTO used, separated by ; |
| `CreateServiceCallWithActivities` | `cmms/sapfsm/service-call-tree/create` | `POST /service-management/api/v2/composite-tree/service-calls` | Write | Service Management API composite tree: create a service call and its activities in one request |
| `CancelServiceCall` | `cmms/sapfsm/service-call/cancel` | `POST /service-management/api/v2/servicecalls/{id}/actions/cancel` | Write | Business action: cancel a service call (not a delete) |
| `CompleteServiceCall` | `cmms/sapfsm/service-call/technically-complete` | `POST /service-management/api/v2/servicecalls/{id}/actions/technically-complete` | Write | Business action: mark a service call technically complete |
| `ReleaseActivity` | `cmms/sapfsm/activity/release` | `POST /service-management/api/v2/activities/{id}/actions/release` | Write | Business action: release a planned activity to the technician |
| `CloseActivity` | `cmms/sapfsm/activity/close` | `POST /service-management/api/v2/activities/{id}/actions/close` | Write | Business action: close an activity |
| `CancelActivity` | `cmms/sapfsm/activity/cancel` | `POST /service-management/api/v2/activities/{id}/actions/cancel` | Write | Business action: cancel an activity (not a delete) |

Every reply is published on the event topic plus `/response`. Data API replies wrap objects as `{"data": [{"serviceCall": {...}}]}` (lower-case DTO name).

## Prerequisites

* An SAP FSM company and its **cluster**: `eu`, `de`, `us` or `au` (China uses `cn.fsm.sapcloud.cn`). Change `BASE_ADDRESS` to `https://<cluster>.fsm.cloud.sap`. The older `coresuite.com` / `coresystems.net` hosts are being migrated to `fsm.cloud.sap`.
* An **OAuth client** created in Account Admin (client id + secret) with a permission group that can read and write service calls, activities and equipment and run the Service Management actions.
* The numeric **account id** and **company id** (Account Admin).
* Outbound HTTPS from the broker to the cluster host.
* For Business Rule webhooks only: a public HTTPS URL that forwards to the broker's port `9012`.

## Authentication

> [!WARNING]
>
> The client secret and every access token act with the client's permission group. Store `base64(client_id:client_secret)` in the Hub secret `SAP_FSM_BASIC_AUTH` (and the ids in `SAP_FSM_ACCOUNT_ID` / `SAP_FSM_COMPANY_ID`), read them with `GET SECRET`, and never put them or a token in a connector file.

`GetToken` posts `grant_type=client_credentials` to `/api/oauth2/v2/token` with HTTP Basic:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic": "<base64 of client_id:client_secret (Hub secret SAP_FSM_BASIC_AUTH)>",
  "form": "grant_type=client_credentials"
}
```

The reply carries `access_token`, `token_type` and `expires_in`. Every other event sends `Authorization: Bearer {value.json.access_token}`, `X-Account-ID` and `X-Company-ID` from the payload, and the fixed `X-Client-ID: custom-coreflux-broker` / `X-Client-Version: 1.0` (SAP asks custom clients to use a `custom-` prefix). Call `GetToken` again before `expires_in` runs out.

Answers seen from the real hosts without valid credentials: a fake client returns `401 {"error":"unauthorized","error_description":"Bad credentials"}`, a Data API call without a token `401 INVALID_LOGIN`, and any call with a fake token `401 {"error":"invalid_token"}`.

## Payload conventions

Each payload carries the context and the event's own fields; the request body comes from `body`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "account_id": "<X-Account-ID>",
  "company_id": "<X-Company-ID>",
  "id": "<ServiceCall id>",
  "force_update": "false",
  "body": {
    "lastChanged": 1759737600000,
    "priority": "LOW",
    "remarks": "Alarm cleared (Coreflux)"
  }
}
```

* `id` is the 32-character FSM id; `external_id` is your id (alarm id, ERP equipment number). Both go into the path, so pass only values you trust.
* `query` is a URL-encoded Data API condition, for example `lastChanged%3E%3D1759737600000` (`lastChanged>=1759737600000`) for incremental polls.
* Updates use **optimistic locking**: send the current `lastChanged` from a GET, or set `force_update` to `"true"`.
* `PATCH .../externalId/<id>` creates the object when it does not exist yet (send all mandatory fields).
* Pages: default 20, `page_size` 1000 at most; replies carry `currentPage`, `lastPage`, `totalObjectCount`.
* DTO versions are pinned: `ServiceCall.27`, `Activity.43`, `Equipment.24`.

### Alarm to service call

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "account_id": "<X-Account-ID>",
  "company_id": "<X-Company-ID>",
  "body": {
    "subject": "Alarm TT-101 = 92.4 C on compressor C-7 (Coreflux)",
    "priority": "HIGH",
    "businessPartner": "<BusinessPartner id>",
    "equipments": [
      "<Equipment id>"
    ],
    "startDateTime": "2026-10-06T08:00:00Z",
    "dueDateTime": "2026-10-07T17:00:00Z",
    "typeCode": "<service call type code>",
    "statusCode": "<service call status code>",
    "originCode": "<origin code>",
    "remarks": "Opened by Coreflux broker"
  }
}
```

Then attach the job (`object` points to the service call):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "account_id": "<X-Account-ID>",
  "company_id": "<X-Company-ID>",
  "body": {
    "subject": "Inspect compressor C-7",
    "type": "ASSIGNMENT",
    "object": {
      "objectId": "<ServiceCall id>",
      "objectType": "SERVICECALL"
    },
    "businessPartner": "<BusinessPartner id>",
    "equipment": "<Equipment id>",
    "startDateTime": "2026-10-06T09:00:00Z",
    "endDateTime": "2026-10-06T10:00:00Z",
    "durationInMinutes": 60,
    "remarks": "Alarm TT-101 (Coreflux)"
  }
}
```

Or create both in one call with the Service Management API:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "account_id": "<X-Account-ID>",
  "company_id": "<X-Company-ID>",
  "body": {
    "subject": "Alarm TT-101 on compressor C-7 (Coreflux)",
    "priority": "HIGH",
    "businessPartner": {
      "id": "<BusinessPartner id>"
    },
    "activities": [
      {
        "subject": "Inspect compressor C-7",
        "durationInMinutes": 60
      }
    ]
  }
}
```

### Machine data on equipment

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "account_id": "<X-Account-ID>",
  "company_id": "<X-Company-ID>",
  "external_id": "<ERP equipment number>",
  "body": {
    "udfValues": [
      {
        "meta": {
          "externalId": "<UDF meta externalId, e.g. RUN_HOURS>"
        },
        "value": "1287.5"
      }
    ]
  }
}
```

`udfValues` reference a user-defined field you create for the equipment in FSM (here by its UDF meta `externalId`). `UpdateEquipment` patches standard fields such as `remarks` by FSM id.

### Query API

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "account_id": "<X-Account-ID>",
  "company_id": "<X-Company-ID>",
  "dtos": "ServiceCall.27;Equipment.24",
  "page": "1",
  "page_size": "100",
  "body": {
    "query": "SELECT sc.id, sc.code, sc.subject, sc.priority FROM ServiceCall sc WHERE sc.priority = 'HIGH'"
  }
}
```

`dtos` must list every DTO the CoreSQL statement uses, separated by `;`.

## Business Rule receiver

FSM has no webhook subscription API. Instead, a **Business Rule** (Admin > Company > Business Rules) with a **Webhook** action calls any URL with your headers and body when a service call, activity or other object is created or changed. Point it at:

| Event | Path | Publishes on |
| - | - | - |
| `NotifyServiceCalls` | `POST /sapfsm/notify/service-calls` | `cmms/sapfsm/service-call-notification/received` |
| `NotifyActivities` | `POST /sapfsm/notify/activities` | `cmms/sapfsm/activity-notification/received` |
| `NotifyEvents` | `POST /sapfsm/notify/events` | `cmms/sapfsm/notification/received` |

> [!WARNING]
>
> Deploying the receiver opens port `9012`. FSM calls out from the SAP cloud, so put a reverse proxy or tunnel with a public TLS certificate in front of it, allow SAP's FSM egress addresses and check a shared secret header there: the connector does not authenticate callers.

## Connector

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — SAP Field Service Management (SAP Field Service and Asset Management) (beta): get an
#   OAuth 2.0 token, create service calls from alarms (Data API v4 ServiceCall.27), upsert them by your own alarm id,
#   find / read / patch service calls, activities (Activity.43) and equipment (Equipment.24, e.g. run hours as a UDF),
#   run read-only CoreSQL queries (Query API v1), create a service call with activities in one call and run the
#   Service Management API v2 business actions (cancel / technically complete service calls, release / close / cancel
#   activities).
#   the Business Accelerator Hub specs need an SAP login). Credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-field-service-management
#
# Host: your cluster, https://YOUR_CLUSTER.fsm.cloud.sap with YOUR_CLUSTER = eu | de | us | au (China:
#   https://cn.fsm.sapcloud.cn). The older eu.coresuite.com / de.coresystems.net hosts are being migrated to
#   fsm.cloud.sap. Use the cluster_url your account shows in Account Admin.
# Auth: OAuth 2.0 client credentials. GetToken posts grant_type=client_credentials ({value.json.form}) to
#   /api/oauth2/v2/token with Authorization: Basic {value.json.basic} (base64 of client_id:client_secret; keep it
#   in the Hub secret SAP_FSM_BASIC_AUTH). Every other event sends Authorization: Bearer {value.json.access_token}
#   plus X-Account-ID {value.json.account_id} and X-Company-ID {value.json.company_id} (numeric, from Account Admin)
#   and X-Client-ID custom-coreflux-broker / X-Client-Version 1.0. Tokens expire (expires_in): call GetToken again.
#   Live (2026-10-06, eu): fake Basic -> 401 {"error":"unauthorized","error_description":"Bad credentials"};
#   Data API without a token -> 401 INVALID_LOGIN; fake Bearer -> 401 invalid_token.
# Objects: Data API v4 DTO versions pinned to the newest on the SAP Help Portal on 2026-10-06 (ServiceCall.27,
#   Activity.43, Equipment.24; SAP/fsm-sdk 4.0.1 still ships 26 / 39 / 23). Status, type, origin and priority codes
#   are company-configurable: read them from an existing service call first.
# Payload fields (control fields stay out of bodies; request bodies come from {value.json.body}):
#   access_token, account_id, company_id, id, external_id, query, page, page_size, force_update, dtos, basic, form, body
#   query is a URL-encoded Data API condition (lastChanged%3E%3D1759737600000 = lastChanged>=...). id / external_id
#   go into the path: pass FSM ids or external ids you trust, never raw user input.
#     CreateServiceCall    body = {"subject": "...", "priority": "HIGH", "businessPartner": "<id>", "equipments": ["<id>"]}
#     UpdateServiceCall    id = <ServiceCall id>, force_update = "false", body = {"lastChanged": <from GET>, "priority": "LOW"}
#     UpsertEquipmentByExternalId  external_id = <ERP equipment no>, body = {"udfValues": [{"meta": {"externalId": "RUN_HOURS"}, "value": "1287.5"}]}
#     Query                dtos = "ServiceCall.27", body = {"query": "SELECT sc.id, sc.subject FROM ServiceCall sc"}
# Errors: 401 (token), 403 (permission group), 404, 409 / CA-* codes (e.g. stale lastChanged); Data API pages are
#   limited to 1000 objects and 100,000 objects per pagination. Writes run the company's Business Rules and sync to ERP.
#

DEFINE CONNECTOR SapFsmApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_CLUSTER.fsm.cloud.sap"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Get an OAuth 2.0 access token (client credentials, HTTP Basic with the FSM OAuth client id:secret). Reply access_token, token_type, expires_in; send access_token on every other event
    ADD EVENT GetToken
        WITH SOURCE_TOPIC "cmms/sapfsm/token/create"
        WITH DESTINATION_TOPIC "cmms/sapfsm/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/oauth2/v2/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic}"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    # Service calls, paged (default 20 per page, keep pageSize at 1000 or less). Reply data[].serviceCall plus currentPage / lastPage
    ADD EVENT ListServiceCalls
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/list"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/ServiceCall?dtos=ServiceCall.27&page={value.json.page}&pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # Service calls matching a URL-encoded Data API query condition, e.g. lastChanged>=<epoch ms> for incremental polls
    ADD EVENT FindServiceCalls
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/find"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/find/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/ServiceCall?dtos=ServiceCall.27&query={value.json.query}&pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # One service call by cloud id
    ADD EVENT GetServiceCall
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/get"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/ServiceCall/{value.json.id}?dtos=ServiceCall.27"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # One service call by your externalId (e.g. the alarm id)
    ADD EVENT GetServiceCallByExternalId
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/get-by-external-id"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/get-by-external-id/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/ServiceCall/externalId/{value.json.external_id}?dtos=ServiceCall.27"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # WRITE: Create a service call from an alarm; reply 201 {data:[{serviceCall:{id, code, lastChanged...}}]}
    ADD EVENT CreateServiceCall
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/create"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data/v4/ServiceCall?dtos=ServiceCall.27"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Patch service call fields; send the current lastChanged (optimistic lock) or force_update true. Reply 201
    ADD EVENT UpdateServiceCall
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/update"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/data/v4/ServiceCall/{value.json.id}?dtos=ServiceCall.27&forceUpdate={value.json.force_update}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Create or update the service call keyed by your externalId (one service call per alarm id; creating needs all mandatory fields)
    ADD EVENT UpsertServiceCallByExternalId
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/upsert"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/upsert/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/data/v4/ServiceCall/externalId/{value.json.external_id}?dtos=ServiceCall.27"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Activities matching a URL-encoded Data API query condition
    ADD EVENT FindActivities
        WITH SOURCE_TOPIC "cmms/sapfsm/activity/find"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity/find/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/Activity?dtos=Activity.43&query={value.json.query}&pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # One activity by cloud id (status, executionStage, responsibles, object -> service call)
    ADD EVENT GetActivity
        WITH SOURCE_TOPIC "cmms/sapfsm/activity/get"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/Activity/{value.json.id}?dtos=Activity.43"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # WRITE: Create an activity under a service call (object = {objectId, objectType SERVICECALL})
    ADD EVENT CreateActivity
        WITH SOURCE_TOPIC "cmms/sapfsm/activity/create"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data/v4/Activity?dtos=Activity.43"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Patch activity fields (send lastChanged or force_update true). Use the Service Management actions to change planning state
    ADD EVENT UpdateActivity
        WITH SOURCE_TOPIC "cmms/sapfsm/activity/update"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/data/v4/Activity/{value.json.id}?dtos=Activity.43&forceUpdate={value.json.force_update}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Equipment matching a URL-encoded query condition (e.g. serialNumber='...')
    ADD EVENT FindEquipment
        WITH SOURCE_TOPIC "cmms/sapfsm/equipment/find"
        WITH DESTINATION_TOPIC "cmms/sapfsm/equipment/find/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/Equipment?dtos=Equipment.24&query={value.json.query}&pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # One equipment by cloud id (read lastChanged before a PATCH)
    ADD EVENT GetEquipment
        WITH SOURCE_TOPIC "cmms/sapfsm/equipment/get"
        WITH DESTINATION_TOPIC "cmms/sapfsm/equipment/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/Equipment/{value.json.id}?dtos=Equipment.24"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # One equipment by externalId (usually the S/4HANA or ERP equipment number)
    ADD EVENT GetEquipmentByExternalId
        WITH SOURCE_TOPIC "cmms/sapfsm/equipment/get-by-external-id"
        WITH DESTINATION_TOPIC "cmms/sapfsm/equipment/get-by-external-id/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data/v4/Equipment/externalId/{value.json.external_id}?dtos=Equipment.24"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
    # WRITE: Patch equipment with machine data (remarks, status, UDF values). force_update true skips the lastChanged lock
    ADD EVENT UpdateEquipment
        WITH SOURCE_TOPIC "cmms/sapfsm/equipment/update"
        WITH DESTINATION_TOPIC "cmms/sapfsm/equipment/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/data/v4/Equipment/{value.json.id}?dtos=Equipment.24&forceUpdate={value.json.force_update}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Patch equipment by externalId, e.g. a run-hours UDF referenced by its UDF meta externalId
    ADD EVENT UpsertEquipmentByExternalId
        WITH SOURCE_TOPIC "cmms/sapfsm/equipment/upsert"
        WITH DESTINATION_TOPIC "cmms/sapfsm/equipment/upsert/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/data/v4/Equipment/externalId/{value.json.external_id}?dtos=Equipment.24"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Read-only CoreSQL query (POST with {"query": ...}); dtos lists every DTO used, separated by ;
    ADD EVENT Query
        WITH SOURCE_TOPIC "cmms/sapfsm/query/run"
        WITH DESTINATION_TOPIC "cmms/sapfsm/query/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/query/v1?dtos={value.json.dtos}&page={value.json.page}&pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Service Management API composite tree: create a service call and its activities in one request
    ADD EVENT CreateServiceCallWithActivities
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call-tree/create"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call-tree/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/service-management/api/v2/composite-tree/service-calls"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Business action: cancel a service call (not a delete)
    ADD EVENT CancelServiceCall
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/cancel"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/cancel/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/service-management/api/v2/servicecalls/{value.json.id}/actions/cancel"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Business action: mark a service call technically complete
    ADD EVENT CompleteServiceCall
        WITH SOURCE_TOPIC "cmms/sapfsm/service-call/technically-complete"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call/technically-complete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/service-management/api/v2/servicecalls/{value.json.id}/actions/technically-complete"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Business action: release a planned activity to the technician
    ADD EVENT ReleaseActivity
        WITH SOURCE_TOPIC "cmms/sapfsm/activity/release"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity/release/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/service-management/api/v2/activities/{value.json.id}/actions/release"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Business action: close an activity
    ADD EVENT CloseActivity
        WITH SOURCE_TOPIC "cmms/sapfsm/activity/close"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity/close/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/service-management/api/v2/activities/{value.json.id}/actions/close"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Business action: cancel an activity (not a delete)
    ADD EVENT CancelActivity
        WITH SOURCE_TOPIC "cmms/sapfsm/activity/cancel"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity/cancel/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/service-management/api/v2/activities/{value.json.id}/actions/cancel"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "X-Account-ID" "{value.json.account_id}"
            ADD "X-Company-ID" "{value.json.company_id}"
            ADD "X-Client-ID" "custom-coreflux-broker"
            ADD "X-Client-Version" "1.0"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# SAP FSM Business Rule receiver — REST_API route (server mode, beta, companion of SapFieldServiceManagementRestApi.lot)
#   Receives the HTTP calls that an SAP Field Service Management Business Rule makes with its 'Webhook' action
#   (Admin > Company > Business Rules: trigger on create / update of a ServiceCall, Activity, Equipment ..., action
#   Webhook, method POST, your URL, header + JSON body you define) and publishes the body on MQTT, so changes made
#   in FSM reach the broker without polling. Opt-in: deploying it opens an HTTP port.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-field-service-management
#
# FSM calls out from the SAP cloud: put a reverse proxy or tunnel with a public TLS certificate in front of
#   SERVER_PORT, allow the SAP FSM cloud egress addresses ('Incoming firewall configuration from SAP Field Service
#   Cloud') and check a shared secret header there: this route does not authenticate callers. The body is
#   whatever your Business Rule sends (e.g. ${serviceCall} variables); treat it as JSON you defined.

DEFINE CONNECTOR SapFsmBusinessRuleReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9012'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Business Rule Webhook action (POST https://<public host>/sapfsm/notify/service-calls) when a service call is created or changes
    ADD EVENT NotifyServiceCalls
        WITH ENDPOINT "/sapfsm/notify/service-calls"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/sapfsm/service-call-notification/received"
    # Same for activities (assignment, release, checkout, close)
    ADD EVENT NotifyActivities
        WITH ENDPOINT "/sapfsm/notify/activities"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/sapfsm/activity-notification/received"
    # Any other Business Rule webhook body (equipment, checklists). Filter on the body in a LoT action
    ADD EVENT NotifyEvents
        WITH ENDPOINT "/sapfsm/notify/events"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/sapfsm/notification/received"
```

## Example actions

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the SapFsmApi route (docs page). Not part of the route template.
# Secrets: SAP_FSM_BASIC_AUTH (base64 of <OAuth client id>:<client secret>, from Account Admin > Clients),
#   SAP_FSM_ACCOUNT_ID and SAP_FSM_COMPANY_ID (numeric ids from Account Admin). The access token is kept on the
#   internal topic internal/sapfsm/access_token. Replace the <...> placeholders (business partner, equipment ids).

DEFINE ACTION SapFsmGetToken
ON EVERY 30 MINUTES DO
    SET "basic" WITH GET SECRET "SAP_FSM_BASIC_AUTH"
    PUBLISH TOPIC "cmms/sapfsm/token/create" WITH { "basic": {basic}, "form": "grant_type=client_credentials" }

DEFINE ACTION SapFsmKeepToken
ON TOPIC "cmms/sapfsm/token/create/response" DO
    SET "tok" WITH (GET JSON "access_token" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/sapfsm/access_token" WITH {tok}

DEFINE ACTION SapFsmServiceCallFromAlarm
ON TOPIC "porto/line1/compressor/alarm/raised" DO
    SET "tok" WITH GET TOPIC "internal/sapfsm/access_token" AS STRING
    SET "acc" WITH GET SECRET "SAP_FSM_ACCOUNT_ID"
    SET "comp" WITH GET SECRET "SAP_FSM_COMPANY_ID"
    SET "alarm" WITH (GET JSON "alarm" IN PAYLOAD AS STRING)
    SET "value" WITH (GET JSON "value" IN PAYLOAD AS STRING)
    SET "subj" WITH "Coreflux alarm " + {alarm} + " (value " + {value} + ")"
    PUBLISH TOPIC "cmms/sapfsm/service-call/create" WITH { "access_token": {tok}, "account_id": {acc}, "company_id": {comp}, "body": { "subject": {subj}, "priority": "HIGH", "businessPartner": "<BusinessPartner id>", "equipments": ["<Equipment id>"] } }

DEFINE ACTION SapFsmRunHoursToEquipment
ON TOPIC "porto/line1/press01/run-hours" DO
    SET "tok" WITH GET TOPIC "internal/sapfsm/access_token" AS STRING
    SET "acc" WITH GET SECRET "SAP_FSM_ACCOUNT_ID"
    SET "comp" WITH GET SECRET "SAP_FSM_COMPANY_ID"
    SET "hours" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "cmms/sapfsm/equipment/upsert" WITH { "access_token": {tok}, "account_id": {acc}, "company_id": {comp}, "external_id": "<ERP equipment number>", "body": { "udfValues": [ { "meta": { "externalId": "RUN_HOURS" }, "value": {hours} } ] } }

DEFINE ACTION SapFsmPollChangedServiceCalls
ON EVERY 15 MINUTES DO
    SET "tok" WITH GET TOPIC "internal/sapfsm/access_token" AS STRING
    SET "acc" WITH GET SECRET "SAP_FSM_ACCOUNT_ID"
    SET "comp" WITH GET SECRET "SAP_FSM_COMPANY_ID"
    PUBLISH TOPIC "cmms/sapfsm/query/run" WITH { "access_token": {tok}, "account_id": {acc}, "company_id": {comp}, "dtos": "ServiceCall.27", "page": "1", "page_size": "100", "body": { "query": "SELECT sc.id, sc.code, sc.subject, sc.priority, sc.statusName FROM ServiceCall sc WHERE sc.priority = 'HIGH'" } }
```

## Notes

* Writes run the company's Business Rules and, if connected, sync to SAP S/4HANA or ECC.
* Status, type, origin and priority codes and UDFs are company-specific: read an existing service call first and copy its codes.
* SAP's own `fsm-sdk` 4.0.1 still pins `ServiceCall.26`, `Activity.39`, `Equipment.23`. If your company rejects the newer versions, change the `dtos=` values in the endpoints.
* The Service API pages also list `X-Account-Name` and `X-Company-Name`. The connector sends only the ids, like SAP's SDK; add the name headers if a business action answers `400`.
* For Service Management calls the SAP Help pages use `/service-management/api/v2/...`; the SDK calls `/service-management/v2/...`. Both reach the API gateway; the connector uses the documented form.

## Not covered

Deletes, full PUT replacement, the Data API batch endpoint, attachments, planning actions that need technician or team ids (plan, replan, reschedule, unassign), bulk actions, approvals and other DTOs (business partners, persons, service assignments, time efforts, materials, checklists). All use the same headers; add events in the same style.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [SAP FSM Data API v4](https://help.sap.com/docs/SAP_FIELD_SERVICE_MANAGEMENT/fsm_data_api/data-api-introduction.html)
* [SAP FSM Service API](https://help.sap.com/docs/SAP_FIELD_SERVICE_MANAGEMENT/fsm_service_api/supported-requests.html)
* [SAP/fsm-sdk on GitHub](https://github.com/SAP/fsm-sdk)


# SAP S/4HANA Cloud
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-s4hana-cloud

Client-mode REST API connector for a curated S/4HANA Cloud OData slice: production orders, confirmations, goods movements, and maintenance notifications

Technical Preview

## Overview

A client-mode connector for a **curated manufacturing and plant-maintenance** slice of [SAP S/4HANA Cloud](https://api.sap.com/products/SAPS4HANACloud/apis/packages) OData APIs on the Business Accelerator Hub:

| Catalog connector event | OData service | Entity set |
| - | - | - |
| GET production orders by plant | `API_PRODUCTION_ORDER_2_SRV` | `A_ProductionOrder_2` |
| POST order confirmation (yield, scrap, time) | `API_PROD_ORDER_CONFIRMATION_2_SRV` | `ProdnOrdConf2` |
| POST goods movement | `API_MATERIAL_DOCUMENT_SRV` | `A_MaterialDocumentHeader` |
| POST maintenance notification from alarm | `API_MAINTNOTIFICATION` | `MaintenanceNotification` |

`BASE_ADDRESS` is the tenant host root (`https://{tenant}-api.s4hana.cloud.sap`). Endpoints carry `/sap/opu/odata/sap/...`. Topics use `erp/sap-s4hana-cloud/<object>/<verb>`.

> [!NOTE]
>
> S/4HANA Cloud OData requires a real tenant and either a communication-user (Basic) or OAuth 2.0 client-credentials Bearer token. Mutating calls need an `X-CSRF-Token` (fetch with `Fetch` first).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — SAP S/4HANA Cloud (curated Manufacturing / PM slice)
# Generated from curated OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes
# Auth: OAuth 2.0 client credentials (Bearer {value.json.access_token}) OR Basic
#       communication user (WITH USERNAME / WITH PASSWORD GET SECRET). Never commit secrets.
# BASE_ADDRESS: https://{tenant}-api.s4hana.cloud.sap — replace YOUR_TENANT.
# OData mutating calls need CSRF: run Fetchcsrf first (X-CSRF-Token: Fetch), then pass
#   {value.json.csrf_token} on POST events. Keep session cookies if the broker exposes them.
# Accelerator Hub refs:
#   API_PRODUCTION_ORDER_2_SRV · API_PROD_ORDER_CONFIRMATION_2_SRV
#   API_MATERIAL_DOCUMENT_SRV · API_MAINTNOTIFICATION

DEFINE CONNECTOR SapS4hanaCloudRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_TENANT-api.s4hana.cloud.sap"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth option A (OAuth client credentials): obtain access_token upstream, pass as Bearer.
        # Auth option B (Basic communication user): uncomment and use Hub secrets:
        #   WITH USERNAME "YOUR_COMM_USER"
        #   WITH PASSWORD GET SECRET "SAP_S4_COMM_PASSWORD"
        # Prefer Hub secrets / GET SECRET — never commit real tokens or passwords.
    ADD EVENT Getproductionordersbyplant
        WITH SOURCE_TOPIC "erp/sap-s4hana-cloud/production-order/get"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-cloud/production-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2?$filter=ProductionPlant eq '{value.json.plant}'&$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getproductionorder
        WITH SOURCE_TOPIC "erp/sap-s4hana-cloud/production-order/get-by-id"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-cloud/production-order/get-by-id/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2('{value.json.ManufacturingOrder}')?$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Fetchcsrf
        WITH SOURCE_TOPIC "erp/sap-s4hana-cloud/csrf/fetch"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-cloud/csrf/fetch/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification?$top=1&$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-CSRF-Token" "Fetch"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createproductionorderconfirmation
        WITH SOURCE_TOPIC "erp/sap-s4hana-cloud/production-order-confirmation/create"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-cloud/production-order-confirmation/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sap/opu/odata/sap/API_PROD_ORDER_CONFIRMATION_2_SRV/ProdnOrdConf2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-CSRF-Token" "{value.json.csrf_token}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Creatematerialdocument
        WITH SOURCE_TOPIC "erp/sap-s4hana-cloud/material-document/create"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-cloud/material-document/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sap/opu/odata/sap/API_MATERIAL_DOCUMENT_SRV/A_MaterialDocumentHeader"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-CSRF-Token" "{value.json.csrf_token}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Createmaintenancenotification
        WITH SOURCE_TOPIC "erp/sap-s4hana-cloud/maintenance-notification/create"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-cloud/maintenance-notification/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-CSRF-Token" "{value.json.csrf_token}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getproductionordersbyplant | GET | `/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2?$filter=ProductionPlant eq '{plant}'` | `erp/sap-s4hana-cloud/production-order/get` | `erp/sap-s4hana-cloud/production-order/get/response` |
| Getproductionorder | GET | `/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2('{ManufacturingOrder}')` | `erp/sap-s4hana-cloud/production-order/get-by-id` | `erp/sap-s4hana-cloud/production-order/get-by-id/response` |
| Fetchcsrf | GET | `/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification` | `erp/sap-s4hana-cloud/csrf/fetch` | `erp/sap-s4hana-cloud/csrf/fetch/response` |
| Createproductionorderconfirmation | POST | `/sap/opu/odata/sap/API_PROD_ORDER_CONFIRMATION_2_SRV/ProdnOrdConf2` | `erp/sap-s4hana-cloud/production-order-confirmation/create` | `erp/sap-s4hana-cloud/production-order-confirmation/create/response` |
| Creatematerialdocument | POST | `/sap/opu/odata/sap/API_MATERIAL_DOCUMENT_SRV/A_MaterialDocumentHeader` | `erp/sap-s4hana-cloud/material-document/create` | `erp/sap-s4hana-cloud/material-document/create/response` |
| Createmaintenancenotification | POST | `/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification` | `erp/sap-s4hana-cloud/maintenance-notification/create` | `erp/sap-s4hana-cloud/maintenance-notification/create/response` |

## Auth

OAuth Bearer (client credentials access token):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Authorization" "Bearer {value.json.access_token}"
```

Or Basic communication user on config (Hub secret):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH USERNAME "YOUR_COMM_USER"
WITH PASSWORD GET SECRET "SAP_S4_COMM_PASSWORD"
```

CSRF on POST:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "X-CSRF-Token" "{value.json.csrf_token}"
```

**access\_token** `string` *required*

OAuth 2.0 access token from the S/4HANA Cloud / BTP token endpoint (client credentials). Prefer a Hub secret. Never commit the token.

**plant** `string` *required*

Production plant code for Getproductionordersbyplant (`ProductionPlant` OData filter).

**ManufacturingOrder** `string`

Production order key for Getproductionorder.

**csrf\_token** `string` *required*

Value from the `X-CSRF-Token` response header after Fetchcsrf. Required on all POST events.

High-level setup (no secrets in the template):

1. Create Communication Arrangements for the needed scenarios (e.g. production / confirmation, material document, maintenance `SAP_COM_0397`).
2. Create a communication user or OAuth client; obtain Basic credentials or an access token.
3. Set `BASE_ADDRESS` to `https://{tenant}-api.s4hana.cloud.sap`.
4. Fetch CSRF, then call GET/POST events with placeholders filled.

GET production orders by plant:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_S4_ACCESS_TOKEN", "plant": "1010"}
```

POST maintenance notification (connector body is `{payload}`; fetch CSRF first):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_S4_ACCESS_TOKEN",
  "csrf_token": "YOUR_CSRF_TOKEN",
  "NotificationType": "Y1",
  "NotificationText": "Alarm from Coreflux edge",
  "TechnicalObject": "EQUIPMENT_ID",
  "TechObjIsEquipOrFuncnlLoc": "EAMS_EQUIP",
  "MaintPriority": "2",
  "MaintenanceObjectIsDown": true
}
```

## Try it

1. Replace `YOUR_TENANT` in `BASE_ADDRESS` and add the connector on your broker.
2. Publish token + plant JSON to `erp/sap-s4hana-cloud/production-order/get`.
3. Subscribe to `erp/sap-s4hana-cloud/production-order/get/response`.
4. For POSTs: call `erp/sap-s4hana-cloud/csrf/fetch` first, then publish with `csrf_token` and body fields.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)
* [SAP Business Accelerator Hub — S/4HANA Cloud](https://api.sap.com/products/SAPS4HANACloud/apis/packages)


# SAP S/4HANA on-premise / ECC (Gateway)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-s4hana-onprem

Client-mode REST API connector for SAP Gateway OData: production orders, confirmations, goods movements, maintenance notifications, work centers, and PM orders

Technical Preview

## Overview

A client-mode connector for a **curated manufacturing and plant-maintenance** slice of [SAP S/4HANA on-premise / ECC](https://api.sap.com/products/SAPS4HANA/apis/all) OData APIs exposed through [SAP Gateway](https://help.sap.com/docs/SAP_GATEWAY):

| Catalog connector event | OData service | Entity set |
| - | - | - |
| GET production orders by plant | `API_PRODUCTION_ORDER_2_SRV` | `A_ProductionOrder_2` |
| POST order confirmation (yield, scrap, time) | `API_PROD_ORDER_CONFIRMATION_2_SRV` | `ProdnOrdConf2` |
| POST goods movement | `API_MATERIAL_DOCUMENT_SRV` | `A_MaterialDocumentHeader` |
| POST maintenance notification from alarm | `API_MAINTNOTIFICATION` | `MaintenanceNotification` |
| GET work centers | `API_WORK_CENTERS` | `A_WorkCenters` |
| GET PM orders | `API_MAINTENANCEORDER` | `MaintenanceOrder` |

`BASE_ADDRESS` is the Gateway host root (`https://{host}:{port}`). Endpoints carry `/sap/opu/odata/sap/...`. Topics use `erp/sap-s4hana-onprem/<object>/<verb>`.

> [!NOTE]
>
> Service naming: Hub/SDK use `API_WORK_CENTERS` (not `API_WORK_CENTER_SRV`) and `API_MAINTENANCEORDER` (not `API_MAINTENANCEORDER_2_SRV`). Activate services in `/IWFND/MAINT_SERVICE` and confirm entity sets with `$metadata` on your host. Older ECC may expose classic PP/PM Gateway names — adjust after metadata check. Mutating OData calls need `X-CSRF-Token`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — SAP S/4HANA on-premise / ECC (SAP Gateway)
# Generated from curated OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes
# Auth: Basic (WITH USERNAME / WITH PASSWORD GET SECRET "SAP_S4_ONPREM_PASSWORD") OR
#       OAuth 2.0 / SAML bearer (Bearer {value.json.access_token}). X.509 at TLS layer.
# BASE_ADDRESS: https://YOUR_HOST:YOUR_PORT — Gateway root; endpoints keep /sap/opu/odata/sap/...
# OData mutating calls need CSRF: run Fetchcsrf first (X-CSRF-Token: Fetch), then pass
#   {value.json.csrf_token} on POST events.

DEFINE CONNECTOR SapS4hanaOnpremRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_HOST:YOUR_PORT"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth option A (OAuth / SAML bearer): obtain access_token upstream, pass as Bearer on events.
        # Auth option B (Basic Gateway user): uncomment and use Hub secrets:
        #   WITH USERNAME "YOUR_GATEWAY_USER"
        #   WITH PASSWORD GET SECRET "SAP_S4_ONPREM_PASSWORD"
        # Prefer Hub secrets / GET SECRET — never commit real tokens or passwords.
        # Auth option C (X.509): configure client cert at TLS / broker level (not in LoT headers).
    ADD EVENT Getproductionordersbyplant
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/production-order/get"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/production-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2?$filter=ProductionPlant eq '{value.json.plant}'&$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getproductionorder
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/production-order/get-by-id"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/production-order/get-by-id/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2('{value.json.ManufacturingOrder}')?$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getworkcenters
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/work-center/get"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/work-center/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_WORK_CENTERS/A_WorkCenters?$filter=Plant eq '{value.json.plant}'&$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Getpmorders
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/pm-order/get"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/pm-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_MAINTENANCEORDER/MaintenanceOrder?$filter=MaintenancePlanningPlant eq '{value.json.plant}'&$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Fetchcsrf
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/csrf/fetch"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/csrf/fetch/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification?$top=1&$format=json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-CSRF-Token" "Fetch"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createproductionorderconfirmation
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/production-order-confirmation/create"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/production-order-confirmation/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sap/opu/odata/sap/API_PROD_ORDER_CONFIRMATION_2_SRV/ProdnOrdConf2"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-CSRF-Token" "{value.json.csrf_token}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Creatematerialdocument
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/material-document/create"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/material-document/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sap/opu/odata/sap/API_MATERIAL_DOCUMENT_SRV/A_MaterialDocumentHeader"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-CSRF-Token" "{value.json.csrf_token}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Createmaintenancenotification
        WITH SOURCE_TOPIC "erp/sap-s4hana-onprem/maintenance-notification/create"
        WITH DESTINATION_TOPIC "erp/sap-s4hana-onprem/maintenance-notification/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-CSRF-Token" "{value.json.csrf_token}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"

```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getproductionordersbyplant | GET | `/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2?$filter=ProductionPlant eq '{plant}'` | `erp/sap-s4hana-onprem/production-order/get` | `erp/sap-s4hana-onprem/production-order/get/response` |
| Getproductionorder | GET | `/sap/opu/odata/sap/API_PRODUCTION_ORDER_2_SRV/A_ProductionOrder_2('{ManufacturingOrder}')` | `erp/sap-s4hana-onprem/production-order/get-by-id` | `erp/sap-s4hana-onprem/production-order/get-by-id/response` |
| Getworkcenters | GET | `/sap/opu/odata/sap/API_WORK_CENTERS/A_WorkCenters?$filter=Plant eq '{plant}'` | `erp/sap-s4hana-onprem/work-center/get` | `erp/sap-s4hana-onprem/work-center/get/response` |
| Getpmorders | GET | `/sap/opu/odata/sap/API_MAINTENANCEORDER/MaintenanceOrder?$filter=MaintenancePlanningPlant eq '{plant}'` | `erp/sap-s4hana-onprem/pm-order/get` | `erp/sap-s4hana-onprem/pm-order/get/response` |
| Fetchcsrf | GET | `/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification` | `erp/sap-s4hana-onprem/csrf/fetch` | `erp/sap-s4hana-onprem/csrf/fetch/response` |
| Createproductionorderconfirmation | POST | `/sap/opu/odata/sap/API_PROD_ORDER_CONFIRMATION_2_SRV/ProdnOrdConf2` | `erp/sap-s4hana-onprem/production-order-confirmation/create` | `erp/sap-s4hana-onprem/production-order-confirmation/create/response` |
| Creatematerialdocument | POST | `/sap/opu/odata/sap/API_MATERIAL_DOCUMENT_SRV/A_MaterialDocumentHeader` | `erp/sap-s4hana-onprem/material-document/create` | `erp/sap-s4hana-onprem/material-document/create/response` |
| Createmaintenancenotification | POST | `/sap/opu/odata/sap/API_MAINTNOTIFICATION/MaintenanceNotification` | `erp/sap-s4hana-onprem/maintenance-notification/create` | `erp/sap-s4hana-onprem/maintenance-notification/create/response` |

## Auth

OAuth / SAML Bearer access token:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Authorization" "Bearer {value.json.access_token}"
```

Or Basic Gateway user on config (Hub secret):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
WITH USERNAME "YOUR_GATEWAY_USER"
WITH PASSWORD GET SECRET "SAP_S4_ONPREM_PASSWORD"
```

CSRF on POST:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "X-CSRF-Token" "{value.json.csrf_token}"
```

**access\_token** `string`

OAuth 2.0 / SAML bearer access token for Gateway. Prefer a Hub secret. Never commit the token. Omit when using Basic on `REST_API_CONFIG`.

**plant** `string` *required*

Plant code for Getproductionordersbyplant, Getworkcenters, and Getpmorders filters.

**ManufacturingOrder** `string`

Production order key for Getproductionorder.

**csrf\_token** `string` *required*

Value from the `X-CSRF-Token` response header after Fetchcsrf. Required on all POST events.

High-level setup (no secrets in the template):

1. Activate the OData services in `/IWFND/MAINT_SERVICE` (and confirm with Gateway Client `/IWFND/GW_CLIENT`).
2. Create a Gateway user (Basic), OAuth/SAML bearer client, or X.509 client cert.
3. Set `BASE_ADDRESS` to `https://{host}:{port}`.
4. Fetch CSRF, then call GET/POST events with placeholders filled.

GET production orders by plant:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_GATEWAY_ACCESS_TOKEN", "plant": "1010"}
```

GET work centers / PM orders use the same shape (`plant`).

POST maintenance notification (connector body is `{payload}`; fetch CSRF first):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_GATEWAY_ACCESS_TOKEN",
  "csrf_token": "YOUR_CSRF_TOKEN",
  "NotificationType": "Y1",
  "NotificationText": "Alarm from Coreflux edge",
  "TechnicalObject": "EQUIPMENT_ID",
  "TechObjIsEquipOrFuncnlLoc": "EAMS_EQUIP",
  "MaintPriority": "2",
  "MaintenanceObjectIsDown": true
}
```

## Try it

1. Replace `YOUR_HOST` / `YOUR_PORT` in `BASE_ADDRESS` and add the connector on your broker.
2. Publish token + plant JSON to `erp/sap-s4hana-onprem/production-order/get` (and optionally `work-center/get` / `pm-order/get`).
3. Subscribe to the matching `/response` topics.
4. For POSTs: call `erp/sap-s4hana-onprem/csrf/fetch` first, then publish with `csrf_token` and body fields.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)
* [SAP S/4HANA Cloud](/latest/lot-language/routes/rest-api-apps/sap-s4hana-cloud)
* [SAP Gateway Help](https://help.sap.com/docs/SAP_GATEWAY)
* [SAP Business Accelerator Hub — S/4HANA](https://api.sap.com/products/SAPS4HANA/apis/all)


# SAP SuccessFactors
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sap-successfactors

LoT connector for SAP SuccessFactors: send clock-in and clock-out punches, record absences, and read users, jobs, departments and time account balances

Technical Preview

## Overview

A client-mode connector for [SAP SuccessFactors](https://help.sap.com/docs/successfactors-platform/sap-successfactors-api-reference-guide-odata-v2/about-sap-successfactors-odata-apis-v2) HXM: the OData v2 API (User Management, Employee Central employment and personal information, Foundation Objects, Time Off) and the Time Tracking Clock In Clock Out APIs. Use it to connect the shop floor to HR:

* Badge readers and gate terminals publish clock-in / clock-out punches on MQTT, and the connector sends them to Clock In Clock Out.
* A kiosk or HMI books or cancels an absence, or shows the remaining vacation balance.
* Line planning and andon boards read who is assigned to a plant and department, with standard hours (EmpJob with `asOfDate`).

The connector `SapSuccessFactorsRestApi` in `SapSuccessfactorsRestApi.lot` has 28 events (23 GET, 5 POST). 3 are writes: `EmployeeTimeCreate`, `Upsert`, `TimeEventsCreate`. There are no DELETE, PUT or PATCH events.

Set `BASE_ADDRESS` to the API server of your data center, with no trailing slash and no `/odata/v2`, for example `https://api55.sapsf.eu` or `https://api4.successfactors.com` (SAP KBA 2215682 lists all API servers). Topics use `finance/sap-successfactors/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

## Setup

1. Create or choose an API user with role-based permissions for the entities the broker uses (for example User, Employee Central job information, Time Off) and **Employee Central API** / **SFAPI** access. Every call runs with this user's permissions.
2. In **Admin Center > Manage OAuth2 Client Applications**, register a client: application name and URL, **Bind to Users** with the API user, and **Generate X.509 Certificate**. Download the certificate (it holds the private key) and save the **API Key** (the `client_id`).
3. For Clock In Clock Out punches, register a second client bound to the technical user `TECHNICAL_USER_CICOTERMINAL_9D3F8AC1`. SuccessFactors accepts punches only with that user's token (SAP KBA 3206348).
4. Note your **company ID**. Keep `SF_COMPANY_ID`, `SF_CLIENT_ID`, the private key or assertions, and the current token in broker secrets and inject them with `GET SECRET`.

## Authentication

SuccessFactors uses the OAuth 2.0 SAML 2.0 bearer assertion grant:

1. **Get a SAML assertion** for the API user, signed with the client's private key. Generate it outside the broker (for example with SAP's assertion generator or an integration platform), or use `SamlAssertion` (`POST /oauth/idp` with `client_id`, `user_id`, `token_url`, `private_key`). SAP has deprecated `/oauth/idp` because the private key travels in the call (KBA 3239495); it still answers today, but prefer generating the assertion yourself.
2. **Get a token** with `OAuthToken`: `POST /oauth/token` with `company_id`, `client_id` and `assertion` (the grant type `urn:ietf:params:oauth:grant-type:saml2-bearer` is fixed in the template). The reply has `access_token`, `token_type` `Bearer` and `expires_in`.
3. Every other event sends `Authorization: Bearer <access_token>` from the payload. `TokenValidate` checks a token.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"company_id": "<SF_COMPANY_ID>", "client_id": "<SF_CLIENT_ID>", "assertion": "<URL-encoded SAML assertion>"}
```

The token events send a form body, so every value must be URL-encoded. Assertions and private keys are Base64 and contain `+`, `/` and `=`: send them as `%2B`, `%2F` and `%3D`, or the server rejects the assertion.

> [!WARNING]
>
> HTTP Basic authentication (`user@companyId:password`) for SuccessFactors APIs reached end of maintenance on 2 June 2025 and is deleted on 13 November 2026 (SAP KBA 3472405), so this template does not use it. If you already use OpenID Connect through SAP Cloud Identity Services, get the token from your Identity Services tenant and send it as `access_token` the same way. Never retain topics that carry an assertion, private key or token, and restrict `finance/sap-successfactors/auth/#` with ACLs.

## Events

| Event | Request | Source topic | Notes |
| - | - | - | - |
| SamlAssertion | `POST /oauth/idp` | `finance/sap-successfactors/auth/assertion` | Generate a SAML 2.0 assertion on the server (deprecated by SAP, KBA 3239495: the X.509 private key travels in the call; prefer signing the assertion yourself). |
| OAuthToken | `POST /oauth/token` | `finance/sap-successfactors/auth/token` | Exchange a SAML assertion for an access token (grant\_type urn:ietf:params:oauth:grant-type:saml2-bearer, fixed). |
| TokenValidate | `GET /oauth/validate` | `finance/sap-successfactors/auth/validate` | Check that access\_token is still valid (401 when it is malformed or expired). Use before a burst of calls or after a 401. |
| Metadata | `GET /odata/v2/{entity_set}/$metadata` | `finance/sap-successfactors/metadata/get` | OData v2 metadata (EDMX XML) of one entity set, for example User, EmpJob or EmployeeTime, including custom fields of your instance. Accept application/xml. |
| EntityQuery | `GET /odata/v2/{entity_set}?{query}` | `finance/sap-successfactors/odata/query` | Generic read of any entity set your API user may read (entity\_set e.g. PerEmail, FOCostCenter, WorkSchedule, Holiday). |
| UsersList | `GET /odata/v2/User?{query}` | `finance/sap-successfactors/users/list` | List users (catalog event). |
| UserGet | `GET /odata/v2/User('{user_id}')?{query}` | `finance/sap-successfactors/users/get` | One user by userId (catalog event), for a badge-to-person lookup. |
| PerPersonList | `GET /odata/v2/PerPerson?{query}` | `finance/sap-successfactors/persons/list` | List persons (biographical information). |
| PerPersonGet | `GET /odata/v2/PerPerson('{person_id}')?{query}` | `finance/sap-successfactors/persons/get` | One person by personIdExternal. |
| EmpEmploymentList | `GET /odata/v2/EmpEmployment?{query}` | `finance/sap-successfactors/employments/list` | Employments (hire, termination, assignment). |
| EmpJobList | `GET /odata/v2/EmpJob?{query}` | `finance/sap-successfactors/jobs/list` | Job information (catalog event): department, location, manager, standard hours, time recording variant. Effective dated: add asOfDate=YYYY-MM-DD or fromDate / toDate. |
| EmpJobGet | `GET /odata/v2/EmpJob(seqNumber={seq_number}L,startDate=datetime'{start_date}',userId='{user_id}')?{query}` | `finance/sap-successfactors/jobs/get` | One job information record by its key: seq\_number (number), start\_date (YYYY-MM-DDT00:00:00), user\_id. |
| FODepartmentList | `GET /odata/v2/FODepartment?{query}` | `finance/sap-successfactors/departments/list` | Departments (Foundation Object, effective dated). |
| FOLocationList | `GET /odata/v2/FOLocation?{query}` | `finance/sap-successfactors/locations/list` | Locations, such as plants and sites (Foundation Object, effective dated). |
| EmployeeTimeList | `GET /odata/v2/EmployeeTime?{query}` | `finance/sap-successfactors/employee-time/list` | Absences and other employee time records. |
| EmployeeTimeGet | `GET /odata/v2/EmployeeTime('{external_code}')?{query}` | `finance/sap-successfactors/employee-time/get` | One EmployeeTime by externalCode, for example to read approvalStatus after a create. |
| EmployeeTimeCreate | `POST /odata/v2/EmployeeTime` | `finance/sap-successfactors/employee-time/create` | Write. Create an EmployeeTime record, such as an absence (catalog event POST EmployeeTime). |
| Upsert | `POST /odata/v2/upsert?{query}` | `finance/sap-successfactors/odata/upsert` | Write. OData v2 upsert: create or update one record (or an array) of any upsertable entity set, named in \_\_metadata.uri. |
| TimeTypeList | `GET /odata/v2/TimeType?{query}` | `finance/sap-successfactors/time-types/list` | Time types (vacation, sickness, shift types) with their codes for EmployeeTime. |
| AvailableTimeTypeList | `GET /odata/v2/AvailableTimeType?{query}` | `finance/sap-successfactors/time-types/available` | Time types available to employees through their time profile. |
| TimeAccountList | `GET /odata/v2/TimeAccount?{query}` | `finance/sap-successfactors/time-accounts/list` | Time accounts (vacation entitlement, overtime) per user. |
| TimeAccountDetailList | `GET /odata/v2/TimeAccountDetail?{query}` | `finance/sap-successfactors/time-accounts/details` | Bookings on time accounts (accruals, absences, payouts). |
| EmpTimeAccountBalanceList | `GET /odata/v2/EmpTimeAccountBalance?{query}` | `finance/sap-successfactors/time-accounts/balances` | Current balance per time account, for a kiosk or HMI that shows remaining vacation. |
| EmployeeTimeCalendarList | `GET /odata/v2/EmployeeTimeCalendar?{query}` | `finance/sap-successfactors/employee-time/calendar` | Day-by-day calendar entries of employee time records. |
| TimeEventsCreate | `POST /rest/timemanagement/timeeventprocessing/v1/TimeEvents` | `finance/sap-successfactors/clock/events/create` | Write. Send clock-in / clock-out punches from a terminal to Clock In Clock Out (catalog clock events). The token must belong to an OAuth client bound to TECHNICAL\_USER\_CICOTERMINAL\_9D3F8AC1. |
| TimeEventsExport | `GET /odatav4/timemanagement/timeeventprocessing/clockinclockout/v1/timeevents?{query}` | `finance/sap-successfactors/clock/events/list` | Export clock events (OData v4, up to 1000 per call; needs the export permission, else an empty list). |
| ClockGroupsList | `GET /odatav4/timemanagement/timeeventprocessing/ClockInClockOutIntegration.svc/v1/ClockInClockOutGroups?{query}` | `finance/sap-successfactors/clock/groups/list` | Clock In Clock Out groups with their time event types (codes for typeCode). |
| ClockGroupGet | `GET /odatav4/timemanagement/timeeventprocessing/ClockInClockOutIntegration.svc/v1/ClockInClockOutGroups('{group_code}')?{query}` | `finance/sap-successfactors/clock/groups/get` | One Clock In Clock Out group by code. |

## Payloads

| Field | Used by | Content |
| - | - | - |
| `company_id`, `client_id`, `assertion` | `OAuthToken` | Company ID, API key of the OAuth client and the SAML assertion, URL-encoded |
| `client_id`, `user_id`, `token_url`, `private_key` | `SamlAssertion` | API key, API user (or `TECHNICAL_USER_CICOTERMINAL_9D3F8AC1`), `https%3A%2F%2F<api-server>%2Foauth%2Ftoken` and the private key, URL-encoded |
| `access_token` | every event except the two token events | Token from `OAuthToken` |
| `user_id`, `person_id`, `external_code`, `group_code` | `UserGet`, `PerPersonGet`, `EmployeeTimeGet`, `ClockGroupGet` | Key of the record |
| `seq_number`, `start_date`, `user_id` | `EmpJobGet` | EmpJob key: sequence number, start date `YYYY-MM-DDT00:00:00`, user ID |
| `entity_set` | `EntityQuery`, `Metadata` | Any OData v2 entity set, for example `PerEmail`, `FOCostCenter`, `EmployeeTime` |
| `query` | read events, `Upsert` | URL query string without `?`, or `""`, with spaces as `%20`, for example `$filter=userId%20eq%20'cgrant'&$top=50` |
| `body` | `EmployeeTimeCreate`, `Upsert`, `TimeEventsCreate` | JSON object (or array for `Upsert`); a JSON array of punches for `TimeEventsCreate` |

OData v2 query options: `$filter`, `$select`, `$expand`, `$orderby`, `$top`, `$skip`, `$format`, `$inlinecount`, and the SuccessFactors effective-dating options `asOfDate`, `fromDate` and `toDate` (`YYYY-MM-DD`). Dates in OData v2 JSON bodies use `/Date(<epoch milliseconds>)/`.

## Basic Syntax

An excerpt of the template (the full file has all 28 events and comments):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SapSuccessFactorsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_API_SERVER"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT OAuthToken
        WITH SOURCE_TOPIC "finance/sap-successfactors/auth/token"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/auth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/oauth/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "company_id={value.json.company_id}&client_id={value.json.client_id}&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2-bearer&assertion={value.json.assertion}"
    ADD EVENT EmpJobList
        WITH SOURCE_TOPIC "finance/sap-successfactors/jobs/list"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/jobs/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/odata/v2/EmpJob?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT EmployeeTimeCreate
        WITH SOURCE_TOPIC "finance/sap-successfactors/employee-time/create"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/employee-time/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/odata/v2/EmployeeTime"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT Upsert
        WITH SOURCE_TOPIC "finance/sap-successfactors/odata/upsert"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/odata/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/odata/v2/upsert?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT TimeEventsCreate
        WITH SOURCE_TOPIC "finance/sap-successfactors/clock/events/create"
        WITH DESTINATION_TOPIC "finance/sap-successfactors/clock/events/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/timemanagement/timeeventprocessing/v1/TimeEvents"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

### Keep a token for the other actions

Publish a fresh, URL-encoded assertion from your signer to `state/sf/assertion` (assertions are short-lived). A `COLLAPSED` model builds the token request, because `PUBLISH TOPIC` does not take inline JSON:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SfTokenRequest COLLAPSED
    ADD STRING "company_id"
    ADD STRING "client_id"
    ADD STRING "assertion"

DEFINE ACTION SfToken
ON TOPIC "state/sf/assertion" DO
    SET "company" WITH GET SECRET "SF_COMPANY_ID"
    SET "client" WITH GET SECRET "SF_CLIENT_ID"
    SET "assertion" WITH PAYLOAD AS STRING
    PUBLISH MODEL SfTokenRequest TO "finance/sap-successfactors/auth/token" WITH
        company_id = {company}
        client_id = {client}
        assertion = {assertion}

DEFINE ACTION SfKeepToken
ON TOPIC "finance/sap-successfactors/auth/token/response" DO
    SET "token" WITH (GET JSON "access_token" IN PAYLOAD AS STRING)
    KEEP TOPIC "state/sf/access_token" WITH {token}
```

### Who works where today

Every hour, read the job information valid today for one plant, with department, manager and standard hours. The reply is OData v2 JSON: rows in `d.results`; follow `d.__next` (a `$skiptoken` link) for the next page.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SfQuery COLLAPSED
    ADD STRING "access_token"
    ADD STRING "query"

DEFINE ACTION SfShiftRoster
ON EVERY 60 MINUTES DO
    SET "token" WITH (GET TOPIC "state/sf/access_token" AS STRING)
    PUBLISH MODEL SfQuery TO "finance/sap-successfactors/jobs/list" WITH
        access_token = {token}
        query = "$filter=location%20eq%20'PORTO'&$select=userId,jobTitle,department,location,standardHours,managerId&$top=200"
```

Without `asOfDate` SuccessFactors returns the record valid today; add `asOfDate=2026-10-05` (or `fromDate` / `toDate`) for another day.

### Send badge punches to Clock In Clock Out

The badge gateway publishes the punch payload on `finance/sap-successfactors/clock/events/create` (a LoT model cannot build the JSON array that the API expects). `access_token` must come from the client bound to `TECHNICAL_USER_CICOTERMINAL_9D3F8AC1`. `P10` / `P20` stand for the clock-in and clock-out time event types of your Clock In Clock Out group; `ClockGroupsList` lists them.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<CICO access_token>", "body": [{"id": "1", "assignmentId": "cgrant", "typeCode": "P10", "timestamp": "2026-10-05T07:58:00+01:00", "terminalId": "PORTO-GATE-1", "timeTypeCode": "WORKING_TIME"}]}
```

SuccessFactors answers `201` with `succeededTimeEvents` (one `UUID` per punch) and `failedTimeEvents` (for example `A time event for this employee and timestamp already exists.`). Up to 1000 punches can go in one call; `id` only has to be unique within the call. Read them back with `TimeEventsExport`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "query": "$filter=workAssignmentId%20eq%20'cgrant'%20and%20timestampUTC%20ge%202026-10-05T00:00:00Z&$orderby=timestampUTC&$top=100"}
```

### Book and cancel an absence

Publish to `finance/sap-successfactors/employee-time/create` (the time type must exist and be allowed for the employee; check with `TimeTypeList` / `AvailableTimeTypeList`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "body": {"externalCode": "CF-0001", "userId": "cgrant", "timeType": "TT_VAC_REC", "startDate": "/Date(1791763200000)/", "endDate": "/Date(1791763200000)/", "comment": "Booked from the plant kiosk"}}
```

Cancel it later with an upsert on `finance/sap-successfactors/odata/upsert`. The reply has one row per record with `status` `OK` or `ERROR` and a `message`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<access_token>", "query": "$format=json", "body": {"__metadata": {"uri": "EmployeeTime('CF-0001')"}, "externalCode": "CF-0001", "approvalStatus": "CANCELLED"}}
```

## Notes

* Effective-dated entities (EmpJob, EmpEmployment, Foundation Objects) return the record valid today unless you pass `asOfDate`, or `fromDate` / `toDate` for history.
* `EmpJob` cannot be created with POST; it is upsert only (the metadata marks it `upsertable`, not `creatable`). `Upsert` works for any upsertable entity, but HR master data changes usually belong in SuccessFactors itself; the template only shows time records.
* `TimeEventsExport` needs the export permission; without it SuccessFactors returns an empty list with `200`.
* Use `Metadata` (`/odata/v2/<entity>/$metadata`) to see the custom fields of your instance, and `EntityQuery` to read entity sets that have no dedicated event.
* Errors: OData v2 returns `401` with `[LGN0007]Invalid OAuth token` for a bad token; the Clock In Clock Out APIs answer `401` `AuthenticationRequired` without a token and `400` `AuthenticationFailed` for a malformed one; `/oauth/token` answers `400` with `errorHttpCode` / `errorMessage`.
* Not packaged on purpose: every DELETE, the Clock In Clock Out mass delete (`PATCH` with `deleted: true`), PUT / MERGE updates (use `Upsert`), `$batch`, SFAPI and Compound Employee, the OData v4 Employee Central APIs, and HTTP Basic authentication.


# Seeq
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/seeq

LoT connector for Seeq: push MQTT values into signals, store alarms as capsules, read samples and capsules back, search items and run Seeq Formulas

Technical Preview

## Overview

Seeq is an advanced analytics application for process manufacturing data. It connects to historians and other sources, and it can also **store** signals and conditions itself. The Seeq web application uses the **Seeq Server REST API** for everything, so anything you do in Workbench can be done through `https://<server>/api/`.

The **SeeqRestApi** connector covers login, server status, item search, stored signals (create, push samples, replace samples, read samples or one sample), stored conditions (create, add capsules, read capsules), Seeq Formula runs, and archiving. Typical uses: send MQTT readings that are not in any historian into a Seeq signal, store alarms or batch events from MQTT as capsules, and pull Seeq results (for example an aggregate) back onto the broker. Each event publishes the server's reply on `<topic>/response`.

| Event | Topic | Request | Notes |
| - | - | - | - |
| Login | `historian/seeq/session/create` | `POST /api/auth/login` | Access key as username + password (Seeq directory); session token comes back in the x-sq-auth response header, body = user |
| Logout | `historian/seeq/session/delete` | `DELETE /api/auth/logout` | Invalidate the session token |
| GetServerStatus | `historian/seeq/server-status/get` | `GET /api/system/server-status` | Server readiness and version (no token needed) |
| Ping | `historian/seeq/ping/get` | `GET /api/system/ping` | Authenticated readiness check; keeps the session alive |
| GetCurrentUser | `historian/seeq/user/get` | `GET /api/users/me` | User behind the token (token check) |
| SearchItems | `historian/seeq/item/search` | `GET /api/items?{query}` | Find signals / conditions / assets: filters=Name==Temperature\&types=StoredSignal\&limit=50 (URL-encoded) |
| GetItem | `historian/seeq/item/get` | `GET /api/items/{id}` | All properties of one item |
| CreateSignal | `historian/seeq/signal/create` | `POST /api/signals` | Create a signal stored in Seeq (name required; valueUnitOfMeasure, interpolationMethod, maximumInterpolation) -> id |
| GetSignal | `historian/seeq/signal/get` | `GET /api/signals/{id}` | Signal metadata |
| ArchiveSignal | `historian/seeq/signal/delete` | `DELETE /api/signals/{id}` | Archive a signal |
| AddSamples | `historian/seeq/sample/create` | `POST /api/signals/{id}/samples` | Push samples \{samples: \[\{key: ISO time, value}]} into a stored signal |
| ReplaceSamples | `historian/seeq/sample/update` | `PUT /api/signals/{id}/samples` | Replace samples in the same time range (optional interval \{start, end}) |
| GetSamples | `historian/seeq/sample/list` | `GET /api/signals/{id}/samples?start={start}&end={end}&limit={limit}` | Samples over an interval (start and end required); continuationToken for the next page |
| GetSample | `historian/seeq/sample/get` | `GET /api/signals/{id}/sample/{key}?lookup={lookup}` | One sample at or near a key; lookup AtOrBefore + now = latest value |
| CreateCondition | `historian/seeq/condition/create` | `POST /api/conditions` | Create a stored condition (name + maximumDuration, e.g. 1d) -> id |
| ArchiveCondition | `historian/seeq/condition/delete` | `DELETE /api/conditions/{id}` | Archive a condition and its capsules |
| AddCapsules | `historian/seeq/capsule/create` | `POST /api/conditions/{id}/capsules` | Store alarms / events as capsules \{capsules: \[\{start, end, properties}]} |
| GetCapsules | `historian/seeq/capsule/list` | `GET /api/conditions/{id}/capsules?start={start}&end={end}&limit={limit}` | Capsules in a time range |
| RunFormula | `historian/seeq/formula/run` | `POST /api/formulas/run` | Run a Seeq Formula \{formula, parameters: \["name=\<id>"], start, end} -> samples / capsules / scalar / table |
| RunFormulaQuery | `historian/seeq/formula-query/run` | `GET /api/formulas/run?{query}` | Same as RunFormula with a URL-encoded query (start, end, formula, parameters, limit) |

## Prerequisites

1. A Seeq server the broker host can reach. Seeq SaaS sites look like `https://<company>.seeq.site`. An on-premises server listens on `http://<host>:34216` by default, or on HTTPS behind 443 / 8443.
2. A Seeq **access key** and its password (profile menu → **Access Keys**). Access keys work with every directory, including OAuth 2.0 / OpenID Connect single sign-on. Access key creation is off by default for non-admin users (`Authentication/AccessKey/Creation/Enabled`). An admin can turn it on or create the key for you. A Seeq directory user name and password also work.
3. Write access to the signals and conditions you push to. A signal or condition created through this connector belongs to the access key's user and has global scope unless you set `scopedTo` to a workbook ID.

## Authentication

Seeq uses a **session token** in the `x-sq-auth` header:

1. Log in: publish `{ "body": { "username": "<access key>", "password": "<access key password>" } }` to `historian/seeq/session/create`. Leave `authProviderClass` and `authProviderId` out to use the Seeq directory, which access keys require. For a directory user (for example LDAP), set both to the directory's datasource class and ID from `GET /api/auth/providers`.
2. Seeq returns the token in the **`x-sq-auth` response header**. The response body (`historian/seeq/session/create/response`) is the user record, not the token. The connector publishes the body, so get the token another way, for example with a one-off call from the broker host, and store it as a Hub secret:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -s -D - -o /dev/null -X POST https://<server>/api/auth/login \
  -H "Accept: application/vnd.seeq.v1+json" -H "Content-Type: application/vnd.seeq.v1+json" \
  -d '{"username":"<access key>","password":"<access key password>"}' | grep -i '^x-sq-auth'
```

3. Send `"auth": "<token>"` with every other event. The connector puts it in the `x-sq-auth` header.
4. Seeq ends a session after a period of inactivity (the user's `sessionDuration`). A `Ping` every few minutes keeps it alive. A `401` on any response means the token has expired: log in again. Access keys also stop working when their user has not logged in to Seeq within `Authentication/AccessKey/ValidityWithoutUserLogin` (14 days by default).

`GetServerStatus` needs no token and is a good connectivity check.

> [!WARNING]
>
> Keep the access key, its password and the session token in Hub secrets and add them with `GET SECRET`. Never put them in the connector file or in retained topics.

## Configuration

* Replace `YOUR_SEEQ_SERVER` in `BASE_ADDRESS` with your Seeq host. For an on-premises server without TLS use `http://<host>:34216` and set `USE_SSL` to `"false"`.
* Every request sends `Accept: application/vnd.seeq.v1+json`, and every body uses `Content-Type: application/vnd.seeq.v1+json`. Seeq rejects other values: `406` for a different `Accept`, `415` for plain `application/json`. Keep these headers if you add your own events.
* Keys (timestamps) are ISO 8601, for example `2026-10-05T07:00:00Z`. Use `Z`. A `+hh:mm` offset in a query string must be URL-encoded (`%2B`).
* Signal, condition and item IDs are Seeq GUIDs. `CreateSignal` and `CreateCondition` return them in `id`. You can also find them with `SearchItems` (`filters=Name==Line1 Temperature&types=StoredSignal`) or copy them from Workbench (Item Properties).
* `GetSamples` and `GetCapsules` return at most `limit` entries. When more exist, the response carries a `continuationToken`.
* Errors are JSON `{ "statusMessage": "..." }`. `403` means the user lacks write access to the item, and `404` means the ID is unknown or archived.
* Seeq SaaS sits behind Cloudflare. Requests with the default Python `urllib` User-Agent are refused with Cloudflare error 1010. Requests with no User-Agent or a normal client User-Agent are accepted.

## Examples

Create a signal stored in Seeq for an MQTT value:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/seeq/signal/create
{ "auth": "<token>",
  "body": { "name": "Coreflux Line1 Temperature", "valueUnitOfMeasure": "degC",
            "interpolationMethod": "Linear", "maximumInterpolation": "1h" } }
// historian/seeq/signal/create/response (shortened)
{ "id": "0EF2C1F0-6E6B-7AF0-9C1A-2B3C4D5E6F70", "name": "Coreflux Line1 Temperature", "type": "StoredSignal", ... }
```

Push samples into the signal:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/seeq/sample/create
{ "auth": "<token>", "id": "<signal id>",
  "body": { "samples": [{ "key": "2026-10-05T07:00:00Z", "value": 21.4 }, { "key": "2026-10-05T07:00:10Z", "value": 21.5 }] } }
```

Read the last hour back (`start` and `end` are required):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/seeq/sample/list
{ "auth": "<token>", "id": "<signal id>", "start": "2026-10-05T06:00:00Z", "end": "2026-10-05T07:00:00Z", "limit": 1000 }
// historian/seeq/sample/list/response
{ "samples": [{ "key": "2026-10-05T06:00:10Z", "value": 20.9 }, ...], "valueUnitOfMeasure": "degC", "limit": 1000 }
```

Store an alarm as a capsule on a stored condition (create it first with `historian/seeq/condition/create` and `{ "name": "Line1 Alarms", "maximumDuration": "1d" }`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/seeq/capsule/create
{ "auth": "<token>", "id": "<condition id>",
  "body": { "capsules": [{ "start": "2026-10-05T06:40:00Z", "end": "2026-10-05T06:55:00Z",
                            "properties": [{ "name": "Alarm", "value": "HighTemp", "unitOfMeasure": "string" }] }] } }
```

Run a Seeq Formula, here hourly averages of a signal (`parameters` binds `$t` to a signal ID):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// publish to historian/seeq/formula/run
{ "auth": "<token>",
  "body": { "formula": "$t.aggregate(average(), hours(), startKey())", "parameters": ["t=<signal id>"],
            "start": "2026-10-05T00:00:00Z", "end": "2026-10-05T07:00:00Z" } }
```

Example actions: keep the session alive, remember the IDs of new items, push an MQTT value as a sample, store a closed alarm as a capsule, and poll the latest value:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SeeqKeepAlive
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET SECRET "SEEQ_AUTH_TOKEN"
    PUBLISH TOPIC "historian/seeq/ping/get" WITH { "auth": {auth} }

DEFINE ACTION SeeqRememberSignalId
ON TOPIC "historian/seeq/signal/create/response" DO
    SET "id" WITH (GET JSON "id" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/seeq/signal-id/line1-temperature" WITH {id}

DEFINE ACTION SeeqRememberConditionId
ON TOPIC "historian/seeq/condition/create/response" DO
    SET "id" WITH (GET JSON "id" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/seeq/condition-id/line1-alarms" WITH {id}

DEFINE ACTION SeeqPushLine1Temperature
ON TOPIC "plant/line1/temperature" DO
    SET "auth" WITH GET SECRET "SEEQ_AUTH_TOKEN"
    SET "sid" WITH GET TOPIC "internal/seeq/signal-id/line1-temperature"
    SET "value" WITH PAYLOAD AS DOUBLE
    SET "ts" WITH TIMESTAMP "UTC"
    PUBLISH TOPIC "historian/seeq/sample/create" WITH { "auth": {auth}, "id": {sid}, "body": { "samples": [ { "key": {ts}, "value": {value} } ] } }

DEFINE ACTION SeeqStoreAlarmCapsule
ON TOPIC "plant/line1/alarm/closed" DO
    SET "auth" WITH GET SECRET "SEEQ_AUTH_TOKEN"
    SET "cid" WITH GET TOPIC "internal/seeq/condition-id/line1-alarms"
    SET "start" WITH (GET JSON "start" IN PAYLOAD AS STRING)
    SET "end" WITH (GET JSON "end" IN PAYLOAD AS STRING)
    SET "alarm" WITH (GET JSON "alarm" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "historian/seeq/capsule/create" WITH { "auth": {auth}, "id": {cid}, "body": { "capsules": [ { "start": {start}, "end": {end}, "properties": [ { "name": "Alarm", "value": {alarm}, "unitOfMeasure": "string" } ] } ] } }

DEFINE ACTION SeeqPollLatestTemperature
ON EVERY 1 MINUTE DO
    SET "auth" WITH GET SECRET "SEEQ_AUTH_TOKEN"
    SET "sid" WITH GET TOPIC "internal/seeq/signal-id/line1-temperature"
    SET "now" WITH TIMESTAMP "UTC"
    PUBLISH TOPIC "historian/seeq/sample/get" WITH { "auth": {auth}, "id": {sid}, "key": {now}, "lookup": "AtOrBefore" }
```

`TIMESTAMP "UTC"` must give an ISO 8601 time for Seeq to accept the sample key. Check the format on your broker version before you rely on it.

## Not covered

* Getting the session token inside the broker. Seeq returns it in the `x-sq-auth` response header, and the connector publishes only the response body (see Authentication).
* Workbooks, worksheets, Organizer topics and reports, assets and asset trees, signal / condition / scalar batch upserts, datasource-ID endpoints (`/signals/{datasourceClass}/{datasourceId}/{dataId}`) and calculated items. Use the same URL pattern and headers with your own event if you need them.
* Seeq Data Lab, SPy, Data Lab Functions, Add-ons and the Seeq Connector SDK.
* OData export (`/odata.svc`), which authenticates with the access key and its password directly.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app catalog](/latest/lot-language/routes/rest-api-apps/index)
* [Seeq APIs and SDKs](https://support.seeq.com/latest/cloud/seeq-apis-and-sdks)
* [Working with Access Keys](https://support.seeq.com/latest/cloud/working-with-access-keys)


# SendGrid
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sendgrid

LoT connector for Twilio SendGrid v3: send email with raw content or dynamic templates, check the user profile, and list or get transactional templates

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Twilio SendGrid API v3](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST mail/send | `POST /mail/send` | Raw content and/or dynamic `template_id`; **202 Accepted** |
| GET user/profile | `GET /user/profile` | API-key credential check |
| GET templates | `GET /templates` | `generations` + required `page_size` |
| GET templates/\{id} | `GET /templates/{template_id}` | Single transactional template |

Default `BASE_ADDRESS` is `https://api.sendgrid.com/v3`. Topics use `messaging/sendgrid/<object>/<verb>`.

> [!NOTE]
>
> All events send `Authorization: Bearer {api_key}`. Prefer Hub secret `SENDGRID_API_KEY`. Inbound Event Webhook (delivered / bounce / open) → MQTT is out of scope for this client-mode package. EU regional subusers may use `https://api.eu.sendgrid.com/v3`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Twilio SendGrid API v3
# Auth: Bearer {value.json.api_key}
# BASE_ADDRESS: https://api.sendgrid.com/v3

DEFINE CONNECTOR SendGridRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.sendgrid.com/v3"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getuserprofile
        WITH SOURCE_TOPIC "messaging/sendgrid/user/get-profile"
        WITH DESTINATION_TOPIC "messaging/sendgrid/user/get-profile/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/user/profile"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Sendmail
        WITH SOURCE_TOPIC "messaging/sendgrid/mail/send"
        WITH DESTINATION_TOPIC "messaging/sendgrid/mail/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/mail/send"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
        WITH BODY "{payload}"
    ADD EVENT Listtemplates
        WITH SOURCE_TOPIC "messaging/sendgrid/template/list"
        WITH DESTINATION_TOPIC "messaging/sendgrid/template/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/templates?generations={value.json.generations}&page_size={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
    ADD EVENT Gettemplate
        WITH SOURCE_TOPIC "messaging/sendgrid/template/get"
        WITH DESTINATION_TOPIC "messaging/sendgrid/template/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/templates/{value.json.template_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_key}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getuserprofile | GET | `/user/profile` | `messaging/sendgrid/user/get-profile` | `messaging/sendgrid/user/get-profile/response` |
| Sendmail | POST | `/mail/send` | `messaging/sendgrid/mail/send` | `messaging/sendgrid/mail/send/response` |
| Listtemplates | GET | `/templates` | `messaging/sendgrid/template/list` | `messaging/sendgrid/template/list/response` |
| Gettemplate | GET | `/templates/{template_id}` | `messaging/sendgrid/template/get` | `messaging/sendgrid/template/get/response` |

## Auth

1. Create an API key in the [SendGrid UI](https://app.sendgrid.com/settings/api_keys) with Mail Send (and preferably Template Engine Read) scopes. Use a verified sender identity for `from`.
2. Set connector `BASE_ADDRESS` to `https://api.sendgrid.com/v3` (or `https://api.eu.sendgrid.com/v3` for EU regional).
3. Pass `api_key` on the MQTT payload so `Authorization: Bearer {value.json.api_key}` resolves.
4. Store the key in Hub / `GET SECRET "SENDGRID_API_KEY"`. Never commit real credentials.
5. Successful `GET /user/profile` returns **HTTP 200**. `POST /mail/send` returns **202 Accepted**. `GET /templates` returns **200** with a paged `result` array.

## Example payloads

**getUserProfile:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY"
}
```

**sendMail (raw):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY",
  "personalizations": [
    {
      "to": [{"email": "ops@example.com"}]
    }
  ],
  "from": {"email": "alerts@your-verified-domain.com", "name": "Coreflux"},
  "subject": "Coreflux alarm: vibration above threshold — Zone A",
  "content": [
    {
      "type": "text/plain",
      "value": "RMS exceeded limit on Zone A"
    }
  ]
}
```

**sendMail (dynamic template):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY",
  "personalizations": [
    {
      "to": [{"email": "ops@example.com"}],
      "dynamic_template_data": {
        "zone": "A",
        "metric": "vibration_rms",
        "value": 12.4
      }
    }
  ],
  "from": {"email": "alerts@your-verified-domain.com"},
  "template_id": "d-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
```

**listTemplates:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "YOUR_SENDGRID_API_KEY",
  "generations": "dynamic",
  "page_size": "10"
}
```

## Install

1. The template ships with the broker. List it with `-listTemplates` or fetch it from the Hub catalog.
2. Deploy with `-addConnector` from `SendGridRestApi.lot` (not `hub-metadata.lot`).

## See also

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Sentry
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sentry

Client-mode REST API connector for a curated Sentry slice: list project issues, get an issue, and resolve it

Technical Preview

# Sentry

Client-mode REST API connector for a curated Sentry slice: list project issues, get an issue, and resolve it.

* Hub category: **Monitoring**.
* Base: `https://sentry.io`

## Template reference

Generated from the shipped broker template `sentry` (`-connectorCode SENTRY`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Sentry connector | no |
| `BaseUrl` | string | Sentry base URL without trailing slash (e.g. [https://sentry.io](https://sentry.io)) | yes |

`BASE_ADDRESS` default: `https://sentry.io`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listissues` | GET | `/api/0/projects/{value.json.organization}/{value.json.project}/issues/` | `monitoring/sentry/issues/list` | `monitoring/sentry/issues/list/response` | `api_token`, `organization`, `project` |
| `Getissue` | GET | `/api/0/issues/{value.json.issue_id}/` | `monitoring/sentry/issues/get` | `monitoring/sentry/issues/get/response` | `api_token`, `issue_id` |
| `Resolveissue` | PUT | `/api/0/issues/{value.json.issue_id}/` | `monitoring/sentry/issues/resolve` | `monitoring/sentry/issues/resolve/response` | `api_token`, `body`, `issue_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SENTRY"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SentryRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://sentry.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listissues
        WITH SOURCE_TOPIC "monitoring/sentry/issues/list"
        WITH DESTINATION_TOPIC "monitoring/sentry/issues/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/0/projects/{value.json.organization}/{value.json.project}/issues/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getissue
        WITH SOURCE_TOPIC "monitoring/sentry/issues/get"
        WITH DESTINATION_TOPIC "monitoring/sentry/issues/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/0/issues/{value.json.issue_id}/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Resolveissue
        WITH SOURCE_TOPIC "monitoring/sentry/issues/resolve"
        WITH DESTINATION_TOPIC "monitoring/sentry/issues/resolve/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/0/issues/{value.json.issue_id}/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listissues` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'monitoring/sentry/issues/list/response' &
mosquitto_pub -t 'monitoring/sentry/issues/list' -m '{"api_token": "<api_token>", "organization": "<organization>", "project": "<project>"}'
```


# Sepasoft MES for Ignition
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sepasoft-mes-for-ignition

LoT connector for Sepasoft MES on Ignition: OEE counts and equipment state, Track and Trace genealogy, work order schedules and gateway health

Technical Preview

## Overview

One client-mode connector, **SepasoftMES**, for Sepasoft MES modules (OEE Downtime, Track and Trace, Settings and Changeover) running on an Inductive Automation Ignition gateway. It moves MES data between your Unified Namespace and the gateway over HTTP.

Sepasoft does not publish a fixed REST API. You author REST endpoints yourself in the Ignition Designer with the Sepasoft **Web Services** module (Web Services, then Providers, then RESTful Endpoints), each one a Python script for `GET`, `POST`, `PUT` or `DELETE`, and the gateway serves them under `/system/ws/rest/<folder>/<resource>`. So the connector has three groups of events:

1. **Gateway health**, no credentials: `/StatusPing` and `/system/gwinfo`.
2. **Generic passthroughs** for any Web Services RESTful endpoint or Ignition WebDev resource you already have.
3. **MES presets** that call a small companion provider folder, `coreflux/v1`. Example scripts for it ship with the connector template (`sepasoft-provider/`), built on documented `system.mes.*` functions.

| Event | Request | Notes |
| - | - | - |
| GatewayStatusPing | `GET /StatusPing` | Returns `{"state":"RUNNING"}` when the gateway is up; no auth |
| GatewayInfo | `GET /system/gwinfo` | Version, platform name and redundancy state as `key=value;` text; no auth |
| WsRestGet | `GET /system/ws/rest/{resource}?{query}` | Any RESTful endpoint `do_GET` |
| WsRestPost | `POST /system/ws/rest/{resource}` | Any RESTful endpoint `do_POST`, JSON body |
| WsRestPut | `PUT /system/ws/rest/{resource}` | Any RESTful endpoint `do_PUT`, JSON body |
| WsRestDelete | `DELETE /system/ws/rest/{resource}?{query}` | Any RESTful endpoint `do_DELETE` |
| WebDevGet | `GET /system/webdev/{project}/{resource}?{query}` | Ignition WebDev resource `doGet` |
| WebDevPost | `POST /system/webdev/{project}/{resource}` | Ignition WebDev resource `doPost` |
| OeeCountInput | `POST /system/ws/rest/coreflux/v1/oee/countinput` | Writes an infeed, outfeed or reject count to the tag your OEE production model reads |
| OeeEquipmentState | `POST /system/ws/rest/coreflux/v1/oee/equipmentstate` | Writes an equipment state code to the OEE state tag |
| OeeAnalysis | `GET /system/ws/rest/coreflux/v1/oee/analysis?{query}` | Runs an MES analysis for `eqPath`, `startDate`, `endDate` |
| TraceMaterialMove | `POST /system/ws/rest/coreflux/v1/trace/materialmove` | Executes a Track and Trace segment with its materials |
| TraceGenealogy | `GET /system/ws/rest/coreflux/v1/trace/genealogy?{query}` | Lot genealogy for `lot` |
| ScheduleRuns | `GET /system/ws/rest/coreflux/v1/schedule/runs?{query}` | Scheduled operations requests for `workOrder` between `begin` and `end` |
| WorkOrderGet | `GET /system/ws/rest/coreflux/v1/workorder/get?{query}` | Work order quantity and scheduled quantity for `name` |

Topics follow `mes/sepasoft/<object>/<verb>`, and each reply arrives on `<topic>/response`.

## Prerequisites

* An Ignition gateway (8.x) with the Sepasoft MES modules you use and the Sepasoft **Web Services** module.
* For the MES presets, the `coreflux/v1` provider folder (see below). The generic events work with any endpoint you already have.
* An Ignition user in the User Source picked on each endpoint, with a role allowed by the endpoint's Required role(s).
* Network reach from the broker to the gateway's HTTPS port (8043 by default) or HTTP port (8088).

## Authentication

Each RESTful endpoint can require **HTTP Basic** authentication against an Ignition User Source, optionally limited to some roles. Missing credentials return `401` with a `WWW-Authenticate` header and wrong credentials return `403`. An HTTP method with no script returns `405`, and a script syntax error returns `500`.

Store the full header value, `Basic <base64 of user:password>`, in a broker secret (suggested `SEPASOFT_BASIC_AUTH`) and map it into the `authorization` payload field with `GET SECRET`. The two gateway health events send no credentials.

## Connector

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SepasoftMES WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_IGNITION_GATEWAY:8043"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GatewayStatusPing
        WITH SOURCE_TOPIC "mes/sepasoft/gateway-status/get"
        WITH DESTINATION_TOPIC "mes/sepasoft/gateway-status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/StatusPing"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT WsRestGet
        WITH SOURCE_TOPIC "mes/sepasoft/ws-rest/get"
        WITH DESTINATION_TOPIC "mes/sepasoft/ws-rest/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/system/ws/rest/{value.json.resource}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT OeeCountInput
        WITH SOURCE_TOPIC "mes/sepasoft/oee-count/create"
        WITH DESTINATION_TOPIC "mes/sepasoft/oee-count/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/system/ws/rest/coreflux/v1/oee/countinput"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
```

The full template, `SepasoftMesForIgnitionRestApi.lot`, has all 15 events. Ignition 7.9 mounted providers under `/main/system/ws/rest/...`; on 7.9, change the endpoint prefix.

## Payload fields

| Field | Used by | Example |
| - | - | - |
| `authorization` | every event except the two gateway events | `"Basic Y29yZWZsdXg6Y2hhbmdlLW1l"` (from `GET SECRET`) |
| `resource` | `WsRest*`, `WebDev*` | `"v1/line-status"` (folder and resource name under the mount) |
| `project` | `WebDev*` | `"MESDemo"` |
| `query` | GET and DELETE events | `"eqPath=Enterprise%5CSite%5CLine%201&startDate=2026-10-05T00:00:00&endDate=2026-10-05T08:00:00"`; send `""` when empty |
| `body` | POST and PUT events | JSON object; the provider receives it as `request['body']` |

## Companion provider `coreflux/v1`

In the Designer, create the folders `coreflux` and `v1` under RESTful Endpoints and four endpoints named `oee`, `trace`, `schedule` and `workorder`. Set Data format to JSON, HTTP Authentication to Basic, choose the User Source and roles, tick Redirect to SSL, and paste the matching example script. The part of the URL after the resource name (for example `/countinput`) reaches the script as `request['path']`.

| Script | Sub-paths | Sepasoft and Ignition functions |
| - | - | - |
| `oee.py` | `POST /countinput`, `POST /equipmentstate`, `GET /analysis` | `system.tag.writeBlocking`, `system.mes.analysis.createMESAnalysisSettings`, `system.mes.analysis.executeAnalysis` |
| `trace.py` | `POST /materialmove`, `GET /genealogy` | `system.mes.createSegment`, `setMaterial`, `execute`, `system.mes.trace.getTraceabilityData` |
| `schedule.py` | `GET /runs` | `system.mes.workorder.getMESWorkOrder`, `getOperationsRequests(begin, end)` |
| `workorder.py` | `GET /get` | `system.mes.workorder.getMESWorkOrder`, `updateQuantities`, `getWorkOrderQuantity`, `getScheduledQuantity` |

> [!WARNING]
>
> The scripts are starting points. Test each one on a development gateway with the Designer's Copy RESTful Endpoint URL before you connect the broker. `OeeCountInput`, `OeeEquipmentState` and `TraceMaterialMove` change production records, so restrict who may publish on those topics with broker rules.

## Examples

Check the gateway every minute:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SepasoftGatewayHealth
ON EVERY 1 MINUTE DO
    PUBLISH TOPIC "mes/sepasoft/gateway-status/get" WITH { "query": "" }
```

Forward a line counter to OEE:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SepasoftLineCount
ON TOPIC "porto/line1/infeed/count" DO
    SET "auth" WITH GET SECRET "SEPASOFT_BASIC_AUTH"
    SET "count" WITH PAYLOAD AS INT
    PUBLISH TOPIC "mes/sepasoft/oee-count/create" WITH { "authorization": {auth}, "body": { "tag_path": "[default]Line1/Infeed Count", "value": {count} } }
```

Record a material move in Track and Trace (publish to `mes/sepasoft/trace-material-move/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Basic <from GET SECRET>",
  "body": {
    "segment": "Mix Dressing",
    "equipment_path": "Dressings Inc\\California\\Mixing\\Mixer 1",
    "materials": [{ "property": "Vinegar", "lot": "LOT-0042", "quantity": 20 }]
  }
}
```

## Troubleshooting

| Symptom | Cause |
| - | - |
| `401` with `WWW-Authenticate` | `authorization` missing or empty |
| `403` | Wrong user or password, or the user lacks a required role |
| `404` | Wrong folder or resource name, or a 7.9 gateway that needs `/main/system/ws/rest` |
| `405` | The endpoint has no script for that HTTP method |
| `500` | Syntax error in the endpoint script, or the script did not return a dict with integer `code` and dict `content` |

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* Sepasoft docs: [RESTful Endpoints](https://docs.sepasoft.com/articles/user-manual/restful-endpoints), [Serving up Analysis Data as a Web Service REST Endpoint](https://docs.sepasoft.com/articles/knowledge-base/serving-up-analysis-data-as-a-web-service-rest-endpoint)


# Service Titan Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/service-titan-api

LoT connector for ServiceTitan: create jobs from equipment faults, add appointments, assign technicians, and register and update installed equipment

Technical Preview

## Overview

Client-mode REST API connector for ServiceTitan field service: create jobs from connected-equipment faults, patch, note and cancel them, attach installed equipment, add appointments and assign technicians, track technicians, register and update installed equipment, and read locations and lookup lists, with OAuth 2.0 client credentials plus the ST-App-Key header.

This is one of the templates in the ServiceTitan REST API app (`servicetitan`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 client credentials: GetToken posts grant\_type=client\_credentials\&client\_id\&client\_secret (form) to [https://auth.servicetitan.io/connect/token](https://auth.servicetitan.io/connect/token); tokens last 900 s, no refresh token. API events: Authorization: \<access\_token> (raw, as in the portal's first-call sample) + ST-App-Key: \<app key> from payload; tenant id in the path. Every event also sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: {value.json.access_token}`, `ST-App-Key: {value.json.app_key}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Service Titan Api connector | no |
| `BaseUrl` | string | Service Titan Api base URL without trailing slash (e.g. [https://api.servicetitan.io](https://api.servicetitan.io)) | yes |

`BASE_ADDRESS` default: `https://api.servicetitan.io`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ListJobs` | GET | `/jpm/v2/tenant/{value.json.tenant}/jobs?{value.json.query}` | `cmms/servicetitan/job/list` | `cmms/servicetitan/job/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `GetJob` | GET | `/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}` | `cmms/servicetitan/job/get` | `cmms/servicetitan/job/get/response` | `access_token`, `app_key`, `id`, `tenant` |
| `CreateJob` | POST | `/jpm/v2/tenant/{value.json.tenant}/jobs` | `cmms/servicetitan/job/create` | `cmms/servicetitan/job/create/response` | `access_token`, `app_key`, `body`, `tenant` |
| `UpdateJob` | PATCH | `/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}` | `cmms/servicetitan/job/update` | `cmms/servicetitan/job/update/response` | `access_token`, `app_key`, `body`, `id`, `tenant` |
| `CancelJob` | PUT | `/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/cancel` | `cmms/servicetitan/job/cancel` | `cmms/servicetitan/job/cancel/response` | `access_token`, `app_key`, `body`, `id`, `tenant` |
| `ListJobCancelReasons` | GET | `/jpm/v2/tenant/{value.json.tenant}/job-cancel-reasons?{value.json.query}` | `cmms/servicetitan/job-cancel-reason/list` | `cmms/servicetitan/job-cancel-reason/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListJobTypes` | GET | `/jpm/v2/tenant/{value.json.tenant}/job-types?{value.json.query}` | `cmms/servicetitan/job-type/list` | `cmms/servicetitan/job-type/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListJobNotes` | GET | `/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/notes?{value.json.query}` | `cmms/servicetitan/job-note/list` | `cmms/servicetitan/job-note/list/response` | `access_token`, `app_key`, `id`, `query`, `tenant` |
| `CreateJobNote` | POST | `/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/notes` | `cmms/servicetitan/job-note/create` | `cmms/servicetitan/job-note/create/response` | `access_token`, `app_key`, `body`, `id`, `tenant` |
| `ListJobEquipment` | GET | `/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/equipment` | `cmms/servicetitan/job-equipment/list` | `cmms/servicetitan/job-equipment/list/response` | `access_token`, `app_key`, `id`, `tenant` |
| `AttachJobEquipment` | POST | `/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/equipment` | `cmms/servicetitan/job-equipment/attach` | `cmms/servicetitan/job-equipment/attach/response` | `access_token`, `app_key`, `body`, `id`, `tenant` |
| `ExportJobs` | GET | `/jpm/v2/tenant/{value.json.tenant}/export/jobs?{value.json.query}` | `cmms/servicetitan/job/export` | `cmms/servicetitan/job/export/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListAppointments` | GET | `/jpm/v2/tenant/{value.json.tenant}/appointments?{value.json.query}` | `cmms/servicetitan/appointment/list` | `cmms/servicetitan/appointment/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `AddAppointment` | POST | `/jpm/v2/tenant/{value.json.tenant}/appointments` | `cmms/servicetitan/appointment/create` | `cmms/servicetitan/appointment/create/response` | `access_token`, `app_key`, `body`, `tenant` |
| `ListAppointmentAssignments` | GET | `/dispatch/v2/tenant/{value.json.tenant}/appointment-assignments?{value.json.query}` | `cmms/servicetitan/assignment/list` | `cmms/servicetitan/assignment/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `AssignTechnicians` | POST | `/dispatch/v2/tenant/{value.json.tenant}/appointment-assignments/assign-technicians` | `cmms/servicetitan/assignment/assign` | `cmms/servicetitan/assignment/assign/response` | `access_token`, `app_key`, `body`, `tenant` |
| `GetTechnicianTracking` | GET | `/dispatch/v2/tenant/{value.json.tenant}/technician-tracking?{value.json.query}` | `cmms/servicetitan/technician-tracking/get` | `cmms/servicetitan/technician-tracking/get/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListTechnicianShifts` | GET | `/dispatch/v2/tenant/{value.json.tenant}/technician-shifts?{value.json.query}` | `cmms/servicetitan/technician-shift/list` | `cmms/servicetitan/technician-shift/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListTechnicians` | GET | `/settings/v2/tenant/{value.json.tenant}/technicians?{value.json.query}` | `cmms/servicetitan/technician/list` | `cmms/servicetitan/technician/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListBusinessUnits` | GET | `/settings/v2/tenant/{value.json.tenant}/business-units?{value.json.query}` | `cmms/servicetitan/business-unit/list` | `cmms/servicetitan/business-unit/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListInstalledEquipment` | GET | `/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment?{value.json.query}` | `cmms/servicetitan/equipment/list` | `cmms/servicetitan/equipment/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `GetInstalledEquipment` | GET | `/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment/{value.json.id}` | `cmms/servicetitan/equipment/get` | `cmms/servicetitan/equipment/get/response` | `access_token`, `app_key`, `id`, `tenant` |
| `CreateInstalledEquipment` | POST | `/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment` | `cmms/servicetitan/equipment/create` | `cmms/servicetitan/equipment/create/response` | `access_token`, `app_key`, `body`, `tenant` |
| `UpdateInstalledEquipment` | PATCH | `/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment/{value.json.id}` | `cmms/servicetitan/equipment/update` | `cmms/servicetitan/equipment/update/response` | `access_token`, `app_key`, `body`, `id`, `tenant` |
| `ListEquipmentTypes` | GET | `/equipmentsystems/v2/tenant/{value.json.tenant}/equipment-types?{value.json.query}` | `cmms/servicetitan/equipment-type/list` | `cmms/servicetitan/equipment-type/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListEquipmentSystems` | GET | `/equipmentsystems/v2/tenant/{value.json.tenant}/equipment-systems?{value.json.query}` | `cmms/servicetitan/equipment-system/list` | `cmms/servicetitan/equipment-system/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `ListLocations` | GET | `/crm/v2/tenant/{value.json.tenant}/locations?{value.json.query}` | `cmms/servicetitan/location/list` | `cmms/servicetitan/location/list/response` | `access_token`, `app_key`, `query`, `tenant` |
| `GetLocation` | GET | `/crm/v2/tenant/{value.json.tenant}/locations/{value.json.id}` | `cmms/servicetitan/location/get` | `cmms/servicetitan/location/get/response` | `access_token`, `app_key`, `id`, `tenant` |
| `CreateLocationNote` | POST | `/crm/v2/tenant/{value.json.tenant}/locations/{value.json.id}/notes` | `cmms/servicetitan/location-note/create` | `cmms/servicetitan/location-note/create/response` | `access_token`, `app_key`, `body`, `id`, `tenant` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SERVICETITAN"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ServiceTitanApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.servicetitan.io"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListJobs
        WITH SOURCE_TOPIC "cmms/servicetitan/job/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT GetJob
        WITH SOURCE_TOPIC "cmms/servicetitan/job/get"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT CreateJob
        WITH SOURCE_TOPIC "cmms/servicetitan/job/create"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateJob
        WITH SOURCE_TOPIC "cmms/servicetitan/job/update"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CancelJob
        WITH SOURCE_TOPIC "cmms/servicetitan/job/cancel"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job/cancel/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/cancel"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListJobCancelReasons
        WITH SOURCE_TOPIC "cmms/servicetitan/job-cancel-reason/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job-cancel-reason/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/job-cancel-reasons?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListJobTypes
        WITH SOURCE_TOPIC "cmms/servicetitan/job-type/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job-type/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/job-types?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListJobNotes
        WITH SOURCE_TOPIC "cmms/servicetitan/job-note/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job-note/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/notes?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT CreateJobNote
        WITH SOURCE_TOPIC "cmms/servicetitan/job-note/create"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job-note/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/notes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListJobEquipment
        WITH SOURCE_TOPIC "cmms/servicetitan/job-equipment/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job-equipment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/equipment"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT AttachJobEquipment
        WITH SOURCE_TOPIC "cmms/servicetitan/job-equipment/attach"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job-equipment/attach/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/jobs/{value.json.id}/equipment"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ExportJobs
        WITH SOURCE_TOPIC "cmms/servicetitan/job/export"
        WITH DESTINATION_TOPIC "cmms/servicetitan/job/export/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/export/jobs?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListAppointments
        WITH SOURCE_TOPIC "cmms/servicetitan/appointment/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/appointment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/appointments?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT AddAppointment
        WITH SOURCE_TOPIC "cmms/servicetitan/appointment/create"
        WITH DESTINATION_TOPIC "cmms/servicetitan/appointment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/jpm/v2/tenant/{value.json.tenant}/appointments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListAppointmentAssignments
        WITH SOURCE_TOPIC "cmms/servicetitan/assignment/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/assignment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/dispatch/v2/tenant/{value.json.tenant}/appointment-assignments?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT AssignTechnicians
        WITH SOURCE_TOPIC "cmms/servicetitan/assignment/assign"
        WITH DESTINATION_TOPIC "cmms/servicetitan/assignment/assign/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/dispatch/v2/tenant/{value.json.tenant}/appointment-assignments/assign-technicians"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTechnicianTracking
        WITH SOURCE_TOPIC "cmms/servicetitan/technician-tracking/get"
        WITH DESTINATION_TOPIC "cmms/servicetitan/technician-tracking/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/dispatch/v2/tenant/{value.json.tenant}/technician-tracking?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListTechnicianShifts
        WITH SOURCE_TOPIC "cmms/servicetitan/technician-shift/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/technician-shift/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/dispatch/v2/tenant/{value.json.tenant}/technician-shifts?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListTechnicians
        WITH SOURCE_TOPIC "cmms/servicetitan/technician/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/technician/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/settings/v2/tenant/{value.json.tenant}/technicians?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListBusinessUnits
        WITH SOURCE_TOPIC "cmms/servicetitan/business-unit/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/business-unit/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/settings/v2/tenant/{value.json.tenant}/business-units?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListInstalledEquipment
        WITH SOURCE_TOPIC "cmms/servicetitan/equipment/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/equipment/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT GetInstalledEquipment
        WITH SOURCE_TOPIC "cmms/servicetitan/equipment/get"
        WITH DESTINATION_TOPIC "cmms/servicetitan/equipment/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT CreateInstalledEquipment
        WITH SOURCE_TOPIC "cmms/servicetitan/equipment/create"
        WITH DESTINATION_TOPIC "cmms/servicetitan/equipment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateInstalledEquipment
        WITH SOURCE_TOPIC "cmms/servicetitan/equipment/update"
        WITH DESTINATION_TOPIC "cmms/servicetitan/equipment/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/equipmentsystems/v2/tenant/{value.json.tenant}/installed-equipment/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListEquipmentTypes
        WITH SOURCE_TOPIC "cmms/servicetitan/equipment-type/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/equipment-type/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/equipmentsystems/v2/tenant/{value.json.tenant}/equipment-types?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListEquipmentSystems
        WITH SOURCE_TOPIC "cmms/servicetitan/equipment-system/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/equipment-system/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/equipmentsystems/v2/tenant/{value.json.tenant}/equipment-systems?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT ListLocations
        WITH SOURCE_TOPIC "cmms/servicetitan/location/list"
        WITH DESTINATION_TOPIC "cmms/servicetitan/location/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v2/tenant/{value.json.tenant}/locations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT GetLocation
        WITH SOURCE_TOPIC "cmms/servicetitan/location/get"
        WITH DESTINATION_TOPIC "cmms/servicetitan/location/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v2/tenant/{value.json.tenant}/locations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
    ADD EVENT CreateLocationNote
        WITH SOURCE_TOPIC "cmms/servicetitan/location-note/create"
        WITH DESTINATION_TOPIC "cmms/servicetitan/location-note/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/crm/v2/tenant/{value.json.tenant}/locations/{value.json.id}/notes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "{value.json.access_token}"
            ADD "ST-App-Key" "{value.json.app_key}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ListJobs` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'cmms/servicetitan/job/list/response' &
mosquitto_pub -t 'cmms/servicetitan/job/list' -m '{"access_token": "<access_token>", "app_key": "<app_key>", "query": "<query>", "tenant": "<tenant>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# ServiceMax (PTC)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/servicemax

LoT connector for ServiceMax on Salesforce: create and close work orders from alarms, update installed products with telemetry and publish Platform Events

Technical Preview

## Overview

[ServiceMax](https://www.servicemax.com/) (part of PTC) is field service management for equipment makers and operators. **ServiceMax Core** is a managed package (`SVMXC__` objects) and **Asset 360** (`SVMXA360__`) builds on Salesforce Field Service; both run inside your Salesforce org. This connector lets the broker open a ServiceMax work order when a machine raises an alarm, put run hours and other telemetry on the installed product, and show each technician's open work orders, so service teams see what the machine sees.

The template has two connectors:

* **ServiceMaxApi** (`ServicemaxRestApi.lot`), a client connector on your org's My Domain with 26 events: 10 writes, 14 reads and 2 token events. It has no `DELETE` events. Events starting with `A360` need Asset 360; the others need ServiceMax Core.
* **ServiceMaxNotificationReceiver** (`cmms_servicemax_webhook.lot`), an optional server connector on port `9011` that receives JSON callouts from a Flow or Apex in your org and publishes them on MQTT.

> [!NOTE]
>
> ServiceMax publishes no OpenAPI or Postman file of its own: its objects are ordinary Salesforce sObjects, read and written with the Salesforce REST API. The events were picked by hand from the PTC data dictionaries ([Work Order](https://support.ptc.com/help/servicemaxcore/en/articles/core/work-order1.html), [Installed Product](https://support.ptc.com/help/servicemaxcore/en/articles/core/installed-product-2.html), [Technician/Equipment](https://support.ptc.com/help/servicemaxcore/en/articles/core/technician-equipment.html)) and the [Salesforce REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/).

## Events

| Event | Topic | Request | Kind | What it does |
| - | - | - | - | - |
| `GetToken` | `cmms/servicemax/token/create` | `POST /services/oauth2/token` | Auth | Get an access token from your My Domain (form body: client\_credentials, or password / JWT bearer / refresh\_token grants). Reply access\_token + instance\_url; send access\_token on every other event |
| `RevokeToken` | `cmms/servicemax/token/revoke` | `POST /services/oauth2/revoke` | Auth | Revoke an access or refresh token (form body token=...). Not a data delete |
| `ListApiVersions` | `cmms/servicemax/api-version/list` | `GET /services/data/` | Read | API versions the org serves (no auth needed). The connector pins v65.0 |
| `GetLimits` | `cmms/servicemax/limit/get` | `GET /services/data/v65.0/limits` | Read | Org limits (DailyApiRequests Max / Remaining and more). Check before polling |
| `Query` | `cmms/servicemax/soql/query` | `GET /services/data/v65.0/query?q={q}` | Read | Any SOQL query, URL-encoded (spaces as +). Up to 2000 rows per page; nextRecordsUrl when done is false |
| `QueryMore` | `cmms/servicemax/soql/next` | `GET /services/data/v65.0/query/{id}` | Read | Next page of a query (the part of nextRecordsUrl after /query/) |
| `DescribeWorkOrder` | `cmms/servicemax/work-order-describe/get` | `GET /services/data/v65.0/sobjects/SVMXC__Service_Order__c/describe` | Read | Field list and the org's picklist values for SVMXC\_\_Order\_Status\_\_c, SVMXC\_\_Priority\_\_c and SVMXC\_\_Order\_Type\_\_c (they are configurable) |
| `GetWorkOrder` | `cmms/servicemax/work-order/get` | `GET /services/data/v65.0/sobjects/SVMXC__Service_Order__c/{id}?{query}` | Read | One ServiceMax work order by record Id (query fields=... or "" for all) |
| `ListOpenWorkOrdersByTechnician` | `cmms/servicemax/work-order/list-open-by-technician` | `GET /services/data/v65.0/query?q=<SOQL>` | Read | Open work orders assigned to one technician (SVMXC\_\_Group\_Member\_\_c, not closed), next scheduled first, 200 max |
| `ListOpenWorkOrdersByInstalledProduct` | `cmms/servicemax/work-order/list-open-by-installed-product` | `GET /services/data/v65.0/query?q=<SOQL>` | Read | Open work orders for one installed product (check before opening a duplicate from a repeating alarm) |
| `CreateWorkOrder` | `cmms/servicemax/work-order/create` | `POST /services/data/v65.0/sobjects/SVMXC__Service_Order__c` | Write | Create a ServiceMax work order from an alarm; reply 201 `{id, success, errors}` |
| `UpdateWorkOrder` | `cmms/servicemax/work-order/update` | `PATCH /services/data/v65.0/sobjects/SVMXC__Service_Order__c/{id}` | Write | Change work order fields (status, priority, technician SVMXC\_\_Group\_Member\_\_c, ...); reply 204 empty |
| `UpsertWorkOrderByExternalId` | `cmms/servicemax/work-order/upsert` | `PATCH /services/data/v65.0/sobjects/SVMXC__Service_Order__c/{external_id_field}/{external_id}` | Write | Create or update a work order keyed by your own External ID field (one work order per alarm id). 201 created / 200 updated |
| `DescribeInstalledProduct` | `cmms/servicemax/installed-product-describe/get` | `GET /services/data/v65.0/sobjects/SVMXC__Installed_Product__c/describe` | Read | Installed product fields, including your custom telemetry fields and SVMXC\_\_Status\_\_c values |
| `GetInstalledProduct` | `cmms/servicemax/installed-product/get` | `GET /services/data/v65.0/sobjects/SVMXC__Installed_Product__c/{id}?{query}` | Read | One installed product by record Id |
| `FindInstalledProductBySerial` | `cmms/servicemax/installed-product/find-by-serial` | `GET /services/data/v65.0/query?q=<SOQL>` | Read | Map a machine serial number from MQTT to its installed product Id |
| `UpdateInstalledProduct` | `cmms/servicemax/installed-product/update` | `PATCH /services/data/v65.0/sobjects/SVMXC__Installed_Product__c/{id}` | Write | Telemetry on the installed product: your custom fields (e.g. Run\_Hours\_\_c) plus SVMXC\_\_Status\_\_c / SVMXC\_\_Latitude\_\_c / SVMXC\_\_Longitude\_\_c; reply 204 |
| `UpdateRecordsBatch` | `cmms/servicemax/record-batch/update` | `PATCH /services/data/v65.0/composite/sobjects` | Write | Update up to 200 records in one call (sObject Collections), e.g. run hours for a whole line; reply per-record success / errors |
| `ListTechnicians` | `cmms/servicemax/technician/list` | `GET /services/data/v65.0/query?q=<SOQL>` | Read | Active technicians / equipment (SVMXC\_\_Service\_Group\_Members\_\_c) with service team and Salesforce user |
| `GetTechnician` | `cmms/servicemax/technician/get` | `GET /services/data/v65.0/sobjects/SVMXC__Service_Group_Members__c/{id}?{query}` | Read | One technician / equipment record by Id |
| `CreateCase` | `cmms/servicemax/case/create` | `POST /services/data/v65.0/sobjects/Case` | Write | Open a Salesforce Case (the usual ServiceMax entry point before a work order is dispatched) |
| `PublishPlatformEvent` | `cmms/servicemax/platform-event/publish` | `POST /services/data/v65.0/sobjects/{event_name}` | Write | Publish a platform event you defined (e.g. Coreflux\_Telemetry\_\_e) for Flows / Apex triggers to act on |
| `A360SaveTechnicalAttributes` | `cmms/servicemax/a360-technical-attribute/save` | `POST /services/apexrest/SVMXA360/technicalAttribute/v1/saveTechnicalAttributes/` | Write | Asset 360 only: write telemetry as technical attributes (up to 200 entries, with time of occurrence) on Assets |
| `A360CreateWorkOrder` | `cmms/servicemax/a360-work-order/create` | `POST /services/data/v65.0/sobjects/WorkOrder` | Write | Asset 360 only: create a standard WorkOrder on an Asset |
| `A360ListOpenWorkOrdersByAsset` | `cmms/servicemax/a360-work-order/list-open-by-asset` | `GET /services/data/v65.0/query?q=<SOQL>` | Read | Asset 360 only: open standard WorkOrders for one Asset |
| `A360UpdateAsset` | `cmms/servicemax/a360-asset/update` | `PATCH /services/data/v65.0/sobjects/Asset/{id}` | Write | Asset 360 only: update a standard Asset (status or your custom telemetry fields) |

Replies arrive on the same topic with `/response` appended. The SOQL behind the fixed query events:

* `ListOpenWorkOrdersByTechnician`:

  ```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
  SELECT Id,Name,SVMXC__Order_Status__c,SVMXC__Priority__c,SVMXC__Order_Type__c,SVMXC__Component__c,SVMXC__Company__c,SVMXC__Scheduled_Date_Time__c,SVMXC__Problem_Description__c FROM SVMXC__Service_Order__c WHERE SVMXC__Group_Member__c='{value.json.technician_id}' AND SVMXC__Closed_On__c=null ORDER BY SVMXC__Scheduled_Date_Time__c LIMIT 200
  ```
* `ListOpenWorkOrdersByInstalledProduct`:

  ```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
  SELECT Id,Name,SVMXC__Order_Status__c,SVMXC__Priority__c,SVMXC__Order_Type__c,SVMXC__Component__c,SVMXC__Company__c,SVMXC__Scheduled_Date_Time__c,SVMXC__Problem_Description__c FROM SVMXC__Service_Order__c WHERE SVMXC__Component__c='{value.json.installed_product_id}' AND SVMXC__Closed_On__c=null LIMIT 200
  ```
* `FindInstalledProductBySerial`:

  ```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
  SELECT Id,Name,SVMXC__Serial_Lot_Number__c,SVMXC__Status__c,SVMXC__Product__c,SVMXC__Company__c,SVMXC__Site__c,SVMXC__Parent__c FROM SVMXC__Installed_Product__c WHERE SVMXC__Serial_Lot_Number__c='{value.json.serial}' LIMIT 5
  ```
* `ListTechnicians`:

  ```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
  SELECT Id,Name,SVMXC__Service_Group__c,SVMXC__Salesforce_User__c,SVMXC__Email__c,SVMXC__Active__c FROM SVMXC__Service_Group_Members__c WHERE SVMXC__Active__c=true LIMIT 200
  ```
* `A360ListOpenWorkOrdersByAsset`:

  ```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
  SELECT Id,WorkOrderNumber,Status,Priority,Subject,AssetId,OwnerId FROM WorkOrder WHERE AssetId='{value.json.asset_id}' AND IsClosed=false LIMIT 200
  ```

## Prerequisites

* A Salesforce org with ServiceMax Core installed (and Asset 360 for the `A360` events).
* An **External Client App** (or Connected App) with OAuth enabled. For server-to-server use enable the **client credentials flow** and set a **Run As** integration user that has the ServiceMax permission sets and access to the objects and fields you write.
* Your org's **My Domain** URL, for example `https://acme.my.salesforce.com` (sandbox `https://acme--uat.sandbox.my.salesforce.com`). Change `BASE_ADDRESS` to it. `login.salesforce.com` and `test.salesforce.com` only issue tokens; REST calls on them fail with `URL_NOT_RESET`.
* Outbound HTTPS from the broker to that host.
* For notifications only: a public HTTPS URL that forwards to the broker's port `9011`.

## Authentication

> [!WARNING]
>
> The consumer secret and every access token act as the Run As user. Store the consumer key and secret in the Hub secrets `SALESFORCE_CLIENT_ID` and `SALESFORCE_CLIENT_SECRET`, read them with `GET SECRET`, and never put them or a token in a connector file or a retained topic.

`GetToken` posts a form body to `/services/oauth2/token` on your My Domain. With the client credentials flow:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "form": "grant_type=client_credentials&client_id=<Consumer Key (Hub secret SALESFORCE_CLIENT_ID)>&client_secret=<Consumer Secret (Hub secret SALESFORCE_CLIENT_SECRET)>"
}
```

The reply carries `access_token` and `instance_url`. Every other event sends `Authorization: Bearer {value.json.access_token}`, so each payload carries the token:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>"
}
```

The same event works for the JWT bearer flow (`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<signed JWT>`) and refresh tokens. Tokens expire with the org's session timeout; on `401 INVALID_SESSION_ID` call `GetToken` again. The example actions refresh it every hour.

Answers seen from the real Salesforce hosts without valid credentials: a fake client returns `400 {"error":"invalid_client_id"}`, a fake JWT `400 invalid_grant`, and any REST call with a fake token `401 [{"errorCode":"INVALID_SESSION_ID"}]`.

## Payload conventions

* `access_token`: the token from `GetToken`.
* `id`: an 18-character Salesforce record Id (work order `a2x...`, installed product, technician, Asset), or the query locator for `QueryMore`.
* `query`: `fields=Id,Name,...` for the get events, or `""` for all fields.
* `q`: a whole SOQL statement, URL-encoded (spaces as `+`).
* `technician_id`, `installed_product_id`, `serial`, `asset_id`: values the fixed queries put inside SOQL quotes.
* `body`: the JSON record, sent unchanged on `POST` and `PATCH` events.

Creates answer `201` with `{"id": "...", "success": true, "errors": []}`; updates answer an empty `204`. Errors are JSON arrays such as `[{"errorCode": "REQUIRED_FIELD_MISSING", "message": "...", "fields": [...]}]`.

> [!WARNING]
>
> `technician_id`, `installed_product_id`, `serial` and `asset_id` are inserted into SOQL as they are. Pass Salesforce Ids or serial numbers that come from your own system, never raw user text with quotes in it.

Create a work order from an alarm. `SVMXC__Component__c` is the installed product, `SVMXC__Company__c` the account:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "body": {
    "SVMXC__Company__c": "<Account Id>",
    "SVMXC__Component__c": "<installed product Id>",
    "SVMXC__Order_Type__c": "Field Service",
    "SVMXC__Priority__c": "High",
    "SVMXC__Problem_Description__c": "Alarm TT-101 = 92.4 C at 2026-10-06T06:15:00Z (Coreflux)"
  }
}
```

Close it. `SVMXC__Order_Status__c`, `SVMXC__Priority__c` and `SVMXC__Order_Type__c` are picklists that each org configures, so read the allowed values with `DescribeWorkOrder` first:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "id": "<work order Id>",
  "body": {
    "SVMXC__Order_Status__c": "Closed"
  }
}
```

To avoid one work order per repeated alarm, add a custom External ID field (for example `Coreflux_Alarm_Id__c`) to the work order and use `UpsertWorkOrderByExternalId`, or check `ListOpenWorkOrdersByInstalledProduct` first.

## Telemetry

ServiceMax Core has no standard telemetry field on `SVMXC__Installed_Product__c`. Add the custom fields you need (for example `Run_Hours__c` and `Last_Telemetry_At__c`) and write them with `UpdateInstalledProduct`, or for many machines at once with `UpdateRecordsBatch` (up to 200 records per call). Map a machine's serial number to its record with `FindInstalledProductBySerial`.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "id": "<installed product Id>",
  "body": {
    "Run_Hours__c": 1287.5,
    "Last_Telemetry_At__c": "2026-10-06T06:30:00Z",
    "SVMXC__Latitude__c": 41.1579,
    "SVMXC__Longitude__c": -8.6291
  }
}
```

On **Asset 360**, send readings as technical attributes instead. `A360SaveTechnicalAttributes` creates missing attributes, records the time of each reading and finds the Asset by Id, name or an identifier field (200 entries per call):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access_token from GetToken>",
  "body": {
    "source": "External System",
    "objectName": "Asset",
    "assetIdentifierFieldAPIName": "SerialNumber",
    "attributeList": [
      {
        "value": "10800",
        "unit": "Watt",
        "attributeKey": "EnergyConsumption",
        "dataType": "Number",
        "timeOfOccurence": "2026-10-06 06:30:00",
        "assetIdentifiers": [
          {
            "identifierName": "Serial Number",
            "value": "SN-PRESS-0042"
          }
        ]
      }
    ]
  }
}
```

## Notification receiver

Deploy `cmms_servicemax_webhook.lot` only if you want the org to push changes to the broker. It opens HTTP port `9011`.

| Event | Request | Published on | What it receives |
| - | - | - | - |
| `NotifyWorkOrders` | `POST /servicemax/notify/work-orders` | `cmms/servicemax/work-order-notification/received` | Flow HTTP Callout / Apex callout with JSON when a work order is created or changes (POST https\://`<public host>`/servicemax/notify/work-orders) |
| `NotifyInstalledProducts` | `POST /servicemax/notify/installed-products` | `cmms/servicemax/installed-product-notification/received` | Same for installed product / Asset changes |
| `NotifyEvents` | `POST /servicemax/notify/events` | `cmms/servicemax/notification/received` | Any other JSON callout (cases, Asset 360 objects). Filter on the body in a LoT action |

Salesforce has no built-in JSON webhook. Build a record-triggered Flow with an **HTTP Callout** action (or an Apex callout) on `SVMXC__Service_Order__c` or `SVMXC__Installed_Product__c`, point a Named Credential at the public URL of the matching path, and send the fields you need as JSON.

> [!WARNING]
>
> The receiver connector does not authenticate callers. Put a reverse proxy with a public TLS certificate in front of port `9011` and check a shared secret header that the Named Credential sends. Outbound Messages are SOAP and expect an `<Ack>true</Ack>` reply, which this connector does not send, so they are not supported.

## Connector

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — ServiceMax (PTC) on the Salesforce REST API v65.0 (beta): get an OAuth token, create
#   ServiceMax Core work orders (SVMXC__Service_Order__c) from alarms, upsert them by your own alarm id, list open work
#   orders by technician (SVMXC__Group_Member__c) or installed product, close them, find installed products
#   (SVMXC__Installed_Product__c) by serial number and PATCH them with telemetry (single or 200-record batch), read
#   technicians (SVMXC__Service_Group_Members__c), open Cases, publish Platform Events, and for Asset 360 orgs write
#   technical attributes, create standard WorkOrders and update Assets.
#   Postman file). Credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/servicemax
#
# Host: your Salesforce org's My Domain, https://YOUR_DOMAIN.my.salesforce.com (sandbox:
#   https://YOUR_DOMAIN--SANDBOX.sandbox.my.salesforce.com). Use the instance_url from the token reply. REST calls on
#   login.salesforce.com / test.salesforce.com answer 400 URL_NOT_RESET; those hosts only issue tokens.
# Auth: Salesforce OAuth 2.0 through an External Client App / Connected App. GetToken posts a form body
#   ({value.json.form}) to /services/oauth2/token on the My Domain: client credentials
#   (grant_type=client_credentials&client_id=...&client_secret=..., needs a Run As user), or the JWT bearer / password
#   / refresh_token grants. Every other event sends Authorization: Bearer {value.json.access_token}. Keep the
#   consumer key / secret in Hub secrets (SALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET) and the token on an
#   internal topic. Tokens expire per the org session timeout (401 INVALID_SESSION_ID): call GetToken again.
#   Live (2026-10-06): no or fake token -> 401 [{"errorCode":"INVALID_SESSION_ID"}]; fake client -> 400 invalid_client_id.
# Objects: ServiceMax Core (managed package SVMXC__) work orders, installed products and technicians. Asset 360
#   (SVMXA360__) orgs use the standard WorkOrder and Asset objects plus the technical attributes Apex REST service;
#   the A360* events need Asset 360, the others need ServiceMax Core. Picklist values (SVMXC__Order_Status__c,
#   SVMXC__Priority__c, SVMXC__Order_Type__c) are org-configurable: check them with DescribeWorkOrder.
# Payload fields (control fields stay out of bodies; request bodies come from {value.json.body}):
#   access_token, id, query, q, technician_id, installed_product_id, serial, asset_id, external_id_field,
#   external_id, event_name, form, body
#   q / query are URL-encoded (spaces as +). technician_id, installed_product_id, serial and asset_id are inserted
#   inside SOQL quotes: pass only Salesforce Ids or serials you trust (no quotes), never raw user input.
#     CreateWorkOrder         body = {"SVMXC__Component__c": "<installed product Id>", "SVMXC__Problem_Description__c": "..."}
#     UpdateWorkOrder         id = <work order Id>, body = {"SVMXC__Order_Status__c": "Closed"}
#     UpdateInstalledProduct  id = <installed product Id>, body = {"Run_Hours__c": 1287.5}   (custom telemetry fields)
#     A360SaveTechnicalAttributes body = {"source": "External System", "objectName": "Asset", "attributeList": [...]}
# Errors: JSON arrays [{"message","errorCode","fields"}]: 400 MALFORMED_QUERY / INVALID_FIELD /
#   REQUIRED_FIELD_MISSING / FIELD_CUSTOM_VALIDATION_EXCEPTION, 401 INVALID_SESSION_ID, 403 REQUEST_LIMIT_EXCEEDED or
#   no object access, 404 NOT_FOUND. Writes fire the org's ServiceMax triggers, flows, SLAs and dispatch rules.
#

DEFINE CONNECTOR ServiceMaxApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_DOMAIN.my.salesforce.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Get an access token from your My Domain (form body: client_credentials, or password / JWT bearer / refresh_token grants). Reply access_token + instance_url; send access_token on every other event
    ADD EVENT GetToken
        WITH SOURCE_TOPIC "cmms/servicemax/token/create"
        WITH DESTINATION_TOPIC "cmms/servicemax/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/oauth2/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    # Revoke an access or refresh token (form body token=...). Not a data delete
    ADD EVENT RevokeToken
        WITH SOURCE_TOPIC "cmms/servicemax/token/revoke"
        WITH DESTINATION_TOPIC "cmms/servicemax/token/revoke/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/oauth2/revoke"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
    # API versions the org serves (no auth needed). The route pins v65.0
    ADD EVENT ListApiVersions
        WITH SOURCE_TOPIC "cmms/servicemax/api-version/list"
        WITH DESTINATION_TOPIC "cmms/servicemax/api-version/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/"
        WITH HEADERS
            ADD "Accept" "application/json"
    # Org limits (DailyApiRequests Max / Remaining and more). Check before polling
    ADD EVENT GetLimits
        WITH SOURCE_TOPIC "cmms/servicemax/limit/get"
        WITH DESTINATION_TOPIC "cmms/servicemax/limit/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/limits"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # Any SOQL query, URL-encoded (spaces as +). Up to 2000 rows per page; nextRecordsUrl when done is false
    ADD EVENT Query
        WITH SOURCE_TOPIC "cmms/servicemax/soql/query"
        WITH DESTINATION_TOPIC "cmms/servicemax/soql/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/query?q={value.json.q}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # Next page of a query (the part of nextRecordsUrl after /query/)
    ADD EVENT QueryMore
        WITH SOURCE_TOPIC "cmms/servicemax/soql/next"
        WITH DESTINATION_TOPIC "cmms/servicemax/soql/next/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/query/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # Field list and the org's picklist values for SVMXC__Order_Status__c, SVMXC__Priority__c and SVMXC__Order_Type__c (they are configurable)
    ADD EVENT DescribeWorkOrder
        WITH SOURCE_TOPIC "cmms/servicemax/work-order-describe/get"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order-describe/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Service_Order__c/describe"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # One ServiceMax work order by record Id (query fields=... or "" for all)
    ADD EVENT GetWorkOrder
        WITH SOURCE_TOPIC "cmms/servicemax/work-order/get"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Service_Order__c/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # Open work orders assigned to one technician (SVMXC__Group_Member__c, not closed), next scheduled first, 200 max
    ADD EVENT ListOpenWorkOrdersByTechnician
        WITH SOURCE_TOPIC "cmms/servicemax/work-order/list-open-by-technician"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order/list-open-by-technician/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/query?q=SELECT+Id,Name,SVMXC__Order_Status__c,SVMXC__Priority__c,SVMXC__Order_Type__c,SVMXC__Component__c,SVMXC__Company__c,SVMXC__Scheduled_Date_Time__c,SVMXC__Problem_Description__c+FROM+SVMXC__Service_Order__c+WHERE+SVMXC__Group_Member__c='{value.json.technician_id}'+AND+SVMXC__Closed_On__c=null+ORDER+BY+SVMXC__Scheduled_Date_Time__c+LIMIT+200"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # Open work orders for one installed product (check before opening a duplicate from a repeating alarm)
    ADD EVENT ListOpenWorkOrdersByInstalledProduct
        WITH SOURCE_TOPIC "cmms/servicemax/work-order/list-open-by-installed-product"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order/list-open-by-installed-product/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/query?q=SELECT+Id,Name,SVMXC__Order_Status__c,SVMXC__Priority__c,SVMXC__Order_Type__c,SVMXC__Component__c,SVMXC__Company__c,SVMXC__Scheduled_Date_Time__c,SVMXC__Problem_Description__c+FROM+SVMXC__Service_Order__c+WHERE+SVMXC__Component__c='{value.json.installed_product_id}'+AND+SVMXC__Closed_On__c=null+LIMIT+200"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # WRITE: Create a ServiceMax work order from an alarm; reply 201 {id, success, errors}
    ADD EVENT CreateWorkOrder
        WITH SOURCE_TOPIC "cmms/servicemax/work-order/create"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Service_Order__c"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Change work order fields (status, priority, technician SVMXC__Group_Member__c, ...); reply 204 empty
    ADD EVENT UpdateWorkOrder
        WITH SOURCE_TOPIC "cmms/servicemax/work-order/update"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Service_Order__c/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Create or update a work order keyed by your own External ID field (one work order per alarm id). 201 created / 200 updated
    ADD EVENT UpsertWorkOrderByExternalId
        WITH SOURCE_TOPIC "cmms/servicemax/work-order/upsert"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order/upsert/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Service_Order__c/{value.json.external_id_field}/{value.json.external_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Installed product fields, including your custom telemetry fields and SVMXC__Status__c values
    ADD EVENT DescribeInstalledProduct
        WITH SOURCE_TOPIC "cmms/servicemax/installed-product-describe/get"
        WITH DESTINATION_TOPIC "cmms/servicemax/installed-product-describe/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Installed_Product__c/describe"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # One installed product by record Id
    ADD EVENT GetInstalledProduct
        WITH SOURCE_TOPIC "cmms/servicemax/installed-product/get"
        WITH DESTINATION_TOPIC "cmms/servicemax/installed-product/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Installed_Product__c/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # Map a machine serial number from MQTT to its installed product Id
    ADD EVENT FindInstalledProductBySerial
        WITH SOURCE_TOPIC "cmms/servicemax/installed-product/find-by-serial"
        WITH DESTINATION_TOPIC "cmms/servicemax/installed-product/find-by-serial/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/query?q=SELECT+Id,Name,SVMXC__Serial_Lot_Number__c,SVMXC__Status__c,SVMXC__Product__c,SVMXC__Company__c,SVMXC__Site__c,SVMXC__Parent__c+FROM+SVMXC__Installed_Product__c+WHERE+SVMXC__Serial_Lot_Number__c='{value.json.serial}'+LIMIT+5"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # WRITE: Telemetry on the installed product: your custom fields (e.g. Run_Hours__c) plus SVMXC__Status__c / SVMXC__Latitude__c / SVMXC__Longitude__c; reply 204
    ADD EVENT UpdateInstalledProduct
        WITH SOURCE_TOPIC "cmms/servicemax/installed-product/update"
        WITH DESTINATION_TOPIC "cmms/servicemax/installed-product/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Installed_Product__c/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Update up to 200 records in one call (sObject Collections), e.g. run hours for a whole line; reply per-record success / errors
    ADD EVENT UpdateRecordsBatch
        WITH SOURCE_TOPIC "cmms/servicemax/record-batch/update"
        WITH DESTINATION_TOPIC "cmms/servicemax/record-batch/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/services/data/v65.0/composite/sobjects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Active technicians / equipment (SVMXC__Service_Group_Members__c) with service team and Salesforce user
    ADD EVENT ListTechnicians
        WITH SOURCE_TOPIC "cmms/servicemax/technician/list"
        WITH DESTINATION_TOPIC "cmms/servicemax/technician/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/query?q=SELECT+Id,Name,SVMXC__Service_Group__c,SVMXC__Salesforce_User__c,SVMXC__Email__c,SVMXC__Active__c+FROM+SVMXC__Service_Group_Members__c+WHERE+SVMXC__Active__c=true+LIMIT+200"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # One technician / equipment record by Id
    ADD EVENT GetTechnician
        WITH SOURCE_TOPIC "cmms/servicemax/technician/get"
        WITH DESTINATION_TOPIC "cmms/servicemax/technician/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/sobjects/SVMXC__Service_Group_Members__c/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # WRITE: Open a Salesforce Case (the usual ServiceMax entry point before a work order is dispatched)
    ADD EVENT CreateCase
        WITH SOURCE_TOPIC "cmms/servicemax/case/create"
        WITH DESTINATION_TOPIC "cmms/servicemax/case/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/data/v65.0/sobjects/Case"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Publish a platform event you defined (e.g. Coreflux_Telemetry__e) for Flows / Apex triggers to act on
    ADD EVENT PublishPlatformEvent
        WITH SOURCE_TOPIC "cmms/servicemax/platform-event/publish"
        WITH DESTINATION_TOPIC "cmms/servicemax/platform-event/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/data/v65.0/sobjects/{value.json.event_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Asset 360 only: write telemetry as technical attributes (up to 200 entries, with time of occurrence) on Assets
    ADD EVENT A360SaveTechnicalAttributes
        WITH SOURCE_TOPIC "cmms/servicemax/a360-technical-attribute/save"
        WITH DESTINATION_TOPIC "cmms/servicemax/a360-technical-attribute/save/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/apexrest/SVMXA360/technicalAttribute/v1/saveTechnicalAttributes/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: Asset 360 only: create a standard WorkOrder on an Asset
    ADD EVENT A360CreateWorkOrder
        WITH SOURCE_TOPIC "cmms/servicemax/a360-work-order/create"
        WITH DESTINATION_TOPIC "cmms/servicemax/a360-work-order/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/data/v65.0/sobjects/WorkOrder"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # Asset 360 only: open standard WorkOrders for one Asset
    ADD EVENT A360ListOpenWorkOrdersByAsset
        WITH SOURCE_TOPIC "cmms/servicemax/a360-work-order/list-open-by-asset"
        WITH DESTINATION_TOPIC "cmms/servicemax/a360-work-order/list-open-by-asset/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/data/v65.0/query?q=SELECT+Id,WorkOrderNumber,Status,Priority,Subject,AssetId,OwnerId+FROM+WorkOrder+WHERE+AssetId='{value.json.asset_id}'+AND+IsClosed=false+LIMIT+200"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # WRITE: Asset 360 only: update a standard Asset (status or your custom telemetry fields)
    ADD EVENT A360UpdateAsset
        WITH SOURCE_TOPIC "cmms/servicemax/a360-asset/update"
        WITH DESTINATION_TOPIC "cmms/servicemax/a360-asset/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/services/data/v65.0/sobjects/Asset/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Notification receiver (optional):

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# ServiceMax notification receiver — REST_API route (server mode, beta, companion of ServicemaxRestApi.lot)
#   Receives JSON callouts that your Salesforce org sends when ServiceMax records change (a record-triggered Flow
#   with an HTTP Callout action, or an Apex trigger / queueable callout) and publishes the body on MQTT, so work
#   order and installed product changes reach the broker without polling. Opt-in: deploying it opens an HTTP port.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/servicemax
#
# Salesforce needs a public HTTPS URL registered as a Named Credential / External Credential (or Remote Site).
#   Put a reverse proxy or tunnel with a public TLS certificate in front of SERVER_PORT and check a shared
#   secret header there: this route does not authenticate callers. Salesforce Outbound Messages are SOAP and need
#   a SOAP <Ack>true</Ack> reply, which this route does not send, so use Flow HTTP Callouts / Apex (JSON) instead.
#   The body is whatever your Flow or Apex sends; treat it as JSON you defined.

DEFINE CONNECTOR ServiceMaxNotificationReceiver WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '9011'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Flow HTTP Callout / Apex callout with JSON when a work order is created or changes (POST https://<public host>/servicemax/notify/work-orders)
    ADD EVENT NotifyWorkOrders
        WITH ENDPOINT "/servicemax/notify/work-orders"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/servicemax/work-order-notification/received"
    # Same for installed product / Asset changes
    ADD EVENT NotifyInstalledProducts
        WITH ENDPOINT "/servicemax/notify/installed-products"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/servicemax/installed-product-notification/received"
    # Any other JSON callout (cases, Asset 360 objects). Filter on the body in a LoT action
    ADD EVENT NotifyEvents
        WITH ENDPOINT "/servicemax/notify/events"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "cmms/servicemax/notification/received"
```

## Example actions

These actions refresh the token every hour, open a work order when a compressor alarm is raised, write run hours to the installed product, and poll one technician's open work orders.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the ServiceMaxApi route (docs page). Not part of the route template.
# Secrets: SALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET (External Client App / Connected App with the client
#   credentials flow enabled and a Run As integration user that has the ServiceMax permission sets). The access
#   token is kept on the internal topic internal/servicemax/access_token. IDs (installed product, technician, account)
#   come from installed-product/find-by-serial and technician/list; replace the <...> placeholders below.

DEFINE ACTION ServiceMaxGetToken
ON EVERY 1 HOUR DO
    SET "cid" WITH GET SECRET "SALESFORCE_CLIENT_ID"
    SET "cs" WITH GET SECRET "SALESFORCE_CLIENT_SECRET"
    SET "form" WITH "grant_type=client_credentials&client_id=" + {cid} + "&client_secret=" + {cs}
    PUBLISH TOPIC "cmms/servicemax/token/create" WITH { "form": {form} }

DEFINE ACTION ServiceMaxKeepToken
ON TOPIC "cmms/servicemax/token/create/response" DO
    SET "tok" WITH (GET JSON "access_token" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/servicemax/access_token" WITH {tok}

DEFINE ACTION ServiceMaxWorkOrderFromAlarm
ON TOPIC "porto/line1/compressor/alarm/raised" DO
    SET "tok" WITH GET TOPIC "internal/servicemax/access_token" AS STRING
    SET "alarm" WITH (GET JSON "alarm" IN PAYLOAD AS STRING)
    SET "value" WITH (GET JSON "value" IN PAYLOAD AS STRING)
    SET "desc" WITH "Coreflux alarm " + {alarm} + " (value " + {value} + ")"
    PUBLISH TOPIC "cmms/servicemax/work-order/create" WITH { "access_token": {tok}, "body": { "SVMXC__Company__c": "<Account Id>", "SVMXC__Component__c": "<installed product Id>", "SVMXC__Order_Type__c": "Field Service", "SVMXC__Priority__c": "High", "SVMXC__Problem_Description__c": {desc} } }

DEFINE ACTION ServiceMaxRunHoursTelemetry
ON TOPIC "porto/line1/press01/run-hours" DO
    SET "tok" WITH GET TOPIC "internal/servicemax/access_token" AS STRING
    SET "hours" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "cmms/servicemax/installed-product/update" WITH { "access_token": {tok}, "id": "<installed product Id>", "body": { "Run_Hours__c": {hours} } }

DEFINE ACTION ServiceMaxPollTechnicianWorkOrders
ON EVERY 15 MINUTES DO
    SET "tok" WITH GET TOPIC "internal/servicemax/access_token" AS STRING
    PUBLISH TOPIC "cmms/servicemax/work-order/list-open-by-technician" WITH { "access_token": {tok}, "technician_id": "<technician Id>" }
```

## Notes

* The connector pins API `v65.0`. Change the version in the endpoints to move up; `ListApiVersions` shows what your org serves.
* "Open" in the fixed queries means `SVMXC__Closed_On__c` is empty. If your org cancels work orders without a close date, use `Query` with your own status filter.
* Every call counts against the org's rolling 24-hour API allocation (`GetLimits` shows `DailyApiRequests`). Over it, Salesforce answers `403 REQUEST_LIMIT_EXCEEDED`. Poll every few minutes, not per message.
* Queries return up to 2000 rows per page; when `done` is false, pass the end of `nextRecordsUrl` to `QueryMore`.
* Writes fire the org's ServiceMax triggers, flows, SLA clocks and dispatch rules.
* `PublishPlatformEvent` needs a platform event you define (for example `Coreflux_Telemetry__e`) that Flows or Apex triggers subscribe to.

## Not covered

Deletes, work detail lines and parts, ServiceMax SFM and dispatch services, Outbound Messages, Pub/Sub API and streaming subscriptions, Bulk API, files, and Asset 360 maintenance plans, warranties and service contracts. All are reachable through the Salesforce APIs and can be added to a fork.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Salesforce](/latest/lot-language/routes/rest-api-apps/salesforce)
* [ServiceMax Core: Work Order object](https://support.ptc.com/help/servicemaxcore/en/articles/core/work-order1.html)
* [Asset 360: technical attributes REST API](https://support.ptc.com/help/servicemax_asset360/en/articles/asset-360/creating-technical-attributes-through-rest-apis.html)
* [Salesforce REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/)


# ServiceNow
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/servicenow

LoT REST API connector for ServiceNow: open incidents from alarms, send Event Management events, patch CMDB CIs and create catalog tasks

Technical Preview

## Overview

A client-mode connector for a **curated ITSM / OT** slice of the [ServiceNow Table API](https://www.servicenow.com/docs/r/api-reference/rest-apis/c_TableAPI.html) and Event Management Connectors under `https://YOUR_INSTANCE.service-now.com`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| (discovery) | `GET /api/now/table/incident` | List incidents (`sysparm_limit` in template) |
| POST table/incident from alarm | `POST /api/now/table/incident` | Create incident (flat JSON fields) |
| POST em/inbound\_event (Event Management) | `POST /api/sn_em_connector/em/inbound_event?source=` | **Verified EM Connectors path** — not `/api/now/em/inbound_event` |
| PATCH table/cmdb\_ci/\{sys\_id} | `PATCH /api/now/table/cmdb_ci/{sys_id}` | Generic CI table; fork for specific CI classes if needed |
| GET table/sc\_task?sysparm\_query= | `GET /api/now/table/sc_task?sysparm_query=` | Catalog / fulfillment tasks |

`BASE_ADDRESS` is `https://{instance}.service-now.com` (no trailing slash; endpoints already include `/api/...`). Topics use `itsm/servicenow/<object>/<verb>`.

> [!NOTE]
>
> Catalog wording places `em/inbound_event` under `/api/now/`. Public Event Management Connectors documentation uses `/api/sn_em_connector/em/inbound_event?source={sourceName}` (for example `genericJson`). Configure a push connector / event rule on the instance before posting events.

> [!NOTE]
>
> Prefer Hub secrets for tokens and passwords.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — ServiceNow (Table API + EM curated slice)
# Auth: Bearer {value.json.access_token} (OAuth) or Basic via config
# BASE_ADDRESS: https://YOUR_INSTANCE.service-now.com

DEFINE CONNECTOR ServiceNowRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.service-now.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listincidents
        WITH SOURCE_TOPIC "itsm/servicenow/incident/list"
        WITH DESTINATION_TOPIC "itsm/servicenow/incident/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/now/table/incident?sysparm_limit={value.json.sysparm_limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createincident
        WITH SOURCE_TOPIC "itsm/servicenow/incident/create"
        WITH DESTINATION_TOPIC "itsm/servicenow/incident/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/now/table/incident"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Postinboundevent
        WITH SOURCE_TOPIC "itsm/servicenow/em/inbound_event"
        WITH DESTINATION_TOPIC "itsm/servicenow/em/inbound_event/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/sn_em_connector/em/inbound_event?source={value.json.source}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Patchcmdbci
        WITH SOURCE_TOPIC "itsm/servicenow/cmdb_ci/patch"
        WITH DESTINATION_TOPIC "itsm/servicenow/cmdb_ci/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/now/table/cmdb_ci/{value.json.sys_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Listsctasks
        WITH SOURCE_TOPIC "itsm/servicenow/sc_task/list"
        WITH DESTINATION_TOPIC "itsm/servicenow/sc_task/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/now/table/sc_task?sysparm_query={value.json.sysparm_query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Listincidents | GET | `/api/now/table/incident?sysparm_limit=` | `itsm/servicenow/incident/list` | `itsm/servicenow/incident/list/response` |
| Createincident | POST | `/api/now/table/incident` | `itsm/servicenow/incident/create` | `itsm/servicenow/incident/create/response` |
| Postinboundevent | POST | `/api/sn_em_connector/em/inbound_event?source=` | `itsm/servicenow/em/inbound_event` | `itsm/servicenow/em/inbound_event/response` |
| Patchcmdbci | PATCH | `/api/now/table/cmdb_ci/{sys_id}` | `itsm/servicenow/cmdb_ci/patch` | `itsm/servicenow/cmdb_ci/patch/response` |
| Listsctasks | GET | `/api/now/table/sc_task?sysparm_query=` | `itsm/servicenow/sc_task/list` | `itsm/servicenow/sc_task/list/response` |

## Auth

**OAuth 2.0 Bearer — default in the template:**

1. Register an OAuth application on the ServiceNow instance (System OAuth → Application Registry).
2. Obtain an `access_token`.
3. Set connector `BASE_ADDRESS` to `https://{instance}.service-now.com`.
4. Pass `access_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.access_token}`
5. Store the token in Hub secrets / `GET SECRET`. Never commit real credentials.

**Basic (username / password):**

1. Create an integration user with roles for Table API / Event Management as needed (e.g. `itil`, `rest_service`, EM connector roles).
2. Prefer `WITH USERNAME "integration.user"` and `WITH PASSWORD GET SECRET "SERVICENOW_PASSWORD"` on `REST_API_CONFIG` (remove Bearer header lines if using config Basic).

## Example payloads

**Create incident from alarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "short_description": "Line sensor fault — Zone A",
  "description": "Vibration above threshold at 2026-10-04T00:00:00Z",
  "urgency": "2",
  "impact": "2",
  "category": "Hardware"
}
```

**EM inbound event:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "source": "genericJson",
  "event_class": "IIoTAlarm",
  "node": "plc-line-a",
  "type": "High Vibration",
  "resource": "ZoneA/Sensor01",
  "severity": "3",
  "description": "Vibration above threshold"
}
```

**PATCH CMDB CI:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "sys_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "operational_status": "2",
  "short_description": "Updated from Coreflux telemetry"
}
```

**List sc\_task:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "sysparm_query": "state=1^ORDERBYnumber"
}
```

## Deploy notes

* Deploy **`ServiceNowRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/servicenow](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/servicenow)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# SharePoint and OneDrive (Microsoft Graph)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sharepoint-and-onedrive

LoT REST API connector for SharePoint and OneDrive via Microsoft Graph: upload files, create list items, list drive children and run large-file uploads

Technical Preview

## Overview

A client-mode connector for a **curated storage** slice of [Microsoft Graph OneDrive / SharePoint](https://learn.microsoft.com/en-us/graph/api/resources/onedrive) under `https://graph.microsoft.com/v1.0`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| PUT drives/\{id}/root:/\{path}:/content | `PUT /drives/{drive-id}/root:/{item-path}:/content` | Small file upload/replace (≤ \~250 MB) — Bearer Entra token |
| POST sites/\{id}/lists/\{id}/items | `POST /sites/{site-id}/lists/{list-id}/items` | Create list item (device register) — Bearer |
| GET drives/\{id}/root/children | `GET /drives/{drive-id}/root/children` | List children under drive root — Bearer |
| (supporting) createUploadSession | `POST /drives/{drive-id}/root:/{item-path}:/createUploadSession` | Large files — returns `uploadUrl` on another host |
| (supporting) GET by path | `GET /drives/{drive-id}/root:/{item-path}:` | driveItem metadata |
| (supporting) PUT upload chunk | `PUT {upload_path}` | **Host:** uploadUrl origin — no Authorization |

Default `BASE_ADDRESS` is `https://graph.microsoft.com/v1.0` (no trailing slash). Topics use `storage/sharepoint-and-onedrive/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Path encoding:** `item_path` is the path under the drive root **without** a leading slash (e.g. `FolderA/telemetry.csv`). URL-encode path segments in the publisher if they contain spaces or reserved characters. LoT ENDPOINT uses `/drives/{value.json.drive_id}/root:/{value.json.item_path}:/content`.

> [!NOTE]
>
> **Large upload sessions:** `createUploadSession` returns an `uploadUrl` that is **not** on `graph.microsoft.com`. When calling `Putuploadchunk`, set connector `BASE_ADDRESS` to that URL's origin (scheme + host + port) and put path + query in `upload_path`. Do not send a Graph `Authorization` header — the session URL embeds auth. Same pattern as Teams Workflows webhooks and S3 presigned PUT.

> [!NOTE]
>
> Prefer Hub secrets for Entra access tokens (`GET SECRET "GRAPH_ACCESS_TOKEN"` or `"SHAREPOINT_GRAPH_TOKEN"`). Typical scopes: `Files.ReadWrite.All`, `Sites.ReadWrite.All`, and `offline_access` for refresh.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — SharePoint and OneDrive (Microsoft Graph)
# Auth: Bearer {value.json.access_token}
# BASE_ADDRESS: https://graph.microsoft.com/v1.0
# Putuploadchunk: set BASE_ADDRESS to uploadUrl origin

DEFINE CONNECTOR SharepointAndOnedriveRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://graph.microsoft.com/v1.0"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Putdriveitemcontent
        WITH SOURCE_TOPIC "storage/sharepoint-and-onedrive/drive-item/put-content"
        WITH DESTINATION_TOPIC "storage/sharepoint-and-onedrive/drive-item/put-content/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/drives/{value.json.drive_id}/root:/{value.json.item_path}:/content"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Postlistitem
        WITH SOURCE_TOPIC "storage/sharepoint-and-onedrive/list-item/create"
        WITH DESTINATION_TOPIC "storage/sharepoint-and-onedrive/list-item/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sites/{value.json.site_id}/lists/{value.json.list_id}/items"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Listdrivechildren
        WITH SOURCE_TOPIC "storage/sharepoint-and-onedrive/drive-children/list"
        WITH DESTINATION_TOPIC "storage/sharepoint-and-onedrive/drive-children/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/drives/{value.json.drive_id}/root/children"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createuploadsession
        WITH SOURCE_TOPIC "storage/sharepoint-and-onedrive/drive-item/create-upload-session"
        WITH DESTINATION_TOPIC "storage/sharepoint-and-onedrive/drive-item/create-upload-session/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/drives/{value.json.drive_id}/root:/{value.json.item_path}:/createUploadSession"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Getdriveitembypath
        WITH SOURCE_TOPIC "storage/sharepoint-and-onedrive/drive-item/get-by-path"
        WITH DESTINATION_TOPIC "storage/sharepoint-and-onedrive/drive-item/get-by-path/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/drives/{value.json.drive_id}/root:/{value.json.item_path}:"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Putuploadchunk
        WITH SOURCE_TOPIC "storage/sharepoint-and-onedrive/upload-session/put-chunk"
        WITH DESTINATION_TOPIC "storage/sharepoint-and-onedrive/upload-session/put-chunk/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "{value.json.upload_path}"
        WITH HEADERS
            ADD "Content-Type" "application/octet-stream"
            ADD "Content-Length" "{value.json.content_length}"
            ADD "Content-Range" "{value.json.content_range}"
        WITH BODY "{payload}"
```

## Auth

1. **Graph events:** pass Entra ID `access_token` on each MQTT payload → `Authorization: Bearer {value.json.access_token}`. Prefer Hub secrets / `GET SECRET "GRAPH_ACCESS_TOKEN"` or `"SHAREPOINT_GRAPH_TOKEN"`. Never commit real tokens.
2. **Scopes:** `Files.ReadWrite.All` (drive content), `Sites.ReadWrite.All` (list items), `offline_access` (refresh). Application (client credentials) or delegated depending on your Entra app registration.
3. **Upload chunk:** no Authorization header. Split `uploadUrl` into origin → `BASE_ADDRESS` and path+query → `upload_path`. Send `Content-Range` / `Content-Length` as placeholders.

## MQTT topics

| Event | Source topic | Response topic |
| - | - | - |
| Putdriveitemcontent | `storage/sharepoint-and-onedrive/drive-item/put-content` | `…/response` |
| Postlistitem | `storage/sharepoint-and-onedrive/list-item/create` | `…/response` |
| Listdrivechildren | `storage/sharepoint-and-onedrive/drive-children/list` | `…/response` |
| Createuploadsession | `storage/sharepoint-and-onedrive/drive-item/create-upload-session` | `…/response` |
| Getdriveitembypath | `storage/sharepoint-and-onedrive/drive-item/get-by-path` | `…/response` |
| Putuploadchunk | `storage/sharepoint-and-onedrive/upload-session/put-chunk` | `…/response` |

## Example payloads

**List drive children** (`BASE_ADDRESS` = `https://graph.microsoft.com/v1.0`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "drive_id": "b!xxxxxxxx"
}
```

**Upload small file content:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "drive_id": "b!xxxxxxxx",
  "item_path": "IIoT/snapshots/line-1.csv",
  "content_type": "text/csv"
}
```

Publish the file bytes (or text) as the MQTT payload body that `{payload}` forwards. Ensure `content_type` matches the body. Path/header placeholders come from `value.json.*`.

**Create list item (device register):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "site_id": "contoso.sharepoint.com,guid,guid",
  "list_id": "LIST_GUID",
  "fields": {
    "Title": "device-42",
    "Status": "online"
  }
}
```

**Create upload session (large file):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ENTRA_ACCESS_TOKEN",
  "drive_id": "b!xxxxxxxx",
  "item_path": "IIoT/archives/big.bin",
  "item": {
    "@microsoft.graph.conflictBehavior": "replace"
  }
}
```

Then `Putuploadchunk` with `BASE_ADDRESS` = uploadUrl origin:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "upload_path": "/upn/…?guid=…",
  "content_length": "1048576",
  "content_range": "bytes 0-1048575/5242880"
}
```

## Sources

* [https://learn.microsoft.com/en-us/graph/api/driveitem-put-content](https://learn.microsoft.com/en-us/graph/api/driveitem-put-content)
* [https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession](https://learn.microsoft.com/en-us/graph/api/driveitem-createuploadsession)
* [https://learn.microsoft.com/en-us/graph/api/driveitem-list-children](https://learn.microsoft.com/en-us/graph/api/driveitem-list-children)
* [https://learn.microsoft.com/en-us/graph/api/listitem-create](https://learn.microsoft.com/en-us/graph/api/listitem-create)
* [https://learn.microsoft.com/en-us/graph/api/driveitem-get](https://learn.microsoft.com/en-us/graph/api/driveitem-get)
* [https://learn.microsoft.com/en-us/graph/api/resources/onedrive](https://learn.microsoft.com/en-us/graph/api/resources/onedrive)
* [https://learn.microsoft.com/en-us/graph/api/resources/sharepoint](https://learn.microsoft.com/en-us/graph/api/resources/sharepoint)
* [https://learn.microsoft.com/en-us/connectors/sharepointonline/](https://learn.microsoft.com/en-us/connectors/sharepointonline/)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Amazon S3](/latest/lot-language/routes/rest-api-apps/amazon-s3)
* [Azure Blob Storage and Data Lake Gen2](/latest/lot-language/routes/rest-api-apps/azure-blob-storage-and-data-lake-gen2)
* [MinIO](/latest/lot-language/routes/rest-api-apps/minio)


# Shelly Cloud Control
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/shelly-cloud-control

LoT REST API connector for the Shelly Cloud Control API v2: list devices and set switches, covers, lights and groups from MQTT with a cloud auth key

Technical Preview

## Overview

Client-mode REST API connectors for Shelly Gen2+ devices (local RPC over HTTP) and the Shelly Cloud Control API v2: switch, cover, light, power and 3-phase energy meter status, energy history, webhooks, relay and cover control.

This is one of the templates in the Shelly (Gen2+ local RPC and Shelly Cloud) REST API app (`shelly`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["none (local, device auth off)", "auth\_key query parameter (cloud)"]
* **secret**: SHELLY\_CLOUD\_AUTH\_KEY
* **note**: Local HTTP RPC uses SHA-256 Digest (RFC 7616) when auth is enabled; the REST\_API connector cannot answer the per-request nonce challenge, so protected devices return 401 except Shelly.GetDeviceInfo and /shelly. Use the device's native MQTT (\<shelly-id>/rpc) or the cloud connector for protected devices.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Shelly Cloud Control connector | no |
| `BaseUrl` | string | Shelly Cloud Control base URL without trailing slash (e.g. [https://shelly-49-eu.shelly.cloud](https://shelly-49-eu.shelly.cloud)) | yes |

`BASE_ADDRESS` default: `https://shelly-49-eu.shelly.cloud`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CloudGetDevices` | POST | `/v2/devices/api/get?auth_key={value.json.auth_key}` | `energy/shelly/cloud/devices/get` | `energy/shelly/cloud/devices/get/response` | `auth_key`, `body` |
| `CloudSetSwitch` | POST | `/v2/devices/api/set/switch?auth_key={value.json.auth_key}` | `energy/shelly/cloud/switch/set` | `energy/shelly/cloud/switch/set/response` | `auth_key`, `body` |
| `CloudSetCover` | POST | `/v2/devices/api/set/cover?auth_key={value.json.auth_key}` | `energy/shelly/cloud/cover/set` | `energy/shelly/cloud/cover/set/response` | `auth_key`, `body` |
| `CloudSetLight` | POST | `/v2/devices/api/set/light?auth_key={value.json.auth_key}` | `energy/shelly/cloud/light/set` | `energy/shelly/cloud/light/set/response` | `auth_key`, `body` |
| `CloudSetGroups` | POST | `/v2/devices/api/set/groups?auth_key={value.json.auth_key}` | `energy/shelly/cloud/groups/set` | `energy/shelly/cloud/groups/set/response` | `auth_key`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SHELLY_CLOUD_CONTROL"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ShellyCloudControl WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://shelly-49-eu.shelly.cloud"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '10'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CloudGetDevices
        WITH SOURCE_TOPIC "energy/shelly/cloud/devices/get"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/devices/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/get?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetSwitch
        WITH SOURCE_TOPIC "energy/shelly/cloud/switch/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/switch/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/switch?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetCover
        WITH SOURCE_TOPIC "energy/shelly/cloud/cover/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/cover/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/cover?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetLight
        WITH SOURCE_TOPIC "energy/shelly/cloud/light/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/light/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/light?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetGroups
        WITH SOURCE_TOPIC "energy/shelly/cloud/groups/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/groups/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/groups?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `CloudGetDevices` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/shelly/cloud/devices/get/response' &
mosquitto_pub -t 'energy/shelly/cloud/devices/get' -m '{"auth_key": "<auth_key>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Shelly Gen2 Rpc
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/shelly-gen2-rpc

LoT REST API connector for Shelly Gen2+ local RPC over HTTP: read device, switch, cover, light and energy meter status, control relays and manage webhooks

Technical Preview

## Overview

Client-mode REST API connectors for Shelly Gen2+ devices (local RPC over HTTP) and the Shelly Cloud Control API v2: switch, cover, light, power and 3-phase energy meter status, energy history, webhooks, relay and cover control.

This is one of the templates in the Shelly (Gen2+ local RPC and Shelly Cloud) REST API app (`shelly`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

* **schemes**: \["none (local, device auth off)", "auth\_key query parameter (cloud)"]
* **secret**: SHELLY\_CLOUD\_AUTH\_KEY
* **note**: Local HTTP RPC uses SHA-256 Digest (RFC 7616) when auth is enabled; the REST\_API connector cannot answer the per-request nonce challenge, so protected devices return 401 except Shelly.GetDeviceInfo and /shelly. Use the device's native MQTT (\<shelly-id>/rpc) or the cloud connector for protected devices.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Shelly Gen2 Rpc connector | no |
| `BaseUrl` | string | Shelly Gen2 Rpc base URL without trailing slash (e.g. [http://192.168.33.1](http://192.168.33.1)) | yes |

`BASE_ADDRESS` default: `http://192.168.33.1`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `GetShellyIdentity` | GET | `/shelly` | `energy/shelly/identity/get` | `energy/shelly/identity/get/response` | none |
| `GetDeviceInfo` | GET | `/rpc/Shelly.GetDeviceInfo` | `energy/shelly/device-info/get` | `energy/shelly/device-info/get/response` | none |
| `GetStatus` | GET | `/rpc/Shelly.GetStatus` | `energy/shelly/status/get` | `energy/shelly/status/get/response` | none |
| `GetConfig` | GET | `/rpc/Shelly.GetConfig` | `energy/shelly/config/get` | `energy/shelly/config/get/response` | none |
| `ListMethods` | GET | `/rpc/Shelly.ListMethods` | `energy/shelly/methods/get` | `energy/shelly/methods/get/response` | none |
| `CheckForUpdate` | GET | `/rpc/Shelly.CheckForUpdate` | `energy/shelly/update/check` | `energy/shelly/update/check/response` | none |
| `SysGetStatus` | GET | `/rpc/Sys.GetStatus` | `energy/shelly/sys/status/get` | `energy/shelly/sys/status/get/response` | none |
| `SwitchGetStatus` | GET | `/rpc/Switch.GetStatus?id={value.json.id}` | `energy/shelly/switch/status/get` | `energy/shelly/switch/status/get/response` | `id` |
| `SwitchGetConfig` | GET | `/rpc/Switch.GetConfig?id={value.json.id}` | `energy/shelly/switch/config/get` | `energy/shelly/switch/config/get/response` | `id` |
| `InputGetStatus` | GET | `/rpc/Input.GetStatus?id={value.json.id}` | `energy/shelly/input/status/get` | `energy/shelly/input/status/get/response` | `id` |
| `CoverGetStatus` | GET | `/rpc/Cover.GetStatus?id={value.json.id}` | `energy/shelly/cover/status/get` | `energy/shelly/cover/status/get/response` | `id` |
| `LightGetStatus` | GET | `/rpc/Light.GetStatus?id={value.json.id}` | `energy/shelly/light/status/get` | `energy/shelly/light/status/get/response` | `id` |
| `Pm1GetStatus` | GET | `/rpc/PM1.GetStatus?id={value.json.id}` | `energy/shelly/pm1/status/get` | `energy/shelly/pm1/status/get/response` | `id` |
| `EmGetStatus` | GET | `/rpc/EM.GetStatus?id={value.json.id}` | `energy/shelly/em/status/get` | `energy/shelly/em/status/get/response` | `id` |
| `EmDataGetStatus` | GET | `/rpc/EMData.GetStatus?id={value.json.id}` | `energy/shelly/emdata/status/get` | `energy/shelly/emdata/status/get/response` | `id` |
| `EmDataGetData` | GET | `/rpc/EMData.GetData?id={value.json.id}&ts={value.json.ts}&end_ts={value.json.end_ts}` | `energy/shelly/emdata/data/get` | `energy/shelly/emdata/data/get/response` | `end_ts`, `id`, `ts` |
| `TemperatureGetStatus` | GET | `/rpc/Temperature.GetStatus?id={value.json.id}` | `energy/shelly/temperature/status/get` | `energy/shelly/temperature/status/get/response` | `id` |
| `WebhookList` | GET | `/rpc/Webhook.List` | `energy/shelly/webhook/list` | `energy/shelly/webhook/list/response` | none |
| `SwitchSet` | POST | `/rpc/Switch.Set` | `energy/shelly/switch/set` | `energy/shelly/switch/set/response` | `body` |
| `SwitchToggle` | POST | `/rpc/Switch.Toggle` | `energy/shelly/switch/toggle` | `energy/shelly/switch/toggle/response` | `body` |
| `CoverOpen` | POST | `/rpc/Cover.Open` | `energy/shelly/cover/open` | `energy/shelly/cover/open/response` | `body` |
| `CoverClose` | POST | `/rpc/Cover.Close` | `energy/shelly/cover/close` | `energy/shelly/cover/close/response` | `body` |
| `CoverStop` | POST | `/rpc/Cover.Stop` | `energy/shelly/cover/stop` | `energy/shelly/cover/stop/response` | `body` |
| `CoverGoToPosition` | POST | `/rpc/Cover.GoToPosition` | `energy/shelly/cover/position/set` | `energy/shelly/cover/position/set/response` | `body` |
| `LightSet` | POST | `/rpc/Light.Set` | `energy/shelly/light/set` | `energy/shelly/light/set/response` | `body` |
| `WebhookCreate` | POST | `/rpc/Webhook.Create` | `energy/shelly/webhook/create` | `energy/shelly/webhook/create/response` | `body` |
| `WebhookDelete` | POST | `/rpc/Webhook.Delete` | `energy/shelly/webhook/delete` | `energy/shelly/webhook/delete/response` | `body` |
| `Reboot` | POST | `/rpc/Shelly.Reboot` | `energy/shelly/reboot` | `energy/shelly/reboot/response` | `body` |
| `Rpc` | POST | `/rpc` | `energy/shelly/rpc` | `energy/shelly/rpc/response` | `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SHELLY_GEN2_RPC"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ShellyGen2Rpc WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://192.168.33.1"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '10'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetShellyIdentity
        WITH SOURCE_TOPIC "energy/shelly/identity/get"
        WITH DESTINATION_TOPIC "energy/shelly/identity/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/shelly"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetDeviceInfo
        WITH SOURCE_TOPIC "energy/shelly/device-info/get"
        WITH DESTINATION_TOPIC "energy/shelly/device-info/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Shelly.GetDeviceInfo"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetStatus
        WITH SOURCE_TOPIC "energy/shelly/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Shelly.GetStatus"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetConfig
        WITH SOURCE_TOPIC "energy/shelly/config/get"
        WITH DESTINATION_TOPIC "energy/shelly/config/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Shelly.GetConfig"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListMethods
        WITH SOURCE_TOPIC "energy/shelly/methods/get"
        WITH DESTINATION_TOPIC "energy/shelly/methods/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Shelly.ListMethods"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT CheckForUpdate
        WITH SOURCE_TOPIC "energy/shelly/update/check"
        WITH DESTINATION_TOPIC "energy/shelly/update/check/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Shelly.CheckForUpdate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT SysGetStatus
        WITH SOURCE_TOPIC "energy/shelly/sys/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/sys/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Sys.GetStatus"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT SwitchGetStatus
        WITH SOURCE_TOPIC "energy/shelly/switch/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/switch/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Switch.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT SwitchGetConfig
        WITH SOURCE_TOPIC "energy/shelly/switch/config/get"
        WITH DESTINATION_TOPIC "energy/shelly/switch/config/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Switch.GetConfig?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT InputGetStatus
        WITH SOURCE_TOPIC "energy/shelly/input/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/input/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Input.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT CoverGetStatus
        WITH SOURCE_TOPIC "energy/shelly/cover/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/cover/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Cover.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT LightGetStatus
        WITH SOURCE_TOPIC "energy/shelly/light/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/light/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Light.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT Pm1GetStatus
        WITH SOURCE_TOPIC "energy/shelly/pm1/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/pm1/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/PM1.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT EmGetStatus
        WITH SOURCE_TOPIC "energy/shelly/em/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/em/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/EM.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT EmDataGetStatus
        WITH SOURCE_TOPIC "energy/shelly/emdata/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/emdata/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/EMData.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT EmDataGetData
        WITH SOURCE_TOPIC "energy/shelly/emdata/data/get"
        WITH DESTINATION_TOPIC "energy/shelly/emdata/data/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/EMData.GetData?id={value.json.id}&ts={value.json.ts}&end_ts={value.json.end_ts}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT TemperatureGetStatus
        WITH SOURCE_TOPIC "energy/shelly/temperature/status/get"
        WITH DESTINATION_TOPIC "energy/shelly/temperature/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Temperature.GetStatus?id={value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT WebhookList
        WITH SOURCE_TOPIC "energy/shelly/webhook/list"
        WITH DESTINATION_TOPIC "energy/shelly/webhook/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rpc/Webhook.List"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT SwitchSet
        WITH SOURCE_TOPIC "energy/shelly/switch/set"
        WITH DESTINATION_TOPIC "energy/shelly/switch/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Switch.Set"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT SwitchToggle
        WITH SOURCE_TOPIC "energy/shelly/switch/toggle"
        WITH DESTINATION_TOPIC "energy/shelly/switch/toggle/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Switch.Toggle"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CoverOpen
        WITH SOURCE_TOPIC "energy/shelly/cover/open"
        WITH DESTINATION_TOPIC "energy/shelly/cover/open/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Cover.Open"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CoverClose
        WITH SOURCE_TOPIC "energy/shelly/cover/close"
        WITH DESTINATION_TOPIC "energy/shelly/cover/close/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Cover.Close"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CoverStop
        WITH SOURCE_TOPIC "energy/shelly/cover/stop"
        WITH DESTINATION_TOPIC "energy/shelly/cover/stop/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Cover.Stop"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CoverGoToPosition
        WITH SOURCE_TOPIC "energy/shelly/cover/position/set"
        WITH DESTINATION_TOPIC "energy/shelly/cover/position/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Cover.GoToPosition"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT LightSet
        WITH SOURCE_TOPIC "energy/shelly/light/set"
        WITH DESTINATION_TOPIC "energy/shelly/light/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Light.Set"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT WebhookCreate
        WITH SOURCE_TOPIC "energy/shelly/webhook/create"
        WITH DESTINATION_TOPIC "energy/shelly/webhook/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Webhook.Create"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT WebhookDelete
        WITH SOURCE_TOPIC "energy/shelly/webhook/delete"
        WITH DESTINATION_TOPIC "energy/shelly/webhook/delete/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Webhook.Delete"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT Reboot
        WITH SOURCE_TOPIC "energy/shelly/reboot"
        WITH DESTINATION_TOPIC "energy/shelly/reboot/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/Shelly.Reboot"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT Rpc
        WITH SOURCE_TOPIC "energy/shelly/rpc"
        WITH DESTINATION_TOPIC "energy/shelly/rpc/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `GetShellyIdentity` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/shelly/identity/get/response' &
mosquitto_pub -t 'energy/shelly/identity/get' -m '{}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Shopify
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/shopify

LoT REST API connector for the Shopify GraphQL Admin API: adjust inventory from sensor counts, publish pick lists to MQTT, look up SKUs and list locations

Technical Preview

## Overview

A client-mode connector for the [Shopify GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql) (version `2026-10`). Use it to connect the shop floor to your online store: when a counter or scale reports finished goods, adjust the sellable stock in Shopify, and push the list of open, unfulfilled orders to MQTT so a packing line or pick-to-light system can work through it.

Every GraphQL event is a `POST` to `/admin/api/2026-10/graphql.json`. The event only decides the MQTT topics; the GraphQL document and its variables travel in the payload as `body`. Canonical bodies for each event are below.

| Event | Request | Notes |
| - | - | - |
| GetShop | `POST /admin/api/2026-10/graphql.json` (`shop`) | Smoke and store check |
| GetLocations | `POST …/graphql.json` (`locations`) | Location ids (`gid://shopify/Location/…`) for inventory changes |
| GetInventoryItems | `POST …/graphql.json` (`inventoryItems`) | Find an inventory item by SKU, with `available` and `on_hand` per location |
| AdjustInventoryQuantities | `POST …/graphql.json` (`inventoryAdjustQuantities`) | Add or remove stock by a delta, with an idempotency key |
| GetOrders | `POST …/graphql.json` (`orders`) | Open, unfulfilled orders with line items (pick list), paged by cursor |
| ClientCredentialsToken | `POST /admin/oauth/access_token` | Exchanges client id and secret for a 24-hour access token |

Topics use `finance/shopify/<object>/<verb>`; replies land on `<topic>/response`. Set `BASE_ADDRESS` to your store's permanent `https://<store>.myshopify.com` domain (not a custom storefront domain).

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** every GraphQL call sends the `X-Shopify-Access-Token` header with `access_token` from the payload. Get a token in one of these ways:
>
> * **Dev Dashboard app, client credentials.** Create an app in the [Dev Dashboard](https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens) in the same Shopify organisation as the store, install it with the scopes below, and publish its client id and secret to ClientCredentialsToken. The token lasts 24 hours (`expires_in` 86399). This only works for stores in your own organisation; other stores answer `shop_not_permitted`.
> * **Existing admin-created custom app.** Its `shpat_…` Admin API access token does not expire. New admin-created custom apps can no longer be made.
> * **Public or custom-distribution app.** Run the authorization code grant outside the broker and pass the token.
>
> Scopes: `read_orders`, `read_inventory`, `write_inventory`, `read_locations` and `read_products`. Keep credentials in Hub secrets (suggested names `SHOPIFY_STORE`, `SHOPIFY_CLIENT_ID`, `SHOPIFY_CLIENT_SECRET`, `SHOPIFY_ACCESS_TOKEN`). Never commit them into the `.lot`.

> [!WARNING]
>
> **Idempotency is required.** From API version `2026-04`, `inventoryAdjustQuantities` must carry the `@idempotent(key: …)` directive. Use one key per physical count event (for example `line3-counter7-000123`) and send the same key when you retry, so a retried message never counts stock twice. Shopify remembers keys for 24 hours. Each change must also set `changeFromQuantity`: the quantity you expect before the change (Shopify rejects the change with `CHANGE_FROM_QUANTITY_STALE` if it moved), or `null` to skip that check.

> [!TIP]
>
> **GraphQL errors come back with HTTP 200.** Check the top-level `errors` array (syntax, `THROTTLED`, access denied) and the mutation's `userErrors` array (validation) in every reply. Only a bad token (**401**), a wrong store (**404**) and a few store states (**402**, **423**) change the HTTP status.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ShopifyAdminGraphqlApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_STORE.myshopify.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: X-Shopify-Access-Token {value.json.access_token}; replace YOUR_STORE. Never commit tokens.
    ADD EVENT GetShop
        WITH SOURCE_TOPIC "finance/shopify/shop/get"
        WITH DESTINATION_TOPIC "finance/shopify/shop/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin/api/2026-10/graphql.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Shopify-Access-Token" "{value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetLocations
        WITH SOURCE_TOPIC "finance/shopify/location/list"
        WITH DESTINATION_TOPIC "finance/shopify/location/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin/api/2026-10/graphql.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Shopify-Access-Token" "{value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetInventoryItems
        WITH SOURCE_TOPIC "finance/shopify/inventory-item/list"
        WITH DESTINATION_TOPIC "finance/shopify/inventory-item/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin/api/2026-10/graphql.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Shopify-Access-Token" "{value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT AdjustInventoryQuantities
        WITH SOURCE_TOPIC "finance/shopify/inventory/adjust"
        WITH DESTINATION_TOPIC "finance/shopify/inventory/adjust/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin/api/2026-10/graphql.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Shopify-Access-Token" "{value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetOrders
        WITH SOURCE_TOPIC "finance/shopify/order/list"
        WITH DESTINATION_TOPIC "finance/shopify/order/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin/api/2026-10/graphql.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Shopify-Access-Token" "{value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ClientCredentialsToken
        WITH SOURCE_TOPIC "finance/shopify/oauth/token"
        WITH DESTINATION_TOPIC "finance/shopify/oauth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin/oauth/access_token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "grant_type=client_credentials&client_id={value.json.client_id}&client_secret={value.json.client_secret}"
```

## MQTT examples

### Get a token (client credentials)

Publish to `finance/shopify/oauth/token`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "client_id": "<from SHOPIFY_CLIENT_ID>",
  "client_secret": "<from SHOPIFY_CLIENT_SECRET>"
}
```

Reply on `finance/shopify/oauth/token/response`: `{"access_token":"…","scope":"read_inventory,write_inventory,…","expires_in":86399}`.

### Find the inventory item for a SKU

Publish to `finance/shopify/inventory-item/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from SHOPIFY_ACCESS_TOKEN>",
  "body": {
    "query": "query InventoryBySku($q: String!) { inventoryItems(first: 5, query: $q) { nodes { id sku tracked inventoryLevels(first: 10) { nodes { location { id name } quantities(names: [\"available\", \"on_hand\"]) { name quantity } } } } } }",
    "variables": {
      "q": "sku:CF-SEAL-01"
    }
  }
}
```

The reply gives the inventory item id, and for each location its id and the `available` and `on_hand` quantities. Use these ids in the adjustment. `GetLocations` lists all locations (`{"query":"query Locations($first: Int!) { locations(first: $first) { nodes { id name isActive } } }","variables":{"first":20}}`).

### Adjust stock from a sensor count

Publish to `finance/shopify/inventory/adjust` (here: 5 finished units counted on line 3):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from SHOPIFY_ACCESS_TOKEN>",
  "body": {
    "query": "mutation AdjustFromSensor($input: InventoryAdjustQuantitiesInput!, $idempotencyKey: String!) { inventoryAdjustQuantities(input: $input) @idempotent(key: $idempotencyKey) { inventoryAdjustmentGroup { id createdAt reason referenceDocumentUri changes { name delta quantityAfterChange } } userErrors { field message code } } }",
    "variables": {
      "idempotencyKey": "line3-counter7-000123",
      "input": {
        "reason": "correction",
        "name": "available",
        "referenceDocumentUri": "gid://coreflux/SensorCount/line3-counter7-000123",
        "changes": [
          {
            "delta": 5,
            "inventoryItemId": "gid://shopify/InventoryItem/30322695",
            "locationId": "gid://shopify/Location/124656943",
            "changeFromQuantity": null
          }
        ]
      }
    }
  }
}
```

`delta` is the change, not the new total. Use a negative delta to remove stock. `reason` must be one of Shopify's reasons, for example `correction`, `cycle_count_available` or `received`. `referenceDocumentUri` shows up in the store's inventory history, so point it at your own system (`gid://coreflux/…`). A good reply has `"userErrors": []` and `quantityAfterChange` for each change.

### Publish the pick list

Publish to `finance/shopify/order/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from SHOPIFY_ACCESS_TOKEN>",
  "body": {
    "query": "query PickList($q: String, $after: String) { orders(first: 25, after: $after, query: $q, sortKey: CREATED_AT) { nodes { id name createdAt displayFulfillmentStatus lineItems(first: 50) { nodes { sku name quantity } } } pageInfo { hasNextPage endCursor } } }",
    "variables": {
      "q": "status:open fulfillment_status:unfulfilled",
      "after": null
    }
  }
}
```

The reply lists open, unfulfilled orders with SKU, name and quantity for each line. When `pageInfo.hasNextPage` is `true`, publish again with `"after"` set to `pageInfo.endCursor`. `read_orders` only reaches recent orders; older ones need the `read_all_orders` scope.

### Smoke test

Publish to `finance/shopify/shop/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<from SHOPIFY_ACCESS_TOKEN>",
  "body": {
    "query": "query Shop { shop { name myshopifyDomain currencyCode } }",
    "variables": {}
  }
}
```

## Keeping the token

Client-credentials tokens last 24 hours. These two actions fetch a new one from Hub secrets twice a day and store it:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ShopifyTokenFromSecrets
ON EVERY 12 HOURS DO
    SET "cid" WITH GET SECRET "SHOPIFY_CLIENT_ID"
    SET "csecret" WITH GET SECRET "SHOPIFY_CLIENT_SECRET"
    PUBLISH TOPIC "finance/shopify/oauth/token" WITH { "client_id": {cid}, "client_secret": {csecret} }

DEFINE ACTION ShopifyKeepToken
ON TOPIC "finance/shopify/oauth/token/response" DO
    SET "access" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    IF {access} != "null" THEN
        KEEP SECRET "SHOPIFY_ACCESS_TOKEN" WITH {access}
```

Restrict who can read the `finance/shopify/#` topics with a rule, because these payloads carry tokens and client credentials.

## Webhooks (companion, not packaged)

Shopify can `POST` an `orders/create` [webhook](https://shopify.dev/docs/apps/build/webhooks/subscribe/https) to an HTTPS URL. Each delivery carries `X-Shopify-Hmac-SHA256`, a base64 HMAC-SHA256 of the raw body made with the app's client secret, and should be rejected if it does not match. A REST API connector in server mode cannot check that signature, so the receiver is not part of this template. Options: put a verifying proxy in front of a separate `ENABLE_SERVER` connector, use Shopify's Amazon EventBridge or Google Cloud Pub/Sub delivery, or poll GetOrders on a timer (for example with `created_at:>…` in `q`).

## Notes

* API versions are released every quarter and each is supported for at least 12 months. `2026-10` is accessible until October 2027. Change the version in each `ENDPOINT` when you upgrade; a retired version is answered by the oldest supported one.
* Rate limits use a calculated query cost in a leaky bucket per app and store; the size and restore rate depend on the store's plan. Each reply carries `extensions.cost`. On `THROTTLED`, wait and retry with the same idempotency key.
* Common errors: **401** `[API] Invalid API key or access token` (bad or expired token), `ACCESS_DENIED` in `errors` (missing scope), `userErrors` such as `CHANGE_FROM_QUANTITY_STALE` or an invalid reason, **404** (wrong store domain).
* Not covered: the REST Admin API (legacy), bulk operations, product and fulfillment mutations, `inventorySetQuantities` (sets an absolute quantity).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Shopify: inventoryAdjustQuantities](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryAdjustQuantities)
* [Shopify: orders query](https://shopify.dev/docs/api/admin-graphql/latest/queries/orders)
* [Shopify: implementing idempotency](https://shopify.dev/docs/apps/build/apis/graphql-admin/implementing-idempotency)
* [Shopify: client credentials tokens](https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens)
* [Shopify API versioning](https://shopify.dev/docs/api/usage/versioning)


# Siemens Industrial Edge Management
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/siemens-industrial-edge-management

LoT REST API connector for Siemens Industrial Edge Management: list Edge Devices, browse the app catalog, deploy and manage apps, and follow install jobs

Technical Preview

## Overview

One client-mode connector, **SiemensIEM**, for the Portal Public API of a self-hosted Siemens Industrial Edge Management (IEM-OS, or IEM Pro on Kubernetes). IEM is the central place where you onboard Industrial Edge Devices (IEDs) and deploy Industrial Edge apps to them. With this connector the broker can publish your edge fleet into the Unified Namespace (device status, statistics, installed apps) and drive app rollouts from MQTT: deploy an app, restart or stop it, push a new app configuration, then follow the batch until every device job is `COMPLETED`.

The connector talks to the IEM management API only. Data on the devices themselves (Databus MQTT, connectors, IIH) is not part of this connector.

| Event | Topic | Request | Notes |
| - | - | - | - |
| Login | `mes/siemens-iem/token/create` | `POST /portal/api/v1/login/direct` | Username/password (or technical user) -> data.access\_token, valid 24 h |
| VerifyToken | `mes/siemens-iem/token/verify` | `GET /portal/api/v1/auth-tokens/verify` | Returns the auth details of the token |
| Logout | `mes/siemens-iem/token/delete` | `GET /portal/api/v1/logout` | Invalidates the token (IEM-OS only; not on IEM on Kubernetes) |
| ListDevices | `mes/siemens-iem/device/list` | `GET /portal/api/v1/devices` | query: page=0\&size=50 (send "" for defaults) |
| GetDevice | `mes/siemens-iem/device/get` | `GET /portal/api/v1/devices/{id}` | data.deviceStatus, deviceVersion, deviceTypeId, ... |
| GetDeviceStatistics | `mes/siemens-iem/device-statistics/get` | `GET /portal/api/v1/devices/{id}/statistics` | Last statistics the device sent (app counts, network, resources) |
| ListInstalledApps | `mes/siemens-iem/device-app/list` | `GET /portal/api/v1/devices/installed-apps` | query: deviceid=\<id> (send "" for all devices) |
| ListCatalogApps | `mes/siemens-iem/application/list` | `GET /portal/api/v1/applications` | Catalog applications with their 32-char application ids |
| GetApplication | `mes/siemens-iem/application/get` | `GET /portal/api/v1/applications/{id}` | Application details and versions |
| ListAppConfigs | `mes/siemens-iem/application-config/list` | `GET /portal/api/v1/applications/{id}/configs` | Config ids, template ids and version ids for updateAppConfig |
| DeployApplication | `mes/siemens-iem/application/deploy` | `POST /portal/api/v1/batches` | Install a catalog app on devices; form = multipart infoMap \{"devices":\[...]} -> data = batch id |
| ApplicationCommand | `mes/siemens-iem/application/command` | `POST /portal/api/v1/batches` | operation: installApplication/updateApplication/uninstallApplication/startApplication/restartApplication/stopApplication/updateAppConfig/deleteAppConfig; query: versionId=...\&schedule=... or "" |
| GetBatch | `mes/siemens-iem/batch/get` | `GET /portal/api/v1/batches/{batchId}` | data = READY / PROCESSED |
| ListBatchJobs | `mes/siemens-iem/batch-job/list` | `GET /portal/api/v1/batches/{id}/jobs` | Per-device install jobs of a batch |
| GetInstallJob | `mes/siemens-iem/job/get` | `GET /portal/api/v1/installjobs/{id}` | data = COMPLETED / PENDING / QUEUED / FAILED / EXECUTING / DELETED / DELETING |

Every reply is published on `<topic>/response`.

## Authentication

The Portal API uses a token in the `Authorization` header, sent **as is** (no `Bearer` prefix):

1. Publish to `mes/siemens-iem/token/create` with `{"body": {"username": "...", "password": "..."}}`. Use an IEM user or a technical user with the rights you need. The reply has `data.access_token`, valid for 24 hours.
2. Put that token in `"authorization"` on every other event.

Keep the user name and password in Hub secrets (for example `SIEMENS_IEM_USERNAME` and `SIEMENS_IEM_PASSWORD`) and read them with `GET SECRET`. Never paste them into the connector. A missing or expired token returns `401`.

> [!WARNING]
>
> Many IEM installations use a self-signed certificate (the Siemens examples call `curl --insecure`). The broker host must trust the IEM certificate authority, or every call fails during the TLS handshake.

## Connector

Replace `YOUR_IEM_HOST` with your IEM address (no path). Every endpoint starts with `/portal/api/v1`.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiemensIEM WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_IEM_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Login
        WITH SOURCE_TOPIC "mes/siemens-iem/token/create"
        WITH DESTINATION_TOPIC "mes/siemens-iem/token/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/portal/api/v1/login/direct"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT VerifyToken
        WITH SOURCE_TOPIC "mes/siemens-iem/token/verify"
        WITH DESTINATION_TOPIC "mes/siemens-iem/token/verify/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/auth-tokens/verify"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT Logout
        WITH SOURCE_TOPIC "mes/siemens-iem/token/delete"
        WITH DESTINATION_TOPIC "mes/siemens-iem/token/delete/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/logout"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "mes/siemens-iem/device/list"
        WITH DESTINATION_TOPIC "mes/siemens-iem/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/devices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "mes/siemens-iem/device/get"
        WITH DESTINATION_TOPIC "mes/siemens-iem/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/devices/{value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDeviceStatistics
        WITH SOURCE_TOPIC "mes/siemens-iem/device-statistics/get"
        WITH DESTINATION_TOPIC "mes/siemens-iem/device-statistics/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/devices/{value.json.device_id}/statistics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListInstalledApps
        WITH SOURCE_TOPIC "mes/siemens-iem/device-app/list"
        WITH DESTINATION_TOPIC "mes/siemens-iem/device-app/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/devices/installed-apps?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListCatalogApps
        WITH SOURCE_TOPIC "mes/siemens-iem/application/list"
        WITH DESTINATION_TOPIC "mes/siemens-iem/application/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/applications"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetApplication
        WITH SOURCE_TOPIC "mes/siemens-iem/application/get"
        WITH DESTINATION_TOPIC "mes/siemens-iem/application/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/applications/{value.json.app_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListAppConfigs
        WITH SOURCE_TOPIC "mes/siemens-iem/application-config/list"
        WITH DESTINATION_TOPIC "mes/siemens-iem/application-config/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/applications/{value.json.app_id}/configs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT DeployApplication
        WITH SOURCE_TOPIC "mes/siemens-iem/application/deploy"
        WITH DESTINATION_TOPIC "mes/siemens-iem/application/deploy/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/portal/api/v1/batches?appid={value.json.app_id}&operation=installApplication"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "multipart/form-data; boundary=CorefluxIemBoundary"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.form}"
    ADD EVENT ApplicationCommand
        WITH SOURCE_TOPIC "mes/siemens-iem/application/command"
        WITH DESTINATION_TOPIC "mes/siemens-iem/application/command/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/portal/api/v1/batches?appid={value.json.app_id}&operation={value.json.operation}&{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "multipart/form-data; boundary=CorefluxIemBoundary"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.form}"
    ADD EVENT GetBatch
        WITH SOURCE_TOPIC "mes/siemens-iem/batch/get"
        WITH DESTINATION_TOPIC "mes/siemens-iem/batch/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/batches/{value.json.batch_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListBatchJobs
        WITH SOURCE_TOPIC "mes/siemens-iem/batch-job/list"
        WITH DESTINATION_TOPIC "mes/siemens-iem/batch-job/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/batches/{value.json.batch_id}/jobs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetInstallJob
        WITH SOURCE_TOPIC "mes/siemens-iem/job/get"
        WITH DESTINATION_TOPIC "mes/siemens-iem/job/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/portal/api/v1/installjobs/{value.json.job_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

## Deploying an app

`POST /portal/api/v1/batches` takes `multipart/form-data` with one field, `infoMap` (JSON). The connector sends the fixed boundary `CorefluxIemBoundary`, so `form` carries the complete multipart body with CRLF line breaks:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "<access_token>",
  "app_id": "46d2ac22e41a4b65af55a434c887578e",
  "form": "--CorefluxIemBoundary\r\nContent-Disposition: form-data; name=\"infoMap\"\r\n\r\n{\"devices\":[\"06cdac6c607e447dad16eef9f767a56e\"]}\r\n--CorefluxIemBoundary--\r\n"
}
```

Publish that to `mes/siemens-iem/application/deploy`. The reply is `{"data": "<batch id>"}`. Then:

1. `mes/siemens-iem/batch/get` with `batch_id`: `READY` (batch accepted) or `PROCESSED` (device jobs created).
2. `mes/siemens-iem/batch-job/list` with `batch_id`: one job per device.
3. `mes/siemens-iem/job/get` with `job_id`: `QUEUED`, `EXECUTING`, `COMPLETED`, `FAILED`, ...

`infoMap` can also carry `delayTime` (1 to 60 minutes between devices) and `configs` (for example `[{"configId": "...", "templateId": "..."}]`, ids from `ListAppConfigs`). For other operations use `mes/siemens-iem/application/command` with `operation` set to `updateApplication`, `uninstallApplication`, `startApplication`, `restartApplication`, `stopApplication`, `updateAppConfig` or `deleteAppConfig`, and `query` set to `""` or `versionId=<id>` (developer apps) and `schedule=<ticks>`.

> [!WARNING]
>
> Deploy and command events change what runs on production edge devices. Restrict who may publish to `mes/siemens-iem/application/#` with a broker rule.

## Example actions

Log in twice a day, keep the token in broker state, and poll the device list every five minutes:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SiemensIemLogin
ON EVERY 12 HOURS DO
    SET "user" WITH GET SECRET "SIEMENS_IEM_USERNAME"
    SET "pass" WITH GET SECRET "SIEMENS_IEM_PASSWORD"
    PUBLISH TOPIC "mes/siemens-iem/token/create" WITH { "body": { "username": {user}, "password": {pass} } }

DEFINE ACTION SiemensIemKeepToken
ON TOPIC "mes/siemens-iem/token/create/response" DO
    SET "token" WITH GET JSON "data.access_token" IN PAYLOAD AS STRING
    KEEP TOPIC "state/siemens-iem/token" WITH {token}

DEFINE ACTION SiemensIemPollDevices
ON EVERY 5 MINUTES DO
    SET "token" WITH GET TOPIC "state/siemens-iem/token" AS STRING
    PUBLISH TOPIC "mes/siemens-iem/device/list" WITH { "authorization": {token}, "query": "page=0&size=100" }
```

## Notes

* `ListDevices` takes `query` such as `page=0&size=50`. `ListInstalledApps` takes `deviceid=<id>`, or `""` for all devices.
* Device status is `data.deviceStatus` from `GetDevice`. There is no separate device status endpoint. `GetDeviceStatistics` returns the last statistics the device sent, keyed by timestamp.
* `Logout` works on IEM-OS only (not on IEM on Kubernetes).
* Not included: application import from file and file-based app configs (multipart file uploads), device creation and deletion, device reboot or shutdown jobs, log downloads, projects and companies, and the separate IEM Admin API.

## References

* [IEM Portal API 1.9.0 (OpenAPI)](https://developer.siemens.com/industrial-edge/api/iem/api-portal/v1.9.0/api-portal-1-9-0.html)
* [Portal Public API reference](https://docs.industrial-operations-x.siemens.cloud/r/en-us/portal-public-api)
* [Industrial Edge APIs and SDKs](https://docs.industrial-operations-x.siemens.cloud/p/industrial-edge-apis-sdks)
* [REST API connectors](/latest/lot-language/routes/rest-api-routes)


# Siemens Insights Hub
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/siemens-insights-hub

LoT REST API connector for Siemens Insights Hub (MindSphere): write and read IoT time series, create and list events, and list assets from MQTT

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [Siemens Insights Hub](https://developer.siemens.com/insights-hub/docs/apis/index.html) (formerly MindSphere) covering these connector events:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| PUT iottimeseries/v3/timeseries/\{asset}/\{aspect} | `PUT /iottimeseries/v3/timeseries/{assetId}/{aspectName}` | Ingest near-real-time time series |
| GET time series | `GET /iottimeseries/v3/timeseries/{assetId}/{aspectName}` | Query with `from` / `to` / `limit` |
| POST eventmanagement/v3/events | `POST /eventmanagement/v3/events` | Create standard or custom events |
| GET assetmanagement/v3/assets | `GET /assetmanagement/v3/assets` | List assets (`page` / `size`) |
| (list) | `GET /eventmanagement/v3/events` | Optional paged event list |

Default `BASE_ADDRESS` is `https://gateway.eu1.mindsphere.io/api` (no trailing slash; substitute `{region}`). Topics use `cloud-iot/siemens-insights-hub/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth header:** Pass the full `Authorization` value via MQTT JSON field `authorization` as `Bearer {access_token}` (OAuth 2.0 technical user client credentials, or application / Token Management credentials). Prefer Hub secrets (`SIEMENS_INSIGHTS_HUB_AUTH`). Never commit real credentials. See [Accessing Industrial IoT APIs from self-hosted applications](https://documentation.mindsphere.io/MindSphere/howto/howto-selfhosted-api-access.html).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Siemens Insights Hub curated slice
# Auth: Authorization via {value.json.authorization} (Bearer …)
# BASE_ADDRESS: https://gateway.eu1.mindsphere.io/api  → substitute {region}

DEFINE CONNECTOR SiemensInsightsHubRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://gateway.eu1.mindsphere.io/api"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT PutTimeseries
        WITH SOURCE_TOPIC "cloud-iot/siemens-insights-hub/timeseries/put"
        WITH DESTINATION_TOPIC "cloud-iot/siemens-insights-hub/timeseries/put/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/iottimeseries/v3/timeseries/{value.json.assetId}/{value.json.aspectName}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT GetTimeseries
        WITH SOURCE_TOPIC "cloud-iot/siemens-insights-hub/timeseries/get"
        WITH DESTINATION_TOPIC "cloud-iot/siemens-insights-hub/timeseries/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/iottimeseries/v3/timeseries/{value.json.assetId}/{value.json.aspectName}?from={value.json.from}&to={value.json.to}&limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateEvent
        WITH SOURCE_TOPIC "cloud-iot/siemens-insights-hub/event/create"
        WITH DESTINATION_TOPIC "cloud-iot/siemens-insights-hub/event/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/eventmanagement/v3/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT ListAssets
        WITH SOURCE_TOPIC "cloud-iot/siemens-insights-hub/asset/list"
        WITH DESTINATION_TOPIC "cloud-iot/siemens-insights-hub/asset/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/assetmanagement/v3/assets?page={value.json.page}&size={value.json.size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListEvents
        WITH SOURCE_TOPIC "cloud-iot/siemens-insights-hub/event/list"
        WITH DESTINATION_TOPIC "cloud-iot/siemens-insights-hub/event/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/eventmanagement/v3/events?page={value.json.page}&size={value.json.size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

## MQTT topics

| Event | Source topic | Response topic |
| - | - | - |
| PutTimeseries | `cloud-iot/siemens-insights-hub/timeseries/put` | `…/timeseries/put/response` |
| GetTimeseries | `cloud-iot/siemens-insights-hub/timeseries/get` | `…/timeseries/get/response` |
| CreateEvent | `cloud-iot/siemens-insights-hub/event/create` | `…/event/create/response` |
| ListAssets | `cloud-iot/siemens-insights-hub/asset/list` | `…/asset/list/response` |
| ListEvents | `cloud-iot/siemens-insights-hub/event/list` | `…/event/list/response` |

## References

* [Insights Hub services index](https://developer.siemens.com/insights-hub/docs/apis/index.html)
* [IoT Time Series overview](https://developer.siemens.com/insights-hub/docs/apis/iot-iottimeseries/api-iottimeseries-overview.html)
* [Event Management overview](https://developer.siemens.com/insights-hub/docs/apis/advanced-eventmanagement/api-eventmanagement-overview.html)
* [Self-hosted API access (OAuth)](https://documentation.mindsphere.io/MindSphere/howto/howto-selfhosted-api-access.html)


# Siemens Opcenter Execution
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/siemens-opcenter-execution

Siemens Opcenter Execution MES: OData reads of work orders and runtime data, archive queries, plant config, OpenAPI discovery and public command invocation

Technical Preview

## Overview

One client-mode connector, **SiemensOpcenterExecution**, for the service layer of Siemens Opcenter Execution. Opcenter Execution Discrete, Process and other solutions built on Opcenter Execution Foundation expose the same surface: OData v4 reads on `/sit-svc`, a read-only archive on `/sit-arch`, and public commands that the solution's workers execute.

Use the connector to bring MES context into your Unified Namespace: publish active work orders next to the machine data that serves them, count open operations per line, or look up a finished order in the archive. In the other direction, a machine event on the broker can call an Opcenter command such as completing an operation or recording a consumption.

Every Opcenter solution is different. Entity sets and command names come from the Apps installed in your solution, and Opcenter generates an OpenAPI 3.0.3 description of them when the solution is built. Start with the discovery events, then use the exact names they return.

| Event | Request | Notes |
| - | - | - |
| GetPlantConfig | `GET /sit-svc/config?{query}` | Configured plants; `plantid=<PlantId>` filters one |
| GetHostMonitoring | `GET /sit-svc/monitoring?{query}` | Host and worker status, the data behind the Solution Studio monitoring screen |
| GetSolutionOpenApi | `GET /sit-svc/{solution_path}/$openapi` | OpenAPI of every public command in the solution |
| GetAppServiceDocument | `GET /sit-svc/{app_path}/odata/` | OData service document: the App's entity sets |
| GetAppMetadata | `GET /sit-svc/{app_path}/odata/$metadata` | CSDL XML: entities, keys, properties, navigation |
| GetAppOpenApi | `GET /sit-svc/{app_path}/odata/$openapi` | OpenAPI of the App's commands and entities |
| QueryEntities | `GET /sit-svc/{app_path}/odata/{entity}?{query}` | Any entity set with `$filter`, `$select`, `$expand`, `$orderby`, `$top`, `$skip` |
| GetEntity | `GET /sit-svc/{app_path}/odata/{entity}({key})?{query}` | One record by key |
| CountEntities | `GET /sit-svc/{app_path}/odata/{entity}/$count?{query}` | Plain-text count |
| ListWorkOrders | `GET /sit-svc/{app_path}/odata/WorkOrder?{query}` | Shortcut for the `WorkOrder` entity set; check the name in `$metadata` |
| QueryArchive | `GET /sit-arch/{app_path}/odata/{entity}?{query}` | Archived runtime data, read-only |
| InvokeCommand | `POST /sit-svc/{app_path}/odata/{command}` | Any public command; body as described in `$openapi` |

Topics are `mes/siemens-opcenter-execution/<object>/<verb>`; every reply goes to `<topic>/response`.

`app_path` is `Application/<AppName>` for the default plant, or `<PlantId>/Application/<AppName>` in a multi-plant installation, for example `Application/AppU4DM` or `Plant1/Application/AppU4DM`. `solution_path` is `Application` or `<PlantId>/Application`.

## Authentication

Every event sends `Authorization: {authorization}`, so pass the whole header value, normally `"Bearer <access token>"`. Opcenter issues tokens through its authentication service (`/sit-auth`), backed by Siemens UMC or the identity provider your installation is configured with. How a service account gets a token depends on that setup, so ask your Opcenter administrator for a service account and the token procedure, and give the account only the roles the commands you plan to call need.

Keep the value in a broker secret (suggested `OPCENTER_AUTHORIZATION`) and map it in with `GET SECRET`. Tokens expire, so refresh the secret on the schedule your identity provider uses. A missing or expired token returns `401`; a role without permission returns `403`.

## Basic Syntax

Opcenter runs on your own servers or private cloud, so set `BASE_ADDRESS` to the host that serves `/sit-svc` (no trailing slash).

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SiemensOpcenterExecution WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_OPCENTER_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT QueryEntities
        WITH SOURCE_TOPIC "mes/siemens-opcenter-execution/entity/query"
        WITH DESTINATION_TOPIC "mes/siemens-opcenter-execution/entity/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/sit-svc/{value.json.app_path}/odata/{value.json.entity}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT InvokeCommand
        WITH SOURCE_TOPIC "mes/siemens-opcenter-execution/command/invoke"
        WITH DESTINATION_TOPIC "mes/siemens-opcenter-execution/command/invoke/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/sit-svc/{value.json.app_path}/odata/{value.json.command}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
```

The full template, with all 12 events, is `SiemensOpcenterExecutionRestApi.lot` in the REST API app.

## MQTT examples

Request bodies go under `body`, so control fields like `authorization`, `app_path`, `entity` and `query` are not sent to Opcenter.

**Discover what an App offers**: publish to `mes/siemens-opcenter-execution/app-openapi/get`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <Opcenter token>",
  "app_path": "Application/AppU4DM"
}
```

The reply lists the App's commands with their request schemas. `app-metadata/get` returns the entity sets and keys.

**Read the first 20 work orders**: publish to `mes/siemens-opcenter-execution/work-order/list`. The OData query must be URL-encoded:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <Opcenter token>",
  "app_path": "Application/AppU4DM",
  "query": "$top=20"
}
```

Use `entity/query` with `"entity": "<EntitySet>"` for any other entity set, and send `"query": ""` when you do not need options.

**Get one record**: publish to `mes/siemens-opcenter-execution/entity/get` with `"entity"` and `"key"`. The key is the OData key literal as it appears in the URL: a Guid as is, a string in single quotes such as `"'WO-0001'"`.

**Call a public command**: publish to `mes/siemens-opcenter-execution/command/invoke`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <Opcenter token>",
  "app_path": "Application/<AppName>",
  "command": "<PublicCommandName>",
  "body": { "...": "fields exactly as the command's request schema in $openapi" }
}
```

The connector sends `body` unchanged, so copy its shape from the command's schema in `GetAppOpenApi` or `GetSolutionOpenApi`.

## Helper actions

Keep the token in a broker secret, poll work orders every minute, and turn a line event into an Opcenter command:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION OpcenterPollActiveWorkOrders
ON EVERY 1 MINUTE DO
    SET "auth" WITH GET SECRET "OPCENTER_AUTHORIZATION"
    PUBLISH TOPIC "mes/siemens-opcenter-execution/work-order/list" WITH { "authorization": {auth}, "app_path": "Application/AppU4DM", "query": "$top=50" }

DEFINE ACTION OpcenterInvokeFromLine
ON TOPIC "porto/line1/opcenter/command" DO
    SET "auth" WITH GET SECRET "OPCENTER_AUTHORIZATION"
    SET "cmd" WITH GET JSON "command" IN PAYLOAD AS STRING
    SET "args" WITH GET JSON "body" IN PAYLOAD
    PUBLISH TOPIC "mes/siemens-opcenter-execution/command/invoke" WITH { "authorization": {auth}, "app_path": "Application/AppU4DM", "command": {cmd}, "body": {args} }
```

Restrict who can publish to `mes/siemens-opcenter-execution/#` with a rule: its payloads carry the token, and `InvokeCommand` changes production records.

## Notes

* Errors come back on the response topic: `401` for a missing or expired token, `403` when the account's role does not allow the call, `404` for an unknown App, entity set or command, `400` for a malformed OData query or command body, and `500` when a command handler fails.
* Commands are executed by Opcenter workers. Some return only after the transaction commits; check the result by reading the affected entity afterwards.
* `/sit-arch` is the archive database and is read-only. Use it for history and audit, and `/sit-svc` for live production data.
* In a multi-plant installation each plant has its own data. Put the plant id in `app_path` and use `GetPlantConfig` with `plantid=<PlantId>` to check it.
* Names differ between Opcenter Execution Discrete, Process and custom solutions. `ListWorkOrders` assumes a `WorkOrder` entity set; if your App names it differently, use `QueryEntities`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [Ignition](/latest/lot-language/routes/rest-api-apps/ignition)
* [SAP Digital Manufacturing](/latest/lot-language/routes/rest-api-apps/sap-digital-manufacturing)


# Siemens Teamcenter
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/siemens-teamcenter

LoT REST API connector for Siemens Teamcenter: read item revisions, BOMs and released drawings, run saved queries and raise problem reports from quality events

Technical Preview

## Overview

[Siemens Teamcenter](https://plm.sw.siemens.com/en-US/teamcenter/) is the PLM system that owns parts, revisions, BOMs, drawings and change processes for many plants. This connector lets shop-floor logic on MQTT read the released revision and BOM of a part, find its released drawing for a work instruction screen, and raise a problem report from a quality event, without custom code.

**SiemensTeamcenterApi** (`SiemensTeamcenterRestApi.lot`) is one client connector on `https://YOUR_TC_SERVER` with 18 events: 1 login, 14 reads and 3 writes. No event deletes, revises or checks out anything.

> [!NOTE]
>
> Teamcenter exposes every SOA service operation as JSON over HTTP: `POST /tc/JsonRestServices/<Library>-<YYYY>-<MM>-<Service>/<operation>` with a body of `{"header": {"state": {}, "policy": {}}, "body": {...}}`. Siemens does not publish an OpenAPI file for Teamcenter. Your installation can generate its own API description (Active Workspace `npm run genSoaApi`). The events here follow public samples: the [Teamcenter REST API Postman collection](https://github.com/Krusty84/Teamcenter_REST_API), [TCSwiftBridge](https://github.com/Krusty84/TCSwiftBridge) and the Mendix [Teamcenter connector docs](https://docs.mendix.com/appstore/industry/teamcenter-connector/services-not-included/). To add another operation, copy an event and change the operation path.

## Server host

Teamcenter is installed per customer, or runs as Teamcenter X (SaaS). Replace `YOUR_TC_SERVER` with your web tier host, with no trailing slash. Add the port when the web tier does not use 443 (for example `:7001` or `:8080`). Behind the Active Workspace gateway, the same operations are also served under `/tc/RestServices/` and need an `X-XSRF-TOKEN` header. This template uses `/tc/JsonRestServices/` on the web tier.

## Authentication

> [!WARNING]
>
> Teamcenter sessions act as their user. Keep the user and password in Hub secrets, map them in with `GET SECRET`, and never publish the session cookie on a topic other clients can read.

1. Publish the credentials on `mes/siemens-teamcenter/session/login`. The web tier answers with a `JSESSIONID` cookie (`Set-Cookie`).
2. Send `"cookie": "JSESSIONID=<id>"` in every other payload. One session holds one Teamcenter server process, so reuse it instead of logging in per call.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "request": {
    "header": {
      "state": {},
      "policy": {}
    },
    "body": {
      "credentials": {
        "user": "<TC user>",
        "password": "<TC password>",
        "role": "",
        "descrimator": "coreflux",
        "locale": "",
        "group": ""
      }
    }
  }
}
```

> [!WARNING]
>
> `JSESSIONID` only comes back in the `Set-Cookie` header, not in the response body. It is not yet verified whether the broker's REST client keeps cookies per connector or passes `Set-Cookie` on. Until that is confirmed, get the session outside the broker and keep the cookie on `internal/siemens-teamcenter/cookie` (the example actions read it there). Sites that use Teamcenter SSO or Teamcenter X log in through Siemens SSO. They need a session from that login flow, which this template does not cover.

## Payload convention

* `request`: the full SOA envelope, sent as the body unchanged. `header.policy` picks which properties come back (`types[].properties[].name`).
* `cookie`: the session cookie, `JSESSIONID=<id>`.
* Objects are referenced as `{"uid": "...", "type": "ItemRevision"}`. Some operations take plain UID strings.

## Events

| Event | Topic | Operation | Kind | What it does |
| - | - | - | - | - |
| `Login` | `mes/siemens-teamcenter/session/login` | `Core-2011-06-Session/login` | Read | Log in with Teamcenter user / password (Core-2011-06-Session/login). The web tier answers with Set-Cookie JSESSIONID; send it as cookie on every other event |
| `GetSessionInfo` | `mes/siemens-teamcenter/session-info/get` | `Core-2007-01-Session/getTCSessionInfo` | Read | Session check: current user, group, role, server version (Core-2007-01-Session/getTCSessionInfo) |
| `GetFavorites` | `mes/siemens-teamcenter/favorites/get` | `Core-2008-03-Session/getFavorites` | Read | Favorites of the session user |
| `GetPreferences` | `mes/siemens-teamcenter/preferences/get` | `Administration-2012-09-PreferenceManagement/getPreferences` | Read | Read Teamcenter preferences by name (for example the default revision rule) |
| `GetItemFromId` | `mes/siemens-teamcenter/item/get` | `Core-2007-01-DataManagement/getItemFromId` | Read | Item and item revision (UIDs and properties) by item\_id and revision id; first call of the BOM and drawing flows |
| `GetProperties` | `mes/siemens-teamcenter/properties/get` | `Core-2006-03-DataManagement/getProperties` | Read | Properties of objects by UID: release\_status\_list / date\_released to check a revision is released, IMAN\_specification / IMAN\_Rendering for its drawing datasets |
| `ExpandGrmRelationsForPrimary` | `mes/siemens-teamcenter/relations-primary/expand` | `Core-2007-09-DataManagement/expandGRMRelationsForPrimary` | Read | Secondary objects of an item revision by relation type (IMAN\_specification, IMAN\_Rendering, ...): find the drawing / PDF datasets for work instruction display |
| `GetSavedQueries` | `mes/siemens-teamcenter/saved-queries/list` | `Query-2006-03-SavedQuery/getSavedQueries` | Read | All saved queries (names and UIDs) |
| `DescribeSavedQueries` | `mes/siemens-teamcenter/saved-queries/describe` | `Query-2006-03-SavedQuery/describeSavedQueries` | Read | Fields (entries) of a saved query |
| `PerformSearch` | `mes/siemens-teamcenter/search/perform` | `Query-2012-10-Finder/performSearch` | Read | Finder search: run a saved query (Awp0SavedQuerySearchProvider) or the inbox (Awp0InboxProvider) with a property policy |
| `GetRevisionRules` | `mes/siemens-teamcenter/revision-rules/list` | `Cad-2007-01-StructureManagement/getRevisionRules` | Read | Revision rules (Latest Working, Any Status; Working, Precise, ...) |
| `CreateBomWindow` | `mes/siemens-teamcenter/bom-window/create` | `Cad-2007-01-StructureManagement/createBOMWindows` | Read | Open a BOM window on an item (revision rule config); returns bomWindow and the top bomLine. Session object only, saves nothing |
| `ExpandBomOneLevel` | `mes/siemens-teamcenter/bom/expand-one-level` | `Cad-2007-01-StructureManagement/expandPSOneLevel` | Read | First-level children of a BOM line (excludeFilter None2) |
| `ExpandBomAllLevels` | `mes/siemens-teamcenter/bom/expand-all-levels` | `Cad-2007-01-StructureManagement/expandPSAllLevels` | Read | Full multi-level BOM below a BOM line, with item revision properties from the policy |
| `CloseBomWindow` | `mes/siemens-teamcenter/bom-window/close` | `Cad-2007-01-StructureManagement/closeBOMWindows` | Read | Close BOM windows opened by CreateBomWindow (frees server memory) |
| `CreateProblemReport` | `mes/siemens-teamcenter/problem-report/create` | `Core-2006-03-DataManagement/createItems` | Write | create an item of a change type such as ProblemReport (createItems; type name per your Change Management template) in a folder |
| `CreateRelations` | `mes/siemens-teamcenter/relations/create` | `Core-2006-03-DataManagement/createRelations` | Write | relate two objects (for example the affected item revision to the problem report; relation type per your template) |
| `StartWorkflow` | `mes/siemens-teamcenter/workflow/start` | `Workflow-2008-06-Workflow/createInstance` | Write | start a workflow process on target objects (for example submit the new problem report for review) |

Replies arrive on `<topic>/response`.

## Flows

### Item revision and BOM

1. `GetItemFromId` with the item ID returns the item and revision UIDs.
2. `CreateBomWindow` with the item UID returns a BOM window and its top BOM line.
3. `ExpandBomOneLevel` or `ExpandBomAllLevels` with the top BOM line returns the children. The property policy in `header.policy` sets which item revision fields come back.
4. `CloseBomWindow` frees the window on the server.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "cookie": "JSESSIONID=<session id>",
  "request": {
    "header": {
      "state": {},
      "policy": {}
    },
    "body": {
      "infos": [
        {
          "itemId": "PRT-000123",
          "revIds": [
            "A"
          ]
        }
      ],
      "nRev": 1,
      "pref": {}
    }
  }
}
```

### Released drawing for work instruction display

1. `GetItemFromId` returns the revision UID.
2. `GetProperties` on the revision with `release_status_list`, `date_released`, `IMAN_specification` and `IMAN_Rendering` tells you whether the revision is released and which datasets hold its drawing. You can also use `ExpandGrmRelationsForPrimary` with `relationTypeName` `IMAN_specification`.
3. Show the dataset in Active Workspace, or download the file through FMS. File download (`getFileReadTickets` and FMS) is not part of this template.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "cookie": "JSESSIONID=<session id>",
  "request": {
    "header": {
      "state": {},
      "policy": {}
    },
    "body": {
      "objects": [
        {
          "uid": "<ItemRevision uid>",
          "type": "ItemRevision"
        }
      ],
      "attributes": [
        "object_name",
        "item_revision_id",
        "release_status_list",
        "date_released",
        "IMAN_specification",
        "IMAN_Rendering"
      ]
    }
  }
}
```

### Problem report from a quality event

1. `CreateProblemReport` creates an item of your problem report type (`ProblemReport` in the example) in a folder.
2. `CreateRelations` links the affected revision to the problem report revision.
3. `StartWorkflow` starts your change process template on it.

The type name, relation type and workflow template depend on your Change Management setup. Confirm them with your Teamcenter administrator.

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "cookie": "JSESSIONID=<session id>",
  "request": {
    "header": {
      "state": {},
      "policy": {}
    },
    "body": {
      "properties": [
        {
          "clientId": "coreflux-qe-1",
          "itemId": "",
          "name": "Porosity on PRT-000123 rev A",
          "type": "ProblemReport",
          "revId": "",
          "uom": "",
          "description": "Quality event QE-1001 from line 1 press 01",
          "extendedAttributes": []
        }
      ],
      "container": {
        "uid": "<home or target folder uid>",
        "className": "Folder",
        "type": "Fnd0HomeFolder"
      },
      "relationType": "contents"
    }
  }
}
```

## Example actions

`docs-helper-actions.lot` holds example actions. They log in every 25 minutes with Hub secrets, look up an item or a revision's drawing datasets when a station asks, and create a problem report from a quality event.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TcLogin
ON EVERY 25 MINUTES DO
    SET "user" WITH GET SECRET "TC_USER"
    SET "password" WITH GET SECRET "TC_PASSWORD"
    PUBLISH TOPIC "mes/siemens-teamcenter/session/login" WITH { "request": { "header": { "state": {}, "policy": {} }, "body": { "credentials": { "user": {user}, "password": {password}, "role": "", "descrimator": "coreflux", "locale": "", "group": "" } } } }

DEFINE ACTION TcReleasedDrawingLookup
ON TOPIC "porto/line1/station03/work-instruction/revision-uid" DO
    SET "ck" WITH GET TOPIC "internal/siemens-teamcenter/cookie" AS STRING
    SET "rev" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "mes/siemens-teamcenter/properties/get" WITH { "cookie": {ck}, "request": { "header": { "state": {}, "policy": {} }, "body": { "objects": [ { "uid": {rev}, "type": "ItemRevision" } ], "attributes": [ "release_status_list", "date_released", "IMAN_specification", "IMAN_Rendering" ] } } }

DEFINE ACTION TcItemLookup
ON TOPIC "porto/line1/station03/work-instruction/item-id" DO
    SET "ck" WITH GET TOPIC "internal/siemens-teamcenter/cookie" AS STRING
    SET "item" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "mes/siemens-teamcenter/item/get" WITH { "cookie": {ck}, "request": { "header": { "state": {}, "policy": {} }, "body": { "infos": [ { "itemId": {item}, "revIds": [] } ], "nRev": 1, "pref": {} } } }

DEFINE ACTION TcQualityEventToProblemReport
ON TOPIC "porto/line1/press01/quality-event" DO
    SET "ck" WITH GET TOPIC "internal/siemens-teamcenter/cookie" AS STRING
    SET "title" WITH GET JSON "title" IN PAYLOAD AS STRING
    SET "detail" WITH GET JSON "detail" IN PAYLOAD AS STRING
    SET "folder" WITH GET TOPIC "internal/siemens-teamcenter/problem-report-folder-uid" AS STRING
    PUBLISH TOPIC "mes/siemens-teamcenter/problem-report/create" WITH { "cookie": {ck}, "request": { "header": { "state": {}, "policy": {} }, "body": { "properties": [ { "clientId": "coreflux-qe", "itemId": "", "name": {title}, "type": "ProblemReport", "revId": "", "uom": "", "description": {detail}, "extendedAttributes": [] } ], "container": { "uid": {folder}, "className": "Folder", "type": "Fnd0HomeFolder" }, "relationType": "contents" } } }
```

## Not included

* Delete, revise and checkout operations (left out on purpose).
* File download and upload through FMS (binary content).
* BOM edits (`addOrUpdateChildrenToParentLine`, `saveBOMWindows`).
* Teamcenter SSO / Teamcenter X login services and the AWC gateway `/tc/RestServices/` variant.

## Connector file

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Siemens Teamcenter (beta): read item revisions, properties, release status and BOMs
#   (BOM window + expand one / all levels), find a revision's released drawing datasets for work instruction display,
#   run saved queries / Finder searches, and from a quality event create a problem report, relate the affected
#   revision and start its workflow, over Teamcenter's JSON SOA REST services (/tc/JsonRestServices/).
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/siemens-teamcenter
#
# Host: Teamcenter is installed per customer (or Teamcenter X SaaS). Replace YOUR_TC_SERVER with the web tier host
#   (add :port, for example :7001 or :8080, when it does not share 443). Operations live under
#   /tc/JsonRestServices/<Library>-<YYYY>-<MM>-<Service>/<operation>; every call is POST with a JSON envelope
#   {"header": {"state": {}, "policy": {}}, "body": {...}}.
# Auth: session. Publish user / password on Login; the web tier returns Set-Cookie JSESSIONID. Send it back as
#   "cookie": "JSESSIONID=<id>" in every other payload. SSO-only sites (Teamcenter SSO / Teamcenter X) need a session
#   obtained outside this route; see the docs. Keep TC user and password in Hub secrets.
# Payloads: "request" is the full SOA envelope sent unchanged as the body; "cookie" is the session cookie.
#     GetItemFromId  {"cookie": "JSESSIONID=...", "request": {"header": {"state": {}, "policy": {}}, "body": {"infos": [{"itemId": "PRT-000123", "revIds": ["A"]}], "nRev": 1, "pref": {}}}}
#

DEFINE CONNECTOR SiemensTeamcenterApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_TC_SERVER"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    # Log in with Teamcenter user / password (Core-2011-06-Session/login). The web tier answers with Set-Cookie JSESSIONID; send it as cookie on every other event
    ADD EVENT Login
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/session/login"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/session/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2011-06-Session/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    # Session check: current user, group, role, server version (Core-2007-01-Session/getTCSessionInfo)
    ADD EVENT GetSessionInfo
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/session-info/get"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/session-info/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2007-01-Session/getTCSessionInfo"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Favorites of the session user
    ADD EVENT GetFavorites
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/favorites/get"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/favorites/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2008-03-Session/getFavorites"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Read Teamcenter preferences by name (for example the default revision rule)
    ADD EVENT GetPreferences
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/preferences/get"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/preferences/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Administration-2012-09-PreferenceManagement/getPreferences"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Item and item revision (UIDs and properties) by item_id and revision id; first call of the BOM and drawing flows
    ADD EVENT GetItemFromId
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/item/get"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/item/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2007-01-DataManagement/getItemFromId"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Properties of objects by UID: release_status_list / date_released to check a revision is released, IMAN_specification / IMAN_Rendering for its drawing datasets
    ADD EVENT GetProperties
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/properties/get"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/properties/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2006-03-DataManagement/getProperties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Secondary objects of an item revision by relation type (IMAN_specification, IMAN_Rendering, ...): find the drawing / PDF datasets for work instruction display
    ADD EVENT ExpandGrmRelationsForPrimary
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/relations-primary/expand"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/relations-primary/expand/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2007-09-DataManagement/expandGRMRelationsForPrimary"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # All saved queries (names and UIDs)
    ADD EVENT GetSavedQueries
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/saved-queries/list"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/saved-queries/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Query-2006-03-SavedQuery/getSavedQueries"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Fields (entries) of a saved query
    ADD EVENT DescribeSavedQueries
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/saved-queries/describe"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/saved-queries/describe/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Query-2006-03-SavedQuery/describeSavedQueries"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Finder search: run a saved query (Awp0SavedQuerySearchProvider) or the inbox (Awp0InboxProvider) with a property policy
    ADD EVENT PerformSearch
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/search/perform"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/search/perform/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Query-2012-10-Finder/performSearch"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Revision rules (Latest Working, Any Status; Working, Precise, ...)
    ADD EVENT GetRevisionRules
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/revision-rules/list"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/revision-rules/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Cad-2007-01-StructureManagement/getRevisionRules"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Open a BOM window on an item (revision rule config); returns bomWindow and the top bomLine. Session object only, saves nothing
    ADD EVENT CreateBomWindow
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/bom-window/create"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/bom-window/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Cad-2007-01-StructureManagement/createBOMWindows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # First-level children of a BOM line (excludeFilter None2)
    ADD EVENT ExpandBomOneLevel
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/bom/expand-one-level"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/bom/expand-one-level/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Cad-2007-01-StructureManagement/expandPSOneLevel"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Full multi-level BOM below a BOM line, with item revision properties from the policy
    ADD EVENT ExpandBomAllLevels
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/bom/expand-all-levels"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/bom/expand-all-levels/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Cad-2007-01-StructureManagement/expandPSAllLevels"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # Close BOM windows opened by CreateBomWindow (frees server memory)
    ADD EVENT CloseBomWindow
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/bom-window/close"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/bom-window/close/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Cad-2007-01-StructureManagement/closeBOMWindows"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # WRITE: create an item of a change type such as ProblemReport (createItems; type name per your Change Management template) in a folder
    ADD EVENT CreateProblemReport
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/problem-report/create"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/problem-report/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2006-03-DataManagement/createItems"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # WRITE: relate two objects (for example the affected item revision to the problem report; relation type per your template)
    ADD EVENT CreateRelations
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/relations/create"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/relations/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Core-2006-03-DataManagement/createRelations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
    # WRITE: start a workflow process on target objects (for example submit the new problem report for review)
    ADD EVENT StartWorkflow
        WITH SOURCE_TOPIC "mes/siemens-teamcenter/workflow/start"
        WITH DESTINATION_TOPIC "mes/siemens-teamcenter/workflow/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/tc/JsonRestServices/Workflow-2008-06-Workflow/createInstance"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Cookie" "{value.json.cookie}"
        WITH BODY "{value.json.request}"
```


# Siemens WinCC Unified (GraphQL server)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/siemens-wincc-unified

LoT REST API connector for the WinCC Unified GraphQL server: browse, read and write tags, read logged values, and list or acknowledge alarms from MQTT

Technical Preview

## Overview

WinCC Unified is the Siemens SCADA / HMI system in TIA Portal. From V19 on, Unified Runtime on a PC includes a **GraphQL server** for reading and writing runtime data: tags, logged (historical) tag values and alarms. Siemens documents it in the online help **WinCC Unified GraphQL (RT Unified)**.

The **WinccUnifiedGraphql** connector sends GraphQL queries and mutations over HTTPS. Every event is a `POST /graphql/` with a JSON body `{"query": "...", "variables": {...}}`. The topic picks the preset and the payload carries the GraphQL document, so you control exactly which fields come back. Typical uses: mirror HMI tags onto MQTT, write setpoints from MQTT, pull tag history into a historian or analytics pipeline, and acknowledge alarms from another system. Each event publishes the server's reply on `<topic>/response`.

| Event | Topic | GraphQL operation | Notes |
| - | - | - | - |
| Login | `historian/siemens-wincc-unified/session/create` | `mutation login` | UMC user configured for Runtime -> data.login.token (Bearer) + expires; error 101 wrong credentials, 102 UMC error |
| ExtendSession | `historian/siemens-wincc-unified/session/update` | `mutation extendSession` | Renew the current session (new expires) |
| Logout | `historian/siemens-wincc-unified/session/delete` | `mutation logout` | End this session (allSessions true = every session of the user) |
| GetSession | `historian/siemens-wincc-unified/session/get` | `query session` | Current session and user (token check) |
| BrowseTags | `historian/siemens-wincc-unified/tag/browse` | `query browse` | Find tags, alarms, logging tags by name filter (wildcards) and object type |
| ReadTagValues | `historian/siemens-wincc-unified/tag-value/get` | `query tagValues` | Current values (value, timestamp, quality); directRead true reads from the PLC instead of the cache |
| WriteTagValues | `historian/siemens-wincc-unified/tag-value/update` | `mutation writeTagValues` | Write values \{name, value\[, timestamp, quality]}; error 2 unknown tag, 201 cannot convert value |
| ReadLoggedTagValues | `historian/siemens-wincc-unified/logged-tag-value/list` | `query loggedTagValues` | Historical values of logging tags (Tag:LoggingTag, or the tag when it has one logging tag); startTime or endTime required, maxNumberOfValues if only one is set |
| ListActiveAlarms | `historian/siemens-wincc-unified/active-alarm/list` | `query activeAlarms` | Active alarms; filterString = WHERE part of ChromQueryLanguage (error 301 syntax) |
| ListLoggedAlarms | `historian/siemens-wincc-unified/logged-alarm/list` | `query loggedAlarms` | Alarm history from the alarm log |
| AcknowledgeAlarms | `historian/siemens-wincc-unified/alarm/acknowledge` | `mutation acknowledgeAlarms` | Acknowledge alarms \{name\[, instanceID]}; instanceID 0 = every instance; 305 not acknowledgeable in this state |
| ResetAlarms | `historian/siemens-wincc-unified/alarm/reset` | `mutation resetAlarms` | Reset alarms that need a reset |
| ShelveAlarms | `historian/siemens-wincc-unified/alarm/shelve` | `mutation shelveAlarms` | Shelve configured alarms (optional shelveTimeout) |
| UnshelveAlarms | `historian/siemens-wincc-unified/alarm/unshelve` | `mutation unshelveAlarms` | Revert shelve |
| DisableAlarms | `historian/siemens-wincc-unified/alarm/disable` | `mutation disableAlarms` | Disable configured alarms (no new instances) |
| EnableAlarms | `historian/siemens-wincc-unified/alarm/enable` | `mutation enableAlarms` | Enable configured alarms again |
| GraphqlRequest | `historian/siemens-wincc-unified/graphql/query` | `any query / mutation` | Any query or mutation of the schema (payload decides); subscriptions are not possible over REST\_API |

## Prerequisites

1. **WinCC Unified Runtime on a PC (V19 or later)** with a project running and the GraphQL server available. Siemens documents it online for V20 and V21. Unified Comfort Panels are not covered by the Siemens GraphQL help.
2. The Runtime **IIS web server** reachable from the broker host on HTTPS 443. The GraphQL server is published at `https://<runtime-host>/graphql/`. The GraphQL service listens on port 4000 on the runtime PC, but Siemens does not support direct access to it. Always go through IIS.
3. The broker must **trust the Runtime web server certificate**, either the self-signed certificate or a CA created with WinCC Unified Certificate Manager. The host name or IP in `BASE_ADDRESS` must be in that certificate. Use IPv4 when you connect by host name.
4. A **UMC user configured for Runtime**. Read rights are needed for queries, write rights for `writeTagValues` and the alarm mutations. Objects the user cannot read are left out of responses, and a write without permission aborts the operation.

## Authentication

1. Log in: publish the `login` mutation to `historian/siemens-wincc-unified/session/create` (example below). The response has `data.login.token` and `data.login.expires`. A wrong user or password returns `data.login.error.code` `101` and no token. `102` is a UMC error.
2. Send `"token": "<data.login.token>"` with every other event. The connector sends it as `Authorization: Bearer <token>`.
3. A session stays open while there is activity. `ExtendSession` (`session/update`) renews it, and `Logout` (`session/delete`) ends it. `allSessions: true` ends every session of the user. Changing the user's password and logging out with `allSessions: true` also closes them.
4. Without a valid token, the server answers with an `errors` array instead of data. When that happens, log in again.

Unlike some APIs, the token is in the **response body**, so a LoT action can read it with `GET JSON "data.login.token"` and keep it internally (see Examples).

> [!WARNING]
>
> Keep the WinCC Unified user and password in Hub secrets and add them with `GET SECRET`. Never put them in the connector file or in retained topics. Restrict who may publish to the write and alarm topics: `writeTagValues` writes to the HMI tags and, through them, to the PLC.

## Configuration

* Replace `YOUR_WINCC_UNIFIED_HOST` in `BASE_ADDRESS` with the Runtime PC's host name or IP. That name must match the Runtime web server certificate. Keep `USE_SSL "true"`.
* Every event is `POST /graphql/` with `Content-Type: application/json`. The body is `{value.json.body}`, sent unchanged. Use GraphQL **variables** for values. That keeps quotes out of the query string and makes the payload easy to build in LoT.
* GraphQL answers HTTP `200` for most errors. Check the `errors` array (syntax, validation, not logged in) and, per item, `error.code`: `0` success, `2` cannot resolve name, `3` argument error, `201` cannot convert value to data type, `202` only leaf elements of a structure tag, `301` alarm filter syntax error, `302` / `303` invalid language, `304` / `305` alarm state does not allow the action.
* Tag names follow the WinCC Unified addressing rules, for example `HMI_Tag_1` or a structure element `Motor_1.Speed`. `BrowseTags` lists them with wildcards (`*`, `?`).
* `loggedTagValues` takes logging tag names (`Tag:LoggingTag`) or a tag name when that tag has only one logging tag. Set `startTime` or `endTime`. If you set only one of them, also set `maxNumberOfValues`. Timestamps are ISO 8601 UTC, for example `2026-10-05T07:00:00.000Z`.
* `activeAlarms` and `loggedAlarms` take an optional `filterString`. This is the WHERE part of a ChromQueryLanguage (SQL-like) filter, for example `Priority >= 10`. Alarm names are full alarm paths, for example `HMI_RT_1::Line1_Temperature:HighHigh`. `instanceID` `0` targets every instance.
* `writeTagValues` takes an optional `timestamp` and `quality` (`{"quality": "GOOD_CASCADE"}`) for the whole list, or per tag in `input`.

## Examples

Log in (publish to `historian/siemens-wincc-unified/session/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "body": {
    "query": "mutation Login($username: String!, $password: String!) { login(username: $username, password: $password) { token expires user { name fullName language autoLogoffSec } error { code description } } }",
    "variables": {
      "username": "<UMC user>",
      "password": "<password>"
    }
  }
}
```

Response on `historian/siemens-wincc-unified/session/create/response`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"data": {"login": {"token": "<token>", "expires": "2026-10-05T07:30:00.000Z", "user": {"name": "operator", "fullName": "Operator", "language": "en-US", "autoLogoffSec": 1800}, "error": {"code": "0", "description": "Success"}}}}
```

Read live tag values (`historian/siemens-wincc-unified/tag-value/get`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "query TagValues($names: [String!]!, $directRead: Boolean) { tagValues(names: $names, directRead: $directRead) { name value { value timestamp quality { quality subStatus } } error { code description } } }",
    "variables": {
      "names": [
        "Line1_Temperature",
        "Line1_Setpoint"
      ]
    }
  }
}
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"data": {"tagValues": [{"name": "Line1_Temperature", "value": {"value": 21.4, "timestamp": "2026-10-05T07:00:00.000Z", "quality": {"quality": "GOOD_CASCADE", "subStatus": "NON_SPECIFIC"}}, "error": {"code": "0", "description": "Success"}}]}}
```

Write a setpoint (`historian/siemens-wincc-unified/tag-value/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "mutation WriteTagValues($input: [TagValueInput]!, $timestamp: Timestamp, $quality: QualityInput) { writeTagValues(input: $input, timestamp: $timestamp, quality: $quality) { name error { code description } } }",
    "variables": {
      "input": [
        {
          "name": "Line1_Setpoint",
          "value": 72.5
        }
      ]
    }
  }
}
```

Browse tags (`historian/siemens-wincc-unified/tag/browse`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "query Browse($nameFilters: [String], $objectTypeFilters: [ObjectTypesEnum], $language: String) { browse(nameFilters: $nameFilters, objectTypeFilters: $objectTypeFilters, language: $language) { name displayName objectType dataType } }",
    "variables": {
      "nameFilters": [
        "Line1_*"
      ],
      "objectTypeFilters": [
        "TAG"
      ],
      "language": "en-US"
    }
  }
}
```

Read the last hour of a logging tag (`historian/siemens-wincc-unified/logged-tag-value/list`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "query LoggedTagValues($names: [String]!, $startTime: Timestamp, $endTime: Timestamp, $maxNumberOfValues: Int, $sortingMode: LoggedTagValuesSortingModeEnum) { loggedTagValues(names: $names, startTime: $startTime, endTime: $endTime, maxNumberOfValues: $maxNumberOfValues, sortingMode: $sortingMode) { loggingTagName error { code description } values { value { value timestamp quality { quality subStatus } } flags } } }",
    "variables": {
      "names": [
        "Line1_Temperature:Line1_Temperature_Log"
      ],
      "startTime": "2026-10-05T06:00:00.000Z",
      "endTime": "2026-10-05T07:00:00.000Z",
      "maxNumberOfValues": 1000,
      "sortingMode": "TIME_ASC"
    }
  }
}
```

List active alarms with priority 10 or higher (`historian/siemens-wincc-unified/active-alarm/list`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "query ActiveAlarms($systemNames: [String], $filterString: String, $filterLanguage: String, $languages: [String]) { activeAlarms(systemNames: $systemNames, filterString: $filterString, filterLanguage: $filterLanguage, languages: $languages) { name instanceID alarmGroupID raiseTime acknowledgmentTime clearTime resetTime modificationTime state priority eventText infoText alarmClassName origin area path value hostName userName } }",
    "variables": {
      "filterString": "Priority >= 10",
      "languages": [
        "en-US"
      ]
    }
  }
}
```

Acknowledge an alarm (`historian/siemens-wincc-unified/alarm/acknowledge`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "mutation AcknowledgeAlarms($input: [AlarmIdentifierInput]!) { acknowledgeAlarms(input: $input) { alarmName alarmInstanceID error { code description } } }",
    "variables": {
      "input": [
        {
          "name": "HMI_RT_1::Line1_Temperature:HighHigh",
          "instanceID": 0
        }
      ]
    }
  }
}
```

Read logged alarms (`historian/siemens-wincc-unified/logged-alarm/list`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "query LoggedAlarms($systemNames: [String], $filterString: String, $languages: [String], $startTime: Timestamp, $endTime: Timestamp, $maxNumberOfResults: Int) { loggedAlarms(systemNames: $systemNames, filterString: $filterString, languages: $languages, startTime: $startTime, endTime: $endTime, maxNumberOfResults: $maxNumberOfResults) { name instanceID raiseTime acknowledgmentTime clearTime resetTime modificationTime state priority eventText origin area } }",
    "variables": {
      "startTime": "2026-10-05T00:00:00.000Z",
      "endTime": "2026-10-05T07:00:00.000Z",
      "maxNumberOfResults": 100
    }
  }
}
```

Keep the session alive (`historian/siemens-wincc-unified/session/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "<token>",
  "body": {
    "query": "mutation ExtendSession { extendSession { token expires error { code description } } }",
    "variables": {}
  }
}
```

Example actions: log in with Hub secrets, keep the token internally, keep the session alive, poll tags and alarms, write a setpoint and acknowledge alarms from MQTT. Send anything to `internal/wincc-unified/login` once to log in.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the WinccUnifiedGraphql route (docs page). Not part of the route template.
# Secrets: WINCC_UNIFIED_USER / WINCC_UNIFIED_PASSWORD = a UMC user configured for Runtime (read rights for queries,
#   write rights for writeTagValues and the alarm mutations). The login mutation returns the token in the response
#   BODY (data.login.token), so an action can keep it internally and add it to every request. The session stays
#   open while there is activity; the keep-alive below renews it. On an "errors" reply, publish to the login topic again.
# Tag and alarm names below are examples: use the names from your WinCC Unified project (BrowseTags lists them).

DEFINE ACTION WinccUnifiedLogin
ON TOPIC "internal/wincc-unified/login" DO
    SET "user" WITH GET SECRET "WINCC_UNIFIED_USER"
    SET "password" WITH GET SECRET "WINCC_UNIFIED_PASSWORD"
    PUBLISH TOPIC "historian/siemens-wincc-unified/session/create" WITH { "body": { "query": "mutation ($u: String!, $p: String!) { login(username: $u, password: $p) { token expires error { code description } } }", "variables": { "u": {user}, "p": {password} } } }

DEFINE ACTION WinccUnifiedRememberToken
ON TOPIC "historian/siemens-wincc-unified/session/create/response" DO
    SET "token" WITH GET JSON "data.login.token" IN PAYLOAD AS STRING
    KEEP TOPIC "internal/wincc-unified/token" WITH {token}

DEFINE ACTION WinccUnifiedKeepAlive
ON EVERY 5 MINUTES DO
    SET "token" WITH GET TOPIC "internal/wincc-unified/token"
    PUBLISH TOPIC "historian/siemens-wincc-unified/session/update" WITH { "token": {token}, "body": { "query": "mutation { extendSession { expires error { code description } } }" } }

DEFINE ACTION WinccUnifiedPollLine1
ON EVERY 10 SECONDS DO
    SET "token" WITH GET TOPIC "internal/wincc-unified/token"
    PUBLISH TOPIC "historian/siemens-wincc-unified/tag-value/get" WITH { "token": {token}, "body": { "query": "query ($names: [String!]!) { tagValues(names: $names) { name value { value timestamp quality { quality } } error { code description } } }", "variables": { "names": [ "Line1_Temperature", "Line1_Setpoint", "Line1_Running" ] } } }

DEFINE ACTION WinccUnifiedWriteSetpoint
ON TOPIC "plant/line1/setpoint/set" DO
    SET "token" WITH GET TOPIC "internal/wincc-unified/token"
    SET "value" WITH PAYLOAD AS DOUBLE
    PUBLISH TOPIC "historian/siemens-wincc-unified/tag-value/update" WITH { "token": {token}, "body": { "query": "mutation ($input: [TagValueInput]!) { writeTagValues(input: $input) { name error { code description } } }", "variables": { "input": [ { "name": "Line1_Setpoint", "value": {value} } ] } } }

DEFINE ACTION WinccUnifiedPollAlarms
ON EVERY 30 SECONDS DO
    SET "token" WITH GET TOPIC "internal/wincc-unified/token"
    PUBLISH TOPIC "historian/siemens-wincc-unified/active-alarm/list" WITH { "token": {token}, "body": { "query": "query ($languages: [String]) { activeAlarms(languages: $languages) { name instanceID state priority raiseTime eventText } }", "variables": { "languages": [ "en-US" ] } } }

DEFINE ACTION WinccUnifiedAcknowledgeFromMqtt
ON TOPIC "plant/line1/alarm/ack" DO
    SET "token" WITH GET TOPIC "internal/wincc-unified/token"
    SET "alarm" WITH GET JSON "name" IN PAYLOAD AS STRING
    PUBLISH TOPIC "historian/siemens-wincc-unified/alarm/acknowledge" WITH { "token": {token}, "body": { "query": "mutation ($input: [AlarmIdentifierInput]!) { acknowledgeAlarms(input: $input) { alarmName alarmInstanceID error { code description } } }", "variables": { "input": [ { "name": {alarm}, "instanceID": 0 } ] } } }
```

## Not covered

* **Subscriptions** (`tagValues`, `activeAlarms`, `reduState`). They need a WebSocket with the `graphql-transport-ws` protocol, which REST\_API connectors do not use. Poll `ReadTagValues` / `ListActiveAlarms` on a timer instead.
* `loginSWAC` (UMC SWAC single sign-on with `nonce` and a signed claim) and `identityProviderURL`. You can still send them through `GraphqlRequest`.
* Unified Comfort Panels, WinCC Unified Openness / ODK, and the Industrial Edge WinCC Unified apps.
* Engineering in TIA Portal (projects, screens, users). This connector only reads and writes runtime data.

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app catalog](/latest/lot-language/routes/rest-api-apps/index)
* [WinCC Unified GraphQL (RT Unified), V21](https://docs.tia.siemens.cloud/r/en-us/v21/wincc-unified-graphql-rt-unified)
* [WinCC Unified GraphQL requirements (RT Unified), V20](https://docs.tia.siemens.cloud/r/en-us/v20/wincc-unified-graphql-rt-unified/basics-rt-unified/requirements-rt-unified)


# Model Context Protocol (MCP)
Source: https://docs.coreflux.org/ai/mcp

Connect AI assistants to the Coreflux knowledge base using the Model Context Protocol

## The Bridge Between AI and Your Coreflux Environment

Modern AI assistants are powerful — but they don't natively understand LoT (Language of Things) syntax, Coreflux broker configuration, or the nuances of industrial IoT architecture. Without access to the official documentation, an AI assistant will guess, often producing code that looks plausible but uses invented syntax.

The **Model Context Protocol (MCP)** solves this. MCP is an open standard that lets AI assistants — like Claude, GitHub Copilot, or any MCP-compatible client — call external tools during a conversation. The **Coreflux MCP Server** exposes the entire Coreflux documentation as a set of tools your assistant can query in real time. When you ask "how do I create a time-based LoT Action?", your assistant doesn't guess — it looks up the answer in the official docs and responds with verified syntax and working examples.

The result: you stay in your editor, describe what you want in plain English, and get accurate LoT code grounded in real documentation.

> [!WARNING]
>
> This page is the **documentation MCP** at `https://docs.coreflux.org/mcp` — it searches official docs for your assistant. It does **not** start or control a broker.
>
> To let an assistant run broker commands and LoT Actions on a live broker, enable the [MCP Server](/latest/mqtt-broker/mcp-server) (`Mcp.Enabled`). To call *external* MCP tools from LoT, use an [MCP connector](/latest/lot-language/routes/mcp-routes) (`TYPE MCP` / `CALL MCP`).

> [!TIP]
>
> **Like giving your AI assistant a library card for Coreflux.** Instead of guessing about LoT syntax or broker configuration, your assistant can look it up directly in the official docs and give you an accurate, sourced answer.

### When to Use This

* You want your AI assistant to **answer Coreflux questions accurately** using official documentation
* You need **LoT syntax help** while coding in an AI-powered editor (Cursor, VS Code with Copilot)
* You want to **search the documentation** through natural language without leaving your workflow
* You're building with Coreflux and want your assistant to have **up-to-date reference material**

***

## How It Works

MCP (Model Context Protocol) is a standard created by Anthropic that defines how AI assistants communicate with external services. It works like a plugin system: an MCP **server** exposes a set of tools, and an MCP **client** (your AI assistant) discovers and calls those tools during conversation.

Here is what happens when you ask your AI assistant a Coreflux question:

| Step | What Happens |
| - | - |
| **1. You ask** | You type a question in natural language — *"Create a LoT Action that monitors temperature sensors"* |
| **2. AI recognizes the domain** | Your assistant detects this is a Coreflux question and decides to consult the MCP tools |
| **3. MCP tool call** | The assistant calls the Coreflux MCP Server — searching the documentation or asking the docs assistant |
| **4. Documentation responds** | The MCP server returns relevant documentation snippets, syntax references, and code examples |
| **5. AI synthesizes** | Your assistant combines the documentation with your specific requirements to produce accurate, grounded LoT code |
| **6. You review** | You receive a response with correct syntax, proper patterns, and source references you can verify |

This loop happens automatically once the MCP is connected. You don't need to tell your assistant to "use the MCP" — it discovers the available tools and calls them whenever your question relates to Coreflux.

| Component | Role |
| - | - |
| **MCP Server** | Coreflux's hosted service that exposes documentation tools |
| **MCP Client** | Your AI assistant (Claude, Copilot, etc.) that calls those tools |
| **Transport** | HTTP connection between client and server |

***

## Setup

Connect your AI assistant to the Coreflux documentation MCP server. Choose **Native** to install from the contextual menu on any documentation page, or **Manual** to paste the server URL into your editor's configuration file.

**Native**

The fastest way to connect is through the **contextual menu** at the top of every documentation page. It copies the hosted MCP server URL or installs the server directly in supported editors — no JSON editing required.

![Documentation page contextual menu expanded, showing Copy page, View as Markdown, Open in ChatGPT, Open in Claude, Copy MCP Server, Copy MCP install command, Connect to Cursor, and Connect to VS Code](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/action-menu-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=ab62d6ffe924c7ef063007d4fc93c08b)

Open the contextual menu from Copy page on any documentation page

| Menu option | What it does |
| - | - |
| **Copy MCP Server** | Copies the hosted MCP server URL to your clipboard |
| **Copy MCP install command** | Copies the `npx add-mcp` command to install the server |
| **Connect to Cursor** | Opens Cursor and installs the MCP server |
| **Connect to VS Code** | Opens VS Code and installs the MCP server |

**VS Code**

**1. Open the contextual menu**

On any Coreflux documentation page, click **Copy page** (top right) to expand the menu.

**2. Connect to VS Code**

Select **Connect to VS Code**. VS Code opens the MCP server installation flow for **Coreflux Documentation**.

**3. Install the server**

On the MCP server page, click **Install** (current window) or **Install in Workspace** (project only). Confirm trust if prompted.

![VS Code MCP Server tab for Coreflux Documentation showing Install and Install in Workspace buttons and configuration with Type http and the MCP server URL](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/vscode-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=e83435c5b09e548d23b3b3ef1cb90b4a)

VS Code MCP server page after Connect to VS Code

**4. Enable tools in Copilot**

Reload the window if needed, then open Copilot Chat in **Agent** mode and enable the Coreflux tools in the tool picker.

**Cursor**

**1. Open the contextual menu**

On any Coreflux documentation page, click **Copy page** (top right) to expand the menu.

**2. Connect to Cursor**

Select **Connect to Cursor**. Cursor opens the MCP server installation flow for **Coreflux Documentation**.

**3. Install the server**

In **Settings → Tools & MCPs**, review the pre-filled **Install MCP Server?** form (name, type, and URL), then click **Install**.

![Cursor Settings Tools page showing Install MCP Server dialog for Coreflux Documentation with Name, Type streamableHttp, URL, and Install button](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/cursor-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=4ba9395dd8281d8683178457bfcb5f20)

Cursor Tools settings after Connect to Cursor

**4. Confirm in Cursor**

Verify **Coreflux Documentation** appears under **Installed MCP Servers** with tools enabled.

> [!NOTE]
>
> To install manually in Cursor instead, use **Copy MCP Server** or **Copy MCP install command**, then switch to the **Manual** tab and follow the **Cursor** steps.

**Other clients**

For Claude Desktop, Claude.ai, or other MCP clients that are not in the menu:

**1. Copy the server URL**

Open the contextual menu and choose **Copy MCP Server**. Paste the URL into your client's MCP configuration.

**2. Or use the install command**

Choose **Copy MCP install command** and run the copied `npx add-mcp` command in your terminal, then follow the prompts for your editor.

**3. Finish setup in your client**

Restart the client and confirm the **Coreflux Documentation** server is connected. See the **Manual** tab for editor-specific configuration examples.

**Manual**

Add the Coreflux MCP server URL to your client's configuration file. Use this method when you need full control over the config or when the contextual menu is unavailable.

**Coreflux MCP Server URL:**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
https://docs.coreflux.org/mcp
```

> [!TIP]
>
> The [Coreflux AI Starter](https://github.com/CorefluxCommunity/coreflux-ai-starter) repository has pre-built MCP config files for Cursor, VS Code, and Claude Desktop — copy the file for your editor instead of writing JSON by hand.

**Cursor**

Cursor supports MCP servers natively. Add the Coreflux MCP to your global configuration or to a specific project.

**1. Open MCP Configuration**

Navigate to your Cursor MCP configuration file. You can use the global configuration at `~/.cursor/mcp.json`, or create a project-level `.cursor/mcp.json` in your workspace root.

**2. Add the Coreflux MCP Server**

Add the following entry to the `mcpServers` object:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux": {
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

**3. Restart Cursor**

Restart Cursor or reload the window for the MCP server to be detected. You should see the Coreflux tools become available in your AI assistant's tool list.

**4. Verify the Connection**

Open Cursor Settings and navigate to the **MCP** section. You should see `coreflux` listed as a connected server with its tools available.

> [!NOTE]
>
> If you already have other MCP servers configured, simply add the `"coreflux"` entry alongside them inside the existing `mcpServers` object.

**Claude Desktop**

Claude Desktop supports MCP servers through its configuration file.

**1. Locate the Configuration File**

Open the Claude Desktop configuration file at:

**Windows**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
%APPDATA%\Claude\claude_desktop_config.json
```

**macOS**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Linux**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
~/.config/Claude/claude_desktop_config.json
```

If the file doesn't exist, create it.

**2. Add the Coreflux MCP Server**

Add or merge the following configuration:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux": {
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

**3. Restart Claude Desktop**

Fully quit and reopen Claude Desktop. The Coreflux tools will appear in Claude's tool picker (the hammer icon) when starting a new conversation.

**Claude.ai**

Claude.ai (the web interface) supports remote MCP server connections through its Integrations settings.

**1. Open Claude.ai Settings**

Go to [claude.ai](https://claude.ai), click your profile icon, and navigate to **Settings**.

**2. Navigate to Integrations**

Select the **Integrations** section in the settings panel.

**3. Add the Coreflux MCP Server**

Click **Add Integration** (or **Add MCP Server**), and enter the Coreflux MCP Server URL:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
https://docs.coreflux.org/mcp
```

Give it a name like **Coreflux** and confirm.

**4. Start a Conversation**

Open a new conversation. The Coreflux tools will be available for Claude to use when relevant to your prompts.

> [!NOTE]
>
> Remote MCP server support on Claude.ai may require a Pro or Team plan. Check your plan's feature availability.

**VS Code**

VS Code supports MCP servers through GitHub Copilot's agent mode. Ensure you have the **GitHub Copilot** extension installed and updated.

**1. Open MCP Configuration**

Create or open the `.vscode/mcp.json` file in your workspace root. Alternatively, you can configure MCP servers globally in your VS Code `settings.json`.

**2. Add the Coreflux MCP Server**

In `.vscode/mcp.json`, add:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "servers": {
    "coreflux": {
      "type": "sse",
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

Or in your global `settings.json`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcp": {
    "servers": {
      "coreflux": {
        "type": "sse",
        "url": "https://docs.coreflux.org/mcp"
      }
    }
  }
}
```

**3. Reload VS Code**

Reload the window (`Ctrl+Shift+P` → **Developer: Reload Window**). The Coreflux MCP tools will become available in Copilot's agent mode.

**4. Confirm trust and enable tools**

After reloading, confirm trust if prompted and open the "Configure Tools" button in the Chat input to verify the tools are enabled in the tool picker before proceeding.

**5. Use in Copilot Chat**

Open the Copilot Chat panel and switch to **Agent** mode. The Coreflux tools will be available for Copilot to call when relevant.

***

## Verify Your Connection

After setup, confirm the MCP is working by sending a test prompt to your AI assistant. The specific prompt doesn't matter — what matters is that the assistant **calls the Coreflux MCP tools** rather than answering from memory.

### Quick Test

Send this prompt to your AI assistant:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Using the Coreflux documentation, show me the correct syntax for 
a LoT Action that triggers every 30 seconds and publishes a 
heartbeat message.
```

> [!TIP]
>
> It's working if your assistant calls one of the MCP tools during its response. In Cursor, you'll see the tool calls in the assistant's output. In Claude Desktop, look for the hammer icon indicating tool usage.

> [!WARNING]
>
> **It's not working** if the assistant answers from general knowledge without calling any Coreflux tools. Double-check your MCP configuration and restart your client.

### What a Connected Response Looks Like

When the MCP is active, your assistant's response will:

* Reference **specific LoT syntax** from the documentation (not invented patterns)
* Include **working code examples** that match the official docs
* Cite **source pages** you can open to verify the information
* Use **correct terminology** — LoT, Actions, Models, Rules, Connectors — exactly as defined in the documentation

Without the MCP, the assistant might still produce LoT-like code, but it will be based on general training data rather than the official Coreflux documentation. Always verify the connection before starting a development session.

***

## Best Practices

> **Be Specific with Your Questions**
>
> The more specific your question, the better the results. Instead of asking "tell me about connectors," try "how do I configure a PostgreSQL data storage connector with authentication." Specific queries help the tools return more relevant documentation.

> **Ask for Source References**
>
> When you need to verify information, ask your assistant to include documentation source links. The Coreflux MCP tools can return references to official pages so you can open and verify the answer yourself.

> **Use for Code Review**
>
> Before deploying LoT code, ask your assistant to validate the syntax against the documentation. For example: *"Check the Coreflux docs — is this the correct syntax for a Modbus TCP connector?"* This ensures your code follows the latest documented patterns.

> **Add the Agent Skills**
>
> The MCP answers questions on demand. On broker 2.22 or later, the [Coreflux agent skills](/ai/agent-skills) give your assistant LoT and broker knowledge before it asks. Install both for the most reliable LoT.

> **Leverage Conversation Context**
>
> The documentation assistant supports multi-turn conversations. Ask follow-up questions to drill deeper into a topic without repeating context — the assistant remembers what you discussed previously in the same conversation.

> [!WARNING]
>
> The Coreflux MCP Server is currently in **beta**. The server URL may change as the service evolves. Check this page for the latest configuration instructions.

***

## Next Steps

> **[Developing LoT Using AI](/ai/developing-with-lot)**
>
> A guide on utilizing AI agents to write, debug, and deploy LoT scripts directly through the MCP interface.

> **[AI-Assisted Development Best Practices](/ai/best-practices)**
>
> Strategic advice on prompt engineering, security guardrails, and maintaining consistency when using AI to manage industrial assets.


# Account, Fleet, and Cloud Mode
Source: https://docs.coreflux.org/hub/account-and-fleet

Sign in to Coreflux HUB with an organization account, open brokers from the fleet, and see how Cloud mode differs from a HUB you run yourself

A Coreflux account is how you see every broker your organization has registered, and how the HUB connects to those brokers without a local password. The account lives at [portal.coreflux.org](https://portal.coreflux.org). The HUB only displays the fleet and opens a broker; registration, licensing, and enrollment stay in the portal.

> [!TIP]
>
> **Like a key cabinet for the sites you run.** Signing in shows the labeled keys (the fleet). Taking a key opens that site. Cutting a new key, or deciding who may hold one, still happens at the front desk — the portal.

## When to use an account

| You want to… | Use |
| - | - |
| Open a broker you saved by host, port, and username | **This machine** on the login card. Those connections stay in this HUB. They do not need an account |
| See brokers the organization registered, and connect as yourself | **Coreflux Fleet**, after **Sign in with Coreflux** |
| Activate a license or enroll a broker you are already connected to | [System Config → License](/hub/system/configuration#license). The portal issues the code or token; the HUB sends it to the broker |

The login card shows **This machine** and **Coreflux Fleet** as two tabs. **This machine** is the default once this HUB has any saved connection. Otherwise the card opens on **Coreflux Fleet**. The tabs are hidden while you are editing a connection.

***

The fleet list is read-only. Nothing on it is starred, edited, or stored as a saved connection.

## Sign in

**Desktop HUB**

The desktop app signs in with no extra configuration. It talks to [portal.coreflux.org](https://portal.coreflux.org).

**1. Open Coreflux Fleet**

On the login card, select **Coreflux Fleet**.

**2. Sign in with Coreflux**

Click **Sign in with Coreflux**. The HUB opens the account sign-in page in your browser and returns to the HUB when it finishes. The card then shows **Signed in as** and your display name.

**3. Sign out**

**Sign out** on that line ends the HUB session. It does not delete saved connections on **This machine**.

If credential storage is off, the card adds **this session only; credential storage is off**. You sign in again after the next launch.

**Browser HUB**

A HUB you open in a browser shows **Sign in with Coreflux** only when the HUB server has all three of these set:

| Variable | Role |
| - | - |
| `COREFLUX_OIDC_CLIENT_ID` | Account client the HUB uses to sign in |
| `HUB_PUBLIC_URL` | Origin users type in the browser, with no trailing slash. The HUB's callback is `{HUB_PUBLIC_URL}/api/account/callback`, and that exact URL must be registered for the account client |
| `HUB_SESSION_SECRET` | Encrypts the session cookie. At least 32 characters. Use the same value on every replica. Changing it signs everyone out |

`COREFLUX_OIDC_CLIENT_SECRET` is optional and only for a confidential client. The desktop app ignores these variables.

To use the HUB assistant in a browser HUB, also set `HUB_AGENT_ALLOWED_HOSTS`. See [Allowed hosts in a browser HUB](/hub/ai-assistant#allowed-hosts-in-a-browser-hub).

The browser never receives the access token. If the session has expired, the HUB reports **Your Coreflux session has expired — sign in again.** If the three variables are missing, a fleet connect reports **Coreflux sign-in is not enabled on this Hub.**

**Signed in as** shows your display name: `preferred_username` from the account token, or your email when that claim is absent. The status bar and the account menu use the same name.

## The fleet list

After sign-in the card shows **FLEET BROKERS** and the count on the same line, for example **FLEET BROKERS 4**.

* **Organization** — A dropdown appears only when the account belongs to more than one organization. **All organizations** lists every membership.
* **Refresh** — Loads the list again.
* **Register broker** — Opens the portal. With one organization, or with one selected in the dropdown, that is the organization's fleet page (`/orgs/…/fleet` on the portal). **All organizations** opens the portal home so you can pick.
* **Sign out** — Ends the account session.

Each row is a broker the platform reported. The HUB does not invent the badges:

| Badge | Meaning |
| - | - |
| **Online**, **Offline**, **Never reported** | An enrolled broker, from the platform's liveness |
| **Enrolling**, **Registered**, **Un-enrolled**, **Requested**, **Deploying**, **Failed**, **Removed** | Any other phase the platform sent |
| **Trial**, **Trial (Growth)**, or **Licensed (Growth)** | The platform's licence bucket. A plan name, when the platform sent one, appears in parentheses |
| **Cloud** or **Self-hosted** | Where that broker runs |

A row the HUB can address has **Connect**. A row that still needs enrollment has **Enrol in portal**. Anything else with no address has **Open in portal**.

Address lines:

* A readable host is shown as `protocol://host:port`.
* A **Cloud** broker with no address yet reads **No address yet — assigned when the deploy finishes**.
* Any other broker with no address reads **No address registered — add one in the portal**.

Empty fleet: **No connections available yet**, with **Register broker**.

The platform did not answer: **Can't reach the Coreflux platform. Your saved connections are unaffected.** **Retry** loads the list again. Saved connections on **This machine** stay usable.

If some organizations loaded and others did not, the rows that loaded stay, with **Couldn't load brokers for .**

**Connect** does not copy the broker into **This machine**. The next time you want that broker from the fleet, you sign in and connect again. A broker you also saved by hand remains a separate card.

## What Connect sends

**Connect** uses your account access token as the MQTT password. The broker must have [OIDC bearer authentication](/latest/mqtt-broker/oidc-authentication) enabled, and its organization binding must include your account. Until [enrollment](/latest/mqtt-broker/licensing) finishes, the broker still accepts local usernames and refuses account tokens.

That is the link between the products:

1. You register and license the broker at [portal.coreflux.org](https://portal.coreflux.org).
2. You enroll the broker so it learns the organization id ([License tab](/hub/system/configuration#license) or `-enroll`).
3. The fleet lists that broker for accounts in the organization.
4. **Connect** presents the account token. The broker maps the token's groups into LoT rules.

The portal's own screens are not documented here. **Register broker**, **Enrol in portal**, and **Open in portal** leave the HUB and open the portal.

## Cloud mode and a HUB you run yourself

Two different "cloud" words show up:

| Name | What it is | What you do |
| - | - | - |
| **Cloud** badge on a fleet row | The broker is hosted for you. **Self-hosted** means the broker runs on infrastructure you operate | Read the badge. You do not set it in the HUB |
| **Cloud mode** on the HUB process | A shared regional HUB. Its MQTT proxy only dials brokers in that region | Leave it off on the desktop app and on a HUB you install beside your own broker |

Desktop and self-hosted HUB builds connect to the broker URL you asked for. That is **This machine** (the host and port you saved) and **Coreflux Fleet** (the address the platform returned).

Cloud mode is on only when the HUB process has `HUB_CLOUD_MODE` set to `true` or `1`. It also needs `HUB_CLOUD_BASE_DOMAIN` (the regional suffix, such as `eu1.coreflux.cloud`). The proxy then accepts only `mqtts://` URLs whose host is a single name under that suffix, on `HUB_CLOUD_BROKER_PORT` (default `8883`). Any other scheme, port, or region is rejected. If Cloud mode is on and `HUB_CLOUD_BASE_DOMAIN` is missing, every connection is rejected.

Do not enable Cloud mode on a desktop app or a HUB container you use to reach a broker on your own network. Those installs leave `HUB_CLOUD_MODE` unset.

Account sign-in and Cloud mode are independent. A self-hosted HUB can show **Sign in with Coreflux** with Cloud mode off, as long as the browser sign-in variables above are set and the brokers accept account tokens.

***

## Limits

> [!WARNING]
>
> The HUB does not register brokers, issue licenses, or complete enrollment by itself. Those stay at [portal.coreflux.org](https://portal.coreflux.org). A fleet row without an address cannot be connected until the portal has one.

* Fleet rows are not editable, and **Connect** does not save a connection.
* Signing in from the connection editor leaves the page and drops an unsaved draft.
* **Sign out** ends the HUB session. The account provider's own browser session can still be active, so the next **Sign in with Coreflux** may not ask for a password.
* The web HUB cannot show token subject or expiry in the connection editor. The browser does not hold the token.

## Next Steps

> **[OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication)**
>
> Configure the broker so an account access token is accepted at MQTT CONNECT.

> **[Licensing and Enrollment](/latest/mqtt-broker/licensing)**
>
> Activate a license and bind the broker to the organization the fleet lists.


# AI Assistant
Source: https://docs.coreflux.org/hub/ai-assistant

Chat with the built-in Coreflux HUB assistant to get insights from live data, build dashboards, and develop LoT Actions using plain language

![Animated sequence: opening the AI Assistant from the dock, typing a prompt, and the assistant responding and applying changes in Coreflux HUB](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-demo.gif?s=a21be6b72ad7e94afe95ee1a9afd6bdb)

Ask the AI Assistant to build something — it opens, drafts, and deploys in the same panel

## Your Broker, Now With a Teammate

The AI Assistant lives inside the same Coreflux MQTT broker that already carries your sensor, PLC, and cloud traffic. You describe what you want in everyday language—**ask for insights** from the data already flowing through your broker, **build Dashboards** with live widgets and KPIs, or **develop LoT (Language of Things) Actions** that run on the broker—and the assistant uses the broker’s own tools to answer, draft, refine, and deploy. It is not a separate chat app pasted on top; it works with your live system.

> [!TIP]
>
> **Like a colleague who already sits at your control desk** — they can read the same screens you see, suggest the next step, and (when you allow it) wire up the change for you.

## When to Use the AI Assistant

* **Ship integrations faster** — Describe connections or logic you need; the assistant drafts and deploys Connectors, Actions, and panels where your permissions allow.
* **Explore without guesswork** — Ask what topics exist, which Connectors are healthy, or how a KPI is calculated before you change anything.
* **Hand off safely** — Use read-only mode for operators or auditors who should see answers but not apply changes.

The picker beside the composer has two kinds of target:

| Target | Where the loop runs | Use it when |
| - | - | - |
| **HUB** | In the HUB, over the broker's [MCP Server](/latest/mqtt-broker/mcp-server) | Conversation with an operator. Provider keys stay on the HUB. Every write asks first |
| **Broker agent** | On the broker, as a `DEFINE AGENT` | The assistant must run with the HUB closed, be called by another agent, or be reached by another service |

A broker agent is a [LoT agent](/latest/lot-language/routes/ai-routes) with `WITH HUB_VISIBLE "true"` and an interaction topic. The HUB does not list a legacy `TYPE AGENT` connector as a target.

## Run Models On-Premise or in the Cloud

Where inference runs is an architecture and compliance choice. The AI Assistant supports **edge (on-premise)** models and **cloud** providers so you can keep prompts and payloads on your network when you need to, or use hosted APIs when policy allows.

![AI Setup provider list grouped into Cloud (OpenAI selected, Anthropic) and Local/Private (Ollama with NO API KEY tag)](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-providers.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=5f2755a9981563d9bd1abcddd9c3d86b)

Provider picker in the AI Setup wizard — cloud providers (OpenAI, Anthropic, OpenAI-compatible) and a local/private option (Ollama)

* **On-premise (edge)** — Run models on hardware you control, for example **Ollama** on the same host or LAN as the broker, so data does not leave your site.
* **Cloud providers** — Connect to hosted models such as **OpenAI** or **Anthropic**, or any **OpenAI-compatible** endpoint, when your organization allows traffic to leave the network.

> [!NOTE]
>
> **Local AI prerequisite:** [Install Ollama](https://ollama.com/download) and have it running on the broker host (or a machine your broker can reach) before you pick **Local / Private** in the setup wizard. Pull your model in Ollama first (e.g. `ollama pull llama3.2`) — the name you enter in step 2 must match a model already available in Ollama. The model must support **tool calling** (function calling); the Assistant relies on tools to act on your broker, so models without tool-calling support will not work. Check the model's capabilities on the [Ollama model library](https://ollama.com/search?c=tools) before pulling it. Coreflux connects to your Ollama endpoint; it does not install Ollama or download models for you. Lightweight models may work for a quick test, but often are not capable enough for reliable agent work or good answer quality.
>
> If the broker runs in **Docker**, `localhost` inside the container is not the host. With **Docker Compose**, point at the Ollama service (e.g. `http://ollama:11434`). If Ollama runs on the host, use `http://host.docker.internal:11434` (Docker Desktop) or the host's LAN IP. On the broker path the wizard writes that URL onto a `TYPE LLM` connector. See [Picking a provider](/latest/lot-language/routes/ai-routes#picking-a-provider).

### Ollama requirements

Ollama is supported with requirements: the model must call tools, and its context must hold the HUB assistant's prompt.

> [!NOTE]
>
> HUB 2.12 sets Ollama's context (`num_ctx`) for each run, so the Ollama setting no longer matters. It uses at least `HUB_OLLAMA_MIN_CTX` (default 16384) and up to `HUB_OLLAMA_MAX_CTX` (default 32768), never above the model's own maximum. A prompt too large for the model ends the run with a clear error instead of being truncated. On low-memory or CPU-only hosts, lower `HUB_OLLAMA_MAX_CTX`.
>
> The same release ends a run when the model sends nothing for `HUB_AGENT_FIRST_OUTPUT_TIMEOUT_MS`, or goes silent mid-answer for `HUB_AGENT_IDLE_TIMEOUT_MS`. Both default to 120000 (120 s), and time spent inside broker tools doesn't count. Raise them on slow hardware, where the first answer can take minutes. These are HUB server environment variables.

> [!NOTE]
>
> On a HUB older than 2.12, raise Ollama's **Settings > Context length** yourself. The prompt is about 4.5k tokens in Insight mode and 9k to 15k tokens in Agent mode, and those versions silently cut the start of it when the context is too small. 16k is the minimum; 128k is a safe choice.

> [!TIP]
>
> The same Assistant panel and modes work whether you point at an edge endpoint or a cloud API—you are not choosing a different product, only where the model runs.

***

## Set up the AI Assistant

The first time you open the AI Assistant, a short wizard asks whether it should run **in the HUB** or **on the broker**, then walks through **provider**, **model**, and **API key**. When the broker path is not signed in as a local broker user, it also asks which broker user the agent's `DEFAULT_USER` should be. You only do this once per broker; after that, clicking the Coreflux icon opens the assistant directly.

> [!NOTE]
>
> The screenshots below were taken on the previous wizard, which installed an agent connector and said "Install the Agent route". The current wizard starts with **In the HUB** (the default) or **On the broker**. The provider, model, and key steps are unchanged.

**1. Open the AI Setup wizard**

Click the **Coreflux** icon in the bottom dock. On a fresh broker, the **AI Setup** wizard slides in on the right and asks you to pick where the model will run—a **Cloud** provider (OpenAI, Anthropic, or an OpenAI-compatible endpoint) or **Local / Private** (Ollama). Pick one and click **Continue**.

![Coreflux HUB with the AI Setup wizard open on the right, titled Set up AI Assistant with the note Install the Agent route on your broker to enable the AI assistant, a step indicator, Cloud providers OpenAI (selected) and Anthropic, Local / Private Ollama tagged No API key, and a Continue button](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/ai-assistant/hub-ai-setup-provider-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=6183b5872491bd19d4bddbc16ebb2130)

AI Setup wizard, step 1: pick a cloud provider (OpenAI, Anthropic, OpenAI-compatible) or a local Ollama model, then Continue

**2. Pick a model**

Choose a model from the suggested list, or type the exact model name your provider supports (for example `gpt-5.4-mini`) into the custom field. Click **Continue** when you are ready.

![AI Setup wizard model step listing suggested models such as gpt-5.5, gpt-5.4-mini, and a custom model field with gpt-5.4-mini typed in](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-setup-model.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=def936ab3298db1a916726f2f79d29fa)

AI Setup wizard step 2 — choose a suggested model or type a custom one

**3. Add your API key**

Paste the API key from your chosen provider. The key is stored as an **encrypted secret on the broker** and is never sent back to your browser. The wizard also shows a quick summary of what it is about to install so you know what to expect.

> [!NOTE]
>
> If you picked **Ollama** in the earlier step, the wizard skips this screen entirely—your local Ollama endpoint does not need a key.

![AI Setup wizard API key step with an OpenAI API key input, a note that the key is stored as an encrypted secret on the broker, and an install summary card](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-setup-apikey.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=558bc27b8c12a978a8f523e591a4c681)

AI Setup wizard step 3 — paste your provider API key; the broker stores it as an encrypted secret

> **Where do I get an API key?**
>
> Sign in to the provider you picked in the previous step and follow their docs to create a key:
>
> * **OpenAI** — [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
> * **Anthropic** — [console.anthropic.com](https://console.anthropic.com/)
> * **OpenAI-compatible** — the key your endpoint's operator issues, if it needs one
>
> If you picked **Ollama**, no key is required—the broker talks to your local Ollama endpoint directly.

**4. Install and you're ready**

Finish the wizard. **In the HUB** stores the provider and an MCP token for this connection, then the assistant calls the broker as that token's user. **On the broker** deploys a `TYPE LLM` connector named `BrokerAgentLlm` and a `DEFINE AGENT` named `BrokerAgent` on the interaction topic `hub/assistant`, visible in the picker. A key you paste is stored with `-setSecret` and referenced from the connector. Ollama needs no key. An OpenAI-compatible endpoint gets a key only when you supply one, and the connector is pinned to Chat Completions.

![AI Setup wizard showing a Setting up AI Assistant progress indicator with Setting API key secret status](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-setup-installing.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=020cb3cafaa3d294a32252521f5dd1ed)

AI Setup finishing — the broker provisions the assistant in the background

> [!TIP]
>
> Once the wizard closes, the AI Assistant is live on this broker. From now on, clicking the **Coreflux** icon opens the assistant directly—no more setup.

**On the broker**, the wizard also adds subscribe rules so your user can read `$SYS/Coreflux/Agents/#` and the `hub/assistant/#` replies. `DEFAULT_USER` is your local MQTT login. A Coreflux account session is not a broker user — the wizard asks for a **Broker user** and will not install until you choose one. A tool call succeeds only when both you and that user are allowed to make it.

The installed agent is granted `read_mqtt`, `read_lot`, `write_mqtt`, and `create_lot` for actions, models, connectors, and panels. Writing grants are deployed with `WITH LEVEL "write"`. Re-running setup sends `-addConnector` and `-addAgent` again. Both update in place, so the agent keeps its conversations. The broker refuses to remove an LLM connector an agent still uses.

Agents are their own LoT entity. Connectors Manager lists `BrokerAgentLlm` and leaves `BrokerAgent` out. The LoT Editor deploys an agent cell with `-addAgent` and removes it with `-removeAgent`.

***

## Manage broker agents

The **Agents** app on the dock lists every `DEFINE AGENT` on the broker as a card, next to an **Activity** tab. Each card has **Configure**, **Disable** / **Enable**, **Open in LoT Editor**, **Show activity**, and **Remove**. A card with no status shows offline. `DEFINE AGENT` is a preview feature in broker 2.22.

### Disable an agent

The power icon on a card redeploys the agent with `DISABLE true`, or without it. A disabled agent stays defined but takes no tasks. Its card is dimmed, with a **Disabled** pill and a grey status dot. On a broker without `DISABLE` support, the HUB changes nothing and says so. In a cluster, the change applies on the node you're connected to.

![Coreflux HUB Agents window, Agents tab, 2 agents: the FlightsTrackerAgent card is dimmed with a Disabled pill and a grey status dot and shows LocalOllama and read\_mqtt (1 topic); the GateOpsAgent card has a green status dot and shows LocalOllama, ollama, llama3.2 and read\_mqtt (1 topic), write\_mqtt (1 topic). Each card has Configure, power, LoT, activity, and remove icons](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/ai-assistant/hub-agents-disabled-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=7ba27b4b2ed67ab48576b3795cf7b319)

Agents app with FlightsTrackerAgent disabled and GateOpsAgent running

### Configure an agent

**Configure** and **Add agent** open a form with three tabs:

| Tab | What you set |
| - | - |
| **Configuration** | Name, LLM connector, description, default user, and **Enabled**. Then the system prompt, guardrails, interaction topic, **Hub visible**, memory, and peers, and the limits (max iterations, max tokens, task timeout, max in flight) |
| **Tools** | The `ADD TOOL` grants, with their topics or targets and level |
| **LoT** | The `DEFINE AGENT` source, with live checks |

![Coreflux HUB Configure GateOpsAgent dialog with Configuration, Tools 2, and LoT tabs; the Agent section shows Name GateOpsAgent, LLM connector LocalOllama, Description Suggests gate changes when departures run late, Default user flights-ops, and the Enabled switch on, with Cancel and Save](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/ai-assistant/hub-agent-config-form-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=221a3bee482408c4063915922e1c1df1)

Configure GateOpsAgent: the Configuration tab

The LoT stays the source of truth. The form rewrites only the clauses you change and keeps everything else as written, including comments, `GET SECRET` and `GET ENV` values, and clauses the form has no field for, which it lists under **Kept as written**. **Save** deploys with `-addAgent`. Running tasks and session memory are kept unless you rename the agent. See [Agent syntax](/latest/lot-language/agents/syntax).

***

## Coming from a TYPE AGENT assistant

A `TYPE AGENT` connector from an earlier release is skipped when the broker loads, and the HUB does not list it, install it, or migrate it. There is no in-panel update that rewrites it.

Rewrite it as a `TYPE LLM` connector plus `DEFINE AGENT`, using the table in [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent), or run the wizard again and let it install `BrokerAgentLlm` and `BrokerAgent`. Your previous provider, model, and key are not copied for you.

> [!NOTE]
>
> The setup wizard is how you install the assistant. It is not a settings screen for an assistant that is already there. Once the HUB target is configured, the menu offers **Change Hub provider…**, which updates the provider, key, and model and keeps the same MCP token.

***

## Open the AI Assistant

Use the **Coreflux** icon in the bottom app dock—the first icon on the left. You can peek at the assistant without opening the full side panel, then click when you want the full workspace.

**1. Hover to preview**

Hover the Coreflux icon. A compact **Coreflux AI** bubble appears above the dock with an **Ask anything…** field and **Insight** / **Agent** mode pills so you can send a quick prompt or pick a mode before you commit to the full panel.

![Coreflux HUB dock with the Coreflux icon highlighted and a compact Coreflux AI popover showing Ask anything placeholder and Insight and Agent toggles](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-hover.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=4832f01bd4c40af988f40d1c774d0d31)

Hover the dock Coreflux icon to open the compact Coreflux AI bubble with Ask anything and mode pills

**2. Click to open the full panel**

Click the Coreflux icon to pin the **AI Assistant** on the right. You get suggested prompts (for example **Create a dashboard** or **Calculate a new KPI**), a **Sources** area for dragging in panels such as the LoT Editor, and the full conversation thread with edit and close controls in the header.

![Coreflux HUB with the full AI Assistant panel open showing suggested actions, Sources with LoT Editor, and Ask me anything input](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-open.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=051b1570ab0d0c92aebdee66e0254294)

Full AI Assistant panel — suggested prompts, Sources, and the main chat input

## Agent vs Insight mode

Pick the mode that matches how much change you want the assistant to make. You can switch at the bottom of the panel at any time.

| Mode | What it does | Use it when |
| - | - | - |
| **Agent** | Can read broker state **and** create or update things—Connectors, Actions, Models, panels—subject to your permissions. On the **HUB** target, each write pauses for Approve or Reject. On a **broker agent**, writing tools run when the grant says `WITH LEVEL "write"` and both you and `DEFAULT_USER` are allowed. | You want the assistant to **build or change** integrations, logic, or dashboards. |
| **Insight** | **Read-only.** The HUB target never shows write tools. A broker agent is sent `"mode": "insight"`, and the broker refuses every writing tool as out of scope, including tools a peer agent would have run. | You want **safe exploration**, reporting, or to give users answers **without** deploy rights. |

The mode pills sit below the main input so you always know which behavior you have selected before you send a message.

## What you can do

These are typical starting points—phrase them in your own words; the assistant will ask follow-ups if something is missing.

> **[Build a dashboard](/hub/dashboards/overview)**
>
> Ask for live gauges, KPI tiles, or layouts bound to your MQTT topics; the assistant drafts and wires widgets you can refine in the panel. See [Build Your First Dashboard](/latest/quick-start/building-dashboards).

> **Develop an Action in LoT**
>
> Describe triggers, conditions, and outputs in plain language; the assistant proposes LoT you review and deploy without leaving the conversation.

> **Calculate a new KPI**
>
> Describe the metric or inputs you care about; the assistant drafts logic, confirms details with you, and deploys an Action in Agent mode.

> **Explain your broker state**
>
> Ask what Connectors or topics exist, why something errored, or how signals relate—natural in Insight mode when you want answers before any changes.

***

## Example: Build a KPI with Agent mode

Below is one real flow: you ask for a KPI, the assistant requests the missing pieces, then deploys an Action and offers a shortcut to the LoT Editor. Stay in **Agent** mode for this path.

**1. Ask**

Type a goal such as **Calculate a new KPI**. The assistant loads context and may offer quick actions that match what you said.

![AI Assistant showing Agent mode selected and suggested prompts including Calculate a new KPI](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-open.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=051b1570ab0d0c92aebdee66e0254294)

AI Assistant in Agent mode with suggested prompts including Calculate a new KPI

**2. Clarify**

When the assistant needs a formula, source topic, or rule, it **pauses and asks you directly**—you reply in the thread instead of guessing what to type up front.

![AI Assistant conversation where the assistant asks the user to provide KPI formula or source data with a Type your answer field](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-ask-user.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=8ce9eee3ebf0ebfe0e336b4734dbf7ce)

Assistant asking for KPI formula or source data before continuing

**3. Deploy**

After you supply enough detail, the assistant can draft LoT, deploy an Action, and show a status card. Use **Open in LoT Editor** when you want to inspect or tweak the definition yourself.

![AI Assistant showing deployed CalculateKPI Action with Running status and Open in LoT Editor link](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-action-deployed.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=a84807cf92b4bb27a348a2bc1d9b0f87)

Deployed Action with Running status and Open in LoT Editor link

> [!TIP]
>
> When you see **Running** (or equivalent success state) on the deployment card, the new Action is live on the broker—confirm in the **LoT Editor** if you want to read the exact definition.

***

## Example: Explore safely with Insight mode

Switch to **Insight** before you send if you only want answers—not changes. You can still get structured output such as tables and follow-up suggestions.

![AI Assistant in Insight mode responding to 'Please create a list of connectors I have on broker' with a table showing Name, Type, Status, Description, and Events columns for Terminal, BrokerAgent, and MyS7Route](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-insight-routes.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=93cc5ba1d07a972a3e4aad3faf1a075a)

Insight mode — list of Connectors returned as a table after a natural-language question

Try questions like **Create me a list of Connectors** or **Which Connectors are in a warning state?** The assistant reads broker state and renders the response in the panel without using write tools.

## Built-in safeguards

* **The HUB target runs as the MCP token's user** — Every call passes the broker's own permission check. Writes pause until you approve them. A request that names no mode is treated as Insight.
* **A broker agent runs as the person who asked, capped by `DEFAULT_USER`** — Both must be allowed. A refusal names the user who lacked the right.
* **Insight mode is read-only** — No deploy, publish, or execute path while Insight is selected.
* **Stop at any time** — Long runs can be cancelled from the UI so you are never stuck waiting on a runaway answer.
* **Same deployment path as humans** — Anything the assistant deploys still goes through the broker’s normal validation and permission checks.
* **A shared web HUB does not call arbitrary hosts**: see [Allowed hosts in a browser HUB](#allowed-hosts-in-a-browser-hub).

### Allowed hosts in a browser HUB

The HUB assistant connects from the HUB server to the broker's MCP endpoint and, for Ollama or an OpenAI-compatible provider, to the model's base URL. On a browser or Docker HUB that other people can reach, the assistant stays off until both of these are true:

1. [Coreflux sign-in](/hub/account-and-fleet#sign-in) is configured on the HUB server, and the user is signed in.
2. `HUB_AGENT_ALLOWED_HOSTS` lists the hosts the assistant may reach.

| Variable | Role |
| - | - |
| `HUB_AGENT_ALLOWED_HOSTS` | Comma-separated list of the broker MCP hosts and Ollama or OpenAI-compatible servers the HUB assistant may connect to. A bare host (`broker.example.com`) matches any port. `host:port` (`10.0.0.5:6278`) matches only that port. Matching is exact and case-insensitive: `evilbroker.example.com` does not match `broker.example.com` |

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
HUB_AGENT_ALLOWED_HOSTS=broker.example.com,10.0.0.5:6278
```

* **Unset or empty**: the assistant is off and reports **HUB\_AGENT\_ALLOWED\_HOSTS names no broker it may reach.**
* **Sign-in not configured**: the assistant is off and tells you to use a broker agent or the desktop app.
* **Not signed in**: **Sign in with your Coreflux account to use the Hub assistant.**
* **Host not listed**: **This Hub may not reach `<host>`. Add it to HUB\_AGENT\_ALLOWED\_HOSTS.**

OpenAI and Anthropic use their fixed API addresses and need no entry. The desktop app listens only on loopback and ignores this variable. Broker agents run on the broker and are not affected.

***

## Broker agents in the HUB

**LoT → Agents** (also the dock and the status-bar **Agents** widget) is where you manage broker agents and watch them work. Add and configure from that window. Saving an existing agent sends `-addAgent` again, which updates it in place and keeps its conversations. Removing an agent cancels its running tasks and forgets its session memory. The activity view is read-only: it follows the task stream, and a question started by `CALL AGENT` shows up as a short preview.

Connectors Manager lists connectors only. An LLM connector can show how many agents use it. The broker refuses to remove that connector while an agent still names it.

***

## Best practices

> **Start in Insight when you are learning**
>
> Use Insight to map topics, Connectors, and health first. Switch to Agent only when you are ready for the assistant to create or update broker objects.

> **Always review what was deployed**
>
> Open new Actions or Connectors in the **LoT Editor** or **Connectors** app to read names, triggers, and bindings before you rely on them in production.

## Next steps

> **[LoT Editor](/hub/lot-editor)**
>
> Open and refine Actions, Models, and Rules the assistant creates—same editor, full control.

> **[Connectors overview](/hub/routes/overview)**
>
> Add or monitor Connectors the assistant can read and help you configure next.


# Cluster Viewer
Source: https://docs.coreflux.org/hub/cluster-viewer

See the nodes, leader, links, LoT ownership, and partitions of a Coreflux cluster from the broker host you are connected to

## Why Use Cluster Viewer?

A cluster is several broker hosts acting as one system. Cluster Viewer draws that system from the broker host you are already connected to, so you can see who leads, which links are up, which node owns each exclusive piece of LoT, and how partitions are placed — without opening a shell on every host.

> [!NOTE]
>
> Cluster Viewer carries a **Beta** badge on its window. The dock icon is labeled **Cluster**. It appears only while the connected broker host is publishing cluster status.

> [!TIP]
>
> **Like a seating chart that updates itself.** You see who is leading, who is sitting in, and who is holding each shared task — from the one host you opened.

## When to Use It

* **Confirm the cluster is up** — See which members are alive and who the leader is
* **Check a link** — See whether data-plane links between hosts are connected
* **Find who runs an exclusive piece of LoT** — Timers, `ON START` actions, exclusive connectors, and scheduled connector events run on one node
* **See partition placement** — See which host owns each partition and where the copies sit

Clustering is an Enterprise license feature. If the license does not grant it, the broker runs standalone and this icon stays off the dock. See [High-availability clustering](/latest/mqtt-broker/clustering) and [Licensing](/latest/mqtt-broker/licensing).

***

Open **Cluster** on the dock. The window is read-only. It reads the cluster status the connected broker host publishes. It does not elect a leader, move ownership, or change cluster settings.

If clustering is off, the icon is not on the dock. Opening the window another way shows that the connected broker is not publishing cluster status.

## What the Window Shows

A strip across the top summarizes the cluster as this broker host sees it:

| Item | What it tells you |
| - | - |
| **Cluster** | The cluster identity |
| **Leader** | The host that currently leads |
| **Members** | How many members are alive out of the member count |
| **Term** / **Commit** | How far leader election and the committed log have progressed |
| **LoT** | Whether nodes are on the same committed LoT version, or the versions are mixed |
| **Data plane** | How many links between hosts are up |
| **Listeners** | Whether any server-connector listener on a member has failed |

The strip also says the view is **Live** (or how old the status is), which host you are seeing it from, and that it is **read-only**.

The canvas draws each member and the links between them. Select a node to open it on the **Node** tab. Select a link to see each direction. The leader is marked on its node. A host the status names but does not describe yet is drawn as unidentified.

> [!WARNING]
>
> The picture is the view from the broker host you are connected to. It is not a second login to every member.

## Details

**Node**

The selected host: whether it is alive, its role, and its endpoint when the cluster published one.

For the host you are connected to, the tab also shows the term and commit index, and whether that host holds the LoT lease.

**LoT** shows the version this host has applied against the version the cluster has committed, whether those match, and any apply errors. **Connector listeners** lists the server connectors that host reported. **Outgoing data-plane links** lists the links that start on this host.

![Coreflux HUB Cluster Viewer window with the Node tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the node details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-node-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=3304d205524e2aaa61ab65c8148a1547)

Node tab: the selected host, its role, LoT version, connector listeners, and outgoing data-plane links

**Links**

**Replication** on the host you are connected to: connected peers, forward backlog, dropped forwards, quorum failures, and how long the last quorum took.

**Data-plane links** lists every reported link, with its state (connected, connecting, disconnected, or unknown). A stale report is marked stale.

![Coreflux HUB Cluster Viewer window with the Links tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the links details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-links-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=b6c4bc1d5c2b32904f7410f31fd3fc97)

Links tab: replication on the connected host and the state of every data-plane link

**Ownership**

Which host runs each piece of LoT that must run on exactly one node:

| Kind | What it is |
| - | - |
| **Actions (timers, ON START)** | Scheduled actions, and actions that run once when the cluster session starts |
| **Exclusive connectors** | Connectors that hold a device, a serial port, or a server port |
| **Scheduled connector events** | A connector's timed events |

**Owner** is the host that runs it. **Next** is the host that takes it if the owner is lost. **Epoch** goes up each time the entity moves. **Unowned** means no live host can run it, so it runs nowhere until one can. An exclusive connector is defined on every node, but only its owner opens the connection. The others hold it ready.

Select a node on the canvas first if you want the list limited to entities that node owns.

![Coreflux HUB Cluster Viewer window with the Ownership tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the ownership details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-ownership-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=3098b8f9b250f96a0bc10111f13db364)

Ownership tab: which host owns each exclusive action, connector, and scheduled connector event

**Partitions**

The partition map: how many partitions there are, the replication factor, how many are under-replicated, and which host owns each one.

Under-replicated partitions still work. Their replica set is smaller than the factor because there are not enough live hosts to place every copy — for example while a host is down. A healthy cluster shows none.

Pick a host to highlight the partitions it owns, the ones where it only keeps a copy, and the ones it does not hold.

![Coreflux HUB Cluster Viewer window with the Partitions tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the partitions details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-partitions-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=08e8a96be261df65232867e5e2f0b2a9)

Partitions tab: the partition map, replication factor, and owner of each partition

**Clients**

The MQTT clients connected to each node right now, with a total across the cluster. A client is connected to one node. Behind a load balancer, the node can change each time it reconnects.

Under **Show the clients of**, pick **All nodes** or one node. Filter by client ID, user, or address, and sort by **Last active**, **Newest connection**, **Most queued**, or **Client id**. The connections the nodes open to each other are hidden unless you turn on **Show the cluster's own connections**.

Each card shows the client ID, user, address, MQTT version, messages in and out, and when it was last active. A **queued** badge counts messages waiting for that client; a number that keeps growing means the client isn't keeping up. Expand a card for when it connected, its last packet, bytes in and out, and how long the broker keeps its session after it disconnects.

Lists refresh every 7 seconds. Other nodes' clients are relayed by those nodes, so they can be a few seconds older. An older broker reports only the clients of the node you're connected to.

![Coreflux HUB Cluster Viewer for cluster acme-plant, leader acme-mqtt-2, 3/3 members alive. The Clients tab shows 9 clients (+12 cluster connections) and 0 queued messages, the node filters All nodes, acme-mqtt-1 4, acme-mqtt-2 3, and acme-mqtt-3 2, the filter box, the Last active sort, and the Show the cluster's own connections checkbox, above cards for hmi-panel-03, the HUB's own connection, line1-plc-gw, and energy-meter-gw, each with node, user, address, MQTT version, messages in and out, and last activity](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-clients-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=c447f955d698db7e81dfa195823d229a)

Clients tab on a three-node cluster: nine clients across acme-mqtt-1, acme-mqtt-2, and acme-mqtt-3, sorted by last active

An older broker host may publish only part of this view. The window then names what is missing and still shows the status it did receive.

***

## Next Steps

> **[High-Availability Clustering](/latest/mqtt-broker/clustering)**
>
> Turn clustering on, choose discovery, and read what failover does and does not cover.

> **[Connections Manager](/hub/connections)**
>
> Open the broker host whose cluster status this window reads.


# Connections Manager
Source: https://docs.coreflux.org/hub/connections

Save multiple broker connections, switch between them without logging out, and secure each one with its own TLS certificates

![Coreflux HUB login card with Local Connections 2: Coreflux local at mqtt://localhost:18840 tagged Coreflux and Mosquitto local at mqtt://localhost:18830 tagged MQTT, both Online with an anonymous identity and Connect buttons, plus All and Starred filters and New Connection](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/connections/hub-login-screen-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=19b9b3a1e41004e0baee97fcf8ccdf4b)

Coreflux HUB login screen with two saved local connections, their broker type and live status, and a New Connection button

## Why Use the Connections Manager

If you work with more than one broker — a local development instance, a staging cluster, a production site — the HUB remembers each one as a saved connection instead of a single remembered URL. Pick a broker from the list to sign in, probe every saved broker for reachability before you commit, and jump between brokers from the account menu without logging out and re-entering details.

## Adding a Connection

**1. Open New Connection**

On the login screen, click **New Connection** in the header (or click a saved card's edit action to modify an existing one). The connection form opens in the same card.

**2. Fill in the broker details**

Enter a name, the **Protocol** (`mqtt://`, `mqtts://`, `ws://`, or `wss://`), **Host**, and **Port**. For a HUB and broker started together with Docker Compose, use **Host** `broker` rather than `localhost` — the HUB proxies MQTT from inside Docker.

![Coreflux HUB connection form for Coreflux local with protocol mqtt://, host localhost, port 18840, the preview mqtt://localhost:18840, an Authentication row No username or password marked Default, Add user, Advanced options, and Save, Test, and Connect buttons](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/connections/hub-login-setup-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=8a0bc7ffdfd5adeaff1721a8a0c3acf2)

Connection form for Coreflux local: name, protocol, host, port, and its identities

**3. Add an identity**

Add at least one identity: a username and password, or an anonymous identity if the broker allows anonymous access. A connection can hold several identities — see [Identities and Switch User](#identities-and-switch-user) below.

**4. Test, then Save or Connect**

Click **Test** to attempt a throwaway connection with the details you entered, without saving anything. Click **Save** to store the connection for later, or **Connect** to save and sign in immediately.

## Default connection (web / Docker)

A web HUB started with Docker can open **New Connection** with the broker already filled in, so a lab or demo does not make every visitor type the address. Set the variables on the HUB container. The HUB reads them when the container starts. The desktop app ignores them.

Setting `HUB_DEFAULT_CONNECTION_HOST` turns the feature on. The other variables are optional. The values pre-fill the **New Connection** form only. They never create or rewrite a saved connection. The connection is stored when someone clicks **Save** or **Connect**, the same as a form they typed.

| Variable | What it sets |
| - | - |
| `HUB_DEFAULT_CONNECTION_HOST` | Broker host. Setting this turns the feature on |
| `HUB_DEFAULT_CONNECTION_NAME` | Name on the form. When omitted, the name is filled in when the connection is saved |
| `HUB_DEFAULT_CONNECTION_PROTOCOL` | `mqtt`, `mqtts`, `ws`, or `wss`. A trailing `://` is accepted. When omitted, the form uses `ws` |
| `HUB_DEFAULT_CONNECTION_PORT` | Port. When omitted, the usual port for that protocol |
| `HUB_DEFAULT_CONNECTION_PATH` | WebSocket path. When omitted, `mqtt` |
| `HUB_DEFAULT_CONNECTION_USERNAME` | Username on the form. When omitted, the form keeps its usual default identity |
| `HUB_DEFAULT_CONNECTION_PASSWORD` | Password for that username. Ignored when no username is set |

The [Compose example](/latest/quick-start/installation) sets host `broker`, protocol `mqtt`, and port `1883` for a broker on the same Docker network.

> [!WARNING]
>
> The password is delivered to every browser that loads the HUB. Use this only for shared lab or demo credentials.

## Saved Connections

Each saved connection appears as a card on the login screen, showing its name, broker URL, and a reachability status the HUB probes in the background. You can see whether that broker answers before you open it.

| Status | Meaning |
| - | - |
| **Checking** | The HUB is still probing this broker |
| **Online** | The broker answered |
| **Sign-in failed** | The broker answered, and the last sign-in did not succeed |
| **Offline** | The broker did not answer |

* **Favorites** — star a connection to pin it; use the **All / Starred** filter above the list to narrow the view.
* **Reorder** — drag a card to change its position in the list.
* **Connect** — pick an identity from the card's dropdown and click **Connect**. With a card focused, the Enter key does the same.
* **Edit or delete** — open a card to change its details, or remove it entirely.

## Identities and Switch User

A single saved connection can hold more than one identity — for example a day-to-day account and an admin account on the same broker. Mark one identity as the **default** for that connection, and switch between the others from the account pill without leaving the app: choose **Switch user** to reconnect as a different identity on the *current* broker, or **Switch broker** to reconnect to a *different* saved connection (using that connection's default identity). Both close the current session cleanly and reopen it against the new target. The rest of that menu is covered in [Desktop shell](/hub/overview#logo-and-the-account-pill).

## Securing a Connection with TLS

For `mqtts://` and `wss://` connections, open the connection's detail panel to attach TLS material:

* A **CA certificate**, if the broker's certificate isn't already trusted by your system.
* A **client certificate and private key**, for brokers that require mutual TLS.

Server certificate verification is on by default for secure connections; only turn it off for trusted development brokers.

> [!NOTE]
>
> This is separate from **connector** certificate management (trust stores for OPC UA and similar connectors running *on* the broker) — see the connector's own Certificate Management section when you configure a [Connector](/hub/routes/overview).

## When the Broker Is Not Coreflux

The HUB detects the broker when you connect. You do not pick a broker type.

When the connection is a generic MQTT broker, the dock keeps **Data Viewer** and **UNS Viewer**. Connectors, the LoT Editor, LoT Flow, Dashboards, and Cluster stay hidden. The status bar offers **Know more about Coreflux**, which explains what a Coreflux broker adds and links to the docs, the install guide, and [coreflux.org](https://coreflux.org). The account menu does not show **LoT Templates** or broker administration.

While the HUB is still checking, the dock shows those same two apps. **Know more about Coreflux** appears once the check settles on a generic broker.

After that session, the saved card is tagged **MQTT**. A card tagged **Coreflux** means the last session reached a Coreflux broker, and the usual apps are available. The tag is absent until a session has settled.

> [!NOTE]
>
> A Coreflux user without system access is still a Coreflux broker. You keep the usual apps. The LoT Editor still needs system access on that broker host, and the status bar can show **No SYS**. That session is not the generic-broker case, and the card is tagged **Coreflux**.

## Where Credentials Are Stored

* **Desktop app** — passwords and the TLS private key are encrypted at rest using your operating system's secure storage. They are never written to the plain settings file the HUB otherwise syncs to disk.
* **Browser app** — credentials are kept for the session and are not written to disk by the HUB; use your browser's own security practices (a trusted device, a locked profile) when saving connections there.

The broker's TLS **certificate** (the public part) can still be attached to a saved connection either way, since it isn't sensitive.

## Coreflux account and fleet

Saved connections are the **This machine** tab: a host, a port, and a username you store in this HUB. **Coreflux Fleet** is the other tab. It lists brokers your organization registered at [portal.coreflux.org](https://portal.coreflux.org) and connects with your account token instead of a saved password. Fleet rows are not added to this list. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).

***

## Next Steps

> **[Installation](/latest/quick-start/installation)**
>
> Install the broker and HUB, and make your first connection.

> **[Managing Connectors](/hub/routes/overview)**
>
> Configure connectors, including per-connector TLS trust stores.


# Container Components
Source: https://docs.coreflux.org/hub/dashboards/components/containers

Group dashboard components with cards and tabs to structure larger panels in the Coreflux HUB.

![A titled Zone 1 Status card containing a temperature readout, a status indicator, and a Details button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/card-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=6f70e4f99fc925a6f366c02adce28287)

A card grouping an asset's readout, status, and action into one unit on the panel grid

Containers group other components. Use them when a panel grows beyond a simple grid — to cluster a machine's readouts under one title or split a screen into tabs.

> [!TIP]
>
> **Like trays on a workbench.** The bench grid holds the trays in place; each tray keeps one job's tools together so they move as a unit.

***

Two containers are available today: `card` for grouping, `tabs` for splitting.

## Card

Groups child components under a title.

**Basic**

A titled card with one readout inside:

![A titled Zone 1 Status card containing a temperature readout](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/card-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=35f61413a5bb1c975c70b82b6ed1fdb0)

A titled card grouping a single temperature readout

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StatusCard" WITH TYPE "card"
    SET TITLE "Zone 1 Status"

    ADD COMPONENT "TempReading" WITH TYPE "value"
        BIND VALUE TO TOPIC "zone1/temperature"
        SET UNIT "°C"
```

**Full example**

A card combining a readout, an indicator, and a navigation button — the two extra children are the new parts:

![A titled Zone 1 Status card with a temperature value, a status indicator, and a Details button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/card-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=6f70e4f99fc925a6f366c02adce28287)

A Zone 1 Status card with a temperature readout, a status indicator, and a Details button

```lot wrap focus={9-17} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StatusCard" WITH TYPE "card"
    SET TITLE "Zone 1 Status"

    ADD COMPONENT "TempReading" WITH TYPE "value"
        BIND VALUE TO TOPIC "zone1/temperature"
        SET UNIT "°C"

    ADD COMPONENT "StatusIndicator" WITH TYPE "indicator"
        BIND STATE TO TOPIC "zone1/status"
        SET ON_VALUE "running" WITH COLOR "green"
        SET ON_VALUE "stopped" WITH COLOR "red"

    ADD COMPONENT "DetailsButton" WITH TYPE "button"
        SET LABEL "Details"
        ON CLICK DO NAVIGATE TO PANEL "Zone1Details"
```

| Property | Type | Description |
| - | - | - |
| `TITLE` | String | Card heading |

## Tabs

Each tab holds its own components — useful for Overview / Analytics / Settings splits on one screen.

> [!NOTE]
>
> In the current HUB build, tab headers show the **inner component name** rather than the `ADD TAB` title. The structure below matches the spec syntax; tab labelling is tracked as a known issue.

**Basic**

![A tabbed container switching between sub-views on one panel](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/tabs.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=190e1e6a76ff7681e1b9e88d412482db)

A tab strip switching between sub-views on one panel (current build labels tabs from their content)

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MainTabs" WITH TYPE "tabs"

    ADD TAB "Overview"
        ADD COMPONENT "OvTemp" WITH TYPE "value"
            BIND VALUE TO TOPIC "zone1/temperature"
            SET UNIT "°C"

    ADD TAB "Analytics"
        ADD COMPONENT "OvGauge" WITH TYPE "gauge"
            SET RANGE FROM 0 TO 100
            BIND VALUE TO TOPIC "zone1/temperature"

    ADD TAB "Settings"
        ADD COMPONENT "OvText" WITH TYPE "text"
            SET LABEL "Settings go here"
```

## Card vs. grid position?

Use **grid positioning** (`AT COLUMN/ROW`) when components are independent readouts. Use a **card** when components belong to the same asset and should travel together — a card moves as one unit when you rearrange the panel. See [Mixing layouts with cards](/latest/lot-language/panels/defining-panels#mixing-layouts-with-cards) for a complete panel that combines both.

## Next Steps

> **[Display components](/hub/dashboards/components/display)**
>
> The readouts you place inside cards and tabs.

> **[Common patterns](/hub/dashboards/patterns)**
>
> Full panels that combine containers with live data.


# Display Components
Source: https://docs.coreflux.org/hub/dashboards/components/display

Read-only widgets: gauges, values, indicators, charts, tables, and alerts.

![A dashboard panel showing several display widgets: a temperature gauge, a pressure readout, a green machine status indicator, a status text line, and a live throughput chart](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/display-showcase.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=348c7d4807b7d8847dcdae57138286c7)

A showcase panel mixing the display widgets on this page: a gauge, a value readout, an indicator, text, and a live chart

Display components show live data without accepting input. Each entry below opens with tabbed examples — the rendered result above the code that produces it — followed by the property reference.

> [!TIP]
>
> **Like instruments on a car dashboard.** Each one reads a signal and shows it its own way — a dial, a number, a warning light — and none of them lets you steer.

***

## Gauge

Circular (radial) or linear gauge for numeric values.

**Basic**

A radial gauge bound to a temperature topic:

![Radial gauge filled about two-thirds with an orange arc, reading 82.0 °C](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/gauge.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=9c3c9dd97bd0c144c93478b5cfbbebb4)

A radial gauge bound to a temperature topic, reading 82.0 °C

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "TempGauge" WITH TYPE "gauge"
    SET RANGE FROM 0 TO 100
    SET UNIT "°C"
    BIND VALUE TO TOPIC "sensor/temperature"
```

**Full example**

A gauge with a label, one decimal place, and two configured thresholds:

![Radial gauge labeled Production Rate showing the live production rate](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/gauge-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=c2fff65712d01bc3505ca6ee6882f1f2)

A labeled production-rate gauge with warning and critical thresholds configured

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ProductionGauge" WITH TYPE "gauge"
    SET STYLE "radial"
    SET RANGE FROM 0 TO 100
    SET UNIT "units/hr"
    SET LABEL "Production Rate"
    SET DECIMALS 1
    BIND VALUE TO TOPIC "factory/production/rate"
    ADD THRESHOLD AT 75 WITH COLOR "warning" LABEL "High"
    ADD THRESHOLD AT 90 WITH COLOR "critical" LABEL "Critical"
```

| Property | Type | Default | Description |
| - | - | - | - |
| `STYLE` | `"radial"` / `"linear"` | `"radial"` | Gauge appearance |
| `RANGE FROM x TO y` | Numbers | required | Min / max values |
| `UNIT` | String | `""` | Unit label |
| `LABEL` | String | `""` | Display label |
| `DECIMALS` | Integer | `0` | Decimal places |

**Bind targets:** `VALUE`, `MIN`, `MAX`

## Value

The simplest read-only display: a number or string, with unit and formatting.

**Basic**

A pressure readout with two decimals:

![Numeric value readout showing 3.42 bar](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/value-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=ce3c932fe08a63c8a6d1528570477a5d)

A numeric readout showing the live pump pressure in bar

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "PressureDisplay" WITH TYPE "value"
    BIND VALUE TO TOPIC "pump/pressure"
    SET UNIT "bar"
    SET DECIMALS 2
```

**A JSON Data example**

Extracting one field from a JSON MQTT payload — `JSON_PATH` and the label are the new parts:

![Large numeric value readout showing 1284.50 Wh extracted from a JSON payload](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/value.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=548c92c9d46401efb14f5eb377c66b9d)

The value widget showing 1284.50 Wh, extracted from a JSON payload field

```lot wrap focus={3,5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "EnergyDisplay" WITH TYPE "value"
    BIND VALUE TO TOPIC "machines/pump1/data"
    SET JSON_PATH "$.energy_wh"
    SET UNIT "Wh"
    SET LABEL "Energy"
    SET DECIMALS 2
```

| Property | Type | Default | Description |
| - | - | - | - |
| `UNIT` | String | `""` | Unit label |
| `LABEL` | String | `""` | Display label |
| `DECIMALS` | Integer | `0` | Decimal places |
| `JSON_PATH` | String | — | JSONPath to extract from payload |

**Bind targets:** `VALUE`, `MAX`

> [!NOTE]
>
> If your topic carries a JSON object rather than a plain number, set `JSON_PATH` to pick the field — otherwise the widget shows the raw payload. Inspect the payload first in the [Data Viewer](/hub/mqtt/data-viewer).

## Text / Label

Dynamic or static text. `label` is an alias for `text`.

**Basic**

A static heading rendered at large size:

![A large static text line reading Zone 1 Overview](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/text-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=4f14a1b82c246e6d1d6ef0fef794a6d4)

A static section heading rendered at large size

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "SectionTitle" WITH TYPE "label"
    SET LABEL "Zone 1 Overview"
    SET SIZE "large"
```

**Full example**

Dynamic text whose content updates live from the broker — the `BIND CONTENT` line is what makes it live:

![A large text line showing a live status message from the system message topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/text-live.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=2900e1241db40d85f0dcb642093e2b85)

A large status line whose text updates live from the system message topic

```lot wrap focus={2} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StatusText" WITH TYPE "text"
    BIND CONTENT TO TOPIC "system/message"
    SET SIZE "large"
```

| Property | Type | Default | Description |
| - | - | - | - |
| `SIZE` | `"small"` / `"medium"` / `"large"` | `"medium"` | Font size |
| `COLOR` | Color string | `"inherit"` | Text color |
| `MARKDOWN` | Boolean | `false` | Render the content as sanitized markdown. Raw HTML, images, and unsafe links are removed |

`SET MARKDOWN true` formats a bound briefing or note. A full panel is in [Markdown text](/latest/lot-language/panels/defining-panels#markdown-text).

**Bind targets:** `CONTENT`, `COLOR`, `TITLE`, `LABEL`

## Indicator

Maps incoming values to colors — running/stopped/fault at a glance.

**Basic**

A pump-running dot — green when the bound topic reads `true`:

![A green pump status indicator dot](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/indicator-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=74db3c3c0743e148f76a6c05d8234978)

A status dot that turns green while the pump-running topic reads true

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "PumpIndicator" WITH TYPE "indicator"
    BIND STATE TO TOPIC "pump/running"
    SET ON_VALUE "true" WITH COLOR "success"
    SET ON_VALUE "false" WITH COLOR "muted"
```

**Full example**

Three states mapped to three colors, rendered large — the extra mapping and size are highlighted:

![A large green machine status indicator dot for the running state](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/indicator-large.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d03616ddc371adef4b1c5e5fe2c66780)

A large green dot for running; switches to red or yellow as the status topic changes

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MachineStatus" WITH TYPE "indicator"
    BIND STATE TO TOPIC "machine/status"
    SET ON_VALUE "running" WITH COLOR "green"
    SET ON_VALUE "stopped" WITH COLOR "red"
    SET ON_VALUE "maintenance" WITH COLOR "yellow"
    SET SIZE "large"
```

| Property | Type | Default | Description |
| - | - | - | - |
| `ON_VALUE` | `"state" WITH COLOR "color"` | required | One or more value-to-color mappings |
| `SIZE` | `"small"` / `"medium"` / `"large"` | `"medium"` | Indicator dot size |

**Bind targets:** `STATE`

## Realtime Chart

Live streaming chart — it receives **individual data points** from a topic and builds the trend itself.

**Basic**

One topic, one trace — every published value becomes a point:

![A realtime line chart labeled Line Throughput trending as values arrive](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/realtime-chart-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=a44d88f1acd67db81e2173eb9de35619)

A realtime-chart building a live trend point by point from the throughput topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ThroughputTrend" WITH TYPE "realtime-chart"
    SET LABEL "Line Throughput"
    BIND VALUE TO TOPIC "factory/throughput"
```

**Full example**

The same idea with an explicit chart type, a y-axis unit, and a series label — the additions are highlighted:

![A realtime line chart labeled Message Count Trend building a live trend as points arrive](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/realtime-chart-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=5b5353a0f8f39c764ece8f5bd1f10db2)

A fully configured realtime-chart trending the message count

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MessageCountTrend" WITH TYPE "realtime-chart"
    SET LABEL "Message Count Trend"
    SET CHART_TYPE "line"
    SET UNIT "msg"
    BIND VALUE TO TOPIC "kpi/operational/messageCount"
        SET SERIES_LABEL "Message Count"
```

> [!NOTE]
>
> **Multi-series is not working in the current HUB build.** Adding a second `BIND VALUE TO TOPIC` (each with its own indented `SET SERIES_LABEL`) is the documented syntax for multiple traces, but the chart currently renders a single trace and no legend. Use one chart per signal for now.

| Property | Type | Description |
| - | - | - |
| `CHART_TYPE` | `"line"` / `"bar"` | Trace style (the current build renders both as a line) |
| `UNIT` | String | Y-axis unit label |
| `LABEL` | String | Chart heading |
| `SERIES_LABEL` | String | Series name — set **under the BIND, indented** |

**Bind target:** `VALUE`

## Image

Static, dynamic, or camera-fed image.

**Basic**

A static image loaded from a URL:

![An image component on a dashboard panel rendering a remote picture](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/image-url.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=da5b8a9d7ff2ff782a718deb9de8303a)

An image component rendering a remote URL on the panel

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ProductPhoto" WITH TYPE "image"
    SET SRC "https://picsum.photos/320/240"
    SET WIDTH 320
    SET HEIGHT 240
```

**Full example**

A live feed whose source URL is published over MQTT — the `BIND SRC` line replaces the static source:

![An image component rendering a picture whose URL was published to a camera snapshot topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/image-topic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cd78420f09d93731dfb671f9a6e6f0e3)

The image swaps live whenever a new source is published to the snapshot topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "CameraFeed" WITH TYPE "image"
    BIND SRC TO TOPIC "camera/1/snapshot"
    SET WIDTH 320
    SET HEIGHT 240
```

| Property | Type | Description |
| - | - | - |
| `SRC` | String / ENV / URL | Image source path or URL |
| `FALLBACK` | String | Fallback image if source fails |
| `WIDTH`, `HEIGHT` | Integer | Dimensions in pixels |

**Bind targets:** `SRC`, `VISIBLE`

## Table

Tabular data from a JSON array topic or a query result.

**Basic**

Each array element becomes a row; `COLUMNS` picks and orders the fields:

![A table with time, barcode, product, and status columns showing recent scans](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/table.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=623c8fc914491f4a61a47c0e610b972e)

A four-column table populated from a JSON array topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ScanHistory" WITH TYPE "table"
    BIND DATA TO TOPIC "barcode/history"
    SET COLUMNS "time, barcode, product, status"
    SET MAX_ROWS 10
```

| Property | Type | Description |
| - | - | - |
| `COLUMNS` | String | Comma-separated column names |
| `MAX_ROWS` | Integer | Maximum rows to display |

**Bind targets:** `DATA`

## List

Scrollable list of items from a topic or model.

**Basic**

![A list widget showing alarm entries from the zone1 alarms topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/list.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=4995d6e427f28360e88a22108d9ba3b5)

A scrollable list of alarm entries from a topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "AlarmLog" WITH TYPE "list"
    BIND DATA TO TOPIC "zone1/alarms"
```

**Bind targets:** `DATA`

## Alert

Banner for critical messages — typically bound to an alarm flag.

**Basic**

The banner appears while the alarm flag is true and shows the live message:

![An alert banner showing a pump pressure critical message](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/alert.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=e7dcc7473dfdd5371642458dddfb02f6)

A banner that appears while the alarm flag is true and shows the live message

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "AlarmBanner" WITH TYPE "alert"
    BIND VISIBLE TO TOPIC "pump/alarm_active"
    BIND CONTENT TO TOPIC "pump/alarm_message"
    SET VARIANT "critical"
```

> [!NOTE]
>
> In the current HUB build the `critical` variant renders in a neutral/muted style rather than a strong red banner — the message and visibility behaviour work as shown.

| Property | Type | Description |
| - | - | - |
| `TYPE` / `VARIANT` | `"critical"` / `"warning"` / `"info"` | Severity style |

**Bind targets:** `CONTENT`, `VISIBLE`

## Common mistakes

> **A property set with WITH is silently ignored**
>
> Properties use `SET`, never `WITH`. `WITH UNIT "msg"`, `WITH RANGE 0, 200`, and `WITH DECIMALS 2` are silently ignored — write `SET UNIT "msg"`, `SET RANGE FROM 0 TO 200`, `SET DECIMALS 2`.

> **The value widget shows a JSON blob instead of a number**
>
> The topic carries a JSON object — add `SET JSON_PATH "$.field"` to extract the field you want, and confirm the payload shape in the Data Viewer.

## Next Steps

> **[Input & control components](/hub/dashboards/components/inputs)**
>
> Buttons, toggles, sliders, and fields that write back to the broker.

> **[Data binding](/latest/lot-language/panels/data-binding)**
>
> Topics, models, queries, transformations, and JSON extraction.


# Input & Control Components
Source: https://docs.coreflux.org/hub/dashboards/components/inputs

Buttons, toggles, sliders, and fields that write back to your broker.

![A two-column operator panel with Start and Emergency Stop buttons, an Enable Production toggle, a setpoint slider, and device name and pressure fields](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/inputs-overview.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=9507498bcc35f2564a2ced1d606e5b0d)

An operator panel built from the components on this page: buttons, a toggle, a slider, and entry fields

Input components let operators act: start a line, set a speed, type a value. One rule applies to all of them: **input components don't publish by themselves** — the `ON <EVENT> DO` handler does.

> [!TIP]
>
> **Like a steering wheel, not a speedometer.** Display widgets read signals; these widgets send them — every interaction ends in a publish back to the broker.

***

One section per control, each with its rendered result, the code, and then the property reference.

## Button

**Basic**

A button that publishes a command when clicked:

![A Start Production button on a dashboard](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/button.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cd6b3b083b4e42d4d4d0c42ce1976ef1)

A button that publishes a start command when clicked

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StartButton" WITH TYPE "button"
    SET LABEL "Start Production"
    ON CLICK DO
        PUBLISH TOPIC "factory/commands/start" WITH 1
```

**Full example**

A danger-styled emergency stop — the `STYLE` line is the new part:

![A red danger-styled Emergency Stop button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/button-danger.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cf98eec449ec0e9b9bdda516a671b4db)

A red danger-styled Emergency Stop button

```lot wrap focus={3} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StopButton" WITH TYPE "button"
    SET LABEL "Emergency Stop"
    SET STYLE "danger"
    ON CLICK DO
        PUBLISH TOPIC "factory/commands/stop" WITH 1
```

| Property | Type | Default | Description |
| - | - | - | - |
| `LABEL` | String | required | Button text |
| `STYLE` | `"primary"` / `"secondary"` / `"danger"` | `"primary"` | Visual style |
| `DISABLED` | Boolean | `false` | Disable button |
| `AWAIT` | Quoted component ids | — | Comma-separated ids that show a pending indicator until their next message. The button stays busy |
| `AWAIT_TIMEOUT` | Seconds | `120` | How long to wait before a timeout note |

`SET AWAIT "Briefing, StatusLamp"` keeps the button busy and marks those components pending until each one receives its next message. A full panel is in [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button).

**Events:** `ON CLICK DO`

## Toggle / Switch

Binary on/off control. `switch` is an alias for `toggle`.

**Basic**

The toggle reflects the bound topic live — publish `true` or `false` to it and the switch follows:

![An Enable Production toggle switched on](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/toggle.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=4c0f81d53f5c464097468abe793ed9c2)

A labeled toggle reflecting the live state of its bound topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "EnableSwitch" WITH TYPE "switch"
    SET LABEL "Enable Production"
    BIND STATE TO TOPIC "factory/production/enabled"
```

| Property | Type | Description |
| - | - | - |
| `LABEL` | String | Toggle label |

**Bind targets:** `STATE` — **Events:** `ON TOGGLE DO`

> [!WARNING]
>
> **Write-back is broken in the current HUB build.** `ON TOGGLE DO PUBLISH ... WITH STATE` fires, but the message payload is the literal text `{{STATE}}` instead of the toggle state (`WITH VALUE` behaves the same). Until this is fixed, use the toggle as a live state display and trigger commands from a [button](#button).

## Slider

Range input for numeric values.

**Basic**

The slider tracks its bound topic live — the thumb moves as new values arrive:

![A temperature setpoint slider set partway along its 0 to 200 degree range](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/slider-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=182df2e5cbb0cbbef6964d442f81ac6c)

A 0–200 °C setpoint slider tracking the live value of its bound topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "SetpointSlider" WITH TYPE "slider"
    SET RANGE FROM 0 TO 200
    SET UNIT "°C"
    BIND VALUE TO TOPIC "control/setpoint"
```

| Property | Type | Description |
| - | - | - |
| `RANGE FROM x TO y` | Numbers | Min / max |
| `UNIT` | String | Unit label |

**Bind targets:** `VALUE` — **Events:** `ON CHANGE DO`

> [!WARNING]
>
> **Write-back is broken in the current HUB build.** `ON CHANGE DO PUBLISH ... WITH VALUE` sends the literal text `{{VALUE}}` instead of the slider position, and dragging is overridden by the bound topic. Until this is fixed, use the slider as a live numeric display and set values from a [number field](#number-field).

## Text Field / Input

Free text entry.

**Basic**

A labeled field pre-filled from its topic; typing publishes the new value:

![A Device Name text field showing pump-station-1](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/text-field.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=c726cca5e1f6c4fce03fdfa93bc56cfb)

A labeled text field pre-filled with the current value from its topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "NameInput" WITH TYPE "text-field"
    SET LABEL "Device Name"
    SET PLACEHOLDER "Enter name..."
    BIND VALUE TO TOPIC "config/device/name"
    ON CHANGE DO
        PUBLISH TOPIC "config/device/name" WITH VALUE
```

| Property | Type | Description |
| - | - | - |
| `LABEL` | String | Field label |
| `PLACEHOLDER` | String | Placeholder text |

**Bind targets:** `VALUE` — **Events:** `ON CHANGE DO`

## Number Field

Numeric-only entry.

**Basic**

Accepts only numbers and publishes the limit on change:

![A numeric input field for a maximum pressure limit](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/number-field.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d1ed70b5baf478df5766d0fc7c7537f3)

A numeric field that accepts only numbers and publishes the limit on change

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MaxPressure" WITH TYPE "number-field"
    SET LABEL "Max Pressure (bar)"
    SET PLACEHOLDER "0.00"
    BIND VALUE TO TOPIC "config/pressure/max"
    ON CHANGE DO
        PUBLISH TOPIC "config/pressure/max" WITH VALUE
```

| Property | Type | Description |
| - | - | - |
| `LABEL` | String | Field label |
| `PLACEHOLDER` | String | Placeholder text |

**Bind targets:** `VALUE` — **Events:** `ON CHANGE DO`

## Common mistakes

> **I typed in a field but nothing was published**
>
> Text and number fields fire `ON CHANGE` when the value is **committed** — press Enter (or leave the field) after typing. Each keystroke alone does not publish.

> **The toggle flips back on its own**
>
> The toggle reflects its `BIND STATE` topic. If nothing updates that topic, the toggle snaps back to the last bound value — make sure something (device, Action, or a test publish) updates the bound state.

## Next Steps

> **[Actions & events](/latest/lot-language/panels/actions-events)**
>
> Everything a control can do: publish, navigate, invoke, trigger, and branch.

> **[Container components](/hub/dashboards/components/containers)**
>
> Group controls and readouts into cards and tabs.


# Dashboard Manager
Source: https://docs.coreflux.org/hub/dashboards/manager

Create, open, share, and manage dashboard panels in the Coreflux HUB.

![Animation showing dashboard widgets updating in real time as MQTT topic values change on the broker](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-live-update.gif?s=4cc30da855182c2b17ae960b90b4a980)

Live data updates flow into widgets as broker values change

## Opening the Dashboard Manager

The **Dashboard Manager** is an app inside the Coreflux HUB. It lists your **panels** (each panel is one dashboard you can open, share, or refine). From here you add panels, refresh the list, and open a panel to see it live.

![Coreflux HUB Dashboards window in Preview grid view with Panels 1, a live thumbnail card for Solar energy site · Energy twin with Public and Published badges and a timestamp, and the List view, Preview grid, Dashboards Builder, themes, create, and refresh controls](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/dashboard/manager/hub-dashboards-manager-grid-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=aef54227e6a3c8be9758849e570cfeb3)

Dashboard Manager in Preview grid view: each panel shows a live thumbnail with its name, visibility, state, and last update

## How Panels Are Defined

The Dashboard Manager and the AI Assistant both produce the same thing: a **LoT panel definition** (`DEFINE PANEL …`). The Manager shows that definition next to its live result so you can edit either by hand or by asking the assistant. The **LoT PANEL** reference documents every panel keyword, component, binding, and event.

> **[Dashboards in the HUB](/hub/dashboards/overview)**
>
> The widget tour, the 60-second first panel, and what dashboards can do.

> **[Defining a panel](/latest/lot-language/panels/defining-panels)**
>
> Read and write the `DEFINE PANEL` source behind every dashboard.

## How data updates on a Dashboard

Each component is tied to **live data** on your broker—typically a MQTT (Message Queuing Telemetry Transport — lightweight messaging for devices and applications) topic that already carries the signal from your machines, databases, or Connectors. When that topic’s value changes, the widget updates. You do not configure polling or manual refresh for normal operation.

![Coreflux HUB with the Dashboards window in the background and the Solar energy site · Energy twin panel open in a floating window showing a 3D site view with live labels and Site power cards for PV, Site load, Grid, Battery, and Fleet state of charge](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/dashboard/manager/hub-dashboards-panel-window-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=77e8d1a36d6ecb4db50def201f54106a)

A panel opened in its own window above the Dashboard Manager, with the dock still visible

## Viewing a Panel

You can experience the same panel in more than one layout depending on where you need it.

**As a window**

Open the panel as a **floating window** on top of the HUB. That keeps the rest of the HUB—connectors, Data Viewer, configuration—one click away while you watch live values or try layout changes.

![Coreflux HUB with the KPI Operational Dashboard expanded across the workspace, showing Status reading good, a Message Count trend line chart, and a Message Per Minute gauge reading 196](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-panel-window-tab.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=d873dc2aeabab536d9befb54a73c895a)

Panel as a floating window over the HUB — live widgets stay visible while you work elsewhere

**Full screen**

Open the panel in a **dedicated full view** when you want a clean surface for a plant display, a wall-mounted screen, or a link you share with people who only need the dashboard.

![Clean full-screen view of the KPI Operational Dashboard with no HUB chrome, showing Status reading good, a Message Count line chart, and a Message Per Minute gauge reading 174 on a dark background](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-panel-fullscreen.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=1a5638f3918fefa04c4b66f948a4962f)

Panel in full view — a clean surface for wall displays and shared links

## Managing Panels

The toggle in the Panels header switches between **List view** and **Preview grid**. The HUB remembers your choice; the list is the default. In the grid, each card shows a live thumbnail of the dashboard, and hovering it shows the same quick actions. Thumbnails don't run `ON MOUNT` actions, and cameras, microphones, video, web views, and barcode scanners show a placeholder.

Each row in the panel list shows the panel name, a visibility hint (for example **Public**), its publication state (for example **Published**), and when it was last updated. Clicking the row itself opens the panel; hovering reveals a row of quick actions on the right for sharing, inspecting, and deleting.

| Action | How to trigger it | What it does |
| - | - | - |
| **Open as a window** | Click the panel row | Opens the panel as a floating window on top of the HUB so you can keep working while it stays live |
| **Open as a link** | Click the first icon on the right (external link) | Opens the panel in a dedicated shareable view—useful for plant displays, wall screens, or sending a URL to a teammate |
| **View source** | Click the second icon on the right (code) | Shows the panel’s underlying definition so you can inspect or copy it |
| **Delete dashboard** | Click the last icon on the right (trash) | Removes the panel from the list after confirmation |

![Coreflux HUB Dashboards app showing the KPI Operational Dashboard row with Public and Published badges and three icons on the right for opening as a link, viewing source code, and deleting the dashboard](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-manager-actions.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=6fcf9d368243527c211a8c60ffa9ff91)

Panel row with quick actions — open as link, view source, and delete

## Sharing Panels on TVs and External Displays

You can put the same live panel on any screen that runs a browser—control-room wall TVs, lobby KPI boards, shop-floor tablets, or a monitor at a remote site—without installing a separate HMI app or giving everyone full access to the Coreflux HUB. The **shareable panel URL** opens a dedicated view of that dashboard so viewers see only the panel, not connectors, configuration, or other HUB apps.

From the **Dashboard Manager**, hover the panel row and click the **external link** icon (first action on the right). That opens the panel in a dedicated tab or window; copy the URL from the address bar and paste it into a browser on a TV stick, kiosk PC, tablet, or any display you want to keep on the loop.

> [!TIP]
>
> **Same live stream as inside the HUB.** The shareable URL reflects broker data the same way as the floating window—widgets update when topics change, without manual refresh for normal operation.

Typical uses:

* **Control-room and plant walls** — Full-screen dashboards that stay readable from a distance
* **Lobby and office KPI screens** — Management views without exposing operator tools
* **Shop-floor tablets** — Lightweight devices that only need one panel
* **Stakeholders and contractors** — A single URL when someone needs read-only visibility

![Coreflux HUB Dashboard Manager highlighting the external link action on a panel row to open a shareable dashboard URL](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-external-link.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=828c67a5b2cc460c3f9ef25244116ba3)

Open the panel as a shareable URL for TVs, kiosks, and external displays

> [!WARNING]
>
> Deleting a panel from the list removes that dashboard permanently after confirmation.

## Best Practices

> **Name panels by audience**
>
> Use names that tell you who it is for (for example “Line 3 — Shift Lead”) so the list stays scannable.

> **Start small**
>
> Ship a minimal panel with the three signals people ask for most, then add depth once it is in daily use.

> **Match symbols to reality**
>
> Use pumps, valves, and tanks where operators already think in those terms; use charts where trends matter more than mimic layout.

> **Verify before you share**
>
> Check labels, ranges, and safety-related controls before handing the panel URL to operators — they will rely on this screen.

***

## Next Steps

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Browse topics and payloads so you know what to bind each widget to.

> **[AI Assistant](/hub/ai-assistant)**
>
> Ask the assistant to suggest layouts, bindings, or improvements to a panel.


# Dashboards in the HUB
Source: https://docs.coreflux.org/hub/dashboards/overview

Live panels bound to your broker data — written in the Dashboard Manager or generated by the AI Assistant.

![Coreflux dashboard panel Solar energy site · Energy twin with a 3D site scene labelled with live values for grid, containers, factory load, and PV arrays, and Site power cards for PV, Site load, Grid, Battery, a Fleet state of charge gauge, and Peak import cap](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/dashboard/overview-hero-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=d66a730bd8466d29aa748fa31e47a610)

A published panel running maximized: a live 3D site view next to KPI cards and a gauge, all bound to broker topics

Dashboards in Coreflux are **panels**: live screens assembled from components — gauges, charts, controls — each wired to data flowing through your broker. You write them in the **Coreflux HUB** Dashboard Manager, where the panel definition and its live result sit side by side, or you ask the **AI Assistant** to build one for you and refine it from there.

> [!TIP]
>
> **Like a control room sketched in plain text.** You describe a gauge, point it at a signal, and it shows that signal live from the moment you save — no wiring diagram, no deploy step.

## What you can build

* **KPI walls** — large readouts and trends for supervisors
* **Line and area overviews** — at-a-glance status for a process or zone
* **Machine detail** — gauges, indicators, and controls for a single asset
* **Operator stations** — buttons, toggles, and setpoints where people work the process
* **Shift and mobile views** — simplified layouts for tablets and shared screens

***

Panels are authored as **LoT (Language of Things)** definitions — the syntax is documented under [LoT PANEL](/latest/lot-language/panels/defining-panels), which versions with your broker. The rest of this page is a quick tour of what the HUB renders; every widget has a full reference linked at the end.

## Your first panel in 60 seconds

**In the Dashboard Manager**

Open **Dashboards** in the HUB, click **Create new panel**, and write the definition below. The panel renders live as you save — point a gauge at a topic and the needle starts moving:

![The Sensor Monitor panel rendering a single radial gauge bound to the temperature topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/first-panel.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=48f432ea78be15567897c387e374eac7)

The saved panel: a live gauge reading 82.0 °C from the temperature topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL SensorMonitor
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Sensor Monitor"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
```

Every part of a definition is covered step by step in [Defining a Panel](/latest/lot-language/panels/defining-panels).

**Ask the AI Assistant**

Describe what you want in plain language:

> "Build me a panel with a radial temperature gauge on `sensor/temperature`, range 0–100 °C, with a warning threshold at 75."

The assistant creates the panel for you. Open it in the Dashboard Manager to see the definition it wrote — and adjust anything directly. See [AI Assistant](/hub/ai-assistant).

> [!NOTE]
>
> Include `WITH VISIBILITY PUBLIC` **and** `WITH STATE PUBLISHED` in every panel definition — panels saved without them may not appear in the Dashboard Manager list. See [Defining a Panel](/latest/lot-language/panels/defining-panels).

## Tour of the main widgets

A quick taste of each family — every widget has a full reference page.

### Readouts

**Gauge**

A value with context: range, unit, and thresholds.

![A radial temperature gauge reading 82.0 °C](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/gauge-threshold.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=b79957bdaedaf310c62a27d90117ddbb)

A radial gauge bound to the temperature topic, with a 75 °C warning threshold configured

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "TempGauge" WITH TYPE "gauge"
    SET RANGE FROM 0 TO 100
    SET UNIT "°C"
    BIND VALUE TO TOPIC "sensor/temperature"
```

**Value**

The big number — unit, decimals, wall-readable.

![A numeric readout labeled Error Rate showing 1.25 percent](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/value-error-rate.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=06d34f7c733788d3397485f270a01bb9)

A formatted error-rate readout with two decimals

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ErrorRate" WITH TYPE "value"
    SET LABEL "Error Rate"
    SET UNIT "%"
    SET DECIMALS 2
    BIND VALUE TO TOPIC "kpi/operational/errorRate"
```

**Indicator**

State at a glance — values mapped to colors.

![A green machine status indicator dot for the running state](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/indicator-status.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=9553919702a348c0ae388c8b11f18c0f)

A status dot that turns green for running and red for stopped

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MachineStatus" WITH TYPE "indicator"
    BIND STATE TO TOPIC "machine/status"
    SET ON_VALUE "running" WITH COLOR "green"
    SET ON_VALUE "stopped" WITH COLOR "red"
```

**Alert**

A banner that appears when a condition is true.

![An alert banner showing a pump pressure critical message](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/alert.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=e7dcc7473dfdd5371642458dddfb02f6)

An alert banner showing the live alarm message while the alarm flag is true

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "AlarmBanner" WITH TYPE "alert"
    BIND VISIBLE TO TOPIC "pump/alarm_active"
    BIND CONTENT TO TOPIC "pump/alarm_message"
    SET VARIANT "critical"
```

### Charts and tables

**Real-time trend**

Builds a live trend from individual data points on a topic.

![A realtime line chart trending as message count points arrive](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/realtime-chart-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=5b5353a0f8f39c764ece8f5bd1f10db2)

A realtime-chart building a line from values as they arrive

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MessageCountTrend" WITH TYPE "realtime-chart"
    SET LABEL "Message Count Trend"
    SET CHART_TYPE "line"
    SET UNIT "msg"
    BIND VALUE TO TOPIC "kpi/operational/messageCount"
        SET SERIES_LABEL "Message Count"
```

**Table**

Rows from a JSON array topic or query result.

![A table with time, barcode, product, and status columns showing recent scans](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/table.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=623c8fc914491f4a61a47c0e610b972e)

A table populated from a JSON array topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ScanHistory" WITH TYPE "table"
    BIND DATA TO TOPIC "barcode/history"
    SET COLUMNS "time, barcode, product, status"
```

### Controls

**Toggle**

On/off switch that tracks the live state of its bound topic.

![A pump enable toggle switched on](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/toggle-pump.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=7e5aa0ef6d5fa569af39fbca00c45118)

A pump-enable toggle reflecting the live pump state

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "PumpControl" WITH TYPE "toggle"
    SET LABEL "Pump Enable"
    BIND STATE TO TOPIC "zone1/pump/state"
```

**Button**

Click to act — publish a command to any topic, or navigate to another panel.

![A Start Production button on a dashboard](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/button.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cd6b3b083b4e42d4d4d0c42ce1976ef1)

A button that publishes a start command when clicked

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StartButton" WITH TYPE "button"
    SET LABEL "Start Production"
    ON CLICK DO
        PUBLISH TOPIC "factory/commands/start" WITH 1
```

**Slider**

Numeric value tracked live on a range.

![A conveyor speed slider set to 65 percent](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/slider-speed.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d28f7e799225dc20c6812dfa4b9b5ead)

A 0–100 % speed slider tracking the live conveyor speed

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "SpeedSlider" WITH TYPE "slider"
    SET RANGE FROM 0 TO 100
    SET UNIT "%"
    BIND VALUE TO TOPIC "zone1/conveyor/speed"
```

## What dashboards can do

* **Live bindings** — bind to MQTT topics, LoT Model fields, or database queries; widgets update the moment values change. See [Data Binding](/latest/lot-language/panels/data-binding).
* **Interactive controls** — buttons and entry fields that publish commands, invoke Actions, and trigger Connectors. See [Actions & Events](/latest/lot-language/panels/actions-events).
* **Multi-page navigation** — buttons and cards that jump between panels with `NAVIGATE`, for overview-to-detail drill-downs. See [Defining a Panel](/latest/lot-language/panels/defining-panels#navigation).
* **Share on any screen** — a panel URL runs full-screen on wall TVs, tablets, and kiosks, no app install. See [Dashboards in the HUB](/hub/dashboards/overview).

## Next Steps

> **[Build your first dashboard](/latest/quick-start/building-dashboards)**
>
> A 10-minute guided walk from topic to published panel.

> **[Component reference](/hub/dashboards/components/display)**
>
> Every widget, every property, every bind target.


# Common Patterns
Source: https://docs.coreflux.org/hub/dashboards/patterns

Ready-to-adapt panel recipes for the most frequent dashboard jobs.

![A KPI dashboard with a Message Count gauge, a rising Message Count Trend line chart, and an Error Rate readout](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/overview-hero.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=269c34293a365f1c597cbcd399f12cb8)

The Live KPI dashboard recipe from this page, running with live data

Each recipe is a complete, working panel. Copy it, swap the topics for yours, and adjust ranges and labels.

> [!TIP]
>
> **Like starter dough.** Each recipe already works as-is — you don't build from scratch, you season: your topics, your ranges, your labels.

***

Five recipes, ordered from the smallest useful panel to data-layer integrations.

## Minimal monitoring panel

**Goal:** one signal, one status — the smallest useful dashboard.

![A dashboard with a temperature gauge reading 82 °C and a green running status indicator](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/patterns/minimal-monitoring.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=5b513f764cd48a4f2b056f1424912b00)

Two-column panel: a temperature gauge on the left, a running status indicator on the right

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL SensorMonitor
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Sensor Monitor"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        AT COLUMN 1 ROW 1
        SET RANGE FROM 0 TO 150
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
        ADD THRESHOLD AT 100 WITH COLOR "warning"
        ADD THRESHOLD AT 130 WITH COLOR "critical"

    ADD COMPONENT "StatusIndicator" WITH TYPE "indicator"
        AT COLUMN 2 ROW 1
        BIND STATE TO TOPIC "machine/status"
        SET ON_VALUE "running" WITH COLOR "green"
        SET ON_VALUE "stopped" WITH COLOR "red"
        SET SIZE "large"
```

**Adapt:** your topic names, the gauge range, the threshold levels.

## Live KPI dashboard

**Goal:** a wall screen with a headline number, its trend, and a secondary KPI.

![A KPI dashboard with a Message Count gauge at 135 msg, a rising Message Count Trend line chart, and an Error Rate readout of 1.25 percent](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/patterns/live-kpi-dashboard.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=69894d551b403fd7d46c5e3b612ac7af)

Three-column KPI wall: a message-count gauge, its live trend, and the error-rate readout

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL KpiDashboard
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Operational KPI Dashboard"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "MessageCountGauge" WITH TYPE "gauge"
        SET LABEL "Message Count"
        SET RANGE FROM 0 TO 200
        SET UNIT "msg"
        BIND VALUE TO TOPIC "kpi/operational/messageCount"

    ADD COMPONENT "MessageCountTrend" WITH TYPE "realtime-chart"
        SET LABEL "Message Count Trend"
        SET CHART_TYPE "line"
        SET UNIT "msg"
        BIND VALUE TO TOPIC "kpi/operational/messageCount"
            SET SERIES_LABEL "Message Count"

    ADD COMPONENT "ErrorRate" WITH TYPE "value"
        SET LABEL "Error Rate"
        SET UNIT "%"
        SET DECIMALS 2
        BIND VALUE TO TOPIC "kpi/operational/errorRate"
```

**Adapt:** share it on a TV via the panel URL — see [Dashboards in the HUB](/hub/dashboards/overview).

## Control panel

**Goal:** drive the line from the dashboard — buttons publish commands, a number field sets the speed, and a slider tracks the live feedback.

![A two-column operator panel with Start and Stop Conveyor buttons, a speed setpoint number field, and a conveyor speed slider](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/patterns/control-panel.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=7bf104e56761bbaae30067a2eab551dc)

Operator panel with start/stop buttons, a speed setpoint field, and a live conveyor speed slider

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Zone1Control
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Zone 1 Control"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "StartButton" WITH TYPE "button"
        AT COLUMN 1 ROW 1
        SET LABEL "Start Conveyor"
        ON CLICK DO
            PUBLISH TOPIC "zone1/conveyor/cmd/start" WITH 1

    ADD COMPONENT "StopButton" WITH TYPE "button"
        AT COLUMN 2 ROW 1
        SET LABEL "Stop Conveyor"
        SET STYLE "danger"
        ON CLICK DO
            PUBLISH TOPIC "zone1/conveyor/cmd/stop" WITH 1

    ADD COMPONENT "SpeedSetpoint" WITH TYPE "number-field"
        AT COLUMN 1 ROW 2
        SET LABEL "Speed Setpoint (%)"
        SET PLACEHOLDER "0"
        ON CHANGE DO
            PUBLISH TOPIC "zone1/conveyor/cmd/speed" WITH VALUE

    ADD COMPONENT "LiveSpeed" WITH TYPE "slider"
        AT COLUMN 2 ROW 2
        SET RANGE FROM 0 TO 100
        SET UNIT "%"
        BIND VALUE TO TOPIC "zone1/conveyor/speed"
```

**Adapt:** the command topics (`cmd/...`) and the feedback topic (`speed`) — keeping them separate means the slider reflects what the line is actually doing, not just the last setpoint sent.

## Panel backed by a LoT Model

**Goal:** when a [Model](/latest/lot-language/models/overview) already aggregates your data layer, bind to its fields instead of raw topics.

> [!WARNING]
>
> **Known issue (current HUB build).** `BIND … TO MODEL` bindings do not receive data yet, and `SET MODEL … WITH VALUE` write-back from panel handlers does not update model fields — so this recipe cannot be shown rendering live values and the setpoint field cannot write back. The syntax below follows the spec; in the meantime, bind widgets to the model's source topics (or its output topic with `JSON_PATH`) and publish setpoints to those topics directly.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL PumpDashboard
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Pump System"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "FlowGauge" WITH TYPE "gauge"
        BIND VALUE TO MODEL "PumpSystem.flow_rate"
        SET UNIT "L/min"
        SET RANGE FROM 0 TO 500

    ADD COMPONENT "PressureDisplay" WITH TYPE "value"
        BIND VALUE TO MODEL "PumpSystem.pressure"
        SET UNIT "bar"
        SET DECIMALS 2

    ADD COMPONENT "PumpStatus" WITH TYPE "indicator"
        BIND STATE TO MODEL "PumpSystem.running"
        SET ON_VALUE "true" WITH COLOR "success"
        SET ON_VALUE "false" WITH COLOR "muted"
        SET SIZE "large"

    ADD COMPONENT "FlowSetpoint" WITH TYPE "number-field"
        SET LABEL "Flow Setpoint (L/min)"
        SET PLACEHOLDER "0"
        BIND VALUE TO MODEL "PumpSystem.setpoint"
```

## Next Steps

> **[Build your first dashboard](/latest/quick-start/building-dashboards)**
>
> Walk through one of these panels end to end with live data.

> **[Dashboards in the HUB](/hub/dashboards/overview)**
>
> Publish, share, and put any of these on a wall screen.


# LoT Editor
Source: https://docs.coreflux.org/hub/lot-editor

Author, deploy, and inspect LoT and Python as notebooks and projects in the Coreflux HUB

![Coreflux HUB LoT Editor showing digital-twin-energy-site badged LIVE with energy-site.lotnb, a markdown cell titled Solar energy site · Modbus TCP + BACnet/IP, a DEFINE ROUTE TwinEnergyModbusU1 cell badged DEPLOYED, BROKER RUNTIME with type counts, CONFIGURATION, LIBRARY, a Deployed chip, main branch, and Deploy All](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=99cf12e43faa20ef201525799789f24a)

The LoT Editor with the live project's notebook open: a markdown introduction above deployed connector cells, Projects lists the project badged LIVE, Broker runtime shows its entities, and the header shows Deployed plus Deploy All

## Why Use the LoT Editor?

The LoT Editor brings the **LoT Notebooks** experience from VS Code into the Coreflux HUB. You author LoT and Python in notebook cells, deploy any cell on its own, and see per-cell whether your copy matches what the broker is running — with the broker's live entity list right beside your code, without leaving the browser.

This makes the HUB a single place to develop, manage, and operate your Coreflux solutions.

> [!NOTE]
>
> **This is parity, not a replacement.** Editing LoT from the [VS Code LoT Notebooks extension](/lot-notebooks/usage) remains fully supported, and you never have to choose between the two. The broker is the source of truth: either editor deploys to it, and both read the same project. `Import .lotnb`, `Push to broker`, and `Pull from broker` are what keep the two workflows one.

> [!TIP]
>
> **Like a lab notebook wired to the machine it describes.** The prose, tables, and code live in one document — and each block of code is the thing that is actually running.

## When to Use It

* **Deploying LoT without another tool installed** — Any HUB install, Docker or desktop app, can author and deploy
* **Checking what is really on the broker** — **Broker runtime** is the authoritative list, next to your code
* **Iterating on one definition** — Run a single cell instead of redeploying a whole project
* **Auditing drift** — Per-cell badges and a broker diff show exactly which definitions have moved out of sync
* **Documenting a solution where it lives** — Markdown cells render inline, so the topic conventions and device maps sit beside the code that implements them
* **Putting live visuals next to the LoT that drives them** — Drag Library components into a markdown cell and watch topics such as `demo/sensor/value` update in the notebook
* **Picking up someone else's project** — Open it from the broker and read the notebook top to bottom
* **Publishing or recovering a project** — Push a local draft, Pull or Inspect one already on the broker, or restore an earlier commit
* **Removing without surprises** — A local delete, an entity remove, and a project remove from the broker are three different operations

***

## Opening the Editor

Select **LoT Editor** in the HUB dock — the notebook-and-pen icon, after **Data Viewer** and **Connections**. An orange dot under the icon marks the editor as the active app.

![Animated walkthrough of clicking the LoT Editor icon in the Coreflux HUB dock to open the editor](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-open.gif?s=db008f31858c416cad334d6e604c5daf)

Opening LoT Editor from the HUB dock: the notebook-and-pen icon is fourth from the left, and the editor opens above the dock

The window header carries the current project and notebook plus the controls that act on the whole notebook:

![Coreflux HUB LoT Editor window above the dock, a template project's notebook.lotnb in the breadcrumb, 12 not running chip, orange Deploy All, Projects listing the project as local, Library Components 28, LoT Editor dock icon active](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-opening.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=cc046a052474a3e221d3b07ddd1a867d)

LoT Editor open on a template project with the dock still visible: breadcrumb project › notebook.lotnb, 12 not running, Deploy All, and the notebook-and-pen dock icon lit with an orange dot

| Control | What it does |
| - | - |
| **Breadcrumb** (`project › notebook.lotnb`) | The open project and file. Click either part to rename it |
| **`Deployed`** | Every comparable cell in the open project matches the broker. Drift shows as an orange count such as `N differs` or `N not running` — on a live project, click it to Push |
| **Branch chip** (`main`) | Git branch of the open project on the broker. Missing git is silence — there is no `Local workspace` chip |
| **`Deploy All`** | Deploys every LoT and Python cell in the **open notebook**. The split control also offers **Deploy project**, which stores and loads the whole project |
| **Action Console** (pulse) | Opens the right-hand **Action Console** rail for running and tracing Actions — see [Action Console](#action-console-traces-and-run-once) |
| **Remove entities** | Removes the entities *this notebook* defines from the broker |
| **Undo** / **Redo** | Step cell changes back and forward |
| **Attach notebook to AI chat** | Hands the open notebook to the HUB's AI assistant as context |
| **`…`** | `Import .lotnb file` and `Export open notebook as .lotnb` |

## A Notebook Is Both Document and Deployment

A notebook is an ordered list of cells, and the cell type dropdown decides what each one is:

| Cell type | Contents | Deployed? |
| - | - | - |
| **LoT** | One complete definition — `DEFINE ACTION`, `DEFINE MODEL`, `DEFINE CONNECTOR`, `DEFINE RULE` | Yes, to the broker |
| **Python** | A Python script your Actions call, named in the cell's **Script name** field | Yes, to the broker |
| **Markdown** | Headings, prose, lists, tables, **live visual components**, and links to project documents | Visuals are published as panels; prose is documentation |

Markdown cells render in place between the executable ones. That is not documentation-only: you can drop a gauge, chart, or card from **Library → Components** into a markdown cell and it stays live, bound to MQTT. A project installed from a template can use this for a **live document preview** — widgets on a topic such as `demo/sensor/value` sit in the notebook itself, so you deploy the cells above and watch the gauge, status, and trend update without leaving the editor.

> [!NOTE]
>
> **Adding visuals in the editor is a first-class authoring step**, not a Dashboards-only feature. Drag from Library, or write the component in the markdown cell — the notebook is allowed to *be* the live view. See [Library](#library-visual-components-and-documents).

To add a cell, use the **`+ Code`** and **`+ Markdown`** buttons that appear in the gutter between cells — so a new cell always lands exactly where you point at it.

## Working With Cells

Every cell has its own toolbar, left to right. Hover the cell to reveal the right-hand controls — **Move up** / **Move down**, **Duplicate**, and **Delete** stay hidden until then.

![Coreflux HUB LoT Editor TwinEnergyProjectKpi cell hovered with the DEPLOYED badge and toolbar controls, DEFINE ACTION TwinEnergyProjectKpi ON EVERY 1 SECOND reading energy-site topics, and the strip TwinEnergyProjectKpi Not yet run with Open in Action Console](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-cell-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=b484791c5871dd84fb153a09bb321933)

TwinEnergyProjectKpi hovered and deployed: drag handle, Run cell, LoT, DEPLOYED, then Run or trace, Move up, Move down, Duplicate, and Delete, with the run strip below

| Control | What it does |
| - | - |
| **Drag handle** | Drag to reorder the cell |
| **Run cell** (`Shift`+`Enter`) | Deploys just this cell to the broker |
| **Cell type** | Switch between `LoT`, `Python`, and `Markdown` |
| **Sync badge** | This cell's state against the broker — see below |
| **Enabled** switch (one ACTION, CONNECTOR, or AGENT per cell) | Turns the entity off or on without removing it — see [Disable an entity](#disable-an-entity) |
| **Run or trace** (pulse, Action cells only) | Pin this Action in the [Action Console](#action-console-traces-and-run-once). While a capture is armed it reads as tracing |
| **Compare with broker** | Shown when the cell is not `DEPLOYED` — see [Comparing a cell with the broker](#comparing-a-cell-with-the-broker). Appears on hover |
| **Move up** / **Move down** | Reorder without dragging. Appear on hover |
| **Duplicate** | Copy the cell and its contents. Appears on hover |
| **Delete cell** | Remove the cell from the notebook. Appears on hover |

Action cells also carry a strip under the code. Here it reads **`SummarizeF2Hvac · Not yet run · Tracing`** — expand it for Traces and Run, or choose **Open in Action Console** to pin the same panel in the right-hand rail. **Tracing** (green) means a five-minute capture is already armed for that Action.

Deleting a cell asks **"Delete this cell?"** and warns that the cell and its contents are removed from the notebook and that it cannot be undone. It changes the notebook only — the entity that cell deployed stays on the broker until you remove it there. See [Removal](#removal-four-different-operations).

### Disable an entity

A cell that holds exactly one action, connector, or agent has an **Enabled** switch in its toolbar. Switch it off to write `DISABLE true` on the line after `DEFINE`. Switch it on to remove that line. The broker keeps a disabled entity defined and listed, but doesn't run it.

![Coreflux HUB LoT Editor with the acme-bottling project open on its Plant actions section: the Heartbeat cell, publishing acme/plant/heartbeat every 5 seconds, with its Enabled switch on, and the AlarmRelay cell with its switch off labelled Disabled, the line DISABLE true under DEFINE ACTION AlarmRelay, and the result Action AlarmRelay added successfully (disabled)](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-cell-enabled-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=a739ffa917c06f8dbde8a943695ef557)

Two Action cells: Heartbeat with the Enabled switch on, and AlarmRelay switched off, which writes DISABLE true into its code

* With a broker connected, the cell is redeployed right away, so the notebook and the broker stay in step.
* Offline, the change stays in the cell and goes out with the next deploy.
* Models, rules, and cells with several entities have no switch.
* On a broker that doesn't support `DISABLE`, the switch is locked and its tooltip says **Requires a broker with DISABLE support**.

See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable) for the matching broker commands.

## Action Console: Traces and Run Once

**Run cell** deploys the definition. The console underneath — or pinned from the header pulse — is where you watch and trigger execution: **Traces** records every run for five minutes, and **Run once** fires the Action with a topic and payload you choose.

Every Action cell has the same console in two places — expanded under the cell, or pinned in the header pulse rail. Both have **Traces** and **Run**.

![Coreflux HUB LoT Editor SampleProcessor console on the Traces tab showing no messages yet, timeline playback controls, and copy that traces record every execution for five minutes](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-action-console.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=027470dfafc40dda6eba53940e30548e)

SampleProcessor Traces tab before a capture: timeline chrome and the note that traces last five minutes while a single run lives on the Run tab

| Control | What it does |
| - | - |
| **Traces** tab | A five-minute capture of every execution, including runs triggered elsewhere. Playback sits on the timeline; a single run's result stays on **Run** |
| **Run** tab | Topic and payload (or JSON parameters for callable Actions), then **Run once** |
| **`Use`** | Fill the payload from the last message on that topic, or from the last run |
| **Run once** | Live run — (re)deploys the version in the cell, then executes it. There is no sandbox: anything the Action publishes is published |
| **Open in Action Console** | Pin this Action in the right-hand rail so you can switch Actions without leaving the strip |

![Coreflux HUB LoT Editor SampleProcessor console on the Run tab with topic demo/sensor/value, payload 60, Use dropdown, and Run once play button](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-run-once.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=4ca68d1b354953da18067f01396c08a9)

SampleProcessor Run tab: topic demo/sensor/value, payload 60, Use menu, and the orange Run once control

> [!WARNING]
>
> **Run once is a live run.** It (re)deploys the Action from the cell and executes it on the broker. Downstream topics, databases, and devices see the same publishes they would from a real trigger.

## Is This Cell Running on the Broker?

Each LoT and Python cell reports its own state against the broker, which is the fastest way to tell whether the code you are reading is the code that is running:

| Badge | Meaning | What to do |
| - | - | - |
| **`DEPLOYED`** | The cell matches an entity running on the broker | Nothing |
| **`DIFFERS`** | The entity is running but the source here has changed | Run the cell to update it |
| **`NOT RUNNING`** | Nothing of that name is running on the broker yet | Run the cell to deploy it |
| **`RUNNING`** | Something is running that this project does not declare | Adopt it, or remove it from Broker runtime |

![Coreflux HUB LoT Editor showing notebook cells badged NOT RUNNING with Compare with broker controls, and a header chip reading a not-running count](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-cell-states.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=089fde4d4225dc42e24d8c7ca069c82a)

Cells that are not on the live project are badged NOT RUNNING — the header chip counts them, and Compare with broker is available on each toolbar

> [!NOTE]
>
> `NOT RUNNING` and `DIFFERS` are how the editor answers "why is my Action missing from [LoT Flow](/hub/lot-flow)?" — the graph is drawn from Broker runtime, so a cell that has never been deployed has nothing to draw.

### Comparing a cell with the broker

Whenever a cell is not `DEPLOYED`, a **Compare with broker (Diff)** control appears on its toolbar. It replaces the editor with a line-by-line comparison of the running definition against your local copy, headed `BROKER · <entity> ⟷ LOCAL` with an added/removed line count:

![Coreflux HUB LoT Editor showing SampleMqttBridge in diff mode, header BROKER · SampleMqttBridge vs LOCAL, CLIENT\_ID changed from bridge-client to bridge, PROJECTS Sample LIVE, orange 1 differs chip and main branch](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-cell-diff.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=3de709341eaca5dfc8b572f533da8eb0)

A cell in diff mode with the header 1 differs: BROKER · SampleMqttBridge ⟷ LOCAL, the removed CLIENT\_ID bridge-client in red and the local CLIENT\_ID bridge in green

For a `NOT RUNNING` cell the comparison is against nothing — every line shows as an addition, which is a quick way to review a whole definition before it goes live.

## Deploying

Two granularities, and the difference matters when a project is large:

* **Run cell** deploys that one definition. Use it while iterating — you get the broker's response for that entity alone.
* **Deploy All** deploys every LoT and Python cell in the **open notebook**. Use it while iterating.
* **Deploy project** (the other half of the split button) stores the whole project and loads it, replacing the broker's entity set. It always confirms first.

Either way the cell's badge flips to `DEPLOYED` once the broker confirms it, and the entity appears under **Broker runtime**.

Here is a complete Model as it appears in a cell — the fields the Action fills in are the ones worth reading first:

```lot wrap focus={2-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SampleTableRow COLLAPSED
    ADD DOUBLE "value"
    ADD STRING "status"
    ADD STRING "timestamp"
```

> [!WARNING]
>
> Running a cell writes to the broker immediately. There is no staging step and no separate save — the definition in the cell replaces whatever the broker was running under that name.

***

## Start from a template

A new project starts with an empty `notebook.lotnb`. Worked examples come from **LoT Templates**, which browses the library at [templates.coreflux.org](https://templates.coreflux.org). The built-in Sample notebook is not part of the HUB.

Open **LoT Templates** from **Help → LoT Templates**, or choose **From a template…** in the new-project dialog that `＋ New` opens.

Each template has three tabs:

| Tab | What you see |
| - | - |
| **Overview** | What the template is for |
| **Notebook** | The notebook cells, read-only |
| **Flow** | How the LoT in the template fits together |

Installing a template creates a LoT Editor project on this HUB. It does not deploy to the broker. Change the example values, then deploy the cells the same way you deploy any notebook.

## Clone from git

**＋ New → From git…** copies a public git repository into a new LoT Editor project. The clone copies files only. It does not load the project, and it does not deploy any cell. Open the notebook and run the cells you want on the broker.

| Limit | What it means |
| - | - |
| Public repositories | The HUB does not accept private credentials |
| 30 seconds | The git clone stops if it has not finished |
| Whole repository | The repository root becomes the project root |
| 64 MB | A project download larger than 64 MB is refused |

***

## The Sidebar: Projects and Broker Runtime

There is **one Projects list**, and **Broker runtime** sits under it as its own section — always present, even when nothing is running.

![Coreflux HUB LoT Editor sidebar with PROJECTS listing a template project LIVE, notebook.lotnb, Entities 12, and its models; BROKER RUNTIME listing that project with type counts; CONFIGURATION Variables Secrets Internal Rules 35; LIBRARY Components 28 Resources 0; header Deployed and main](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-sidebar.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6a109a8c2d3c7e1c37fcce28f40c5e2a)

The LoT Editor sidebar: PROJECTS lists a template project badged LIVE with notebook.lotnb and Entities 12, BROKER RUNTIME shows that project with Actions, Models, Rules, Connectors, Python, Themes, and Panels, then CONFIGURATION and LIBRARY

| Section | What it holds |
| - | - |
| **Projects** | Every project you can open — on the broker, local-only drafts, and the one currently **LIVE**. `＋ New` creates a draft with an empty `notebook.lotnb`. **From a template…** opens [LoT Templates](#start-from-a-template). **From git…** clones a public repository ([Clone from git](#clone-from-git)). Hover a name for placement (`On broker · live`, `On broker · idle`, `Local draft`). The row plug is **Activate** or **Deactivate** |
| **Broker runtime** | What is actually running. The group reads **`Project: {name}`** for the live project, or **`Standalone`** when none is. Click the name to open the inspector table |
| **Configuration** | `Variables`, `Secrets`, and `Internal Rules` — the broker's locked built-in permission rules |
| **Library** | Visual components, documents, and images — see [Library](#library-visual-components-and-documents) |

Editing a notebook changes your local copy. Only deploying, Push, Activate, or Deploy project writes to the broker. A colleague on another machine sees the same Broker runtime and the same on-broker projects, not your unpublished local edits — which is why you Push and Pull.

### Broker runtime

Expanding **Broker runtime** groups everything running by type — `Actions`, `Models`, `Rules`, `Connectors`, `Agents`, `Things`, `Python`, `Themes`, `Panels` — each with a count and names beneath. Click **`Project: {name}`** or **Standalone** to open the inspector:

![Coreflux HUB Broker runtime inspector with All 37, Actions 19, Models 9, Rules 0, Routes 9, Python 0, Themes 0, and Panels 0 filters, Filter by name, and a table of running TwinEnergy actions and models, each in project digital-twin-energy-site and notebook energy-site.lotnb](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-broker-runtime-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=b5a941979edc02d71c8aed9a27dc9a4f)

Broker runtime inspector: type filters and a table of STATUS, TYPE, NAME, PROJECT, and NOTEBOOK for every entity running on the broker

The inspector is where mixed ownership is obvious: rows that belong to the open project point at `notebook.lotnb`; a connector you added on its own, outside any project, leaves **Project** and **Notebook** blank. Select a row to read the running source and use **Open notebook**, **Copy to project**, or **Remove**.

A project's own **Entities** folder (under the project in **Projects**) is what that project's notebooks *declare*. Broker runtime is what is *running*. Those counts can disagree — **Connectors (1)** under the project versus **Connectors (2)** on the broker — because a connector added from Connectors Manager is running but not declared in the notebook.

An agent (`DEFINE AGENT`) is its own entity. The editor deploys that cell with `-addAgent` and removes it with `-removeAgent`. It does not appear as a connector. The LLM connector it uses does. See [AI Assistant](/hub/ai-assistant) and [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

### Things in the editor

A cell with `DEFINE THING` blocks deploys as one Thing payload. The broker expands it; the HUB never does. See [LoT THING](/latest/lot-language/things/overview).

* **Run cell** first checks the cell with `-addThing --dryRun`, together with every template it references in the workspace. Problems show as markers in the code. If they pass, the same payload is applied. `-addThing` updates in place, so a Thing is never removed first.
* When you change a template that other Things use, the editor asks **Also redeploy N other Things?** before it applies.
* **Broker runtime → Things** lists each root Thing, its instances, and the entities they own. Owned entities are read-only and leave the per-type folders. The inspector table includes Things. A **Templates** subfolder shows which Things use each template. The project's **Entities** folder has a **Things** group too.
* On a broker without THING support, THING cells show a red chip, **Requires a broker with THING support**, and don't deploy.
* A THING cell in the older syntax offers an update. It previews the changes (`TEMPLATE`, and `{p}` to `{{p}}`) and applies them only when you confirm.

**Flow preview** in the editor toolbar opens a **Flow** pane with the [Things view](/hub/lot-flow#things-tree-and-flat-views) of the open notebook, from the same dry run. Click an entity to bring the cell that owns it into view.

![Coreflux HUB LoT Editor on the acme-bottling notebook. Under Broker runtime, the Things folder lists Acme with 16 entities and its line1 and line2 BottlingLine instances, Utilities with 4, and Templates with 3. The notebook shows the cell with DEFINE THING Acme and DEFINE THING Utilities, and the read-only Flow preview pane, built from the broker's dry run, shows All Things with 2 root Things: MQTT clients feeding the Acme and Utilities cards, and the Acme alarms going to Not in a Thing](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-things-flow-preview-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=8ece8ec2230b2c9213e0906dcf63b9ac)

Broker runtime → Things with the Acme root expanded, and the Flow pane previewing the open notebook's Things

An idle project's declarations can match the running set and still read `NOT RUNNING` on cells — Activate that project before treating those badges as a deploy to-do.

> [!NOTE]
>
> **Connectors and Python scripts deploy from the editor too.** Connectors still have their own [Connectors Manager](/hub/routes/overview) for connection status and templates.

Two counts are easy to misread:

* **`Rules`** under a project counts rules that project owns. Locked built-ins live under **Configuration → Internal Rules**, not here.
* **`Python`** counts *scripts*. [LoT Flow](/hub/lot-flow)'s Python group counts the individual *functions* those scripts expose.

## Library: Visual Components and Documents

**Library** is the bottom of the LoT Editor sidebar. It is how you put *views* and *files* into a project — not a second editor.

![Coreflux HUB LoT Editor sidebar scrolled to the Library with Components expanded, listing Gauge, Indicator, Value, Text, Header, Card, Container, Chart, Realtime Chart, Table, List, Button, Switch, Toggle, Slider, Input, Text Field, Number Field, Select, Date Picker, Map, Markers, Trace, SVG, Image, Video, Camera, Audio, Barcode, Web View, and Twin Controls with group labels, and Resources below](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-library-full-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=f4bd7a802f93c7ad6d703b80687c24dc)

Library open with Components expanded: visual component types listed with their group (display, data viz, input, maps and graphics, media, digital twin), then Resources

### Components

**Components** is the palette of live widgets you can drop onto a **markdown** cell. Each row is a type (Gauge, Chart, Button, Map, …) with its group on the right. Drag a row onto a markdown cell to embed a viewer bound to an MQTT topic. A template project's live preview is this capability in use: a card of gauge, status, and trend sitting in the document.

![Coreflux HUB LoT Editor markdown cell titled Live document preview with a Sensor overview card showing a gauge at 65.0, status normal, and a live trend chart](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-live-preview.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=f56fd16e7097462257c1bcddb944c846)

Live document preview in a template project: Sensor overview card with a gauge at 65.0, status normal, and a live trend on demo/sensor/value

Types you can drop today, by group:

| Group | Components |
| - | - |
| **Display** | Gauge, Indicator, Value, Text, Header |
| **Containers** | Card, Frame |
| **Data viz** | Chart, Realtime Chart, Table, List |
| **Input** | Button, Switch, Toggle, Slider, Input, Text Field, Number Field, Select, Date Picker |
| **Geo / spatial** | Map, Markers, Trace |
| **Media / graphics** | SVG, Image, Video, Camera, Audio, Barcode |

Widgets in the notebook publish as panels when the document is saved, so they are the same component types Dashboards uses — authored next to the LoT that feeds them.

### Resources: documents and images

**Resources** nests **Documents** and **Images**. These are files in the project, not a separate scrapbook you have to remember to Push.

![Coreflux HUB LoT Editor Library Resources with Documents expanded to site-notes.md and Add file, Images collapsed with count 1](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-library.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=a48e3215b3a464fdf2d32b28d696edfb)

Library Resources: Documents lists site-notes.md with Add file…, Images shows a count of 1

| Item | What it holds | How you add it | What drop onto markdown does |
| - | - | - | - |
| **Documents** | `.txt`, `.md`, and `.pdf` files in the **open project** | **Add file…**, or project / folder **Import file…** | Inserts a relative markdown link |
| **Images** | Project images (PNG, JPEG, SVG, GIF, WebP, and similar) | **Add file…** under Images, **Import file…**, or drag an image onto a project | Inserts a relative markdown image |

Click a document or image in Library to open it in the main pane (it replaces the notebook until you go back). Hover **Remove** on a Library leaf to delete that file from the list.

Right-click a project or folder for **Import file…** when you want the file to live under a specific folder rather than the Library picker. Dropping a Library image onto a project copies it into that project.

## Standalone Deployments vs Projects

The broker can run LoT **with** a live project, or **without** one. Broker runtime tells you which:

| Mode | Broker runtime label | What it means |
| - | - | - |
| **Live project** | **`Project: {name}`** (the live project's name) | At most one project is **LIVE**. Deployments from that project auto-commit. **Activate** / **Deactivate** on the project row choose which stored project is active |
| **Standalone** | **`Standalone`** | No project is loaded. Entities can still be running — you deployed cells with nothing live, or leftovers that no project owns. Auto-commit is off |

Standalone is a normal state: a scratchpad, the view after **Deactivate**, or entities deployed outside a project (another editor, an older session, or a cell run with nothing LIVE).

How the two interact:

* **Run cell / Deploy All** with nothing LIVE writes straight into standalone runtime. The toolbar stays a direct action.
* **Deploy All** from an idle project on the broker asks you to **Activate** first — it does not silently load that project.
* **Deploy All** from a local-only draft while another project is LIVE is refused (the toast points you at **Push**). Deploying those cells would write into the other live project.
* **Activate** loads a stored project's declarations. If the broker publishes entity ownership, only that project's entities stop; standalone leftovers stay. Without ownership, the confirm says the current project's entities are replaced.
* **Deactivate** unloads the live project and **removes its entities from running**. Auto-commit stops until you Activate again. Broker runtime then reads **Standalone** (plus anything that was never owned by that project). The confirm is explicit: *Deactivating **BMS** unloads it from the broker and **removes its entities from running**.*
* **Adopt into project** (Broker runtime context menu) writes selected running entities into a notebook and Pushes — that is how you turn a standalone set into a project.

## Moving Work Between Projects and the Broker

Right-click a project under **Projects** for operations on that row. A **LIVE** project and an idle on-broker project do not offer the same items (idle has **Inspect** and **Activate**; live has **Deactivate** and the full create/import set).

![Context menu for the digital-twin-energy-site project in the Coreflux HUB LoT Editor with New notebook, New folder, Import .lotnb, Import file, Push project to broker, Pull project from broker, Version history, Inspect, Activate, Deactivate, Rename, Delete local copy, and Remove project from broker in red](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-project-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=b1de7710d3bd7dbab1546706ab06d1ae)

The project context menu: notebooks and import, Push and Pull, Version history, Inspect, Activate and Deactivate, then Rename, Delete local copy, and Remove project from broker

| Item | What it does |
| - | - |
| **`New notebook`** / **`New folder`** | Add a `.lotnb` file or a folder inside the project |
| **`Push to broker`** | Send the whole project — every notebook and folder — to the broker. This is what links a local project to a broker project and puts it under version control |
| **`Pull from broker`** | Replace your local copy with the broker's. If you have unsaved local changes, a **"Pull from broker?"** prompt warns you first |
| **`Version history`** | Open the broker's git history for this project |
| **`Import .lotnb`** / **`Import file…`** | Bring a notebook or other file from outside into this project |
| **`Inspect`** | Download the broker's copy of an idle on-broker project into the editor (does not Activate) |
| **`Activate`** / **`Deactivate`** | Load or unload the stored project as the live one — see [Standalone vs projects](#standalone-deployments-vs-projects) |
| **`Rename`** | Rename the local project |
| **`Delete local copy`** | Delete the HUB notebooks only |
| **`Remove project from broker`** | Permanently delete the project from the broker |

Click **`Project: {name}`** to open the inspector table (status, type, name, owning project, notebook). A row with empty **Project** / **Notebook** is a standalone leftover — see [Standalone vs projects](#standalone-deployments-vs-projects). Right-click **Broker runtime** for operations on the running set:

![Context menu on the Broker runtime project in the Coreflux HUB LoT Editor with Adopt into project, Open in LoT Flow, Download all entities to notebook, and Remove all entities from broker in red](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-broker-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=4478729d7cf78baf27d769cf01f2b94a)

The Broker runtime context menu: Adopt into project, Open in LoT Flow, Download all entities to notebook, and Remove all entities from broker

| Item | What it does |
| - | - |
| **`Adopt into project`** | Write the selected (or all) running entities into a notebook, then Push |
| **`Open in LoT Flow`** | Open the live graph of this runtime |
| **`Download all entities to notebook…`** | Copy running definitions into a `.lotnb` file |
| **`Remove all entities from broker…`** | Undeploy the running set. Internal Rules stay |

## Version History

Broker projects are git repositories, and the editor exposes enough of that to recover from mistakes without a terminal:

![Coreflux HUB version history dialog for digital-twin-energy-site on main at ba3e485, explaining that history comes from the broker's git repository with auto-commit while active, RECENT COMMITS listing ba3e485 Initial project commit with Restore, a Branch / tag / commit to checkout field, and Checkout, Pull, Push, and refresh buttons](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-version-history-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=2f5e689648b640e271af79f91991accd)

Version history for digital-twin-energy-site on main: the note that history comes from the broker's git repository and that entity changes auto-commit while the project is active, recent commits with Restore, and Checkout, Pull, and Push

The dialog reports the project's branch and current commit, lists recent commits with their messages, and shows any uncommitted changes on the broker. From here you can:

* **Restore a commit** — checks that commit out on the broker and reloads the workspace if the project is active
* **Checkout a branch, tag, or commit** — type a ref and check it out
* **Pull** and **Push** — synchronise with the broker's configured git remote

> [!NOTE]
>
> **Entity changes auto-commit while the project is active.** You do not commit by hand — deploying an entity produces a commit like `Update connector: BacnetPortoHq`, which is why the history reads as a log of deployments.

> [!WARNING]
>
> Restoring a commit can discard uncommitted changes on the broker. Check the **Uncommitted changes** list in the same dialog before restoring.

## Pulling Entities Back Into a Notebook

Deployment is not one-way. Anything running on the broker can be brought back into a notebook, which is how you adopt LoT that was deployed by other means.

Right-click an entity **type group** under **Broker runtime**:

![Context menu on the Models entity type group in the Coreflux HUB LoT Editor Broker runtime showing Download all models to notebook… and Remove all models… in red](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-entity-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=23d5170f2ac72fbff7fbdc6c18350ed1)

The context menu on the Models group offers Download all models to notebook… and a red Remove all models…

Every type group carries its own pair, and the `Entities` group itself carries **`Download all to notebook…`** and **`Remove all from broker…`** for the whole set. Right-clicking a **single entity** offers **`Open in code editor`**, **`Download to notebook…`**, and **`Remove from broker…`**.

Any download asks **"Choose notebook"** — pick an existing `.lotnb` file in the project, or create a new one — and the definitions arrive as cells you can then edit and redeploy.

## Removal: Four Different Operations

Deleting locally and removing from the broker are different operations with different consequences, and the HUB guards them differently on purpose. Read the dialog: it tells you which one you are in.

| Trigger | Dialog | What it destroys | Guard |
| - | - | - | - |
| Workspace project → **`Delete local copy`** | **"Delete project?"** — local notebooks and folders only | Your local copy only | Plain confirm |
| Single entity → **`Remove from broker…`** | **"Remove from broker?"** — *Remove action "SummarizeF2Hvac" from the broker. This cannot be undone.* | One running entity | Plain confirm |
| `Entities` → **`Remove all from broker…`** | **"Remove all from broker?"** — *Remove 3 action(s), 3 model(s), 1 connector(s), 1 python script(s), 0 theme(s), and 0 panel(s) from the broker. Project-owned rules are also cleared; built-in and operator custom rules are preserved.* | Everything loaded on the broker | Plain confirm, but it enumerates live counts — read them |
| Broker project → **`Remove from broker…`** | **"Remove project from broker"** — *This permanently deletes **BMS** from the broker — all its files **and its entire git history**. This cannot be undone.* | The project, its files, and every commit | **Type-to-confirm** — the button stays disabled until you type the project name |

> [!WARNING]
>
> **Deleting a workspace project does not touch the broker, and removing a project from the broker does not touch your workspace.** A local delete leaves every entity running and every commit intact; a broker removal leaves your notebooks on disk but destroys the project's git history. Neither is a substitute for the other, and only the broker removal is guarded by type-to-confirm.

![Coreflux HUB dialog titled Remove project from broker in red, warning that this permanently deletes BMS from the broker including all its files and its entire git history and cannot be undone, with a Type BMS to confirm field and a greyed-out Remove permanently button beside Cancel](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-remove-project.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=dd4382034bd5b27a3afc4c80930feba1)

The broker project removal dialog: the description spells out that the git history goes too, and Remove permanently stays disabled until the project name is typed into the field

The bulk-remove wording also settles a question the sidebar raises: **project-owned rules are cleared, while built-in and operator custom rules are preserved.** That is why the `Rules` count under **Broker runtime** can be small while **Configuration → Internal Rules** lists the broker's locked built-ins separately.

> [!NOTE]
>
> A `.lotnb` file is the safety net worth having before any removal. **`Download all to notebook…`** on the `Entities` group captures everything currently deployed, and **`Export open notebook as .lotnb`** in the header `…` menu writes it out as a file.

## Editing the Same Project From VS Code

The in-HUB editor and VS Code share the same broker-held project and git history: a project pushed from the HUB opens in the VS Code extension and vice versa, and `.lotnb` files move between them directly:

* **`Import .lotnb`** on a project, or **`Import .lotnb file`** in the header `…` menu, brings a notebook from outside into that project
* **`Export open notebook as .lotnb`** takes the open notebook back out
* **`Push to broker`** and **`Pull from broker`** move the whole project, which is how two people using two editors stay on one project

Whichever tool deployed an entity, it appears the same way under **Broker runtime** and is drawn the same way in [LoT Flow](/hub/lot-flow).

***

## Next Steps

> **[LoT Flow](/hub/lot-flow)**
>
> See the entities you just deployed as a live dependency graph.

> **[VS Code LoT Notebooks](/lot-notebooks/usage)**
>
> Edit the same broker-held project from VS Code, then Push and Pull to stay in sync.


# LoT Flow
Source: https://docs.coreflux.org/hub/lot-flow

See the Actions, Models, Connectors, and topics deployed on your broker as a live dependency graph

![Coreflux HUB LoT Flow with the Entities rail listing 19 Actions and 9 Models, and a canvas showing topic groups such as u20/ and u1/ feeding TwinEnergyModbus route nodes badged MODBUS\_TCP, whose output groups connect to Action nodes like TwinEnergyTrackContext ON TOPIC and TwinEnergyProjectKpi ON EVERY 1 SECOND](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-flow/hub-lot-flow-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=a2e62ee81f95645778dd07f7971d8937)

LoT Flow for an energy-site project: write topics feed MODBUS\_TCP connectors, their topic groups fan out to ON TOPIC and ON EVERY Actions, and the Entities rail lists Actions and Models

## Why Use LoT Flow?

Once you have more than a handful of Actions, Models, and Connectors on a broker, the question "what happens when this topic changes?" stops having an obvious answer. Tracing it means opening each definition and following topic names by hand. LoT Flow reads the LoT entities deployed on your broker and draws how they connect — what triggers what, and which topics each one reads and writes — so you can follow the data flow instead of reconstructing it from source.

> [!NOTE]
>
> LoT Flow carries a **`Beta`** badge in its window header. It is available for everyday use, but its controls and layout may still change between releases.

> [!TIP]
>
> **Like a wiring diagram that draws itself.** You never maintain the diagram — it is rebuilt from whatever is actually running on the broker.

## When to Use It

* **Understanding an inherited project** — See the whole entity graph before changing any of it
* **Answering "what does this topic affect?"** — Follow trigger edges from a topic to the Actions it fires
* **Confirming a deployment** — Check that a newly deployed Action appears, and that it is wired to the topics you intended
* **Finding orphans** — Spot entities that nothing triggers and topics that nothing consumes
* **Reviewing an integration** — See which topics a Connector publishes into your namespace and which it writes back out
* **Debugging execution order** — Follow trigger and event edges to understand what runs before what

***

## LoT Flow Reads the Broker, Not Your Workspace

This is the single most important thing to know about LoT Flow: **the graph is built entirely from entities deployed on the connected broker.**

The LoT Editor's sidebar is split into two halves that are easy to conflate:

| Sidebar section | What it holds |
| - | - |
| **Workspace** | Notebook files local to your browser profile. Editing them changes nothing on the broker |
| **Broker** | `Projects`, `Entities`, `Configuration`, and `Library` — shared server state |

A notebook cell you have written but not yet deployed is marked **`NOT RUNNING`** in the editor, and it will **not** appear in LoT Flow. Deploy it — with **Deploy All**, or by running the individual cell — and it appears. Cells already live on the broker are marked **`DEPLOYED`**.

> [!NOTE]
>
> If an entity you just wrote is missing from LoT Flow, check that it was deployed. **Broker runtime** in the LoT Editor is the authoritative list of what is actually running on the broker, and the graph matches that list.

Because the graph reflects the broker rather than any one editor, it does not matter which tool produced the LoT. Entities deployed from the [LoT Editor in the HUB](/hub/lot-editor) and entities deployed from VS Code appear the same way.

***

## Accessing LoT Flow

Select **LoT Flow** in the HUB dock. The window header carries a **`Beta`** badge. The canvas top-right cluster is the layout chrome:

| Control | What it does |
| - | - |
| **Freshness** (`3m ago`) | How long ago the graph was last built from the broker |
| **Reset layout** | Auto-arranges every node from scratch — use it after collapsing topics, after dragging nodes out of place, or whenever the graph looks tangled. Tooltip: *Auto-arrange LoT Flow from scratch* |
| **Open LoT Editor** | Opens the editor so you can change the entities this graph is drawn from |

Zoom, pan, **Fit View**, and **Download image** sit at the bottom-left of the canvas. Fit the view after Reset layout or after changing grouping — a freshly laid-out graph is often off-centre.

## The Entity Rail

The **Entities** tab groups everything deployed, with a count per group and a **Find entity** search for jumping straight to one by name. Groups start collapsed; a search opens every group with a match:

| Group | Contents |
| - | - |
| **Actions** | Event-driven logic, each badged with its trigger type |
| **Models** | Data schemas that map topic values into structured documents |
| **Connectors** | Connections to external systems, badged with the connector type |
| **Agents** | `DEFINE AGENT` agents on the broker |
| **Things** | Root Things and their instances, when the broker has any |
| **Python** | The individual Python functions your Actions call |

Selecting an entity focuses it on the canvas and opens its detail panel.

> [!NOTE]
>
> The **Python** group lists the individual *functions* invoked from Actions, so its count is usually higher than the number of Python *scripts* deployed. A single script exposing four functions appears as one entity under **Broker runtime** in the LoT Editor and as four nodes here.

## Things, Tree, and Flat Views

When the broker has at least one root Thing, a toggle at the top-right of the canvas offers three views. Things is the default, and the HUB remembers your choice.

| View | What it shows |
| - | - |
| **Things** | One card per Thing and one line per pair of parties that exchange data. Drill in one level at a time, for example `All Things › Plant › line1 › oven`. Ports stand for whatever lies outside the current level. Entities that belong to no Thing are grouped as **Not in a Thing** |
| **Tree** | The whole containment tree on one canvas: `All Things`, the roots, then every instance. Each node shows `ROOT` or `OF <template>` and what it holds. Use search, **Depth**, and **Expand all** / **Collapse all** like in the [UNS Viewer](/hub/mqtt/uns-viewer). Switch on **Templates** to add the templates to the tree |
| **Flat** | The graph described below, with every entity and topic |

Select a Thing to open its details below the canvas: its chain, template, path, parameters (an override of a template default is marked), and what it owns. **Open level in Things view**, **Open in UNS Viewer**, and **Open cell in LoT Editor** jump to it. The UNS Viewer focus is temporary and doesn't change your saved root filter.

In the live Things view, panel cards have an expand toggle that grows the card into a watch-only preview of the panel. **Open in window** opens it to interact. See [LoT THING](/latest/lot-language/things/overview).

![Coreflux HUB LoT Flow window in the Things view with the breadcrumb All Things › Acme, root, path acme/plant/, 16/16 ok. Cards for line2 and line1, each OF BottlingLine with filler, capper, and labeler, 4 models, and 4 actions; an MQTT clients port with 8 topics in on the left, and lines labelled alarm ×3 to the Not in a Thing port on the right. The Things, Tree, and Flat toggle is at the top right](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-flow/hub-lot-flow-things-view-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=1b007e9780637beb1686ebbae3e0abb2)

Things view, one level into Acme: the line1 and line2 instances, with ports for the MQTT clients that feed them and for Not in a Thing, where their alarms go

![Coreflux HUB LoT Flow window in the Tree view with Search Things, Depth 3, Collapse all, Expand all, Compact spacing, and the Templates switch off. All Things, with 2 roots and 15 entities not in a Thing, branches to Acme, ROOT with 2 bottling lines, and Utilities, ROOT with 2 temp sensors. line1 and line2, OF BottlingLine, each hold filler OF Filler and capper and labeler OF TempSensor; Utilities holds chiller and compressor OF TempSensor](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/lot-flow/hub-lot-flow-tree-view-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=e1e5c9988c085e846b7971f63d57e3fc)

Tree view with templates hidden: All Things, the Acme and Utilities roots, and every instance with its template

## Reading the Graph

The canvas draws your entities, the topics that wire them together, and the Python they call:

| Node | Meaning |
| - | - |
| **Action** | Event-driven logic, badged with its trigger (for example `ON TOPIC`) |
| **Model** | A data schema, badged `Model` |
| **Connector** | An external connection, badged with its type and a health indicator |
| **Python** | A Python function, badged with the script it belongs to |
| **Topic** | An MQTT topic, showing its current value |
| **Topic group** | Many topics sharing a prefix, collapsed into one node with a count |

Edges are colour-coded by relationship — solid lines are live data flow, muted dashed lines are structure. The vocabulary covers `publish`/`sub`, `trigger`, `write`, `event`, `python call`, `dependency` (a value read but not triggered on), `internal state`, `extends`, and grouping links. Turn on the **Legend** from the Settings tab while you are still learning it.

> [!NOTE]
>
> LoT **Rules** are not drawn on the canvas. Rules govern access control rather than moving data, so the graph focuses on Actions, Models, Connectors, and Python. Rules deployed on your broker still appear under **Broker runtime** in the LoT Editor.

### How a single Action becomes a subgraph

The Action below reads four topics, calls two Python functions, and publishes a Model to a status topic:

```lot wrap focus={7-12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SummarizeF2Hvac
ON TOPIC "uns/porto/hq/f2/hvac/temp" DO
    SET "temp" WITH (GET TOPIC "uns/porto/hq/f2/hvac/temp" AS DOUBLE)
    SET "humidity" WITH (GET TOPIC "uns/porto/hq/f2/hvac/humidity" AS DOUBLE)
    SET "occupied" WITH (GET TOPIC "uns/porto/hq/f2/hvac/occupied" AS BOOL)
    SET "setpoint" WITH (GET TOPIC "uns/porto/hq/f2/hvac/setpoint" AS DOUBLE)
    CALL PYTHON "BuildingInsights.comfort_score"
        WITH ({temp}, {humidity}, {setpoint})
        RETURN AS {score}
    CALL PYTHON "BuildingInsights.comfort_label"
        WITH ({score})
        RETURN AS {label}
    PUBLISH MODEL F2HvacModel TO "uns/porto/hq/f2/hvac/status" WITH
        temp = {temp}
        humidity = {humidity}
        occupied = {occupied}
        setpoint = {setpoint}
        comfort_score = {score}
        comfort_label = {label}
        timestamp = TIMESTAMP "ISO"
```

On the canvas that becomes one Action node with a trigger edge from `temp`, dependency edges from the three topics it reads, `python call` edges to both `BuildingInsights` functions, and an edge to the Model that publishes the result. You can read the same relationships from the other direction in the [UNS Viewer](/hub/mqtt/uns-viewer), where each topic reports the Actions and Connectors that produce and consume it.

## Inspecting an Entity

Select any node, or any entity in the rail, to open its detail panel.

![Coreflux HUB LoT Flow with TwinEnergyProjectKpi selected in the Entities rail and highlighted on the canvas; the detail panel shows Receiving data, Trigger ON EVERY 1 SECOND, Enable Trace, Inputs 8, Outputs 1, Internal state, a Publish a test value control, and a LoT Code block beginning DEFINE ACTION TwinEnergyProjectKpi](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-flow/hub-lot-flow-entities-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=213dda03b837e62cb448f90af5bca340)

The detail panel for the TwinEnergyProjectKpi Action: Receiving data, its ON EVERY 1 SECOND trigger, Trace, inputs and outputs, Publish a test value, and the deployed LoT source

Depending on the entity type, the panel reports:

* **Its trigger** and a live status such as `Receiving data`
* **Inputs and outputs** — the topics it consumes and produces, with counts
* **The deployed LoT source**, syntax-highlighted, so you can read what is actually running
* **Connector status** for Connector entities, including connection health
* **Trace** — capture this Action's executions to see it run. Traces auto-expire after five minutes
* **Publish a test value** — send a value to one of the entity's topics to exercise it

> [!TIP]
>
> **Trace answers "did it actually run?"** Rendering a graph proves an Action is deployed and wired up; a trace proves it fired.

## Keeping Large Graphs Readable

The **Settings** tab is the Canvas menu — grouping, look, and collapse live here. Layout itself is the **Reset layout** control at the top-right of the canvas, not in this list.

| Option | What it does |
| - | - |
| **Legend** | Puts a key for node and edge types on the canvas |
| **Minimap** | An overview map. Leave it off on a wide graph — it parks in the bottom-right and can cover real nodes |
| **Topic update flash** | Pulses a topic node when a new value arrives |
| **Edge style** | Smooth step, Bezier, Step, or Straight. This is a persisted preference, not a fixed default |
| **Spacing** | Compact, Comfortable, or Spacious. Also persisted |
| **Group large branches** | Fold sibling topics that share a prefix into one topic-group node with a count |
| **Collapse over** | How many children a branch needs before it groups. `1` groups every sibling set, which is the most readable hero view on a busy namespace. The field accepts `1`–`50` |
| **Collapse all** / **Expand all** | Collapse or expand every grouped branch at once |

After you change grouping, click **Reset layout** (top-right of the canvas) so the remaining nodes are placed again, then **Fit View**. Collapsing without resetting leaves the old positions and a lot of empty space.

Topic grouping is the most effective control on a busy namespace: **Collapse over** `1` folds each floor/device prefix — `…/f2/hvac/` `4/4`, `…/f2/energy/` `2/2` — into one node. The relationships stay on the graph; only the leaf clutter goes.

***

## Next Steps

> **[UNS Viewer](/hub/mqtt/uns-viewer)**
>
> Explore the topic namespace those entities read from and write to.

> **[LoT Editor](/hub/lot-editor)**
>
> Create and deploy the entities that appear in this graph, cell by cell.


# Connected Clients
Source: https://docs.coreflux.org/hub/mqtt/connected-clients

View active MQTT client connections and their status in the Coreflux HUB

![Coreflux HUB Connected Clients view listing two active MQTT v4 connections, coreflux-controller-a4d3f1ef at 127.0.0.1:32946 with 20m duration and 31.31 MB traffic and mqtt-explorer-05b06873 at 127.0.0.1:14107 with 40m duration and 36.23 MB traffic, and an empty detail panel on the right prompting to select a client to view details](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/connected-clients/connected-clients-list.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=9faadc42c50d926edd5fb7930032b751)

Connected Clients view in the Coreflux HUB showing two active MQTT v4 connections with an empty detail panel

## Why View Connected Clients?

You need to know which clients are connected to your broker—devices, applications, or the Coreflux HUB itself. The Connected Clients view shows all active MQTT connections with detailed connection info, traffic statistics, session data, and last activity so you can verify connectivity and troubleshoot disconnections.

## When to Use It

* **Verifying device connections** — Confirm that sensors or gateways are connected
* **Troubleshooting** — Check if a client has disconnected or failed to connect
* **Monitoring** — See how many clients are using the broker and their traffic
* **Debugging** — Inspect session state, pending messages, and last activity timestamps

***

## Connected Clients Interface

The Connected Clients view has two panels: a client list on the left and a detail panel on the right. Select a client to view its connection information.

![Coreflux HUB Connected Clients with 4 clients listed on the left (MQTT v5 and v4, endpoint, connected time, and traffic), and the selected client's Connection Information, Traffic Statistics for received and sent bytes, packets and messages, Session Information with status Connected, and Last Activity](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/connected-clients/connected-clients-detail-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=9ccafcb4161bec7f398c841d7663c85b)

Connected Clients with a client selected: connection information, traffic statistics, session information, and last activity

***

## Client List (Left Panel)

The left panel lists all clients currently connected to the broker. For each client you see:

| Field | Description |
| - | - |
| **Client ID** | Unique identifier for the connection (e.g., `coreflux-controller-0e1e882c`) |
| **Endpoint** | Client IP and port (e.g., `127.0.0.1:62983`) |
| **Connection Duration** | How long the client has been connected (e.g., `40m`) |
| **Total Traffic** | Estimated bytes received and sent combined (e.g., `15.16 MB`) |
| **Protocol** | MQTT version (e.g., `MQTT v4`) |

Select a client to view its detailed information in the right panel.

## Client Details (Right Panel)

When you select a client from the list, the right panel shows four sections:

### Connection Information

| Field | Description |
| - | - |
| **Protocol Version** | MQTT version (e.g., MQTT v4) |
| **Source Port** | Client's source port |
| **Connected** | Timestamp when the client connected |
| **Client IP** | Client IP address |
| **Full Endpoint** | IP:port (e.g., `127.0.0.1:62983`) |
| **Duration** | Connection duration (e.g., `40m`) |

### Traffic Statistics

| Direction | Fields |
| - | - |
| **Received** | Bytes, Packets, Messages |
| **Sent** | Bytes, Packets, Messages |

Use these to see how much data the client has exchanged with the broker.

### Session Information

| Field | Description |
| - | - |
| **Session ID** | Session identifier (typically matches Client ID) |
| **Created** | Timestamp when the session was created |
| **Expiry Interval** | Session expiry (e.g., `0s` for no expiry) |
| **Pending Messages** | Number of messages awaiting delivery to this client |
| **Status** | Connection status (e.g., Connected) |

### Last Activity

| Field | Description |
| - | - |
| **Last Packet Received** | Timestamp of the last packet received from the client |
| **Last Packet Sent** | Timestamp of the last packet sent to the client |
| **Last Non-KeepAlive** | Timestamp of the last non-keepalive packet |

## Refreshing the List

The view updates as clients connect and disconnect. Use the refresh control if you need to force an update of the displayed list. The detail panel shows an "Updated" timestamp indicating when the data was last refreshed.

***

## Next Steps

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Explore topics and publish messages.

> **[MQTT Protocol](/latest/mqtt-broker/protocol)**
>
> Understand MQTT client connections and sessions.


# Data Viewer
Source: https://docs.coreflux.org/hub/mqtt/data-viewer

Subscribe to topics, view the topic tree, listen to raw PCM, and publish messages from the Coreflux HUB

![Coreflux HUB Data Viewer with Publish and Settings icons on the left, a Filter field set to energy-site-01, the topic tree expanded to Modbus units and lot and status branches with live values and JSON previews, and the status/host card on the right with a Live timeline histogram and a parsed payload](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-overview-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=6b410c1ce65cc1f77a640aa79184b898)

Data Viewer with the topic tree filtered to energy-site-01 and expanded with live values, and the status/host topic pinned on the right with its message timeline and payload

## Why Use the Data Viewer?

You need to see what data is flowing through your broker—which topics are active, what payloads look like, and how to send test messages. The built-in Data Viewer in the Coreflux HUB lets you subscribe to topics, browse the topic tree, and publish messages without installing an external MQTT client.

> [!TIP]
>
> **An MQTT data viewer built into your Coreflux.** Designed to feel as intuitive as the popular MQTT Explorer desktop app — but with zero installation, right inside the HUB.

## When to Use It

* **Viewing device data** — Subscribe to sensor or device topics to see live readings (temperature, status, etc.) as they arrive
* **Exploring your topic structure** — Browse the Topic Tree to understand which topics exist and how they are organized
* **Verifying Actions** — Subscribe to output topics to confirm your LoT Actions are publishing correctly
* **Debugging** — Inspect payloads and topic structure in real time
* **Testing** — Publish messages to trigger Actions, test Connectors, or simulate device data
* **Monitoring broker activity** — Watch `$SYS` topics to check broker health, connected clients, and message throughput
* **Listening to audio** — Hear raw PCM on a topic, watch the waveform, and export a WAV clip

***

## Accessing the Data Viewer

1. In the HUB top navigation, select **MQTT**, then **Data Viewer**.
2. The Topic Tree appears on the left, showing topics as they receive messages.
3. Select a topic to view its payloads in the right panel.

![Animated walkthrough showing how to open the Data Viewer from the Coreflux HUB top navigation](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/view-mqtt-data.gif?s=0c0d326259f91e2d49562aff1c27d5ae)

Opening the Data Viewer from the Coreflux HUB dashboard

## Topic Tree

The Topic Tree shows the hierarchical structure of topics. Topics appear as messages are received. Expand branches to navigate and select a topic to view its payload history in the payload viewer.

![Coreflux HUB Data Viewer with the filter energy-site-01/lot, the tree expanded to dt/v1/demo/energy-site-01/lot listing alarm, building, connectivity, kpi, pv, site, and storage with JSON previews, kpi highlighted, and the lot/kpi card with a Live timeline and fields such as source, processed\_at, pv\_kwh, and import\_kwh](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-topic-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=4cd3168e93257369c4f91b31013cd20b)

Topic Tree filtered to energy-site-01/lot with the kpi topic selected: its card on the right shows a live message timeline and the parsed payload

## Exploring Live Data

The Data Viewer is laid out as three vertical panels: **Publish** on the left, the **Topic Tree** in the middle, and a **Detail area** on the right where you build a personal view of the topics you care about right now. You can drag the divider between the tree and the detail area, and collapse the Publish panel into a thin rail to give yourself more room.

> [!TIP]
>
> **Like an instrument panel for your broker.** Instead of reading rows of raw messages, you pin the topics that matter to the right side and watch them update — values, charts, lamps, even maps — in real time.

### Previewing a topic

Get a feel for what is happening on the broker without committing to a layout. Click any topic in the tree and its latest payload appears in the Detail area as a quick preview.

Each row in the tree carries a small **type icon** that tells you at a glance what kind of value the topic currently holds:

| Icon | Meaning |
| - | - |
| Glowing orange dot | Boolean `true` |
| Empty dot | Boolean `false` |
| `#` | Number |
| `{}` | JSON object |
| `[]` | JSON array |
| `"` | Plain string |

Rows briefly **flash orange** whenever a new message arrives, so you can see broker activity without staring at every value. To narrow the list, type any part of a topic path into the **Filter** box at the top of the tree — the filter matches anywhere in the path, and the usual display cap is lifted while you are filtering. For broader monitoring, you can also subscribe with a wildcard pattern such as `sensors/#`, and every matching topic appears in the tree as messages come in.

### Tracking what matters

Once a topic is worth watching, **pin it**: double-click the topic, or drag it from the tree onto the Detail area. A card appears for it, and the card shape adapts to the payload so you don't have to mentally decode raw values:

* **Numbers** render as a large value with a **sparkline** of recent history — perfect for sensor readings like temperature or RPM.
* **Booleans** render as a glowing **lamp** — green when `true`, dim when `false`.
* **JSON and text** render with colored keys and an expandable tree, so nested objects stay readable.
* **Geolocation** payloads (latitude/longitude) render as a small **map** with the current point and a trail of recent positions, plus the raw payload underneath. The map uses OpenStreetMap tiles. In the dark theme those tiles are darkened, while the marker, the trail, and the **© OpenStreetMap contributors** attribution keep their own colours.

Cards can be reordered by dragging them up or down, copied to the clipboard with one click, and removed with the **X** in their corner. Add more topics any time from the dashed **+ Add topic** button at the bottom of the cards, which opens a searchable list of every known topic.

![Coreflux HUB Data Viewer with the Topic Tree on the left expanded to kpi/operational showing messageCount, messagesPerMinute, and status with their inline values; on the right a tracked card for operational/messageCount displays the value 113 with a sparkline trail, a timeline above shows 197 message marks, and an + Add topic button sits below the card](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/mqtt-explorer-tracked-card.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=ca9252f0862b63263046c6777f2d6161)

Tracking kpi/operational/messageCount: the tree on the left shows live values with type icons, while the right panel pins the topic as a card with the current value (113) and a sparkline of recent history, plus a timeline of the last 197 messages above it

### Replaying history with the timeline

As soon as you are tracking topics with more than one message of history, a **timeline** appears at the top of the Detail area. Every tracked topic gets its own color, and every message it has received is drawn as a colored mark on a horizontal track.

From there you can:

* **Click or drag** anywhere on the track to scrub to a moment in time — every card below jumps to the values they had then.
* Step message-by-message with **First / Previous / Next / Last**.
* Hit **Play** to replay the message history like a video, with cards animating through every value.
* Tap **Live** to snap back to the latest message and resume real-time updates (the label turns green when you are caught up).
* Open the gear icon to change the **history buffer** per topic, from 50 up to 2 000 messages — larger buffers give you more scrub range.

While the viewer is focused, the arrow keys step through messages, **Home** jumps to the first, and **End** jumps back to live.

![Coreflux HUB Data Viewer with three tracked topics lot/kpi, lot/pv, and lot/storage as colored chips, a multi-row message timeline with playback controls, Live, and a position counter, and the three topic cards stacked below with their parsed payloads](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-timeline-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=11a166413664ec8113e3586eacc071fd)

Timeline tracking three topics: each topic gets its own chip and row, with playback controls and the Live indicator above the stacked cards

### Drilling into payloads

When a payload is too big to read inline, click its preview in the tree to open the **payload inspector** — a floating window that parses the full payload and lets you expand JSON to any depth. If the payload contains coordinates, the inspector draws the same OpenStreetMap map at the top.

For payloads where you only care about one number, drag a single value out of the inspector (or out of a card's expanded JSON tree) onto the Detail area. That value becomes its own **extraction card** — a small card that tracks just that one field, sparkline included if it's numeric. It's the fastest way to follow `temperature` from a 30-field sensor payload without the surrounding noise.

![Coreflux HUB Data Viewer payload inspector floating over the tree for dt/v1/demo/energy-site-01/lot/kpi, showing the pretty-printed JSON payload with source, processed\_at, telemetry\_sequence, pv\_kwh, import\_kwh, export\_kwh, self\_consumption\_pct, and peak\_import\_kw, view buttons in the header, and a playback timeline with Live at the bottom](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-payload-inspector-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=1b1ed2d645e4fee2da7783596b525bee)

Payload inspector for dt/v1/demo/energy-site-01/lot/kpi in Code view: the payload is pretty-printed, with Graph, Code, Diff, Message list, and Expanded views and a message timeline at the bottom

### Drag-and-drop cheatsheet

Most of the viewer is built around dragging. While you are dragging, valid drop zones light up so you can't miss them.

| Drag this | Onto this | Result |
| - | - | - |
| A topic in the tree | The Detail area | Adds a tracked card for that topic |
| A topic in the tree | The timeline's topic chips | Adds the topic to the timeline only |
| A topic in the tree | The Publish panel's Topic input | Pre-fills the publish topic |
| A topic in the tree | The Publish panel's Payload area | Pastes the topic's current value |
| A JSON value from a payload | The Detail area | Creates an extraction card for that single field |
| A JSON value from a payload | The Publish panel's Payload area | Pastes just that value |

## Publishing Messages

To publish a test message:

1. Click the **Publish** (paper plane) icon in the Data Viewer's left rail to open the Publish panel.
2. Select or enter the target topic.
3. Enter the payload and pick its format (**RAW**, **JSON**, or **XML**), with optional **QoS** and **Retain**.
4. Click **Publish** to send the message.

Use this to trigger Actions, test connector configurations, or simulate device data.

![Coreflux HUB Data Viewer with the Publish panel open showing a Topic field, QoS 0 selector, Retain toggle, an orange Publish button, RAW, JSON, and XML format buttons, and an empty payload editor, next to the topic tree](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-publish-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=c7b230435ce5d99898f4f101ca39bd1d)

The Publish panel open on the left of the Data Viewer: topic, QoS, Retain, the Publish button, payload format, and the payload editor

## Listening to PCM audio

Some topics carry sound as raw bytes — the chunks an [Audio Input](/latest/lot-language/routes/media/audio-input) connector publishes from a microphone, a tone, or a file. When the payload is that raw PCM, the detail area switches to an audio view.

The viewer decides from the payload, not from the topic path. A topic named `sensors/line1/status` is audio if the bytes are PCM. A topic with `audio` in the path stays a normal text or JSON card when the payload is not PCM.

From that view you can:

* Watch a **live waveform** as chunks arrive.
* **Listen** to the stream.
* **Capture** a stretch of audio and **review** it before you keep it.
* **Export WAV** of the captured clip.
* **Scrub the timeline** — the waveform, playback, and the other tracked cards stay on the same moment.

## Open the viewer in its own window

In the HUB, **Open in a new window** opens the Data Viewer in its own window on the broker you are already connected to.

***

## Next Steps

> **[Connected Clients](/hub/mqtt/connected-clients)**
>
> See which clients are connected to your broker.

> **[MQTT Broker Protocol](/latest/mqtt-broker/protocol)**
>
> Learn how MQTT topics and wildcards work.


# MQTT Overview
Source: https://docs.coreflux.org/hub/mqtt/overview

Browse topics, publish messages, and see who's connected — all from your Coreflux HUB

![Coreflux HUB Data Viewer showing the publish panel on the left, the topic tree expanded to \$SYS/Coreflux/Resources, and the Resources/MemoryInfoTotal topic plotted live on the right](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/hub-mqtt-overview.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=eb0667ff8af36d41369915e029c35661)

Data Viewer in Coreflux HUB — topic tree with publish controls

## Your MQTT Dashboard

Welcome to your built-in MQTT toolbox. From here you can browse every topic on your broker, publish test messages, and check which clients are online — all without leaving the Coreflux HUB. Two widgets are ready for you: **Data Viewer** for topics and messages, and **Connected Clients** for monitoring connections.

> [!TIP]
>
> **No need to install external tools** — the Data Viewer is built right into the Coreflux HUB.

## Pick the Right Widget

| Widget | You want to... |
| - | - |
| **Data Viewer** | Browse topics, inspect payloads, or publish test messages |
| **Connected Clients** | See who's connected and check connection health |

***

## Next Steps

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Subscribe to topics, browse the topic tree, and publish messages.

> **[Connected Clients](/hub/mqtt/connected-clients)**
>
> View active MQTT client connections and their status.


# UNS Viewer
Source: https://docs.coreflux.org/hub/mqtt/uns-viewer

Explore your broker's topic namespace as a live hierarchy graph in the Coreflux HUB

![Coreflux HUB UNS Viewer with the Namespace rail on the left showing Root filter #, Include \$ topics, Expand depth 3, Collapse all and Expand all, and Canvas options Legend, Minimap, Edge style Bezier, Spacing Compact; the canvas shows Root 97 branching into dt 96 and spBv1.0 1, then v1, demo 95, twins 1, CorefluxDemo and NDATA, with a 97 topics badge](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/uns-viewer/hub-uns-viewer-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=fd8a60376ed29d0c30d89f6909536a6c)

UNS Viewer showing a namespace of 97 topics: Root splits into dt and spBv1.0, dt expands through v1 into demo and twins, and spBv1.0 into CorefluxDemo and NDATA

## Why Use the UNS Viewer?

You have hundreds or thousands of topics on your broker and you need to understand their *shape* — how the namespace is organised, which levels exist, and where a given device or metric sits in the hierarchy. Reading that structure from a flat list of topic strings is slow and error-prone. The UNS Viewer draws your broker's namespace as a hierarchy graph, so you can see the structure at a glance instead of reconstructing it in your head.

> [!NOTE]
>
> The UNS Viewer carries a **`BETA`** badge in its window header. It is available for everyday use, but its controls and layout may still change between releases.

> [!TIP]
>
> **Like a map of your factory instead of a list of street names.** A topic list tells you what exists; the namespace graph shows you how it all fits together.

## When to Use It

* **Understanding an unfamiliar broker** — Open the namespace and read the hierarchy top-down instead of guessing at topic conventions
* **Reviewing your namespace design** — Check that a new site, line, or device was published under the level you intended
* **Finding where a metric lives** — Search for a name and see which branch of the hierarchy it belongs to
* **Tracing a topic back to your logic** — Each leaf reports which Actions and Connectors produce or consume it
* **Comparing several topics at once** — Select multiple topics and watch their values and history side by side
* **Spotting activity** — Live pulses show which parts of the namespace are actually receiving traffic

***

## Accessing the UNS Viewer

Select **UNS Viewer** in the HUB dock. The window opens with the namespace already built from the topics the HUB has seen, and a `N topics` badge in the top-right corner reports how many leaf topics are currently in scope.

## Reading the Graph

The canvas draws two kinds of node:

| Node | Shape | Meaning |
| - | - | - |
| **Namespace node** | Square | A level in the hierarchy. Carries a count of everything beneath it, and a chevron to expand or collapse its children |
| **Leaf topic** | Rounded | An actual MQTT topic. Shows its current value inline |

Colour and motion carry meaning too, and the **Legend** toggle puts a key on the canvas while you are learning the vocabulary:

* **Live value** — a green pulse means a message just arrived on that topic
* **Activity pulse** — a green glow on a namespace node shows aggregated traffic somewhere below it
* **Search match** — an amber ring marks topics matching your current search

Only leaf topics carry payloads. Selecting a namespace node reports `No message at this time`, because the values live on its children.

## Navigating the Namespace

The **NAMESPACE** section of the left rail controls how much of the tree is drawn:

| Control | What it does |
| - | - |
| **Root filter** | An MQTT filter that scopes the whole view, `#` by default. The `N topics` badge follows the filter |
| **Include \$ topics** | Brings broker-internal `$SYS` and `$Visu` topics into the graph, which are hidden by default |
| **Expand depth** | How many levels are expanded when the graph is built. Defaults to `3` |
| **Collapse all** / **Expand all** | Collapse the whole tree, or expand every level at once |

> [!NOTE]
>
> The **Root filter** applies when you press **Enter** — typing a filter alone does not redraw the graph.

On a large namespace, narrowing the root filter to a subtree such as `uns/porto/hq/f1/#` is the fastest way to keep the graph readable.

The **Search topics** box highlights matching topics in place with an amber ring rather than filtering the graph, so you keep the surrounding structure as context while you locate something.

![Coreflux HUB UNS Viewer with Root filter dt/v1/demo/energy-site-01/#, a 95 topics badge, Expand depth 3, Legend and Minimap switched on, a canvas chain Root, dt, v1, demo, a minimap in the bottom-right, and a legend for Live value, Activity / update pulse, and Search match](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/uns-viewer/hub-uns-viewer-controls-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=8981393eb1aa9810857d5159bdb994d3)

The Namespace rail with the Root filter scoped to dt/v1/demo/energy-site-01/#, which narrows the badge to 95 topics; Legend and Minimap are on, adding a key at the bottom and an overview map in the corner

### Canvas options

The **CANVAS** section changes how the graph is drawn without changing what it contains:

| Option | Choices |
| - | - |
| **Legend** | Show or hide the node and edge key |
| **Minimap** | Show or hide an overview map for staying oriented in large graphs |
| **Edge style** | Smooth step, Bezier, Step, or Straight |
| **Spacing** | Compact, Comfortable, or Spacious |

Zoom, pan, and a **fit-view** control sit at the bottom-left of the canvas. Fit the view after expanding or filtering — a freshly laid-out graph is often off-centre.

***

## Inspecting a Topic

Select a leaf topic to open the inspector on the right. It reports the topic's breadcrumb path, its live value, its history, and how it relates to the LoT running on your broker.

![Coreflux HUB UNS Viewer with the topic inspector open for uns/porto/hq/f2/hvac/temp, showing a breadcrumb of uns, porto, hq, f2, hvac, temp, First/Previous/Play/Next/Last playback controls, a green Live toggle, a timestamp of 23:07:36.790 with position 250 / 250, an orange message histogram running from 23:03:27.788 to 23:07:36.790, a value card reading 20.61 with a sparkline, and three cross-reference rows reading Triggers action SummarizeF2Hvac, Referenced by action SummarizeF2Hvac, and Produced by connector BacnetPortoHq](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/uns-viewer/hub-uns-viewer-inspector.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6083e4aeca9e5f2afd26eca7402d47f8)

The inspector for uns/porto/hq/f2/hvac/temp: a Live indicator, playback controls, a message histogram spanning 23:03:27 to 23:07:36, a position counter reading 250 / 250, a value card showing 20.61 with a sparkline of recent history, and cross-references reporting that the topic triggers and is referenced by action SummarizeF2Hvac and is produced by connector BacnetPortoHq

The inspector gives you:

* **A value card** with the current value and a **sparkline** of recent history
* **A message histogram** with the start and end timestamps of the buffered history
* **Playback controls** — step to first, previous, next, or last message, or play the history back
* **A `Live` toggle** that snaps to the latest message and resumes real-time updates
* **LoT cross-references** — which Actions the topic triggers, which reference it, and which Connector produces it

Those cross-references are the bridge between your namespace and your logic. A topic written by a Connector and consumed by an Action shows all three relationships, and a topic that nothing uses reports `Not referenced by any action or connector.`

> [!TIP]
>
> Cross-references answer "is anything actually using this topic?" — useful when cleaning up a namespace, or when confirming that a newly deployed Action really is wired to the topic you intended.

### Comparing several topics

Turn on **multi-select** in the top-right corner to keep more than one topic selected. Each selection becomes a removable chip carrying its own message count, the inspector header counts them, and the histogram merges every selected topic onto one timeline so you can line their behaviour up against each other. Press `Esc` to leave multi-select.

With multi-select off, a plain click replaces the current selection, while `Shift`, `Ctrl`, or `⌘` click adds to it.

***

## Namespace Best Practices

The UNS Viewer makes the consequences of namespace design visible, and the shape it draws is only as good as the topics you publish:

* **Keep the hierarchy consistent** — model your physical or organisational structure, so the graph reads like your plant
* **Use lowercase, stable, descriptive segment names** — and avoid renaming a level once it is in use
* **Publish state as retained messages** so late subscribers, including this viewer, get the current value
* **Prefer descriptive leaf metrics** over opaque blobs that have to be parsed downstream
* **Narrow the root filter** on large namespaces rather than fighting a graph with thousands of nodes

> [!NOTE]
>
> The viewer builds its tree from the topics the HUB has observed. A topic that has never published, and holds no retained value, cannot appear in the graph.

***

## Next Steps

> **[LoT Flow](/hub/lot-flow)**
>
> See the Actions, Models, and Connectors behind those topics as a dependency graph.

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Read individual payloads, track topics as cards, and publish test messages.


# Coreflux HUB Overview
Source: https://docs.coreflux.org/hub/overview

Manage your Coreflux broker—explore MQTT topics, edit LoT code, configure connectors, and monitor system health from the browser or the standalone desktop app

![Coreflux HUB desktop with wallpaper, the top-right status bar showing 9 Routes, Enterprise, the date and time and the root broker menu, and the bottom dock with Coreflux AI, Data Viewer, Routes, LoT Editor, LoT Flow, UNS Viewer, and Dashboards](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/hub/overview/hub-desktop-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=5bbbc917ee62f5c33515685359a848ed)

Coreflux HUB desktop with the app dock and the status bar (connectors, license, time, and broker menu)

## Why Use the Coreflux HUB?

You need a single place to manage your broker without installing extra tools or connecting via the command line. The Coreflux HUB gives you an interface to explore topics, create and edit LoT (Language of Things) definitions, configure connectors, and monitor system status—all from one dashboard. It is available as a browser app (its own container, via Docker Compose) or as a standalone desktop application for Windows and Linux.

> [!NOTE]
>
> The Coreflux HUB is a **separate container** from the broker — it is not bundled in the broker image. Run it with **Docker** or **Docker Compose** (open `http://localhost:3000`) or as a **standalone desktop application** for Windows x64, Linux x64, and Linux ARM64. See [Installation](/latest/quick-start/installation) for Docker commands, Compose profiles, the HUB desktop app, and the login flow. Download builds from the [Downloads page](https://portal.coreflux.org/downloads). An installed desktop app updates itself — see [Update the HUB desktop app](/latest/updating-coreflux#hub-desktop).

> [!NOTE]
>
> A web HUB (Docker or Docker Compose) can be installed from the browser as an app that opens in its own window. After the page loads, use the browser's install control — often **Install** or **Add to Home Screen**. Browsers offer this on `localhost` and on HTTPS. The desktop app is already installed and does not use this.

> [!TIP]
>
> Serve a web HUB over HTTPS (a reverse proxy that terminates TLS) or open it on `localhost`. Over plain HTTP on a LAN address, browsers block clipboard access, so the HUB's copy buttons fail on current versions. See [Copy buttons don't work](/latest/quick-start/installation#copy-buttons-dont-work-in-the-hub).

> [!TIP]
>
> **Like a control panel for your broker.** The HUB puts Data Viewer, LoT Editor, connector management, and system tools in one place so you can deploy and debug without extra tooling.

## When to Use the HUB

* **Manage everything from the HUB** — Configure your broker, deploy logic, and set up data connectors without installing desktop tools
* **Go from idea to deployment in minutes** — Write and deploy Actions, Models, and Rules directly in the built-in editor
* **Monitor your system in real time** — See device connections, data flow, and system health at a glance
* **Diagnose issues fast** — Inspect live MQTT messages and run broker commands from one interface

## Prerequisites

Install the HUB (and the broker, if you do not already have one) from [Installation](/latest/quick-start/installation). After `docker compose --profile full up`, open `http://localhost:3000`, click **New Connection**, and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`). The desktop app is on the **HUB desktop** tab of that page.

To open brokers your organization registered at [portal.coreflux.org](https://portal.coreflux.org), use **Coreflux Fleet** on the login card instead of **New Connection**. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).

## How the HUB Is Organized

The HUB is built around six apps. Each app groups related tools so you can switch between tasks without leaving the browser. **Cluster Viewer** is Beta. Its dock icon, labeled **Cluster**, appears only when the broker host you are connected to is in a cluster.

> **[MQTT](/hub/mqtt/overview)**
>
> Explore topics, publish messages, and view connected clients.

> **[LoT Editor](/hub/lot-editor)**
>
> Create and edit Actions, Models, and Rules in the browser.

> **[Dashboards](/hub/dashboards/overview)**
>
> Build live panels with gauges, charts, and controls bound to broker data.

> **[Connectors](/hub/routes/overview)**
>
> Add, configure, and monitor connectors with templates or LoT code.

> **[System](/hub/system/overview)**
>
> Broker configuration, user management, trace logs, and command console.

> **[Cluster Viewer](/hub/cluster-viewer)**
>
> See nodes, the leader, links, and ownership on a clustered broker host. Beta.

> [!NOTE]
>
> Connected to a generic MQTT broker, the dock keeps **Data Viewer** and **UNS Viewer**. Coreflux apps stay hidden, and the status bar offers **Know more about Coreflux**. See [When the broker is not Coreflux](/hub/connections#when-the-broker-is-not-coreflux).

### MQTT

Browse live data flowing through your broker. The MQTT app includes a **Data Viewer** for subscribing to topics and publishing test messages, and a **Connected Clients** view to see which devices are online.

![Coreflux HUB Data Viewer maximized, topic tree filtered to energy-site-01 with live values, and the status/host topic pinned on the right with a Live message timeline and a parsed JSON payload](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-overview-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=6b410c1ce65cc1f77a640aa79184b898)

Data Viewer: the topic tree filtered to a site, with a topic pinned on the right showing its message timeline and payload

### LoT Editor

Write and deploy logic directly in the HUB. The LoT Editor is a notebook editor: cells hold LoT, Python, or Markdown, each cell deploys on its own, and the sidebar lists everything currently running on the broker — no external tools required.

![Coreflux HUB LoT Editor showing the digital-twin-energy-site project badged LIVE, energy-site.lotnb open with a markdown intro and a DEFINE ROUTE cell badged DEPLOYED, and the Broker runtime tree with Actions, Models, Rules, Routes, Python, Themes, and Panels](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=99cf12e43faa20ef201525799789f24a)

LoT Editor with the live project's notebook open: Projects, Broker runtime, Configuration, and Library in the sidebar, with Deployed and Deploy All in the header

### Dashboards

Design operator-facing screens from a component library—gauges, charts, industrial symbols, and controls—and bind each widget to live data on your broker. The **Dashboard Manager** lists your panels; open one to preview or use it full screen for walls and shared links.

![Coreflux HUB panel Solar energy site · Energy twin with a 3D site scene labelled with live power values, and Site power cards for PV, Site load, Grid, Battery, a Fleet state of charge gauge, and Peak import cap](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/dashboard/overview-hero-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=d66a730bd8466d29aa748fa31e47a610)

Dashboards: a published panel with a live 3D site view and KPI cards bound to broker topics

### Connectors

Connect your broker to databases, PLCs, and external systems. The Connectors app shows each connector as a card with a live **status indicator**, and lets you configure connectors visually or in LoT code.

![Coreflux HUB Connectors Manager with connector cards for LegacyLogs and PlantArchive (FILE\_STORAGE), each with a status dot and Configuration, Monitor, Documentation, and Delete icons, an Add connector card, and the status bar Connectors popover](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/routes/overview/connectors-manager-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=6b518a51578d5981f1a1dbae80dbe065)

Connectors Manager: connector cards with type badges, live status dots, and quick actions

### System

Administer the broker itself. The System app provides **Broker Configuration**, **User Management**, a **Command Console** for direct broker commands, and **Broker Logs** for real-time diagnostics.

![Coreflux HUB broker menu opened from the status bar showing Online with the broker version, then Broker items Connected Clients, Broker Settings, User Management, Command Console, Broker Logs, HUB items Themes and Hub Settings, Help items, and Log out](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/hub/overview/hub-system-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=a3a37badfbbd20a8f97e5fbdef5dbf09)

The broker menu in the status bar: broker tools, HUB settings, and help

### Cluster Viewer

See how the broker hosts in a cluster fit together: who leads, which links are up, which node owns each exclusive piece of LoT, and how partitions are placed. Open **Cluster** on the dock. The window carries a **Beta** badge, and the icon is there only while that broker host publishes cluster status. See [Cluster Viewer](/hub/cluster-viewer).

***

## Desktop shell

The desktop layout keeps a Coreflux logo at the top left, a status bar at the top right, and the app dock along one edge of the screen. The logo returns you to the desktop. The account pill on the status bar opens broker tools and settings for this HUB install. You get this layout in the standalone app and in a desktop browser. A phone keeps a full-width bar and leaves these saved preferences unchanged.

### Logo and the account pill

Click the Coreflux logo to show the desktop. Every open window minimizes. The logo hides and returns together with the status bar.

The account pill shows your display name while you are connected, and **Disconnected** when you are not. Open it for the sections below.

| Section | What you open |
| - | - |
| **Broker** | **Connected Clients**, **Broker Settings**, **User Management**, **Command Console**, and **Broker Logs**. This section appears when you have system access on the broker host. **Broker Settings** opens [System Configuration](/hub/system/configuration). |
| **Hub** | **Themes** and **Hub Settings**. This section stays available without system access on the broker host, including an anonymous sign-in. These choices stay on this HUB install. |
| **Help** | **Documentation**, **LoT Templates**, **What's New**, **Send Feedback**, **About**, and **Walkthroughs**. |

**Switch user** appears when the current connection has more than one identity. **Switch broker** appears when this HUB has another saved connection. **Log out** ends the session. See [Connections Manager](/hub/connections) for identities and saved connections.

### First-run walkthroughs

The first time you open the HUB, a Hub tour walks the desktop. The first time you open an app, a short tour of that app runs. **Help → Walkthroughs** replays a tour, and the same menu offers **Mark all walkthroughs done** and **Reset all walkthroughs**. Whether you have already seen a tour is stored for this browser profile, or for this desktop install.

### Hub Settings

Open the account pill, choose **Hub**, then **Hub Settings**. The window configures this HUB install, and you can open it without system access on the broker host. Changes apply as you make them.

| Section | What you set |
| - | - |
| **Profile** | A **Default** or **Optimized** preset for the sections below |
| **Desktop** | Dock position, dock auto-hide, and status-bar auto-hide. A phone leaves the saved values unchanged |
| **Diagnostics** | Memory and CPU for this HUB, and **Prune now** to drop idle topics from the local cache |
| **MQTT store** | How many topics, and how much history, the HUB keeps in memory |
| **Subscriptions** | Which topics Data Viewer and UNS Viewer subscribe to |
| **Viewers** | How often UNS Viewer and LoT Flow refresh, and whether they pause while minimized or while the HUB is in the background |
| **Look & motion** | **Performance mode**, and whether video wallpapers keep playing |

### Dock and status bar

Right-click the dock bar — the strip behind the icons — to set its layout. Right-click an app icon to open that window's own menu.

| Dock | Choices | Default |
| - | - | - |
| **Position** | **Bottom**, **Left**, **Right** | **Bottom** |
| **Auto-hide** | **Always**, **Never**, **When fullscreen** | **When fullscreen** |

**Left** and **Right** turn the dock into a vertical column. The dock draws over your windows, and the workspace keeps its full size.

Right-click the status bar to set when it hides.

| Status bar | Choices | Default |
| - | - | - |
| **Auto-hide** | **Always**, **Never**, **When fullscreen** | **Never** |

The same three controls are under **Hub Settings → Desktop**. The HUB saves them for this install. When a bar is hidden, move the pointer to its edge to bring it back.

**When fullscreen** hides that bar while a window is fullscreen. A zoomed window leaves the dock and status bar where they are.

### Zoom and fullscreen

| Gesture | What happens |
| - | - |
| Double-click the title bar | The window zooms to fill the area under the status bar. |
| Maximize, with status-bar auto-hide **Never** | The window zooms, the same as a double-click. **Never** is the default, so the status bar stays on screen. |
| Maximize, with status-bar auto-hide **Always** or **When fullscreen** | The window fills the screen. The dock and status bar then follow their own auto-hide settings. **Escape** restores the previous size. Move the pointer to the top edge to reveal the title bar and the status bar together. |

A dock set to **Never** stays on screen during fullscreen. **When fullscreen** on the dock hides the dock only in that state.

***

## Next Steps

> **[Installation](/latest/quick-start/installation)**
>
> Run the HUB with Docker, Compose, or the desktop app — then connect from New Connection.

> **[Connections Manager](/hub/connections)**
>
> Save multiple brokers, secure them with TLS, and switch between them.

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Subscribe to topics and publish messages from the browser.


# Connector Configuration
Source: https://docs.coreflux.org/hub/routes/configuration

Edit connector configuration, events, mappings, and tags in Visual or LoT mode

![Coreflux HUB Connector Configuration panel showing Visual Mode and LoT Mode toggle with configuration, events, and mappings tabs](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-configuration.gif?s=d642fb924e3ae9df150f67ca8925cbc2)

Connector Configuration panel in the Coreflux HUB — edit settings, events, mappings, and tags in Visual or LoT mode

## Why Configure Connectors in the Coreflux HUB?

You need to adjust connector settings—connection parameters, events, mappings, and tags—without editing files or publishing MQTT commands. The Connector Configuration in the HUB lets you edit connectors with a form-based Visual Mode or switch to LoT Mode to modify the raw LoT code by hand.

## When to Use It

* **Updating connection settings** — Change IP, port, credentials, or other config fields
* **Adding events or mappings** — Extend a connector with new events, mappings, or tags
* **Switching modes** — Use Visual Mode for guided editing or LoT Mode for full control

For an overview of how to add connectors, select connector types, and use templates, see [Connectors Overview](/hub/routes/overview).

***

## Visual Mode vs LoT Mode

| Mode | Best For |
| - | - |
| **Visual Mode** | Form-based editing with add/remove fields, modals, and validation |
| **LoT Mode** | Direct LoT code editing for power users who prefer hand-editing |

Toggle between modes using the **Visual Mode** / **LoT Mode** toggle at the top of the connector configuration panel. Changes in either mode are applied when you click **Save Changes**.

### LoT Mode

Switch to **LoT Mode** to view and edit the full connector definition as LoT code. This gives you direct control over the syntax and is useful for copying configurations or making bulk changes.

![Coreflux HUB Connector Configuration LoT source editor for SiemensS7Route showing syntax-highlighted DEFINE ROUTE SiemensS7Route WITH TYPE SIEMENS\_S7 with an S7\_CONFIG block (IP, CPU\_TYPE, RACK, SLOT), a MAPPING TestPLC block with SOURCE\_TOPIC, EVERY, and a Real TAG with ADDRESS, ADDRESS\_TYPE, and DATA\_TYPE, plus Cancel and Save Changes buttons in the bottom bar](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-lot-mode.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=da2702726190777943ddd601f5a4c751)

LoT source editor in Config: SiemensS7Route showing the full connector definition as editable LoT code with Cancel and Save Changes controls

The editor shows the keyword you wrote. A connector defined with `DEFINE CONNECTOR` keeps that spelling when you edit and save it, and one defined with `DEFINE ROUTE` keeps `DEFINE ROUTE`.

![Coreflux HUB Config: PlantArchive window open over the Connectors Manager, with the LoT tab selected showing DEFINE CONNECTOR PlantArchive WITH TYPE FILE\_STORAGE, an ADD FILE\_STORAGE\_CONFIG block with STORAGE\_DIR and FILE\_PATTERN, and an ADD EVENT StoreReading block with SOURCE\_TOPIC and DESTINATION\_TOPIC, plus Cancel and Save Changes](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/configuration/connector-lot-mode-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=c5159970c47c3e52dc9a6e5d13ce1e47)

LoT tab in Config: PlantArchive, a connector written with DEFINE CONNECTOR

### Renaming Elements

You can rename connectors, events, mappings, and tags directly from the configuration panel. Click the **pencil icon** next to any element name to turn it into an editable text field, type the new name, and press **Enter** to confirm. A **Renamed** badge appears briefly to confirm the change.

This works the same way for all element types:

* **Connector name** — Displayed at the top of the configuration panel
* **Event name** — Displayed in the Events tab header for each event
* **Mapping name** — Displayed in the Mappings tab header for each mapping
* **Tag name** — Displayed in the tag header within a mapping

> [!NOTE]
>
> Renaming takes effect when you click **Save Changes**. If you cancel without saving, the original names are restored.

***

## Configuration Tab

The **Configuration** tab shows the connector's connection and protocol settings (e.g., `S7_CONFIG`, `SQL_CONFIG`, `MODBUS_CONFIG`). Each field displays its name, whether it is required or optional, its data type, and a description.

![Coreflux HUB Connector Configuration tab for Connector: SiemensS7Route with Configuration, Events, and Mappings tabs; Configuration is selected showing the S7 Configuration section with four fields — IP required string set to 127.0.0.1, CPU\_TYPE string set to S71200, RACK int set to 0, and SLOT int set to 1 — plus an + Add Field button and Cancel and Save Changes buttons at the bottom](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-config-tab.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=78d5d3fc3a7628636fdee3aa03e74aee)

Configuration tab for Connector: SiemensS7Route showing the S7 Configuration fields with types, descriptions, and current values

* **View fields** — See all configuration fields with their types and descriptions
* **Edit field** — Change values in the input fields
* **Add field** — Click **+ Add Field** to add optional fields from a list of available parameters
* **Delete field** — Use the delete icon on a field to remove it

### Adding a Configuration Field

Click **+ Add Field** to open the **Add Configuration Field** modal. This shows all optional fields available for the connector type, along with their data types and descriptions.

![Coreflux HUB Add Configuration Field modal prompting to select an optional field to add to the connector configuration, listing PORT int for the TCP port for S7 connection (default 102), CONNECTION\_TYPE string with four options PG, OP, S7BASIC, and S7\_BASIC (default PG), RETRY\_ATTEMPTS int for number of retry attempts (default 3), RETRY\_TIME\_SECONDS int for seconds to wait between retries (default 5), REFRESH\_TIME\_MS int for refresh time in milliseconds (default 1000), and a partially visible READ\_TIMEOUT int field](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-config-add-field.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=36ebef56014dff425241204b5189e21b)

Add Configuration Field modal listing the optional parameters available for a Siemens S7 connector

***

## Events Tab

The **Events** tab manages event definitions for the connector. Events define how the connector reacts to MQTT messages—typically by reading from or writing to the connected device or service.

![Coreflux HUB Connector Configuration Events tab for Connector: SiemensS7Route showing Event ONDEMANDREAD with 3 fields — SOURCE\_TOPIC string set to s7sim/event/read, DESTINATION\_TOPIC string set to s7sim/event/read/result, and QUERY string containing a JSON S7 operation with operation, address, data\_type, and count placeholders — plus + Add Event and + Add Field controls and Cancel and Save Changes buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-events-tab.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=ff69ae3999f7ff6cccaf9dbf965fde0d)

Events tab for Connector: SiemensS7Route showing the OnDemandRead event with SOURCE\_TOPIC, DESTINATION\_TOPIC, and QUERY fields

* **Add Event** — Click **+ Add Event** to create a new event with a name and fields
* **Rename event** — Click the pencil icon next to the event name to rename it
* **Edit event** — Expand an event to view and edit its fields (e.g., `SOURCE_TOPIC`, `DESTINATION_TOPIC`, `QUERY`)
* **Add field** — Use **+ Add Field** within an event to add optional fields

### Adding an Event Field

Click **+ Add Field** inside an event to open the **Add Event Field** modal. This shows the optional fields available for the event.

![Coreflux HUB Add Event Field modal prompting to select an optional field to add to the event, showing a single option DESTINATION\_TOPIC string described as MQTT topic to publish S7 results](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-events-add-field.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=280372399c9f896a6ad1ed8592ade5b5)

Add Event Field modal showing the optional DESTINATION\_TOPIC field available for the event

***

## Mappings Tab

The **Mappings** tab manages mapping definitions and tags. Mappings define periodic data polling from a connected device—reading tags at a set interval and publishing the data to MQTT topics.

![Coreflux HUB Connector Configuration Mappings tab for Connector: SiemensS7Route showing Mapping TESTPLC with Mapping Configuration (SOURCE\_TOPIC string set to plc, EVERY string set to 1 SECOND) and a Tags section containing the Real tag with ADDRESS string set to DB1.DBD28, ADDRESS\_TYPE string set to DATABLOCK, and DATA\_TYPE string set to REAL, plus + Add Mapping, + Add Field, + Add Tag, and + Field controls and Cancel and Save Changes buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-mappings-tab.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=fca2b2f2d4c4b7f2dce91c29f84dbad1)

Mappings tab for Connector: SiemensS7Route showing the TestPLC mapping with SOURCE\_TOPIC and EVERY fields and a Real tag with address and data type properties

* **Add Mapping** — Click **+ Add Mapping** to create a new mapping with a name, mapping fields, and tags
* **Rename mapping** — Click the pencil icon next to the mapping name to rename it
* **Edit mapping** — Expand a mapping to edit its configuration (e.g., `EVERY`, `SOURCE_TOPIC`) and tags
* **Add Tag** — Use **+ Add Tag** within a mapping to add tags with address, data type, and other properties

### Adding a New Mapping

Click **+ Add Mapping** to open the **Add New Mapping** modal. Enter a mapping name, then use **+ Add Field** and **+ Add Tag** to build the mapping.

![Coreflux HUB Add New Mapping modal titled Create a new mapping with optional fields and tags, showing a Mapping Name input with an e.g., MyMapping placeholder, a Mapping Fields (0) section with an + Add Field button, a Tags (0) section with an + Add Tag button and a No tags added yet placeholder, plus Cancel and Create Mapping buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-add-mapping.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=2b97467ace88ce3402d5fbd3a92a6625)

Add New Mapping modal with a name field, a mapping fields section, and a tags section, plus Cancel and Create Mapping actions

### Adding a Mapping Field

Click **+ Add Field** inside a mapping to open the **Add Mapping Field** modal. This shows the optional fields available for the mapping, such as `DESTINATION_TOPIC` and `QUERY`.

![Coreflux HUB Add Mapping Field modal prompting to select an optional field to add to the mapping, showing DESTINATION\_TOPIC string described as MQTT topic to publish polled data (legacy mode) and QUERY string described as S7 read operation in JSON format (legacy mode)](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-mapping-add-field.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6170698bccf06b927d26da081cf399c2)

Add Mapping Field modal showing the optional DESTINATION\_TOPIC and QUERY fields available for the mapping

#### Tags

Tags are defined inside mappings. Each tag represents a data point to read from the connected device. You can add, edit, rename, and remove tags and their properties (address, address type, data type, scaling, unit, etc.) from the Mappings tab. To rename a tag, click the pencil icon next to the tag name.

#### Saving and Canceling

* **Save Changes** — Applies all edits to the broker
* **Cancel** — Discards unsaved changes and closes the configuration panel

***

## Next Steps

> **[Connectors Overview](/hub/routes/overview)**
>
> Create new connectors with templates or LoT code.

> **[Connectors Monitoring](/hub/routes/monitoring)**
>
> View and export connector-specific logs and status.


# Connectors Monitoring
Source: https://docs.coreflux.org/hub/routes/monitoring

View real-time connector status and logs — monitor connection health, message counts, and export logs

![Coreflux HUB connector card titled MyS7Route with a green status dot in the top-right corner and a row of action icons at the bottom — a gear for Configuration, a monitor icon currently hovered showing a Connector Monitor tooltip, a globe for Documentation, and a trash can for Delete](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/monitoring/route-card-monitor.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6c79ac2bb8b22e0de12ec2fdc8e3b5e2)

Connector card for MyS7Route with the monitor icon highlighted and a Connector Monitor tooltip

## Why Monitor Connectors?

You need to know whether a connector is running correctly — whether it is connected, how many messages it has processed, and whether there are errors. The Monitor window gives you live status metrics and real-time logs filtered to a single connector, so you can troubleshoot without searching through broker-wide output.

## When to Use It

* **Verifying connectivity** — Confirm that a connector is connected to its target system after creation or configuration changes
* **Tracking activity** — Check message counts and error rates to validate that events and mappings are executing
* **Troubleshooting connections** — See why a connector failed to connect using status details and log entries
* **Exporting for analysis** — Download filtered logs as JSON, CSV, or LOG for offline review

***

## Accessing the Monitor

Open the Connectors Manager, click on a connector card, and select **Monitor**. The Monitor window opens with two tabs: **Status** and **Logs**.

![Coreflux HUB Connectors Manager showing how to click a connector card and select Monitor to open the monitoring window](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/monitoring/access-monitoring.gif?s=dd2b6994e11dd9a6ae6bbd6ec7dd2399)

Opening the Monitor from a connector card in the Connectors Manager

***

## Status Tab

The Status tab displays live metrics from the broker for the selected connector.

![Coreflux HUB Monitor window for the BACNET connector TwinEnergyBms with Connection Connected, Health Green, and Uptime in the header; the Status tab shows Overview cards for Connection, Health, Messages, and Errors, and an Activity Timeline with Last Activity, Last Success, and Last Error](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/monitoring/route-monitor-status-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=f61f98c5fa654e5252b651211d08faee)

Monitor window, Status tab: connection, health, and uptime in the header, then the Overview cards and the Activity Timeline

| Field | Description |
| - | - |
| **Connection** | Whether the connector is currently connected to its target |
| **Health** | Health indicator (Green, Yellow, Red) based on error rates |
| **Messages** | Total messages processed, with success and failure counts |
| **Errors** | Total and consecutive error counts |

The **Activity Timeline** shows timestamps for last activity, last success, and last error. When the connector has recent failures, a **Recent Errors** list appears below the timeline with a link to view them all in the Logs tab. Uptime is shown in the window header.

### Start and Stop

The header has a **Stop** button while the connector runs, and **Start** while it's stopped. **Stop** saves the connector with `DISABLE true`, the same as **Disable** on its card. The connector stays defined but doesn't run, and the header says so. **Start** removes the line. The button follows changes made elsewhere, such as in the LoT Editor.

![Coreflux HUB Monitor window for the FILE\_STORAGE connector FlightLog, with the header text Stopped. The connector stays defined but does not run. and a Start button, above the Status tab with Connection Disconnected, Health Red, Messages 12 with 12 ok and 0 failed, Errors 0, and the activity timeline](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/monitoring/connector-monitor-stopped-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=f6fde9f2b49338803896202dafaa6d46)

Monitor window for a stopped FILE\_STORAGE connector, with Start in the header

***

## Logs Tab

The Logs tab shows real-time log entries filtered to the selected connector.

![Coreflux HUB Monitor window for the TwinFillerPlc OPCUA connector with the Logs tab selected: ALL, Fatal, Error, WARN, and INFO level filters, a JSON format selector and export button, an ERROR entry for CheckRouteConnection, and an INFO entry for RouteCertificates](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/monitoring/route-monitor-logs-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=9ce2d08745e4011559af9873d19fdb17)

Monitor window — Logs tab with level filters, JSON format selector, and export controls

### Filter by Level

Use the filter buttons to show only certain log levels:

| Filter | Description |
| - | - |
| **ALL** | Show all log entries |
| **FATAL** | Fatal errors only |
| **ERROR** | Errors only |
| **WARN** | Warnings only |
| **INFO** | Informational messages only |

### Log Entry Fields

Each log entry displays:

| Field | Description |
| - | - |
| **Timestamp** | When the event occurred |
| **Log level** | FATAL, ERROR, WARN, or INFO |
| **Category** | Event category (e.g., Action, Event) |
| **Name** | Event or action name |
| **Outcome** | Success or failure |
| **Description** | Detailed message or structured data |

### Export

Use the export dropdown to choose a format:

* **JSON** — Structured export for parsing or integration
* **CSV** — Spreadsheet-friendly format
* **LOG** — Plain text log file

Click **Export** to download the filtered logs.

![Coreflux HUB Monitor: SiemensS7Route Logs tab displaying the three INFO ProcessCloudCLICommand entries and a Logs Exported toast in the top-right corner confirming Exported 3 logs as JSON, with level filters, JSON format selector, and export controls still visible](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/monitoring/route-logs-export.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=28d8c1b127124585efb66f1c2bbea7ec)

Exporting SiemensS7Route logs as JSON with a Logs Exported confirmation toast in the top-right corner

### Clear Logs

Use **Clear Logs** to remove displayed entries from the view. This does not affect the broker — it only clears the HUB display.

***

## Next Steps

> **[Connectors Configuration](/hub/routes/configuration)**
>
> Edit connector settings if status or logs show connection or configuration issues.

> **[Broker Logs](/hub/system/broker-logs)**
>
> View broker-wide logs for system-level troubleshooting.


# Connectors Overview
Source: https://docs.coreflux.org/hub/routes/overview

Add, configure, and monitor Connectors in the Coreflux HUB—view status, edit configuration, and inspect connector logs

![Coreflux HUB Connectors Manager with a 2 connectors count, delete and add buttons, connector cards for LegacyLogs and PlantArchive (FILE\_STORAGE), each with a red status dot and Configuration, Monitor, Documentation, and Delete icons, an Add connector card, and the status bar Connectors popover listing both connectors as Disconnected with an Open Connectors Manager link](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/routes/overview/connectors-manager-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=6b518a51578d5981f1a1dbae80dbe065)

Connectors Manager: connector cards with live connection status, configuration, and monitoring tools

## Why Use the Connectors Section?

You need to manage Connectors from the browser—add new connectors, edit configuration, check connection status, and troubleshoot with logs. The Connectors section of the Coreflux HUB lets you configure connectors with a visual editor or LoT code, view connected and disconnected connectors, and inspect connector-specific logs.

## When to Use It

* **Adding connectors** — Create connectors from templates (PostgreSQL, MongoDB, Modbus, etc.) or write LoT code directly
* **Configuring connectors** — Edit configuration, events, mappings, and tags in Visual or LoT mode
* **Monitoring** — See which connectors are connected and which are not, and view real-time status metrics
* **Troubleshooting** — View connector logs, filter by level, and export for analysis

***

## Connectors Tools

> **[Connectors Configuration](/hub/routes/configuration)**
>
> Edit connectors, view status (connected/not connected), and delete connectors.

> **[Connectors Monitoring](/hub/routes/monitoring)**
>
> View real-time status metrics and logs filtered by connector, export as JSON/CSV/LOG.

***

## Connector List and Status

The Connectors Manager displays all defined connectors as cards. Each connector card shows the connector name, type (e.g., `SIEMENS_S7`), and a **status indicator** dot in the top-right corner. The dot color tells you the current connection state at a glance:

| Color | Status |
| - | - |
| **Green** | Connected |
| **Red** | Not connected |
| **Gray** | Unknown status |
| **Yellow** | Reconnecting |

![Coreflux HUB connector card titled SiemensS7Route with the SIEMENS\_S7 type badge, a green status dot in the top-right corner indicating a connected connector, and four action icons along the bottom for configuration, monitor, documentation, and delete](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/overview/route-card-status.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=db53f51d8830d4e9a06115e91104829e)

Connector card for SiemensS7Route with a green status dot in the top-right indicating the connector is connected

Use the controls at the top to **sort** connectors by name and **filter** by type. The **Delete All** button removes all connectors, and the **Add a connector +** button opens the connector creation options.

## Connector Card Actions

Click on a connector card to open its context menu with three options:

![Coreflux HUB SiemensS7Route card with the SIEMENS\_S7 type badge and a row of four action icons at the bottom — a gear for Configuration, a monitor for Monitor, a globe for Documentation, and a trash can for Delete](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/overview/routes-card-menu.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=36825ce968d967294732d3246fca19cd)

Connector card action icons — gear for Configuration, monitor for Monitor, globe for Documentation, and trash for Delete

| Action | Description |
| - | - |
| **Configuration** | Opens the [Connectors Configuration](/hub/routes/configuration) panel to edit settings, events, mappings, and tags |
| **Monitor** | Opens the [Connectors Monitoring](/hub/routes/monitoring) window with a **Status** tab (connection, health, messages, errors) and a **Logs** tab (real-time connector logs) |
| **Documentation** | Opens the Coreflux documentation for the connector type directly inside the HUB |
| **Disable** / **Enable** | Turns the connector off or on without deleting it. See [Disable a connector](#disable-a-connector) |

### Disable a connector

**Disable** saves the connector's definition with `DISABLE true`, and **Enable** removes it. A disabled connector stays defined but doesn't run: its card is dimmed, with a grey status dot and a **Disabled** chip. No connection check runs while it's disabled.

![Coreflux HUB Connectors Manager with 3 connectors: the FILE\_STORAGE connector FlightLog dimmed with a grey status dot, a DISABLED chip, and the Enable tooltip over its power icon; the REST\_API connector FlightsTrackerApi and the LLM connector LocalOllama, used by 2 agents, both with green status dots; and an Add connector card](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/overview/connectors-manager-disabled-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=3ebddad645e53b3f870bc2c472fe7a7e)

FlightLog is disabled, with its Enable action hovered. FlightsTrackerApi and LocalOllama are enabled

The broker refuses to disable a `TYPE LLM` connector that agents still use: disable those agents first. On a broker without `DISABLE` support, the HUB changes nothing and says so. The **Start** / **Stop** button in the [Monitor window](/hub/routes/monitoring#start-and-stop) does the same thing.

### Connector Documentation

The Documentation option opens the Coreflux docs page for the connector type in an embedded viewer inside the HUB. This gives you quick access to syntax reference, configuration parameters, and examples without leaving the interface.

![Coreflux HUB embedded Docs window titled SiemensS7Route loading the Siemens S7 Connector page from docs.coreflux.org with Connectors navigation on the left, Siemens S7 Overview and Basic Syntax content in the center, and an On this page outline on the right, plus Refresh and Open in Browser controls](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/overview/route-documentation.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=55472cee084ba947719f458fbed8a658)

Embedded Docs window showing the Siemens S7 Connector page from the Coreflux documentation inside the HUB

***

## Adding a Connector

Click **Add connector** (the last card) or the **+** button in the Connectors Manager toolbar. The **New connector** window opens with everything in one place: the connector type catalog on the left and the connector editor on the right.

![Coreflux HUB New connector window with a Search 301 connector types field, All plans, Available, Community, and Licensed filters, an All categories dropdown, the Industrial Connectors list with Beckhoff ADS selected, and Configuration, Events, Mappings, and LoT tabs showing the ADS configuration fields, plus Cancel and Create Connector](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/routes/overview/new-connector-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=d47a51a6874a37a2be824bee8b490be7)

New connector window: pick a connector type on the left, then fill in its configuration, events, mappings, or LoT on the right

**1. Pick a connector type**

Use the **Search connector types...** field, the plan filter (**All plans**, **Available**, **Community**, **Licensed**), or the **All categories** list (for example **Industrial Connectors**, **Data Storage Connectors**, or **AI Connectors**) to narrow the catalog, then click a type. Types still in preview carry a **Beta** badge. The editor on the right fills in with that type's template. The AI category includes the **LLM** connector. An agent is not a connector type: add the LLM connector here, then define the agent in LoT. See [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

**2. Fill in the configuration**

The **Configuration** tab lists the type's fields with a short description each. Required fields are marked **Required**, and secrets such as passwords are masked. Use **+ Add Field** to include optional parameters.

**3. Add events and mappings**

Use the **Events** tab for actions triggered by MQTT messages (for example, a query on each message), and the **Mappings** tab for the tags or points the connector polls and publishes.

**4. Review the LoT**

The **LoT** tab shows the generated LoT definition. You can edit the definition directly there if you prefer writing LoT.

**5. Name and create**

The connector gets a generated name such as `NewBeckhoffADS_<timestamp>` at the bottom of the window. Click the pencil to rename it, then click **Create Connector** to deploy it to the broker. **Cancel** closes the window; if you have unsaved changes, the HUB asks before discarding them.

For example, a PostgreSQL connector written in the **LoT** tab looks like this (`DEFINE ROUTE` remains a supported alias):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MyPostgres WITH TYPE POSTGRESQL
  ADD SQL_CONFIG
    WITH SERVER "localhost"
    WITH PORT '5432'
    WITH DATABASE "iot_data"
    WITH USERNAME "admin"
    WITH PASSWORD "your_password"
  ADD EVENT StoreSensor
    WITH SOURCE_TOPIC "sensors/#"
    WITH QUERY "INSERT INTO readings (topic, value) VALUES ('{topic}', '{value.json}')"
```

Every supported connector type has a template in the catalog, including the [gRPC connector](/latest/lot-language/routes/streaming/grpc). See the [Connectors Overview](/latest/lot-language/routes/overview) for the full list of types and their documentation.

***

## Next Steps

> **[Connectors Configuration](/hub/routes/configuration)**
>
> Edit connectors with Visual or LoT mode.

> **[LoT Connectors](/latest/lot-language/routes/overview)**
>
> Learn connector syntax and available connector types.


# Broker Logs
Source: https://docs.coreflux.org/hub/system/broker-logs

View broker logs, filter by level and date, search, and export as JSON or LOG

![Coreflux HUB Broker Logs window with an entries count, a Level dropdown set to All, a Search logs field, From and To date pickers, refresh, download and clear icons, and a table with Level, Time, and Description showing an Info entry](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/broker-logs-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=db46094ae91877df9c37d0c2fccaf995)

Broker Logs with level filter, search, date range, and refresh, export, and clear controls

## Why Use Broker Logs?

You need to see what the broker is doing—startup messages, connection events, errors, warnings. The Broker Logs in the Coreflux HUB show broker-wide logs with filtering, search, and export so you can troubleshoot and audit broker activity.

## When to Use It

* **Troubleshooting** — Find errors or warnings related to broker startup or connections
* **Auditing** — Review broker activity over a date range
* **Exporting** — Save logs as JSON or LOG for offline analysis or support

***

## Filter by Level

Use the **All Levels** dropdown to filter logs by severity:

| Level | Description |
| - | - |
| **All Levels** | Show all log entries |
| **Information** | Informational messages |
| **Warning** | Warnings |
| **Error** | Errors |
| **Critical** | Critical failures |

## Search for Keyword

Use the **Search logs...** field to search for specific text in log messages. Enter a keyword or phrase to filter the displayed logs.

## Export

Export logs in two formats:

* **JSON** — Structured export for parsing or integration
* **LOG** — Plain text log file

Click **Export** to download the filtered logs.

## Control Refresh Rate

Use the refresh control to set how often logs update:

| Option | Description |
| - | - |
| **Sync** | Real-time updates (continuous) |
| **1s** | Refresh every 1 second |
| **5s** | Refresh every 5 seconds |
| **10s** | Refresh every 10 seconds |

## Filter by Date

Use the **From** and **To** date fields to limit logs to a specific time range. Enter dates (and optionally times) to filter the displayed entries.

## Status Indicators

The Broker Logs view shows status such as:

* **Connected** — HUB is connected to the broker
* **Logging Initialized** — Logging is active

## Clear Logs

Use **Clear** to remove displayed logs from the view. This does not affect the broker—it only clears the HUB display.

***

## Next Steps

> **[MQTT Broker](/latest/mqtt-broker/overview)**
>
> Learn about the Coreflux MQTT Broker.

> **[Introduction to LoT](/latest/lot-language/introduction)**
>
> Learn the fundamentals of the Language of Things and how it works.


# Certificates
Source: https://docs.coreflux.org/hub/system/certificates

Manage the broker's TLS server certificate, Root CA, and mTLS client trust store from the Coreflux HUB

> [!NOTE]
>
> The Certificates tab is new in HUB 2.12 and needs broker 2.22. On an older broker the tab reports **Unsupported broker version**.

## Why Use Certificates?

A broker that serves MQTTS or WSS presents a server certificate, and with mutual TLS (mTLS) it also checks the certificates clients present. The **Certificates** tab lets an administrator see and change all of that from the HUB: which certificate the broker presents, which Root CA it validates client chains against, which client certificates it trusts, and which are about to expire. You don't need shell access to the broker host.

## When to Use It

* **Renew the server certificate** before it expires, without restarting the broker.
* **Onboard a device** by trusting its client certificate.
* **Cut off a device** by revoking its certificate.
* **Watch expiry** across the server certificate, the Root CA, and every trusted client certificate.

## Open the Certificates Tab

Open **System Config** (Broker Settings) and select **Certificates**, the tab right after **General**. You need administrator rights on the broker (`AllowedSystemConfiguration`, shown as **Full Access** in [User Management](/hub/system/user-management)).

The tab has two parts: **Broker**, the identity the broker presents on its TLS ports, and **Clients**, the trust store used for mTLS.

## Broker: Server Certificate and Root CA

![Coreflux HUB Broker Settings window on the Certificates tab. Server certificate card for mqtt.acme-factory.com and Root CA card for Acme Industrial Root CA, both Valid, each with issuer, algorithm, expiry, SHA-256 fingerprint, and Download and Replace buttons, above the trust store settings](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificates-broker-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=c45fad78631e2e77f62f44f229b1d20b)

Certificates tab, Broker section: server certificate and Root CA cards

Each card shows the certificate's common name, status, issuer, algorithm, expiry date with the days left, and SHA-256 fingerprint.

* **Download** saves the public certificate as PEM (`broker-server.crt` or `broker-root-ca.crt`). Private keys are never downloaded.
* **Replace** uploads a new certificate.

### Replace the server certificate

Upload a `.pfx`/`.p12` with its passphrase, a PEM that embeds the private key, or a certificate plus a separate key file (and the key passphrase if it is encrypted). The key must be RSA or ECDSA. The broker checks that the key matches the certificate before it writes anything.

* **`ServerCertificatePath` already set and TLS running**: the broker keeps a timestamped backup of the old files (`<file>.bak-<yyyyMMddHHmmss>`), writes the new ones in the same format, and swaps them in. New TLS connections use the new certificate right away. Existing connections stay up. No restart.
* **No server certificate configured yet**: the broker writes `server.pem` to a `broker/` folder under the storage path, sets `ServerCertificatePath` to it, and asks you to restart the broker to turn TLS on.

### Replace the Root CA

Upload the CA certificate (`.crt`, `.pem`, or `.cer`) used to validate client certificate chains. The broker keeps a timestamped backup of the old file and applies the new CA to chain validation immediately. If the uploaded certificate is not marked as a CA, the broker still installs it and warns you.

## Clients: the mTLS Trust Store

![Client certificates list with Total 7, Valid 4, Expiring 2, and Expired 1, the drop zone, search and filters, and rows for energy-meter-gw, historian-01, line1-plc and line2-plc.acme-factory.com, mes-connector, packaging-robot-02, scada-gateway, and the revoked hmi-panel-03](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificates-clients-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=ed47833d5e1634e66a39228ee7fcff2d)

Certificates tab, Clients section: trust store settings and the client certificate list

### Trust store settings

| Setting | Broker field | What it does |
| - | - | - |
| **Storage path** | `ClientCertificateSourcePath` | Folder of trusted client certificates. Empty means the default: `/var/lib/coreflux/certs` on Linux and macOS, `C:\ProgramData\Coreflux\certs` on Windows. The hint under the field says whether the broker can read and write it. |
| **Expiry alert** | `CertificateExpiryThresholdDays` | Days before expiry at which a certificate counts as **Expiring**. 1 to 365, default 30. Applies to client certificates, the server certificate, and the Root CA. |
| **Require client certificates** | `ClientCertificationValidation` | TLS clients must present a trusted certificate. Takes full effect on the TLS listeners after a broker restart. |
| **Validate chain to the Root CA** | `CheckCertificateChainValidation` | Also checks that a client certificate chains to the Root CA. Off means only the trusted list is checked. Takes effect immediately. |

The broker refuses a storage path that:

* is not absolute,
* is the filesystem root or inside a system folder (for example `/etc`, `/usr`, `/proc`, `/root`, or the Windows and Program Files folders), unless it is a subfolder of `CONFIG_PATH` (see below),
* is the `CONFIG_PATH` folder itself, which holds the broker config and secrets. The error suggests a `certs` subfolder instead,
* is the folder that holds the broker's server certificate or key,
* on Linux and macOS, sits outside the allowed roots: `/var/lib`, `/opt`, `/srv`, `/data`, `/mnt`, `/media`, `/home`, `/Users`, temp folders, the default path's parent, and the folders in `COREFLUX_DATA_PATH` and `CONFIG_PATH`. Add roots with `COREFLUX_CERT_STORAGE_ROOTS` (a list separated by `:` on Linux and macOS).

A subfolder of `CONFIG_PATH` is allowed even when `CONFIG_PATH` sits under a system folder. In Docker, where `CONFIG_PATH` is `/etc/project`, `/etc/project/certs` works. This exception doesn't apply when `CONFIG_PATH` is a system folder itself: with `CONFIG_PATH=/etc`, paths under `/etc` stay refused.

Symbolic links are resolved first, so the check applies to the real folder: a link that points into a system folder, or out of `CONFIG_PATH`, is refused. If the folder doesn't exist, the broker creates it.

> [!TIP]
>
> In Docker, keep the trust store in a `certs` subfolder of the project volume, for example `/etc/project/certs`, so certificates persist with the rest of the broker data.

When the path can't be used (missing, unreadable, or read-only), the tab shows a red banner with the reason. On a non-default path, **Reset to default** puts the default back. A read-only path still lists certificates, but upload and revoke are disabled.

### Upload client certificates

Click **Upload** or drop files on the drop zone. Accepted types are `.crt`, `.pem`, `.cer`, `.der`, `.p12`, and `.pfx`, up to 10 MB each.

Private keys and CSRs are refused: `.key` and `.csr` files, and PEM files that contain only a key or a CSR. The error reads *"Private keys and CSRs are not stored in the client trust store; use Replace on the broker certificate to install a server key."* To install a server key, use **Replace** on the broker certificate.

> [!WARNING]
>
> Uploading a certificate trusts it. A client presenting it can complete mTLS as soon as the upload finishes.

* **PKCS#12 (`.p12`, `.pfx`)**: the HUB asks for the passphrase. The broker stores only the certificates, as a `.pem`, and discards the private key and the passphrase.
* **PEM with an embedded private key**: the key is discarded and only the certificate is stored. The detail view says so.
* **Duplicates**: a certificate already in the store is refused. A revoked certificate can't be uploaded again. Restore it from the `revoked/` folder on the host instead.

The broker reloads the trust store after each upload. Every change is written to the audit log.

### Find a certificate

The list shows each certificate's common name, file name, status, algorithm, and expiry. Search by common name, issuer, or file name, and filter by **All**, **Valid**, **Expiring**, or **Expired**. Select a row to open its detail: issuer, algorithm, serial, validity dates, SANs, SHA-256 fingerprint, and the file path.

![Certificate detail panel for line2-plc.acme-factory.com marked Expiring soon, showing its file path, issuer, algorithm, serial, not before, not after, SANs, and SHA-256, with Download and Revoke buttons](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificate-detail-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=3c2559eb17e4982f8db00561abeca4a6)

Certificate detail with Download and Revoke

**Download** saves certificate files only. Files holding a private key, and symbolic links, can't be downloaded.

### Revoke a certificate

Choose **Revoke** from the row menu or the detail view, then confirm. The broker moves the file to `revoked/` under the storage path and rejects new connections that present it immediately. The revocation is audit-logged. Revoked certificates stay in the list with a **Revoked** badge.

Certificates in the folder set by `ClientCertificateRevocationListPath` are also treated as revoked.

## Status Bar Alerts

![HUB status bar with a red dot and 7 Certificates; the popover lists 4 valid, 2 expiring, and 1 expired, with mes-connector expired, line2-plc and historian-01 expiring, and an Open Certificates link](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/certificates/certificates-status-bar-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=0598220ce2f9a68e8b66b932a9408251)

Status bar certificate indicator and its popover

The HUB status bar always shows a certificate count, for example **7 Certificates**, with a colored dot: red when a certificate is expired or invalid (unreadable or not yet valid) or the storage path is unavailable, yellow when one is expiring, and green when everything is valid. The server certificate and the Root CA count too. Hover the indicator to see the counts per status and the certificates that need attention. Click it, or **Open Certificates** in the popover, to open the Certificates tab filtered to the matching certificates.

The indicator reads the retained [`$SYS/Coreflux/Certificates/Summary`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary) topic.

## From MQTT

The HUB uses the admin-only [`-brokerCertificates`](/latest/mqtt-broker/commands#broker-certificates) command. You can script the same operations over `$SYS/Coreflux/Command`.

## Next Steps

> **[TLS and mTLS settings](/latest/mqtt-broker/configuration#mutual-tls-mtls)**
>
> Configure server certificates and client validation in the broker config.

> **[System Configuration](/hub/system/configuration)**
>
> The other Broker Settings tabs.


# Command Console
Source: https://docs.coreflux.org/hub/system/command-console

Execute broker commands directly from the Coreflux HUB

![Navigating to the Command Console in the Coreflux HUB by selecting System in the top navigation and clicking Command Console](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/command-console/open-command-console.gif?s=c904f3e9adcf5549f006772cc8e3e28f)

Opening the Command Console from the Coreflux HUB System menu

## Why Use the Command Console?

You need to run broker commands—add Actions, remove Connectors, or perform other operations—without connecting an external MQTT client. The Command Console lets you execute broker commands directly from the Coreflux HUB.

## When to Use It

* **Adding entities** — Send `-addAction`, `-addConnector` (or `-addRoute`), or similar commands
* **Removing entities** — Send `-removeAction`, `-removeConnector` (or `-removeRoute`), etc.
* **Other operations** — Any command supported by the broker's command topic

***

## How It Works

The Command Console sends your input to `$SYS/Coreflux/Command`. The broker replies with a JSON envelope on `$SYS/Coreflux/Command/Output`, which the HUB displays.

You do not need to:

* Subscribe to the command topic yourself
* Use an external MQTT client (for example, MQTT Explorer)
* Publish from the command line

Use `-requestId` when you send several commands in a row and need to tell the replies apart. The full command list is in [Broker Commands](/latest/mqtt-broker/commands).

![Coreflux HUB Command Console window with Connected and Output subscribed in the header, the Coreflux Command Console v1.0 banner, a timestamped Broker output JSON response and Subscribed to command output topic line, and the Enter command input with a send button](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/command-console/command-console-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=3249ddb1694a4e4df02c2066a1ad3564)

Command Console with a connected status, a broker response, and the command input at the bottom

## Entering Commands

1. In the HUB top navigation, select **System**, then **Command Console**.
2. Enter the command in the input field (e.g., `-addAction DEFINE ACTION ...`).
3. Send the command. The broker processes it and returns a result.

***

## Next Steps

> **[MQTT Broker Commands](/latest/mqtt-broker/commands)**
>
> Learn available broker commands and syntax.

> **[Broker Logs](/hub/system/broker-logs)**
>
> View command execution logs.


# System Configuration
Source: https://docs.coreflux.org/hub/system/configuration

Edit broker settings, environment variables, secrets, licenses, and the MCP Server in the Coreflux HUB

![Navigating to System Configuration in the Coreflux HUB by selecting System in the top navigation and clicking System Config](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/configuration/open-system-configuration.gif?s=ffa83aea0901586d1be5c6913918342f)

Opening System Configuration from the Coreflux HUB System menu

## Why Use System Configuration?

You need to change broker settings—ports, TLS, connection limits, or other parameters—without editing configuration files. The System Configuration in the Coreflux HUB lets you view and modify broker settings from the browser.

## When to Use It

* **Adjusting ports** — Change MQTT, TLS, or WebSocket ports
* **TLS configuration** — Enable or configure TLS for secure connections
* **Binding settings** — Control which IP addresses the broker listens on
* **License and enrollment** — Activate with a code or signed file, refresh a lease, enroll the broker in an organization. Register at [portal.coreflux.org](https://portal.coreflux.org) for a 30-day Growth-type license and to manage your fleet
* **MCP Server** — Enable the listener, restrict advertised tools, and mint client tokens
* **Other broker options** — Any configurable broker parameter exposed in the UI

> [!WARNING]
>
> Changes made here are sent to `$SYS/Coreflux/Config/New`. The broker processes these changes, and some may require a manual restart or sysadmin intervention to apply. The displayed configuration reflects `$SYS/Coreflux/Config`.

***

## Accessing System Configuration

In the HUB top navigation, select **System**, then **System Configuration**. The configuration panel shows available settings grouped by category.

## Configuration Panel

The **Broker Settings** window groups settings into tabs: **General**, **Certificates** (HUB 2.12 with broker 2.22, see [Certificates](/hub/system/certificates)), **Variables & Secrets**, **License**, and **MCP Server**. The **General** tab displays broker settings as editable form fields, organized into groups.

> [!NOTE]
>
> Dock layout, memory limits, viewer refresh, and video wallpaper belong to this HUB install. Open **Hub Settings** from the account pill. See [Desktop shell](/hub/overview#hub-settings).

![Coreflux HUB Broker Settings window with General, Variables & Secrets, License, and MCP Server tabs; the General tab shows Broker Name, MQTT, TLS, WebSocket and WebSocket TLS ports, Allow persistent sessions and Max pending messages, bind IPs, and Security toggles for Allow Anonymous Login, Full Debug Logging, and Resend Retained Topics](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/configuration/broker-settings-general-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=c1e0f8a28487a2c9d14a0092930c50f6)

Broker Settings: General tab with Identity, Network, MQTT Sessions, Binding, and Security groups

| Group | Settings |
| - | - |
| **Identity** | Broker Name |
| **Network** | MQTT Port, TLS Port, WebSocket Port, WebSocket TLS Port |
| **MQTT Sessions** | Require clean sessions, Max pending messages |
| **Binding** | MQTT Bind IP, MQTT TLS Bind IP, WebSocket Bind IP, WebSocket TLS Bind IP |

Edit values as needed and click the save button to apply changes. Use the import and export icons in the top-right of the General group to upload or download the configuration.

***

## ENV Variables & Secrets

The **ENV & Secrets** tab is where you keep reusable values out of your Actions and Connectors. Instead of typing the same database address or API key in every place that needs it, you save it once here and reference it by name. When the value changes, you update it in one spot.

> [!TIP]
>
> **Like a notebook and a vault.** ENV Variables are the notebook -- quick to read and easy to update for things like a server address. Secrets are the vault -- locked away and only used by the broker, perfect for passwords and API keys.

> [!NOTE]
>
> For advanced topics like encryption keys, Docker and Kubernetes deployment, CLI commands, and the full LoT (Language of Things) syntax, see [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env).

### ENV Variables

ENV Variables hold plain text values that anyone with access to the HUB can read. Use them for things that change between environments but aren't sensitive -- a database hostname, a port number, an API base URL, or a feature flag.

![Variables & Secrets tab in the Coreflux HUB Broker Settings window with the Variables sub-tab selected, the GET ENV hint, a NAME and VALUE table of variables, and an inline row at the bottom with e.g. DB\_HOST and e.g. postgres.example.com placeholders](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/configuration/broker-settings-variables-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=0aa4cf0e93a4d6d37fe3aeeae2c5f3e6)

Variables list in the Variables & Secrets tab, with the inline add row at the bottom

#### Adding a Variable

**1. Use the inline row**

The last row of the Variables table is always an empty add row, with `e.g. DB_HOST` and `e.g. postgres.example.com` as placeholders.

**2. Fill in the name and value**

Type a clear name like `DB_HOST` in the first field and its value, for example `postgres.example.com`, in the second.

**3. Save**

Press **Enter** or click the check mark at the end of the row. The variable is saved to the broker and shows up in the list.

#### Managing Existing Variables

Hover over any row in the list to reveal three quick actions on the right side:

| Action | What it does |
| - | - |
| **Copy value** | Copies the current value to your clipboard so you can paste it elsewhere. |
| **Edit** | Reopens the form so you can change the value. The name stays the same. |
| **Delete** | Permanently removes the variable. Anything that uses it stops finding the value. |

> [!TIP]
>
> The hint at the top of the list -- *In LoT: GET ENV "NAME" -- Drag onto a Storage card field* -- shows you how to use the variable later when you build Actions or Connectors.

### Secrets

Secrets hold sensitive values that should never be shown again after you save them. The HUB encrypts them at rest, so even an administrator looking at the list only sees dots where the value should be. Use Secrets for passwords, API keys, tokens, and any other credentials.

![Variables & Secrets tab in the Coreflux HUB Broker Settings window with the Secrets sub-tab selected, 0 secrets, the note This broker has no secrets, an inline row with e.g. API\_KEY and New value — press Enter, and the AES-256-GCM encrypted at rest notice](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/configuration/broker-settings-secrets-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=7d0be9ff0fa7a76be7926f66b1dfd1a6)

Secrets list in the Variables & Secrets tab: values are never readable again after saving

#### Adding a Secret

**1. Use the inline row**

Switch to the **Secrets** sub-tab. The last row of the table is an empty add row with `e.g. API_KEY` as the name placeholder and a hidden value field.

**2. Fill in the name and value**

Type a clear name like `API_KEY` and paste the value into the hidden field. The note below the table reminds you that values are *AES-256-GCM encrypted at rest* and *never readable again after saving*.

**3. Save**

Press **Enter**. The secret shows up in the list with its value masked.

#### Managing Existing Secrets

Hover over any row in the list to reveal two quick actions on the right side:

| Action | What it does |
| - | - |
| **Set a new value** | Opens the form so you can overwrite the secret with a new value. There is no way to view the current one. |
| **Delete** | Permanently removes the secret. Anything that uses it stops finding the value. |

> [!WARNING]
>
> Once a secret is saved or deleted its original value cannot be recovered -- not even by an administrator. If you lose a credential, set a new value or remove it and create it again with the correct value.

***

## MCP

The **MCP** tab turns the broker's [MCP Server](/latest/mqtt-broker/mcp-server) on, edits its listen settings, and mints access tokens so Cursor, Claude Code, or Claude Desktop can call broker tools as a broker user.

HUB itself is **not** an MCP client. This tab writes the `Mcp` block through the same save-and-restart path as the System tab, and runs `-createMcpToken` / `-listMcpTokens` / `-revokeMcpToken` over the command envelope.

> [!NOTE]
>
> Older brokers have no `Mcp` key in `$SYS/Coreflux/Config` and no retained `$SYS/Coreflux/MCP/Info`. The tab explains that the feature is absent and does not write a block the broker would drop. Update the broker first.

### Server

The tab shows **Enabled**, a status dot (**Listening**, **Disabled**, or **Pending restart**), the endpoint URL with a copy button, plus **Port**, **Bind IP**, and **Endpoint**.

The broker applies the `Mcp` block at **startup**. Saving **Enabled** does nothing until you restart the broker. HUB cannot restart it for you.

A bind outside loopback shows an amber note: bearer tokens cross the network in clear text, so put TLS in front. HUB does not configure TLS for this listener.

### Tools

**Expose all tools** maps to `Mcp.EnableAllTools`. When it is off, only the allow-list is advertised. The picker is seeded from the advertised Streamable HTTP catalogue (not only `$SYS/Coreflux/MCP/Tools`, which lists tools the *running* server currently exposes and can be empty). Use advertised names (`get_route_template`), not command tokens (`route_code`). Add `action_*` names with **Custom tool**.

**Token lifetime** is the default TTL in days for new tokens (`0` never expires). **Advanced** holds **Server name** and **Server version**.

### Tokens

When the server is enabled and no active token exists, the tab warns that every request is `401` while the listener stays up.

**1. Create a token**

Click **Create token**. Pick a broker user (tool calls run with that user's RBAC — prefer a least-privilege account), a name **without whitespace**, and an optional lifetime in days.

**2. Copy the value immediately**

The plaintext is returned **once**. Copy it from the dialog. HUB does not write it to the connection log, a store, or disk. Closing the dialog clears it.

**3. Paste a client snippet**

The result view offers **Claude Code** (`.mcp.json`), **Cursor** (`.cursor/mcp.json`), and **Claude Desktop** snippets. Every snippet includes `"type": "http"` and `Authorization: Bearer …`. Claude Code and Claude Desktop skip an entry that has a `url` but no `type`, with no error.

When the broker binds `0.0.0.0`, the URL on `$SYS/Coreflux/MCP/Info` is not reachable as written. HUB substitutes the host it is itself connected to; a loopback bind is used verbatim.

The token table shows name, user, created, expires, last used, and state. **Revoke** refuses clients immediately. Filter the list by user if needed.

Broker refusals (`McpTokenManagement`, unknown user, already-revoked) are shown verbatim. Timeouts say the broker did not respond — token commands use `McpTokenManagement`, not `AllowedSystemConfiguration` alone.

***

## License

The **License** tab reads the retained `$SYS/Coreflux/License` topic and sends the four broker commands: `-activateLicense`, `-loadLicense`, `-refreshLicense`, and `-enroll`. The HUB never verifies a license itself — it displays what the broker reports.

The status bar, this tab, and the fleet pills share one set of labels: **Trial**, **Trial (Growth)**, and **Licensed (Growth)**.

The broker always starts. With no license it runs as **Community**. The HUB does **not** start a trial. Register at [portal.coreflux.org](https://portal.coreflux.org) for a **30-day Growth-type license**, then paste the activation code (or drop the signed file) on this tab. Use the same portal to **manage your fleet of brokers**, and open that fleet from the HUB login card after you [sign in with a Coreflux account](/hub/account-and-fleet).

Cards, top to bottom:

| Card | What you see |
| - | - |
| **Status** | The license label (**Trial**, **Trial (Growth)**, or **Licensed (Growth)** — the plan in parentheses), plus licensed-to and expiry. An **online lease** also shows last-validated age, lease expiry, seat mode, and a **Refresh** button (`-refreshLicense`). An **offline license** shows the source the broker used. With no license the card reads **Running as Community** with the artifact and connector limits from `EffectiveLimits`. |
| **Usage** | Progress bars for **Artifacts** (Models, Actions, Scripts, Panels, Rules) and **Connectors** versus the license limit. |
| **Features** | Premium features with a check when the license unlocks them (advanced connectors, RBAC, cluster, and related gates). |
| **Activate** | A two-option switch. **Activation code** is a `CFLX-…` field and an **Activate** button (`-activateLicense`). **License file** shows the broker host's hardware fingerprint (copy button) and a drop zone that accepts `.jws`, `.license`, and `.txt` — the contents must be a signed compact JWS, which the HUB sends as `-loadLicense`. |
| **Organization enrollment** | **Enrolled**, plus the bound organization id, when `Enrollment.Enrolled` is true or `Enrollment.BoundOrg` is set. **Not enrolled** when `Enrolled` is `false`. **Enrollment pending**, with the broker's reason sentence, while enrollment is pending. **Enrollment not reported** on older payloads that only have `{ Pending, Reason }`. The `et_…` token field (`-enroll`) stays available in every state. |

> [!NOTE]
>
> `Enrollment.Pending: false` means the broker has not recorded a problem — not that it is bound to an organization. The card uses `Enrollment.Enrolled` and `Enrollment.BoundOrg` as the source of truth for **Enrolled**. Manage the fleet at [portal.coreflux.org](https://portal.coreflux.org). The token field stays available until the card shows **Enrolled**.

### Activate with a code (online)

**1. Get an activation code**

Register at [portal.coreflux.org](https://portal.coreflux.org) for a license — including a 30-day Growth-type trial. Then paste the `CFLX-…` activation code on this tab. The broker must be able to reach `https://license.coreflux.org`.

**2. Paste and activate**

On the License tab, choose **Activation code**, paste the code, and click **Activate**. Limits apply immediately — no broker restart.

**3. Confirm status**

The status card refreshes from the next retained `$SYS/Coreflux/License` payload. Use **Refresh** later to pick up a plan change without waiting for the daily lease timer.

### Install a signed file (offline)

**1. Copy the fingerprint**

On the **License file** option, copy the hardware fingerprint shown above the drop zone. Send it to Coreflux so the signed license can be bound to that broker host. If the source is `hostname+mac` (typical in containers), the fingerprint can change when the container is recreated.

**2. Drop the signed file**

Save the signed license Coreflux issued. Drop a `.jws` file (`.license` and `.txt` extensions are accepted for the same JWS text). The HUB strips wrapping whitespace and sends the token to the broker.

**3. Confirm binding**

Status should show an offline license. If the broker replies that the license file was not found and the path starts with `eyJ`, this broker is too old to accept JWS text over MQTT — update the broker, or install on the host with `--load-license`.

### Enroll in an organization

Enrollment is separate from the plan. Paste a one-shot `et_…` token. Treat it as done when the card shows **Enrolled** and the bound organization — `Enrollment.Pending` clearing is not enough. **Not enrolled** means the broker published `Enrolled: false`. **Enrollment pending** shows the broker's reason sentence. **Enrollment not reported** means this payload only has `{ Pending, Reason }` (typical of an older broker). The token field stays reachable in every state. Local users keep working while enrollment is pending; federated logins that need an org binding are refused. Manage the fleet at [portal.coreflux.org](https://portal.coreflux.org).

Full operator reference, including `GET /license` and process environment variables: [Licensing and Enrollment](/latest/mqtt-broker/licensing).

> [!WARNING]
>
> If a feature you need stays disabled after activation, the license does not include it — refresh the lease, or contact Coreflux for a different plan. A signature-valid license the broker refused to honour (`BindingOk` false or tampering detected) looks like Community until you fix the binding.

***

## Next Steps

> **[Licensing and Enrollment](/latest/mqtt-broker/licensing)**
>
> Activation codes, signed licenses, enrollment, and `GET /license`.

> **[MCP Server](/latest/mqtt-broker/mcp-server)**
>
> Enablement, endpoints, tokens, and `$SYS/Coreflux/MCP` topics.


# System Overview
Source: https://docs.coreflux.org/hub/system/overview

Broker administration, user management, command console, and broker logs

![Animated overview of the Coreflux HUB System section showing System Configuration, User Management, Command Console, and Broker Logs tools](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/system-overview.gif?s=0368e951dcbd30549346ecd0e8227094)

System section in the Coreflux HUB — broker administration, user management, command console, and logs

## Why Use the System Section?

You need to administer your broker—configure settings, manage users, run commands, and view broker logs. The System section of the Coreflux HUB provides tools for broker administration, monitoring, and debugging in one place.

## When to Use Each Tool

| Tool | Use When |
| - | - |
| **System Configuration** | Changing broker settings, connection parameters, ENV/secrets, license, or the MCP Server |
| **User management** | Creating, editing, or deleting users; managing credentials and access control |
| **Command Console** | Sending commands directly to `$SYS/Coreflux/Command` without an external MQTT client |
| **Broker Logs** | Viewing broker-wide logs, filtering by level, searching, and exporting |

***

## System Tools

> **[System Configuration](/hub/system/configuration)**
>
> Broker settings, ENV and secrets, license, and the MCP Server.

> **[User Management](/hub/system/user-management)**
>
> Create, edit, and delete users; manage credentials.

> **[Command Console](/hub/system/command-console)**
>
> Execute broker commands via the HUB.

> **[Broker Logs](/hub/system/broker-logs)**
>
> View broker logs, filter by level and date, export.

***

## Next Steps

> **[System Configuration](/hub/system/configuration)**
>
> Configure broker settings.

> **[MQTT Broker Configuration](/latest/mqtt-broker/configuration)**
>
> Learn broker configuration options.


# User Management
Source: https://docs.coreflux.org/hub/system/user-management

Create, edit, and delete broker users; manage credentials and access control

![Navigating to User Management in the Coreflux HUB by selecting System in the top navigation and clicking User Management](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/user-management/open-user-management.gif?s=eda7d906fd1b830ab2f547da307bc216)

Opening User Management from the Coreflux HUB System menu

## Why Use User Management?

You need to control who can connect to your broker—add users, set passwords, and manage access. The User Management in the Coreflux HUB lets you create, edit, and delete users without editing configuration files or using command-line tools.

## When to Use It

* **Adding users** — Create new users for devices, applications, or operators
* **Updating credentials** — Change passwords
* **Managing permissions** — Control which features each user can access
* **Removing access** — Delete users who no longer need broker access

For topic-level and group-based access control with LoT Rules, see [RBAC with LoT Rules](/latest/lot-language/rules/rbac).

***

## Accessing User Management

In the HUB top navigation, select **System**, then **User Management**. The user accounts table shows all configured users with their permissions.

![Coreflux HUB User Management window with a 1 user badge, Search users, refresh and add buttons, and a table listing root (You) with Full Access, User Management, and Log Management Enabled plus edit and change password actions, and the note Permission edits apply only after Save](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/user-management/user-management-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=8b3bcf7850921fc5d7fd9da35e59e6fa)

User Management showing the user accounts table with permission badges and action buttons

## User Permissions

Each user has permission flags. The HUB table exposes three toggles that map to broker flags:

| HUB toggle | Broker flag | Description |
| - | - | - |
| **Full Access** | `AllowedSystemConfiguration` | System configuration and broad administrative access |
| **User Management** | `AllowedUserManagement` | Create, edit, and delete other users; manage group membership via MQTT |
| **Log Management** | `AllowedLogManagement` | Access to broker logs, trace logs, and log export |

Toggle permissions on or off for each user. The `root` user has special permissions that cannot be fully modified.

### Groups

Users can belong to named groups used by LoT Rules (`USER IN GROUP`) and Visu panel sharing. Manage groups with MQTT commands (`-addUserToGroup`, `-removeUserFromGroup`, `-listUserGroups`) — see [Broker Commands](/latest/mqtt-broker/commands) and [RBAC](/latest/lot-language/rules/rbac).

## Creating a User

1. Click the **+** button in the top-right corner.
2. The **Add New User** modal opens.

![Coreflux HUB Add New User modal overlaid on the User Management window with the description Create a new user account; the user will be created with default permissions, and three input fields — Username with placeholder Enter username highlighted, Password with placeholder Enter password and a visibility toggle, and Confirm Password with placeholder Confirm password and a visibility toggle — plus Cancel and Add User buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/user-management/user-management-add-user.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=cb276e551ab3b53898123e71231083e6)

Add New User modal with Username, Password, and Confirm Password fields and a Create a new user account description

3. Enter a username and password (with confirmation).
4. Click **Add User**. The user is created with default permissions and can now connect to the broker.

## Editing a User

Toggle permission switches directly in the user table to modify access. When you change a permission, the user row shows a **Modified** badge and action buttons appear:

![Coreflux HUB User Management window with an Important Notice at the top and a System Configuration Updated banner explaining that the system user configuration has been updated while editing and offering to refresh; the User Accounts table shows root with Full Access Enabled and User Management and Log Management Disabled, and test with a Modified badge, Full Access toggled off with an Original: true note, and save, cancel, change password, and delete action icons on the right](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/user-management/user-management-modified.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=b6ac9b2093682ebed9db8383271c641c)

User Management with a modified user row and a System Configuration Updated banner, showing save, cancel, change password, and delete actions

| Action | Icon | Description |
| - | - | - |
| **Save** | Floppy disk | Save the modified permissions to the broker |
| **Cancel** | X | Revert unsaved changes |
| **Change Password** | Key | Update the user's password |
| **Delete** | Trash | Remove the user from the broker |

The header bar shows badges for **modified** users and **System Updated** status when the broker configuration changes while you are editing.

## Deleting a User

Click the delete (trash) icon next to a user and confirm the deletion. The `root` user cannot be deleted.

***

## Next Steps

> **[RBAC with LoT Rules](/latest/lot-language/rules/rbac)**
>
> Groups, permission flags, and topic access rules.

> **[MQTT Broker Configuration](/latest/mqtt-broker/configuration)**
>
> Learn about authentication and security options.


# Agent Examples
Source: https://docs.coreflux.org/latest/lot-language/agents/examples

Simple, ready-to-deploy DEFINE AGENT examples across manufacturing, energy, smart cities, smart buildings, and logistics (preview)

Preview

> [!WARNING]
>
> `DEFINE AGENT` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change.

## Why build with Agents

Whether you operate a production line, a solar substation, a city sensor network, or a cold-chain fleet, raw MQTT telemetry only tells you *what* changed — not *what to do next*. With a **LoT Agent**, you pair a language model (`TYPE LLM` connector) with explicit, scoped tool grants (`ADD TOOL`) so people and LoT Actions can ask questions, classify events, summarize operations, and trigger approved workflows right inside the broker.

> [!TIP]
>
> **Like hiring a specialist with a keycard.** The `TYPE LLM` connector is the brain, and each `DEFINE AGENT` is a specialist whose keycard (`ADD TOOL`) only opens the exact topics, actions, and connectors needed for that job.

### When to use these patterns

| Example | Pattern | Best for |
| - | - | - |
| [Core agent patterns](#core-agent-patterns) | `read_mqtt`, `write_mqtt` + `INTERACTION_TOPIC` | Chatting with live telemetry and publishing scoped reports |
| [Supervisor with specialists](#supervisor-with-specialists) | Multi-agent delegation (`WITH AGENTS`) | Coordinating domain specialists under one shared token budget |
| [Manufacturing use cases](#manufacturing-use-cases) | `CALL AGENT` + `execute_routes` | Classifying floor notes and logging quality checks to a database |
| [Energy use cases](#energy-use-cases) | Scoped advisories + fault triage | Advising solar farm dispatch and triaging EV charger faults |
| [Smart cities use cases](#smart-cities-use-cases) | Scheduled `CALL AGENT` + `execute_actions` | Publishing air quality bulletins and coordinating street lighting |
| [Smart buildings and logistics](#smart-buildings-and-logistics) | Guardrails + cold-chain excursion alerts | Running an HVAC comfort desk and protecting refrigerated cargo |
| [Intelligent Things (Things with Agents)](#intelligent-things-things-with-agents) | `DEFINE THING` + `WITH AGENT` | Stamping out equipment templates where every asset has its own scoped agent |

***

The examples below are complete and ready to deploy. Create each `DEFAULT_USER` with `-addUser`, deploy connectors with `-addConnector`, deploy agents with `-addAgent`, and deploy actions with `-addAction` (or validate first with `-validateLot`).

## Core agent patterns

Start with the two most common building blocks: a read-only chat agent running on a local Ollama model, and a reporting agent that is allowed to publish summaries to a single topic tree.

**Chat with a local agent**

Run a tools-capable Ollama model on the broker host and grant it read access to one topic tree. Create the user `line-viewer` with `-addUser` before deploying the agent:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "ollama"
        WITH BASE_URL "http://localhost:11434"
        WITH MODEL "llama3.2"

DEFINE AGENT LineWatcher
    USES LLM CONNECTOR LocalLlama
    WITH DESCRIPTION "Answers questions about line telemetry"
    WITH DEFAULT_USER "line-viewer"
    WITH INTERACTION_TOPIC "plant/watcher"
    ADD TOOL "read_mqtt"
        WITH TOPICS "lines/+/telemetry/#"
```

Publish `Is line 2 running hot?` to `plant/watcher/s1/ask`. The answer arrives on `plant/watcher/s1/response`, and each tool call appears on `$SYS/Coreflux/Agents/LineWatcher/task/s1/stream`.

**Publish a shift report**

Grant `write_mqtt` with `WITH LEVEL "write"` so the agent can publish under `reports/shift/#` and nowhere else:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Claude WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "anthropic"
        WITH MODEL "claude-sonnet-5-5"
        WITH API_KEY GET SECRET "ANTHROPIC_API_KEY"

DEFINE AGENT ShiftReporter
    USES LLM CONNECTOR Claude
    WITH DESCRIPTION "Writes the end-of-shift report"
    WITH DEFAULT_USER "report-writer"
    WITH INTERACTION_TOPIC "plant/reporter"
    ADD TOOL "read_mqtt"
        WITH TOPICS "alarms/#, lines/+/counters/#"
    ADD TOOL "write_mqtt"
        WITH TOPICS "reports/shift/#"
        WITH LEVEL "write"
```

A publish to `reports/shift/2026-10-22` succeeds when `report-writer` has publish permission there. Any attempt to publish to `lines/3/cmd` is refused as `out_of_scope` on the task stream.

***

## Supervisor with specialists

Instead of giving one agent every topic in the plant, split the work across focused specialists and let a supervisor delegate with `WITH AGENTS`. All agents share one `TYPE LLM` connector and one root task token budget:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gpt6 WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"

DEFINE AGENT AlertAnalyst
    USES LLM CONNECTOR Gpt6
    WITH DESCRIPTION "Explains active alarms from recent history"
    WITH DEFAULT_USER "alarm-viewer"
    WITH MEMORY "none"
    ADD TOOL "read_mqtt"
        WITH TOPICS "alarms/#"

DEFINE AGENT MaintenancePlanner
    USES LLM CONNECTOR Gpt6
    WITH DESCRIPTION "Reads the maintenance schedule and open work orders"
    WITH DEFAULT_USER "maint-viewer"
    ADD TOOL "read_mqtt"
        WITH TOPICS "maintenance/#"

DEFINE AGENT ShiftSupervisor
    USES LLM CONNECTOR Gpt6
    WITH DESCRIPTION "Prepares the shift briefing with specialist input"
    WITH DEFAULT_USER "shift-ops"
    WITH AGENTS "AlertAnalyst, MaintenancePlanner"
    WITH MAX_TOKENS 80000
    WITH INTERACTION_TOPIC "plant/supervisor"
    ADD TOOL "read_lot"
```

When an operator asks a question on `plant/supervisor/s1/ask`, `ShiftSupervisor` can delegate to `AlertAnalyst` and `MaintenancePlanner`. Every tool call in the delegation tree still authorizes against the user who started the chain:

| Agent | Role | Tool grants | Memory |
| - | - | - | - |
| `AlertAnalyst` | Explains alarm history | `read_mqtt` on `alarms/#` | `none` (stateless) |
| `MaintenancePlanner` | Checks schedules and work orders | `read_mqtt` on `maintenance/#` | `individual` (default) |
| `ShiftSupervisor` | Coordinates both specialists | `read_lot` + delegates to both peers | `individual` (default) |

***

## Manufacturing use cases

On the shop floor, agents can classify unstructured operator notes automatically from LoT Actions or log structured quality checks through a database connector.

**Classify operator notes**

Use a stateless agent (`WITH MEMORY "none"`) and `CALL AGENT` inside an Action to label every floor note as `safety`, `quality`, or `maintenance`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "ollama"
        WITH BASE_URL "http://localhost:11434"
        WITH MODEL "llama3.2"

DEFINE AGENT NoteClassifier
    USES LLM CONNECTOR LocalLlama
    WITH DESCRIPTION "Labels operator shift notes by category"
    WITH DEFAULT_USER "agent-svc"
    WITH SYSTEM_PROMPT "Classify the operator note with one word: safety, quality, or maintenance."
    WITH MEMORY "none"

DEFINE ACTION ClassifyFloorNote
ON TOPIC "factory/notes/raw" DO
    CALL AGENT "NoteClassifier.execute"
        WITH (task = PAYLOAD)
        RETURN AS {category}
    PUBLISH TOPIC "factory/notes/labeled" WITH {category}
```

Publishing `"Guard door sensor on press 2 is loose"` to `factory/notes/raw` runs `NoteClassifier` without storing conversation history and publishes `"safety"` to `factory/notes/labeled`.

**Log quality inspections**

Grant `execute_routes` on a single connector event (`QualityDB.InsertCheck`) so an inspector can ask the agent to check live batch tolerances and record the result in PostgreSQL:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR QualityDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER GET ENV "PG_HOST"
        WITH PORT 5432
        WITH DATABASE "manufacturing"
        WITH USERNAME GET ENV "PG_USER"
        WITH PASSWORD GET SECRET "PG_PASSWORD"
    ADD EVENT InsertCheck
        WITH SOURCE_TOPIC "factory/quality/db/insert"
        WITH DESTINATION_TOPIC "factory/quality/db/result"
        WITH QUERY "INSERT INTO quality_checks (notes, created_at) VALUES ('{payload}', NOW())"

DEFINE CONNECTOR Claude WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "anthropic"
        WITH MODEL "claude-sonnet-5-5"
        WITH API_KEY GET SECRET "ANTHROPIC_API_KEY"

DEFINE AGENT QualityInspector
    USES LLM CONNECTOR Claude
    WITH DESCRIPTION "Reviews batch measurements and logs quality checks"
    WITH DEFAULT_USER "quality-ops"
    WITH INTERACTION_TOPIC "factory/quality/assistant"
    ADD TOOL "read_mqtt"
        WITH TOPICS "factory/quality/batches/#"
    ADD TOOL "execute_routes"
        WITH TARGET "QualityDB.InsertCheck"
        WITH LEVEL "write"
```

`QualityInspector` can trigger `QualityDB.InsertCheck`, while any other event on `QualityDB` (such as a delete or schema query) remains `out_of_scope`.

***

## Energy use cases

Power generation sites and EV charging hubs use agents to summarize inverter telemetry for dispatchers and translate raw charger fault codes into field instructions.

**Solar farm advisor**

Let grid operators query live solar inverter output and grid frequency under `grid/solar/#`, and allow the agent to publish curtailment advisories under `grid/solar/advisories/#`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gpt6 WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"

DEFINE AGENT SolarAdvisor
    USES LLM CONNECTOR Gpt6
    WITH DESCRIPTION "Monitors solar inverters and publishes dispatch advisories"
    WITH DEFAULT_USER "grid-ops"
    WITH SYSTEM_PROMPT "Check inverter power_kw and frequency_hz topics. Flag any inverter below 49.8 Hz or underperforming its peers."
    WITH INTERACTION_TOPIC "grid/solar/advisor"
    ADD TOOL "read_mqtt"
        WITH TOPICS "grid/solar/+/telemetry/#, grid/solar/+/alarm"
    ADD TOOL "write_mqtt"
        WITH TOPICS "grid/solar/advisories/#"
        WITH LEVEL "write"
```

| Topic pattern | Access | Purpose |
| - | - | - |
| `grid/solar/advisor/<session>/ask` | Inbound chat | Grid operators ask about site generation or alarms |
| `grid/solar/+/telemetry/#` | `read_mqtt` | Agent reads live power and frequency per inverter |
| `grid/solar/advisories/#` | `write_mqtt` (`write`) | Agent publishes dispatch or curtailment notes |

**EV charging fault triage**

When an EV charging bay reports a fault on `chargers/+/fault`, an Action calls a stateless technician agent to read the bay's session telemetry and publish a three-step troubleshooting note:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Claude WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "anthropic"
        WITH MODEL "claude-sonnet-5-5"
        WITH API_KEY GET SECRET "ANTHROPIC_API_KEY"

DEFINE AGENT ChargerTech
    USES LLM CONNECTOR Claude
    WITH DESCRIPTION "Triages EV charger faults with live bay telemetry"
    WITH DEFAULT_USER "charger-ops"
    WITH SYSTEM_PROMPT "Read the bay session topic and explain the fault in 3 short steps: cause, remote check, and whether to dispatch a technician."
    WITH MEMORY "none"
    ADD TOOL "read_mqtt"
        WITH TOPICS "chargers/+/session, chargers/+/alarm"

DEFINE ACTION TriageChargerFault
ON TOPIC "chargers/+/fault" DO
    SET "bay" WITH TOPIC POSITION 2
    CALL AGENT "ChargerTech.execute"
        WITH (task = "Bay " + {bay} + " reported fault: " + PAYLOAD)
        RETURN AS {steps}
    PUBLISH TOPIC "chargers/" + {bay} + "/triage" WITH {steps}
```

Publishing `"OCPP_ERR_OVERCURRENT"` to `chargers/bay3/fault` reads `chargers/bay3/session` and publishes the triage steps to `chargers/bay3/triage`.

***

## Smart cities use cases

Municipal teams use agents to turn sensor networks into plain-language public bulletins and to coordinate district infrastructure such as street lighting.

**Urban air quality bulletin**

Run a scheduled Action every hour that asks `AirQualityReporter` to read city-wide `PM2.5` and `NO2` stations and publish a short bulletin for school zones and public dashboards:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gpt6 WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"

DEFINE AGENT AirQualityReporter
    USES LLM CONNECTOR Gpt6
    WITH DESCRIPTION "Summarizes urban air quality readings into public bulletins"
    WITH DEFAULT_USER "city-env"
    WITH SYSTEM_PROMPT "Read all station readings under city/air/. Summarize PM2.5 and NO2 levels in 3 bullet points, highlighting any school_zone alerts."
    WITH MEMORY "none"
    ADD TOOL "read_mqtt"
        WITH TOPICS "city/air/#"

DEFINE ACTION HourlyAirBulletin
ON EVERY 1 HOURS DO
    CALL AGENT "AirQualityReporter.execute"
        WITH (task = "Write the hourly city air quality bulletin from live station topics.")
        RETURN AS {bulletin}
    PUBLISH TOPIC "city/bulletins/air" WITH {bulletin}
```

Every hour, `HourlyAirBulletin` publishes a fresh summary to `city/bulletins/air` without requiring an open chat session.

**District lighting coordinator**

Grant `execute_actions` on a specific fallback action (`EnableStormLighting`) so a city operations desk can inspect ambient `lux` sensors and switch an entire district to full brightness during severe weather:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION EnableStormLighting
ON TOPIC "city/lights/downtown/storm_override" DO
    PUBLISH TOPIC "city/lights/downtown/main_st/brightness" WITH 100
    PUBLISH TOPIC "city/lights/downtown/park_ave/brightness" WITH 100

DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "ollama"
        WITH BASE_URL "http://localhost:11434"
        WITH MODEL "llama3.2"

DEFINE AGENT LightingCoordinator
    USES LLM CONNECTOR LocalLlama
    WITH DESCRIPTION "Monitors district street lights and triggers storm lighting"
    WITH DEFAULT_USER "lighting-ops"
    WITH GUARDRAILS "Only run EnableStormLighting when ambient lux is below 25 or a weather alert is active."
    WITH INTERACTION_TOPIC "city/lights/desk"
    ADD TOOL "read_mqtt"
        WITH TOPICS "city/lights/downtown/#, city/weather/alerts"
    ADD TOOL "execute_actions"
        WITH TARGET "EnableStormLighting"
        WITH LEVEL "write"
```

`LightingCoordinator` can read `city/lights/downtown/#` and invoke `EnableStormLighting`, but cannot run any other action on the broker.

***

## Smart buildings and logistics

Facility managers and logistics teams use agents to balance occupant comfort with energy targets and to protect temperature-sensitive cargo in transit.

**Building HVAC comfort desk**

Let facility staff ask questions about floor temperatures and CO2 levels, and allow the agent to publish setpoint recommendations within safe guardrails:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Claude WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "anthropic"
        WITH MODEL "claude-sonnet-5-5"
        WITH API_KEY GET SECRET "ANTHROPIC_API_KEY"

DEFINE AGENT ComfortDesk
    USES LLM CONNECTOR Claude
    WITH DESCRIPTION "Advises facility managers on HVAC comfort and CO2 levels"
    WITH DEFAULT_USER "facilities-ops"
    WITH SYSTEM_PROMPT "You assist building operators. Check zone temperature, humidity, and CO2 before recommending a setpoint."
    WITH GUARDRAILS "Never recommend a temperature setpoint below 19 C or above 24 C."
    WITH INTERACTION_TOPIC "building/hvac/desk"
    ADD TOOL "read_mqtt"
        WITH TOPICS "building/zones/+/telemetry/#, building/chillers/#"
    ADD TOOL "write_mqtt"
        WITH TOPICS "building/hvac/recommendations/#"
        WITH LEVEL "write"
```

Note that `WITH GUARDRAILS` steers the model's recommendations, while `ADD TOOL "write_mqtt"` enforces that the agent can only publish to `building/hvac/recommendations/#` — never directly to physical damper or chiller command topics.

**Cold-chain fleet monitor**

When a refrigerated truck reports a temperature excursion on `fleet/+/excursion`, an Action calls `ColdChainAnalyst` with `session_id` set to the truck ID so repeated alerts on the same vehicle share conversation context:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gpt6 WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"

DEFINE AGENT ColdChainAnalyst
    USES LLM CONNECTOR Gpt6
    WITH DESCRIPTION "Assesses cold-chain temperature excursions for refrigerated trucks"
    WITH DEFAULT_USER "fleet-ops"
    WITH SYSTEM_PROMPT "Check the truck reefer temperature, door status, and ETA. State whether cargo is at risk and the next action for dispatch."
    ADD TOOL "read_mqtt"
        WITH TOPICS "fleet/+/telemetry/#"

DEFINE ACTION AssessExcursion
ON TOPIC "fleet/+/excursion" DO
    SET "truckId" WITH TOPIC POSITION 2
    CALL AGENT "ColdChainAnalyst.execute"
        WITH (task = "Excursion on " + {truckId} + ": " + PAYLOAD, session_id = {truckId})
        RETURN AS {assessment}
    PUBLISH TOPIC "fleet/" + {truckId} + "/assessment" WITH {assessment}
```

Because `ColdChainAnalyst` uses the default `MEMORY "individual"` and `AssessExcursion` passes `session_id = {truckId}`, each truck gets its own ongoing session history across multiple excursion alerts.

***

## Intelligent Things (Things with Agents)

When you have repeated physical assets that each need their own AI assistant, embed `WITH AGENT` inside a [`DEFINE THING TEMPLATE`](/latest/lot-language/things/examples#intelligent-things). Every Thing instance automatically gets an agent scoped to its own topic path (`{{path}}/#`), and a parent station can delegate to its child assets' agents using relative paths (`p1.Assistant, p2.Assistant`):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantLLM WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"

DEFINE THING TEMPLATE SmartPump
    WITH PARAM llm AS CONNECTOR
    WITH PARAM agentUser
    WITH AGENT Assistant
        USES LLM CONNECTOR {{llm}}
        WITH DEFAULT_USER "{{agentUser}}"
        WITH INTERACTION_TOPIC "{{path}}/assistant"
        ADD TOOL "read_mqtt"
            WITH TOPICS "{{path}}/#"
    WITH ACTION DiagnoseAlarm
    ON TOPIC "{{path}}/alarm" DO
        CALL AGENT "Assistant.execute"
            WITH (task = "Pump {{thing}} alarm: " + PAYLOAD)
            RETURN AS {advice}
        PUBLISH TOPIC "{{path}}/advice" WITH {advice}

DEFINE THING TEMPLATE SmartStation
    WITH PARAM llm AS CONNECTOR
    WITH PARAM agentUser
    WITH THING p1 OF SmartPump
    WITH THING p2 OF SmartPump
    WITH AGENT Supervisor
        USES LLM CONNECTOR {{llm}}
        WITH DEFAULT_USER "{{agentUser}}"
        WITH AGENTS "p1.Assistant, p2.Assistant"
        WITH INTERACTION_TOPIC "{{path}}/supervisor"
        ADD TOOL "read_mqtt"
            WITH TOPICS "{{path}}/#"

DEFINE THING north OF SmartStation
    WITH PARAM path "plant/north"
    WITH PARAM llm "PlantLLM"
    WITH PARAM agentUser "agent-north"
```

Deploying `PlantLLM` with `-addConnector` and the `DEFINE THING` blocks with `-addThing` expands `north` into two pump assistants (`north_p1_Assistant`, `north_p2_Assistant`), two diagnostic actions (`north_p1_DiagnoseAlarm`, `north_p2_DiagnoseAlarm`), and a station supervisor (`north_Supervisor`) that can delegate to both pumps. See [Thing Examples](/latest/lot-language/things/examples#intelligent-things) for more patterns.

***

## Verify your deployment

**1. Validate the LoT code**

Send `-validateLot <DEFINE …>` to `$SYS/Coreflux/Command` to check connector, agent, and action syntax before deploying.

**2. Deploy the LLM connector and the agent**

Send `-addConnector <DEFINE CONNECTOR …>` and `-addAgent <DEFINE AGENT …>` to `$SYS/Coreflux/Command`. Run `-listAgents` to confirm the agent status is `online`.

**3. Watch the live task stream**

Use MQTT Explorer or Coreflux HUB to subscribe to `$SYS/Coreflux/Agents/<agent>/task/+/stream` and `{INTERACTION_TOPIC}/+/response` while sending a test question to `{INTERACTION_TOPIC}/s1/ask`.

## Best practices

> **Give each agent a least-privilege DEFAULT\_USER**
>
> Every tool call checks both `ADD TOOL` scope and the permissions of the user the task runs as (plus `DEFAULT_USER`). Never use `root` as `DEFAULT_USER` — create a dedicated user with only the topic and command permissions the agent needs.

> **Use MEMORY none for one-shot classifiers and scheduled jobs**
>
> Set `WITH MEMORY "none"` on agents called by high-volume `ON TOPIC` or `ON EVERY` actions so each run is stateless and does not spend tokens resending prior turns.

> **Use ADD TOOL for hard limits and GUARDRAILS for guidance**
>
> `WITH GUARDRAILS` steers the model's reasoning, but `ADD TOOL` and RBAC are what enforce boundaries. Keep critical actuator topics outside `write_mqtt` grants until a human or deterministic LoT Action validates the output.

## Next steps

> **[Agent Syntax](/latest/lot-language/agents/syntax)**
>
> Full reference for `DEFINE AGENT` clauses, `ADD TOOL` grants, delegation, and topics.

> **[Agents Overview](/latest/lot-language/agents/overview)**
>
> Learn how agents pair with `TYPE LLM` connectors and when to use `CALL AGENT`.


# Agents Overview
Source: https://docs.coreflux.org/latest/lot-language/agents/overview

What a LoT agent is, how it relates to the TYPE LLM connector, and when to use one

Preview

> [!WARNING]
>
> `DEFINE AGENT` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change.

## What an agent is

Your broker already moves sensor data, drives equipment, and stores history. Two LoT pieces add a language model to that world.

A **`TYPE LLM` connector** sends one prompt and returns text. Actions use it for a classification, a summary, or a short conversation. A **`DEFINE AGENT`** is a named assistant that runs on that connector. It can read topics, publish, run connector events, and hand work to other agents — only where you grant it.

The connector holds the provider, the model, the key, and the price. Every agent that names it with `USES LLM CONNECTOR` picks up a change to that connector. An agent is its own LoT entity. It is deployed with `-addAgent`, and it does not appear in the connector list.

> [!TIP]
>
> **Like a phone line and the people who answer it.** The `TYPE LLM` connector is the line to the model. Each `DEFINE AGENT` is a person you hire, with a job description and a set of keys. `CALL LLM` dials the line directly. `CALL AGENT` asks a specific person to do the job.

### When to use which

* **Prompt in, text out** — a `TYPE LLM` connector and `CALL LLM` inside an Action
* **An assistant that reads or changes the broker** — `DEFINE AGENT`, then `ADD TOOL` for each thing it may touch
* **People and apps chatting over MQTT** — `WITH INTERACTION_TOPIC` on the agent
* **Hands-off work** — `CALL AGENT` from an Action on a topic or a timer
* **Several specialists** — one LLM connector, several agents, and `WITH AGENTS` for the peers a supervisor may call

Both need a **Growth or Enterprise** license, the same row as **LLM / Agent** on [Licensing](/latest/mqtt-broker/licensing#plans). On Community, `-addAgent` is refused. An agent does not consume a connector slot.

## Agents and the LLM connector

An agent never talks to a provider directly. `USES LLM CONNECTOR` names a [`TYPE LLM` connector](/latest/lot-language/routes/ai-routes#the-llm-connector), and that connector holds the provider (`ollama`, `openai`, `anthropic`, or `compatible`), the model, the key, and prices. The connector itself never calls tools. The agent adds the job description, the grants, the budgets, and the topics people and Actions use to reach it.

| | `TYPE LLM` connector | `DEFINE AGENT` |
| - | - | - |
| Deployed with | `-addConnector` | `-addAgent` |
| Listed by | `-listConnectors` | `-listAgents` |
| Called from an Action | `CALL LLM` | `CALL AGENT` |
| Calls tools | No | Only what `ADD TOOL` grants |
| Counts as a connector | Yes | No |

Agents and connectors share one namespace, so an agent can't take the name of a connector. Deploy order doesn't matter: an agent whose connector is missing waits in `error` and comes online when the connector starts.

> **[Agent syntax](/latest/lot-language/agents/syntax)**
>
> `DEFINE AGENT`, its properties, `ADD TOOL`, delegation, topics, and `CALL AGENT`.

> **[Agent examples](/latest/lot-language/agents/examples)**
>
> A chat agent, a reporting agent, and a supervisor with specialists.

***

## Best practices

> **Give every agent its own service user**
>
> `DEFAULT_USER "root"` turns every grant into whatever root can do. Create a user that can do the job and nothing wider, and name that user.

> **Keep keys on the LLM connector**
>
> `WITH API_KEY GET SECRET "OPENAI_API_KEY"`. A literal key is copied into every project export.

> **Grant the narrowest topics that do the job**
>
> `write_mqtt` on `reports/line/#` with `WITH LEVEL "write"`. A grant of `#` lets the agent publish anywhere its user can.

> **Say LEVEL write on anything the agent must do today**
>
> A writing grant without `LEVEL` is refused. Approvals are not available yet.

> **Name peers in WITH AGENTS**
>
> An undeclared peer is not offered to the model.

> **Watch the stream while you tune grants**
>
> Subscribe to `$SYS/Coreflux/Agents/<agent>/task/+/stream`. Every refusal is a `tool_result` with an `outcome`.

Guardrail text steers the model. `ADD TOOL` and RBAC are the limit. Anything the agent must never do stays outside its grants.

***

## Limits

| Limit | Default | When you hit it |
| - | - | - |
| `MAX_IN_FLIGHT` | 4 per agent | New tasks are `rejected` with `agent_busy` |
| `MAX_ITERATIONS` | 10 per run | Further tool calls are refused with `budget_exhausted` |
| `MAX_TOKENS` | 50 000 per tree | Further tool calls are refused, then the task fails with `budget_exhausted` |
| `TASK_TIMEOUT` | 600 seconds per tree | `deadline_exceeded` |
| `MAX_CHAIN_DEPTH` | 4 hops | Delegation is refused with `hop_limit` |
| Working memory | 256 sessions, 256 KiB, 40 messages | Oldest sessions and turns are dropped |

Task work runs on the agent's own pool, so a slow model does not stall other connectors.

***

## Coming from TYPE AGENT

`DEFINE CONNECTOR … WITH TYPE AGENT`, `DEFINE ROUTE … WITH TYPE AGENT`, and `ADD AGENT_CONFIG` are gone. `-addConnector` refuses the block. A connector file that still holds one is skipped at load and the log names the replacement. Nothing is migrated for you. Rewrite each one by hand.

| Old `AGENT_CONFIG` setting | Where it goes |
| - | - |
| `PROVIDER`, `BASE_URL`, `MODEL`, `API_KEY`, `TEMPERATURE`, `MAX_TOKENS` | A `TYPE LLM` connector. `MAX_TOKENS` there caps one completion |
| `SYSTEM_PROMPT`, `MAX_ITERATIONS`, `DEFAULT_USER`, `INTERACTION_TOPIC`, `DESCRIPTION` | The `DEFINE AGENT` |
| `BROKER_TOOLS`, `ENABLED_COMMANDS` | `ADD TOOL` grants. Nothing is granted by default |
| `ACTIONS` | `ADD TOOL "execute_actions"` with `WITH TARGET` for each action and `WITH LEVEL "write"` |
| `MCP_ROUTES` | Legacy. A `TYPE LLM` connector ignores it and logs a warning to use `ADD TOOL`. `-addAgent` refuses it on `DEFINE AGENT`. MCP tools are not offered to the model, and `execute_routes` cannot reach them. Write a callable action that runs `CALL MCP` and publishes the reply, grant it with `ADD TOOL "execute_actions"` (`WITH LEVEL "write"`), and read the reply topic with `read_mqtt`. See [Agents and MCP Tools](/latest/lot-language/routes/mcp-routes#agents-and-mcp-tools) |
| `MODELS`, `VECTOR_STORE`, `HISTORY_MODE` | Dropped. Working memory is per session (`WITH MEMORY`) |
| `MAX_HISTORY_*` | `WITH MAX_HISTORY_TOKENS` on the agent caps the session history it keeps |
| `INTERACTION_MODE`, `TOOL_EXECUTION_MODE`, `CONFIRM_TOPIC`, `AGENT_MODE` | Dropped. Confirmation in the broker is a later release. The HUB still asks before a write when the assistant runs in the HUB |
| `TRACE`, `TRACE_TOPIC`, `DEBUG`, `ARTIFACT_FORMAT`, `TOOL_MODE` | Dropped. Every task streams on `…/task/<id>/stream` |

Clients that published to `{InteractionTopic}/{agent}/{session}/input` and read `artifacts` or `stream` move to `{INTERACTION_TOPIC}/{session}/ask`, `…/response`, and `$SYS/Coreflux/Agents/<agent>/task/<session>/stream`. `CALL AGENT "<name>.execute"` keeps its call shape.

The old `$SYS/Coreflux/Agents/<name>/Capabilities` and `…/Metrics` topics are not published. Read the card, the status topic, and the task stream.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlannerLlm WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "anthropic"
        WITH MODEL "claude-sonnet-5-5"
        WITH API_KEY GET SECRET "ANTHROPIC_API_KEY"

DEFINE AGENT Planner
    USES LLM CONNECTOR PlannerLlm
    WITH DEFAULT_USER "agent_svc"
    WITH INTERACTION_TOPIC "factory/agent/planner"
    ADD TOOL "read_lot"
```

***

## Not available yet

`-addAgent` refuses these, with a message that names what is missing, so a setting is never silently ignored.

* `WITH LEVEL "write_confirm"` and any writing grant that omits `LEVEL`
* `AGENT_MODE "insight"` as a default, and `TOOL_EXECUTION_MODE "confirm"`. Per-request `"mode": "insight"` works today
* `WITH SKILLS`
* Shared or long-term memory (`MEMORY "shared:…"`, `WITH LONG_TERM_MEMORY`)
* Collaboration modes other than `delegate`
* `EXTERNAL_ACCESS "true"`
* `WITH OUTPUT_MODEL`
* `ADD TOOL "run_lot_once"`

***

## Next steps

> **[Creating Agents in Coreflux](/latest/quick-start/creating-agents)**
>
> Paste a site guide, a scheduled report, alert triage, or a shift handover and try them over MQTT.

> **[AI Connectors](/latest/lot-language/routes/ai-routes)**
>
> Providers, `LLM_CONFIG`, and `CALL LLM`.


# Agent Syntax
Source: https://docs.coreflux.org/latest/lot-language/agents/syntax

DEFINE AGENT reference: properties, ADD TOOL grants, WITH LEVEL write, delegation, topics, CALL AGENT, and management commands

Preview

> [!WARNING]
>
> `DEFINE AGENT` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change.

An agent runs on a `TYPE LLM` connector. See [Agents Overview](/latest/lot-language/agents/overview) for how the two fit together, and [AI Connectors](/latest/lot-language/routes/ai-routes#the-llm-connector) for the connector itself.

## Define an agent

`USES LLM CONNECTOR` is the first line of the body. `DEFAULT_USER` is required. Every other line can follow in any order. Add the block with `-addAgent`. `-addConnector` refuses an agent block.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gpt6 WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"
        WITH MAX_TOKENS 4096
        WITH PRICE_INPUT "1.25"
        WITH PRICE_OUTPUT "10"

DEFINE AGENT LineOperator
    USES LLM CONNECTOR Gpt6
    WITH DESCRIPTION "Operates production lines 1-4 and files line reports"
    WITH DEFAULT_USER "line-ops"
    WITH SYSTEM_PROMPT "You operate lines 1-4. Report every intervention."
    WITH GUARDRAILS "Never restart a line that reports an operator on the floor."
    WITH AGENTS "AlertAnalyst, ShiftSupervisor"
    WITH MAX_CHAIN_DEPTH 4
    WITH MAX_ITERATIONS 10
    WITH MAX_TOKENS 50000
    WITH TASK_TIMEOUT 600
    WITH MAX_IN_FLIGHT 4
    WITH MEMORY "individual"
    WITH INTERACTION_TOPIC "plant/operator"
    WITH HUB_VISIBLE "true"
    ADD TOOL "read_mqtt"
        WITH TOPICS "lines/#"
    ADD TOOL "write_mqtt"
        WITH TOPICS "reports/line/#"
        WITH LEVEL "write"
    ADD TOOL "read_lot"
        WITH TARGET "action, route"
    ADD TOOL "execute_routes"
        WITH TARGET "SensorDB.InsertReading"
        WITH LEVEL "write"
    ADD TOOL "execute_actions"
        WITH TARGET "RestartLineX"
        WITH LEVEL "write"
```

Create `line-ops` before you add the agent. `GUARDRAILS` is prompt text. It steers the model. Grants and permissions are what stop a tool call.

| Clause | Required | Default | Description |
| - | - | - | - |
| `USES LLM CONNECTOR <name>` | **Yes** | — | Unquoted name of a `TYPE LLM` connector. First line of the body. `USES LLM ROUTE` is still accepted as an alias |
| `WITH DEFAULT_USER` | **Yes** | — | Broker user a task runs as when no MQTT client started it. There is no implicit admin |
| `WITH DESCRIPTION` | No | `Agent <name>.` | One line on the discovery card. The HUB and peer agents read it |
| `WITH SYSTEM_PROMPT` | No | — | Persona and operating instructions |
| `WITH GUARDRAILS` | No | — | Extra prompt text. The card only records that it is set |
| `WITH AGENTS` | No | none | Comma-separated peers this agent may delegate to. A self-listing is ignored |
| `WITH AGENT_COLLAB_MODE` | No | `delegate` | Only `delegate` is accepted |
| `WITH MAX_CHAIN_DEPTH` | No | `4` | Delegation hops a chain started by this agent may take |
| `WITH MAX_ITERATIONS` | No | `10` | Tool calls per run. Each agent in a chain has its own count |
| `WITH MAX_TOKENS` | No | `50000` | Token budget for the whole tree, delegations included. The connector's `MAX_TOKENS` caps one completion |
| `WITH TASK_TIMEOUT` | No | `600` | Seconds before the task fails with `deadline_exceeded` |
| `WITH MAX_IN_FLIGHT` | No | `4` | Tasks this agent runs at once. A further MQTT task or delegation is refused as `agent_busy` |
| `WITH QUEUE_SIZE` | No | `64` | `CALL AGENT` calls from Actions that may wait when the agent is at `MAX_IN_FLIGHT`. `0` means no queue |
| `WITH QUEUE_TIMEOUT` | No | `60` | Seconds a queued `CALL AGENT` waits before it is refused as busy. `0` means do not wait |
| `WITH MAX_HISTORY_TOKENS` | No | `12000` | Estimated tokens of conversation a `MEMORY "individual"` session keeps between runs and resends to the model. Oldest turns go first. `0` keeps only the 40-message cap |
| `WITH MEMORY` | No | `individual` | `individual` keeps a conversation per session. `none` makes every task stateless |
| `WITH INTERACTION_TOPIC` | No | — | Enables `{topic}/<session>/ask`, `…/response`, and `…/cancel` |
| `WITH HUB_VISIBLE` | No | `false` | Shows the agent in the HUB chat picker. Management and status topics stay available either way |

`AGENT_MODE`, `TOOL_EXECUTION_MODE`, and `EXTERNAL_ACCESS` accept only their defaults (`agent`, `auto`, and `false`). Other values are refused at `-addAgent`. Numbers may be bare or quoted. Any value may use `GET ENV` or `GET SECRET`.

`MCP_ROUTES` is a legacy clause. `-addAgent` refuses it on `DEFINE AGENT` with a message to use `ADD TOOL`. On a `TYPE LLM` connector it is ignored with a warning. To give an agent an MCP tool, grant a callable action that runs `CALL MCP`. See [Agents and MCP Tools](/latest/lot-language/routes/mcp-routes#agents-and-mcp-tools).

> [!NOTE]
>
> **Models that reason before answering** spend part of each completion on hidden reasoning. If the connector's `MAX_TOKENS` is `1024`, the agent can get an empty answer. Set the `TYPE LLM` connector's `MAX_TOKENS` to `4096` or more for these models. The agent's own `MAX_TOKENS` is the budget for the whole tree, not one completion.

An agent that loads a large built-in skill resends that context on every model call. A panel-building run can need a `MAX_TOKENS` budget of several hundred thousand.

## Tools

Nothing is granted until `ADD TOOL` says so. Grants of the same tool are merged. A grant never adds a permission the user lacks, and a permission never widens a grant.

| Tool | Scope | Class | What it does |
| - | - | - | - |
| `read_mqtt` | `WITH TOPICS` (**required**) | read | Latest payload of known topics that match the filter, paged. A wildcard filter cuts payloads over 1,024 characters to a preview marked `payload_truncated`. The exact topic returns the whole payload |
| `write_mqtt` | `WITH TOPICS` (**required**) | write | Publishes one message to a concrete topic. Wildcards are refused |
| `read_lot` | `WITH TARGET` (optional) | read | Lists loaded LoT entities. Optional kind: `action`, `model`, `route`, `rule`, `panel`, `agent`, `python`. Or one name |
| `create_lot` | `WITH TARGET` (**required**) | write | Creates or replaces one entity from a full LoT block. Kinds: `action`, `model`, `route`, `rule`, `panel` |
| `execute_routes` | `WITH TARGET` (**required**) | write | Runs a connector event. A connector name grants every event on it. Use `<connector>.<event>` to name one |
| `execute_actions` | `WITH TARGET` (**required**) | write | Runs one LoT action |

`WITH TOPICS` is refused on tools that are not MQTT. `WITH TARGET` is refused on the MQTT tools. `+` and `#` must fill a whole topic level.

Every agent can also read a built-in LoT skill. That read changes no broker state and needs no `ADD TOOL`. The skills meant for external coding agents are also published as [Coreflux agent skills](/ai/agent-skills). Declaring skills with `WITH SKILLS` is not available yet.

> [!WARNING]
>
> A writing tool (`write_mqtt`, `create_lot`, `execute_routes`, `execute_actions`) must say `WITH LEVEL "write"`. Omitting `LEVEL` means `write_confirm`, and `-addAgent` refuses that until approvals exist. Read tools do not take `LEVEL`.

`create_lot` with `TARGET "skill"` or `"agent"` is refused. `write_mqtt` cannot publish anywhere under `$SYS/Coreflux/Agents/`. `execute_routes` refuses events on agents and events whose names start with `_`. The tool name stays `execute_routes`, also for connectors defined with `DEFINE CONNECTOR`. It runs only events that have a `SOURCE_TOPIC` or a schedule, and it does not reach MCP tools. To give an agent an MCP tool, see [Agents and MCP Tools](/latest/lot-language/routes/mcp-routes#agents-and-mcp-tools).

`execute_actions` passes an optional JSON object to the action's `INPUT` parameters. It returns the action name and a trace id, not the action's output. Have the action publish what the agent needs, and grant that topic with `read_mqtt`.

### Who a task runs as

Two checks run on every tool call. **RBAC** (`unauthorized`) asks whether this user may do it. **Scope** (`out_of_scope`) asks whether `ADD TOOL` granted it. Both the user the task runs as and the agent's `DEFAULT_USER` must be allowed. An agent never does more than its `DEFAULT_USER` may, and never more than the person who asked.

| Task started by | Authorizes as |
| - | - |
| An MQTT client on `…/task/<id>/request`, `{INTERACTION_TOPIC}/<session>/ask`, or an event source topic | That client's user (`anonymous` for an anonymous session) |
| A message the broker published (an Action `PUBLISH`, a connector writing device data) | The agent's `DEFAULT_USER` |
| `CALL AGENT` from an Action | The agent's `DEFAULT_USER` |
| Another agent, by delegation | Whoever started the chain |

Publishing to an agent's topics does not lend the publisher the agent's `DEFAULT_USER`. A cancel is honoured only from the user the task runs as.

| `outcome` on the stream | Meaning |
| - | - |
| `ok` | The tool ran |
| `unauthorized` | The user the task runs as may not do this |
| `out_of_scope` | The agent was not granted this topic or target |
| `refused` | A limit refused it (budget, deadline, busy peer, hop limit, cycle) |
| `error` | The tool ran and failed, or the model named a tool that does not exist |

For `read_mqtt`, `write_mqtt`, and `execute_routes`, a call that fails both checks reports `out_of_scope`.

### Insight mode

A request body can ask for a read-only run:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "text": "Why is line 3 slow?", "session_id": "operator-7", "mode": "insight" }
```

`"mode": "insight"` refuses every writing tool as `out_of_scope`, including inside delegated peers. This is the HUB Insight toggle. A per-agent default of insight mode is not available yet. The agent's `AGENT_MODE` stays `agent`.

***

## Delegation: WITH AGENTS

`WITH AGENTS` is the allow-list. Each registered peer is offered to the model as a delegation tool. An agent with no `WITH AGENTS` reaches no one. A peer that is not registered yet is offered once it registers.

```lot wrap focus={10} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gpt6 WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"

DEFINE AGENT ShiftSupervisor
    USES LLM CONNECTOR Gpt6
    WITH DEFAULT_USER "shift-ops"
    WITH AGENTS "AlertAnalyst, MaintenancePlanner"
    WITH MAX_TOKENS 80000
    WITH INTERACTION_TOPIC "plant/supervisor"
    ADD TOOL "read_lot"
```

Declare `AlertAnalyst` and `MaintenancePlanner` the same way, each with the grants its job needs. The whole tree shares the root task's token budget and deadline. `MAX_CHAIN_DEPTH` and cycle detection bound it. Each hop publishes a `hop` event on the caller's stream. The child runs with its own task id on the peer's stream, and every tool call in the tree authorizes as the user who started the chain.

In-process delegation needs no extra `PublishSys` rule. An explicit `DENY` on the peer's `…/task/+/request` topic for that user still refuses the hop as `unauthorized`.

Share one `TYPE LLM` connector across agents that use the same model. Changing the key or the model on the connector updates every agent that names it. Set prices once and every agent's `run_end` can report `cost`.

Match the model to the job: a local model for high-volume classification, a cloud model where the answer has to be sharper. `WITH MEMORY "none"` on a classifier so an earlier conversation cannot steer it.

***

## Agent topics

The broker publishes these topics. Reading them needs `SubscribeSys` on the path.

| Topic | Retained | Carries |
| - | - | - |
| `$SYS/Coreflux/Agents/<agent>` | yes | The `DEFINE AGENT` source |
| `$SYS/Coreflux/Agents/<agent>/card` | yes | Discovery card, schema version 1 |
| `$SYS/Coreflux/Agents/<agent>/status` | yes | `online`, `offline`, or `error`, plus `reason` |
| `$SYS/Coreflux/Agents/<agent>/task/<id>/request` | no | Inbound work. You choose `<id>` |
| `…/task/<id>/response` | no | Final answer |
| `…/task/<id>/stream` | no | Event stream, schema version 1 |
| `…/task/<id>/status` | no | `running`, `done`, `canceled`, `failed`, or `rejected` |
| `…/task/<id>/cancel` | no | Cancel this task |
| `{INTERACTION_TOPIC}/<session>/ask` | no | Chat request. The session id is the task id |
| `{INTERACTION_TOPIC}/<session>/response` | no | Chat answer |
| `{INTERACTION_TOPIC}/<session>/cancel` | no | Cancel that session |

The card includes `schemaVersion`, `name`, `description`, `status`, `llmRoute`, `provider`, `model`, `hubVisible`, `interactionTopic`, `peers`, `tools`, and `memory`. Ignore unknown fields. `read_lot` with no `TARGET` appears as an empty object. The card never carries the API key or the guardrail text.

`-removeAgent` clears the card and the status with empty retained payloads. At startup the broker also clears retained topics under `$SYS/Coreflux/Agents/` that no running or defined agent owns (skipped in a cluster), including leftovers from a removed `TYPE AGENT` connector.

### How work arrives

**Task topic.** Publish to `$SYS/Coreflux/Agents/<agent>/task/<id>/request`. Subscribe to that task's `status`, `stream`, and `response` first. Publishing under `$SYS` is default-deny, including for `root`. Without a `PublishSys` rule the publish is dropped before the agent sees it.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE AllowAskPlanner WITH PRIORITY 100 FOR PublishSys TO TOPIC "$SYS/Coreflux/Agents/Planner/task/+/request"
    IF USER IS "planner_client" THEN
        ALLOW
    ELSE
        DENY
```

Cancel needs the same rule on `…/task/+/cancel`.

**Interaction topic.** With `INTERACTION_TOPIC "plant/operator"`, publish plain text or JSON to `plant/operator/<session>/ask`. These are ordinary topics, so ordinary publish rules apply. Restrict who may subscribe to `{INTERACTION_TOPIC}/#` when answers are sensitive.

A request body is plain text, or JSON with `text`, optional `session_id`, optional `mode`, and optional `image` or `pdf` data URIs (`image/*` or `application/pdf`, at most 10 MiB decoded). A bad attachment is dropped with a broker warning and the question is still answered.

**`CALL AGENT`.** See [below](#call-an-agent-from-an-action).

Stream events are QoS 0 and not retained. Each one has `v: 1` and a `type`: `run_start`, `delta`, `tool_call`, `tool_result`, `hop`, or `run_end`. Ignore unknown types. `run_start.requestPreview` is the request text, redacted and cut at 200 characters. It is the only copy of a `CALL AGENT` task argument or a delegated child's question, because those do not publish a `…/request`. A refusal before the run starts publishes a `rejected` status and no stream events.

`…/task/<id>/status` uses `done` when the model answered, `canceled` when someone published to `…/cancel`, `failed` with a `code` such as `deadline_exceeded` or `budget_exhausted`, and `rejected` with a `code` such as `unauthorized`, `unknown_agent`, `agent_busy`, `out_of_scope`, `cycle_detected`, or `hop_limit`.

An agent on an Ollama connector can also fail with `llm_timeout`, `llm_unreachable`, `model_not_found`, or `context_overflow`. The message names the model and the URL. See [Ollama context and timeouts](/latest/lot-language/routes/ai-routes#ollama-context-and-timeouts).

### Working memory

`MEMORY "individual"` keeps one conversation per session. The session is the `/ask` topic segment, or `session_id` in a task-request body. A request with neither is stateless. A conversation belongs to the user it runs as: another user who reuses the session id starts a separate conversation.

Each agent keeps up to 256 sessions (least recently used are dropped), each at most 256 KiB and 40 messages. Memory is saved on shutdown and loaded at the next agent start. `-removeAgent` forgets that agent's sessions. A task still running when the agent stops is cancelled and its turn is not kept. `CALL AGENT "<agent>.clear_history"` forgets one of the `DEFAULT_USER`'s sessions.

Delegated children do not inherit the caller's conversation. A second question on a session whose task is still running is refused as `agent_busy`.

***

## Call an agent from an Action

`CALL AGENT` waits until the task finishes. It runs as the agent's `DEFAULT_USER`, through the same limits, status, and stream as any other task. `execute` returns the answer text, or a JSON object `{ "success": false, "status", "code", "message" }` when the task is refused or fails. `use_history` on the call is ignored. The session is the memory.

```lot wrap focus={11-16} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH MODEL "llama3.2"

DEFINE AGENT Classifier
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    WITH SYSTEM_PROMPT "Answer with one word: safety, quality or other."
    WITH MEMORY "none"

DEFINE ACTION ClassifyNote
ON TOPIC "operators/notes" DO
    CALL AGENT "Classifier.execute"
        WITH (task = PAYLOAD)
        RETURN AS {label}
    PUBLISH TOPIC "operators/notes/classified" WITH {label}
```

| Method | Arguments | Returns |
| - | - | - |
| `execute` | `task` (required), `session_id` (optional) | The answer text, or a JSON failure |
| `clear_history` | `session_id` | JSON confirming that session was cleared |

A name that is not a `DEFINE AGENT`, or an agent that exists but is `offline` or in `error`, returns `unknown_agent`. Read a failure with `GET JSON`:

```lot wrap focus={10-15} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH MODEL "llama3.2"

DEFINE AGENT Planner
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    ADD TOOL "read_lot"

DEFINE ACTION AskPlannerFailureCode
ON TOPIC "planner/ask" DO
    CALL AGENT "Planner.execute"
        WITH (task = PAYLOAD)
        RETURN AS {result}
    PUBLISH TOPIC "planner/code" WITH (GET JSON "code" IN {result} AS STRING)
```

On success `{result}` is plain text, so `code` is empty. On failure it is the JSON object above.

***

## Disable an agent

Add `DISABLE true` on its own line to keep an agent defined but not started:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE AGENT NightShift
    DISABLE true
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    ADD TOOL "read_mqtt"
        WITH TOPICS "plant/#"
```

A disabled agent stays listed and keeps its definition, but takes no tasks. `-disableAgent <name>` and `-enableAgent <name>` switch it without editing the code. In a cluster, agents are local to each node, so these two commands change only the node that receives them.

***

## Managing agents

| Command | What it does |
| - | - |
| `-addAgent <DEFINE AGENT …>` | Adds the agent, or updates an existing one in place and keeps its conversations. Refused when a connector already has that name |
| `-removeAgent <name>` | Cancels running tasks, removes the agent, clears the card and status, forgets its sessions |
| `-listAgents` | Returns `name`, `llmRoute`, `status`, and `description` for each agent |
| `-disableAgent <name>` / `-enableAgent <name>` | Redeploys the agent with `DISABLE true`, or without it. An agent already in that state is left alone |

`-addAgent` needs `AgentManagementCreation`. `-removeAgent` needs `AgentManagementRemove`. Seeded rules allow `root`, `admin`, and `AllowedSystemConfiguration`, the same gate as connectors. See [Rules syntax](/latest/lot-language/rules/syntax#entity-management).

Agents are absent from `-listConnectors`, `-checkConnectorConnection`, and `$SYS/Coreflux/Routes/`. Their source is retained on `$SYS/Coreflux/Agents/<name>`. Ask an agent on its task topic or its interaction topic. Do not publish to `$SYS/Coreflux/Routes/<agent>/Events/…/Trigger`.

`-removeConnector` and `-removeAllConnectors` refuse to remove a `TYPE LLM` connector an agent uses, and they name those agents. Point the agents at another connector, or remove them, first. To change the model, key, or provider, send `-addConnector` with the new block. The connector updates in place and its agents stay bound. They show `error` for the moment the connector restarts, then come back online.

`-loadProject` and `-loadFolder` skip a project's agents, with a warning, when the caller lacks `AgentManagementCreation`. Projects deploy agents after connectors.

***

## Troubleshooting

> **The agent stays in error**
>
> Read `$SYS/Coreflux/Agents/<agent>/status`. The usual `reason` is that the LLM connector is missing, stopped, or not a running `TYPE LLM` connector. Add or fix the connector. The agent comes online on its own.

> **-addAgent is refused**
>
> `USES LLM CONNECTOR` or `DEFAULT_USER` is missing, a writing tool has no `WITH LEVEL "write"`, a scope setting is missing, or the name is already a connector or an agent. Agents and connectors share one namespace.

> **A task publish disappears**
>
> No `PublishSys` rule for that user on `…/task/+/request`, so the broker dropped the publish. Add the rule in [How work arrives](#how-work-arrives), or use the interaction topic.

> **Tool calls are refused**
>
> `unauthorized`: grant the permission to the user the task runs as (the originator, for a delegated task). `out_of_scope`: widen `ADD TOOL`. A tool the model never calls was never granted, or the task is in insight mode.

***


# Actions & Events
Source: https://docs.coreflux.org/latest/lot-language/panels/actions-events

Reacting to clicks and value changes — publishing commands and navigating between panels.

![An operator control panel with Start and Stop Conveyor buttons and a speed setpoint field, each wired to an event handler that publishes commands](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/patterns/control-panel.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=7bf104e56761bbaae30067a2eab551dc)

A control panel in action: each control fires an ON event that publishes back to the broker

Events make a panel interactive: a click publishes a command, a field change writes a setpoint. The pattern is always `ON <EVENT> DO <ACTION>`.

> [!TIP]
>
> **Like a light switch wired to more than a light.** Flipping it (the event) can turn on the lamp, ring a bell, and log the time (the actions) — the switch doesn't care what's wired to it.

***

First the event triggers, then each action you can wire to them. The broker parses this grammar; which triggers the HUB actually dispatches, and any write-back caveats, are documented with the [input components](/hub/dashboards/components/inputs) — that catalog ships with the HUB, not the broker.

## Event triggers

| Event | Fires when |
| - | - |
| `ON CLICK DO` | Mouse click / tap |
| `ON CHANGE DO` | Value changed (`text-field`, `number-field`) |
| `ON TOGGLE DO` | Toggle state changed — see [input components](/hub/dashboards/components/inputs) for HUB write-back support |

## Actions

### Publish to a topic

The workhorse: send a command or value to any MQTT topic.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ON CLICK DO
    PUBLISH TOPIC "factory/commands/start" WITH 1
```

Literal payloads on buttons work out of the box. On `text-field` and `number-field`, use `WITH VALUE` to publish what the operator typed — see the [Input components](/hub/dashboards/components/inputs) page for full write-back examples.

### Navigate between panels

Jump to another panel by name:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ON CLICK DO
    NAVIGATE TO PANEL "Zone1Details"
```

Or return to the previous panel:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ON CLICK DO
    NAVIGATE BACK
```

See the [Navigation section in Defining a Panel](/latest/lot-language/panels/defining-panels#navigation) for a complete overview-and-detail example with screenshots.

### Wait on a button

A click can start work that finishes later, such as an agent briefing. `SET AWAIT` names the components that should show progress, and `SET AWAIT_TIMEOUT` sets how long to wait.

The button stays busy after the click. Each id in `SET AWAIT` shows a pending indicator until that component's next message. If nothing arrives in time, the panel shows a timeout note. The wait is 120 seconds when you omit `SET AWAIT_TIMEOUT`.

Ids are the names from `ADD COMPONENT`, separated by commas inside one quoted string.

This panel asks for a briefing and waits on the text that will show it:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL SiteBriefing
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Site briefing"
WITH LAYOUT "vertical"

    ADD COMPONENT "AskBrief" WITH TYPE "button"
        SET LABEL "Refresh briefing"
        SET AWAIT "Briefing"
        SET AWAIT_TIMEOUT 30
        ON CLICK DO
            PUBLISH TOPIC "site/briefing/refresh" WITH 1

    ADD COMPONENT "Briefing" WITH TYPE "text"
        BIND CONTENT TO TOPIC "site/briefing"
```

`SET AWAIT "Briefing, StatusLamp"` waits on two components. The same clauses are listed with the [button properties](/hub/dashboards/components/inputs#button).

## Common mistakes

> **The control shows data but does nothing when used**
>
> Input components don't publish by themselves — the `ON <EVENT> DO` handler does. A button without `ON CLICK DO PUBLISH ...` is a label in practice.

> **The handler runs but nothing changes on the panel**
>
> `PUBLISH` writes to the broker; the panel only reflects it if some component **binds** to that topic. Check the bound topic and the published topic match (command vs. feedback topics are often intentionally different).

## Next Steps

> **[Input & control components](/hub/dashboards/components/inputs)**
>
> The controls that fire these events, with full write-back examples.

> **[Common patterns](/hub/dashboards/patterns)**
>
> Complete panels that put events and actions to work.


# Data Binding
Source: https://docs.coreflux.org/latest/lot-language/panels/data-binding

Wiring components to live MQTT topics — JSON extraction, coercion, and formatting.

![A radial gauge displaying a live temperature value received from an MQTT topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/gauge.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=9c3c9dd97bd0c144c93478b5cfbbebb4)

A gauge made live by a single BIND line — every message on the topic moves the needle

A binding is the live wire between a component and your data. When the source changes, the widget updates — no polling, no refresh. Most "why is my widget blank?" questions are answered on this page.

> [!TIP]
>
> **Like plugging an appliance into a socket.** The widget is the appliance, the topic is the socket — once plugged in, the power (data) flows on its own.

***

Start by wiring one widget to one topic; the deeper reference — targets, coercion, JSON extraction — follows after.

## Bind a widget in 30 seconds

Pick a topic you can see updating in the [Data Viewer](/hub/mqtt/data-viewer), and point a component at it with one `BIND` line:

```lot wrap focus={10} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL SensorMonitor
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Sensor Monitor"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
```

Save, publish a number to `sensor/temperature`, and the needle moves. That one highlighted line is all a binding is: *which aspect of the widget* (`VALUE`) gets fed *from where* (`TOPIC "sensor/temperature"`).

## Where data comes from

Today, bindings read from **MQTT topics** — the widget updates on every message. Browse what's available in the [Data Viewer](/hub/mqtt/data-viewer):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
BIND VALUE TO TOPIC "sensor/temperature"
```

## Extracting from JSON payloads

Real device payloads are rarely a bare number. When the topic carries a JSON object, add `JSON_PATH` on the component to pick a field:

```lot wrap focus={3} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "EnergyDisplay" WITH TYPE "value"
    BIND VALUE TO TOPIC "machines/pump1/data"
    SET JSON_PATH "$.energy_wh"
    SET UNIT "Wh"
```

> [!TIP]
>
> Always inspect the payload in the [Data Viewer](/hub/mqtt/data-viewer) before binding — you'll see immediately whether you need `JSON_PATH`, `AS NUMBER`, or neither.

***

That covers most panels. The rest of the page is the reference: the full grammar, every bind target, and the transformation options that work today.

## Anatomy of a binding

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
BIND <TARGET> TO TOPIC "<topic>"
```

Three parts, all required:

* **Target** — which aspect of the component receives the data (`VALUE`, `STATE`, `DATA`, ...).
* **`TO TOPIC`** — both words are mandatory; the source is always an MQTT topic path.
* **Topic path** — the topic string in quotes.

## Bind targets

| Target | Used with | Description |
| - | - | - |
| `VALUE` | gauge, value, slider, chart, realtime-chart | Numeric value |
| `STATE` | indicator, toggle, switch | Boolean / state |
| `CONTENT` | text, label, alert | Text content |
| `MAX` / `MIN` | gauge, value | Dynamic range bounds |
| `COLOR` | Any | Dynamic color |
| `TITLE` | card, panel | Dynamic title |
| `LABEL` | button, toggle, text | Dynamic label |
| `DATA` | chart, table, list | Dataset |
| `VISIBLE` | Any | Show / hide |
| `SRC` | image | Dynamic source URL |

## Type coercion

If a topic publishes text but the component expects a number or boolean, append a coercion keyword to the bind line:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
BIND VALUE TO TOPIC "sensor/raw_value" AS NUMBER
BIND STATE TO TOPIC "status/text"     AS BOOLEAN
```

Validated on a live panel: a text payload `"87.5"` coerced with `AS NUMBER` displays as `87.50` on a `value` component.

## Formatting readouts

Apply units and decimal places on the **component**, not on the `BIND` line:

```lot wrap focus={4-5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "FlowRate" WITH TYPE "value"
    BIND VALUE TO TOPIC "flow/rate"
    SET UNIT "L/min"
    SET DECIMALS 1
```

`SET UNIT` and `SET DECIMALS` are documented per widget in [Display components](/hub/dashboards/components/display).

## Common mistakes

> **The widget shows nothing at all**
>
> Check the binding line word by word — these are the usual silent breakers:
>
> | Wrong (silently broken) | Correct |
> | - | - |
> | `BIND TOPIC "kpi/x"` | `BIND VALUE TO TOPIC "kpi/x"` — target missing |
> | `BIND VALUE TOPIC "kpi/x"` | `BIND VALUE TO TOPIC "kpi/x"` — `TO` missing |

> **The widget shows the raw payload instead of one field**
>
> The topic carries JSON — add `SET JSON_PATH "$.field"` to the component, as shown in [Extracting from JSON payloads](#extracting-from-json-payloads).

## Next Steps

> **[Actions & events](/latest/lot-language/panels/actions-events)**
>
> The other half of interactivity: reacting to clicks, changes, and thresholds.

> **[Display components](/hub/dashboards/components/display)**
>
> Which target each widget accepts, with rendered examples.


# Defining a Panel
Source: https://docs.coreflux.org/latest/lot-language/panels/defining-panels

Reading and writing panel definitions: structure, layouts, positioning, and lifecycle.

![The Coreflux HUB Dashboard Manager showing a panel's LoT definition next to the rendered live panel](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/manager/code-dashboard.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=29c5b64f6d927ac71385def4b80027bb)

A panel definition and its live result, side by side in the Dashboard Manager

Every dashboard is one `DEFINE PANEL` block, written in the Dashboard Manager or generated by the AI Assistant. The block names the panel, sets a few panel-wide attributes, and lists the components it contains — this page walks through each part.

> [!TIP]
>
> **Like a recipe card for a screen.** The header says what the dish is and how the table is set (title, layout); each ingredient line below adds one widget and says where its data comes from.

***

Start with the smallest complete panel, then each section below adds one concept: reading the syntax, layouts, positioning, and lifecycle.

## Panel skeleton

A panel opens with `DEFINE PANEL`, four panel-level attributes, then one or more components:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL MyPanel
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "My Panel"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "MyComponent" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        BIND VALUE TO TOPIC "sensor/temperature"
```

* The panel **name** (`MyPanel`) identifies the panel in the Dashboard Manager.
* `WITH VISIBILITY` and `WITH STATE` declare the panel's audience and lifecycle — see [Lifecycle and visibility](#lifecycle-and-visibility).
* `WITH TITLE` is the heading people see; `WITH LAYOUT` arranges the components.
* Components are added with `ADD COMPONENT "<name>" WITH TYPE "<type>"`.

> [!WARNING]
>
> **Always include `WITH VISIBILITY PUBLIC` and `WITH STATE PUBLISHED`.** A panel saved without them may not appear in the Dashboard Manager list.

## Layouts

The layout is declared on the panel header and controls how the panel's top-level components are arranged:

| Layout | Syntax | Use it for |
| - | - | - |
| Grid | `WITH LAYOUT "grid" COLUMNS 3 ROWS 2` | Most dashboards — explicit placement and spans |
| Vertical | `WITH LAYOUT "vertical"` | Simple stacked mobile/tablet views |
| Horizontal | `WITH LAYOUT "horizontal"` | Strips of KPIs on wide screens |

Each tab below arranges the same three station readouts with a different layout — only the `WITH LAYOUT` line changes:

**Grid**

Components flow into the declared columns, one cell each:

![A panel with a three-column grid layout showing temperature, humidity, and pressure readouts side by side](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/layout-grid.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d71afea1009eb61ecc9cd91d17afd351)

Grid: the three readouts fill one row of three columns

```lot wrap focus={5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL StationGrid
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Station — Grid"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "Temperature" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/temperature"
        SET UNIT "°C"

    ADD COMPONENT "Humidity" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/humidity"
        SET UNIT "%"

    ADD COMPONENT "Pressure" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/pressure"
        SET UNIT "bar"
```

**Vertical**

Components stack top to bottom, each taking the full width:

![A panel with a vertical layout showing temperature, humidity, and pressure readouts stacked full-width](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/layout-vertical.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=258274c4588ef9a57e309ab65e4779b6)

Vertical: the same readouts stacked full-width, top to bottom

```lot wrap focus={5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL StationVertical
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Station — Vertical"
WITH LAYOUT "vertical"

    ADD COMPONENT "Temperature" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/temperature"
        SET UNIT "°C"

    ADD COMPONENT "Humidity" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/humidity"
        SET UNIT "%"

    ADD COMPONENT "Pressure" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/pressure"
        SET UNIT "bar"
```

**Horizontal**

Components sit side by side in a single row:

![A panel with a horizontal layout showing temperature, humidity, and pressure readouts in a single row](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/layout-horizontal.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=6203e11369ee496dfc098575222646d9)

Horizontal: the readouts laid out as a single row strip

```lot wrap focus={5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL StationHorizontal
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Station — Horizontal"
WITH LAYOUT "horizontal"

    ADD COMPONENT "Temperature" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/temperature"
        SET UNIT "°C"

    ADD COMPONENT "Humidity" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/humidity"
        SET UNIT "%"

    ADD COMPONENT "Pressure" WITH TYPE "value"
        BIND VALUE TO TOPIC "station/pressure"
        SET UNIT "bar"
```

### Mixing layouts with cards

The panel layout positions **top-level** components. To group several widgets into one grid slot, wrap them in a [`card`](/hub/dashboards/components/containers#card): the card occupies a cell (and can span columns like any component), while its children stack inside it. This is how you mix a coarse grid with finer-grained grouping:

![A two-column dashboard with a Zone 1 card containing a temperature readout and a running indicator on the left, and a speed gauge at 64% on the right](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/mixed-layout.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=5f4f0c1b913c1e9d5910f86f2404c861)

The grid sees two cells: the Zone 1 card (stacking a readout and an indicator) and the speed gauge

```lot wrap  theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL MixedLayout
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Mixed Layout"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "ZoneCard" WITH TYPE "card"
        SET TITLE "Zone 1"

        ADD COMPONENT "ZoneTemp" WITH TYPE "value"
            BIND VALUE TO TOPIC "zone1/temperature"
            SET UNIT "°C"

        ADD COMPONENT "ZoneStatus" WITH TYPE "indicator"
            BIND STATE TO TOPIC "zone1/status"
            SET ON_VALUE "running" WITH COLOR "green"
            SET ON_VALUE "stopped" WITH COLOR "red"

    ADD COMPONENT "SpeedGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        SET UNIT "%"
        BIND VALUE TO TOPIC "zone1/conveyor/speed"
```

The grid sees two components — the card and the gauge — while the card internally stacks a readout and an indicator. Use grid position for independent widgets; use a card when components belong to the same asset and should travel together.

## Positioning components on a grid

Use `AT COLUMN x ROW y` to place a component, and `SPAN n COLUMNS` to stretch it across the grid:

![A dashboard grid with a wide chart across the top row and two gauges in the second row](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/grid-positioning.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=3ebe8d7cc1b434d02df0ca9f3e2349a9)

The resulting layout: a chart spanning the full top row with two gauges placed below it

```lot wrap focus={7,8,12,13,17,18} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL GridExample
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Grid Example"
WITH LAYOUT "grid" COLUMNS 3 ROWS 2

    ADD COMPONENT "FullWidthChart" WITH TYPE "realtime-chart"
        AT COLUMN 1 ROW 1 SPAN 3 COLUMNS
        SET LABEL "Throughput"
        BIND VALUE TO TOPIC "factory/throughput"

    ADD COMPONENT "Gauge1" WITH TYPE "gauge"
        AT COLUMN 1 ROW 2
        SET RANGE FROM 0 TO 100
        BIND VALUE TO TOPIC "sensor/1"

    ADD COMPONENT "Gauge2" WITH TYPE "gauge"
        AT COLUMN 2 ROW 2
        SET RANGE FROM 0 TO 100
        BIND VALUE TO TOPIC "sensor/2"
```

## Navigation

A dashboard doesn't have to fit on one screen. Any component with a click handler can jump to another panel with `NAVIGATE TO PANEL "<name>"`, and the target panel can return with `NAVIGATE BACK` — the classic pattern is an overview panel with a button per zone, each leading to a detail panel.

The overview panel links to the detail panel by name:

![A Zone Overview panel with a temperature readout and a Zone 1 details button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/nav-overview.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=083fc155bceb1ceba5e81015f02d0ad8)

The overview panel: a live readout next to a button that opens the detail panel

```lot wrap focus={11-14} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL NavOverview
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Zone Overview"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "Zone1Temp" WITH TYPE "value"
        BIND VALUE TO TOPIC "sensor/temperature"
        SET UNIT "°C"

    ADD COMPONENT "Zone1Details" WITH TYPE "button"
        SET LABEL "Zone 1 details"
        ON CLICK DO
            NAVIGATE TO PANEL "NavDetail"
```

The detail panel offers the way back with `NAVIGATE BACK`:

![A Zone 1 Detail panel with a temperature gauge and a Back to overview button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/nav-detail.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=ed8df5ac1b1b092b57c2e005601ca2a2)

The detail panel after clicking the button — its Back button returns to the overview

```lot wrap focus={12-15} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL NavDetail
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Zone 1 — Detail"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "DetailTemp" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"

    ADD COMPONENT "BackButton" WITH TYPE "button"
        SET LABEL "Back to overview"
        ON CLICK DO
            NAVIGATE BACK
```

Navigation is just another action — it works from buttons, cards, or anything else with an `ON CLICK` handler. The full action reference is in [Actions & Events](/latest/lot-language/panels/actions-events#navigate-between-panels).

## Lifecycle and visibility

A panel also carries lifecycle attributes:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Zone1
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Zone 1"
```

| Attribute | Values | Meaning |
| - | - | - |
| `WITH STATE` | `DRAFT` · `PUBLISHED` · `ARCHIVED` | **Draft** while building (hidden), **Published** for daily use, **Archived** to retire without deleting |
| `WITH VISIBILITY` | `PUBLIC` · `SHARED` · `PRIVATE` | Who is allowed to open the panel |

* New panels open in **Draft** — switch to `PUBLISHED` when operators should rely on the panel.
* `PUBLIC` panels are open to any connected client; `PRIVATE` restricts to the creator and admins.
* The same lifecycle is surfaced as badges in the Dashboard Manager — see [Dashboards in the HUB](/hub/dashboards/overview).

> [!NOTE]
>
> **Current HUB behaviour.** These attributes are honoured by the renderer but are not yet manageable from the HUB itself: a panel saved without explicit `WITH VISIBILITY` / `WITH STATE` values may not appear in the Dashboard Manager list at all, and the manager offers no way to view or change them outside the source text. Until that integration improves, always write both attributes explicitly in the definition.

## Markdown text

A text component shows its content as plain text. `SET MARKDOWN true` renders that content as markdown instead.

The HUB sanitizes the markdown before drawing it. Raw HTML is not rendered, images are dropped, and unsafe links are removed.

A briefing topic can carry markdown and show as formatted text:

```lot wrap focus={8} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL BriefingNote
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Briefing"
WITH LAYOUT "vertical"

    ADD COMPONENT "Briefing" WITH TYPE "text"
        SET MARKDOWN true
        BIND CONTENT TO TOPIC "site/briefing"
```

`label` is an alias of `text`, so the same clause applies there. Other text properties are on [Text / Label](/hub/dashboards/components/display#text-label).

## Common mistakes

> **A property set with WITH is silently ignored**
>
> Properties use `SET`, not `WITH`. `WITH UNIT "°C"`, `WITH RANGE 0, 100`, and `WITH DECIMALS 2` do nothing — write `SET UNIT "°C"`, `SET RANGE FROM 0 TO 100`, `SET DECIMALS 2`.

> **WITH TYPE inside a component body does nothing**
>
> Component **types** are set on the header, not in the body. `WITH TYPE "line"` inside a chart body is silently ignored — use `SET CHART_TYPE "line"` instead.

> **The panel saves but does not show up in the Dashboard Manager**
>
> Check that both `WITH VISIBILITY PUBLIC` and `WITH STATE PUBLISHED` are present — panels saved without them may not appear in the panel list.

## Next Steps

> **[Display components](/hub/dashboards/components/display)**
>
> The widgets you place inside a panel, property by property.

> **[Data binding](/latest/lot-language/panels/data-binding)**
>
> Wire each component to a topic, model, or query.


# AI Connectors and Agents
Source: https://docs.coreflux.org/latest/lot-language/routes/ai-routes

Call a language model from LoT with a TYPE LLM connector, or run a tool-using assistant with DEFINE AGENT on that connector

## A model call, or an assistant that can act

Your broker already moves sensor data, drives equipment, and stores history. Two LoT pieces add a language model to that world.

A **`TYPE LLM` connector** sends one prompt and returns text. Actions use it for a classification, a summary, or a short conversation. A **`DEFINE AGENT`** is a named assistant that runs on that connector. It can read topics, publish, run connector events, and hand work to other agents — only where you grant it.

The connector holds the provider, the model, the key, and the price. Every agent that names it with `USES LLM CONNECTOR` picks up a change to that connector. An agent is its own LoT entity. It is deployed with `-addAgent`, and it does not appear in the connector list.

> [!TIP]
>
> **Like a phone line and the people who answer it.** The `TYPE LLM` connector is the line to the model. Each `DEFINE AGENT` is a person you hire, with a job description and a set of keys. `CALL LLM` dials the line directly. `CALL AGENT` asks a specific person to do the job.

### When to use which

* **Prompt in, text out**: a `TYPE LLM` connector and `CALL LLM` inside an Action. This page.
* **An assistant that reads or changes the broker**: a `DEFINE AGENT` on that connector. See [Agents Overview](/latest/lot-language/agents/overview).

Both need a **Growth or Enterprise** license, the same row as **LLM / Agent** on [Licensing](/latest/mqtt-broker/licensing#plans).

> [!NOTE]
>
> First time? Paste a working agent in [Creating Agents in Coreflux](/latest/quick-start/creating-agents). Come back here for providers and `CALL LLM`. Grants, topics, and the move off `TYPE AGENT` are in [Agent Syntax](/latest/lot-language/agents/syntax).

***

The example below is complete. Deploy the LLM connector with `-addConnector`.

## Quick Start

**Ask a model from an Action**

One prompt, one answer. The connector has no tools.

Store the key once with `KEEP SECRET "OPENAI_API_KEY" WITH "sk-..."`, or with `-setSecret`. See [Secrets](/latest/mqtt-broker/secrets-and-env).

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantModel WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"

DEFINE ACTION ExplainAlarm
ON TOPIC "alarms/raw/+" DO
    CALL LLM "PlantModel.generate"
        WITH (prompt = PAYLOAD)
        RETURN AS {result}
    PUBLISH TOPIC "alarms/explained" WITH (GET JSON "response" IN {result} AS STRING)
```

Publish an alarm payload to `alarms/raw/line3`. The explanation arrives on `alarms/explained`. Read `success` in `{result}` before you trust `response`.

For agent examples, see [Agent Examples](/latest/lot-language/agents/examples).

***

## The LLM connector

`DEFINE CONNECTOR … WITH TYPE LLM` is the connector (`DEFINE ROUTE` and the `-addRoute` / `-removeRoute` commands still work as aliases). Actions call it with `CALL LLM`. Agents name it with `USES LLM CONNECTOR`. The connector itself never calls tools.

### Picking a provider

| Provider | `WITH PROVIDER` | Typical `BASE_URL` | Auth |
| - | - | - | - |
| **Ollama** (default) | `ollama` | `http://localhost:11434` | none |
| **OpenAI** | `openai` | omit (the provider default) | `API_KEY` |
| **Anthropic** | `anthropic` | omit (the provider default), or a proxy | `API_KEY` |
| **OpenAI-compatible** | `compatible` | your gateway URL | `API_KEY` when that server requires one |

> [!NOTE]
>
> **Local Ollama.** [Install Ollama](https://ollama.com/download) on the broker host, or on a machine the broker can reach, and pull a **tools-capable** model before you deploy (`ollama pull llama3.2` or `ollama pull qwen3`). The `MODEL` value must match `ollama list`. Only some Ollama models call tools. Coreflux connects to the endpoint you set. It does not install Ollama or download models.
>
> If the broker runs in **Docker**, `localhost` inside the container is the container. Point `BASE_URL` at the Ollama service on the Compose network (for example `http://ollama:11434`), or at `http://host.docker.internal:11434` when Ollama runs on the Docker host.

**Ollama**

The default provider. Omit `PROVIDER` and the connector still uses Ollama at `http://localhost:11434`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "ollama"
        WITH BASE_URL "http://localhost:11434"
        WITH MODEL "llama3.2"
```

**OpenAI**

`API_SURFACE "auto"` uses the Responses API, which current reasoning models such as `gpt-6-luna` require. Leave `TEMPERATURE` unset for those models.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gpt6 WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"
        WITH API_SURFACE "auto"
        WITH REASONING_EFFORT "medium"
        WITH PRICE_INPUT "1.25"
        WITH PRICE_OUTPUT "10"
```

**Anthropic**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Claude WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "anthropic"
        WITH MODEL "claude-sonnet-5-5"
        WITH API_KEY GET SECRET "ANTHROPIC_API_KEY"
```

**OpenAI-compatible**

Use `compatible` for a gateway that speaks the OpenAI HTTP API. `API_SURFACE "auto"` on this provider uses Chat Completions. Set `API_SURFACE "responses"` only when that gateway implements the Responses API.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR Gateway WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "compatible"
        WITH BASE_URL "https://llm.example.com/v1"
        WITH MODEL "local-large"
        WITH API_KEY GET SECRET "GATEWAY_API_KEY"
        WITH API_SURFACE "chat_completions"
```

### `LLM_CONFIG`

| Parameter | Required | Default | Description |
| - | - | - | - |
| `MODEL` | **Yes** | — | Model name the provider expects (`llama3.2`, `gpt-6-luna`, `claude-sonnet-5-5`) |
| `PROVIDER` | No | `ollama` | `ollama`, `openai`, `anthropic`, or `compatible` |
| `BASE_URL` | No | Ollama: `http://localhost:11434`. Others: the provider default | Required in practice for `compatible` |
| `API_KEY` | Conditional | — | Required for `openai`, `anthropic`, and most `compatible` endpoints. Use `GET SECRET` |
| `API_SURFACE` | No | `auto` | `openai` and `compatible` only: `auto`, `responses`, or `chat_completions`. `auto` is Responses for `openai` and Chat Completions for `compatible` |
| `REASONING_EFFORT` | No | see below | `none`, `low`, `medium`, `high`, or `extra_high`, sent on every call. `none` sends nothing |
| `TEMPERATURE` | No | Ollama: `0.7`. Others: not sent | `0.0`–`2.0`. Leave it unset for reasoning models, which reject a temperature |
| `MAX_TOKENS` | No | `2048` | Maximum completion tokens for **one** call. An agent's `MAX_TOKENS` is a different budget |
| `PRICE_INPUT` | No | — | Price per million input tokens. Agent tasks then report `cost` on `run_end` when either price is set |
| `PRICE_OUTPUT` | No | — | Price per million output tokens |
| `SYSTEM_PROMPT` | No | empty | Default system message for `CALL LLM`. Agents use their own `SYSTEM_PROMPT` |

> [!NOTE]
>
> **Models that reason before answering** spend part of the connector's `MAX_TOKENS` on reasoning they don't show. With `1024` the answer can come back empty. Set `MAX_TOKENS` to `4096` or more on the `TYPE LLM` connector for these models.

Without `REASONING_EFFORT`, only `PROVIDER "openai"` on the Responses API sends one: Medium. That default is skipped for older families (`gpt-4*`, `gpt-3*`, `chatgpt-*`), which reject it. A `compatible` connector sends no reasoning effort unless you set it. Set `REASONING_EFFORT "none"` when an OpenAI model rejects the default.

`MCP_ROUTES` is legacy. On a `TYPE LLM` connector the broker ignores it and logs a warning to use `ADD TOOL`. The connector still starts. A `TYPE LLM` call runs no tools. On `DEFINE AGENT` it is a legacy clause, and `-addAgent` refuses it. To give an agent an MCP tool, see [Agents and MCP Tools](/latest/lot-language/routes/mcp-routes#agents-and-mcp-tools). See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).

The connector does not probe the provider at start. A wrong key, URL, or model shows up on the first call, as `"success": false`.

### Ollama context and timeouts

Ollama uses the model's default context window (often 2k–8k tokens) unless the request asks for more, and silently drops the start of a longer prompt. The broker therefore sends `num_ctx` on every Ollama call, for `CALL LLM` and for each step of an agent's tool loop:

* It estimates the prompt (messages, tool results, and tool schemas) plus `MAX_TOKENS`.
* It uses 16,384 tokens when that fits, otherwise `MAX_CONTEXT_WINDOW`. Only two sizes, because each change makes Ollama reload the model.
* It never goes above the model's own maximum, read from Ollama and cached for five minutes.
* A prompt that still doesn't fit fails with `context_overflow` and is never sent.

| Parameter | Default | Description |
| - | - | - |
| `CONTEXT_WINDOW` | sized per call | A fixed `num_ctx` in tokens instead of the automatic size. Still capped at the model's maximum |
| `MAX_CONTEXT_WINDOW` | `32768` | The largest `num_ctx` the broker picks. Larger windows use more memory on the Ollama host |
| `FIRST_OUTPUT_TIMEOUT` | `120` | Seconds from sending a request to its first streamed output, model load included. `0` turns it off |
| `IDLE_TIMEOUT` | `60` | Longest gap, in seconds, between streamed chunks. `0` turns it off. Time spent in tools never counts |

These four settings apply to `PROVIDER "ollama"` only.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalLlama WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "ollama"
        WITH BASE_URL "http://ollama:11434"
        WITH MODEL "qwen3"
        WITH MAX_CONTEXT_WINDOW 16384
        WITH FIRST_OUTPUT_TIMEOUT 300
```

Both timeouts apply per gap, so a long answer that keeps arriving never times out. An agent's `TASK_TIMEOUT` and cancel also end a call that is waiting on Ollama. A large model loading cold on a slow machine can take more than two minutes: raise `FIRST_OUTPUT_TIMEOUT` for it. On a low-memory Ollama host, a 32k window may not fit next to the model. Lower `MAX_CONTEXT_WINDOW` (for example to `16384`).

| Failure code | Meaning |
| - | - |
| `llm_timeout` | No output within `FIRST_OUTPUT_TIMEOUT`, or a gap longer than `IDLE_TIMEOUT` |
| `llm_unreachable` | Nothing listens at `BASE_URL`: Ollama isn't running, or the host or port is wrong |
| `model_not_found` | Ollama doesn't have `MODEL`. Run `ollama pull` or fix the name |
| `context_overflow` | The prompt doesn't fit the largest window the connector allows |

Agents report these as the task's `code`. `CALL LLM` returns `"success": false` with the same message, which names the model and the URL, in `error`.

### Call the model from an Action

| Method | What it does |
| - | - |
| `generate` | One turn. No history |
| `chat` | Multi-turn. Pass `use_history = "true"` and a `session_id` to keep the thread |
| `clear_history` | Drops the in-memory thread for that `session_id` |

`CALL LLM` and `INVOKE LLM` are the same call.

```lot wrap focus={7-13} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR PlantModel WITH TYPE LLM
    ADD LLM_CONFIG
        WITH PROVIDER "openai"
        WITH MODEL "gpt-6-luna"
        WITH API_KEY GET SECRET "OPENAI_API_KEY"

DEFINE ACTION ContinueThread
ON TOPIC "assistants/+/message" DO
    SET "user_id" WITH TOPIC POSITION 2
    CALL LLM "PlantModel.chat"
        WITH (prompt = PAYLOAD, use_history = "true", session_id = {user_id})
        RETURN AS {result}
    PUBLISH TOPIC "assistants/" + {user_id} + "/reply" WITH (GET JSON "response" IN {result} AS STRING)
```

A success payload for `generate` and `chat` includes `success`, `response`, `model`, `session_id`, `used_history`, and `execution_time_ms`. A failure sets `success` to `false` and puts the reason in `error`.

History for `CALL LLM` stays in memory on that connector: the last 50 messages per `session_id`, dropped when the connector stops or the broker restarts. Agent conversations are separate and survive a restart. See [Working memory](/latest/lot-language/agents/syntax#working-memory).

You can also fire the connector with `TRIGGER "PlantModel" TO {prompt} FOR "generate"` (or `FOR "chat"` for the history mapping). That path publishes the result to the mapping's `DESTINATION_TOPIC`, or to `{RouteName}/llm/response` when that mapping has none. `TRIGGER` keeps chat history only when the mapping name is `chat`, unless the JSON payload sets `use_history`.

Status is the usual connector topic `$SYS/Coreflux/Routes/{Name}/status`. The connector does not publish `…/Capabilities` or `…/Metrics`.

`-discoverAIProviders` probes local and cloud model lists and retains a summary on `$SYS/Coreflux/AI/Providers`. That probe is independent of the providers a `TYPE LLM` connector accepts.

***

## Agents

`DEFINE AGENT` has its own section: [Agents Overview](/latest/lot-language/agents/overview), [Agent Syntax](/latest/lot-language/agents/syntax) (properties, `ADD TOOL`, delegation, topics, `CALL AGENT`, management), and [Agent Examples](/latest/lot-language/agents/examples). Moving off `TYPE AGENT`? See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).

***

## Troubleshooting

> **Ollama never calls a tool**
>
> The model does not support tools. Pull a tools-capable tag such as `llama3.2` or `qwen3`.

> **OpenAI returns HTTP 400**
>
> Reasoning models reject `TEMPERATURE`. Leave it unset. `gpt-6-luna` rejects a Chat Completions call. Use `API_SURFACE "auto"` or `"responses"`.

***

***

## Limitations

> [!WARNING]
>
> `CALL LLM` waits for the full answer and does not stream. `CALL LLM` history is in memory only. For agent limits, see [Agents Overview](/latest/lot-language/agents/overview#limits).

***

## Next steps

> **[Creating Agents in Coreflux](/latest/quick-start/creating-agents)**
>
> Paste a site guide, a scheduled report, alert triage, or a shift handover and try them over MQTT.

> **[MCP Connectors](./mcp-routes)**
>
> Call external MCP tools from Actions. Agents do not receive those tools automatically.


# Connector Examples
Source: https://docs.coreflux.org/latest/lot-language/routes/examples

Complete examples of LoT connector configurations for common integration scenarios

## Examples Index

Find the right example for your use case:

| Example | Connector Type | Key Features |
| - | - | - |
| [Edge-to-Cloud Sync](#edge-to-cloud-sensor-sync) | MQTT\_BRIDGE | TLS, outbound sync |
| [Cloud Commands](#cloud-command-reception) | MQTT\_BRIDGE | Inbound direction |
| [Multi-Site Network](#multi-site-synchronization) | MQTT\_BRIDGE | Multiple mappings |
| [MongoDB Sensor Storage](#mongodb-sensor-storage) | MONGODB | CLEAN query format |
| [REST API Integration](#rest-api-integration) | REST\_API | HTTP requests from MQTT |
| [Critical Alerts Email](#critical-alert-notifications) | EMAIL | Template placeholders |
| [OpenSearch Analytics](#opensearch-sensor-archive) | OPENSEARCH | STORE keyword |
| [Complete Integration](#complete-integration-example) | Multiple | Combined setup |
| [gRPC calls](/latest/lot-language/routes/streaming/grpc) | `GRPC` | Unary and streaming calls, one bidirectional call per device topic |

***

## MQTT Bridge Examples

### Edge-to-Cloud Sensor Sync

This example demonstrates synchronizing sensor data from a local edge device to a cloud broker. The `out` direction ensures data flows from your local broker to the cloud, while TLS encryption secures the connection:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EdgeToCloudSync WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloudprovider.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "EdgeDevice-Factory1"
        WITH USERNAME "edge_device_001"
        WITH PASSWORD "secure_cloud_password"
        WITH USE_TLS true
    ADD MAPPING allSensors
        WITH SOURCE_TOPIC "local/sensors/#"
        WITH DESTINATION_TOPIC "factory1/edge/sensors/#"
        WITH DIRECTION "out"
    ADD MAPPING equipmentStatus
        WITH SOURCE_TOPIC "local/equipment/+/status"
        WITH DESTINATION_TOPIC "factory1/edge/equipment/+/status"
        WITH DIRECTION "out"
```

### Cloud Command Reception

Receive commands from cloud systems and distribute them to local devices. The `in` direction means data flows from the remote broker to your local broker:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CloudCommands WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloudprovider.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "EdgeDevice-Factory1-Commands"
        WITH USE_TLS true
    ADD MAPPING deviceCommands
        WITH SOURCE_TOPIC "local/commands/devices/+"
        WITH DESTINATION_TOPIC "factory1/commands/devices/+"
        WITH DIRECTION "in"
    ADD MAPPING configUpdates
        WITH SOURCE_TOPIC "local/config/#"
        WITH DESTINATION_TOPIC "factory1/config/#"
        WITH DIRECTION "in"
```

### Multi-Site Synchronization

Connect multiple factory locations to a central broker. This pattern enables enterprise-wide visibility while keeping local operations independent:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FactoryNetwork WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "central-broker.company.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "Factory-Chicago"
        WITH USE_TLS true
    ADD MAPPING productionData
        WITH SOURCE_TOPIC "production/#"
        WITH DESTINATION_TOPIC "chicago/production/#"
        WITH DIRECTION "out"
    ADD MAPPING qualityData
        WITH SOURCE_TOPIC "quality/#"
        WITH DESTINATION_TOPIC "chicago/quality/#"
        WITH DIRECTION "out"
    ADD MAPPING centralCommands
        WITH SOURCE_TOPIC "local/commands/#"
        WITH DESTINATION_TOPIC "chicago/commands/#"
        WITH DIRECTION "in"
```

***

## MongoDB Examples

### MongoDB Sensor Storage

Store sensor readings in MongoDB using the CLEAN query format. This example captures all sensor readings and stores them with metadata including the original topic and timestamp:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorStorage WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:password@mongodb.example.com:27017/iot?authSource=admin"
        WITH DATABASE "iot"
    ADD EVENT StoreSensorReading
        WITH QUERY "CLEAN:{collection: sensor_readings, document: {sensor_id: {sensor_id}, value: {value.json}, topic: {source_topic}, timestamp: {timestamp}}}"
        WITH SOURCE_TOPIC "sensors/+/reading"
```

### MongoDB Event Logging

Create an event log collection for system events:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EventLogger WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://localhost:27017/logs"
        WITH DATABASE "logs"
    ADD EVENT LogSystemEvent
        WITH QUERY "CLEAN:{collection: system_events, document: {event_type: {event_type}, source: {source_topic}, data: {value.json}, created_at: {timestamp}}}"
        WITH SOURCE_TOPIC "events/+/+"
```

***

## REST API Examples

### REST API Integration

Connect your MQTT broker to external REST APIs. This example calls a weather API when a request arrives on the trigger topic:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WeatherService WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_CLIENT "true"
        WITH BASE_ADDRESS "https://api.openweathermap.org"
    ADD MAPPING GetWeather
        WITH SOURCE_TOPIC "weather/request"
        WITH DESTINATION_TOPIC "weather/response"
        WITH QUERY '{
            "method": "GET",
            "endpoint": "/data/2.5/weather",
            "headers": {
                "Content-Type": "application/json"
            }
        }'
```

### REST API with Authentication

Call authenticated APIs with headers extracted from the MQTT payload:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR NotificationService WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_CLIENT "true"
        WITH BASE_ADDRESS "https://api.notification-service.com"
    ADD MAPPING SendNotification
        WITH SOURCE_TOPIC "notifications/send"
        WITH DESTINATION_TOPIC "notifications/result"
        WITH QUERY '{
            "method": "POST",
            "endpoint": "/v1/notify",
            "headers": {
                "Content-Type": "application/json",
                "Authorization": "Bearer {api_key}"
            },
            "content": "{payload.json}"
        }'
```

***

## Email Notification Examples

### Critical Alert Notifications

Send emails for critical system alerts. Template placeholders like `{value.json.equipment_id}` are replaced with values from the MQTT payload:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR CriticalAlerts WITH TYPE EMAIL
    ADD MQTT_CONFIG
        WITH BROKER SELF
    ADD SMTP_CONFIG
        WITH HOST "smtp.gmail.com"
        WITH PORT '587'
        WITH USERNAME "alerts@mycompany.com"
        WITH PASSWORD "gmail-app-password"
        WITH USE_TLS true
    ADD MAPPING criticalEquipment
        WITH SOURCE_TOPIC "alerts/critical/equipment/+"
        WITH TEMPLATE_PATH "/templates/equipment_alert.html"
        WITH SUBJECT "CRITICAL: Equipment {value.json.equipment_id} - {value.json.alert_type}"
        WITH RECIPIENT "ops-team@mycompany.com"
    ADD MAPPING criticalSafety
        WITH SOURCE_TOPIC "alerts/critical/safety/+"
        WITH TEMPLATE_PATH "/templates/safety_alert.html"
        WITH SUBJECT "SAFETY ALERT: {value.json.location}"
        WITH RECIPIENT "safety-team@mycompany.com"
```

### Dynamic User Notifications

Send to recipients specified in the MQTT payload using `{value.json.email}`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR UserNotifications WITH TYPE EMAIL
    ADD MQTT_CONFIG
        WITH BROKER SELF
    ADD SMTP_CONFIG
        WITH HOST "smtp.office365.com"
        WITH PORT '587'
        WITH USERNAME "noreply@company.com"
        WITH PASSWORD "office365-password"
        WITH USE_TLS true
    ADD MAPPING userAlert
        WITH SOURCE_TOPIC "users/+/notifications"
        WITH TEMPLATE_PATH "/templates/user_notification.html"
        WITH SUBJECT "Hello {value.json.username}, {value.json.notification_type}"
        WITH RECIPIENT "{value.json.email}"
```

***

## Data Storage Examples

### OpenSearch Sensor Archive

Index all sensor data for real-time analytics and historical queries:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorArchive WITH TYPE OPENSEARCH
    ADD OPENSEARCH_CONFIG
        WITH BASE_URL "https://opensearch.company.com:9200"
        WITH USERNAME "sensor_writer"
        WITH PASSWORD "opensearch_password"
        WITH USE_SSL true
    ADD EVENT IndexSensorReading
        WITH QUERY "CLEAN:{index: sensor-readings, body: {@timestamp: {timestamp}, sensor_id: {sensor_id}, data: {value.json}}}"
        WITH SOURCE_TOPIC "sensors/+/data"
```

### Combined Bridge and Storage

Bridge data from a remote broker and simultaneously store it in OpenSearch using the `STORE` keyword:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProcessAndArchive WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER_ADDRESS "factory-broker.local"
        WITH BROKER_PORT '1883'
        WITH CLIENT_ID "ArchiveBridge"
    ADD DESTINATION_CONFIG
        WITH BROKER SELF
    ADD MAPPING sensorData
        WITH SOURCE_TOPIC "factory/sensors/+/data"
        WITH DESTINATION_TOPIC "archived/sensors/+/data"
        WITH DIRECTION "in"
    STORE SensorArchive WITH INDEX_NAME "factory_sensors"
```

***

## Complete Integration Example

This comprehensive example combines multiple connector types into a complete IoT integration setup. It demonstrates how different connectors work together:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
// 1. MongoDB storage for historical data
DEFINE CONNECTOR DataWarehouse WITH TYPE MONGODB
    ADD MONGODB_CONFIG
        WITH CONNECTION_STRING "mongodb://user:pass@mongodb.company.com:27017/iot?ssl=true"
        WITH DATABASE "iot"
    ADD EVENT StoreProduction
        WITH QUERY "CLEAN:{collection: production_data, document: {timestamp: {timestamp}, data: {value.json}}}"
        WITH SOURCE_TOPIC "production/#"

// 2. Cloud synchronization for remote monitoring
DEFINE CONNECTOR CloudSync WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS "iot.cloud.com"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID "Factory-Main"
        WITH USE_TLS true
    ADD MAPPING allData
        WITH SOURCE_TOPIC "production/#"
        WITH DESTINATION_TOPIC "factory-main/production/#"
        WITH DIRECTION "out"

// 3. REST API for external integrations
DEFINE CONNECTOR ERPIntegration WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_CLIENT "true"
        WITH BASE_ADDRESS "https://erp.company.com/api"
    ADD MAPPING UpdateInventory
        WITH SOURCE_TOPIC "production/completed"
        WITH DESTINATION_TOPIC "erp/response"
        WITH QUERY '{"method": "POST", "endpoint": "/inventory/update", "content": "{payload.json}"}'

// 4. Email alerts for critical events
DEFINE CONNECTOR CriticalAlerts WITH TYPE EMAIL
    ADD MQTT_CONFIG
        WITH BROKER SELF
    ADD SMTP_CONFIG
        WITH HOST "smtp.company.com"
        WITH PORT '587'
        WITH USERNAME "alerts@company.com"
        WITH PASSWORD "email_password"
        WITH USE_TLS true
    ADD MAPPING critical
        WITH SOURCE_TOPIC "alerts/critical/#"
        WITH TEMPLATE_PATH "/templates/critical.html"
        WITH SUBJECT "CRITICAL: {value.json.type}"
        WITH RECIPIENT "ops@company.com"
```

***

## Pattern Summary

Choose the right connector pattern for your scenario:

| Scenario | Connector Type | Key Configuration |
| - | - | - |
| Edge to Cloud | MQTT\_BRIDGE | `WITH DIRECTION "out"` |
| Cloud Commands | MQTT\_BRIDGE | `WITH DIRECTION "in"` |
| Bidirectional Sync | MQTT\_BRIDGE | `WITH DIRECTION "both"` |
| Document Storage | MONGODB | CLEAN query format |
| Search/Analytics | OPENSEARCH | Index configuration |
| API Integration | REST\_API | HTTP method + endpoint |
| Email Alerts | EMAIL | Template + placeholders |

## Next Steps

> **[High-Availability Clustering](/latest/mqtt-broker/clustering)**
>
> Run multiple Coreflux brokers as a fault-tolerant cluster.

> **[OT Connectors](./industrial/modbus-tcp-client)**
>
> Connect to industrial equipment via Modbus.


# MCP Connectors
Source: https://docs.coreflux.org/latest/lot-language/routes/mcp-routes

Connect your Coreflux broker to external tools and services through the Model Context Protocol (MCP)

## Plug Your Broker Into Any MCP Tool

MCP (Model Context Protocol) is an open standard that defines how applications communicate with external tool servers. MCP Connectors let your Coreflux broker connect to any MCP-compatible server — file systems, messaging platforms, cloud storage, spreadsheets, and more — and call their tools directly from LoT Actions.

> [!WARNING]
>
> This page is the **MCP client connector** (`DEFINE CONNECTOR … WITH TYPE MCP` and `CALL MCP` from Actions). The broker connects *out* to an external MCP server.
>
> To expose **this broker** as an MCP server for Cursor or Claude Desktop, use the [MCP Server](/latest/mqtt-broker/mcp-server) (`Mcp.Enabled`). `TYPE MCP_SERVER` was removed. The hosted [documentation MCP](/ai/mcp) searches docs.coreflux.org and does not control a broker.

> [!NOTE]
>
> A `DEFINE AGENT` does not receive this connector's tools, and `execute_routes` cannot reach them. Call MCP tools from an Action with `CALL MCP`. To give an agent one tool, wrap the call in a callable action and grant that action with `ADD TOOL "execute_actions"`. See [Agents and MCP Tools](#agents-and-mcp-tools).

> [!TIP]
>
> **Like adding power tools to a workbench.** Each MCP Connector plugs a new tool into your broker — a Slack server for sending messages, a filesystem server for reading logs, a Google Drive server for cloud backups. Once connected, any LoT Action can pick up and use that tool.

***

## Integration Architecture

MCP Connectors allow the Coreflux Broker to connect to external MCP servers as a **client**. This enables LoT Actions to call tools provided by any MCP server—file systems, cloud services, communication platforms, and more.

```mermaid actions={false} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
graph LR
    subgraph mcpServers [External MCP Servers]
        Filesystem[Filesystem Server]
        Slack[Slack Server]
        GDrive[Google Drive]
        Custom[Custom MCP Server]
    end
    
    subgraph broker [Coreflux Broker]
        MCPRoutes[MCP Connectors]
        Actions[LoT Actions]
        Topics[MQTT Topics]
    end
    
    subgraph devices [IoT Layer]
        Sensors[Sensors]
        Actuators[Actuators]
    end
    
    MCPRoutes -->|connects to| Filesystem
    MCPRoutes -->|connects to| Slack
    MCPRoutes -->|connects to| GDrive
    MCPRoutes -->|connects to| Custom
    
    Actions -->|CALL MCP| MCPRoutes
    Actions -->|PUBLISH/KEEP| Topics
    Topics <--> Sensors
    Topics <--> Actuators
```

### How It Works

1. **Define MCP Connectors** - Each connector connects to an external MCP server
2. **Discover Tools** - The broker discovers available tools from each server, once after it connects
3. **Call from Actions** - Use `CALL MCP` in LoT Actions to invoke any tool
4. **Reusable Connections** - Multiple actions can share the same MCP connector

> [!TIP]
>
> **MCP as a Connection Type.** Just like database connectors or REST API connectors, MCP connectors provide a reusable connection that any action can leverage. Define the connector once, use it everywhere.

***

## Basic Syntax

The `MCP` connector type connects your Coreflux broker to an external MCP server, making that server's tools callable from LoT Actions. Each connector manages one MCP server connection, and you can define multiple connectors to connect to different servers simultaneously.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPFilesystem WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "npx"
        WITH SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-filesystem, /data"
        WITH CLIENT_NAME "CorefluxFS"
```

Once connected, any LoT Action can use `CALL MCP` to invoke the server's tools — send Slack messages, read and write files, generate spreadsheet reports, or interact with any other MCP-compatible service.

***

## MCP Configuration

### MCP\_CONFIG Parameters

A connector reaches its server in one of two ways. Set `SERVER_COMMAND` and `SERVER_ARGUMENTS` to start a local server process (stdio). Or set `SERVER_URL` to connect to a remote server over HTTP. When `SERVER_URL` is set, `SERVER_COMMAND` and `SERVER_ARGUMENTS` are not needed. Without it, `-addConnector` requires both.

**SERVER\_COMMAND** `string`

MCP server command to execute (e.g., `npx`, `python`, `node`). Required unless `SERVER_URL` is set.

**SERVER\_ARGUMENTS** `string`

Comma-separated server arguments (e.g., `-y, @modelcontextprotocol/server-filesystem`). Required unless `SERVER_URL` is set.

**SERVER\_URL** `string`

URL of a remote MCP server (e.g., `https://mcp.example.com/mcp`). Replaces `SERVER_COMMAND` and `SERVER_ARGUMENTS`. The broker sends no authentication headers to this URL.

**SERVER\_ENV** `string`

`WITH SERVER_ENV "NAME" <value>` sets one environment variable on the server process. Repeat the line for each variable. The value can be a string, a number, `true`/`false`, `GET ENV "..."`, or `GET SECRET "..."`, resolved when the connector starts. Applies only to a server started with `SERVER_COMMAND`.

**CLIENT\_NAME** `string`

MCP client identifier. Default: CorefluxBroker.

***

## Configuration Examples

**Filesystem Server**

Enable LoT Actions to perform file operations:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPFilesystem WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "npx"
        WITH SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-filesystem, /data"
        WITH CLIENT_NAME "CorefluxFS"
```

**Custom MCP Server**

Connect to a custom MCP server:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPCustom WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "python"
        WITH SERVER_ARGUMENTS "-m, my_mcp_server"
        WITH CLIENT_NAME "CorefluxCustom"
```

**Node.js Server**

Run a Node.js MCP server:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPNode WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "node"
        WITH SERVER_ARGUMENTS "/opt/mcp/server.js, --config, /etc/mcp/config.json"
        WITH CLIENT_NAME "CorefluxNode"
```

**Server Credentials**

Pass an API key to a local server as an environment variable. Keep the key in a secret, not in the connector:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPNotion WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "npx"
        WITH SERVER_ARGUMENTS "-y, @notionhq/notion-mcp-server"
        WITH SERVER_ENV "NOTION_API_KEY" GET SECRET "NOTION_KEY"
        WITH SERVER_ENV "NOTION_CACHE_TTL" "300"
```

**Remote Server**

Connect to an MCP server over HTTP. No local Node.js or Python is needed:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPRemote WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_URL "https://mcp.example.com/mcp"
        WITH CLIENT_NAME "CorefluxRemote"
```

The broker sends no API key, token, or OAuth credentials to a `SERVER_URL`. Use a server that accepts unauthenticated calls from the broker's network, or run the server locally with `SERVER_COMMAND` and pass its credentials with `SERVER_ENV`.

***

## MCP Server Examples

The MCP ecosystem includes servers for various platforms and services. These examples show how to connect popular MCP servers to your Coreflux broker for IoT integration.

**Node.js Servers (npx)**

Node.js-based MCP servers can be run directly using `npx`. These are the most common and include official Anthropic servers.

| Server | LoT Configuration | IoT Use Case |
| - | - | - |
| **Filesystem** | `SERVER_COMMAND "npx"` with `SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-filesystem, /data"` | Read sensor logs, manage config files |
| **Google Drive** | `SERVER_COMMAND "npx"` with `SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-gdrive"` | Cloud backup of IoT data |
| **Slack** | `SERVER_COMMAND "npx"` with `SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-slack"` | Send alerts to team channels |
| **Memory** | `SERVER_COMMAND "npx"` with `SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-memory"` | Persist context across AI sessions |
| **Fetch** | `SERVER_COMMAND "npx"` with `SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-fetch"` | Access external APIs and web data |
| **Windows Control** | `SERVER_COMMAND "npx"` with `SERVER_ARGUMENTS "-y, mcp-control"` | Automate HMI/SCADA systems |

**Example: Slack Alerts for IoT Events**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPSlack WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "npx"
        WITH SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-slack"
        WITH CLIENT_NAME "CorefluxSlack"
```

**Python Servers (uvx)**

Python-based MCP servers use `uvx` (the uv package runner). These are common for third-party integrations.

| Server | LoT Configuration | IoT Use Case |
| - | - | - |
| **Spotify** | `SERVER_COMMAND "uvx"` with `SERVER_ARGUMENTS "spotify-mcp"` | Smart home audio control |
| **Excel** | `SERVER_COMMAND "uvx"` with `SERVER_ARGUMENTS "excel-mcp-server"` | Generate reports from sensor data |

**Example: Excel Reports from Sensor Data**

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPExcel WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "uvx"
        WITH SERVER_ARGUMENTS "excel-mcp-server"
        WITH CLIENT_NAME "CorefluxExcel"
```

***

## Calling MCP Tools

Once an MCP connector is defined, you can call its tools from within LoT Actions using the `CALL MCP` syntax. This enables AI-powered automation triggered by MQTT events.

### Basic Syntax

The standard syntax to invoke an MCP tool from an Action:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL MCP "RouteName.ToolName"
    WITH (arg1 = value1, arg2 = value2)
    RETURN AS {result_variable}
```

| Component | Format | Description |
| - | - | - |
| **Connector.Tool** | `"RouteName.ToolName"` | Connector name and tool name separated by a dot |
| **WITH** | `WITH (name = value, ...)` | Named arguments in parentheses |
| **RETURN AS** | `RETURN AS {varname}` | Capture the result in a variable |

### Return Value

`RETURN AS` always receives a JSON string, also when the call fails. Check `success` before you use `result`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "tool_name": "send-message",
  "route_name": "MCPSlack",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "execution_time_ms": 150,
  "result": { }
}
```

| Field | Description |
| - | - |
| `success` | `true` when the server ran the tool |
| `tool_name` | The tool that was called |
| `route_name` | The connector that called it |
| `timestamp` | UTC time of the reply |
| `execution_time_ms` | Time the call took, in milliseconds |
| `result` | The MCP server's tool result. Present only on success |
| `error` | Why the call failed. Present only when `success` is `false` |

A failed call has `success: false` and an `error` such as `Tool 'X' not found. Available tools: ...`, `MCP client is not connected`, or `MCP route 'X' not found or not an MCP route`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CALL MCP "MCPSlack.send-message"
    WITH (channel = "alerts", message = "Line 2 stopped")
    RETURN AS {reply}
SET "sent" WITH (GET JSON "success" IN {reply} AS BOOL)
IF {sent} EQUALS FALSE THEN
    PUBLISH TOPIC "alerts/slack/error" WITH (GET JSON "error" IN {reply} AS STRING)
END IF
```

### Complete Example

This Action monitors a temperature sensor and uses an MCP tool to send a Slack message when the temperature exceeds a threshold:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TemperatureAlert
ON TOPIC "sensors/+/temperature" DO
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    SET "sensor_id" WITH TOPIC POSITION 2
    
    IF {temp} > 80 THEN
        CALL MCP "MCPSlack.send-message"
            WITH (channel = "alerts", message = "🔥 Sensor " + {sensor_id} + " at " + {temp} + "°C")
            RETURN AS {result}
        
        PUBLISH TOPIC "alerts/temperature/sent" WITH "Sensor: " + {sensor_id} + " Temp: " + {temp} + " Result: " + {result}
    END IF
```

### Syntax Variations

> **No Arguments**
>
> Some tools don't require arguments:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> CALL MCP "MCPSystem.get-status"
>     RETURN AS {status}
> ```

> **Multiple Arguments**
>
> Pass multiple named parameters:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> CALL MCP "MCPFilesystem.write-file"
>     WITH (path = "/data/log.txt", content = {payload}, append = true)
>     RETURN AS {write_result}
> ```

> **String Concatenation**
>
> Build dynamic values using expressions:
>
> ```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> CALL MCP "MCPSlack.send-message"
>     WITH (message = "Device " + {device_id} + " reported: " + {value} + " at " + TIMESTAMP "UTC")
>     RETURN AS {chat_result}
> ```

### Who Can Call Tools

`CALL MCP` has no permission check of its own. Any action that runs `CALL MCP` can call any tool on any configured MCP connector, whichever role deployed the action. So:

* Only let trusted administrators add MCP connectors. Every tool those servers expose becomes callable from LoT.
* Restrict which roles can add or change actions. A role that can deploy actions can reach every tool on every MCP connector.
* To give an agent one tool, grant it one callable action with `execute_actions`. See [Agents and MCP Tools](#agents-and-mcp-tools).

***

## Agents and MCP Tools

A `DEFINE AGENT` cannot call an MCP tool directly. `ADD TOOL "execute_routes"` does not help: an MCP connector runs nothing when one of its events is fired. Use a callable action as the bridge:

1. A callable action takes the tool arguments as `INPUT`, runs `CALL MCP`, and publishes the reply to a topic.
2. The agent runs that action with `execute_actions`, passing the inputs as a JSON object.
3. The agent reads the reply topic with `read_mqtt`.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MCPSlack WITH TYPE MCP
    ADD MCP_CONFIG
        WITH SERVER_COMMAND "npx"
        WITH SERVER_ARGUMENTS "-y, @modelcontextprotocol/server-slack"

DEFINE ACTION PostSlackMessage
INPUT channel AS STRING
INPUT message AS STRING
DO
    CALL MCP "MCPSlack.send-message"
        WITH (channel = {channel}, message = {message})
        RETURN AS {reply}
    PUBLISH TOPIC "agents/slack/last_reply" WITH {reply}

DEFINE AGENT ShiftReporter
    USES LLM CONNECTOR Claude
    WITH DESCRIPTION "Posts shift summaries to Slack"
    WITH DEFAULT_USER "shift-reporter"
    ADD TOOL "read_mqtt"
        WITH TOPICS "lines/#, agents/slack/last_reply"
    ADD TOOL "execute_actions"
        WITH TARGET "PostSlackMessage"
        WITH LEVEL "write"
```

`Claude` is a `TYPE LLM` connector. Create `shift-reporter` with `-addUser` before you add the agent. `execute_actions` tells the agent only that the action ran, with the action name and a trace id. It does not return the action's output, so the reply goes through a topic. Grant one action per tool you want the agent to have.

`MCP_ROUTES` is legacy. A `TYPE LLM` connector ignores it and logs a warning to use `ADD TOOL`, and `-addAgent` refuses it on `DEFINE AGENT`. Grant tools with `ADD TOOL` on the agent instead. See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).

***

## Tool Discovery

When an MCP connector connects to a server, Coreflux discovers the server's tools about 10 seconds later and publishes them to MQTT system topics. Discovery runs once, after the connector connects. The broker ignores the server's `tools/list_changed` notifications, so a tool the server adds or changes later shows up only after the connector reconnects.

### System Topics

| Topic | Description |
| - | - |
| `$SYS/Coreflux/Routes/{name}/Tools` | Summary of all tools for a connector |
| `$SYS/Coreflux/Routes/{name}/Tools/{tool}` | Detailed info for a specific tool |
| `$SYS/Coreflux/Routes/{name}/Tools/{tool}/Capability` | Call statistics for one tool, updated after every call |

All three are retained. The broker republishes the summary and tool topics with its periodic status updates.

### Tools Summary Payload

Subscribe to the summary topic to see all available tools:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "route_name": "MCPSlack",
  "route_type": "MCP",
  "total_tools": 8,
  "tools": ["send-message", "list-channels", "get-channel-history", "add-reaction", ...],
  "capability_overview": {
    "total_executions": 42,
    "fast_tools": 3,
    "reliable_tools": 5,
    "avg_reliability": 97.5
  },
  "timestamp": "2026-10-23T12:00:00.000Z"
}
```

`fast_tools` counts tools rated `FAST`. `reliable_tools` counts tools rated `EXCELLENT`.

### Individual Tool Payload

Each tool publishes its description, parameters, and call statistics:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "name": "send-message",
  "description": "Send a message to a Slack channel",
  "parameters": {
    "channel": { "type": "string", "description": "Channel name or ID" },
    "message": { "type": "string", "description": "Message text" }
  },
  "route_name": "MCPSlack",
  "tool_type": "MCP",
  "capability": {
    "execution_count": 42,
    "average_latency_ms": 150.25,
    "min_latency_ms": 90,
    "max_latency_ms": 420,
    "success_count": 41,
    "failure_count": 1,
    "reliability_percent": 97.62,
    "performance_rating": "MEDIUM",
    "reliability_rating": "EXCELLENT",
    "first_executed": "2026-10-23T08:00:00.000Z",
    "last_executed": "2026-10-23T11:59:00.000Z",
    "last_error": ""
  },
  "timestamp": "2026-10-23T12:00:00.000Z"
}
```

Each parameter carries only `type` and `description`. An `array` parameter also carries `items`, which defaults to `{ "type": "string" }`. The payload does not say which parameters are required. Read the tool's description or the server's own documentation for that.

A tool that has never been called shows `0` counts, `UNKNOWN` ratings, and `never` for both dates. The first publish after discovery also carries `usage_example` (a ready `CALL MCP` block) and `trigger_example` (`TRIGGER "MCPSlack" TO PAYLOAD FOR "send-message"`). The periodic republish leaves them out.

### Capability Payload

`…/Tools/{tool}/Capability` is published after every call to that tool:

| Field | Description |
| - | - |
| `tool_name`, `route_name` | The tool and its connector |
| `execution_count`, `success_count`, `failure_count` | Calls since the connector started |
| `average_latency_ms`, `min_latency_ms`, `max_latency_ms` | Call time in milliseconds |
| `reliability_percent` | Share of calls that succeeded |
| `performance_rating` | `FAST` (under 100 ms), `MEDIUM` (under 500 ms), `SLOW` (under 2,000 ms), or `VERY_SLOW` |
| `reliability_rating` | `EXCELLENT` (95% or more), `GOOD` (85% or more), `FAIR` (70% or more), or `POOR` |
| `first_executed`, `last_executed` | UTC times of the first and latest call |
| `last_error` | Error of the latest failed call |
| `timestamp` | UTC time of this publish |

### Subscribing to Tool Discovery

Use MQTT Explorer or any MQTT client to discover available tools:

| What to Find | Topic Pattern |
| - | - |
| All tools for a specific connector | `$SYS/Coreflux/Routes/MCPSlack/Tools` |
| Details for a specific tool | `$SYS/Coreflux/Routes/MCPSlack/Tools/send-message` |
| Call statistics for a specific tool | `$SYS/Coreflux/Routes/MCPSlack/Tools/send-message/Capability` |
| All tools across all MCP connectors | `$SYS/Coreflux/Routes/+/Tools/#` |

> [!NOTE]
>
> Tool discovery topics are **retained messages**, so the information is immediately available when you subscribe—you don't need to wait for the next update.

***

## Use Cases

> **Alerting and Notifications**
>
> Connect to Slack, email, or other messaging MCP servers to send alerts directly from LoT Actions. When a sensor crosses a threshold, the Action calls the messaging tool — no external middleware needed.

> **File and Data Management**
>
> Use filesystem MCP servers to read configuration files, write sensor logs, or manage data exports. LoT Actions can read a config file at startup or append readings to a log file on every event.

> **Cloud Integration**
>
> Connect to Google Drive, Excel, or other cloud MCP servers to back up IoT data, generate reports from sensor readings, or sync configurations with cloud storage.

> **External Automation**
>
> Use Windows Control or custom MCP servers to automate HMI/SCADA interfaces, trigger external scripts, or interact with desktop applications as part of your IoT workflow.

***

## Best Practices

> **Security Considerations**
>
> * `CALL MCP` has no permission check. Restrict which roles can add or change actions, because any action can call any tool on a configured MCP connector. See [Who Can Call Tools](#who-can-call-tools)
> * `SERVER_COMMAND` starts any program on the broker host. Only let trusted administrators add MCP connectors
> * Pass server credentials with `SERVER_ENV` and `GET SECRET`, never as plain text in the connector
> * The broker sends no credentials to a `SERVER_URL`. Do not expose a remote MCP server that needs no key outside a trusted network
> * Monitor MCP tool calls through logging
> * Implement rate limiting for MCP requests

> **Resource Management**
>
> * Configure appropriate timeouts for MCP operations
> * Limit concurrent MCP connections if needed
> * Monitor memory usage of MCP server processes

> **Error Handling**
>
> * Implement graceful fallbacks when the MCP server is unavailable
> * Log MCP communication errors for debugging
> * Set up alerts for repeated failures

***

## Troubleshooting

> **MCP Server Won't Start**
>
> * Verify SERVER\_COMMAND path is correct
> * Check SERVER\_ARGUMENTS syntax (comma-separated)
> * Ensure required packages are installed (npx, node, python)
> * Check system PATH includes required executables

> **Connection Timeout**
>
> * Verify MCP server is running and responsive
> * Check network/firewall settings
> * Increase timeout values if server startup is slow
> * Check server logs for errors

> **Tool Execution Fails**
>
> * Verify the requested tool is available
> * Check permissions for the operation
> * Review server logs for detailed error messages
> * Ensure broker has required access rights

***

## Next Steps

> **[REST API Connectors](./rest-api-routes)**
>
> Connect to external REST APIs.

> **[Python Integration](../actions/python-integration)**
>
> Add custom AI/ML logic with Python.


# Audio Input Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/media/audio-input

Capture raw 16-bit PCM from a microphone, tone, silence, or file with TYPE AUDIO_INPUT and FFmpeg

## Publish microphone audio to MQTT

Audio Input opens a microphone, a synthetic source, or a file on the broker host and publishes raw 16-bit little-endian PCM. Each MQTT message is one time slice of samples — bytes, not JSON and not Base64. A LoT action can wrap those bytes in protobuf when a downstream service expects a message, not a bare buffer.

> [!TIP]
>
> **Like a voice recorder that saves short tapes.** Every tenth of a second (by default) a new tape of samples lands on the topic, ready for the next step in your project.

### When to use this

Use `TYPE AUDIO_INPUT` when you need live microphone audio, a test tone, silence for an automated run, or PCM from a file, on an MQTT topic. FFmpeg must be on the broker host (or in the slim image). The connector does not open Core Audio, WASAPI, or Pulse itself.

> [!NOTE]
>
> Do not set `WITH FORMAT`. That keyword belongs to models. This connector always publishes `s16le` PCM.

[Video Input](./video-input) is the camera sibling: JPEG data-URIs instead of PCM, with the same FFmpeg install.

***

Each tab is a full connector. Publish any payload to the start topic to begin. Chunks then arrive on `DESTINATION_TOPIC` until stop.

## Quick Start

**Silence for tests**

`anullsrc` needs no microphone. Use it in CI and on hosts with no audio device:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MicCi WITH TYPE AUDIO_INPUT
    ADD AUDIO_INPUT_CONFIG
        WITH SOURCE "anullsrc"
        WITH DESTINATION_TOPIC "audio/pcm/ci"
        WITH SAMPLE_RATE 16000
        WITH CHANNELS 1
        WITH CHUNK_MS 100
    ADD EVENT Start
        WITH SOURCE_TOPIC "audio/control/ci/start"
        WITH QUERY "START"
    ADD EVENT Stop
        WITH SOURCE_TOPIC "audio/control/ci/stop"
        WITH QUERY "STOP"
```

**Microphone**

`mic:0` is the default input on macOS and Linux. Windows rejects `mic:N` — use the DirectShow tab:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BuiltInMic WITH TYPE AUDIO_INPUT
    ADD AUDIO_INPUT_CONFIG
        WITH SOURCE "mic:0"
        WITH DESTINATION_TOPIC "audio/pcm/builtin"
        WITH SAMPLE_RATE 16000
        WITH CHANNELS 1
        WITH CHUNK_MS 100
    ADD EVENT Start
        WITH SOURCE_TOPIC "audio/control/start"
        WITH QUERY "START"
    ADD EVENT Stop
        WITH SOURCE_TOPIC "audio/control/stop"
        WITH QUERY "STOP"
```

**Windows microphone**

Set the environment variable to the exact DirectShow name, including the `audio=` prefix (`audio=Microphone (Realtek Audio)`):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WindowsMic WITH TYPE AUDIO_INPUT
    ADD AUDIO_INPUT_CONFIG
        WITH SOURCE GET ENV "AUDIO_SOURCE"
        WITH DESTINATION_TOPIC "audio/pcm/headset"
        WITH SAMPLE_RATE 16000
        WITH CHANNELS 1
        WITH CHUNK_MS 100
    ADD EVENT Start
        WITH SOURCE_TOPIC "audio/control/start"
        WITH QUERY "START"
    ADD EVENT Stop
        WITH SOURCE_TOPIC "audio/control/stop"
        WITH QUERY "STOP"
```

**Timed capture**

`CAPTURE 5 SECONDS` records a finite window, then stops on its own:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ClipMic WITH TYPE AUDIO_INPUT
    ADD AUDIO_INPUT_CONFIG
        WITH SOURCE "mic:0"
        WITH DESTINATION_TOPIC "audio/pcm/clip"
        WITH CHUNK_MS 100
    ADD EVENT RecordFiveSeconds
        WITH SOURCE_TOPIC "audio/control/clip"
        WITH QUERY "CAPTURE 5 SECONDS"
        WITH DESTINATION_TOPIC "audio/pcm/clip"
```

***

## Configuration

**SOURCE** `string` *required*

Microphone, DirectShow name, synthetic source, or file path. See the source table below.

**DESTINATION\_TOPIC** `string`

Topic for PCM chunks. Required on the config or on the event that starts capture. `START` and `STOP` events often omit it and inherit this topic.

**SAMPLE\_RATE** `integer`

Output rate in Hz, from `8000` to `48000`. Default: `16000`.

**CHANNELS** `integer`

`1` (mono) or `2` (stereo). Default: `1`.

**CHUNK\_MS** `integer`

Slice length in milliseconds, from `20` to `1000`. Default: `100`.

## Capture sources

| `SOURCE` | Broker host | What opens |
| - | - | - |
| `mic:0` | macOS | First input in the system audio list |
| `mic:0` | Linux | PulseAudio `default` |
| `mic:1` | Linux | ALSA `hw:1,0` |
| `mic:N` | Windows | Rejected. Use `audio=<name>` |
| `audio=Microphone (Realtek Audio)` | Windows | DirectShow device. The name must match exactly |
| `anullsrc` or `lavfi:anullsrc` | Any | Silence. No hardware |
| `tone:440` or `sine:440` | Any | A sine tone at that frequency |
| File path | Any | Passed through as a media file (`.wav` and other formats FFmpeg can read) |

List Windows devices on the broker host:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ffmpeg -list_devices true -f dshow -i dummy
```

Copy the **audio** device name into `audio=…`.

## Events

**QUERY** `string` *required*

`START`, `STOP`, or `CAPTURE <N> SECONDS`.

**SOURCE\_TOPIC** `string` *required*

Topic that runs the event.

**DESTINATION\_TOPIC** `string`

Override for this event. When omitted, chunks use the config topic.

| Query | Result |
| - | - |
| `START` | Stop any capture already running, then capture until `STOP` |
| `STOP` | Stop FFmpeg and stop publishing |
| `CAPTURE <N> SECONDS` | Capture for N seconds, then stop |

There is no audio callback on the connector. Control is only these queries.

## What arrives on the topic

Each payload is raw `s16le` bytes. At the defaults — 16 kHz, mono, 100 ms — one chunk is 3200 bytes, about 32 KB/s. That is small next to [Video Input](./video-input) JPEGs. Keep the default `CHUNK_MS` unless the consumer expects a different window. Do not retain the PCM topic; the next chunk replaces it immediately and retained audio is stale the moment it is stored.

Subscribe with any MQTT client that can show a binary payload. Do not JSON-parse the chunk.

### Wrap the bytes for gRPC

Publish PCM on your own topic (`audio/pcm/…`). When a service expects protobuf, a LoT action copies `PAYLOAD AS BYTES` into a model and publishes that message. A [gRPC connector](/latest/lot-language/routes/streaming/grpc) with `RPC_TYPE` `BIDI` can forward those bytes. Field layout is a [protobuf model](/latest/lot-language/models/protobuf): `bytes` fields use `ADD OBJECT`, assigned from the raw payload rather than from Base64.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ForwardPcmChunk
ON TOPIC "audio/pcm/builtin" DO
    PUBLISH TOPIC "audio/wrapped/builtin" WITH PAYLOAD AS BYTES
```

Use `GET ENV` or `GET SECRET` for device names and for any gRPC address. Keep the hot path in LoT. Do not shell out to a script to move each chunk.

## Docker and FFmpeg

Install FFmpeg on the broker host and confirm `ffmpeg -version` there. This is the same install as Video Input. The slim broker image includes FFmpeg on amd64 and arm64. The minimal image does not, and arm/v7 does not.

`anullsrc` and `tone:440` need no device mount, including inside Docker. A physical microphone has to be visible to FFmpeg on the broker host. macOS and Windows Docker Desktop usually cannot pass the host microphone into the Linux VM; run the broker on the host, or use a synthetic source, when you need audio in that setup.

## Best Practices

> **Test without hardware**
>
> `anullsrc` for silence and `tone:440` for a sine wave. Automated runs should not depend on a plugged-in microphone.

> **Keep device names out of LoT**
>
> On Windows, `WITH SOURCE GET ENV "AUDIO_SOURCE"` and set the variable to `audio=Exact Device Name`.

> **Leave PCM as bytes**
>
> Downstream models and connectors should read the payload as bytes. Parsing it as JSON or as a string yields an empty or garbage field.

> **Match the chunk the consumer expects**
>
> 100 ms at 16 kHz mono is the default. Change `SAMPLE_RATE`, `CHANNELS`, or `CHUNK_MS` only when the next service requires a different window.

## Troubleshooting

> **The connector is added but no chunks appear**
>
> FFmpeg is missing or not on `PATH`. Run `ffmpeg -version` on the broker host, or use the slim image.

> **mic:0 is rejected on Windows**
>
> Indexed microphones are not supported. List DirectShow devices and set `audio=<exact name>`.

> **A protobuf audio field is empty**
>
> The chunk was read as text or JSON. Assign the MQTT payload with `PAYLOAD AS BYTES` into an `ADD OBJECT` bytes field. See [protobuf models](/latest/lot-language/models/protobuf).

> **A REST call sends the text System.Byte\[]**
>
> A body template such as `{payload}` stringifies the buffer. Omit `BODY` on the REST event so the connector posts the raw bytes as `application/octet-stream`.

## Next Steps

> **[Video Input](./video-input)**
>
> Capture JPEG frames with the same FFmpeg setup on the broker host.

> **[gRPC Connector](/latest/lot-language/routes/streaming/grpc)**
>
> Forward wrapped audio on a bidirectional call.


# Barcode Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/media/barcode

Decode barcode images from MQTT and encode text as PNG or PDF symbols with TYPE BARCODE

## Read and draw barcodes on MQTT

The Barcode connector turns an image on a topic into the text inside the symbol, or turns text into a PNG or PDF you can display and print. Point a camera connector at the decode event when the image is already a frame on MQTT.

> [!TIP]
>
> **Like a checkout scanner.** You show it a picture of the code (decode), or you hand it the product number and it prints the label (encode).

### When to use this

Use `TYPE BARCODE` when a camera, file, or upstream system already has the image, or when you need to generate a QR, retail, or 2D symbol from text. Limit `SUPPORTED_FORMATS` to the families you actually scan so detection stays fast.

***

Each tab below is a complete connector. Publish an image to the decode topic, or a JSON request to the encode topic.

## Quick Start

**Decode an image**

Read a symbol from a base64 image and publish JSON, plus an annotated copy of the frame:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BarcodeScanner WITH TYPE BARCODE
    ADD BARCODE_CONFIG
        WITH SUPPORTED_FORMATS "QR_CODE,CODE_128,EAN_13,UPC_A"
    ADD EVENT ScanBarcode
        WITH MODE "DECODE"
        WITH SOURCE_TOPIC "camera/frame"
        WITH DESTINATION_TOPIC "barcode/decoded"
        WITH ANNOTATED_IMAGE_TOPIC "barcode/annotated"
        WITH ENABLE_ANNOTATION "true"
        WITH ANNOTATION_COLOR "Blue"
        WITH ANNOTATION_THICKNESS "3"
```

**Encode a symbol**

Generate a PNG from a JSON request on `barcode/generate`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR BarcodeGenerator WITH TYPE BARCODE
    ADD BARCODE_CONFIG
        WITH SUPPORTED_FORMATS "QR_CODE,CODE_128"
    ADD EVENT GenerateBarcode
        WITH MODE "ENCODE"
        WITH SOURCE_TOPIC "barcode/generate"
        WITH DESTINATION_TOPIC "barcode/image"
```

**Line scanner**

Decode two cameras on one connector, and annotate only the serial camera:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionScanner WITH TYPE BARCODE
    ADD BARCODE_CONFIG
        WITH SUPPORTED_FORMATS "CODE_128,DATA_MATRIX"
    ADD EVENT ScanProduct
        WITH MODE "DECODE"
        WITH SOURCE_TOPIC "line/camera/frame"
        WITH DESTINATION_TOPIC "line/product/scanned"
    ADD EVENT ScanSerial
        WITH MODE "DECODE"
        WITH SOURCE_TOPIC "line/serial/frame"
        WITH DESTINATION_TOPIC "line/serial/decoded"
        WITH ENABLE_ANNOTATION "true"
        WITH ANNOTATED_IMAGE_TOPIC "line/serial/annotated"
```

***

## Configuration

**SUPPORTED\_FORMATS** `string`

Comma-separated format names. Omit it to allow every format in the table below. Names are uppercase (`QR_CODE`, not `qr_code`).

### Supported formats

| Format | Kind |
| - | - |
| `QR_CODE` | 2D |
| `CODE_128` | 1D |
| `CODE_39` | 1D |
| `EAN_13` | 1D retail |
| `EAN_8` | 1D retail |
| `UPC_A` | 1D retail |
| `UPC_E` | 1D retail |
| `PDF_417` | 2D stacked |
| `DATA_MATRIX` | 2D |
| `AZTEC` | 2D |
| `ITF` | 1D |
| `MSI` | 1D |
| `PLESSEY` | 1D |
| `CODABAR` | 1D |
| `RSS_14` | 1D |
| `RSS_EXPANDED` | 1D |
| `MAXICODE` | 2D |

## Events

Every event sets `MODE` to `DECODE` or `ENCODE`.

**MODE** `string` *required*

`DECODE` reads a symbol from an image. `ENCODE` draws a symbol from JSON.

**SOURCE\_TOPIC** `string` *required*

Topic that triggers the event. Decode expects an image. Encode expects JSON.

**DESTINATION\_TOPIC** `string` *required*

Topic for the JSON result.

### Decode

Publish the image as a raw base64 string. A data-URI prefix such as `data:image/jpeg;base64,` is accepted. A [Video Input](./video-input) frame is already in that form, so you can set the decode `SOURCE_TOPIC` to the camera's frame topic.

> **Annotation**
>
> **ENABLE\_ANNOTATION** `string`
>
> `true` or `false`. Default: `true`. Draws a box around the symbol that was read.
>
> **ANNOTATED\_IMAGE\_TOPIC** `string`
>
> Topic for the annotated image. The payload is a raw base64 string, same shape as the input image.
>
> **ANNOTATION\_COLOR** `string`
>
> Color name, for example `Red` or `Blue`. Default: `Red`.
>
> **ANNOTATION\_THICKNESS** `string`
>
> Line thickness as an integer. Default: `5`.

A successful decode publishes JSON like this:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "success": true,
  "text": "Decoded barcode text",
  "format": "QR_CODE",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "route_name": "BarcodeScanner",
  "event_name": "ScanBarcode"
}
```

When no symbol is found, `success` is `false` and `error` explains why (for example `No barcode found in image`). Check `success` before you trust `text`.

Large frames are scaled down before detection. If a sharp 1080p frame still fails, publish a 1280×720 or 640×480 image instead.

### Encode

Publish JSON on the encode `SOURCE_TOPIC`. `text` is the payload to draw. `format` must be one of the names in `SUPPORTED_FORMATS`.

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "text": "Product-12345",
  "format": "QR_CODE",
  "width": 300,
  "height": 300,
  "margin": 0,
  "output_type": "IMAGE"
}
```

| Field | Default | Role |
| - | - | - |
| `text` | — | Content to encode |
| `format` | — | Symbol family, uppercase |
| `width` / `height` | — | Pixel size of the symbol |
| `margin` | `0` | Quiet zone around the symbol |
| `output_type` | `IMAGE` | `IMAGE` (PNG data-URI) or `PDF` |

An image result includes `image_base64` (`data:image/png;base64,…`). A PDF result includes `pdf_base64` (`data:application/pdf;base64,…`). Both include `success`, `text`, `format`, `output_type`, `width`, `height`, `timestamp`, `route_name`, and `event_name`.

> **PDF page placement**
>
> Set `output_type` to `PDF` and add `pdf_options`. Units are points (A4 is 595 × 842).
>
> | Field | Default | Role |
> | - | - | - |
> | `page_width` | `595` | Page width |
> | `page_height` | `842` | Page height |
> | `x_position` | `50` | Left edge of the symbol |
> | `y_position` | `750` | Baseline position on the page |
> | `include_text` | `true` | Print the encoded text on the page |
> | `text_below` | `true` | Place that text under the symbol |
> | `font_size` | `12` | Text size |
>
> ```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
> {
>   "text": "1234567890123",
>   "format": "EAN_13",
>   "width": 300,
>   "height": 100,
>   "output_type": "PDF",
>   "pdf_options": {
>     "page_width": 595,
>     "page_height": 842,
>     "x_position": 50,
>     "y_position": 750,
>     "include_text": true,
>     "text_below": true,
>     "font_size": 12
>   }
> }
> ```

## Trigger from an action

Publish the image or the encode JSON straight to `SOURCE_TOPIC`, or hand the payload to a named event:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DecodeBarcodeFromImage
ON TOPIC "camera/capture" DO
    TRIGGER "BarcodeScanner" TO PAYLOAD FOR "ScanBarcode"
```

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION GenerateQRCode
ON TOPIC "qr/generate" DO
    SET "data" WITH CLEAN:{text: {value.json.text}, format: "QR_CODE", width: 300, height: 300, output_type: "IMAGE"}
    TRIGGER "BarcodeGenerator" TO {data} FOR "GenerateBarcode"
```

## Best Practices

> **Image quality**
>
> Use a sharp, evenly lit frame. Blur and glare are the usual reason decode returns `No barcode found in image`. For retail codes, 640×480 to 1280×720 is enough.

> **Format selection**
>
> QR for URLs and mixed content. EAN-13 and UPC-A for retail. Code 128 for alphanumeric IDs. List only those names in `SUPPORTED_FORMATS`.

> **Errors**
>
> Branch on `success`. A `false` result still arrives on `DESTINATION_TOPIC`, so a downstream action should not treat every message as a good scan.

## Troubleshooting

> **No barcode found in image**
>
> Confirm the symbol is in frame and the format name is listed in `SUPPORTED_FORMATS`. Retry with a smaller, sharper image.

> **Invalid barcode format**
>
> Use the uppercase names from the format table, spelled exactly, and include that name in `SUPPORTED_FORMATS`.

> **Base64 decode error**
>
> The payload must be the base64 image, with or without a `data:image/…;base64,` prefix, and with no extra characters around it.

## Next Steps

> **[Video Input](./video-input)**
>
> Publish camera frames, then point a decode event at that topic.

> **[Media Connectors](./overview)**
>
> Choose barcode, video, or audio.


# Media Connectors
Source: https://docs.coreflux.org/latest/lot-language/routes/media/overview

Decode barcodes, capture camera frames, and publish microphone audio as MQTT from the broker host

## Why Media Connectors?

Give the broker a way to read images, cameras, and microphones without a sidecar process. A barcode scan, a camera frame, and a microphone chunk each become an MQTT message you can route, store, or wrap in LoT (Language of Things).

> [!TIP]
>
> **Like adding eyes and ears to the broker.** A camera frame or a microphone chunk arrives on a topic, and the rest of your project treats it like any other message.

## When to use these

| Connector | Use it when you need to |
| - | - |
| [Barcode](./barcode) | Read a code from an image, or draw a QR, EAN, or Code 128 image from text |
| [Video Input](./video-input) | Publish JPEG frames from a camera, RTSP/HTTP stream, or video file |
| [Audio Input](./audio-input) | Publish raw microphone, tone, silence, or file audio as PCM chunks |

> **[Barcode](./barcode)**
>
> Decode barcode images and encode text as QR, retail, and 2D symbols.

> **[Video Input](./video-input)**
>
> Capture JPEG frames from a camera, stream, or file on the broker host.

> **[Audio Input](./audio-input)**
>
> Capture raw 16-bit PCM from a microphone, a synthetic source, or a file.

***

Video Input and Audio Input both launch FFmpeg on the broker host. Install FFmpeg on that host, or run the slim broker image (amd64 and arm64), which already includes it. The minimal image does not include FFmpeg, and arm/v7 does not either.

Barcode does not use FFmpeg. It reads and writes images that are already on MQTT.

## Next Steps

> **[Barcode Connector](./barcode)**
>
> Decode a camera image or generate a label.

> **[Connectors Overview](../overview)**
>
> See every connector family and the shared `DEFINE CONNECTOR` pattern.


# Video Input Connector
Source: https://docs.coreflux.org/latest/lot-language/routes/media/video-input

Capture JPEG frames from a camera, RTSP or HTTP stream, or file with TYPE VIDEO_INPUT and FFmpeg

## Publish camera frames to MQTT

Video Input opens a camera, network stream, or file on the broker host and publishes each frame as a JPEG data-URI. Dashboards and Coreflux HUB can drop that payload straight into an image tag. You start and stop capture with MQTT events.

> [!TIP]
>
> **Like a photo booth on a timer.** You press start, and a new picture lands on the topic at the rate you chose — not a video file, a series of JPEGs.

### When to use this

Use `TYPE VIDEO_INPUT` when a dashboard, barcode decode, or action needs still frames from a local camera, an RTSP or HTTP(S) camera, or a video file. FFmpeg must be on the broker host (or in the slim image). The connector does not talk to camera drivers itself.

> [!NOTE]
>
> Do not set `WITH FORMAT`. That keyword belongs to models. Every frame this connector publishes is a JPEG data-URI (`data:image/jpeg;base64,…`).

***

Pick the source that matches the camera. Each tab is a full connector: a config block plus start and stop events.

## Quick Start

**IP camera**

Store the RTSP URL in an environment variable so the password never sits in LoT:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EntranceCamera WITH TYPE VIDEO_INPUT
    ADD VIDEO_INPUT_CONFIG
        WITH SOURCE GET ENV "CAMERA_RTSP_URL"
        WITH FRAME_RATE "10"
        WITH WIDTH "640"
        WITH HEIGHT "480"
        WITH QUALITY "5"
        WITH DESTINATION_TOPIC "video/entrance/frames"
    ADD EVENT StartCapture
        WITH QUERY "START"
        WITH SOURCE_TOPIC "video/entrance/control/start"
    ADD EVENT StopCapture
        WITH QUERY "STOP"
        WITH SOURCE_TOPIC "video/entrance/control/stop"
```

**Local camera**

On macOS and Linux, `webcam:0` is the first camera. On Linux that is `/dev/video0`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR LocalCamera WITH TYPE VIDEO_INPUT
    ADD VIDEO_INPUT_CONFIG
        WITH SOURCE "webcam:0"
        WITH FRAME_RATE "5"
        WITH WIDTH "640"
        WITH HEIGHT "480"
        WITH QUALITY "5"
        WITH DESTINATION_TOPIC "video/local/frames"
    ADD EVENT StartCapture
        WITH QUERY "START"
        WITH SOURCE_TOPIC "video/local/control/start"
    ADD EVENT StopCapture
        WITH QUERY "STOP"
        WITH SOURCE_TOPIC "video/local/control/stop"
    ADD EVENT TakeSnapshot
        WITH QUERY "CAPTURE 1 FRAME"
        WITH SOURCE_TOPIC "video/local/control/snapshot"
        WITH DESTINATION_TOPIC "video/local/picture"
```

**Windows camera**

Copy the video device name from the DirectShow list. The `video=` prefix is required:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WindowsCamera WITH TYPE VIDEO_INPUT
    ADD VIDEO_INPUT_CONFIG
        WITH SOURCE "video=Integrated Webcam"
        WITH FRAME_RATE "5"
        WITH WIDTH "640"
        WITH HEIGHT "480"
        WITH QUALITY "5"
        WITH DESTINATION_TOPIC "video/windows/frames"
    ADD EVENT StartCapture
        WITH QUERY "START"
        WITH SOURCE_TOPIC "video/windows/control/start"
    ADD EVENT StopCapture
        WITH QUERY "STOP"
        WITH SOURCE_TOPIC "video/windows/control/stop"
```

**File**

Play a file on the broker host. On Windows, use a path FFmpeg accepts, such as `C:/media/sample.mp4`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR FileCamera WITH TYPE VIDEO_INPUT
    ADD VIDEO_INPUT_CONFIG
        WITH SOURCE "/var/media/sample.mp4"
        WITH FRAME_RATE "5"
        WITH DESTINATION_TOPIC "video/file/frames"
    ADD EVENT StartCapture
        WITH QUERY "START"
        WITH SOURCE_TOPIC "video/file/control/start"
    ADD EVENT StopCapture
        WITH QUERY "STOP"
        WITH SOURCE_TOPIC "video/file/control/stop"
```

Publish any payload to the start topic to begin. Frames then arrive on `DESTINATION_TOPIC` until you publish to the stop topic.

***

## Configuration

**SOURCE** `string` *required*

Camera, URL, or file. `webcam:N` on macOS and Linux. `video=Device Name` on Windows. An `rtsp://`, `http://`, or `https://` URL, or a file path, on any host. Prefer `GET ENV` or `GET SECRET` when the URL contains a password.

**DESTINATION\_TOPIC** `string`

MQTT topic for JPEG frames. A `START` event uses this topic. A `CAPTURE` event can override it.

**FRAME\_RATE** `string`

How many frames to publish per second, from `1` to `60`. On a local camera this is the publish rate. Many cameras only capture at 15 or 30 fps in hardware; `5` still works as the rate on the topic.

**WIDTH** `string`

Output width in pixels. Set it together with `HEIGHT`.

**HEIGHT** `string`

Output height in pixels. Set it together with `WIDTH`.

**QUALITY** `string`

JPEG quantizer from `1` to `31`. Lower numbers keep more detail and publish larger payloads. `5` is a balanced start. This is not a 1–100 percentage.

`WIDTH`, `HEIGHT`, and `QUALITY` apply to the JPEG on MQTT. They do not reconfigure the camera's own encoder.

Broker logs redact `user:pass@` in RTSP and HTTP URLs. HTTP(S) sources use a 10 second timeout and the user-agent `CorefluxVideoInput/1.0`. RTSP uses TCP with the same timeout.

## Capture sources

| `SOURCE` | Broker host | What opens |
| - | - | - |
| `webcam:0` | macOS | First camera in the system list (built-in on many Macs) |
| `webcam:1` | macOS | Second camera, often USB |
| `webcam:0` | Linux | `/dev/video0` |
| `video=Integrated Webcam` | Windows | DirectShow device. The name must match exactly |
| `rtsp://…`, `http://…`, `https://…` | Any | Network stream. One attempt, no local-camera retry |
| File path | Any | File input |

`webcam:N` is rejected on Windows. Device indexes are not stable in DirectShow, so use `video=` plus the exact name. A raw `/dev/video0`, or a Windows name without `video=`, is treated as a file path and skips the local-camera retries.

On start, a local camera tries several input profiles until one stays open. Network URLs and files are a single attempt.

### List devices on the broker host

| Host | Command |
| - | - |
| Linux | `ls -l /dev/video*` — `webcam:0` is `/dev/video0` |
| macOS | `ffmpeg -f avfoundation -list_devices true -i ""` |
| Windows | `ffmpeg -list_devices true -f dshow -i dummy` — copy the **video** name into `video=…` |

If macOS capture fails immediately, allow Camera access for the process that started the broker.

## Events

**QUERY** `string` *required*

`START`, `STOP`, `CAPTURE <N> FRAMES`, `CAPTURE <N> SECONDS`, or `CAPTURE <N> MINUTES`. `CAPTURE 1` and `CAPTURE 1 FRAME` take one picture.

**SOURCE\_TOPIC** `string` *required*

Topic that runs the event. Keep control topics separate from the frame topic.

**DESTINATION\_TOPIC** `string`

Override for a snapshot or a timed clip. Continuous `START` uses the topic on `VIDEO_INPUT_CONFIG`.

| Query | Result |
| - | - |
| `START` | Capture until `STOP` |
| `STOP` | Stop every capture on this connector |
| `CAPTURE 1 FRAME` | One JPEG |
| `CAPTURE <N> FRAMES` | That many frames |
| `CAPTURE <N> SECONDS` | Frames for N seconds |
| `CAPTURE <N> MINUTES` | Frames for N minutes |

There is no motion or per-frame callback on the connector. Every decoded frame goes to `DESTINATION_TOPIC`. Failures show up in the broker log and on `$SYS/Coreflux/Routes/{RouteName}/status`. You can also publish `-checkConnectorConnection <RouteName>` to `$SYS/Coreflux/Command`.

An action can start a named event without a control publish:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION StartEntranceCamera
ON TOPIC "control/video/start" DO
    TRIGGER "EntranceCamera" TO PAYLOAD FOR "StartCapture"
```

## Docker and FFmpeg

Install FFmpeg on the broker host and confirm `ffmpeg -version` there. The slim broker image includes FFmpeg on amd64 and arm64. The minimal image does not, and arm/v7 does not.

RTSP and HTTP work in Docker with no camera hardware. A local camera needs the device node inside the container.

| Where the broker runs | Local camera | Without a device mount |
| - | - | - |
| Linux container | Pass `--device /dev/video0` (or the matching node). Inside the image, `webcam:0` is `/dev/video0` | RTSP, HTTP, or a file |
| macOS or Windows Docker Desktop | The camera stays on the desktop host, not in the Linux VM | RTSP, HTTP, or a file |

## Payload size

JPEG on MQTT is much larger than sensor telemetry. Start at 5 fps, 640×480, and `QUALITY` `5`. If subscribers or the HUB fall behind, lower `FRAME_RATE` or raise `QUALITY` (a larger quantizer) before you increase width and height.

For a live camera, shed frames instead of blocking publishers:

```lot wrap focus={8-9} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EntranceCamera WITH TYPE VIDEO_INPUT
    ADD VIDEO_INPUT_CONFIG
        WITH SOURCE GET ENV "CAMERA_RTSP_URL"
        WITH FRAME_RATE "5"
        WITH WIDTH "640"
        WITH HEIGHT "480"
        WITH QUALITY "5"
        WITH DESTINATION_TOPIC "video/entrance/frames"
    ADD CONNECTOR_CONFIG
        WITH OVERLOAD_POLICY "realtime"
    ADD EVENT StartCapture
        WITH QUERY "START"
        WITH SOURCE_TOPIC "video/entrance/control/start"
    ADD EVENT StopCapture
        WITH QUERY "STOP"
        WITH SOURCE_TOPIC "video/entrance/control/stop"
```

See [Connector overload](../store-and-forward).

## Pair with Video Output

`TYPE VIDEO_OUTPUT` serves those JPEGs as an HTTP MJPEG stream. Set its source topic to this connector's frame topic.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR OperatorView WITH TYPE VIDEO_OUTPUT
    ADD VIDEO_OUTPUT_CONFIG
        WITH SOURCE_TOPIC "video/entrance/frames"
        WITH OUTPUT_PROTOCOL "HTTP"
        WITH OUTPUT_PATH ":8080/entrance"
    ADD EVENT StartView
        WITH QUERY "START"
```

Operators open `http://<broker-host>:8080/entrance`.

The same frame topic can feed a [Barcode](./barcode) decode event. [Audio Input](./audio-input) is the microphone equivalent: raw PCM chunks instead of JPEGs, also through FFmpeg.

## Best Practices

> **Keep secrets out of LoT**
>
> `WITH SOURCE GET ENV "CAMERA_RTSP_URL"` or `GET SECRET`. Do not paste `rtsp://user:password@…` into the connector.

> **Match the host**
>
> `webcam:N` on macOS and Linux. `video=Exact Name` on Windows. A missing `video=` prefix is opened as a file.

> **Separate control from frames**
>
> Put `START` and `STOP` on `…/control/…` topics. Publishing `START` on the frame topic mixes commands with JPEG payloads.

> **Prefer a network camera in Docker Desktop**
>
> USB cameras rarely appear inside macOS or Windows Docker Desktop. Use RTSP or HTTP unless the broker runs on Linux with a device mount.

## Troubleshooting

> **FFmpeg is missing**
>
> `ffmpeg -version` on the broker host. Install FFmpeg there, or switch to the slim image.

> **webcam:0 opens as a file**
>
> Use `webcam:0` on macOS and Linux. On Windows use `video=` plus the DirectShow name.

> **Linux device missing**
>
> `ls -l /dev/video*`. Plug in the camera or pass `--device /dev/video0` into the container.

> **Windows rejects webcam:N**
>
> List devices with `ffmpeg -list_devices true -f dshow -i dummy` and set `WITH SOURCE "video=…"`.

> **macOS permission or a busy camera**
>
> Grant Camera access to the process that launched the broker. Close other apps using the camera. Try `webcam:1` for a USB camera.

> **RTSP or HTTP never starts**
>
> The timeout is 10 seconds. From the broker host, confirm the URL is reachable and that RTSP allows TCP. Put the full URL in `GET ENV`.

> **Dashboards stall**
>
> Lower `FRAME_RATE`, shrink `WIDTH` and `HEIGHT`, or raise `QUALITY`. Add `ADD CONNECTOR_CONFIG` with `OVERLOAD_POLICY` `realtime` (`ADD ROUTE_CONFIG` remains a supported alias).

## Next Steps

> **[Audio Input](./audio-input)**
>
> Publish microphone PCM the same way, through FFmpeg on the broker host.

> **[Barcode Connector](./barcode)**
>
> Decode a symbol from the JPEG topic.


# Sight Machine
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sight-machine

LoT REST API connector for Sight Machine: read machines, cycles, downtime, parts, KPIs, Data Viz results and dashboard values from MQTT on your tenant

Technical Preview

## Overview

[Sight Machine](https://sightmachine.com) is a Manufacturing Data Platform. It models plant data as machines, cycles, downtime, parts and production lines, and computes KPIs such as OEE, quality and availability. This connector connects the Coreflux broker to the REST API of your Sight Machine tenant, so plant logic on MQTT can read production data, KPI results, recipe recommendations and dashboard values without custom code.

* **SightMachineApi** (`SightMachineRestApi.lot`) is a client connector on `https://YOUR_TENANT.sightmachine.io` with 24 events.

> [!WARNING]
>
> Sight Machine does not publish its API reference. Each tenant serves it to logged-in users at `https://<tenant>.sightmachine.io/#/api-docs`. These events come only from public first-party sources: the [API Keys and Dashboard API page](https://docs.sightmachine.com/docs/apis) and the [Sight Machine Python SDK](https://github.com/sightmachine/sightmachine-sdk) (`smsdk`), which calls these endpoints. Request bodies follow the SDK. Check the response shapes against your tenant's API reference before you rely on them.

Every path and method was checked on a live Sight Machine tenant. Each event is rejected for an invalid key, while unknown paths return `404` and wrong methods return `405` (see Status).

## Tenant host

Each customer gets its own tenant at `https://<tenant>.sightmachine.io`. Replace `YOUR_TENANT` in `BASE_ADDRESS` with your tenant name, with no trailing slash. For a private or dedicated deployment, use the host Sight Machine gave you.

## Authentication

> [!WARNING]
>
> The API key and secret act as your Sight Machine user. Keep them in Hub secrets, map them in with `GET SECRET`, and never publish them on a topic other clients can read.

1. In your tenant, open **User Profile** (top right), scroll to **Security** and click **Create API Key**. Copy the API key and secret.
2. Every event takes `"api_key_id"` and `"api_secret"` in its MQTT payload. The connector sends them as `X-SM-API-Key-Id` and `X-SM-API-Secret`. `ListFactories` (legacy `/api`) also sends `X-SM-API-Key` with the secret, like the SDK does.

Suggested secrets: `SIGHTMACHINE_API_KEY_ID` and `SIGHTMACHINE_API_SECRET`. A missing or wrong key returns `401` with `{"error":"unauthenticated","description":"Not logged in or invalid API key provided"}`.

> [!NOTE]
>
> Edge API keys (the **CONNECT** menu) are a different credential. FactoryTX uses them to upload data. If your tenant uses workspaces, the SDK selects one with an `X-Sm-Workspace-Id` header. This template does not send that header, so add it to the events if you need it.

## Payload conventions

* **Queries.** The `/v1/datatab/...`, estimate, KPI, Data Viz, line Data Viz and cookbook current-value events are read-only `POST` queries. Each one sends `"body"` unchanged. The body is the SDK query object: `asset_selection`, `select`, `where` (`name`, `op`, `value`), `order_by`, `time_selection` (relative or absolute), `offset`, `limit` and `db_mode` (`"sql"`). See the [SDK reference](https://github.com/sightmachine/sightmachine-sdk/blob/master/docs/README.md) for every field.
* **Names.** Use system names in queries: `machine_source` (for example `Oven_1`), `machine_type` (`Oven`), field names from `GetMachineTypeFields`, and part types from `ListPartTypes`. `ListMachines` and `ListMachineTypes` map display names to system names.
* **Query strings.** Events with `?{query}` take a pre-encoded query string. Send `""` for none. `ListMachines` takes `limit` plus `where`, `order_by` and `select` as URL-encoded JSON.
* **Paging.** Data table events return up to `limit` rows (at most 50000) under `results`. Page with `offset`.
* **Asynchronous Data Viz.** `SubmitDataVizTask` and `SubmitLineVizTask` return `response.task_id`. Poll `GetDataVizTask` or `GetLineVizTask` until `response.state` is `SUCCESS`, then read `response.meta.results`. `FAILURE` and `REVOKED` mean the query failed.

## Assets and metadata

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListAssets | `GET /v1/selector/assets` | `mes/sight-machine/asset/list` | Credential check: machines, lines and KPIs the key can see (the SDK's own login check). Response has machine, line and kpi lists |
| ListMachines | `GET /v1/obj/machine?{query}` | `mes/sight-machine/machine/list` | Machines with metadata (source, source\_clean, source\_type, timezone ...); query limit, where, order\_by, select (send "" for none) |
| ListMachineTypes | `GET /v1/obj/machine_type?{query}` | `mes/sight-machine/machine-type/list` | Machine types (source\_type, source\_type\_clean, stats ...); send query "" for none |
| GetMachineTypeFields | `GET /v1/selector/datatab/cycle/{machine_type}/field?{query}` | `mes/sight-machine/machine-type-field/list` | Cycle schema of a machine type: fields with name, display\_name, type, data\_type, unit, stream\_types, raw\_data\_field |
| ListPartTypes | `GET /v1/obj/part_type?{query}` | `mes/sight-machine/part-type/list` | Part types configured on the tenant |
| GetPartTypeFields | `GET /v1/selector/datatab/part/{part_type}/field?db_mode=sql&strip_aliases=false` | `mes/sight-machine/part-type-field/list` | Part schema of a part type (fields, types, units) |
| ListFactories | `GET /api/factory?{query}` | `mes/sight-machine/factory/list` | Factories (sites) with timezone and metadata. Legacy /api surface: also sends X-SM-API-Key like the SDK |

**ListMachines** (`mes/sight-machine/machine/list`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "query": "limit=100"
}
```

**GetMachineTypeFields** (`mes/sight-machine/machine-type-field/list`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "machine_type": "Oven",
  "query": "_offset=0&_limit=2000"
}
```

## Production data (cycles, downtime, parts, lines, raw data)

| Event | Request | Topic | Notes |
| - | - | - | - |
| QueryCycles | `POST /v1/datatab/cycle` | `mes/sight-machine/cycle/query` | Catalog: cycles of a machine (one row per production cycle with its fields); read-only query, page with offset / limit (max 50000) |
| QueryDowntimes | `POST /v1/datatab/downtime` | `mes/sight-machine/downtime/query` | Downtime events of a machine (start, end, duration, reason, category, type); read-only query |
| QueryParts | `POST /v1/datatab/part` | `mes/sight-machine/part/query` | Parts of a part type (one row per serialized part, joined across machines); read-only query |
| QueryLineData | `POST /v1/datatab/line` | `mes/sight-machine/line-data/query` | Line data: one unified table across the machines of a production line; read-only query |
| QueryRawData | `POST /v1/datatab/raw_data` | `mes/sight-machine/raw-data/query` | Catalog: raw sensor records of a raw data table (before cycle modelling); read-only query, not an ingest |

**QueryCycles** (`mes/sight-machine/cycle/query`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "body": {
    "asset_selection": {
      "machine_source": "Oven_1",
      "machine_type": "Oven"
    },
    "select": [
      {
        "name": "endtime"
      },
      {
        "name": "machine__source"
      },
      {
        "name": "total"
      }
    ],
    "where": [
      {
        "name": "endtime",
        "op": "gte",
        "value": "2026-10-05T00:00:00"
      },
      {
        "name": "endtime",
        "op": "lt",
        "value": "2026-10-06T00:00:00"
      }
    ],
    "order_by": [
      {
        "name": "endtime",
        "order": "desc"
      }
    ],
    "offset": 0,
    "limit": 400,
    "db_mode": "sql"
  }
}
```

**QueryDowntimes** (`mes/sight-machine/downtime/query`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "body": {
    "asset_selection": {
      "machine_source": "Oven_1",
      "machine_type": "Oven"
    },
    "select": [
      {
        "name": "machine__source"
      },
      {
        "name": "starttime"
      },
      {
        "name": "endtime"
      },
      {
        "name": "total"
      },
      {
        "name": "reason"
      },
      {
        "name": "category"
      },
      {
        "name": "downtime_type"
      }
    ],
    "where": [
      {
        "name": "starttime",
        "op": "gte",
        "value": "2026-10-05T00:00:00"
      },
      {
        "name": "endtime",
        "op": "lt",
        "value": "2026-10-06T00:00:00"
      }
    ],
    "offset": 0,
    "limit": 400,
    "db_mode": "sql"
  }
}
```

**QueryRawData** (`mes/sight-machine/raw-data/query`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "body": {
    "asset_selection": {
      "raw_data_table": "oven_sensors"
    },
    "select": [
      {
        "name": "temperature"
      },
      {
        "name": "pressure"
      }
    ],
    "time_selection": {
      "time_type": "absolute",
      "start_time": "2026-10-05T00:00:00.000Z",
      "end_time": "2026-10-06T00:00:00.000Z",
      "time_zone": "Europe/Lisbon"
    },
    "db_mode": "sql",
    "offset": 0,
    "limit": 400
  }
}
```

## Counts

| Event | Request | Topic | Notes |
| - | - | - | - |
| EstimateCycleCount | `POST /v1/selector/datavis/estimate/cycle` | `mes/sight-machine/cycle-count/get` | Estimated cycle count of a machine type in a time window (read-only) |
| EstimatePartCount | `POST /v1/selector/datavis/estimate/part` | `mes/sight-machine/part-count/get` | Estimated part count of a part type in a time window (read-only) |

**EstimateCycleCount** (`mes/sight-machine/cycle-count/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "body": {
    "model": "cycle:Oven",
    "asset_selection": {
      "machine_source": [
        "Oven_1"
      ]
    },
    "time_selection": {
      "time_type": "absolute",
      "start_time": "2026-10-01T00:00:00",
      "end_time": "2026-10-06T00:00:00"
    },
    "limit": 1,
    "db_mode": "sql"
  }
}
```

## KPIs and Data Viz

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListKpisForAsset | `POST /v1/selector/datavis/kpi/y_axis` | `mes/sight-machine/kpi-asset/list` | Catalog: KPIs available for machines / machine types (quality, oee, availability, performance ...) |
| SubmitDataVizTask | `POST /v1/datavis/task/async` | `mes/sight-machine/datavis-task/create` | Catalog: start a Data Viz KPI query (OEE, quality, availability ... aggregated over time); returns response.task\_id. Read-only compute |
| GetDataVizTask | `GET /v1/datavis/task/async/{task_id}` | `mes/sight-machine/datavis-task/get` | Poll a Data Viz task: response.state PENDING / SUCCESS / FAILURE / REVOKED; results in response.meta.results |
| SubmitLineVizTask | `POST /v1/linevis/task/async` | `mes/sight-machine/linevis-task/create` | Start a line Data Viz query across the machines of a line; returns response.task\_id. Read-only compute |
| GetLineVizTask | `GET /v1/linevis/task/async/{task_id}` | `mes/sight-machine/linevis-task/get` | Poll a line Data Viz task (state, meta.results) |
| CreateShareLink | `POST /v1/obj/ui_share_state` | `mes/sight-machine/share-link/create` | Save a Data Viz chart state and get a shareable link (for alerts and shift reports); state\_hash is any 8-char id **(write)** |

**ListKpisForAsset** (`mes/sight-machine/kpi-asset/list`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "body": {
    "asset_selection": {
      "machine_type": [
        "Oven"
      ],
      "machine_source": [
        "Oven_1"
      ]
    },
    "db_mode": "sql"
  }
}
```

**SubmitDataVizTask** (`mes/sight-machine/datavis-task/create`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "body": {
    "model": "kpi",
    "asset_selection": {
      "machine_source": [
        "Oven_1"
      ],
      "machine_type": [
        "Oven"
      ]
    },
    "d_vars": [
      {
        "name": "oee",
        "aggregate": [
          "avg"
        ]
      },
      {
        "name": "quality",
        "aggregate": [
          "avg"
        ]
      }
    ],
    "i_vars": [
      {
        "name": "endtime",
        "time_resolution": "hour",
        "query_tz": "Europe/Lisbon",
        "output_tz": "Europe/Lisbon",
        "bin_strategy": "user_defined2",
        "bin_count": 50
      }
    ],
    "time_selection": {
      "time_type": "relative",
      "relative_start": 1,
      "relative_unit": "day",
      "ctime_tz": "Europe/Lisbon"
    },
    "where": [],
    "db_mode": "sql"
  }
}
```

**GetDataVizTask** (`mes/sight-machine/datavis-task/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "task_id": "<task id>"
}
```

## Cookbooks (recipes)

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListCookbooks | `GET /v1/obj/recipe/cookbook?{query}` | `mes/sight-machine/cookbook/list` | Cookbooks (recipe optimisation): recipe groups, levers, constraints, KPI |
| GetCookbookTopResults | `GET /v1/recipe/top_results/{recipe_group_id}?limit={limit}` | `mes/sight-machine/cookbook-top-results/get` | Best recipe runs of a recipe group (lever settings that gave the best KPI) |
| GetCookbookCurrentValues | `POST /v1/recipe/current_value` | `mes/sight-machine/cookbook-current-value/get` | Catalog: current value of levers / fields per machine (latest value within the last N minutes); read-only |

**GetCookbookCurrentValues** (`mes/sight-machine/cookbook-current-value/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "body": {
    "variables": [
      {
        "asset": "Oven_1",
        "name": "Temperature"
      },
      {
        "asset": "Oven_1",
        "name": "Pressure"
      }
    ],
    "minutes": 60
  }
}
```

## Dashboards

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetDashboardValues | `GET /v1/obj/dashboard/{dashboard_id}/full_values` | `mes/sight-machine/dashboard-values/get` | Catalog: resolved values of every background-loading widget of a dashboard (panels with id, name, type single \| table, status, data) |

**GetDashboardValues** (`mes/sight-machine/dashboard-values/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key_id": "<api key id>",
  "api_secret": "<api secret>",
  "dashboard_id": "65552e878f90924c54a3de7f"
}
```

The response has one entry per widget under `panels`, with `id`, `name`, `type` (`single` or `table`), `status` and `data`. Only Data Visualization and Single Value widgets set to [background loading](https://docs.sightmachine.com/docs/background-loading-for-widgets) return data. The others report `unsupported type`, `background loading not enabled` or `no completed jobs found`. The dashboard id is the last part of the dashboard URL.

## Sending plant data to Sight Machine

Sight Machine takes plant data in through FactoryTX, its edge data layer, not through a public REST write. Its upload endpoints are not published, so this template has no ingest event. To send Coreflux data to Sight Machine, point a FactoryTX [MQTT Data Receiver](https://docs.sightmachine.com/docs/mqtt-data-receiver) at the Coreflux broker. Sight Machine documents no webhooks, so this template has no receiver connector either.

## Examples

Helper actions (`docs-helper-actions.lot`): an OEE Data Viz query every 15 minutes with polling of the task, the dashboard values every hour, sent on to a plant topic, and current lever values every 5 minutes.

```
DEFINE ACTION SightMachinePollLineOee
ON EVERY 15 MINUTES DO
    SET "kid" WITH GET SECRET "SIGHTMACHINE_API_KEY_ID"
    SET "sec" WITH GET SECRET "SIGHTMACHINE_API_SECRET"
    PUBLISH TOPIC "mes/sight-machine/datavis-task/create" WITH { "api_key_id": {kid}, "api_secret": {sec}, "body": { "model": "kpi", "asset_selection": { "machine_source": ["Oven_1"], "machine_type": ["Oven"] }, "d_vars": [ { "name": "oee", "aggregate": ["avg"] } ], "i_vars": [ { "name": "endtime", "time_resolution": "hour", "query_tz": "Europe/Lisbon", "output_tz": "Europe/Lisbon", "bin_strategy": "user_defined2", "bin_count": 24 } ], "time_selection": { "time_type": "relative", "relative_start": 1, "relative_unit": "day", "ctime_tz": "Europe/Lisbon" }, "where": [], "db_mode": "sql" } }

DEFINE ACTION SightMachinePollDataVizTask
ON TOPIC "mes/sight-machine/datavis-task/create/response" DO
    SET "kid" WITH GET SECRET "SIGHTMACHINE_API_KEY_ID"
    SET "sec" WITH GET SECRET "SIGHTMACHINE_API_SECRET"
    SET "task" WITH (GET JSON "response.task_id" IN PAYLOAD AS STRING)
    KEEP TOPIC "internal/sight-machine/datavis-task" WITH {task}
    PUBLISH TOPIC "mes/sight-machine/datavis-task/get" WITH { "api_key_id": {kid}, "api_secret": {sec}, "task_id": {task} }

DEFINE ACTION SightMachineShiftDashboard
ON EVERY 1 HOUR DO
    SET "kid" WITH GET SECRET "SIGHTMACHINE_API_KEY_ID"
    SET "sec" WITH GET SECRET "SIGHTMACHINE_API_SECRET"
    SET "dash" WITH GET SECRET "SIGHTMACHINE_DASHBOARD_ID"
    PUBLISH TOPIC "mes/sight-machine/dashboard-values/get" WITH { "api_key_id": {kid}, "api_secret": {sec}, "dashboard_id": {dash} }

DEFINE ACTION SightMachineDashboardToPlant
ON TOPIC "mes/sight-machine/dashboard-values/get/response" DO
    PUBLISH TOPIC "plant/porto/sight-machine/dashboard" WITH PAYLOAD

DEFINE ACTION SightMachineCurrentLevers
ON EVERY 5 MINUTES DO
    SET "kid" WITH GET SECRET "SIGHTMACHINE_API_KEY_ID"
    SET "sec" WITH GET SECRET "SIGHTMACHINE_API_SECRET"
    PUBLISH TOPIC "mes/sight-machine/cookbook-current-value/get" WITH { "api_key_id": {kid}, "api_secret": {sec}, "body": { "variables": [ { "asset": "Oven_1", "name": "Temperature" }, { "asset": "Oven_1", "name": "Pressure" } ], "minutes": 60 } }
```

> [!NOTE]
>
> The helper actions read the key and secret with `GET SECRET` on every call. Restrict the `mes/sight-machine/#` request topics with broker ACLs, because the payloads carry the secret.

## Writes

Write events: CreateShareLink. `CreateShareLink` saves a Data Viz chart state on the tenant and returns a share link. Every other event is read-only, including the `POST` query events. No preset deletes anything.

## Not packaged

Data ingest (FactoryTX upload and RDPv3 endpoints are not published), password and SSO login (`/auth/password/login` sets a browser session cookie, so use API keys), the ODBC / JDBC connector (SQL, not REST), legacy `/api` cycle, part, machine and downtime endpoints (replaced by `/v1`), workspace selection (`X-Sm-Workspace-Id`), and any endpoint that appears only in the tenant's login-gated API reference.


# Slack REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/slack

Client-mode REST API connector for a small Slack Web API admin subset, triggered from MQTT

Technical Preview

## Overview

This client-mode connector calls the [Slack Web API](https://api.slack.com/web) so plant or ops events on MQTT can approve apps or manage conversations. The packaged events are eight **admin** methods only (`admin.apps.*`, `admin.conversations.*`). It does not include `chat.postMessage`.

> [!NOTE]
>
> The LoT file still sets `BASE_ADDRESS` to `https://api.example.com` because the source spec did not carry the Slack host. Change it to `https://slack.com/api` before you deploy.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Slack Web API
# Generated from OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

DEFINE CONNECTOR SlackRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Optional: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT AdminAppsApprove
        WITH SOURCE_TOPIC "integrations/slack/request/AdminAppsApprove"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminAppsApprove"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin.apps.approve"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT AdminAppsApprovedList
        WITH SOURCE_TOPIC "integrations/slack/request/AdminAppsApprovedList"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminAppsApprovedList"
        WITH METHOD "GET"
        WITH ENDPOINT "/admin.apps.approved.list"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT AdminAppsRequestsList
        WITH SOURCE_TOPIC "integrations/slack/request/AdminAppsRequestsList"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminAppsRequestsList"
        WITH METHOD "GET"
        WITH ENDPOINT "/admin.apps.requests.list"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT AdminAppsRestrict
        WITH SOURCE_TOPIC "integrations/slack/request/AdminAppsRestrict"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminAppsRestrict"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin.apps.restrict"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT AdminAppsRestrictedList
        WITH SOURCE_TOPIC "integrations/slack/request/AdminAppsRestrictedList"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminAppsRestrictedList"
        WITH METHOD "GET"
        WITH ENDPOINT "/admin.apps.restricted.list"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT AdminConversationsArchive
        WITH SOURCE_TOPIC "integrations/slack/request/AdminConversationsArchive"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminConversationsArchive"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin.conversations.archive"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT AdminConversationsConverttoprivate
        WITH SOURCE_TOPIC "integrations/slack/request/AdminConversationsConverttoprivate"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminConversationsConverttoprivate"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin.conversations.convertToPrivate"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT AdminConversationsCreate
        WITH SOURCE_TOPIC "integrations/slack/request/AdminConversationsCreate"
        WITH DESTINATION_TOPIC "integrations/slack/response/AdminConversationsCreate"
        WITH METHOD "POST"
        WITH ENDPOINT "/admin.conversations.create"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| AdminAppsApprove | POST | `/admin.apps.approve` | `integrations/slack/request/AdminAppsApprove` | `integrations/slack/response/AdminAppsApprove` |
| AdminAppsApprovedList | GET | `/admin.apps.approved.list` | `integrations/slack/request/AdminAppsApprovedList` | `integrations/slack/response/AdminAppsApprovedList` |
| AdminAppsRequestsList | GET | `/admin.apps.requests.list` | `integrations/slack/request/AdminAppsRequestsList` | `integrations/slack/response/AdminAppsRequestsList` |
| AdminAppsRestrict | POST | `/admin.apps.restrict` | `integrations/slack/request/AdminAppsRestrict` | `integrations/slack/response/AdminAppsRestrict` |
| AdminAppsRestrictedList | GET | `/admin.apps.restricted.list` | `integrations/slack/request/AdminAppsRestrictedList` | `integrations/slack/response/AdminAppsRestrictedList` |
| AdminConversationsArchive | POST | `/admin.conversations.archive` | `integrations/slack/request/AdminConversationsArchive` | `integrations/slack/response/AdminConversationsArchive` |
| AdminConversationsConverttoprivate | POST | `/admin.conversations.convertToPrivate` | `integrations/slack/request/AdminConversationsConverttoprivate` | `integrations/slack/response/AdminConversationsConverttoprivate` |
| AdminConversationsCreate | POST | `/admin.conversations.create` | `integrations/slack/request/AdminConversationsCreate` | `integrations/slack/response/AdminConversationsCreate` |

## Auth

Slack expects a bot or user token as Bearer:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Authorization" "Bearer {value.json.api_token}"
```

**BASE\_ADDRESS** `string` *required*

Set to `https://slack.com/api` (the file default is a placeholder).

**api\_token** `string` *required*

Slack token with the admin scopes those methods need. Pass it on the MQTT payload. Prefer a Hub secret or `GET SECRET` upstream. Never commit the token.

POST events send `{payload}` as JSON. Put method arguments in that body (Slack also accepts form bodies; this template uses `application/json`).

## Try it

1. Fix `BASE_ADDRESS` to `https://slack.com/api`, then add the connector on your broker.
2. Publish `{"api_token": "YOUR_SLACK_TOKEN"}` to `integrations/slack/request/AdminAppsApprovedList`.
3. Subscribe to `integrations/slack/response/AdminAppsApprovedList`.
4. POST methods: include both `api_token` and the method fields. The connector body is `{payload}`, so keep secrets out of logs.

> [!NOTE]
>
> No live Slack call has been recorded for this package (no token on the build host, and no test log). `admin.*` methods need a workspace token with admin scopes.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# Smartsheet
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/smartsheet

LoT REST API connector for Smartsheet: add and update rows from plant events, keep summary KPIs current, read sheets and reports, and register webhooks

Technical Preview

## Overview

A client-mode connector for the [Smartsheet API 2.0](https://developers.smartsheet.com/api/smartsheet/introduction) that puts plant data into the sheets operations teams already work in. A typical flow appends a row to a shift log, downtime tracker or quality-check sheet whenever the broker sees an event, updates status and readings on that row as things change, keeps sheet-summary KPIs such as OEE, scrap or uptime current, adds a comment and a dashboard link to the row, asks the shift lead to confirm the cause with an update request, and moves closed rows to an archive sheet. The same connector reads sheets, rows, cell history, reports and dashboards back into the broker, and registers Smartsheet webhooks that post sheet changes to a Coreflux server connector.

One connector carries 44 events (27 GET, 12 POST, 5 PUT; 17 writes, no DELETE). Topics use `devops/smartsheet/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. In Smartsheet, open **Account > Apps & Integrations > API Access** and generate an API access token. The token acts as the user who created it, so use a service account (for example `plant-integration@example.com`) that is shared on the sheets you automate. OAuth 2.0 access tokens work the same way.
2. Keep the token in a broker secret (for example `SMARTSHEET_ACCESS_TOKEN`) and inject it in a LoT action with `GET SECRET`. Never retain topics that carry it.
3. Read the sheet once with `SheetGet` or `ColumnsList` to get its column ids. Rows are written by column id, not by column title.

## Authentication

Every event sends `Authorization: Bearer <token>` built from the `access_token` field of the payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "YOUR_SMARTSHEET_TOKEN"}
```

`ServerInfo` also works with an empty `access_token`, which makes it a simple reachability check.

## Regions

The template points at `https://api.smartsheet.com` (paths under `/2.0/`). For Smartsheet Regions Europe change `BASE_ADDRESS` to `https://api.smartsheet.eu`; for Smartsheet Regions Australia use `https://api.smartsheet.au`. Each region issues its own tokens, so a token from one region does not work on another.

## Query parameters and bodies

Events that take query parameters read them, already URL-encoded, from `query` (for example `rowsModifiedSince=2026-10-05T06%3A00%3A00Z&level=2`). Leave `query` empty for defaults. Writes send JSON from `body`. Smartsheet ids are 64-bit integers: send them as JSON numbers inside `body`, and as plain digits in path fields such as `sheet` and `row`. Values are sent as given, so URL-encode `query` yourself.

## Examples

Append a downtime row when a press stops (`devops/smartsheet/rows/add`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "sheet": "4583173393803140", "query": "allowPartialSuccess=true", "body": [{"toBottom": true, "cells": [{"columnId": 7960873114331012, "value": "Press 7"}, {"columnId": 642523719853956, "value": 94.2}, {"columnId": 5225480965908356, "value": "Open"}]}]}
```

Smartsheet answers with `result`, which holds the new rows and their `id` values. Keep the row id to update the row later.

Close the row when the press restarts (`devops/smartsheet/rows/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "sheet": "4583173393803140", "query": "", "body": [{"id": 2361756178769796, "cells": [{"columnId": 5225480965908356, "value": "Closed"}]}]}
```

Read only the rows that changed this shift (`devops/smartsheet/sheets/get`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "sheet": "4583173393803140", "query": "rowsModifiedSince=2026-10-05T06%3A00%3A00Z&columnIds=7960873114331012,5225480965908356"}
```

Poll `devops/smartsheet/sheets/version/get` first if you only need to know whether anything changed.

Update a KPI in the sheet summary (`devops/smartsheet/sheets/summary/fields/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "sheet": "4583173393803140", "query": "", "body": [{"id": 101, "objectValue": 87.4}]}
```

Send sheet changes to a Coreflux server connector (`devops/smartsheet/webhooks/create`, then `devops/smartsheet/webhooks/update` with `{"enabled": true}`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<token>", "body": {"name": "Porto line 2 downtime", "callbackUrl": "https://broker.example.com/smartsheet/events", "scope": "sheet", "scopeObjectId": 4583173393803140, "events": ["*.*"], "version": 1}}
```

> [!WARNING]
>
> New webhooks are created disabled. When you enable one, Smartsheet sends a verification request to `callbackUrl` with a `Smartsheet-Hook-Challenge` header and a `challenge` body field. The receiving server connector must answer `200` and echo the value in a `Smartsheet-Hook-Response` header or a `smartsheetHookResponse` JSON field. Smartsheet repeats this check once every 100 callbacks and disables the webhook (`DISABLED_VERIFICATION_FAILED`) if it fails. Requests come from `webhooks.smartsheet.com`. Callbacks carry only event metadata (object type, ids, event type), so read the changed rows with `RowGet` or `SheetGet`.

Every write event sends `Smartsheet-Change-Agent: coreflux-broker`. Callbacks for changes made through this connector then carry `changeAgent` `coreflux-broker`, so the server connector can skip them and avoid update loops.

## Events

| Event | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - |
| `UserMe` | `GET` | `/2.0/users/me?{value.json.query}` | `devops/smartsheet/users/me` | | Smoke: the user who owns the token (id, email, account, locale). query e.g. include=groups (or empty). |
| `ServerInfo` | `GET` | `/2.0/serverinfo` | `devops/smartsheet/server-info/get` | | Application constants (formats, locales, server version). Works with an empty access\_token: a reachability check for the region host. |
| `UsersList` | `GET` | `/2.0/users?{value.json.query}` | `devops/smartsheet/users/list` | | Users in the organization (ids and emails for update requests and assignments). query e.g. email=tech%40example.com or page=1\&pageSize=100. |
| `SheetsList` | `GET` | `/2.0/sheets?{value.json.query}` | `devops/smartsheet/sheets/list` | | Sheets the token can see. query e.g. modifiedSince=2026-10-01T00:00:00Z\&pageSize=100\&page=1 (or includeAll=true). |
| `SheetGet` | `GET` | `/2.0/sheets/{value.json.sheet}?{value.json.query}` | `devops/smartsheet/sheets/get` | | Catalog 'GET sheets/\{id}'. Sheet with columns and rows. query e.g. rowsModifiedSince=2026-10-05T06:00:00Z\&columnIds=\<id>,\<id>\&level=2\&include=objectValue (or rowIds=..., filterId=..., ifVersionAfter=\<version>). |
| `SheetVersionGet` | `GET` | `/2.0/sheets/{value.json.sheet}/version` | `devops/smartsheet/sheets/version/get` | | Sheet version only: a cheap poll to see whether anything changed before calling SheetGet. |
| `SheetUpdate` | `PUT` | `/2.0/sheets/{value.json.sheet}` | `devops/smartsheet/sheets/update` | Yes | Rename a sheet or change its settings. body: \{"name":"Line 2 shift log 2026-W41"}. |
| `SheetCreateInWorkspace` | `POST` | `/2.0/workspaces/{value.json.workspace}/sheets?{value.json.query}` | `devops/smartsheet/sheets/create-in-workspace` | Yes | Create a sheet in a workspace (or a copy of a template with fromId). body: \{"name":"Porto line 2 downtime","columns":\[\{"title":"Asset","primary":true,"type":"TEXT\_NUMBER"},\{"title":"Minutes","type":"TEXT\_NUMBER"},\{"title":"Status","type":"PICKLIST","options":\["Open","Closed"]}]}. query e.g. include=attachments (or empty). |
| `SheetCreateInFolder` | `POST` | `/2.0/folders/{value.json.folder}/sheets?{value.json.query}` | `devops/smartsheet/sheets/create-in-folder` | Yes | Create a sheet in a folder. Same body as SheetCreateInWorkspace. query e.g. include=data (or empty). |
| `SheetCopy` | `POST` | `/2.0/sheets/{value.json.sheet}/copy?{value.json.query}` | `devops/smartsheet/sheets/copy` | Yes | Copy a template sheet, e.g. one per batch or week. body: \{"destinationType":"workspace","destinationId":\<workspaceId>,"newName":"Batch 2026-1005-A"}. query e.g. include=data,discussions (or empty). |
| `SheetSummaryGet` | `GET` | `/2.0/sheets/{value.json.sheet}/summary?{value.json.query}` | `devops/smartsheet/sheets/summary/get` | | Sheet summary fields (ids and current values, e.g. OEE, scrap, uptime). query e.g. include=format (or empty). |
| `SheetSummaryFieldsUpdate` | `PUT` | `/2.0/sheets/{value.json.sheet}/summary/fields?{value.json.query}` | `devops/smartsheet/sheets/summary/fields/update` | Yes | Keep summary KPIs current (OEE, scrap, uptime). body: \[\{"id":\<fieldId>,"objectValue":87.4}] (ids from SheetSummaryGet; objectValue is a string, number or boolean for simple fields). query e.g. renameIfConflict=true (or empty). |
| `ColumnsList` | `GET` | `/2.0/sheets/{value.json.sheet}/columns?{value.json.query}` | `devops/smartsheet/columns/list` | | Columns of a sheet (ids and types for RowsAdd / RowsUpdate). query e.g. includeAll=true (or empty). |
| `ColumnGet` | `GET` | `/2.0/sheets/{value.json.sheet}/columns/{value.json.column}?{value.json.query}` | `devops/smartsheet/columns/get` | | One column. query e.g. level=2 (or empty). |
| `ColumnsAdd` | `POST` | `/2.0/sheets/{value.json.sheet}/columns` | `devops/smartsheet/columns/add` | Yes | Add columns (same index for every column in one call). body: \[\{"title":"Temperature C","type":"TEXT\_NUMBER","index":3}]. |
| `ColumnUpdate` | `PUT` | `/2.0/sheets/{value.json.sheet}/columns/{value.json.column}` | `devops/smartsheet/columns/update` | Yes | Rename a column or change its picklist options. body: \{"title":"Status","type":"PICKLIST","options":\["Open","In progress","Closed"]}. |
| `RowsAdd` | `POST` | `/2.0/sheets/{value.json.sheet}/rows?{value.json.query}` | `devops/smartsheet/rows/add` | Yes | Catalog 'POST sheets/\{id}/rows'. Append one row per event, or a batch. body: \[\{"toBottom":true,"cells":\[\{"columnId":\<id>,"value":"Press 7"},\{"columnId":\<id>,"value":94.2}]}]. query e.g. allowPartialSuccess=true\&overrideValidation=true (or empty). Returns the new row ids. |
| `RowsUpdate` | `PUT` | `/2.0/sheets/{value.json.sheet}/rows?{value.json.query}` | `devops/smartsheet/rows/update` | Yes | Catalog 'PUT sheets/\{id}/rows'. Update cells on existing rows by row id. body: \[\{"id":\<rowId>,"cells":\[\{"columnId":\<id>,"value":"Closed"}]}]. query e.g. allowPartialSuccess=true (or empty). |
| `RowGet` | `GET` | `/2.0/sheets/{value.json.sheet}/rows/{value.json.row}?{value.json.query}` | `devops/smartsheet/rows/get` | | One row with its cells. query e.g. include=columns,objectValue (or empty). |
| `RowsMove` | `POST` | `/2.0/sheets/{value.json.sheet}/rows/move?{value.json.query}` | `devops/smartsheet/rows/move` | Yes | Move closed rows to an archive sheet (instead of deleting). body: \{"rowIds":\[\<rowId>],"to":\{"sheetId":\<archiveSheetId>}}. query e.g. include=attachments,discussions. |
| `RowsCopy` | `POST` | `/2.0/sheets/{value.json.sheet}/rows/copy?{value.json.query}` | `devops/smartsheet/rows/copy` | Yes | Copy rows to another sheet (e.g. a plant-wide roll-up). body: \{"rowIds":\[\<rowId>],"to":\{"sheetId":\<targetSheetId>}}. query e.g. include=all (or empty). |
| `CellHistoryList` | `GET` | `/2.0/sheets/{value.json.sheet}/rows/{value.json.row}/columns/{value.json.column}/history?{value.json.query}` | `devops/smartsheet/cells/history/list` | | Change history of one cell (who changed it and when). 30 requests per minute per token. query e.g. pageSize=50 (or empty). |
| `SheetSearch` | `GET` | `/2.0/search/sheets/{value.json.sheet}?{value.json.query}` | `devops/smartsheet/search/sheet` | | Search one sheet. query: query=Press%207. |
| `Search` | `GET` | `/2.0/search?{value.json.query}` | `devops/smartsheet/search/all` | | Search everything the token can see. query: query=Press%207\&scopes=cellData\&modifiedSince=2026-10-01T00:00:00Z. |
| `SheetAttachmentsList` | `GET` | `/2.0/sheets/{value.json.sheet}/attachments?{value.json.query}` | `devops/smartsheet/attachments/list` | | Attachments on a sheet and its rows. query e.g. includeAll=true (or empty). |
| `AttachmentGet` | `GET` | `/2.0/sheets/{value.json.sheet}/attachments/{value.json.attachment}` | `devops/smartsheet/attachments/get` | | One attachment with a temporary download url. |
| `RowAttachmentsList` | `GET` | `/2.0/sheets/{value.json.sheet}/rows/{value.json.row}/attachments?{value.json.query}` | `devops/smartsheet/rows/attachments/list` | | Attachments on one row. query e.g. includeAll=true (or empty). |
| `RowAttachmentAddUrl` | `POST` | `/2.0/sheets/{value.json.sheet}/rows/{value.json.row}/attachments` | `devops/smartsheet/rows/attachments/add-url` | Yes | Attach a link to a row (no file upload). body: \{"attachmentType":"LINK","url":"[https://broker.example.com/panels/press7","name":"Press](https://broker.example.com/panels/press7","name":"Press) 7 trend"}. |
| `DiscussionsList` | `GET` | `/2.0/sheets/{value.json.sheet}/discussions?{value.json.query}` | `devops/smartsheet/discussions/list` | | Discussions on a sheet. query e.g. include=comments\&includeAll=true. |
| `RowDiscussionsList` | `GET` | `/2.0/sheets/{value.json.sheet}/rows/{value.json.row}/discussions?{value.json.query}` | `devops/smartsheet/rows/discussions/list` | | Discussions on one row. query e.g. include=comments (or empty). |
| `RowDiscussionCreate` | `POST` | `/2.0/sheets/{value.json.sheet}/rows/{value.json.row}/discussions` | `devops/smartsheet/rows/discussions/create` | Yes | Start a comment thread on a row. body: \{"comment":\{"text":"Temperature back to 71 C at 14:20"}}. |
| `DiscussionCommentAdd` | `POST` | `/2.0/sheets/{value.json.sheet}/discussions/{value.json.discussion}/comments` | `devops/smartsheet/discussions/comments/add` | Yes | Reply in an existing discussion. body: \{"text":"Bearing replaced, line restarted"}. |
| `UpdateRequestCreate` | `POST` | `/2.0/sheets/{value.json.sheet}/updaterequests` | `devops/smartsheet/update-requests/create` | Yes | Ask someone to fill in rows by email (e.g. shift lead signs off a downtime row). body: \{"sendTo":\[\{"email":"[shift.lead@example.com](mailto:shift.lead@example.com)"}],"rowIds":\[\<rowId>],"columnIds":\[\<id>,\<id>],"subject":"Confirm downtime cause","message":"Press 7 stopped 42 min","ccMe":false,"includeAttachments":false,"includeDiscussions":false}. |
| `ReportsList` | `GET` | `/2.0/reports?{value.json.query}` | `devops/smartsheet/reports/list` | | Reports the token can see. query e.g. modifiedSince=2026-10-01T00:00:00Z (or empty). |
| `ReportGet` | `GET` | `/2.0/reports/{value.json.report}?{value.json.query}` | `devops/smartsheet/reports/get` | | One report with rows across its source sheets (e.g. all open downtime rows plant-wide). query e.g. pageSize=100\&page=1\&include=sourceSheets. |
| `WorkspacesList` | `GET` | `/2.0/workspaces?{value.json.query}` | `devops/smartsheet/workspaces/list` | | Workspaces (token-based pagination). query e.g. maxItems=100 (then lastKey=\<lastKey>). |
| `WorkspaceChildrenList` | `GET` | `/2.0/workspaces/{value.json.workspace}/children?{value.json.query}` | `devops/smartsheet/workspaces/children/list` | | Sheets, reports, dashboards and folders in a workspace. query e.g. childrenResourceTypes=sheets,folders\&maxItems=100. |
| `FolderChildrenList` | `GET` | `/2.0/folders/{value.json.folder}/children?{value.json.query}` | `devops/smartsheet/folders/children/list` | | Contents of a folder. query e.g. childrenResourceTypes=sheets\&maxItems=100. |
| `DashboardsList` | `GET` | `/2.0/sights?{value.json.query}` | `devops/smartsheet/dashboards/list` | | Dashboards (sights). query e.g. maxItems=100 (or empty). |
| `DashboardGet` | `GET` | `/2.0/sights/{value.json.dashboard}?{value.json.query}` | `devops/smartsheet/dashboards/get` | | One dashboard with its widgets. dashboard = sight id. query e.g. level=4 (or empty). |
| `WebhooksList` | `GET` | `/2.0/webhooks?{value.json.query}` | `devops/smartsheet/webhooks/list` | | Webhooks owned by the token's user. query e.g. includeAll=true or pageSize=100 (or empty). |
| `WebhookCreate` | `POST` | `/2.0/webhooks` | `devops/smartsheet/webhooks/create` | Yes | Subscribe to sheet changes; Smartsheet posts them to a Coreflux ENABLE\_SERVER REST\_API connector. body: \{"name":"Porto line 2 downtime","callbackUrl":"[https://broker.example.com/smartsheet/events","scope":"sheet","scopeObjectId":\&lt;sheetId>,"events":\["\*.\*"\],"version":1\\}](https://broker.example.com/smartsheet/events","scope":"sheet","scopeObjectId":\&lt;sheetId>,"events":\["*.*"],"version":1\\}). Created disabled; enable with WebhookUpdate. |
| `WebhookGet` | `GET` | `/2.0/webhooks/{value.json.webhook}` | `devops/smartsheet/webhooks/get` | | One webhook (enabled, status such as ENABLED or DISABLED\_VERIFICATION\_FAILED, stats). |
| `WebhookUpdate` | `PUT` | `/2.0/webhooks/{value.json.webhook}` | `devops/smartsheet/webhooks/update` | Yes | Enable (starts the verification challenge), pause or retarget a webhook. body: \{"enabled":true} or \{"enabled":false} or \{"callbackUrl":"https\://..."}. |

## Limits

Smartsheet allows 300 requests per minute per token for most operations. Cell history and file attachments count ten times, which leaves 30 requests per minute. Above that Smartsheet answers `429` with error code 4003. Batch rows into one `RowsAdd` or `RowsUpdate` call instead of one call per value. Lists are paginated: use `page` and `pageSize` (or `includeAll=true`) on most lists, and `maxItems` and `lastKey` on workspaces, folder children and dashboards.

## Not packaged

* All DELETE endpoints (sheets, rows, columns, discussions, comments, attachments, webhooks) on purpose. Archive closed rows with `RowsMove` instead.
* File uploads (multipart or binary) to sheets, rows and comments. `RowAttachmentAddUrl` attaches links only.
* Sharing, groups, user administration, favorites, proofs, automation rules, cross-sheet references, publish settings, sheet import, event reporting (enterprise audit) and OAuth token exchange.
* The incoming webhook direction: Smartsheet posts callbacks to a separate `ENABLE_SERVER` REST\_API connector, which must answer the verification challenge.


# Snowflake SQL API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/snowflake-sql-api

Client-mode REST API connector for the Snowflake SQL API: submit a statement and poll its handle

Technical Preview

# Snowflake

Client-mode REST API connector for the Snowflake SQL API: submit a statement and poll its handle.

* Hub category: **Analytics**.
* Base: `https://ACCOUNT.snowflakecomputing.com`

## Template reference

Generated from the shipped broker template `snowflake-sql-api` (`-connectorCode SNOWFLAKE_SQL_API`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`, `X-Snowflake-Authorization-Token-Type: {value.json.token_type}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Snowflake SQL API connector | no |
| `BaseUrl` | string | Snowflake SQL API base URL without trailing slash (e.g. [https://ACCOUNT.snowflakecomputing.com](https://ACCOUNT.snowflakecomputing.com)) | yes |

`BASE_ADDRESS` default: `https://ACCOUNT.snowflakecomputing.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Submitstatement` | POST | `/api/v2/statements` | `analytics/snowflake/statements/submit` | `analytics/snowflake/statements/submit/response` | `api_token`, `body`, `token_type` |
| `Getstatement` | GET | `/api/v2/statements/{value.json.statement_handle}` | `analytics/snowflake/statements/get` | `analytics/snowflake/statements/get/response` | `api_token`, `statement_handle`, `token_type` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SNOWFLAKE_SQL_API"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SnowflakeRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://ACCOUNT.snowflakecomputing.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Submitstatement
        WITH SOURCE_TOPIC "analytics/snowflake/statements/submit"
        WITH DESTINATION_TOPIC "analytics/snowflake/statements/submit/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/statements"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
            ADD "X-Snowflake-Authorization-Token-Type" "{value.json.token_type}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getstatement
        WITH SOURCE_TOPIC "analytics/snowflake/statements/get"
        WITH DESTINATION_TOPIC "analytics/snowflake/statements/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/statements/{value.json.statement_handle}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
            ADD "X-Snowflake-Authorization-Token-Type" "{value.json.token_type}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Submitstatement` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'analytics/snowflake/statements/submit/response' &
mosquitto_pub -t 'analytics/snowflake/statements/submit' -m '{"api_token": "<api_token>", "body": {}, "token_type": "<token_type>"}'
```


# SolarEdge
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/solaredge

Client-mode REST API connector for a curated SolarEdge monitoring slice: list sites and read a site overview

Technical Preview

# SolarEdge

Client-mode REST API connector for a curated SolarEdge monitoring slice: list sites and read a site overview.

* Hub category: **Energy**.
* Base: `https://monitoringapi.solaredge.com`

## Template reference

Generated from the shipped broker template `solaredge` (`-connectorCode SOLAREDGE`). It lists every event the template defines.

### Auth

The template sets no auth header. Check the event headers below.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the SolarEdge connector | no |
| `BaseUrl` | string | SolarEdge base URL without trailing slash (e.g. [https://monitoringapi.solaredge.com](https://monitoringapi.solaredge.com)) | yes |

`BASE_ADDRESS` default: `https://monitoringapi.solaredge.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listsites` | GET | `/site/list?api_key={value.json.api_token}` | `energy/solaredge/sites/list` | `energy/solaredge/sites/list/response` | `api_token` |
| `Getoverview` | GET | `/site/{value.json.site_id}/overview?api_key={value.json.api_token}` | `energy/solaredge/sites/overview` | `energy/solaredge/sites/overview/response` | `api_token`, `site_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SOLAREDGE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SolarEdgeRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://monitoringapi.solaredge.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listsites
        WITH SOURCE_TOPIC "energy/solaredge/sites/list"
        WITH DESTINATION_TOPIC "energy/solaredge/sites/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/site/list?api_key={value.json.api_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getoverview
        WITH SOURCE_TOPIC "energy/solaredge/sites/overview"
        WITH DESTINATION_TOPIC "energy/solaredge/sites/overview/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/site/{value.json.site_id}/overview?api_key={value.json.api_token}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listsites` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/solaredge/sites/list/response' &
mosquitto_pub -t 'energy/solaredge/sites/list' -m '{"api_token": "<api_token>"}'
```


# SolarEdge Monitoring API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/solaredge-monitoring-api

LoT REST API connector for the SolarEdge Monitoring API V2: list sites, read power, energy, alerts and inventory, and pull inverter, meter and battery data

Technical Preview

> [!WARNING]
>
> **This connector uses the SolarEdge Monitoring API V2.** SolarEdge plans to switch off the legacy V1 API (`/site/{id}/...` with `?api_key=` in the URL) on **November 3, 2026**. V1 keys do not work on V2. Create a new key in the [SolarEdge developer console](https://developer.solaredge.com).

## Overview

SolarEdge inverters, meters and batteries report to the SolarEdge cloud monitoring platform. The **SolarEdge Monitoring API V2** (`https://monitoringapi.solaredge.com/v2`) gives read access to that data. It is documented on the [SolarEdge developer docs](https://api-docs.solaredge.com), with official OpenAPI specs for the **Basic Monitoring API** (every tier) and the **Advanced Monitoring API** (Business Pro and Enterprise).

The **SolarEdgeMonitoringApi** connector maps 23 MQTT topics onto that API: 17 Basic Monitoring events and 6 Advanced Monitoring events. Typical uses are putting PV production, self-consumption and battery state of charge on the broker next to plant data, feeding energy KPIs (specific yield, performance ratio) to dashboards, and turning SolarEdge alerts into broker alarms. Each event publishes the SolarEdge reply on `<topic>/response`.

| Event | Topic | Request | Use |
| - | - | - | - |
| `ListSites` | `energy/solaredge/site/list` | `GET /v2/sites?{query}` | Sites of your account, sub-accounts and associated accounts (API key only), e.g. query page=1\&sites-in-page=100 or name=Porto |
| `GetSite` | `energy/solaredge/site/get` | `GET /v2/sites/{id}` | Site metadata: name, peak power, installation date, location, time zone, activation status |
| `GetSiteOverview` | `energy/solaredge/site-overview/get` | `GET /v2/sites/{id}/overview?{query}` | Production and consumption for a window, split by destination / source (default: midnight today until now); query from=\&to= or "" |
| `GetSitePerformance` | `energy/solaredge/site-performance/get` | `GET /v2/sites/{id}/overview/performance?{query}` | Specific yield (kWh/kWp) and performance ratio for a window |
| `GetSitePower` | `energy/solaredge/site-power/get` | `GET /v2/sites/{id}/power?{query}` | Site PV power series, resolution QUARTER\_HOUR (max 12 h) or HOUR (max 24 h), unit W/KW/MW |
| `GetSiteEnergy` | `energy/solaredge/site-energy/get` | `GET /v2/sites/{id}/energy?{query}` | Site PV energy series, resolution QUARTER\_HOUR..YEAR or TOTAL (lifetime with from=installation date), unit WH/KWH/MWH |
| `GetSiteEnvironmentalBenefits` | `energy/solaredge/site-environmental-benefits/get` | `GET /v2/sites/{id}/environmental-benefits?{query}` | Lifetime CO2 avoided and EV miles; query unit=METRIC/IMPERIAL or "" |
| `ListFleetAlerts` | `energy/solaredge/fleet-alert/list` | `GET /v2/alerts?{query}` | Alerts across the fleet (API key only), e.g. query only-open=true\&alerts-in-page=100 |
| `ListSiteAlerts` | `energy/solaredge/site-alert/list` | `GET /v2/sites/{id}/alerts?{query}` | Alerts of one site, e.g. query only-open=true |
| `ListSiteDevices` | `energy/solaredge/device/list` | `GET /v2/sites/{id}/devices?{query}` | Device inventory (default INVERTER only), e.g. query types=INVERTER\&types=METER\&types=BATTERY; gives the serials for telemetry |
| `GetDevice` | `energy/solaredge/device/get` | `GET /v2/sites/{id}/devices/{serial}` | One device: manufacturer, model, firmware, communication status |
| `GetSiteInverterTelemetry` | `energy/solaredge/site-inverter-telemetry/get` | `GET /v2/sites/{id}/inverters/telemetry?{query}` | All active inverters: power, energy, consumedAcPower/Energy, voltage, current, frequency |
| `GetInverterTelemetry` | `energy/solaredge/inverter-telemetry/get` | `GET /v2/sites/{id}/inverters/{serial}/telemetry?{query}` | Inverter telemetry for specific serials (comma-separated) |
| `GetSiteMeterTelemetry` | `energy/solaredge/site-meter-telemetry/get` | `GET /v2/sites/{id}/meters/telemetry?{query}` | All active meters: production, consumption, import, export power and energy |
| `GetMeterTelemetry` | `energy/solaredge/meter-telemetry/get` | `GET /v2/sites/{id}/meters/{serial}/telemetry?{query}` | Meter telemetry for specific serials (comma-separated) |
| `GetSiteStorageTelemetry` | `energy/solaredge/site-storage-telemetry/get` | `GET /v2/sites/{id}/storage/telemetry?{query}` | All active batteries: charge/discharge power and energy, stateOfEnergy (%), remainingEnergy |
| `GetStorageTelemetry` | `energy/solaredge/storage-telemetry/get` | `GET /v2/sites/{id}/storage/{serial}/telemetry?{query}` | Battery telemetry for specific serials (comma-separated) |
| `GetPowerPerDestination` | `energy/solaredge/power-per-destination/get` | `GET /v2/sites/{id}/power/per-destination?{query}` | Advanced (Business Pro / Enterprise): PV power split into self-consumption, storage, grid |
| `GetEnergyPerDestination` | `energy/solaredge/energy-per-destination/get` | `GET /v2/sites/{id}/energy/per-destination?{query}` | Advanced (Business Pro / Enterprise): PV energy split into self-consumption, storage, grid |
| `GetPowerFlow` | `energy/solaredge/power-flow/get` | `GET /v2/sites/{id}/power-flow` | Advanced: latest power-flow sample (PV, grid, storage, load and directions); refreshRate 300 when no live session |
| `StartLivePowerFlow` | `energy/solaredge/power-flow/start` | `POST /v2/sites/{id}/power-flow` | Advanced: start a 1-minute live power flow session (no body; docs say OAuth SITE\_DATA may be required) |
| `GetWeatherGuard` | `energy/solaredge/weather-guard/get` | `GET /v2/sites/{id}/weather-guard` | Advanced: whether Weather Guard storm mode is enabled (read-only) |
| `GetBackupReserve` | `energy/solaredge/backup-reserve/get` | `GET /v2/sites/{id}/backup-reserve` | Advanced: battery backup reserve (minimum state of charge kept for outages, read-only) |

The API is **read-only**. `StartLivePowerFlow` is the only `POST`. It starts a one-minute live power flow session and changes no site data. Weather Guard and backup reserve settings can only be read here; SolarEdge says changing them will be part of a separate Fleet Management API.

> [!TIP]
>
> For local, sub-minute inverter data without the cloud, read the inverter over Modbus TCP (SunSpec) with a native Modbus connector instead. This connector is for cloud fleet data.

## Prerequisites

* A **SolarEdge developer account** at [developer.solaredge.com](https://developer.solaredge.com). The Free tier starts automatically (2,000 credits per month, 10 calls per minute). Installer account admins can add developer access to their existing installer account.
* A **Fleet Access** application with its **App API Key**. Choose **My Fleet** for sites in your own installer account, or **External Fleet** to request access to another company's fleet through a consent link. The key is shown only once, and you set its expiry (3, 6 or 12 months, or a custom date).
* The **site id** of each site you want to read (from `site/list`) and, for device telemetry, the device serial numbers (from `device/list`).
* For the Advanced events: a **Business Pro** or **Enterprise** subscription. Lower tiers get `403`.
* Outbound HTTPS from the broker to `monitoringapi.solaredge.com`.

## Authentication

Every event sends `X-API-Key: {value.json.api_key}`. Store the App API Key as a Hub secret, for example `SOLAREDGE_API_KEY`, and read it with `GET SECRET` in the action that publishes to the connector. V2 does not accept the key as a URL parameter.

| Response | Meaning |
| - | - |
| `401` `{"error":"invalid_request","error_description":"The access token is missing"}` | No `X-API-Key` header |
| `401` `{"message":"Unauthorized"}` | The key is unknown, expired, revoked or regenerated |
| `403` | The key has no access to that site, or the event needs a higher tier |
| `429` with `retry-after` | Calls-per-minute limit reached; retry after the next minute starts |
| `429` `"Monthly credit limit reached."` (no `retry-after`) | Monthly credits used up; calls resume at the next billing cycle |

**Homeowner sites (Site Access, OAuth 2.0).** If the system owner, not your installer account, must grant access, SolarEdge uses an OAuth 2.0 authorization code flow (`https://connect.solaredge.com/authorize`, scopes `SITE_DATA` and `DEVICE_DATA`). Access tokens last 2 hours. To use OAuth, fork the connector and replace the `X-API-Key` header with `ADD "Authorization" "{value.json.authorization}"`, then publish `Bearer <access_token>` in the `authorization` field. Refresh tokens on your backend, because the refresh call needs the client secret. `site/list` and `fleet-alert/list` accept only the API key.

## Configuration

| Setting | Value |
| - | - |
| `BASE_ADDRESS` | `https://monitoringapi.solaredge.com` (endpoints carry `/v2`) |
| `USE_SSL` | `"true"` |
| `DEFAULT_CONTENT_TYPE` | `application/json` |
| Payload fields | `api_key`, `id` (SolarEdge site id), `serial` (device serial number; comma-separated serials for the `*-telemetry/get` events), `query` (pre-encoded query string, `""` for none) |

Query parameters:

| Parameter | Example | Notes |
| - | - | - |
| `from`, `to` | `from=2026-10-05T06:00:00Z&to=2026-10-05T18:00:00Z` | ISO 8601 date-times. Encode a `+` offset as `%2B`. Without them, the window is midnight today (site time) until now |
| `resolution` | `resolution=HOUR` | `QUARTER_HOUR` (default), `HOUR`, `DAY`, `WEEK`, `MONTH`, `YEAR`, `TOTAL`. Site power and power per destination accept only `QUARTER_HOUR` and `HOUR` |
| `unit` | `unit=KW`, `unit=KWH`, `unit=IMPERIAL` | Power `W`/`KW`/`MW`, energy `WH`/`KWH`/`MWH`, environmental benefits `METRIC`/`IMPERIAL` |
| `page`, `sites-in-page`, `alerts-in-page` | `page=2&sites-in-page=1000` | Sites: default 50, maximum 1,000. Alerts: default 50, maximum 100 |
| `only-open` | `only-open=true` | Alerts: only open alerts (default `true`) |
| `types` | `types=INVERTER&types=METER&types=BATTERY` | Device list filter. Default is `INVERTER` only. Other values: `BATTERY_MODULE`, `OPTIMIZER`, `EV_CHARGER`, `BUI`, `GATEWAY` |
| `name`, `group`, `state`, `city`, `type` | `name=Porto` | Site and alert filters |

Maximum window between `from` and `to`:

| Resolution | Maximum window |
| - | - |
| `QUARTER_HOUR` | 12 hours |
| `HOUR` | 24 hours |
| `DAY` | 1 month |
| `WEEK` | 1 year |
| `MONTH` | 3 years |
| `YEAR`, `TOTAL` | Unlimited (`TOTAL` returns one value; set `from` to the installation date for a lifetime total) |

A longer window returns `400` with an RFC 7807 problem body (`title`, `status`, `detail`). Time series come back as `{"period": {"from", "to"}, "unit", "resolution", "values": [{"timestamp", "value"}]}`, and each timestamp marks the start of its bucket.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — SolarEdge Monitoring API V2 (PV, battery and meter monitoring):
#   list the sites of a fleet, read site metadata, overview, performance (specific yield / performance ratio), PV
#   power and energy time series and environmental benefits, read fleet and site alerts, discover devices (inverters,
#   meters, batteries, gateways, ...), pull bulk inverter / meter / storage telemetry, and (Advanced Monitoring tier)
#   read power / energy per destination, the live power flow (and start a 1-minute live session), Weather Guard and
#   battery backup reserve.
#   OpenAPI 3.0.1 (info.version 2.0.1) from the SolarEdge developer docs (api-docs.solaredge.com, Stoplight export,
#   only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/solaredge-monitoring-api
#
# V1 vs V2: the legacy V1 Monitoring API (/site/{id}/..., ?api_key= in the URL) is planned to stop responding on
#   2026-11-03 (SolarEdge "Migrating from V1 to V2"). This route targets V2 only: host https://monitoringapi.solaredge.com,
#   every endpoint carries /v2, paths are plural (/sites/{id}/...). V1 keys do not work on V2.
# Auth (Fleet Access): X-API-Key: {value.json.api_key} on every call (App API Key from the developer console at
#   developer.solaredge.com, "My Fleet" or "External Fleet" application). Keep it in Hub secrets (suggested
#   SOLAREDGE_API_KEY) and map it into the payload with GET SECRET. The key is a header, never a URL parameter.
#   Missing key: 401 {"error":"invalid_request","error_description":"The access token is missing"}; unknown key:
#   401 {"message":"Unauthorized"}; no access to the site or tier too low: 403.
# Auth (Site Access, OAuth 2.0 for homeowner-consented sites): fork the route and replace the X-API-Key header with
#   ADD "Authorization" "{value.json.authorization}" ("Bearer <access_token>", 2 h lifetime, refresh server-side).
#   ListSites and ListFleetAlerts accept the API key only.
# Quotas: per developer account, tiered: Free 2,000 credits / month and 10 calls per minute (CPM); Business Starter 25,
#   Growth 50, Pro 100 CPM. Every call costs 1 credit. 429 with retry-after = CPM exceeded; 429 "Monthly credit limit
#   reached." (no retry-after) = credits exhausted. Telemetry arrives about every 5 minutes and the minimum resolution
#   is QUARTER_HOUR, so poll every 15 minutes or slower and prefer the bulk telemetry events.
# Queries: GET events take the pre-encoded query string in "query" ("" for none). Time windows use from= / to= as
#   ISO 8601 date-times (URL-encode "+" offsets as %2B, or use Z), resolution=QUARTER_HOUR|HOUR|DAY|WEEK|MONTH|YEAR|TOTAL
#   (power: QUARTER_HOUR|HOUR only) and unit= (W|KW|MW, WH|KWH|MWH, METRIC|IMPERIAL). Window limits: QUARTER_HOUR 12 h,
#   HOUR 24 h, DAY 1 month, WEEK 1 year, MONTH 3 years, YEAR / TOTAL unlimited; longer windows answer 400.
#   Lists: page= and sites-in-page= (default 50, max 1000) / alerts-in-page= (default 50, max 100), only-open=true|false.
# Writes: none. The Monitoring API is read-only. The only POST (StartLivePowerFlow) starts a 1-minute live power flow
#   session; it changes no data. Weather Guard / backup reserve changes belong to the forthcoming Fleet Management API.
# Advanced Monitoring events (power / energy per destination, power flow, Weather Guard, backup reserve) need the
#   Business Pro or Enterprise tier; lower tiers get 403.
# Responses: JSON. Time series: {"period": {"from", "to"}, "unit", "resolution", "values": [{"timestamp", "value"}]}.
#   Errors: RFC 7807 problem+json {"type", "title", "status", "detail", "traceId"?, "errors"?}.
#
# Payload fields: api_key, id (SolarEdge site id), serial (device serial number; comma-separated for the
#   *-telemetry/get events), query
#     GetSiteEnergy            id = "1148616", query = "from=2026-10-01T00:00:00Z&to=2026-10-05T00:00:00Z&resolution=DAY&unit=KWH"
#     GetSiteInverterTelemetry id = "1148616", query = "from=2026-10-05T06:00:00Z&to=2026-10-05T18:00:00Z&resolution=QUARTER_HOUR"
#     GetMeterTelemetry        id = "1148616", serial = "606001234", query = "resolution=HOUR"
#     ListSiteDevices          id = "1148616", query = "types=INVERTER&types=METER&types=BATTERY"
#     ListFleetAlerts          query = "only-open=true&alerts-in-page=100"

DEFINE CONNECTOR SolarEdgeMonitoringApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://monitoringapi.solaredge.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListSites
        WITH SOURCE_TOPIC "energy/solaredge/site/list"
        WITH DESTINATION_TOPIC "energy/solaredge/site/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSite
        WITH SOURCE_TOPIC "energy/solaredge/site/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSiteOverview
        WITH SOURCE_TOPIC "energy/solaredge/site-overview/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-overview/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/overview?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSitePerformance
        WITH SOURCE_TOPIC "energy/solaredge/site-performance/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-performance/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/overview/performance?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSitePower
        WITH SOURCE_TOPIC "energy/solaredge/site-power/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-power/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/power?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSiteEnergy
        WITH SOURCE_TOPIC "energy/solaredge/site-energy/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-energy/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/energy?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSiteEnvironmentalBenefits
        WITH SOURCE_TOPIC "energy/solaredge/site-environmental-benefits/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-environmental-benefits/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/environmental-benefits?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListFleetAlerts
        WITH SOURCE_TOPIC "energy/solaredge/fleet-alert/list"
        WITH DESTINATION_TOPIC "energy/solaredge/fleet-alert/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/alerts?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListSiteAlerts
        WITH SOURCE_TOPIC "energy/solaredge/site-alert/list"
        WITH DESTINATION_TOPIC "energy/solaredge/site-alert/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/alerts?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListSiteDevices
        WITH SOURCE_TOPIC "energy/solaredge/device/list"
        WITH DESTINATION_TOPIC "energy/solaredge/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/devices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "energy/solaredge/device/get"
        WITH DESTINATION_TOPIC "energy/solaredge/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/devices/{value.json.serial}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSiteInverterTelemetry
        WITH SOURCE_TOPIC "energy/solaredge/site-inverter-telemetry/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-inverter-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/inverters/telemetry?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetInverterTelemetry
        WITH SOURCE_TOPIC "energy/solaredge/inverter-telemetry/get"
        WITH DESTINATION_TOPIC "energy/solaredge/inverter-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/inverters/{value.json.serial}/telemetry?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSiteMeterTelemetry
        WITH SOURCE_TOPIC "energy/solaredge/site-meter-telemetry/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-meter-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/meters/telemetry?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetMeterTelemetry
        WITH SOURCE_TOPIC "energy/solaredge/meter-telemetry/get"
        WITH DESTINATION_TOPIC "energy/solaredge/meter-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/meters/{value.json.serial}/telemetry?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSiteStorageTelemetry
        WITH SOURCE_TOPIC "energy/solaredge/site-storage-telemetry/get"
        WITH DESTINATION_TOPIC "energy/solaredge/site-storage-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/storage/telemetry?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetStorageTelemetry
        WITH SOURCE_TOPIC "energy/solaredge/storage-telemetry/get"
        WITH DESTINATION_TOPIC "energy/solaredge/storage-telemetry/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/storage/{value.json.serial}/telemetry?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetPowerPerDestination
        WITH SOURCE_TOPIC "energy/solaredge/power-per-destination/get"
        WITH DESTINATION_TOPIC "energy/solaredge/power-per-destination/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/power/per-destination?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetEnergyPerDestination
        WITH SOURCE_TOPIC "energy/solaredge/energy-per-destination/get"
        WITH DESTINATION_TOPIC "energy/solaredge/energy-per-destination/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/energy/per-destination?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetPowerFlow
        WITH SOURCE_TOPIC "energy/solaredge/power-flow/get"
        WITH DESTINATION_TOPIC "energy/solaredge/power-flow/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/power-flow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT StartLivePowerFlow
        WITH SOURCE_TOPIC "energy/solaredge/power-flow/start"
        WITH DESTINATION_TOPIC "energy/solaredge/power-flow/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/sites/{value.json.id}/power-flow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
        WITH BODY ""
    ADD EVENT GetWeatherGuard
        WITH SOURCE_TOPIC "energy/solaredge/weather-guard/get"
        WITH DESTINATION_TOPIC "energy/solaredge/weather-guard/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/weather-guard"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetBackupReserve
        WITH SOURCE_TOPIC "energy/solaredge/backup-reserve/get"
        WITH DESTINATION_TOPIC "energy/solaredge/backup-reserve/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/sites/{value.json.id}/backup-reserve"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-API-Key" "{value.json.api_key}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
```

## Examples

Publish directly to a connector topic:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_key": "<App API Key>", "id": "1148616", "query": "from=2026-10-01T00:00:00Z&to=2026-10-05T00:00:00Z&resolution=DAY&unit=KWH"}
```

to `energy/solaredge/site-energy/get`, then read `energy/solaredge/site-energy/get/response` for the daily PV energy of the last four days.

Actions that poll the connector on a schedule that fits the Free tier (one site):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the SolarEdgeMonitoringApi route (docs page). Not part of the route template.
# Secret: SOLAREDGE_API_KEY = the Fleet Access App API Key from developer.solaredge.com (shown once; header X-API-Key).
# Site id 1148616 is the example id SolarEdge uses in its V2 docs. Replace it with your own (from site/list).
# Inline JSON object literals are not supported when publishing to a topic, so the request payload is a COLLAPSED
#   model sent with PUBLISH MODEL.
# Credit budget: the Free tier has 2,000 credits / month and 10 calls per minute. These four actions use about
#   744 + 372 + 248 + 124 = 1,488 credits / month for one site. Paid tiers allow faster polling.
# No from / to is sent, so each call covers midnight today (site time) until now. HOUR resolution keeps that window
#   inside the 24 h limit (QUARTER_HOUR is limited to 12 h).

DEFINE MODEL SolarEdgeRequest COLLAPSED
    ADD STRING "api_key"
    ADD STRING "id"
    ADD STRING "query"

DEFINE ACTION SolarEdgeOverviewHourly
ON EVERY 1 HOUR DO
    PUBLISH MODEL SolarEdgeRequest TO "energy/solaredge/site-overview/get" WITH
        api_key = (GET SECRET "SOLAREDGE_API_KEY")
        id = "1148616"
        query = ""

DEFINE ACTION SolarEdgeBatteryEvery2Hours
ON EVERY 2 HOURS DO
    PUBLISH MODEL SolarEdgeRequest TO "energy/solaredge/site-storage-telemetry/get" WITH
        api_key = (GET SECRET "SOLAREDGE_API_KEY")
        id = "1148616"
        query = "resolution=HOUR"

DEFINE ACTION SolarEdgeOpenAlertsEvery3Hours
ON EVERY 3 HOURS DO
    PUBLISH MODEL SolarEdgeRequest TO "energy/solaredge/site-alert/list" WITH
        api_key = (GET SECRET "SOLAREDGE_API_KEY")
        id = "1148616"
        query = "only-open=true&alerts-in-page=100"

DEFINE ACTION SolarEdgeInverterTelemetryEvery6Hours
ON EVERY 6 HOURS DO
    PUBLISH MODEL SolarEdgeRequest TO "energy/solaredge/site-inverter-telemetry/get" WITH
        api_key = (GET SECRET "SOLAREDGE_API_KEY")
        id = "1148616"
        query = "resolution=HOUR"
```

Restrict who can publish to `energy/solaredge/#` with a rule, because these payloads carry the API key.

## Quotas and polling

| Tier | Credits / month | Calls / minute |
| - | - | - |
| Free | 2,000 | 10 |
| Business Starter | 20,000 | 25 |
| Business Growth | 100,000 | 50 |
| Business Pro | 400,000 | 100 |
| Enterprise | Custom | Custom |

Every call costs 1 credit. Credits and the calls-per-minute limit are shared by every application in your developer account. Device telemetry arrives about every 5 minutes, the finest resolution is 15 minutes, and SolarEdge refreshes the site overview about every 15 minutes. Polling faster than every 15 minutes only spends credits. Prefer the bulk `*-telemetry/get` events over many single calls: one call returns a whole window for every device of a type. Pricing is from the SolarEdge tiers page and may change; the developer console has the current values.

## Coming from V1

| V1 (catalog hint) | V2 event |
| - | - |
| `GET /site/{id}/overview?api_key=` | `GetSiteOverview` (new shape; lifetime energy moved to `GetSiteEnergy` with `resolution=TOTAL`) |
| `GET /site/{id}/powerDetails`, `/energyDetails`, `/meters` | `GetSiteMeterTelemetry` / `GetMeterTelemetry` |
| `GET /site/{id}/currentPowerFlow` | `GetPowerFlow` (Advanced tier only) |
| `GET /equipment/{siteId}/{serial}/data` | `GetSiteInverterTelemetry` / `GetInverterTelemetry` |
| `GET /site/{id}/storageData` | `GetSiteStorageTelemetry` / `GetStorageTelemetry` |
| `GET /sites/list`, `/site/{id}/details`, `/site/{id}/inventory` | `ListSites`, `GetSite`, `ListSiteDevices` |

V2 renames `startTime`/`endTime`/`startDate`/`endDate` to `from`/`to`, and `timeUnit` to `resolution`. Bulk multi-site paths (`/sites/1,4/...`) are gone, so call each site separately. V2 inverter telemetry has no per-phase values, DC voltage, temperature or inverter mode, and storage telemetry has no battery temperature or numeric battery state. Use the alert events for fault detection.

## Notes

* **Live power flow:** `GetPowerFlow` returns the last sample (`refreshRate` 300 seconds) unless a live session is active. `StartLivePowerFlow` starts a session that lasts one minute. It needs a supported firmware version and an Ethernet, Wi-Fi or LTE (US only) connection. SolarEdge's reference says this call may need an OAuth token with `SITE_DATA`.
* **Display rules:** SolarEdge's API terms ask apps that display this data to show the SolarEdge logo, linked to solaredge.com.
* **Key rotation:** regenerating an App API Key invalidates the old key at once. Update the Hub secret right after you regenerate it.
* Errors come back on the response topic: `400` invalid parameter or window, `401` missing or bad key, `403` no access or tier too low, `404` unknown site or device, `429` rate or credit limit.

## Not covered

The 21 per-metric endpoints (for example `/inverters/{serial}/voltage` or `/storage/{serial}/state-of-energy`). The bulk telemetry events return the same metrics in one call. Also not covered: the OAuth token exchange (run it on your backend), the legacy V1 API, and the forthcoming Fleet Management API.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [ENTSO-E Transparency Platform](/latest/lot-language/routes/rest-api-apps/entso-e-transparency-platform)
* [Open-Meteo](/latest/lot-language/routes/rest-api-apps/open-meteo)


# Soracom
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/soracom

LoT REST API connector for Soracom: manage IoT SIMs and groups, read usage and Harvest data, send downlinks and SMS, with an optional webhook receiver

Technical Preview

## Overview

[Soracom](https://soracom.io) is an IoT connectivity platform: IoT SIMs for cellular devices (Air), data forwarding to clouds and servers (Beam, Funnel, Funk, Unified Endpoint), data and file storage (Harvest Data, Harvest Files), event handlers and LwM2M device management (Inventory). These connectors connect the Coreflux broker to the Soracom API, so plant logic on MQTT can watch and control the SIMs of field gateways and machines, read their data usage and stored data, reconfigure forwarding, and reach devices behind the cellular network with downlink HTTP, ping and SMS.

* **SoracomApi** (`SoracomRestApi.lot`) is a client connector on `https://g.api.soracom.io` (global coverage) with 44 events from the [Soracom API reference](https://developers.soracom.io/en/api/).
* **SoracomWebhookReceiver** (`cloud-iot_soracom_webhook.lot`, opt-in, server mode) receives device data that [Soracom Beam](https://developers.soracom.io/en/docs/beam/) forwards over HTTP and event handler web requests, so device data and SIM events reach MQTT without polling.

Every endpoint below matches Soracom's published OpenAPI definition, and every event was checked against the live API (see Status).

> [!TIP]
>
> For Japan coverage SIMs, change `BASE_ADDRESS` to `https://api.soracom.io`. The endpoints are the same, but each coverage holds its own SIMs.

## Authentication

> [!WARNING]
>
> An AuthKey grants API access as its user. Create the AuthKey on a SAM user whose permissions cover only the events you use. Keep it in Hub secrets, map it in with `GET SECRET`, and never publish it, the API key or the token on a topic other clients can read.

Soracom uses a two-step session:

1. Publish `{"body": {"authKeyId": "...", "authKey": "...", "tokenTimeoutSeconds": 3600}}` on `cloud-iot/soracom/token/create` (`Auth`, `POST /v1/auth`). The response on `cloud-iot/soracom/token/create/response` carries `apiKey`, `token` and `operatorId`.
2. Every other event takes `"api_key"` and `"token"` in its MQTT payload and sends them as `X-Soracom-API-Key` and `X-Soracom-Token`.

Tokens expire after `tokenTimeoutSeconds` (180 to 172800 seconds, default 86400), so call `Auth` again before then. `Auth` also accepts a SAM user (`operatorId`, `userName`, `password`) or the root account (`email`, `password`), but AuthKeys are the right choice for a broker. Suggested secrets: `SORACOM_AUTH_KEY_ID` and `SORACOM_AUTH_KEY`.

A wrong or expired API key or token returns `403` with `{"code":"AGW0011","message":"Invalid API Key or Token"}`. A wrong AuthKey on `Auth` returns `401` with `{"code":"AUM0029","message":"Invalid AuthKey supplied."}`.

## Payload conventions

* **Ids.** `"sim_id"` is the SIM ID (`simId` in `ListSims` and `GetSim`), `"imsi"` a subscriber IMSI, `"group_id"` and `"handler_id"` UUIDs, `"device_id"` a Soracom Inventory device id. LwM2M events take `"object_id"`, `"instance_id"` and `"lwm2m_resource_id"` (for example `3303`, `0`, `5700`).
* **Query strings.** Events with `?{query}` take a pre-encoded query string. Send `""` for none. Usage reports require `from`, `to` (Unix seconds) and `period` (`month`, `day` or `minutes`). Harvest Data, session and status history take `from` and `to` in milliseconds.
* **Bodies.** Write events and downlinks send `"body"` unchanged.
* **Paging.** List events return up to `limit` items. Soracom returns the next-page key in the `x-soracom-next-key` response header, to pass back as `last_evaluated_key`. The connector publishes the response body, so prefer a large `limit` or narrower filters (`SearchSims`, `ListSimsInGroup`) when the header is not available.

## Authentication

| Event | Request | Topic | Notes |
| - | - | - | - |
| Auth | `POST /v1/auth` | `cloud-iot/soracom/token/create` | Credential check: exchange an AuthKey ID + secret (or SAM operatorId/userName/password, or root email/password) for apiKey + token + operatorId; tokenTimeoutSeconds 180-172800 (default 86400) |

**Auth** (`cloud-iot/soracom/token/create`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "body": {
    "authKeyId": "<authkey id>",
    "authKey": "<authkey secret>",
    "tokenTimeoutSeconds": 3600
  }
}
```

## IoT SIMs

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListSims | `GET /v1/sims?{query}` | `cloud-iot/soracom/sim/list` | Catalog: IoT SIMs (paged); query limit=100\&last\_evaluated\_key=\<simId> (send "" for none) |
| GetSim | `GET /v1/sims/{sim_id}` | `cloud-iot/soracom/sim/get` | One IoT SIM: status, speedClass, sessionStatus (online, IMEI, cell, ueIpAddress), groupId, tags, profiles, expiry |
| SearchSims | `GET /v1/query/sims?{query}` | `cloud-iot/soracom/sim/search` | Search SIMs by name, group, imsi, iccid, msisdn, tag, status, session\_status (ONLINE / OFFLINE), imei ... (search\_type and \| or) |
| ActivateSim | `POST /v1/sims/{sim_id}/activate` | `cloud-iot/soracom/sim/activate` | Catalog: set the SIM to active (billing starts, data allowed) **(write)** |
| DeactivateSim | `POST /v1/sims/{sim_id}/deactivate` | `cloud-iot/soracom/sim/deactivate` | Set the SIM to inactive (no data; basic fee still charged) **(write)** |
| SuspendSim | `POST /v1/sims/{sim_id}/suspend` | `cloud-iot/soracom/sim/suspend` | Suspend the SIM (for example a lost or stolen device) **(write)** |
| SetSimToStandby | `POST /v1/sims/{sim_id}/set_to_standby` | `cloud-iot/soracom/sim/standby` | Put a ready SIM in standby (becomes active on first connection) **(write)** |
| UpdateSimSpeedClass | `POST /v1/sims/{sim_id}/update_speed_class` | `cloud-iot/soracom/sim-speed-class/update` | Change the speed class; body \{"speedClass": "s1.minimum"} (s1.minimum \| s1.slow \| s1.standard \| s1.fast \| s1.4xfast \| s1.8xfast \| u1.standard \| u1.slow, per plan) **(write)** |
| PutSimTags | `PUT /v1/sims/{sim_id}/tags` | `cloud-iot/soracom/sim-tags/update` | Add or update SIM tags; body \[\{"tagName": "name", "tagValue": "porto-line1-gateway"}] **(write)** |
| SetSimGroup | `POST /v1/sims/{sim_id}/set_group` | `cloud-iot/soracom/sim-group/set` | Move the SIM into a group (the group's Air / Beam / Funnel / Funk / Harvest settings then apply); body \{"groupId": "..."} **(write)** |
| UnsetSimGroup | `POST /v1/sims/{sim_id}/unset_group` | `cloud-iot/soracom/sim-group/unset` | Remove the SIM from its group **(write)** |
| ListSimSessionEvents | `GET /v1/sims/{sim_id}/events/sessions?{query}` | `cloud-iot/soracom/sim-session-event/list` | Session history (Created / Modified / Deleted with cell, IMEI, RAT); query from / to (ms), limit |
| ListSimStatusHistory | `GET /v1/sims/{sim_id}/statuses/history?{query}` | `cloud-iot/soracom/sim-status-history/list` | Status operation history of the SIM (who changed status and when) |

**SearchSims** (`cloud-iot/soracom/sim/search`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "query": "session_status=ONLINE&tag=line1&search_type=and&limit=100"
}
```

**UpdateSimSpeedClass** (`cloud-iot/soracom/sim-speed-class/update`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "8942310222000000000",
  "body": {
    "speedClass": "s1.minimum"
  }
}
```

**PutSimTags** (`cloud-iot/soracom/sim-tags/update`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "8942310222000000000",
  "body": [
    {
      "tagName": "name",
      "tagValue": "porto-line1-gateway"
    },
    {
      "tagName": "line",
      "tagValue": "1"
    }
  ]
}
```

## Usage reports

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetSimAirStats | `GET /v1/stats/air/sims/{sim_id}?{query}` | `cloud-iot/soracom/sim-usage/get` | Catalog: data usage of one SIM (upload / download bytes and packets per period); query from, to (Unix seconds) and period=month\|day\|minutes (all required) |
| GetGroupAirStats | `GET /v1/stats/air/groups/{group_id}?{query}` | `cloud-iot/soracom/group-usage/get` | Data usage of all SIMs in a group; query from, to (Unix seconds), period (required) |
| GetHarvestStats | `GET /v1/stats/harvest/subscribers/{imsi}?{query}` | `cloud-iot/soracom/harvest-usage/get` | Harvest Data write counts of a subscriber (IMSI); query from, to, period (required) |
| GetBeamStats | `GET /v1/stats/beam/subscribers/{imsi}?{query}` | `cloud-iot/soracom/beam-usage/get` | Beam request counts per entry point of a subscriber; query from, to, period (required) |
| GetFunnelStats | `GET /v1/stats/funnel/subscribers/{imsi}?{query}` | `cloud-iot/soracom/funnel-usage/get` | Funnel request counts of a subscriber; query from, to, period (required) |

**GetSimAirStats** (`cloud-iot/soracom/sim-usage/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "8942310222000000000",
  "query": "from=1790812800&to=1791244800&period=day"
}
```

## Groups (Air, Beam, Funnel, Funk, Harvest settings)

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListGroups | `GET /v1/groups?{query}` | `cloud-iot/soracom/group/list` | Groups (paged); query tag\_name / tag\_value / tag\_value\_match\_mode / limit (send "" for none) |
| GetGroup | `GET /v1/groups/{group_id}` | `cloud-iot/soracom/group/get` | One group with its full configuration per namespace (SoracomAir, SoracomBeam, SoracomFunnel, SoracomFunk, SoracomHarvest ...) |
| CreateGroup | `POST /v1/groups` | `cloud-iot/soracom/group/create` | Create a group; body \{"tags": \{"name": "porto-line1"}, "configuration": \{"SoracomHarvest": \{"enabled": true}}} **(write)** |
| PutGroupConfiguration | `PUT /v1/groups/{group_id}/configuration/{namespace}` | `cloud-iot/soracom/group-config/update` | Set Beam / Funnel / Funk / Harvest / Air / UnifiedEndpoint parameters of a group; namespace SoracomBeam with key [http://beam.soracom.io:8888/](http://beam.soracom.io:8888/) (or udp\://beam.soracom.io:23080) forwards device data to SoracomWebhookReceiver; SoracomHarvest \[\{"key": "enabled", "value": true}] turns on Harvest Data **(write)** |
| PutGroupTags | `PUT /v1/groups/{group_id}/tags` | `cloud-iot/soracom/group-tags/update` | Add or update group tags; body \[\{"tagName": "site", "tagValue": "porto"}] **(write)** |
| ListSimsInGroup | `GET /v1/groups/{group_id}/sims?{query}` | `cloud-iot/soracom/group-sim/list` | SIMs in a group; query status\_filter / speed\_class\_filter / limit (send "" for none) |

**CreateGroup** (`cloud-iot/soracom/group/create`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "body": {
    "tags": {
      "name": "porto-line1"
    },
    "configuration": {
      "SoracomHarvest": {
        "enabled": true
      },
      "SoracomAir": {
        "metadata": {
          "enabled": true
        }
      }
    }
  }
}
```

**PutGroupConfiguration** (`cloud-iot/soracom/group-config/update`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "group_id": "3c9a1f2e-7b4d-4e8a-9c21-5f0d2b6a8e11",
  "namespace": "SoracomBeam",
  "body": [
    {
      "key": "http://beam.soracom.io:8888/",
      "value": {
        "name": "Coreflux",
        "destination": "https://broker.example.com/soracom/webhook/beam",
        "enabled": true,
        "addSubscriberHeader": true,
        "addSimIdHeader": true,
        "addSignature": false
      }
    }
  ]
}
```

## Harvest Data

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetSimData | `GET /v1/sims/{sim_id}/data?{query}` | `cloud-iot/soracom/harvest-sim-data/get` | Harvest Data entries sent by one SIM (time ms, contentType, content); query from / to (ms), sort, limit, last\_evaluated\_key |
| GetDataEntries | `GET /v1/data/{resource_type}/{resource_id}?{query}` | `cloud-iot/soracom/harvest-data/get` | Harvest Data of any resource; resource\_type Sim \| Subscriber \| Device \| LoraDevice \| SigfoxDevice \| SoraCam, resource\_id the SIM id / IMSI / device id |
| ListDataResources | `GET /v1/data/resources?{query}` | `cloud-iot/soracom/harvest-resource/list` | Resources that have Harvest Data (resourceType, resourceId, lastModifiedTime); send query "" for none |

**GetSimData** (`cloud-iot/soracom/harvest-sim-data/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "8942310222000000000",
  "query": "from=1790812800000&to=1791244800000&sort=desc&limit=100"
}
```

## Harvest Files

| Event | Request | Topic | Notes |
| - | - | - | - |
| FindFiles | `GET /v1/files?{query}` | `cloud-iot/soracom/harvest-file/find` | Find Harvest Files by path prefix; query scope=private\|public and prefix (required) |
| ListFiles | `GET /v1/files/{scope}/{file_path}/?{query}` | `cloud-iot/soracom/harvest-directory/list` | Files and folders in a Harvest Files directory (file\_path without leading or trailing slash) |
| GetFile | `GET /v1/files/{scope}/{file_path}` | `cloud-iot/soracom/harvest-file/get` | Download a Harvest Files object (text / JSON content suits MQTT; large binaries do not) |
| PutFile | `PUT /v1/files/{scope}/{file_path}` | `cloud-iot/soracom/harvest-file/upload` | Upload a JSON file to Harvest Files (scope private), e.g. a config file devices fetch from harvest-files.soracom.io; body is the file content **(write)** |

**PutFile** (`cloud-iot/soracom/harvest-file/upload`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "scope": "private",
  "file_path": "config/line1.json",
  "body": {
    "setpoint": 180,
    "line": "1"
  }
}
```

## Downlink to devices

| Event | Request | Topic | Notes |
| - | - | - | - |
| SendDownlinkHttp | `POST /v1/sims/{sim_id}/downlink/http` | `cloud-iot/soracom/downlink-http/send` | Catalog: HTTP request from Soracom to the device on its SIM IP (no public IP or VPN needed); body \{"method", "path", "port", "ssl", "headers", "body" (string)}; response carries the device's status, headers and body **(write)** |
| SendDownlinkPing | `POST /v1/sims/{sim_id}/downlink/ping` | `cloud-iot/soracom/downlink-ping/send` | Reachability check: ICMP ping to the device (max 5 requests, timeout max 3 s); read-only |
| SendSmsToSim | `POST /v1/sims/{sim_id}/send_sms` | `cloud-iot/soracom/sms/send` | Send an SMS to the SIM (wake-up or command); encodingType 1 = GSM 7-bit (160 chars), 2 = UCS-2 (70 chars) **(write)** |

**SendDownlinkHttp** (`cloud-iot/soracom/downlink-http/send`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "8942310222000000000",
  "body": {
    "method": "POST",
    "path": "/api/setpoint",
    "port": 8080,
    "ssl": false,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"setpoint\": 180}"
  }
}
```

**SendSmsToSim** (`cloud-iot/soracom/sms/send`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "8942310222000000000",
  "body": {
    "encodingType": 1,
    "payload": "reboot"
  }
}
```

## Event handlers

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListEventHandlers | `GET /v1/event_handlers?{query}` | `cloud-iot/soracom/event-handler/list` | Event handlers; query target=operator\|imsi\|sim\|group (send "" for none) |
| GetEventHandler | `GET /v1/event_handlers/{handler_id}` | `cloud-iot/soracom/event-handler/get` | One event handler: target, ruleConfig, actionConfigList, status |
| CreateEventHandler | `POST /v1/event_handlers` | `cloud-iot/soracom/event-handler/create` | Create an event handler (rule on status, speed class, traffic volume, session ...); an ExecuteWebRequestAction pointed at SoracomWebhookReceiver pushes it to MQTT **(write)** |
| UpdateEventHandler | `PUT /v1/event_handlers/{handler_id}` | `cloud-iot/soracom/event-handler/update` | Replace an event handler (send the full definition, e.g. status inactive to mute it) **(write)** |

**CreateEventHandler** (`cloud-iot/soracom/event-handler/create`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "body": {
    "name": "porto-sim-status",
    "description": "SIM status changes to Coreflux",
    "status": "active",
    "targetGroupId": "3c9a1f2e-7b4d-4e8a-9c21-5f0d2b6a8e11",
    "ruleConfig": {
      "type": "SimStatusAttributeRule",
      "properties": {
        "inactiveTimeoutDateConst": "NEVER",
        "targetStatus": "inactive"
      }
    },
    "actionConfigList": [
      {
        "type": "ExecuteWebRequestAction",
        "properties": {
          "executionDateTimeConst": "IMMEDIATELY",
          "url": "https://broker.example.com/soracom/webhook/event-handler",
          "httpMethod": "POST",
          "contentType": "application/json",
          "headers": "{\"X-Coreflux-Secret\":\"<shared secret>\"}",
          "body": "{\"simId\":\"${simId}\",\"imsi\":\"${imsi}\",\"oldStatus\":\"${oldStatus}\",\"newStatus\":\"${newStatus}\"}"
        }
      }
    ]
  }
}
```

## Soracom Inventory (LwM2M devices)

| Event | Request | Topic | Notes |
| - | - | - | - |
| ListInventoryDevices | `GET /v1/devices?{query}` | `cloud-iot/soracom/inventory-device/list` | Soracom Inventory (LwM2M) devices; query tag\_name / tag\_value / limit (send "" for none) |
| ReadDeviceResource | `GET /v1/devices/{device_id}/{object_id}/{instance_id}/{lwm2m_resource_id}?{query}` | `cloud-iot/soracom/inventory-resource/get` | Read one LwM2M resource from the device, e.g. 3303/0/5700 (temperature sensor value); query model=true adds the object model |
| WriteDeviceResource | `PUT /v1/devices/{device_id}/{object_id}/{instance_id}/{lwm2m_resource_id}` | `cloud-iot/soracom/inventory-resource/update` | Write an LwM2M resource, e.g. 3308/0/5900 (set point value); body \{"value": 180} **(write)** |
| ExecuteDeviceResource | `POST /v1/devices/{device_id}/{object_id}/{instance_id}/{lwm2m_resource_id}/execute` | `cloud-iot/soracom/inventory-resource/execute` | Execute an LwM2M resource, e.g. 3/0/4 (device reboot); optional body \{"value": "\<argument>"} **(write)** |

**ReadDeviceResource** (`cloud-iot/soracom/inventory-resource/get`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "device_id": "d-0123456789abcdefghij",
  "object_id": "3303",
  "instance_id": "0",
  "lwm2m_resource_id": "5700",
  "query": "model=false"
}
```

**WriteDeviceResource** (`cloud-iot/soracom/inventory-resource/update`)

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "device_id": "d-0123456789abcdefghij",
  "object_id": "3308",
  "instance_id": "0",
  "lwm2m_resource_id": "5900",
  "body": {
    "value": 180
  }
}
```

## Audit logs

| Event | Request | Topic | Notes |
| - | - | - | - |
| GetApiAuditLogs | `GET /v1/audit_logs/api?{query}` | `cloud-iot/soracom/audit-log/list` | Soracom API call audit log (who called what, from where); query api\_kind, from\_epoch\_ms, to\_epoch\_ms, limit |

## Webhook receiver

`SoracomWebhookReceiver` listens on port `9007` and publishes each delivery on MQTT unchanged:

| Path | Soracom source | MQTT topic |
| - | - | - |
| `/soracom/webhook/beam` | Beam HTTP entry point (`http://beam.soracom.io:8888/`) or Unified Endpoint over HTTP | `cloud-iot/soracom/webhook-beam/received` |
| `/soracom/webhook/beam-udp` | Beam UDP → HTTP or TCP → HTTP entry point (`beam.soracom.io:23080`), body `{"payload": "<base64>"}` | `cloud-iot/soracom/webhook-beam-udp/received` |
| `/soracom/webhook/event-handler` | Event handler `ExecuteWebRequestAction` | `cloud-iot/soracom/webhook-event-handler/received` |

1. **Beam.** Configure the group with `PutGroupConfiguration` (namespace `SoracomBeam`) or in the User Console. Use key `http://beam.soracom.io:8888/` with destination `https://<public host>/soracom/webhook/beam`, or key `udp://beam.soracom.io:23080` (or `tcp://beam.soracom.io:23080`) with destination `https://<public host>/soracom/webhook/beam-udp`. Turn on the IMSI and SIM ID headers and the signature header with a pre-shared key. Devices then send to `http://uni.soracom.io` (Unified Endpoint) or the Beam entry point. Only `POST` is received.
2. **Event handlers.** Add an `ExecuteWebRequestAction` (see `CreateEventHandler`) with `url` `https://<public host>/soracom/webhook/event-handler`, `httpMethod` `POST`, `contentType` `application/json`, a shared-secret header and a body template such as `{"simId":"${simId}","imsi":"${imsi}","newStatus":"${newStatus}"}`.
3. Soracom calls the URL from its cloud. Put a reverse proxy or tunnel with a public TLS certificate in front of port `9007`, have it check `X-Soracom-Signature` or the shared-secret header, and forward to `http://<broker>:9007/soracom/webhook/...`. The connector itself does not check headers, and headers are not forwarded to MQTT.

> [!WARNING]
>
> Deploying the receiver opens an HTTP port on the broker. Deploy it only where you need push delivery.

> [!TIP]
>
> Soracom Beam also has an MQTT entry point that can forward device MQTT messages straight to a Coreflux broker. That path needs an MQTT bridge, not this REST connector.

## Examples

Read one day of data usage for a SIM:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "<sim id>",
  "query": "from=1790812800&to=1791244800&period=day"
}
```

Throttle a SIM that is using too much data:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "api_key": "<api key>",
  "token": "<token>",
  "sim_id": "<sim id>",
  "body": {
    "speedClass": "s1.minimum"
  }
}
```

Helper actions (refresh the session every 12 hours, keep the key and token in the broker with `KEEP TOPIC`, which is never published to MQTT, poll a SIM, send a set point to a device over HTTP downlink, fan event handler calls out to plant topics):

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SoracomLogin
ON EVERY 12 HOURS DO
    SET "kid" WITH GET SECRET "SORACOM_AUTH_KEY_ID"
    SET "key" WITH GET SECRET "SORACOM_AUTH_KEY"
    PUBLISH TOPIC "cloud-iot/soracom/token/create" WITH { "body": { "authKeyId": {kid}, "authKey": {key}, "tokenTimeoutSeconds": 86400 } }

DEFINE ACTION SoracomKeepSession
ON TOPIC "cloud-iot/soracom/token/create/response" DO
    SET "apikey" WITH GET JSON "apiKey" IN PAYLOAD AS STRING
    SET "token" WITH GET JSON "token" IN PAYLOAD AS STRING
    KEEP TOPIC "internal/soracom/api-key" WITH {apikey}
    KEEP TOPIC "internal/soracom/token" WITH {token}

DEFINE ACTION SoracomPollLineSimStatus
ON EVERY 1 HOUR DO
    SET "apikey" WITH GET TOPIC "internal/soracom/api-key" AS STRING
    SET "token" WITH GET TOPIC "internal/soracom/token" AS STRING
    SET "sim" WITH GET SECRET "SORACOM_SIM_ID"
    PUBLISH TOPIC "cloud-iot/soracom/sim/get" WITH { "api_key": {apikey}, "token": {token}, "sim_id": {sim} }

DEFINE ACTION SoracomSendSetpoint
ON TOPIC "porto/line1/setpoint" DO
    SET "apikey" WITH GET TOPIC "internal/soracom/api-key" AS STRING
    SET "token" WITH GET TOPIC "internal/soracom/token" AS STRING
    SET "sim" WITH GET SECRET "SORACOM_SIM_ID"
    SET "sp" WITH PAYLOAD AS STRING
    PUBLISH TOPIC "cloud-iot/soracom/downlink-http/send" WITH { "api_key": {apikey}, "token": {token}, "sim_id": {sim}, "body": { "method": "POST", "path": "/api/setpoint", "port": 8080, "headers": { "Content-Type": "text/plain" }, "body": {sp} } }

DEFINE ACTION SoracomSimEventToPlant
ON TOPIC "cloud-iot/soracom/webhook-event-handler/received" DO
    SET "sim" WITH (GET JSON "simId" IN PAYLOAD AS STRING)
    PUBLISH TOPIC "plant/soracom/sim/" + {sim} + "/event" WITH PAYLOAD
```

> [!NOTE]
>
> The helper actions keep the API key and token on retained `internal/soracom/...` topics. Restrict those topics with broker ACLs so only the broker's own actions can read them.

## Writes

Write events: ActivateSim, DeactivateSim, SuspendSim, SetSimToStandby, UpdateSimSpeedClass, PutSimTags, SetSimGroup, UnsetSimGroup, CreateGroup, PutGroupConfiguration, PutGroupTags, PutFile, SendDownlinkHttp, SendSmsToSim, CreateEventHandler, UpdateEventHandler, WriteDeviceResource, ExecuteDeviceResource. Activating a SIM starts billing, and status, speed class and group changes take effect on the live connection. `SendDownlinkHttp` and `ExecuteDeviceResource` act on the device itself, and `SendSmsToSim` is charged per message. `SendDownlinkPing` is read-only. No preset deletes anything or terminates a SIM.

## Not packaged

Every delete (SIMs, groups, tags, configuration, files, event handlers, devices), SIM termination and registration, virtual SIM creation, Arc, Napter, Krypton, SoraCam, Lagoon, Query Intelligence, billing and payment, users, roles and credential sets, Sigfox and LoRaWAN device APIs, and the Japan host (change `BASE_ADDRESS`). Harvest Data is written by devices through Unified Endpoint, not through the API.


# Splunk Enterprise and Cloud
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/splunk-enterprise-and-cloud

Client-mode REST API connector for a curated Splunk Enterprise/Cloud slice: HEC JSON and raw ingest, HEC health, and search job create/results

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of the Splunk [HTTP Event Collector](https://help.splunk.com/en/splunk-enterprise/get-data-in/collect-http-event-data/http-event-collector-rest-api-endpoints) and [search jobs REST API](https://help.splunk.com/en/splunk-enterprise/leverage-rest-apis/rest-api-tutorials/10.4/rest-api-tutorials/creating-searches-using-the-rest-api):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET collector health (helper) | `GET /services/collector/health` | Typically **unauthenticated**; HEC healthy payload |
| POST collector/event | `POST /services/collector/event` | `Authorization: Splunk <hec_token>`; JSON envelope (`event` required) |
| POST collector/raw | `POST /services/collector/raw` | Splunk token; `text/plain`; channel GUID when indexer ack enabled |
| POST search/jobs | `POST /services/search/jobs` | Management **:8089**; form-urlencoded `search=` + `output_mode=json` |
| GET search/jobs/\{sid}/results | `GET /services/search/jobs/{sid}/results` | Management **:8089**; results only when job `DONE` |

Default `BASE_ADDRESS` is `https://splunk.example.com:8088` (HEC). Topics use `itsm/splunk/<object>/<verb>`.

> [!NOTE]
>
> **Ports:** HEC defaults to **:8088**; management REST (search jobs) defaults to **:8089**. Keep HEC as primary BASE. For CreateSearchJob / GetSearchResults, point BASE at the management host (or deploy a second connector copy). Splunk Cloud HEC often uses `https://http-inputs-&lt;host&gt;.splunkcloud.com:8088`. Do not put a trailing slash on `BASE_ADDRESS`.

> [!NOTE]
>
> Prefer Hub secrets for the HEC token (`Authorization: Splunk …`). Search jobs need management Basic or Bearer credentials.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Splunk Enterprise and Cloud (HEC + search curated slice)
# Auth HEC: Authorization: Splunk {value.json.hec_token}
# Auth search: Authorization: Bearer {value.json.token} (or Basic)
# BASE_ADDRESS: https://splunk.example.com:8088  (HEC; use :8089 for search)
# GetCollectorHealth: no Authorization header

DEFINE CONNECTOR SplunkRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://splunk.example.com:8088"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getcollectorhealth
        WITH SOURCE_TOPIC "itsm/splunk/collector/health"
        WITH DESTINATION_TOPIC "itsm/splunk/collector/health/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/collector/health"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Postcollectorevent
        WITH SOURCE_TOPIC "itsm/splunk/collector/event"
        WITH DESTINATION_TOPIC "itsm/splunk/collector/event/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/collector/event"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Splunk {value.json.hec_token}"
        WITH BODY "{payload}"
    ADD EVENT Postcollectorraw
        WITH SOURCE_TOPIC "itsm/splunk/collector/raw"
        WITH DESTINATION_TOPIC "itsm/splunk/collector/raw/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/collector/raw?channel={value.json.channel}&sourcetype={value.json.sourcetype}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain"
            ADD "Authorization" "Splunk {value.json.hec_token}"
            ADD "X-Splunk-Request-Channel" "{value.json.channel}"
        WITH BODY "{payload}"
    ADD EVENT Createsearchjob
        WITH SOURCE_TOPIC "itsm/splunk/search/jobs/create"
        WITH DESTINATION_TOPIC "itsm/splunk/search/jobs/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/services/search/jobs"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Getsearchresults
        WITH SOURCE_TOPIC "itsm/splunk/search/jobs/results"
        WITH DESTINATION_TOPIC "itsm/splunk/search/jobs/results/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/services/search/jobs/{value.json.sid}/results?output_mode={value.json.output_mode}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getcollectorhealth | GET | `/services/collector/health` | `itsm/splunk/collector/health` | `itsm/splunk/collector/health/response` |
| Postcollectorevent | POST | `/services/collector/event` | `itsm/splunk/collector/event` | `itsm/splunk/collector/event/response` |
| Postcollectorraw | POST | `/services/collector/raw?channel=&sourcetype=` | `itsm/splunk/collector/raw` | `itsm/splunk/collector/raw/response` |
| Createsearchjob | POST | `/services/search/jobs` | `itsm/splunk/search/jobs/create` | `itsm/splunk/search/jobs/create/response` |
| Getsearchresults | GET | `/services/search/jobs/{sid}/results?output_mode=` | `itsm/splunk/search/jobs/results` | `itsm/splunk/search/jobs/results/response` |

## Auth

**HEC token (preferred for event/raw):**

1. Create an [HTTP Event Collector](https://help.splunk.com/en/splunk-enterprise/get-data-in/collect-http-event-data/format-events-for-http-event-collector) token in Splunk Web or via REST.
2. Set connector `BASE_ADDRESS` to your HEC host (`:8088` or Cloud ingest URL; no trailing slash).
3. Pass `hec_token` on the MQTT request payload so headers resolve:
   * `Authorization: Splunk {value.json.hec_token}`
4. Store the token in Hub secrets / `GET SECRET "SPLUNK_HEC_TOKEN"`. Never commit real credentials.

**HEC Basic (alternative):** username any string, password = HEC token — configure `WITH USERNAME` / `WITH PASSWORD GET SECRET "SPLUNK_HEC_TOKEN"` and drop Splunk Authorization headers.

**Management / search (`:8089`):**

1. Point `BASE_ADDRESS` at the management port (or a second connector copy).
2. Use `Authorization: Bearer {value.json.token}` **or** Basic `WITH USERNAME` / `WITH PASSWORD GET SECRET "SPLUNK_PASSWORD"`.

**GetCollectorHealth:** omit Authorization — most installs expose HEC health without a token.

## Example payloads

**Health:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{}
```

**Post JSON event from alarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "hec_token": "YOUR_HEC_TOKEN",
  "event": "Vibration above threshold — Zone A",
  "sourcetype": "coreflux:iot",
  "source": "coreflux",
  "fields": { "zone": "A", "metric": "vibration" }
}
```

**Post raw:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "hec_token": "YOUR_HEC_TOKEN",
  "channel": "00872DC6-AC83-4EDE-8AFE-8413C3825C4C",
  "sourcetype": "coreflux:raw"
}
```

Body is the raw text (`{payload}`). Include `channel` when indexer acknowledgement is enabled.

**Create search job** (BASE = management `:8089`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BEARER_OR_SESSION_TOKEN",
  "payload": "search=search%20index%3Dmain%20earliest%3D-15m%20%7C%20head%2010&output_mode=json"
}
```

**Get search results:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BEARER_OR_SESSION_TOKEN",
  "sid": "1728000000.12",
  "output_mode": "json"
}
```

## Deploy notes

* Deploy **`SplunkRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/splunk-enterprise-and-cloud](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/splunk-enterprise-and-cloud)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Stripe REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/stripe

Deferred client-mode REST API connector for a small Stripe subset (balance, charges, PaymentIntents, customers)

Technical Preview

## Overview

A **deferred, non-priority** client connector for a curated eight-operation slice of the [Stripe API](https://docs.stripe.com/api): balance, charges, PaymentIntents, customers, and products. It is kept as a reference. It is not part of the IIoT or enterprise-system catalog rollout.

> [!NOTE]
>
> Stripe calls need a secret key (`sk_test_…` or `sk_live_…`). A missing or invalid key returns HTTP 401. Prefer PaymentIntents over creating legacy Charges.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Stripe
# Generated from OpenAPI; credentials are placeholders only.
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-routes

DEFINE CONNECTOR StripeRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.stripe.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Stripe secret key as Bearer — pass {value.json.api_token} (sk_test_... / sk_live_...).
        # Prefer Hub secrets / GET SECRET upstream — never commit real keys.
        # Optional Basic (legacy): WITH USERNAME "sk_..." / WITH PASSWORD "" — Bearer header preferred.
    ADD EVENT Getbalance
        WITH SOURCE_TOPIC "integrations/stripe/request/Getbalance"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Getbalance"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/balance"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listcharges
        WITH SOURCE_TOPIC "integrations/stripe/request/Listcharges"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Listcharges"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/charges"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getcharge
        WITH SOURCE_TOPIC "integrations/stripe/request/Getcharge"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Getcharge"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/charges/{value.json.charge}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createpaymentintent
        WITH SOURCE_TOPIC "integrations/stripe/request/Createpaymentintent"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Createpaymentintent"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/payment_intents"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Getpaymentintent
        WITH SOURCE_TOPIC "integrations/stripe/request/Getpaymentintent"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Getpaymentintent"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/payment_intents/{value.json.intent}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createcustomer
        WITH SOURCE_TOPIC "integrations/stripe/request/Createcustomer"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Createcustomer"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/customers"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Getcustomer
        WITH SOURCE_TOPIC "integrations/stripe/request/Getcustomer"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Getcustomer"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/customers/{value.json.customer}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listproducts
        WITH SOURCE_TOPIC "integrations/stripe/request/Listproducts"
        WITH DESTINATION_TOPIC "integrations/stripe/response/Listproducts"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/products"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getbalance | GET | `/v1/balance` | `integrations/stripe/request/Getbalance` | `integrations/stripe/response/Getbalance` |
| Listcharges | GET | `/v1/charges` | `integrations/stripe/request/Listcharges` | `integrations/stripe/response/Listcharges` |
| Getcharge | GET | `/v1/charges/{value.json.charge}` | `integrations/stripe/request/Getcharge` | `integrations/stripe/response/Getcharge` |
| Createpaymentintent | POST | `/v1/payment_intents` | `integrations/stripe/request/Createpaymentintent` | `integrations/stripe/response/Createpaymentintent` |
| Getpaymentintent | GET | `/v1/payment_intents/{value.json.intent}` | `integrations/stripe/request/Getpaymentintent` | `integrations/stripe/response/Getpaymentintent` |
| Createcustomer | POST | `/v1/customers` | `integrations/stripe/request/Createcustomer` | `integrations/stripe/response/Createcustomer` |
| Getcustomer | GET | `/v1/customers/{value.json.customer}` | `integrations/stripe/request/Getcustomer` | `integrations/stripe/response/Getcustomer` |
| Listproducts | GET | `/v1/products` | `integrations/stripe/request/Listproducts` | `integrations/stripe/response/Listproducts` |

## Auth

Bearer secret key:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD "Authorization" "Bearer {value.json.api_token}"
```

**api\_token** `string` *required*

Stripe secret key. Publish it as `api_token` from a Hub secret. Never commit `sk_` keys. Dashboard: Stripe API keys.

Balance payload:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_STRIPE_SECRET_KEY"}
```

Create PaymentIntent (body is `{payload}`). Stripe also accepts form-urlencoded; this template sends `application/json`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"api_token": "YOUR_STRIPE_SECRET_KEY", "amount": 1000, "currency": "eur"}
```

## Try it

1. Add the connector on your broker that is allowed to call Stripe.
2. Publish the balance payload to `integrations/stripe/request/Getbalance`.
3. Subscribe to `integrations/stripe/response/Getbalance`.
4. Read a charge or intent by publishing `api_token` plus `charge` or `intent` to the matching request topic.

> [!NOTE]
>
> Probes: `GET /v1/balance` with no key returned HTTP 401, and an invalid `sk_test_` Bearer also returned HTTP 401.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps)


# SugarCRM
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/sugarcrm

LoT REST API connector for SugarCRM: open, note and close Cases from machine alarms, upsert records by external id, and filter or search any module

Technical Preview

## Overview

A client-mode connector for the [SugarCRM REST API](https://support.sugarcrm.com/documentation/sugar_developer/sugar_developer_guide_25.2/integration/web_services/rest_api/) (Sugar Sell, Sugar Serve and Sugar Enterprise, SugarCloud or on-premise) that connects plant and product events to CRM records. A connected machine that raises an alarm can open a Case on the customer's Account, the team can add notes while it is handled, and the Case can be closed when the alarm clears. Records can be upserted by an external id kept in the `sync_key` field (an asset serial, for example), Accounts can be kept current from live data, and any module can be listed, filtered, counted and searched.

Most events take the module name from the payload (`Cases`, `Accounts`, `Contacts`, `Bugs`, custom modules), so one connector covers the whole instance. Topics use `crm/sugarcrm/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. Set `BASE_ADDRESS` in the connector to your instance URL, for example `https://acme.sugarondemand.com`. Endpoints carry `/rest/v11_24`, the version the 25.2 reference covers. Newer releases keep serving older versions (26.1 goes up to `v11_27`), so change the prefix only if you need a newer endpoint.
2. Create a dedicated integration user. The `sync_key` events (`RecordGetBySyncKey`, `RecordUpsertBySyncKey`) need an admin user.
3. In **Admin > Configure API Platforms**, add a platform name for the broker (for example `coreflux`). Logging in with the default `base` platform can sign the same user out of the web client.

## Authentication

Sugar uses two-legged OAuth 2.0 with a password grant (see [REST API authentication](https://support.sugarcrm.com/documentation/sugar_developer/sugar_developer_guide_25.2/integration/web_services/rest_api/endpoints/oauth2token_post/)):

1. Publish to `crm/sugarcrm/oauth/token` (event `TokenGet`):

   ```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
   {"body": {"grant_type": "password", "client_id": "sugar", "client_secret": "", "username": "<user>", "password": "<password>", "platform": "coreflux"}}
   ```

2. Read `access_token` (valid 3600 seconds) and `refresh_token` (valid 14 days) from `crm/sugarcrm/oauth/token/response`. Pass `access_token` in every other payload; the connector sends it in the `OAuth-Token` header.

3. When a call answers 401, publish `{"body": {"grant_type": "refresh_token", "refresh_token": "<refresh token>", "client_id": "sugar", "client_secret": "", "platform": "coreflux"}}` to `crm/sugarcrm/oauth/refresh` for a new pair. Keep only the refresh token, never the password, in long-term storage.

> [!WARNING]
>
> Store the integration user's credentials as broker secrets (for example `SUGARCRM_USERNAME` and `SUGARCRM_PASSWORD`) and have a LoT action add them with `GET SECRET`. The token response topics carry live tokens: restrict them with a rule, never retain them, and do not put tokens in retained messages.

## Payload fields

| Field | Used by | Notes |
| - | - | - |
| `body` | `TokenGet`, `TokenRefresh` and every POST / PUT / PATCH event | JSON sent as the request body (record fields, a filter, or a bulk request list) |
| `access_token` | every event except `TokenGet` and `TokenRefresh` | Sent as the `OAuth-Token` header |
| `module` | the generic `Records...`, `Related...`, `DuplicateCheck`, `RecordAudit`, `EnumValues` events | Module name, case-sensitive: `Cases`, `Accounts`, `Contacts`, ... |
| `id` | events with `{id}` in the path | Record id (UUID) |
| `link` / `remote_id` | `RelatedList`, `RelatedCreate`, `RelationshipAdd` | Link field name (for example `cases`, `notes`, `contacts`) and the related record id |
| `field` | `EnumValues` | Dropdown field name, for example `status` |
| `sync_key` | `RecordGetBySyncKey`, `RecordUpsertBySyncKey` | External id stored in the record's `sync_key` field |
| `query` | `RecordsList`, `RelatedList`, `GlobalSearch`, `AccountsFilter` | URL-encoded query string |

## Events

| Event | Method | Endpoint | Source topic | Write |
| - | - | - | - | - |
| `TokenGet` | `POST` | `/rest/v11_24/oauth2/token` | `crm/sugarcrm/oauth/token` | |
| `TokenRefresh` | `POST` | `/rest/v11_24/oauth2/token` | `crm/sugarcrm/oauth/refresh` | |
| `Logout` | `POST` | `/rest/v11_24/oauth2/logout` | `crm/sugarcrm/oauth/logout` | |
| `Ping` | `GET` | `/rest/v11_24/ping` | `crm/sugarcrm/ping` | |
| `ServerTime` | `GET` | `/rest/v11_24/ping/whattimeisit` | `crm/sugarcrm/ping/time` | |
| `CurrentUser` | `GET` | `/rest/v11_24/me` | `crm/sugarcrm/me/get` | |
| `RecordsList` | `GET` | `/rest/v11_24/{module}?{query}` | `crm/sugarcrm/records/list` | |
| `RecordsFilter` | `POST` | `/rest/v11_24/{module}/filter` | `crm/sugarcrm/records/filter` | |
| `RecordsCount` | `POST` | `/rest/v11_24/{module}/filter/count` | `crm/sugarcrm/records/count` | |
| `RecordGet` | `GET` | `/rest/v11_24/{module}/{id}` | `crm/sugarcrm/records/get` | |
| `RecordCreate` | `POST` | `/rest/v11_24/{module}` | `crm/sugarcrm/records/create` | yes |
| `RecordUpdate` | `PUT` | `/rest/v11_24/{module}/{id}` | `crm/sugarcrm/records/update` | yes |
| `RecordGetBySyncKey` | `GET` | `/rest/v11_24/{module}/sync_key/{sync_key}` | `crm/sugarcrm/records/sync-key/get` | |
| `RecordUpsertBySyncKey` | `PATCH` | `/rest/v11_24/{module}/sync_key/{sync_key}` | `crm/sugarcrm/records/sync-key/upsert` | yes |
| `RelatedList` | `GET` | `/rest/v11_24/{module}/{id}/link/{link}?{query}` | `crm/sugarcrm/related/list` | |
| `RelatedCreate` | `POST` | `/rest/v11_24/{module}/{id}/link/{link}` | `crm/sugarcrm/related/create` | yes |
| `RelationshipAdd` | `POST` | `/rest/v11_24/{module}/{id}/link/{link}/{remote_id}` | `crm/sugarcrm/related/link` | yes |
| `DuplicateCheck` | `POST` | `/rest/v11_24/{module}/duplicateCheck` | `crm/sugarcrm/records/duplicate-check` | |
| `RecordAudit` | `GET` | `/rest/v11_24/{module}/{id}/audit` | `crm/sugarcrm/records/audit` | |
| `EnumValues` | `GET` | `/rest/v11_24/{module}/enum/{field}` | `crm/sugarcrm/enum/get` | |
| `GlobalSearch` | `GET` | `/rest/v11_24/globalsearch?{query}` | `crm/sugarcrm/search/global` | |
| `Bulk` | `POST` | `/rest/v11_24/bulk` | `crm/sugarcrm/bulk` | yes |
| `CaseCreate` | `POST` | `/rest/v11_24/Cases` | `crm/sugarcrm/cases/create` | yes |
| `CasesFilter` | `POST` | `/rest/v11_24/Cases/filter` | `crm/sugarcrm/cases/filter` | |
| `CaseNoteCreate` | `POST` | `/rest/v11_24/Cases/{id}/link/notes` | `crm/sugarcrm/cases/notes/create` | yes |
| `AccountsFilter` | `GET` | `/rest/v11_24/Accounts/filter?{query}` | `crm/sugarcrm/accounts/filter` | |
| `AccountUpdate` | `PUT` | `/rest/v11_24/Accounts/{id}` | `crm/sugarcrm/accounts/update` | yes |

No DELETE events are packaged on purpose. `TokenGet`, `TokenRefresh` and `Logout` are POSTs but only handle the session; `RecordsFilter`, `RecordsCount`, `CasesFilter` and `DuplicateCheck` are POSTs that only read.

## Connector excerpt

The full connector is in `SugarcrmRestApi.lot`. The first events look like this:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SugarCrmRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://your-instance.sugarondemand.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TokenGet
        WITH SOURCE_TOPIC "crm/sugarcrm/oauth/token"
        WITH DESTINATION_TOPIC "crm/sugarcrm/oauth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v11_24/oauth2/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Cache-Control" "no-cache"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RecordUpdate
        WITH SOURCE_TOPIC "crm/sugarcrm/records/update"
        WITH DESTINATION_TOPIC "crm/sugarcrm/records/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/rest/v11_24/{value.json.module}/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Cache-Control" "no-cache"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "OAuth-Token" "{value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CaseCreate
        WITH SOURCE_TOPIC "crm/sugarcrm/cases/create"
        WITH DESTINATION_TOPIC "crm/sugarcrm/cases/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v11_24/Cases"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Cache-Control" "no-cache"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "OAuth-Token" "{value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

**Case from an alarm**

Find the customer's Account with `crm/sugarcrm/accounts/filter` (`"query": "filter%5B0%5D%5Bname%5D%5B%24starts%5D=ACME&fields=id,name"`), then publish to `crm/sugarcrm/cases/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "body": {"name": "Press 7 overtemperature (E42)", "account_id": "<account id>", "priority": "P1", "type": "Product", "description": "Press 7 reported E42 at 13:55"}}
```

The response is the created Case, including its `id`.

**Note and close**

While the alarm is handled, publish to `crm/sugarcrm/cases/notes/create`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "id": "<case id>", "body": {"name": "Spindle temperature back to 61 C"}}
```

When it clears, publish `{"access_token": "...", "module": "Cases", "id": "<case id>", "body": {"status": "Closed"}}` to `crm/sugarcrm/records/update`. Valid status values come from `crm/sugarcrm/enum/get` with `"module": "Cases", "field": "status"`.

**Open cases for an account**

Publish to `crm/sugarcrm/cases/filter`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "body": {"filter": [{"account_id": "<account id>"}, {"status": {"$not_in": ["Closed", "Rejected"]}}], "fields": "id,name,status,priority", "max_num": 50}}
```

For just the number, send the same filter to `crm/sugarcrm/records/count` with `"module": "Cases"`.

**Upsert by asset id**

With an admin user, keep one record per machine by its serial in `sync_key`. Publish to `crm/sugarcrm/records/sync-key/upsert`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"access_token": "<from TokenGet>", "module": "Accounts", "sync_key": "PLANT-PORTO-01", "body": {"name": "ACME Porto plant", "description": "3 lines online"}}
```

Sugar answers 201 when it created the record and 200 when it updated it, with `{"record": "<id>"}`.

## Receiving changes from Sugar

Sugar pushes record changes out with Web Logic Hooks (**Admin > Web Logic Hooks**): pick a module, a trigger event (for example after save) and a URL, and Sugar sends the record as JSON. Deliveries are queued and sent by the "Dispatch Web Logic Hook" scheduled job, so they arrive on the next cron run, not instantly. Point the hook at a separate server-mode REST\_API connector that enables `ENABLE_SERVER`; Sugar does not sign deliveries, so restrict that endpoint (network or a secret path).

## Troubleshooting

| Symptom | Cause |
| - | - |
| 401 on `TokenGet` | Wrong username or password, or `client_id` / `platform` missing or not registered |
| 401 `invalid_grant` or `need_login` on a call | Access token expired (one hour) or missing; refresh it on `crm/sugarcrm/oauth/refresh` |
| Users get signed out of the web client | The broker logs in with the `base` platform; register and use a dedicated platform |
| 403 `not_authorized` on a `sync_key` event | Those endpoints are admin only |
| 404 `not_found` on a module endpoint | Module names are case-sensitive (`Cases`, not `cases`), or the module, link or record does not exist |
| Empty or partial lists | `max_num` defaults to 20; page with `offset` until `next_offset` is -1 |

## Related

* [REST API connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [SugarCRM REST API endpoint reference](https://support.sugarcrm.com/documentation/sugar_developer/sugar_developer_guide_25.2/integration/web_services/rest_api/endpoints/)


# Supabase
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/supabase

Client-mode REST API connector for Supabase PostgREST select/insert/upsert and Storage list/upload — MQTT into Postgres tables and buckets

Technical Preview

## Overview

A client-mode connector for a **curated** slice of the [Supabase Data API](https://supabase.com/docs/guides/api) (PostgREST on Postgres) plus [Storage](https://supabase.com/docs/guides/storage/uploads/standard-uploads) HTTP:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET rest/v1/\{table}?device\_id=eq.\{id} | `GET /rest/v1/{table}` | PostgREST filters + `select=` |
| POST rest/v1/\{table} | `POST /rest/v1/{table}` | Insert; `Prefer: return=representation` |
| Upsert merge-duplicates | `POST /rest/v1/{table}?on_conflict=` | `Prefer: resolution=merge-duplicates,return=representation` |
| (supporting) PATCH / DELETE | same table path + filter | Row updates / deletes |
| (supporting) OpenAPI | `GET /rest/v1/` | Auto-generated per project |
| (supporting) Storage list / upload | `/storage/v1/object/...` | List + standard upload |
| Database webhook | outbound from Supabase | Inbound receive → separate `ENABLE_SERVER` connector |

Default `BASE_ADDRESS` is `https://YOUR_PROJECT_REF.supabase.co` (no trailing slash). Topics use `data/supabase/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** every request needs `apikey` **and** `Authorization: Bearer &lt;jwt&gt;` (anon/publishable or service\_role/secret). Prefer Hub secrets (`GET SECRET "SUPABASE_ANON_KEY"` / `"SUPABASE_SERVICE_ROLE_KEY"`). Never expose service\_role in browsers.

> [!NOTE]
>
> **Database webhooks:** Supabase POSTs outbound when rows change. Receiving those callbacks on Coreflux needs a separate server-mode REST\_API connector — not part of this client-only template.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Supabase PostgREST / Storage
# Auth: apikey + Authorization Bearer {value.json.api_token}
# BASE_ADDRESS: https://YOUR_PROJECT_REF.supabase.co

DEFINE CONNECTOR SupabaseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_PROJECT_REF.supabase.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SelectRows
        WITH SOURCE_TOPIC "data/supabase/rows/select"
        WITH DESTINATION_TOPIC "data/supabase/rows/select/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/{value.json.table}?device_id=eq.{value.json.device_id}&select={value.json.select}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT UpsertRows
        WITH SOURCE_TOPIC "data/supabase/rows/upsert"
        WITH DESTINATION_TOPIC "data/supabase/rows/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/{value.json.table}?on_conflict={value.json.on_conflict}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Prefer" "resolution=merge-duplicates,return=representation"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
```

## Topics

| Event | Source topic | Destination topic |
| - | - | - |
| SelectRows | `data/supabase/rows/select` | `…/response` |
| InsertRows | `data/supabase/rows/insert` | `…/response` |
| UpsertRows | `data/supabase/rows/upsert` | `…/response` |
| PatchRows | `data/supabase/rows/patch` | `…/response` |
| DeleteRows | `data/supabase/rows/delete` | `…/response` |
| GetOpenApi | `data/supabase/openapi` | `…/response` |
| ListStorageObjects | `data/supabase/storage/list` | `…/response` |
| UploadStorageObject | `data/supabase/storage/upload` | `…/response` |

## Configuration

1. Set `BASE_ADDRESS` to `https://{project_ref}.supabase.co`.
2. Store anon or service\_role JWT in Hub secrets; map into MQTT `api_key` / `api_token` (or broker secret placeholders when your Hub wiring supports it).
3. Expose the target table to the Data API and add RLS policies for the role you use.
4. For upsert, pass `on_conflict` (unique / PK columns) and include those columns in the JSON body.

## References

* [Supabase Data API](https://supabase.com/docs/guides/api)
* [Creating API connectors](https://supabase.com/docs/guides/api/creating-routes)
* [Database webhooks](https://supabase.com/docs/guides/database/webhooks)
* [Storage standard uploads](https://supabase.com/docs/guides/storage/uploads/standard-uploads)
* [PostgREST tables and views](https://postgrest.org/en/stable/references/api/tables_views.html)

## Template reference

Generated from the shipped broker template `supabase` (`-connectorCode SUPABASE`). It lists every event the template defines.

### Auth

apikey header + Authorization: Bearer \{value.json.api\_token} (anon/publishable or service\_role/secret JWT). Prefer GET SECRET SUPABASE\_ANON\_KEY or SUPABASE\_SERVICE\_ROLE\_KEY. Never commit real credentials.

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`, `apikey: {value.json.api_key}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Supabase connector | no |
| `BaseUrl` | string | Supabase base URL without trailing slash (e.g. [https://YOUR\_PROJECT\_REF.supabase.co](https://YOUR_PROJECT_REF.supabase.co)) | yes |

`BASE_ADDRESS` default: `https://YOUR_PROJECT_REF.supabase.co`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `SelectRows` | GET | `/rest/v1/{value.json.table}?device_id=eq.{value.json.device_id}&select={value.json.select}` | `data/supabase/rows/select` | `data/supabase/rows/select/response` | `api_key`, `api_token`, `device_id`, `select`, `table` |
| `InsertRows` | POST | `/rest/v1/{value.json.table}` | `data/supabase/rows/insert` | `data/supabase/rows/insert/response` | `api_key`, `api_token`, `body`, `table` |
| `UpsertRows` | POST | `/rest/v1/{value.json.table}?on_conflict={value.json.on_conflict}` | `data/supabase/rows/upsert` | `data/supabase/rows/upsert/response` | `api_key`, `api_token`, `body`, `on_conflict`, `table` |
| `PatchRows` | PATCH | `/rest/v1/{value.json.table}?device_id=eq.{value.json.device_id}` | `data/supabase/rows/patch` | `data/supabase/rows/patch/response` | `api_key`, `api_token`, `body`, `device_id`, `table` |
| `DeleteRows` | DELETE | `/rest/v1/{value.json.table}?device_id=eq.{value.json.device_id}` | `data/supabase/rows/delete` | `data/supabase/rows/delete/response` | `api_key`, `api_token`, `device_id`, `table` |
| `GetOpenApi` | GET | `/rest/v1/` | `data/supabase/openapi` | `data/supabase/openapi/response` | `api_key`, `api_token` |
| `ListStorageObjects` | POST | `/storage/v1/object/list/{value.json.bucket}` | `data/supabase/storage/list` | `data/supabase/storage/list/response` | `api_key`, `api_token`, `body`, `bucket` |
| `UploadStorageObject` | POST | `/storage/v1/object/{value.json.bucket}/{value.json.object_path}` | `data/supabase/storage/upload` | `data/supabase/storage/upload/response` | `api_key`, `api_token`, `body`, `bucket`, `content_type`, `object_path`, `x_upsert` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode SUPABASE"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SupabaseRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_PROJECT_REF.supabase.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT SelectRows
        WITH SOURCE_TOPIC "data/supabase/rows/select"
        WITH DESTINATION_TOPIC "data/supabase/rows/select/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/{value.json.table}?device_id=eq.{value.json.device_id}&select={value.json.select}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT InsertRows
        WITH SOURCE_TOPIC "data/supabase/rows/insert"
        WITH DESTINATION_TOPIC "data/supabase/rows/insert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/{value.json.table}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Prefer" "return=representation"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpsertRows
        WITH SOURCE_TOPIC "data/supabase/rows/upsert"
        WITH DESTINATION_TOPIC "data/supabase/rows/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/{value.json.table}?on_conflict={value.json.on_conflict}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Prefer" "resolution=merge-duplicates,return=representation"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT PatchRows
        WITH SOURCE_TOPIC "data/supabase/rows/patch"
        WITH DESTINATION_TOPIC "data/supabase/rows/patch/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/rest/v1/{value.json.table}?device_id=eq.{value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Prefer" "return=representation"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteRows
        WITH SOURCE_TOPIC "data/supabase/rows/delete"
        WITH DESTINATION_TOPIC "data/supabase/rows/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/rest/v1/{value.json.table}?device_id=eq.{value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Prefer" "return=representation"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT GetOpenApi
        WITH SOURCE_TOPIC "data/supabase/openapi"
        WITH DESTINATION_TOPIC "data/supabase/openapi/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/"
        WITH HEADERS
            ADD "Accept" "application/openapi+json"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT ListStorageObjects
        WITH SOURCE_TOPIC "data/supabase/storage/list"
        WITH DESTINATION_TOPIC "data/supabase/storage/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/storage/v1/object/list/{value.json.bucket}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT UploadStorageObject
        WITH SOURCE_TOPIC "data/supabase/storage/upload"
        WITH DESTINATION_TOPIC "data/supabase/storage/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/storage/v1/object/{value.json.bucket}/{value.json.object_path}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "{value.json.content_type}"
            ADD "x-upsert" "{value.json.x_upsert}"
            ADD "apikey" "{value.json.api_key}"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `SelectRows` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'data/supabase/rows/select/response' &
mosquitto_pub -t 'data/supabase/rows/select' -m '{"api_key": "<api_key>", "api_token": "<api_token>", "device_id": "<device_id>", "select": "<select>", "table": "<table>"}'
```


# Tableau (Server and Cloud)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/tableau

LoT REST API connector for Tableau Server and Cloud: sign in with a PAT, pull view data as CSV, trigger extract refreshes, poll jobs and list content

Technical Preview

## Overview

A client-mode connector for the [Tableau REST API](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm) on Tableau Server and Tableau Cloud. Use it to refresh a dashboard's extract as soon as a shift, batch or line event lands on the broker, instead of waiting for the next schedule, and to pull summarized view data (OEE, scrap, downtime by line) back into MQTT as CSV.

| Event | Request | Notes |
| - | - | - |
| ServerInfo | `GET /api/3.24/serverinfo` | No auth. Smoke and version check (`restApiVersion`) |
| SignIn | `POST /api/3.24/auth/signin` | PAT credentials in the MQTT payload; returns `token` and the site LUID |
| SignOut | `POST /api/3.24/auth/signout` | Ends the session; `204` |
| ListWorkbooks | `GET /api/3.24/sites/{site}/workbooks?pageSize=&pageNumber=` | Paged list |
| ListViews | `GET /api/3.24/sites/{site}/views?pageSize=&pageNumber=` | Find view LUIDs |
| GetViewData | `GET /api/3.24/sites/{site}/views/{view}/data?maxAge=` | `200` `text/csv` |
| GetViewDataFiltered | `GET .../views/{view}/data?maxAge=&vf_<field>=<value>` | One view filter |
| ListDataSources | `GET /api/3.24/sites/{site}/datasources?pageSize=&pageNumber=` | Published data sources |
| RefreshDataSource | `POST /api/3.24/sites/{site}/datasources/{ds}/refresh` | Body `{}`; `202` with a job |
| RefreshWorkbook | `POST /api/3.24/sites/{site}/workbooks/{wb}/refresh` | Body `{}`; `202` with a job |
| ListExtractRefreshTasks | `GET /api/3.24/sites/{site}/tasks/extractRefreshes` | Task ids for RunExtractRefreshTask |
| RunExtractRefreshTask | `POST /api/3.24/sites/{site}/tasks/extractRefreshes/{task}/runNow` | Body `{}`; `200` with a job |
| GetJob | `GET /api/3.24/sites/{site}/jobs/{job}` | `finishCode` 0 = success, 1 = error, 2 = cancelled |

Set `BASE_ADDRESS` to your Tableau host with no trailing slash and no `/api`. On Tableau Cloud the host must include the pod, for example `https://prod-useast-a.online.tableau.com` or `https://10ax.online.tableau.com` (copy it from the browser address bar). Topics use `analytics/tableau/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** sign in once with a **personal access token** (PAT), then send `X-Tableau-Auth: {value.json.auth_token}` on every other call together with `site_id`, the site **LUID** from the sign-in response (not the site name or `contentUrl`). A session lasts 240 minutes on Tableau Server (default) and 120 minutes on Tableau Cloud. Keep the PAT in Hub secrets (suggested names `TABLEAU_PAT_NAME` and `TABLEAU_PAT_SECRET`, and `TABLEAU_AUTH_TOKEN` for the current session token). Never commit them into the `.lot`. Signing in again with the same PAT ends that PAT's earlier session, so give each broker or connector its own PAT.

> [!NOTE]
>
> **API version.** Every endpoint uses `/api/3.24`. That works on Tableau Cloud and on Tableau Server 2025.1 or later. For Tableau Server 2024.2 change `3.24` to `3.23` (2023.3 uses `3.21`). `ServerInfo` returns the highest version your server supports.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TableauRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_TABLEAU_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ServerInfo
        WITH SOURCE_TOPIC "analytics/tableau/server/info"
        WITH DESTINATION_TOPIC "analytics/tableau/server/info/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/serverinfo"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT SignIn
        WITH SOURCE_TOPIC "analytics/tableau/auth/signin"
        WITH DESTINATION_TOPIC "analytics/tableau/auth/signin/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/3.24/auth/signin"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT SignOut
        WITH SOURCE_TOPIC "analytics/tableau/auth/signout"
        WITH DESTINATION_TOPIC "analytics/tableau/auth/signout/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/3.24/auth/signout"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
    ADD EVENT ListWorkbooks
        WITH SOURCE_TOPIC "analytics/tableau/workbooks/list"
        WITH DESTINATION_TOPIC "analytics/tableau/workbooks/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/workbooks?pageSize={value.json.page_size}&pageNumber={value.json.page_number}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
    ADD EVENT ListViews
        WITH SOURCE_TOPIC "analytics/tableau/views/list"
        WITH DESTINATION_TOPIC "analytics/tableau/views/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/views?pageSize={value.json.page_size}&pageNumber={value.json.page_number}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
    ADD EVENT GetViewData
        WITH SOURCE_TOPIC "analytics/tableau/views/data/get"
        WITH DESTINATION_TOPIC "analytics/tableau/views/data/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/views/{value.json.view_id}/data?maxAge={value.json.max_age}"
        WITH HEADERS
            ADD "Accept" "text/csv"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
    ADD EVENT GetViewDataFiltered
        WITH SOURCE_TOPIC "analytics/tableau/views/data/filter"
        WITH DESTINATION_TOPIC "analytics/tableau/views/data/filter/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/views/{value.json.view_id}/data?maxAge={value.json.max_age}&vf_{value.json.filter_field}={value.json.filter_value}"
        WITH HEADERS
            ADD "Accept" "text/csv"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
    ADD EVENT ListDataSources
        WITH SOURCE_TOPIC "analytics/tableau/datasources/list"
        WITH DESTINATION_TOPIC "analytics/tableau/datasources/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/datasources?pageSize={value.json.page_size}&pageNumber={value.json.page_number}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
    ADD EVENT RefreshDataSource
        WITH SOURCE_TOPIC "analytics/tableau/datasources/refresh"
        WITH DESTINATION_TOPIC "analytics/tableau/datasources/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/datasources/{value.json.datasource_id}/refresh"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT RefreshWorkbook
        WITH SOURCE_TOPIC "analytics/tableau/workbooks/refresh"
        WITH DESTINATION_TOPIC "analytics/tableau/workbooks/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/workbooks/{value.json.workbook_id}/refresh"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListExtractRefreshTasks
        WITH SOURCE_TOPIC "analytics/tableau/tasks/extract-refreshes/list"
        WITH DESTINATION_TOPIC "analytics/tableau/tasks/extract-refreshes/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/tasks/extractRefreshes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
    ADD EVENT RunExtractRefreshTask
        WITH SOURCE_TOPIC "analytics/tableau/tasks/extract-refreshes/run"
        WITH DESTINATION_TOPIC "analytics/tableau/tasks/extract-refreshes/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/tasks/extractRefreshes/{value.json.task_id}/runNow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetJob
        WITH SOURCE_TOPIC "analytics/tableau/jobs/get"
        WITH DESTINATION_TOPIC "analytics/tableau/jobs/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/3.24/sites/{value.json.site_id}/jobs/{value.json.job_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Tableau-Auth" "{value.json.auth_token}"
```

## MQTT examples

**SignIn** (`analytics/tableau/auth/signin`). The whole payload becomes the request body. Expect **200**:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "credentials": {
    "personalAccessTokenName": "coreflux-broker",
    "personalAccessTokenSecret": "<pat-secret>",
    "site": { "contentUrl": "PlantAnalytics" }
  }
}
```

Response:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "credentials": {
    "site": { "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "contentUrl": "PlantAnalytics" },
    "user": { "id": "d5704762-603a-42b2-a9a7-f9cd2b2c4253" },
    "token": "HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "estimatedTimeToExpiration": "364:23:59"
  }
}
```

On Tableau Server, `"contentUrl": ""` signs in to the Default site. Tableau Cloud always needs the site's `contentUrl`.

**RunExtractRefreshTask** (`analytics/tableau/tasks/extract-refreshes/run`), expect **200** with a job:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "auth_token": "<token from SignIn>",
  "site_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "task_id": "9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c",
  "body": {}
}
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "job": { "id": "7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6", "mode": "Asynchronous", "type": "RefreshExtract" } }
```

Get `task_id` from **ListExtractRefreshTasks** (`analytics/tableau/tasks/extract-refreshes/list`, payload `{"auth_token": "...", "site_id": "..."}`). A second request while the refresh is still queued returns **409** (`409093`).

**RefreshDataSource** (`analytics/tableau/datasources/refresh`) and **RefreshWorkbook** (`analytics/tableau/workbooks/refresh`) refresh an extract without a schedule. Expect **202** with a job:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "auth_token": "<token>", "site_id": "<site LUID>", "datasource_id": "<data source LUID>", "body": {} }
```

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "auth_token": "<token>", "site_id": "<site LUID>", "workbook_id": "<workbook LUID>", "body": {} }
```

**GetJob** (`analytics/tableau/jobs/get`): `{"auth_token": "<token>", "site_id": "<site LUID>", "job_id": "7b6b59a8-ac3c-4d1d-2e9e-0b5b4ba8a7b6"}`. Poll until `completedAt` is set, then check `finishCode`. Only site and server administrators can query jobs.

**GetViewData** (`analytics/tableau/views/data/get`), expect **200** `text/csv`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "auth_token": "<token>", "site_id": "<site LUID>", "view_id": "2474164d-8d37-4a4c-abc7-c2070fd25fd5", "max_age": "5" }
```

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Line,Shift,OEE,Good Parts
A,1,0.82,1200
B,1,0.91,1340
```

**GetViewDataFiltered** (`analytics/tableau/views/data/filter`) adds one view filter, `vf_<filter_field>=<filter_value>`. URL-encode both values (a field called `Plant Line` becomes `Plant%20Line`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "auth_token": "<token>", "site_id": "<site LUID>", "view_id": "<view LUID>", "max_age": "5", "filter_field": "Line", "filter_value": "B" }
```

**ListWorkbooks**, **ListViews** and **ListDataSources** (`analytics/tableau/workbooks/list`, `.../views/list`, `.../datasources/list`): `{"auth_token": "<token>", "site_id": "<site LUID>", "page_size": "100", "page_number": "1"}`. `page_size` is 1 to 1000.

**ServerInfo** (`analytics/tableau/server/info`): any payload, for example `{}`. **SignOut** (`analytics/tableau/auth/signout`): `{"auth_token": "<token>"}`, expect **204** with an empty body.

Control fields (`auth_token`, `site_id`, ids, paging) only fill the URL and headers. Only `body` (and the full payload for SignIn) is sent as the request body.

## Keeping the session

Each request needs the token and site LUID from the latest sign-in. A small action can store them when the sign-in reply arrives:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TableauKeepSession
ON TOPIC "analytics/tableau/auth/signin/response" DO
    SET "token" WITH GET JSON "credentials.token" IN PAYLOAD AS STRING
    SET "site" WITH GET JSON "credentials.site.id" IN PAYLOAD AS STRING
    KEEP TOPIC "analytics/tableau/session/auth_token" WITH {token}
    KEEP TOPIC "analytics/tableau/session/site_id" WITH {site}
```

Sign in again before the session expires (for example every 100 minutes on Tableau Cloud), or when a call returns **401** with code `401002`. Restrict who can read the `analytics/tableau/#` topics with a rule, because sign-in payloads carry the PAT secret and replies carry the session token.

## Webhooks (companion, not packaged)

Tableau [webhooks](https://help.tableau.com/current/developer/webhooks/en-us/) can `POST` to an HTTPS URL when, for example, a data source refresh succeeds or fails (`DatasourceRefreshSucceeded`, `DatasourceRefreshFailed`, `WorkbookRefreshFailed`). Receiving them needs a separate `ENABLE_SERVER` REST API connector on a publicly reachable HTTPS address. That companion connector is not part of this template. Writing `.hyper` extract files uses the Hyper API client library, not REST, so it is not covered either.

## Notes

* View data is summary-level, and a dashboard returns only its first sheet. Data is cached for 60 minutes by default. Lower `max_age` (minimum 1) when you need fresher numbers.
* PATs expire after 15 days without use (and at the site's maximum PAT lifetime). Sign in at least that often or rotate the PAT.
* Tableau Cloud allows 20 concurrent long-running requests (view data, exports). Above that it returns **429**; retry later.
* Non-admin users can run refresh tasks and refresh data sources or workbooks they own. Querying jobs needs a site or server administrator. RunNow fails if an administrator has disabled it for the site.
* Before API 3.28, RefreshDataSource always runs a full refresh. Incremental refresh bodies need `/api/3.28`.
* Without `Accept: application/json`, Tableau answers in XML. The template sets JSON for every call except view data, which is CSV.
* Not covered: publishing workbooks or data sources (multipart uploads), view image, PDF and crosstab exports, the Metadata API (GraphQL), and connected-app JWT or unified access token sign-in. JWT sign-in works through the same SignIn event with a different `credentials` body.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Tableau REST API reference](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm)
* [Authentication methods](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_authentication.htm)
* [Jobs, tasks and schedules](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm)
* [Workbooks and views](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_workbooks_and_views.htm)
* [REST API versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm)
* [Tableau REST API Postman collection](https://github.com/tableau/tableau-postman)


# TDengine
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/tdengine

LoT REST API connector for TDengine: run SQL over taosAdapter REST, write InfluxDB line protocol or OpenTSDB JSON from MQTT, and check health

Technical Preview

## Overview

A client-mode connector for the [TDengine REST API](https://docs.tdengine.com/developer-guide/connectors-reference/rest-api/) served by [taosAdapter](https://docs.tdengine.com/operations-and-tooling/components/taosadapter/) (default port `6041`). It streams MQTT telemetry into TDengine and runs SQL from MQTT:

| Catalog connector event | Endpoint | Notes |
| - | - | - |
| POST SQL (INSERT, DDL) | `POST /rest/sql/{db}` | Raw SQL in the body (`text/plain`). Returns `{"code":0,"column_meta":…,"data":…,"rows":n}`. |
| POST SELECT (rows as objects) | `POST /rest/sql/{db}?row_with_meta=true` | Same SQL endpoint; each row comes back as a JSON object keyed by column name. |
| POST InfluxDB line write | `POST /influxdb/v1/write?db={db}&precision=ms` | Schemaless InfluxDB line protocol; super tables and columns auto-create. `204` on success. |
| POST OpenTSDB JSON write | `POST /opentsdb/v1/put/json/{db}` | Schemaless OpenTSDB JSON (`metric`, `timestamp`, `value`, `tags`). `204` on success. |
| GET ping | `GET /-/ping` | taosAdapter health, `200` (`503` when memory thresholds are exceeded). |

Default `BASE_ADDRESS` is `http://YOUR_TDENGINE_HOST:6041`. Replace `YOUR_DATABASE` in the endpoints with your database name; the database must already exist (create it once with `CREATE DATABASE IF NOT EXISTS …` through the SQL event). Topics use `data/tdengine/<object>/<verb>`.

> [!WARNING]
>
> **Check `code` in SQL responses.** By default taosAdapter answers `HTTP 200` even when a SQL statement or the login fails (`httpCodeServerError = false`). Success is `"code": 0`; anything else carries the error in `desc`, for example `{"code":855,"desc":"Authentication failure"}`. Schemaless writes do return `500` with a JSON error on failure.

## Auth

taosAdapter uses HTTP Basic authentication. The connector sets `WITH USERNAME` and `WITH PASSWORD GET SECRET "TDENGINE_PASSWORD"`, so store the database password as a Hub secret and never commit it. TDengine also accepts `Authorization: Taosd <token>` (token from `GET /rest/login/<user>/<password>`) and, on TDengine Cloud, a `?token=` query parameter. Change the default `root` / `taosdata` credentials on any real deployment.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TdengineRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "http://YOUR_TDENGINE_HOST:6041"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "false"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        WITH USERNAME "root"
        WITH PASSWORD GET SECRET "TDENGINE_PASSWORD"
    ADD EVENT Ping
        WITH SOURCE_TOPIC "data/tdengine/ping"
        WITH DESTINATION_TOPIC "data/tdengine/ping/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/-/ping"
    ADD EVENT ExecSql
        WITH SOURCE_TOPIC "data/tdengine/sql/exec"
        WITH DESTINATION_TOPIC "data/tdengine/sql/exec/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/sql/YOUR_DATABASE"
        WITH HEADERS
            ADD "Content-Type" "text/plain; charset=utf-8"
        WITH BODY "{payload}"
    ADD EVENT QueryRows
        WITH SOURCE_TOPIC "data/tdengine/query/rows"
        WITH DESTINATION_TOPIC "data/tdengine/query/rows/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/sql/YOUR_DATABASE?row_with_meta=true"
        WITH HEADERS
            ADD "Content-Type" "text/plain; charset=utf-8"
            ADD "Accept" "application/json"
        WITH BODY "{payload}"
    ADD EVENT WriteInfluxLine
        WITH SOURCE_TOPIC "data/tdengine/influx/write"
        WITH DESTINATION_TOPIC "data/tdengine/influx/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/influxdb/v1/write?db=YOUR_DATABASE&precision=ms"
        WITH HEADERS
            ADD "Content-Type" "text/plain; charset=utf-8"
        WITH BODY "{payload}"
    ADD EVENT WriteOpenTsdbJson
        WITH SOURCE_TOPIC "data/tdengine/opentsdb/write"
        WITH DESTINATION_TOPIC "data/tdengine/opentsdb/write/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/opentsdb/v1/put/json/YOUR_DATABASE"
        WITH HEADERS
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
```

## Example MQTT payloads

**Create a super table and insert a row (topic `data/tdengine/sql/exec`).** The payload is raw SQL text:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
CREATE STABLE IF NOT EXISTS site_readings (ts TIMESTAMP, temperature DOUBLE) TAGS (site BINARY(32))
```

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
INSERT INTO porto_site USING site_readings TAGS ('porto') VALUES (NOW, 21.5)
```

**Stream telemetry as line protocol (topic `data/tdengine/influx/write`):**

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
factory_line,site=porto temperature=22.5 1791234567890
```

**Stream telemetry as OpenTSDB JSON (topic `data/tdengine/opentsdb/write`):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "metric": "factory_otsdb", "timestamp": 1791234567890, "value": 23.5, "tags": { "site": "porto" } }
```

**Query rows (topic `data/tdengine/query/rows`):**

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SELECT site, temperature FROM site_readings
```

The response topic receives `{"code":0,"column_meta":[…],"data":[{"site":"porto","temperature":21.5}],"rows":1}`.

> [!TIP]
>
> `value` is a reserved word in TDengine SQL. Name metric columns something like `temperature` or `val` when you create tables by hand. Schemaless OpenTSDB writes store the reading in a `_value` column.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps](/latest/lot-language/routes/rest-api-apps/index)
* [InfluxDB](/latest/lot-language/routes/rest-api-apps/influxdb)
* [QuestDB](/latest/lot-language/routes/rest-api-apps/questdb)


# Telegram Bot API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/telegram-bot-api

Client-mode REST API connector for a curated Telegram Bot API slice: sendMessage, sendPhoto, getUpdates, setWebhook, and getMe

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Telegram Bot API](https://core.telegram.org/bots/api):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST sendMessage | `POST /bot{token}/sendMessage` | Text alerts to a chat |
| POST sendPhoto | `POST /bot{token}/sendPhoto` | Photo via `file_id` or HTTPS URL |
| GET getUpdates | `GET /bot{token}/getUpdates` | Long poll; mutually exclusive with webhook |
| POST setWebhook | `POST /bot{token}/setWebhook` | Register HTTPS webhook URL (client-mode) |
| GET getMe | `GET /bot{token}/getMe` | Credential check |

Default `BASE_ADDRESS` is `https://api.telegram.org`. Topics use `messaging/telegram/<object>/<verb>`.

> [!NOTE]
>
> Telegram authenticates by embedding the bot token in the URL path (`/bot{token}/METHOD_NAME`). This template does **not** send an Authorization header. Prefer Hub secrets for the token. `getUpdates` and `setWebhook` cannot both be active. Inbound webhook → MQTT is out of scope for this client-mode package.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Telegram Bot API
# Auth: path /bot{value.json.token}/METHOD (no Authorization header)
# BASE_ADDRESS: https://api.telegram.org

DEFINE CONNECTOR TelegramBotApiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.telegram.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getme
        WITH SOURCE_TOPIC "messaging/telegram/bot/get-me"
        WITH DESTINATION_TOPIC "messaging/telegram/bot/get-me/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bot{value.json.token}/getMe"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Sendmessage
        WITH SOURCE_TOPIC "messaging/telegram/message/send"
        WITH DESTINATION_TOPIC "messaging/telegram/message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bot{value.json.token}/sendMessage"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Sendphoto
        WITH SOURCE_TOPIC "messaging/telegram/photo/send"
        WITH DESTINATION_TOPIC "messaging/telegram/photo/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bot{value.json.token}/sendPhoto"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Getupdates
        WITH SOURCE_TOPIC "messaging/telegram/update/get"
        WITH DESTINATION_TOPIC "messaging/telegram/update/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/bot{value.json.token}/getUpdates?offset={value.json.offset}&limit={value.json.limit}&timeout={value.json.timeout}"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Setwebhook
        WITH SOURCE_TOPIC "messaging/telegram/webhook/set"
        WITH DESTINATION_TOPIC "messaging/telegram/webhook/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/bot{value.json.token}/setWebhook"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getme | GET | `/bot{token}/getMe` | `messaging/telegram/bot/get-me` | `messaging/telegram/bot/get-me/response` |
| Sendmessage | POST | `/bot{token}/sendMessage` | `messaging/telegram/message/send` | `messaging/telegram/message/send/response` |
| Sendphoto | POST | `/bot{token}/sendPhoto` | `messaging/telegram/photo/send` | `messaging/telegram/photo/send/response` |
| Getupdates | GET | `/bot{token}/getUpdates` | `messaging/telegram/update/get` | `messaging/telegram/update/get/response` |
| Setwebhook | POST | `/bot{token}/setWebhook` | `messaging/telegram/webhook/set` | `messaging/telegram/webhook/set/response` |

## Auth

1. Create a bot with [@BotFather](https://t.me/BotFather) and copy the bot token.
2. Set connector `BASE_ADDRESS` to `https://api.telegram.org`.
3. Pass `token` on the MQTT request payload so path placeholders resolve: `/bot{value.json.token}/…`.
4. Store the token in Hub secrets / `GET SECRET "TELEGRAM_BOT_TOKEN"`. Never commit real credentials.
5. Successful `getMe` / `sendMessage` returns **HTTP 200** with JSON `"ok": true`.

## Example payloads

**getMe:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN"
}
```

**sendMessage:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN",
  "chat_id": 123456789,
  "text": "Hello from Coreflux"
}
```

**sendPhoto:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN",
  "chat_id": 123456789,
  "photo": "https://example.com/image.png",
  "caption": "Snapshot"
}
```

**setWebhook:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "token": "YOUR_BOTFATHER_TOKEN",
  "url": "https://your.public.host/telegram/webhook"
}
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Official Bot API](https://core.telegram.org/bots/api)
* [Bot tutorial](https://core.telegram.org/bots/tutorial)


# Teltonika RMS
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/teltonika-rms

LoT REST API connector for Teltonika RMS: list routers, read monitoring and usage data, reboot devices, run commands, push config and queue firmware updates

Technical Preview

## Overview

One client-mode connector, **TeltonikaRMS**, for the [Teltonika RMS API](https://developers.rms.teltonika-networks.com/). RMS (Remote Management System) is Teltonika's cloud service for managing fleets of its industrial routers, gateways and modems, the boxes that often connect a plant cell, a substation or a remote pump station to the network.

Use the connector to bring fleet health into your Unified Namespace: list every gateway and its online state, signal and temperature, pull monitoring graphs and Data Collect values, track location and mobile data usage, and raise alerts. It can also act on the fleet: refresh metrics, reboot a device, run a CLI command, push configuration, queue a firmware update, run a saved task group and organise devices with tags.

| Event | Request | Notes |
| - | - | - |
| GetApiInfo | `GET /api/` | No auth; build and server time, a reachability check |
| ListDevices | `GET /devices?{query}` | Filters such as `status=online`, `model`, `tag_id`, `limit`, `fields` |
| GetDevice | `GET /devices/{device_id}` | Full device record: model, serial, firmware, signal, temperature, WAN state |
| UpdateDevice | `PUT /devices/{device_id}` | Name, description, monitoring intervals, user-set coordinates, tags |
| SetDevicesMonitoring | `PUT /devices/monitoring` | Turn monitoring on (`1`) or off (`0`) for many devices |
| GetDeviceStatistics | `GET /devices/statistics?{query}` | Counts per chart; `charts` is required (`status`, `model`, `signal`...) |
| GetOnlineDeviceStatistics | `GET /statistics/devices/online?{query}` | `start_date`, `end_date`, `company_id` required |
| GetDeviceGraphData | `GET /devices/{device_id}/information/{type}?{query}` | `type` is `dynamic`, `io` or `gps`; `start_date` / `end_date` required |
| GetDeviceCustomData | `GET /devices/{device_id}/custom-data?{query}` | Values gathered by Data Collect templates; dates required |
| GetDeviceLocation | `GET /devices/{device_id}/locations` | Last known position |
| GetDeviceLocationHistory | `GET /devices/{device_id}/locations/history?{query}` | Dates required |
| GetDeviceDataUsage | `GET /devices/{device_id}/data-usage?{query}` | Mobile data used; dates required |
| GetDeviceLogs | `GET /devices/{device_id}/logs?{query}` | `limit`, `offset` |
| ExecuteDeviceAction | `POST /devices/actions` | `reboot`, `update_metrics_data`, `download_backup`, `download_eventslog`, `download_troubleshoot`; returns a status channel |
| CancelDeviceAction | `POST /devices/actions/cancel` | By `device_id` and `job_id` lists |
| GetDeviceActionLogs | `GET /devices/actions/logs?{query}` | `device_id` and `tag_id` required |
| ExecuteDeviceCommand | `POST /devices/{device_id}/command` | Runs a shell command on the device; returns a status channel |
| GetActionStatus | `GET /status/channel/{channel}` | Polls the Status API; `404 CHANNEL_NOT_FOUND` once it expires |
| GetConfigSpecification | `GET /devices/configurator/specification?{query}` | Which settings RMS can configure on this device; `device_id` required |
| GetConfigValues | `POST /devices/configurator/configuration` | Read current values for configuration paths |
| SendConfiguration | `POST /devices/configurator/configure` | Push configuration to one or many devices |
| ListPendingUpdates | `GET /devices/updates/pending?{query}` | Queued firmware and backup jobs |
| SetUpdates | `POST /devices/updates/set` | Queue `update_firmware` or `upload_backup` with an RMS file id |
| ListTaskGroups | `GET /devices/tasks/groups?{query}` | |
| ExecuteTaskGroup | `POST /devices/tasks/groups/{task_group_id}` | Run saved CLI tasks on a device list |
| ListAlerts | `GET /alerts?{query}` | Filter by `device_id`, `type`, `company_id` |
| GetAlert | `GET /alerts/{alert_id}` | |
| DeleteAlert | `DELETE /alerts/{alert_id}` | |
| ListTags | `GET /tags?{query}` | |
| CreateTag | `POST /tags` | Returns `201` |
| DeleteTag | `DELETE /tags/{tag_id}` | |
| AssignDeviceTags | `PUT /devices/tags/assign` | |
| UnassignDeviceTags | `PUT /devices/tags/unassign` | |

Topics are `cloud-iot/teltonika-rms/<object>/<verb>`; every reply goes to `<topic>/response`. Paths in the table are relative to `/api`, except `GetApiInfo` (`/api/`) and `GetActionStatus` (`/status/channel/{channel}`).

## Authentication

Every authenticated event sends `Authorization: {authorization}`, so pass the whole header value: `"Bearer <token>"`.

* A **Personal Access Token** is the simple choice for one RMS account. Create it in RMS under account settings, Applications (RMS asks you to turn on two-factor authentication first) and tick only the scopes the connector needs, for example `devices:read`, `device_actions:write`, `device_configurations:write`, `device_alerts:read` and `tags:write`.
* An **OAuth 2.0 access token** is for apps that act on behalf of many RMS users.

Keep it in a broker secret (suggested `TELTONIKA_RMS_AUTHORIZATION`) and map it in with `GET SECRET`. A missing, expired or wrong token returns `401` with `{"success": false, "errors": [{"code": "UNAUTHORIZED"}]}`; some endpoints return `403` when the token or user is not allowed to do that.

## Basic Syntax

RMS is hosted by Teltonika, so `BASE_ADDRESS` is always `https://rms.teltonika-networks.com`.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TeltonikaRMS WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://rms.teltonika-networks.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "cloud-iot/teltonika-rms/device/list"
        WITH DESTINATION_TOPIC "cloud-iot/teltonika-rms/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ExecuteDeviceAction
        WITH SOURCE_TOPIC "cloud-iot/teltonika-rms/device-action/execute"
        WITH DESTINATION_TOPIC "cloud-iot/teltonika-rms/device-action/execute/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/devices/actions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetActionStatus
        WITH SOURCE_TOPIC "cloud-iot/teltonika-rms/action-status/get"
        WITH DESTINATION_TOPIC "cloud-iot/teltonika-rms/action-status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/status/channel/{value.json.channel}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
```

The full template, with all 33 events, is `TeltonikaRmsRestApi.lot` in the REST API app.

## MQTT examples

Request bodies go under `body`, so control fields like `authorization`, `device_id` and `query` are not sent to RMS. `device_id` is the numeric RMS id from `ListDevices`, not the serial number or IMEI.

**List online gateways**: publish to `cloud-iot/teltonika-rms/device/list`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <RMS token>",
  "query": "status=online&limit=100&fields=id,name,serial,model,status,signal,temperature"
}
```

Send `"query": ""` when you do not need filters.

**Read the last 6 hours of monitoring data**: publish to `cloud-iot/teltonika-rms/device-graph/get`. `type` is `dynamic` (signal, temperature, traffic), `io` or `gps`, and the dates must be URL-encoded:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <RMS token>",
  "device_id": 46920,
  "type": "dynamic",
  "query": "start_date=2026-10-05%2000%3A00%3A00&end_date=2026-10-05%2006%3A00%3A00"
}
```

**Refresh or reboot a device**: publish to `cloud-iot/teltonika-rms/device-action/execute`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <RMS token>",
  "body": {"action": "update_metrics_data", "device_id": [46920]}
}
```

RMS answers straight away with `{"success": true, "meta": {"channel": "private-status.1...."}}`. Publish that channel to `cloud-iot/teltonika-rms/action-status/get` as `{"authorization": "...", "channel": "<channel>"}` and repeat until each device's last entry has `"status": "completed"`. Use `"action": "reboot"` to restart the device.

**Run a command on a gateway**: publish `{"authorization": "...", "device_id": 46920, "body": {"command": "gsmctl -q"}}` to `cloud-iot/teltonika-rms/device-command/execute` and poll the returned channel the same way.

**Tag a device**: create a tag on `cloud-iot/teltonika-rms/tag/create` with `"body": {"name": "porto-line-1", "company_id": 125, "color": "#4287f5"}`, then assign it on `cloud-iot/teltonika-rms/device-tags/assign`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "authorization": "Bearer <RMS token>",
  "body": {"data": [{"device_id": 46920, "tag_id": [7841]}]}
}
```

## Helper actions

Keep the token in a broker secret, poll fleet status every few minutes, and refresh metrics on demand:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION TeltonikaRmsPollFleet
ON EVERY 5 MINUTES DO
    SET "auth" WITH GET SECRET "TELTONIKA_RMS_AUTHORIZATION"
    PUBLISH TOPIC "cloud-iot/teltonika-rms/device/list" WITH { "authorization": {auth}, "query": "limit=100&fields=id,name,serial,model,status,signal,temperature" }

DEFINE ACTION TeltonikaRmsRefreshDevice
ON TOPIC "porto/network/+/refresh" DO
    SET "auth" WITH GET SECRET "TELTONIKA_RMS_AUTHORIZATION"
    SET "device" WITH GET JSON "rms_device_id" IN PAYLOAD AS INT
    PUBLISH TOPIC "cloud-iot/teltonika-rms/device-action/execute" WITH { "authorization": {auth}, "body": { "action": "update_metrics_data", "device_id": [{device}] } }
```

Restrict who can publish to `cloud-iot/teltonika-rms/#` with a rule: its payloads carry the token, and events such as `ExecuteDeviceAction`, `ExecuteDeviceCommand`, `SendConfiguration` and `SetUpdates` can reboot, reconfigure or reflash devices in the field.

## Notes

* Errors come back on the response topic: `401` for a missing, expired or wrong token (or a resource that belongs to another company), `403` when the token or user is not allowed, `404` for an unknown device, alert, tag or channel, `422` for validation errors such as a missing `start_date` (the OpenAPI spec does not document rate limits, so keep polling coarse).
* Long-running actions (reboot, backups, firmware, commands, configuration) return a status channel instead of the result. RMS also streams these statuses over Socket.IO; this template uses the HTTP polling endpoint only.
* `GetDeviceStatistics` needs `charts`, and the graph, Data Collect, location history, data usage and online statistics events need `start_date` and `end_date`; RMS rejects the call with `422` otherwise.
* API calls act on the same devices, companies and credits as the RMS web interface, so a token sees exactly what its user sees.
* To talk to a single router on the local network instead of through RMS, use the device's own RUTOS API; this template covers the RMS cloud API only.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [balena](/latest/lot-language/routes/rest-api-apps/balena)
* [Mender](/latest/lot-language/routes/rest-api-apps/mender)


# The Things Stack
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/the-things-stack

LoT REST API connector for The Things Stack (TTN/TTI): read applications and devices, push LoRaWAN downlinks, and fetch stored uplink messages

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [The Things Stack](https://www.thethingsindustries.com/docs/api/reference/http/routes/) (The Things Network and The Things Industries) covering these connector events:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET application / end device | `GET /applications/{application_id}` (+ devices list/get) | Identity Server registry check |
| POST webhook downlink push | `POST /as/applications/{app}/webhooks/{id}/devices/{dev}/down/push` | Schedule downlink via webhook path |
| (AS downlink) | `POST /as/applications/{app}/devices/{dev}/down/push` | AppAs.DownlinkQueuePush |
| GET storage uplink\_message | `GET /as/applications/{app}/packages/storage/uplink_message` | Storage Integration (SSE / NDJSON) |

Default `BASE_ADDRESS` is `https://eu1.cloud.thethings.network/api/v3` (no trailing slash; substitute TTN `{region}` or TTI `https://{cluster}.cloud.thethings.industries/api/v3`). Topics use `cloud-iot/the-things-stack/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth header:** Pass the full `Authorization` value via MQTT JSON field `authorization` as `Bearer {api_key}` (Console / CLI API key, typically `NNSXS.…`). Prefer Hub secrets (`THE_THINGS_STACK_AUTH`). Never commit real credentials. See [Scheduling Downlinks](https://www.thethingsindustries.com/docs/integrations/webhooks/scheduling-downlinks/) and the [HTTP API connectors](https://www.thethingsindustries.com/docs/api/reference/http/routes/).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — The Things Stack curated slice
# Auth: Authorization via {value.json.authorization} (Bearer NNSXS.…)
# BASE_ADDRESS: https://eu1.cloud.thethings.network/api/v3  → substitute region / TTI cluster

DEFINE CONNECTOR TheThingsStackRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://eu1.cloud.thethings.network/api/v3"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetApplication
        WITH SOURCE_TOPIC "cloud-iot/the-things-stack/application/get"
        WITH DESTINATION_TOPIC "cloud-iot/the-things-stack/application/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/applications/{value.json.application_id}?field_mask={value.json.field_mask}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListDevices
        WITH SOURCE_TOPIC "cloud-iot/the-things-stack/device/list"
        WITH DESTINATION_TOPIC "cloud-iot/the-things-stack/device/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/applications/{value.json.application_id}/devices?field_mask={value.json.field_mask}&limit={value.json.limit}&page={value.json.page}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDevice
        WITH SOURCE_TOPIC "cloud-iot/the-things-stack/device/get"
        WITH DESTINATION_TOPIC "cloud-iot/the-things-stack/device/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/applications/{value.json.application_id}/devices/{value.json.device_id}?field_mask={value.json.field_mask}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT WebhookDownlinkPush
        WITH SOURCE_TOPIC "cloud-iot/the-things-stack/downlink/webhook-push"
        WITH DESTINATION_TOPIC "cloud-iot/the-things-stack/downlink/webhook-push/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/as/applications/{value.json.application_id}/webhooks/{value.json.webhook_id}/devices/{value.json.device_id}/down/push"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT AsDownlinkPush
        WITH SOURCE_TOPIC "cloud-iot/the-things-stack/downlink/as-push"
        WITH DESTINATION_TOPIC "cloud-iot/the-things-stack/downlink/as-push/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/as/applications/{value.json.application_id}/devices/{value.json.device_id}/down/push"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{payload}"
    ADD EVENT GetStoredUplinks
        WITH SOURCE_TOPIC "cloud-iot/the-things-stack/storage/uplink-message"
        WITH DESTINATION_TOPIC "cloud-iot/the-things-stack/storage/uplink-message/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/as/applications/{value.json.application_id}/packages/storage/uplink_message?limit={value.json.limit}&after={value.json.after}&before={value.json.before}"
        WITH HEADERS
            ADD "Accept" "text/event-stream"
            ADD "Authorization" "{value.json.authorization}"
```

## MQTT topics

| Event | Source topic | Response topic |
| - | - | - |
| GetApplication | `cloud-iot/the-things-stack/application/get` | `…/application/get/response` |
| ListDevices | `cloud-iot/the-things-stack/device/list` | `…/device/list/response` |
| GetDevice | `cloud-iot/the-things-stack/device/get` | `…/device/get/response` |
| WebhookDownlinkPush | `cloud-iot/the-things-stack/downlink/webhook-push` | `…/downlink/webhook-push/response` |
| AsDownlinkPush | `cloud-iot/the-things-stack/downlink/as-push` | `…/downlink/as-push/response` |
| GetStoredUplinks | `cloud-iot/the-things-stack/storage/uplink-message` | `…/storage/uplink-message/response` |

## References

* [HTTP API connectors](https://www.thethingsindustries.com/docs/api/reference/http/routes/)
* [Scheduling Downlinks (webhooks)](https://www.thethingsindustries.com/docs/integrations/webhooks/scheduling-downlinks/)
* [Application Server APIs](https://www.thethingsindustries.com/docs/api/reference/grpc/application_server/)
* [Storage Integration API](https://www.thethingsindustries.com/docs/api/reference/grpc/storage_integration/)
* [End Device APIs](https://www.thethingsindustries.com/docs/api/reference/grpc/end_device/)
* [Storage Integration guide](https://www.thethingsindustries.com/docs/integrations/storage/)


# ThingsBoard
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/thingsboard

Client-mode REST API connector for a curated ThingsBoard slice: device HTTP telemetry, server timeseries POST/GET, one-way RPC, and JWT login

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [ThingsBoard](https://thingsboard.io/docs/reference/rest-api/) (CE, PE, Cloud, and compatible Edge) covering JWT login, device HTTP telemetry, server-side timeseries, and one-way RPC:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST v1/\{token}/telemetry | `POST /v1/{accessToken}/telemetry` | Device HTTP API — access token in path |
| POST plugins/telemetry/.../timeseries/ANY | `POST /plugins/telemetry/{entityType}/{entityId}/timeseries/ANY` | Server-side write (JWT or ApiKey) |
| GET plugins/telemetry/.../values/timeseries | `GET /plugins/telemetry/{entityType}/{entityId}/values/timeseries?keys=…` | Latest / ranged values |
| POST rpc/oneway/\{id} | `POST /rpc/oneway/{deviceId}` | Server-side one-way RPC |
| (auth helper) | `POST /auth/login` · `GET /auth/user` | JWT obtain + connectivity check |

Default `BASE_ADDRESS` is `https://demo.thingsboard.io/api` (no trailing slash; substitute `{host}`). Topics use `cloud-iot/thingsboard/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth header:** ThingsBoard uses `X-Authorization` (not `Authorization`). Pass the full value (`Bearer {JWT}` or `ApiKey {key}`) via MQTT JSON field `x_authorization`. Device telemetry uses the access token in the URL only.

> [!NOTE]
>
> Prefer Hub secrets for JWT / device tokens (`THINGSBOARD_JWT`, `THINGSBOARD_DEVICE_TOKEN`).

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — ThingsBoard curated slice
# Auth: X-Authorization via {value.json.x_authorization} (Bearer JWT or ApiKey)
# Device telemetry: access token in path — no JWT header
# BASE_ADDRESS: https://demo.thingsboard.io/api

DEFINE CONNECTOR ThingsboardRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://demo.thingsboard.io/api"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Login
        WITH SOURCE_TOPIC "cloud-iot/thingsboard/auth/login"
        WITH DESTINATION_TOPIC "cloud-iot/thingsboard/auth/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/auth/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT GetCurrentUser
        WITH SOURCE_TOPIC "cloud-iot/thingsboard/auth/user"
        WITH DESTINATION_TOPIC "cloud-iot/thingsboard/auth/user/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/auth/user"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.x_authorization}"
    ADD EVENT PostDeviceTelemetry
        WITH SOURCE_TOPIC "cloud-iot/thingsboard/device/telemetry"
        WITH DESTINATION_TOPIC "cloud-iot/thingsboard/device/telemetry/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/{value.json.access_token}/telemetry"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT SaveTimeseries
        WITH SOURCE_TOPIC "cloud-iot/thingsboard/telemetry/save"
        WITH DESTINATION_TOPIC "cloud-iot/thingsboard/telemetry/save/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/plugins/telemetry/{value.json.entity_type}/{value.json.entity_id}/timeseries/ANY"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Authorization" "{value.json.x_authorization}"
        WITH BODY "{payload}"
    ADD EVENT GetTimeseriesValues
        WITH SOURCE_TOPIC "cloud-iot/thingsboard/telemetry/values"
        WITH DESTINATION_TOPIC "cloud-iot/thingsboard/telemetry/values/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/plugins/telemetry/{value.json.entity_type}/{value.json.entity_id}/values/timeseries?keys={value.json.keys}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.x_authorization}"
    ADD EVENT OneWayRpc
        WITH SOURCE_TOPIC "cloud-iot/thingsboard/rpc/oneway"
        WITH DESTINATION_TOPIC "cloud-iot/thingsboard/rpc/oneway/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rpc/oneway/{value.json.device_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Authorization" "{value.json.x_authorization}"
        WITH BODY "{payload}"
```

## References

* [ThingsBoard REST API](https://thingsboard.io/docs/reference/rest-api/)
* [Device HTTP telemetry](https://thingsboard.io/docs/reference/http-api/telemetry/)
* [Swagger UI (demo)](https://demo.thingsboard.io/swagger-ui/)
* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)


# Traccar (open-source GPS server) REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/traccar

Client-mode REST API connector for Traccar positions, devices, and connector reports

Technical Preview

## Overview

Client-mode REST API connector for Traccar positions, devices, and connector reports. `BASE_ADDRESS` defaults to `https://YOUR_TRACCAR_HOST:8082`. Auth: **Basic or Bearer session token**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

Basic or Bearer session token. Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR TraccarRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_TRACCAR_HOST:8082"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Authorization Bearer {value.json.api_token} — prefer Hub secrets / GET SECRET.
        # Optional Basic: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Listdevices
        WITH SOURCE_TOPIC "integrations/traccar/request/Listdevices"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Listdevices"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getdevice
        WITH SOURCE_TOPIC "integrations/traccar/request/Getdevice"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Getdevice"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listpositions
        WITH SOURCE_TOPIC "integrations/traccar/request/Listpositions"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Listpositions"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/positions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listpositionsbydevice
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/traccar/request/...`; responses on `integrations/traccar/response/...`.

## Template reference

Generated from the shipped broker template `traccar` (`-connectorCode TRACCAR`). It lists every event the template defines.

### Auth

Basic or Bearer session token

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Traccar connector | no |
| `BaseUrl` | string | Traccar base URL without trailing slash (e.g. https\://YOUR\_TRACCAR\_HOST:8082) | yes |

`BASE_ADDRESS` default: `https://YOUR_TRACCAR_HOST:8082`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listdevices` | GET | `/api/devices` | `integrations/traccar/request/Listdevices` | `integrations/traccar/response/Listdevices` | `api_token` |
| `Getdevice` | GET | `/api/devices/{value.json.id}` | `integrations/traccar/request/Getdevice` | `integrations/traccar/response/Getdevice` | `api_token`, `id` |
| `Listpositions` | GET | `/api/positions` | `integrations/traccar/request/Listpositions` | `integrations/traccar/response/Listpositions` | `api_token` |
| `Listpositionsbydevice` | GET | `/api/positions?deviceId={value.json.deviceId}` | `integrations/traccar/request/Listpositionsbydevice` | `integrations/traccar/response/Listpositionsbydevice` | `api_token`, `deviceId` |
| `Getroutereport` | GET | `/api/reports/route?deviceId={value.json.deviceId}&from={value.json.from}&to={value.json.to}` | `integrations/traccar/request/Getroutereport` | `integrations/traccar/response/Getroutereport` | `api_token`, `deviceId`, `from`, `to` |
| `Createsession` | POST | `/api/session` | `integrations/traccar/request/Createsession` | `integrations/traccar/response/Createsession` | `api_token`, `body` |
| `Listevents` | GET | `/api/events` | `integrations/traccar/request/Listevents` | `integrations/traccar/response/Listevents` | `api_token` |
| `Listgeofences` | GET | `/api/geofences` | `integrations/traccar/request/Listgeofences` | `integrations/traccar/response/Listgeofences` | `api_token` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode TRACCAR"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TraccarRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_TRACCAR_HOST:8082"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listdevices
        WITH SOURCE_TOPIC "integrations/traccar/request/Listdevices"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Listdevices"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getdevice
        WITH SOURCE_TOPIC "integrations/traccar/request/Getdevice"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Getdevice"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/devices/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listpositions
        WITH SOURCE_TOPIC "integrations/traccar/request/Listpositions"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Listpositions"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/positions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listpositionsbydevice
        WITH SOURCE_TOPIC "integrations/traccar/request/Listpositionsbydevice"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Listpositionsbydevice"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/positions?deviceId={value.json.deviceId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getroutereport
        WITH SOURCE_TOPIC "integrations/traccar/request/Getroutereport"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Getroutereport"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/reports/route?deviceId={value.json.deviceId}&from={value.json.from}&to={value.json.to}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Createsession
        WITH SOURCE_TOPIC "integrations/traccar/request/Createsession"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Createsession"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/session"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Listevents
        WITH SOURCE_TOPIC "integrations/traccar/request/Listevents"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Listevents"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Listgeofences
        WITH SOURCE_TOPIC "integrations/traccar/request/Listgeofences"
        WITH DESTINATION_TOPIC "integrations/traccar/response/Listgeofences"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/geofences"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listdevices` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/traccar/response/Listdevices' &
mosquitto_pub -t 'integrations/traccar/request/Listdevices' -m '{"api_token": "<api_token>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# Trackunit Iris
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/trackunit-iris

LoT REST API connector for Trackunit Iris: list assets, read locations, engine hours, fuel and faults, query events, sites and groups, and ingest asset data

Technical Preview

## Overview

Client-mode REST API connector for Trackunit construction and off-highway telematics: list and find assets, latest GeoJSON locations, engine hours, fuel and other machine insights from the Time Series and ISO 15143-3 (AEMP 2.0) APIs, CAN faults, asset events, device health, sites and groups, asset notes and custom fields, and broker data ingestion, with OAuth 2.0 client credentials (API Tokens v2); companion server connector for Trackunit webhooks.

This is one of the templates in the Trackunit REST API app (`trackunit`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

API Tokens v2: GetToken posts grant\_type=client\_credentials\&client\_id\&client\_secret\&scope (form) to [https://auth.trackunit.com/token/v2](https://auth.trackunit.com/token/v2); tokens last 1200 s, no refresh token. Legacy API user: GetTokenLegacy posts grant\_type=password\&username\&password\&scope=api (form) with Authorization: Basic base64(client\_id:client\_secret) to [https://auth.trackunit.com/token](https://auth.trackunit.com/token); tokens last 3600 s, refresh\_token with offline\_access. API events: Authorization: Bearer \<access\_token> from payload. Every event also sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Trackunit Iris connector | no |
| `BaseUrl` | string | Trackunit Iris base URL without trailing slash (e.g. [https://iris.trackunit.com](https://iris.trackunit.com)) | yes |

`BASE_ADDRESS` default: `https://iris.trackunit.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ListAssets` | GET | `/api/asset/v2/assets?{value.json.query}` | `fleet/trackunit/asset/list` | `fleet/trackunit/asset/list/response` | `access_token`, `query` |
| `GetAsset` | GET | `/api/asset/v2/assets/{value.json.id}` | `fleet/trackunit/asset/get` | `fleet/trackunit/asset/get/response` | `access_token`, `id` |
| `QueryAssets` | POST | `/api/asset/v2/assets/query` | `fleet/trackunit/asset/query` | `fleet/trackunit/asset/query/response` | `access_token`, `body` |
| `UpdateAsset` | PATCH | `/api/asset/v2/assets` | `fleet/trackunit/asset/update` | `fleet/trackunit/asset/update/response` | `access_token`, `body` |
| `QueryAssetNotes` | POST | `/api/asset/v2/assets/notes/query` | `fleet/trackunit/asset-note/query` | `fleet/trackunit/asset-note/query/response` | `access_token`, `body` |
| `UpdateAssetNote` | PATCH | `/api/asset/v2/assets/note` | `fleet/trackunit/asset-note/update` | `fleet/trackunit/asset-note/update/response` | `access_token`, `body` |
| `ListLocations` | GET | `/api/location/v1/locations?{value.json.query}` | `fleet/trackunit/location/list` | `fleet/trackunit/location/list/response` | `access_token`, `query` |
| `GetAssetLocation` | GET | `/api/location/v1/locations/{value.json.id}` | `fleet/trackunit/location/get` | `fleet/trackunit/location/get/response` | `access_token`, `id` |
| `ListAssetSeries` | GET | `/api/time-series/v1/assets/{value.json.id}/prometheus/api/v1/series?{value.json.query}` | `fleet/trackunit/series/list` | `fleet/trackunit/series/list/response` | `access_token`, `id`, `query` |
| `QueryAssetMetric` | GET | `/api/time-series/v1/assets/{value.json.id}/prometheus/api/v1/query?{value.json.query}` | `fleet/trackunit/metric/query` | `fleet/trackunit/metric/query/response` | `access_token`, `id`, `query` |
| `QueryAssetMetricRange` | GET | `/api/time-series/v1/assets/{value.json.id}/prometheus/api/v1/query_range?{value.json.query}` | `fleet/trackunit/metric/query-range` | `fleet/trackunit/metric/query-range/response` | `access_token`, `id`, `query` |
| `GetAssetRawMetrics` | GET | `/api/time-series/v1/assets/{value.json.id}/metrics?{value.json.query}` | `fleet/trackunit/metric/raw` | `fleet/trackunit/metric/raw/response` | `access_token`, `id`, `query` |
| `GetFleetSnapshot` | GET | `/public/api/aemp/v2/15143/-3/Fleet/{value.json.page}?{value.json.query}` | `fleet/trackunit/aemp-fleet/get` | `fleet/trackunit/aemp-fleet/get/response` | `access_token`, `page`, `query` |
| `GetEquipmentSnapshot` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}?{value.json.query}` | `fleet/trackunit/aemp-equipment/get` | `fleet/trackunit/aemp-equipment/get/response` | `access_token`, `id`, `query` |
| `GetOperatingHours` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/CumulativeOperatingHours/{value.json.start}/{value.json.end}/1` | `fleet/trackunit/operating-hours/get` | `fleet/trackunit/operating-hours/get/response` | `access_token`, `end`, `id`, `start` |
| `GetIdleHours` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/CumulativeIdleHours/{value.json.start}/{value.json.end}/1` | `fleet/trackunit/idle-hours/get` | `fleet/trackunit/idle-hours/get/response` | `access_token`, `end`, `id`, `start` |
| `GetFuelUsed` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/CumulativeFuelUsed/{value.json.start}/{value.json.end}/1` | `fleet/trackunit/fuel-used/get` | `fleet/trackunit/fuel-used/get/response` | `access_token`, `end`, `id`, `start` |
| `GetFuelRemaining` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/FuelRemainingRatio/{value.json.start}/{value.json.end}/1` | `fleet/trackunit/fuel-remaining/get` | `fleet/trackunit/fuel-remaining/get/response` | `access_token`, `end`, `id`, `start` |
| `GetLocationHistory` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/Locations/{value.json.start}/{value.json.end}/1` | `fleet/trackunit/location-history/get` | `fleet/trackunit/location-history/get/response` | `access_token`, `end`, `id`, `start` |
| `GetDiagnosticCodes` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/Faults/{value.json.start}/{value.json.end}/1` | `fleet/trackunit/diagnostic-code/get` | `fleet/trackunit/diagnostic-code/get/response` | `access_token`, `end`, `id`, `start` |
| `GetMachineInsightSeries` | GET | `/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/{value.json.insight}/{value.json.start}/{value.json.end}/1` | `fleet/trackunit/machine-insight/get` | `fleet/trackunit/machine-insight/get/response` | `access_token`, `end`, `id`, `insight`, `start` |
| `GetActiveFaults` | GET | `/public/api/can-faults/get-unit-active-faults?{value.json.query}` | `fleet/trackunit/fault/active` | `fleet/trackunit/fault/active/response` | `access_token`, `query` |
| `QueryFaults` | POST | `/public/api/can-faults/faults` | `fleet/trackunit/fault/query` | `fleet/trackunit/fault/query/response` | `access_token`, `body` |
| `ListActiveEvents` | POST | `/public/api/eventlog/v3/asset-event/active?{value.json.query}` | `fleet/trackunit/event/active` | `fleet/trackunit/event/active/response` | `access_token`, `body`, `query` |
| `QueryEventLog` | POST | `/public/api/eventlog/v3/asset-event/log?{value.json.query}` | `fleet/trackunit/event/log` | `fleet/trackunit/event/log/response` | `access_token`, `body`, `query` |
| `ListDeviceHealthIssues` | GET | `/api/device-health-issues/v1/issues?{value.json.query}` | `fleet/trackunit/device-health/list` | `fleet/trackunit/device-health/list/response` | `access_token`, `query` |
| `ListAssetDeviceHealthIssues` | GET | `/api/device-health-issues/v1/assets/{value.json.id}/issues?{value.json.query}` | `fleet/trackunit/asset-device-health/list` | `fleet/trackunit/asset-device-health/list/response` | `access_token`, `id`, `query` |
| `ListSites` | GET | `/api/site/v1/sites?{value.json.query}` | `fleet/trackunit/site/list` | `fleet/trackunit/site/list/response` | `access_token`, `query` |
| `ListAssetsOnSites` | POST | `/api/site/v1/sites/assets?{value.json.query}` | `fleet/trackunit/site-asset/list` | `fleet/trackunit/site-asset/list/response` | `access_token`, `body`, `query` |
| `ListSitesForAssets` | POST | `/api/site/v1/assets/sites?{value.json.query}` | `fleet/trackunit/asset-site/list` | `fleet/trackunit/asset-site/list/response` | `access_token`, `body`, `query` |
| `ListGroups` | GET | `/api/organization/v1/groups?{value.json.query}` | `fleet/trackunit/group/list` | `fleet/trackunit/group/list/response` | `access_token`, `query` |
| `ListGroupAssets` | GET | `/api/organization/v1/groups/{value.json.id}/assets` | `fleet/trackunit/group-asset/list` | `fleet/trackunit/group-asset/list/response` | `access_token`, `id` |
| `ListAlertConfigurations` | GET | `/api/alerts/v1/configurations?{value.json.query}` | `fleet/trackunit/alert-configuration/list` | `fleet/trackunit/alert-configuration/list/response` | `access_token`, `query` |
| `ListCustomFieldDefinitions` | GET | `/api/custom-fields/v1/definitions/?{value.json.query}` | `fleet/trackunit/custom-field-definition/list` | `fleet/trackunit/custom-field-definition/list/response` | `access_token`, `query` |
| `GetCustomFieldValues` | GET | `/api/custom-fields/v1/values/?{value.json.query}` | `fleet/trackunit/custom-field-value/list` | `fleet/trackunit/custom-field-value/list/response` | `access_token`, `query` |
| `SetCustomFieldValues` | POST | `/api/custom-fields/v1/set-values/` | `fleet/trackunit/custom-field-value/set` | `fleet/trackunit/custom-field-value/set/response` | `access_token`, `body` |
| `IngestAssetData` | POST | `/api/data-ingestion/v1beta2/assets/ingestions` | `fleet/trackunit/ingestion/create` | `fleet/trackunit/ingestion/create/response` | `access_token`, `body` |
| `GetIngestionStatus` | GET | `/api/data-ingestion/v1beta2/assets/ingestions/{value.json.id}?{value.json.query}` | `fleet/trackunit/ingestion/get` | `fleet/trackunit/ingestion/get/response` | `access_token`, `id`, `query` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode TRACKUNIT"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TrackunitIris WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://iris.trackunit.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListAssets
        WITH SOURCE_TOPIC "fleet/trackunit/asset/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/asset/v2/assets?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetAsset
        WITH SOURCE_TOPIC "fleet/trackunit/asset/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/asset/v2/assets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT QueryAssets
        WITH SOURCE_TOPIC "fleet/trackunit/asset/query"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/asset/v2/assets/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateAsset
        WITH SOURCE_TOPIC "fleet/trackunit/asset/update"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/asset/v2/assets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT QueryAssetNotes
        WITH SOURCE_TOPIC "fleet/trackunit/asset-note/query"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset-note/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/asset/v2/assets/notes/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateAssetNote
        WITH SOURCE_TOPIC "fleet/trackunit/asset-note/update"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset-note/update/response"
        WITH METHOD "PATCH"
        WITH ENDPOINT "/api/asset/v2/assets/note"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListLocations
        WITH SOURCE_TOPIC "fleet/trackunit/location/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/location/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/location/v1/locations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetAssetLocation
        WITH SOURCE_TOPIC "fleet/trackunit/location/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/location/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/location/v1/locations/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListAssetSeries
        WITH SOURCE_TOPIC "fleet/trackunit/series/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/series/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/time-series/v1/assets/{value.json.id}/prometheus/api/v1/series?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT QueryAssetMetric
        WITH SOURCE_TOPIC "fleet/trackunit/metric/query"
        WITH DESTINATION_TOPIC "fleet/trackunit/metric/query/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/time-series/v1/assets/{value.json.id}/prometheus/api/v1/query?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT QueryAssetMetricRange
        WITH SOURCE_TOPIC "fleet/trackunit/metric/query-range"
        WITH DESTINATION_TOPIC "fleet/trackunit/metric/query-range/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/time-series/v1/assets/{value.json.id}/prometheus/api/v1/query_range?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetAssetRawMetrics
        WITH SOURCE_TOPIC "fleet/trackunit/metric/raw"
        WITH DESTINATION_TOPIC "fleet/trackunit/metric/raw/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/time-series/v1/assets/{value.json.id}/metrics?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "*/*"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetFleetSnapshot
        WITH SOURCE_TOPIC "fleet/trackunit/aemp-fleet/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/aemp-fleet/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/{value.json.page}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetEquipmentSnapshot
        WITH SOURCE_TOPIC "fleet/trackunit/aemp-equipment/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/aemp-equipment/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetOperatingHours
        WITH SOURCE_TOPIC "fleet/trackunit/operating-hours/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/operating-hours/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/CumulativeOperatingHours/{value.json.start}/{value.json.end}/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetIdleHours
        WITH SOURCE_TOPIC "fleet/trackunit/idle-hours/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/idle-hours/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/CumulativeIdleHours/{value.json.start}/{value.json.end}/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetFuelUsed
        WITH SOURCE_TOPIC "fleet/trackunit/fuel-used/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/fuel-used/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/CumulativeFuelUsed/{value.json.start}/{value.json.end}/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetFuelRemaining
        WITH SOURCE_TOPIC "fleet/trackunit/fuel-remaining/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/fuel-remaining/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/FuelRemainingRatio/{value.json.start}/{value.json.end}/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetLocationHistory
        WITH SOURCE_TOPIC "fleet/trackunit/location-history/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/location-history/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/Locations/{value.json.start}/{value.json.end}/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetDiagnosticCodes
        WITH SOURCE_TOPIC "fleet/trackunit/diagnostic-code/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/diagnostic-code/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/Faults/{value.json.start}/{value.json.end}/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetMachineInsightSeries
        WITH SOURCE_TOPIC "fleet/trackunit/machine-insight/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/machine-insight/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/aemp/v2/15143/-3/Fleet/Equipment/ID/{value.json.id}/{value.json.insight}/{value.json.start}/{value.json.end}/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetActiveFaults
        WITH SOURCE_TOPIC "fleet/trackunit/fault/active"
        WITH DESTINATION_TOPIC "fleet/trackunit/fault/active/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/public/api/can-faults/get-unit-active-faults?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT QueryFaults
        WITH SOURCE_TOPIC "fleet/trackunit/fault/query"
        WITH DESTINATION_TOPIC "fleet/trackunit/fault/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/api/can-faults/faults"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListActiveEvents
        WITH SOURCE_TOPIC "fleet/trackunit/event/active"
        WITH DESTINATION_TOPIC "fleet/trackunit/event/active/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/api/eventlog/v3/asset-event/active?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT QueryEventLog
        WITH SOURCE_TOPIC "fleet/trackunit/event/log"
        WITH DESTINATION_TOPIC "fleet/trackunit/event/log/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/public/api/eventlog/v3/asset-event/log?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDeviceHealthIssues
        WITH SOURCE_TOPIC "fleet/trackunit/device-health/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/device-health/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/device-health-issues/v1/issues?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListAssetDeviceHealthIssues
        WITH SOURCE_TOPIC "fleet/trackunit/asset-device-health/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset-device-health/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/device-health-issues/v1/assets/{value.json.id}/issues?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListSites
        WITH SOURCE_TOPIC "fleet/trackunit/site/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/site/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/site/v1/sites?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListAssetsOnSites
        WITH SOURCE_TOPIC "fleet/trackunit/site-asset/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/site-asset/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/site/v1/sites/assets?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListSitesForAssets
        WITH SOURCE_TOPIC "fleet/trackunit/asset-site/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/asset-site/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/site/v1/assets/sites?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ListGroups
        WITH SOURCE_TOPIC "fleet/trackunit/group/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/group/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/organization/v1/groups?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListGroupAssets
        WITH SOURCE_TOPIC "fleet/trackunit/group-asset/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/group-asset/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/organization/v1/groups/{value.json.id}/assets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListAlertConfigurations
        WITH SOURCE_TOPIC "fleet/trackunit/alert-configuration/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/alert-configuration/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/alerts/v1/configurations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT ListCustomFieldDefinitions
        WITH SOURCE_TOPIC "fleet/trackunit/custom-field-definition/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/custom-field-definition/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/custom-fields/v1/definitions/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetCustomFieldValues
        WITH SOURCE_TOPIC "fleet/trackunit/custom-field-value/list"
        WITH DESTINATION_TOPIC "fleet/trackunit/custom-field-value/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/custom-fields/v1/values/?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT SetCustomFieldValues
        WITH SOURCE_TOPIC "fleet/trackunit/custom-field-value/set"
        WITH DESTINATION_TOPIC "fleet/trackunit/custom-field-value/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/custom-fields/v1/set-values/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT IngestAssetData
        WITH SOURCE_TOPIC "fleet/trackunit/ingestion/create"
        WITH DESTINATION_TOPIC "fleet/trackunit/ingestion/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/data-ingestion/v1beta2/assets/ingestions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetIngestionStatus
        WITH SOURCE_TOPIC "fleet/trackunit/ingestion/get"
        WITH DESTINATION_TOPIC "fleet/trackunit/ingestion/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/data-ingestion/v1beta2/assets/ingestions/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ListAssets` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/trackunit/asset/list/response' &
mosquitto_pub -t 'fleet/trackunit/asset/list' -m '{"access_token": "<access_token>", "query": "<query>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Trello
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/trello

LoT REST API connector for Trello: open maintenance cards from plant events, move, comment and label them, read boards for andon screens, and register webhooks

Technical Preview

## Overview

A client-mode connector for the [Trello REST API](https://developer.atlassian.com/cloud/trello/rest/) that turns plant events into visible work. A typical flow opens a card on the maintenance board when an alarm fires, moves it from **To do** to **In progress** to **Done** as the work order progresses, adds comments with live readings, labels it by line, assigns a technician, attaches a dashboard link, ticks lockout checklist items and records asset or downtime values in custom fields. The same connector reads boards, lists and cards back into the broker for andon screens and shift reports, and registers Trello webhooks that post board changes to a Coreflux server connector.

One connector carries 38 events (21 GET, 11 POST, 6 PUT; 17 writes, no DELETE). Topics use `devops/trello/<object>/<verb>`; each response is published on `<source topic>/response`.

## Setup

1. Create a Power-Up in the [Trello Power-Up admin portal](https://trello.com/power-ups/admin) and generate its API key.
2. Generate a user token for that key (the **Token** link next to the key, or `https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=<key>`). The token acts as the user who approved it, so use a service account that is a member of the boards you automate.
3. Keep both in broker secrets (for example `TRELLO_API_KEY` and `TRELLO_TOKEN`) and build the header value in a LoT action with `GET SECRET`. Never retain topics that carry it.

## Authentication

Trello takes the key and token either as `key` and `token` query parameters or in an `Authorization` header. This connector uses the header so credentials never appear in URLs or logs. Pass the whole header value in `authorization`:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "OAuth oauth_consumer_key=\"YOUR_KEY\", oauth_token=\"YOUR_TOKEN\""}
```

Public boards can be read with an empty `authorization`.

## Query parameters and bodies

Trello reads create and update fields from query parameters, so writes pass them URL-encoded in `query` (for example `idList=<listId>&name=Press%207%20overtemperature&pos=top`). Reads use `query` for `fields`, `filter` and limits; leave it empty for defaults. Only `CardCustomFieldSet` takes a JSON `body`. Values are sent as given, so URL-encode them yourself.

## Examples

Open a maintenance card when a press overheats (`devops/trello/cards/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<header value>", "query": "idList=5abbe4b7ddc1b351ef961414&name=Press%207%20overtemperature&desc=94%20C%20on%20line%202&pos=top&due=2026-10-06T08:00:00.000Z"}
```

Trello answers with the new card, including `id` and `shortUrl`.

Move it to **In progress** when a technician accepts the work order (`devops/trello/cards/update`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<header value>", "card": "<cardId>", "query": "idList=<inProgressListId>&pos=top"}
```

Record downtime minutes in a number custom field (`devops/trello/cards/custom-fields/set`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<header value>", "card": "<cardId>", "custom_field": "<fieldId>", "body": {"value": {"number": "42"}}}
```

Read the open maintenance queue for an andon screen (`devops/trello/lists/cards/list`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<header value>", "list": "<listId>", "query": "fields=name,due,labels,idMembers,shortUrl"}
```

Send board changes to a Coreflux server connector (`devops/trello/webhooks/create`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "<header value>", "query": "callbackURL=https%3A%2F%2Fbroker.example.com%2Ftrello%2Fevents&idModel=<boardId>&description=Porto%20maintenance"}
```

> [!WARNING]
>
> Trello sends a `HEAD` request to `callbackURL` when you create a webhook and only creates it if that answers 200. Each delivery carries an `X-Trello-Webhook` signature (HMAC-SHA1 of the body plus the callback URL, keyed with your Power-Up secret); check it in the receiving server connector.

## Events

| Event | Method | Endpoint | Source topic | Write | Notes |
| - | - | - | - | - | - |
| `MemberMe` | `GET` | `/1/members/me?{value.json.query}` | `devops/trello/members/me` | | Smoke: the member who owns the token (id, username, fullName, idBoards). query e.g. fields=username,fullName,idBoards (or empty). |
| `MemberBoardsList` | `GET` | `/1/members/{value.json.member}/boards?{value.json.query}` | `devops/trello/members/boards/list` | | Boards a member can see. member = me or a member id/username. query e.g. filter=open\&fields=name,url,idOrganization. |
| `OrganizationBoardsList` | `GET` | `/1/organizations/{value.json.org}/boards?{value.json.query}` | `devops/trello/organizations/boards/list` | | Boards in a Workspace. org = Workspace id or name. query e.g. filter=open\&fields=name,url. |
| `BoardGet` | `GET` | `/1/boards/{value.json.board}?{value.json.query}` | `devops/trello/boards/get` | | One board. board = board id or short link. query e.g. fields=name,url,closed\&lists=open\&labels=all (or empty). Public boards work with an empty authorization. |
| `BoardCreate` | `POST` | `/1/boards/?{value.json.query}` | `devops/trello/boards/create` | Yes | Create a board. query: name=Porto%20Line%202%20Maintenance\&idOrganization=\<workspaceId>\&defaultLists=true\&prefs\_permissionLevel=org (or idBoardSource=\<templateBoardId> to copy a template board). |
| `BoardUpdate` | `PUT` | `/1/boards/{value.json.board}?{value.json.query}` | `devops/trello/boards/update` | Yes | Rename, describe or close a board. query e.g. desc=Owned%20by%20Porto%20maintenance or closed=true. |
| `BoardListsList` | `GET` | `/1/boards/{value.json.board}/lists?{value.json.query}` | `devops/trello/boards/lists/list` | | Lists on a board (get list ids for CardCreate and CardUpdate). query e.g. filter=open\&fields=name,pos. |
| `BoardCardsList` | `GET` | `/1/boards/{value.json.board}/cards?{value.json.query}` | `devops/trello/boards/cards/list` | | Cards on a board. query e.g. fields=name,idList,due,dueComplete,labels,shortUrl (or empty). |
| `BoardLabelsList` | `GET` | `/1/boards/{value.json.board}/labels?{value.json.query}` | `devops/trello/boards/labels/list` | | Labels on a board (ids for CardLabelAdd). query e.g. fields=name,color\&limit=50. |
| `BoardMembersList` | `GET` | `/1/boards/{value.json.board}/members` | `devops/trello/boards/members/list` | | Members of a board (ids for CardMemberAdd). |
| `BoardCustomFieldsList` | `GET` | `/1/boards/{value.json.board}/customFields` | `devops/trello/boards/custom-fields/list` | | Custom field definitions on a board (ids and types for CardCustomFieldSet). Needs the Custom Fields Power-Up on the board. |
| `BoardActionsList` | `GET` | `/1/boards/{value.json.board}/actions?{value.json.query}` | `devops/trello/boards/actions/list` | | Board activity (audit trail). query e.g. filter=createCard,updateCard:idList,commentCard\&limit=50\&since=2026-10-05T00:00:00Z. |
| `ListGet` | `GET` | `/1/lists/{value.json.list}?{value.json.query}` | `devops/trello/lists/get` | | One list. query e.g. fields=name,closed,idBoard,pos (or empty). |
| `ListCardsList` | `GET` | `/1/lists/{value.json.list}/cards?{value.json.query}` | `devops/trello/lists/cards/list` | | Catalog 'GET lists/\{id}/cards'. Cards in a list, e.g. the open maintenance queue for an andon screen. query e.g. fields=name,due,labels,idMembers,shortUrl. |
| `ListCreate` | `POST` | `/1/lists?{value.json.query}` | `devops/trello/lists/create` | Yes | Add a list to a board. query: name=Waiting%20for%20parts\&idBoard=\<boardId>\&pos=bottom. |
| `ListUpdate` | `PUT` | `/1/lists/{value.json.list}?{value.json.query}` | `devops/trello/lists/update` | Yes | Rename, reorder, move or archive a list. query e.g. name=Done%20this%20week or closed=true or pos=top. |
| `CardGet` | `GET` | `/1/cards/{value.json.card}?{value.json.query}` | `devops/trello/cards/get` | | One card. query e.g. fields=name,desc,idList,due,dueComplete,labels,shortUrl\&checklists=all\&customFieldItems=true. |
| `CardCreate` | `POST` | `/1/cards?{value.json.query}` | `devops/trello/cards/create` | Yes | Catalog 'POST cards'. query: idList=\<listId> (required), name, desc, pos=top, due=2026-10-06T08:00:00.000Z, idLabels=\<id1>,\<id2>, idMembers=\<id>, urlSource=\<link> (attach a dashboard URL). Returns the card with id and shortUrl. |
| `CardUpdate` | `PUT` | `/1/cards/{value.json.card}?{value.json.query}` | `devops/trello/cards/update` | Yes | Catalog 'PUT cards/\{id} (move list)'. query e.g. idList=\<inProgressListId>\&pos=top, or dueComplete=true, or name/desc/due, or closed=true to archive. idBoard plus idList moves it to another board. |
| `CardActionsList` | `GET` | `/1/cards/{value.json.card}/actions?{value.json.query}` | `devops/trello/cards/actions/list` | | Card history and comments. query e.g. filter=commentCard,updateCard:idList. |
| `CardCommentAdd` | `POST` | `/1/cards/{value.json.card}/actions/comments?{value.json.query}` | `devops/trello/cards/comments/add` | Yes | Comment on a card. query: text=Temperature%20back%20to%2071%20C%20at%2014%3A20. |
| `CardLabelAdd` | `POST` | `/1/cards/{value.json.card}/idLabels?{value.json.query}` | `devops/trello/cards/labels/add` | Yes | Add an existing label to a card. query: value=\<labelId>. |
| `CardMemberAdd` | `POST` | `/1/cards/{value.json.card}/idMembers?{value.json.query}` | `devops/trello/cards/members/add` | Yes | Assign a member to a card. query: value=\<memberId>. |
| `CardAttachmentsList` | `GET` | `/1/cards/{value.json.card}/attachments?{value.json.query}` | `devops/trello/cards/attachments/list` | | Attachments on a card. query e.g. fields=name,url,date (or empty). |
| `CardAttachmentAddUrl` | `POST` | `/1/cards/{value.json.card}/attachments?{value.json.query}` | `devops/trello/cards/attachments/add-url` | Yes | Attach a link (no file upload). query: url=https%3A%2F%2Fbroker.example.com%2Fpanels%2Fpress7\&name=Press%207%20trend. |
| `CardChecklistsList` | `GET` | `/1/cards/{value.json.card}/checklists?{value.json.query}` | `devops/trello/cards/checklists/list` | | Checklists and their items on a card. query e.g. checkItems=all\&fields=name. |
| `ChecklistCreate` | `POST` | `/1/checklists?{value.json.query}` | `devops/trello/checklists/create` | Yes | Add a checklist to a card. query: idCard=\<cardId>\&name=Lockout%20tagout (or idChecklistSource=\<id> to copy a standard procedure). |
| `ChecklistItemAdd` | `POST` | `/1/checklists/{value.json.checklist}/checkItems?{value.json.query}` | `devops/trello/checklists/items/add` | Yes | Add an item to a checklist. query: name=Isolate%20hydraulic%20supply\&pos=bottom\&checked=false. |
| `CardCheckItemUpdate` | `PUT` | `/1/cards/{value.json.card}/checkItem/{value.json.check_item}?{value.json.query}` | `devops/trello/cards/check-items/update` | Yes | Tick or rename a checklist item on a card. query: state=complete (or incomplete), or name=... |
| `CardCustomFieldItemsList` | `GET` | `/1/cards/{value.json.card}/customFieldItems` | `devops/trello/cards/custom-fields/list` | | Custom field values set on a card. |
| `CardCustomFieldSet` | `PUT` | `/1/cards/{value.json.card}/customField/{value.json.custom_field}/item` | `devops/trello/cards/custom-fields/set` | Yes | Set a custom field value. body (JSON): \{"value":\{"number":"42"}} (or text, date, checked "true"), or \{"idValue":"\<optionId>"} for a dropdown. Empty value clears it. |
| `LabelCreate` | `POST` | `/1/labels?{value.json.query}` | `devops/trello/labels/create` | Yes | Create a label on a board. query: name=Line%202\&color=orange\&idBoard=\<boardId>. |
| `Search` | `GET` | `/1/search?{value.json.query}` | `devops/trello/search` | | Search cards, boards and more. query: query=press%207\&modelTypes=cards\&idBoards=\<boardId>\&cards\_limit=10\&partial=true. |
| `TokenWebhooksList` | `GET` | `/1/tokens/{value.json.token}/webhooks` | `devops/trello/webhooks/list` | | Webhooks owned by a token. token = the same Trello token used in authorization; do not retain this topic. |
| `WebhookCreate` | `POST` | `/1/webhooks/?{value.json.query}` | `devops/trello/webhooks/create` | Yes | Point board, list or card changes at a Coreflux ENABLE\_SERVER REST\_API connector. query: callbackURL=https%3A%2F%2Fbroker.example.com%2Ftrello%2Fevents\&idModel=\<boardId>\&description=Porto%20maintenance. Trello sends a HEAD request to callbackURL first and needs a 200. |
| `WebhookGet` | `GET` | `/1/webhooks/{value.json.webhook}` | `devops/trello/webhooks/get` | | One webhook (callbackURL, idModel, active, consecutiveFailures). |
| `WebhookUpdate` | `PUT` | `/1/webhooks/{value.json.webhook}?{value.json.query}` | `devops/trello/webhooks/update` | Yes | Pause, resume or retarget a webhook. query e.g. active=false or callbackURL=... |
| `Batch` | `GET` | `/1/batch?{value.json.query}` | `devops/trello/batch` | | Up to 10 GET calls in one request. query: urls=/boards/\<boardId>/lists,/lists/\<listId>/cards (paths without /1). |

## Limits

Trello allows 300 requests per 10 seconds per API key and 100 requests per 10 seconds per token, and answers `429` above that. `Batch` folds up to 10 GET calls into one request. Custom fields need the Custom Fields Power-Up on the board.

## Not packaged

* All DELETE endpoints (boards, lists, cards, labels, checklists, attachments, webhooks) on purpose; archive with `closed=true` instead.
* File uploads to cards (multipart); `CardAttachmentAddUrl` attaches links only.
* Board membership and Workspace administration, enterprise endpoints, Power-Up plugin data, stickers, emoji, notifications and saved searches.
* The incoming webhook direction: Trello posts change events to a separate `ENABLE_SERVER` REST\_API connector, which must answer the creation `HEAD` request and verify `X-Trello-Webhook`.


# Tulip
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/tulip

Client-mode REST API connector for a curated Tulip MES slice: table records create/update/list and machine attribute report

Technical Preview

## Overview

A client-mode connector for a **curated MES** slice of the [Tulip public API](https://support.tulip.co/apidocs/):

| Catalog connector event | Path |
| - | - |
| POST tables/\{id}/records | `POST /api/v3/tables/{tableId}/records` |
| PUT tables/\{id}/records/\{rid} | `PUT /api/v3/tables/{tableId}/records/{recordId}` |
| POST attributes/reportMachineAttributes | `POST /api/v3/attributes/report` |
| GET tables/\{id}/records?filters= | `GET /api/v3/tables/{tableId}/records?limit=&filters=` |
| list tables | `GET /api/v3/tables` |
| get table | `GET /api/v3/tables/{tableId}` |
| get record | `GET /api/v3/tables/{tableId}/records/{recordId}` |

`BASE_ADDRESS` is the instance root (`https://YOUR_INSTANCE.tulip.co`, no trailing slash). Topics use `mes/tulip/<object>/<verb>`. Interactive OpenAPI is also on each instance at `/apiDocs`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** HTTP **Basic** with a [Tulip API Token](https://support.tulip.co/docs/setting-up-a-tulip-api) — username = token **key**, password = token **secret**. Prefer Hub secrets (`TULIP_API_KEY` / `TULIP_API_SECRET`) or pass `Authorization: Basic {value.json.basic_b64}` on each MQTT payload. Never commit real tokens. Typical scopes: `tables:read`, `tables:write`, `attributes:report`.

> [!NOTE]
>
> For **global** API tokens, provide workspace context with path prefix `/api/v3/w/{workspaceId}/…` or header `X-Tulip-Workspace-ID`. Workspace-scoped tokens infer the workspace. The first workspace is often `DEFAULT`.

> [!NOTE]
>
> This template has **not** been verified against a live authenticated Tulip tenant.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Tulip (curated MES slice)
# Auth: HTTP Basic (API Token key:secret) via Basic {value.json.basic_b64}
#   or WITH USERNAME / WITH PASSWORD GET SECRET "TULIP_API_SECRET"
# BASE_ADDRESS: https://YOUR_INSTANCE.tulip.co

DEFINE CONNECTOR TulipRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.tulip.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listtables
        WITH SOURCE_TOPIC "mes/tulip/tables/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables?limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createtablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/create"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Updatetablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/update"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Listtablerecords
        WITH SOURCE_TOPIC "mes/tulip/tables/records/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records?limit={value.json.limit}&filters={value.json.filters}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Reportmachineattributes
        WITH SOURCE_TOPIC "mes/tulip/attributes/report"
        WITH DESTINATION_TOPIC "mes/tulip/attributes/report/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/attributes/report"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
```

## MQTT payload examples

**List tables:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_b64": "<Base64(api_key:api_secret)>",
  "limit": "20"
}
```

**Create record** — publish body fields in `payload` (must include `id`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_b64": "<Base64(api_key:api_secret)>",
  "tableId": "gthSX9t3tY2cJfBWe",
  "payload": "{\"id\":\"wo-1001\",\"status\":\"open\"}"
}
```

**Report machine attributes:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "basic_b64": "<Base64(api_key:api_secret)>",
  "payload": "{\"attributes\":[{\"machineId\":\"m1\",\"attributeId\":\"a1\",\"value\":42}]}"
}
```

## References

* [Tulip API introduction](https://support.tulip.co/apidocs/)
* [Table API guide](https://support.tulip.co/docs/table-api-guide)
* [Machine attributes API](https://support.tulip.co/docs/use-the-machine-attributes-api)
* [Set up a Tulip API Token](https://support.tulip.co/docs/setting-up-a-tulip-api)

## Template reference

Generated from the shipped broker template `tulip` (`-connectorCode TULIP`). It lists every event the template defines.

### Auth

HTTP Basic (Tulip API Token key as username + secret as password). Prefer Hub secrets TULIP\_API\_KEY / TULIP\_API\_SECRET or Authorization: Basic \{value.json.basic\_b64}. Never commit real credentials. Scopes: tables:read, tables:write, attributes:report.

Auth headers used by the template: `Authorization: Basic {value.json.basic_b64}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Tulip connector | no |
| `BaseUrl` | string | Tulip base URL without trailing slash (e.g. [https://YOUR\_INSTANCE.tulip.co](https://YOUR_INSTANCE.tulip.co)) | yes |

`BASE_ADDRESS` default: `https://YOUR_INSTANCE.tulip.co`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listtables` | GET | `/api/v3/tables?limit={value.json.limit}` | `mes/tulip/tables/list` | `mes/tulip/tables/list/response` | `basic_b64`, `limit` |
| `Gettable` | GET | `/api/v3/tables/{value.json.tableId}` | `mes/tulip/tables/get` | `mes/tulip/tables/get/response` | `basic_b64`, `tableId` |
| `Listtablerecords` | GET | `/api/v3/tables/{value.json.tableId}/records?limit={value.json.limit}&filters={value.json.filters}` | `mes/tulip/tables/records/list` | `mes/tulip/tables/records/list/response` | `basic_b64`, `filters`, `limit`, `tableId` |
| `Createtablerecord` | POST | `/api/v3/tables/{value.json.tableId}/records` | `mes/tulip/tables/records/create` | `mes/tulip/tables/records/create/response` | `basic_b64`, `body`, `tableId` |
| `Gettablerecord` | GET | `/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}` | `mes/tulip/tables/records/get` | `mes/tulip/tables/records/get/response` | `basic_b64`, `recordId`, `tableId` |
| `Updatetablerecord` | PUT | `/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}` | `mes/tulip/tables/records/update` | `mes/tulip/tables/records/update/response` | `basic_b64`, `body`, `recordId`, `tableId` |
| `Reportmachineattributes` | POST | `/api/v3/attributes/report` | `mes/tulip/attributes/report` | `mes/tulip/attributes/report/response` | `basic_b64`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode TULIP"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR TulipRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_INSTANCE.tulip.co"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listtables
        WITH SOURCE_TOPIC "mes/tulip/tables/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables?limit={value.json.limit}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Gettable
        WITH SOURCE_TOPIC "mes/tulip/tables/get"
        WITH DESTINATION_TOPIC "mes/tulip/tables/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Listtablerecords
        WITH SOURCE_TOPIC "mes/tulip/tables/records/list"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records?limit={value.json.limit}&filters={value.json.filters}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createtablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/create"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{value.json.body}"
    ADD EVENT Gettablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/get"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Updatetablerecord
        WITH SOURCE_TOPIC "mes/tulip/tables/records/update"
        WITH DESTINATION_TOPIC "mes/tulip/tables/records/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v3/tables/{value.json.tableId}/records/{value.json.recordId}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{value.json.body}"
    ADD EVENT Reportmachineattributes
        WITH SOURCE_TOPIC "mes/tulip/attributes/report"
        WITH DESTINATION_TOPIC "mes/tulip/attributes/report/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v3/attributes/report"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listtables` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/tulip/tables/list/response' &
mosquitto_pub -t 'mes/tulip/tables/list' -m '{"basic_b64": "<basic_b64>", "limit": "<limit>"}'
```


# Twilio (SMS, Voice, WhatsApp)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/twilio

LoT REST API connector for Twilio: send SMS and WhatsApp messages, place voice calls with TwiML, list messages and calls, and check account credentials

Technical Preview

## Overview

A client-mode connector for a **curated messaging/voice** slice of the [Twilio REST API](https://www.twilio.com/docs/usage/api) (v2010-04-01):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST Messages.json | `POST /2010-04-01/Accounts/{AccountSid}/Messages.json` | SMS from alarm; WhatsApp via `whatsapp:+E164` |
| POST Calls.json | `POST /2010-04-01/Accounts/{AccountSid}/Calls.json` | Voice alert with `Url` or inline `Twiml` |
| GET Messages.json | `GET /2010-04-01/Accounts/{AccountSid}/Messages.json` | List recent messages |
| GET Calls.json | `GET /2010-04-01/Accounts/{AccountSid}/Calls.json` | List recent calls |
| GET Account | `GET /2010-04-01/Accounts/{AccountSid}.json` | Credential check |

Default `BASE_ADDRESS` is `https://api.twilio.com`. Topics use `messaging/twilio/<object>/<verb>`.

> [!NOTE]
>
> Twilio authenticates with **HTTP Basic** (Account SID + Auth Token, or API Key SID + secret). Create Message/Call bodies use `application/x-www-form-urlencoded`, not JSON. The Verify API (`verify.twilio.com`) and inbound SMS webhook → MQTT are out of scope for this client-mode package.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Twilio
# Auth: HTTP Basic (Account SID + Auth Token) or Basic {value.json.basic_b64}
# BASE_ADDRESS: https://api.twilio.com

DEFINE CONNECTOR TwilioRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.twilio.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/x-www-form-urlencoded"
        # Optional config-level Basic:
        # WITH USERNAME "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        # WITH PASSWORD GET SECRET "TWILIO_AUTH_TOKEN"
    ADD EVENT Getaccount
        WITH SOURCE_TOPIC "messaging/twilio/account/get"
        WITH DESTINATION_TOPIC "messaging/twilio/account/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createmessage
        WITH SOURCE_TOPIC "messaging/twilio/message/send"
        WITH DESTINATION_TOPIC "messaging/twilio/message/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Messages.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Listmessages
        WITH SOURCE_TOPIC "messaging/twilio/message/list"
        WITH DESTINATION_TOPIC "messaging/twilio/message/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Messages.json?PageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
    ADD EVENT Createcall
        WITH SOURCE_TOPIC "messaging/twilio/call/create"
        WITH DESTINATION_TOPIC "messaging/twilio/call/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Calls.json"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Basic {value.json.basic_b64}"
        WITH BODY "{payload}"
    ADD EVENT Listcalls
        WITH SOURCE_TOPIC "messaging/twilio/call/list"
        WITH DESTINATION_TOPIC "messaging/twilio/call/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/2010-04-01/Accounts/{value.json.account_sid}/Calls.json?PageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Basic {value.json.basic_b64}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getaccount | GET | `/2010-04-01/Accounts/{AccountSid}.json` | `messaging/twilio/account/get` | `messaging/twilio/account/get/response` |
| Createmessage | POST | `/2010-04-01/Accounts/{AccountSid}/Messages.json` | `messaging/twilio/message/send` | `messaging/twilio/message/send/response` |
| Listmessages | GET | `/2010-04-01/Accounts/{AccountSid}/Messages.json` | `messaging/twilio/message/list` | `messaging/twilio/message/list/response` |
| Createcall | POST | `/2010-04-01/Accounts/{AccountSid}/Calls.json` | `messaging/twilio/call/create` | `messaging/twilio/call/create/response` |
| Listcalls | GET | `/2010-04-01/Accounts/{AccountSid}/Calls.json` | `messaging/twilio/call/list` | `messaging/twilio/call/list/response` |

## Auth

1. Create (or open) a Twilio account and copy the **Account SID** and **Auth Token** from the Console (or create an **API Key** SID + secret for production).
2. Set connector `BASE_ADDRESS` to `https://api.twilio.com`.
3. Configure Basic auth via Hub secrets (`WITH USERNAME` / `WITH PASSWORD GET SECRET "TWILIO_AUTH_TOKEN"`) **or** pass `basic_b64` (base64 of `sid:token`) on each MQTT payload.
4. Pass `account_sid` on every request so path placeholders resolve.
5. Never commit real credentials. Successful account fetch returns **HTTP 200**; create Message/Call typically returns **HTTP 201**.

## Example payloads

**getAccount:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_b64": "BASE64_OF_SID_COLON_TOKEN"
}
```

**createMessage (form body string for `{payload}`):**

```
To=%2B15558675310&From=%2B15557122661&Body=Coreflux%20alarm%3A%20Zone%20A
```

**createMessage WhatsApp:**

```
To=whatsapp%3A%2B15557770006&From=whatsapp%3A%2B15555238886&Body=Coreflux%20alarm
```

**createCall (inline TwiML):**

```
To=%2B15558675310&From=%2B15557122661&Twiml=%3CResponse%3E%3CSay%3ECoreflux%20alarm%3C%2FSay%3E%3C%2FResponse%3E
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [Twilio Message resource](https://www.twilio.com/docs/messaging/api/message-resource)
* [Twilio Call resource](https://www.twilio.com/docs/voice/api/call-resource)


# Ubidots
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ubidots

Client-mode REST API connector for a curated Ubidots v1.6 slice: post device values and read a variable

Technical Preview

# Ubidots

Client-mode REST API connector for a curated Ubidots v1.6 slice: post device values and read a variable.

* Hub category: **Cloud IoT**.
* Base: `https://industrial.api.ubidots.com`

## Template reference

Generated from the shipped broker template `ubidots` (`-connectorCode UBIDOTS`). It lists every event the template defines.

### Auth

Auth headers used by the template: `X-Auth-Token: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Ubidots connector | no |
| `BaseUrl` | string | Ubidots base URL without trailing slash (e.g. [https://industrial.api.ubidots.com](https://industrial.api.ubidots.com)) | yes |

`BASE_ADDRESS` default: `https://industrial.api.ubidots.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Postvalues` | POST | `/api/v1.6/devices/{value.json.device}` | `iot/ubidots/devices/post` | `iot/ubidots/devices/post/response` | `api_token`, `body`, `device` |
| `Getvalues` | GET | `/api/v1.6/devices/{value.json.device}/{value.json.variable}/values` | `iot/ubidots/variables/values` | `iot/ubidots/variables/values/response` | `api_token`, `device`, `variable` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode UBIDOTS"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR UbidotsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://industrial.api.ubidots.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Postvalues
        WITH SOURCE_TOPIC "iot/ubidots/devices/post"
        WITH DESTINATION_TOPIC "iot/ubidots/devices/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v1.6/devices/{value.json.device}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "X-Auth-Token" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getvalues
        WITH SOURCE_TOPIC "iot/ubidots/variables/values"
        WITH DESTINATION_TOPIC "iot/ubidots/variables/values/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v1.6/devices/{value.json.device}/{value.json.variable}/values"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Auth-Token" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Postvalues` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'iot/ubidots/devices/post/response' &
mosquitto_pub -t 'iot/ubidots/devices/post' -m '{"api_token": "<api_token>", "body": {}, "device": "<device>"}'
```


# UpKeep
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/upkeep

Client-mode REST API connector for a curated UpKeep v2 slice: list and create work orders

Technical Preview

# UpKeep

Client-mode REST API connector for a curated UpKeep v2 slice: list and create work orders.

* Hub category: **Field service**.
* Base: `https://api.onupkeep.com`

## Template reference

Generated from the shipped broker template `upkeep` (`-connectorCode UPKEEP`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Session-Token: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the UpKeep connector | no |
| `BaseUrl` | string | UpKeep base URL without trailing slash (e.g. [https://api.onupkeep.com](https://api.onupkeep.com)) | yes |

`BASE_ADDRESS` default: `https://api.onupkeep.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listworkorders` | GET | `/api/v2/work-orders` | `cmms/upkeep/workorders/list` | `cmms/upkeep/workorders/list/response` | `api_token` |
| `Createworkorder` | POST | `/api/v2/work-orders` | `cmms/upkeep/workorders/create` | `cmms/upkeep/workorders/create/response` | `api_token`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode UPKEEP"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR UpKeepRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.onupkeep.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listworkorders
        WITH SOURCE_TOPIC "cmms/upkeep/workorders/list"
        WITH DESTINATION_TOPIC "cmms/upkeep/workorders/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/work-orders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Session-Token" "Bearer {value.json.api_token}"
    ADD EVENT Createworkorder
        WITH SOURCE_TOPIC "cmms/upkeep/workorders/create"
        WITH DESTINATION_TOPIC "cmms/upkeep/workorders/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/work-orders"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Session-Token" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listworkorders` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'cmms/upkeep/workorders/list/response' &
mosquitto_pub -t 'cmms/upkeep/workorders/list' -m '{"api_token": "<api_token>"}'
```


# Ups Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/ups-api

LoT REST API connector for UPS APIs: track packages, rate and shop shipments, validate addresses, create labels and pickups, and handle paperless documents

Technical Preview

## Overview

Client-mode REST API connector for the UPS Developer Portal APIs: OAuth 2.0 client credentials, package tracking, Track Alert push subscriptions, rating and shop rates, address validation, time in transit, locations and Access Points, shipments and labels (purchase), void, label recovery, landed cost, pickups (purchase), paperless trade documents, Quantum View, Delivery Intercept eligibility and charges, dangerous goods data; companion server connector for Track Alert webhooks.

This is one of the templates in the UPS Developer Portal REST API app (`ups-developer-portal`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

OAuth 2.0 client credentials (client\_secret\_basic): GetToken posts grant\_type=client\_credentials (form) to /security/v1/oauth/token with Authorization: Basic base64(client\_id:client\_secret); GetTokenForAccount adds x-merchant-id (shipper account). Reply access\_token, token\_type, issued\_at, expires\_in (seconds, string), status; no refresh token. UpsApi events: Authorization: Bearer \<access\_token>, transId \<unique, max 32> and transactionSrc Coreflux-Broker. Every event also sends User-Agent: Coreflux-Broker.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Ups Api connector | no |
| `BaseUrl` | string | Ups Api base URL without trailing slash (e.g. [https://onlinetools.ups.com](https://onlinetools.ups.com)) | yes |

`BASE_ADDRESS` default: `https://onlinetools.ups.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `TrackPackage` | GET | `/api/track/v1/details/{value.json.id}?{value.json.query}` | `fleet/ups/track/get` | `fleet/ups/track/get/response` | `access_token`, `id`, `query`, `trans_id` |
| `TrackShipment` | GET | `/api/track/v1/shipment/details/{value.json.id}?{value.json.query}` | `fleet/ups/track-shipment/get` | `fleet/ups/track-shipment/get/response` | `access_token`, `id`, `query`, `trans_id` |
| `TrackByReference` | GET | `/api/track/v1/reference/details/{value.json.id}?{value.json.query}` | `fleet/ups/track-reference/get` | `fleet/ups/track-reference/get/response` | `access_token`, `id`, `query`, `trans_id` |
| `SubscribeTrackAlert` | POST | `/api/track/v2/subscription/standard/package` | `fleet/ups/track-alert/create` | `fleet/ups/track-alert/create/response` | `access_token`, `body`, `trans_id` |
| `SubscribeTrackAlertEnhanced` | POST | `/api/track/v2/subscription/enhanced/package` | `fleet/ups/track-alert-enhanced/create` | `fleet/ups/track-alert-enhanced/create/response` | `access_token`, `body`, `trans_id` |
| `RateShipment` | POST | `/api/rating/v2409/Rate` | `fleet/ups/rate/get` | `fleet/ups/rate/get/response` | `access_token`, `body`, `trans_id` |
| `ShopRates` | POST | `/api/rating/v2409/Shop` | `fleet/ups/rate-shop/get` | `fleet/ups/rate-shop/get/response` | `access_token`, `body`, `trans_id` |
| `ShopRatesWithTransit` | POST | `/api/rating/v2409/Shoptimeintransit` | `fleet/ups/rate-shop-transit/get` | `fleet/ups/rate-shop-transit/get/response` | `access_token`, `body`, `trans_id` |
| `ValidateAddress` | POST | `/api/addressvalidation/v2/3?{value.json.query}` | `fleet/ups/address/validate` | `fleet/ups/address/validate/response` | `access_token`, `body`, `query`, `trans_id` |
| `GetTransitTimes` | POST | `/api/shipments/v1/transittimes` | `fleet/ups/transit-time/get` | `fleet/ups/transit-time/get/response` | `access_token`, `body`, `trans_id` |
| `FindLocations` | POST | `/api/locations/v3/search/availabilities/1` | `fleet/ups/location/search` | `fleet/ups/location/search/response` | `access_token`, `body`, `trans_id` |
| `FindAccessPoints` | POST | `/api/locations/v3/search/availabilities/64` | `fleet/ups/access-point/search` | `fleet/ups/access-point/search/response` | `access_token`, `body`, `trans_id` |
| `CreateShipment` | POST | `/api/shipments/v2409/ship` | `fleet/ups/shipment/create` | `fleet/ups/shipment/create/response` | `access_token`, `body`, `trans_id` |
| `VoidShipment` | DELETE | `/api/shipments/v2409/void/cancel/{value.json.id}?{value.json.query}` | `fleet/ups/shipment/void` | `fleet/ups/shipment/void/response` | `access_token`, `id`, `query`, `trans_id` |
| `RecoverLabel` | POST | `/api/labels/v1/recovery` | `fleet/ups/label/recover` | `fleet/ups/label/recover/response` | `access_token`, `body`, `trans_id` |
| `QuoteLandedCost` | POST | `/api/landedcost/v1/quotes` | `fleet/ups/landed-cost/quote` | `fleet/ups/landed-cost/quote/response` | `access_token`, `body`, `trans_id` |
| `RatePickup` | POST | `/api/shipments/v2409/pickup/{value.json.pickup_type}` | `fleet/ups/pickup/rate` | `fleet/ups/pickup/rate/response` | `access_token`, `body`, `pickup_type`, `trans_id` |
| `GetPendingPickups` | GET | `/api/shipments/v2409/pickup/{value.json.pickup_type}` | `fleet/ups/pickup-pending/get` | `fleet/ups/pickup-pending/get/response` | `access_token`, `account_number`, `pickup_type`, `trans_id` |
| `CreatePickup` | POST | `/api/pickupcreation/v2409/pickup` | `fleet/ups/pickup/create` | `fleet/ups/pickup/create/response` | `access_token`, `body`, `trans_id` |
| `CancelPickup` | DELETE | `/api/shipments/v2409/pickup/02` | `fleet/ups/pickup/cancel` | `fleet/ups/pickup/cancel/response` | `access_token`, `prn`, `trans_id` |
| `ListPickupPoliticalDivisions` | GET | `/api/pickup/v2409/countries/{value.json.country}` | `fleet/ups/pickup-division/list` | `fleet/ups/pickup-division/list/response` | `access_token`, `country`, `trans_id` |
| `FindPickupServiceCenters` | POST | `/api/pickup/v2409/servicecenterlocations` | `fleet/ups/pickup-service-center/search` | `fleet/ups/pickup-service-center/search/response` | `access_token`, `body`, `trans_id` |
| `UploadPaperlessDocument` | POST | `/api/paperlessdocuments/v2/upload` | `fleet/ups/paperless-document/upload` | `fleet/ups/paperless-document/upload/response` | `access_token`, `body`, `shipper_number`, `trans_id` |
| `PushPaperlessImage` | POST | `/api/paperlessdocuments/v2/image` | `fleet/ups/paperless-document/push` | `fleet/ups/paperless-document/push/response` | `access_token`, `body`, `shipper_number`, `trans_id` |
| `DeletePaperlessDocument` | DELETE | `/api/paperlessdocuments/v2/DocumentId/ShipperNumber` | `fleet/ups/paperless-document/delete` | `fleet/ups/paperless-document/delete/response` | `access_token`, `document_id`, `shipper_number`, `trans_id` |
| `GetQuantumViewEvents` | POST | `/api/quantumview/v3/events` | `fleet/ups/quantum-view/get` | `fleet/ups/quantum-view/get/response` | `access_token`, `body`, `trans_id` |
| `CheckInterceptEligibility` | GET | `/api/deliveryintercept/v2/eligibility/intercept/{value.json.id}` | `fleet/ups/intercept-eligibility/get` | `fleet/ups/intercept-eligibility/get/response` | `access_token`, `id`, `trans_id` |
| `GetInterceptCharges` | POST | `/api/deliveryintercept/v2/charges/{value.json.id}` | `fleet/ups/intercept-charges/get` | `fleet/ups/intercept-charges/get/response` | `access_token`, `body`, `id`, `trans_id` |
| `GetChemicalReferenceData` | POST | `/api/dangerousgoods/v2409/chemicalreferencedata` | `fleet/ups/dangerous-goods-chemical/get` | `fleet/ups/dangerous-goods-chemical/get/response` | `access_token`, `body`, `trans_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode UPS_DEVELOPER_PORTAL"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR UpsApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://onlinetools.ups.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT TrackPackage
        WITH SOURCE_TOPIC "fleet/ups/track/get"
        WITH DESTINATION_TOPIC "fleet/ups/track/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/track/v1/details/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
    ADD EVENT TrackShipment
        WITH SOURCE_TOPIC "fleet/ups/track-shipment/get"
        WITH DESTINATION_TOPIC "fleet/ups/track-shipment/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/track/v1/shipment/details/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
    ADD EVENT TrackByReference
        WITH SOURCE_TOPIC "fleet/ups/track-reference/get"
        WITH DESTINATION_TOPIC "fleet/ups/track-reference/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/track/v1/reference/details/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
    ADD EVENT SubscribeTrackAlert
        WITH SOURCE_TOPIC "fleet/ups/track-alert/create"
        WITH DESTINATION_TOPIC "fleet/ups/track-alert/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/track/v2/subscription/standard/package"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT SubscribeTrackAlertEnhanced
        WITH SOURCE_TOPIC "fleet/ups/track-alert-enhanced/create"
        WITH DESTINATION_TOPIC "fleet/ups/track-alert-enhanced/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/track/v2/subscription/enhanced/package"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RateShipment
        WITH SOURCE_TOPIC "fleet/ups/rate/get"
        WITH DESTINATION_TOPIC "fleet/ups/rate/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/rating/v2409/Rate"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ShopRates
        WITH SOURCE_TOPIC "fleet/ups/rate-shop/get"
        WITH DESTINATION_TOPIC "fleet/ups/rate-shop/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/rating/v2409/Shop"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ShopRatesWithTransit
        WITH SOURCE_TOPIC "fleet/ups/rate-shop-transit/get"
        WITH DESTINATION_TOPIC "fleet/ups/rate-shop-transit/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/rating/v2409/Shoptimeintransit"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT ValidateAddress
        WITH SOURCE_TOPIC "fleet/ups/address/validate"
        WITH DESTINATION_TOPIC "fleet/ups/address/validate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/addressvalidation/v2/3?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetTransitTimes
        WITH SOURCE_TOPIC "fleet/ups/transit-time/get"
        WITH DESTINATION_TOPIC "fleet/ups/transit-time/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/shipments/v1/transittimes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT FindLocations
        WITH SOURCE_TOPIC "fleet/ups/location/search"
        WITH DESTINATION_TOPIC "fleet/ups/location/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/locations/v3/search/availabilities/1"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT FindAccessPoints
        WITH SOURCE_TOPIC "fleet/ups/access-point/search"
        WITH DESTINATION_TOPIC "fleet/ups/access-point/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/locations/v3/search/availabilities/64"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CreateShipment
        WITH SOURCE_TOPIC "fleet/ups/shipment/create"
        WITH DESTINATION_TOPIC "fleet/ups/shipment/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/shipments/v2409/ship"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT VoidShipment
        WITH SOURCE_TOPIC "fleet/ups/shipment/void"
        WITH DESTINATION_TOPIC "fleet/ups/shipment/void/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/api/shipments/v2409/void/cancel/{value.json.id}?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
    ADD EVENT RecoverLabel
        WITH SOURCE_TOPIC "fleet/ups/label/recover"
        WITH DESTINATION_TOPIC "fleet/ups/label/recover/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/labels/v1/recovery"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT QuoteLandedCost
        WITH SOURCE_TOPIC "fleet/ups/landed-cost/quote"
        WITH DESTINATION_TOPIC "fleet/ups/landed-cost/quote/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/landedcost/v1/quotes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT RatePickup
        WITH SOURCE_TOPIC "fleet/ups/pickup/rate"
        WITH DESTINATION_TOPIC "fleet/ups/pickup/rate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/shipments/v2409/pickup/{value.json.pickup_type}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetPendingPickups
        WITH SOURCE_TOPIC "fleet/ups/pickup-pending/get"
        WITH DESTINATION_TOPIC "fleet/ups/pickup-pending/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/shipments/v2409/pickup/{value.json.pickup_type}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "AccountNumber" "{value.json.account_number}"
    ADD EVENT CreatePickup
        WITH SOURCE_TOPIC "fleet/ups/pickup/create"
        WITH DESTINATION_TOPIC "fleet/ups/pickup/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/pickupcreation/v2409/pickup"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CancelPickup
        WITH SOURCE_TOPIC "fleet/ups/pickup/cancel"
        WITH DESTINATION_TOPIC "fleet/ups/pickup/cancel/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/api/shipments/v2409/pickup/02"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Prn" "{value.json.prn}"
    ADD EVENT ListPickupPoliticalDivisions
        WITH SOURCE_TOPIC "fleet/ups/pickup-division/list"
        WITH DESTINATION_TOPIC "fleet/ups/pickup-division/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/pickup/v2409/countries/{value.json.country}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
    ADD EVENT FindPickupServiceCenters
        WITH SOURCE_TOPIC "fleet/ups/pickup-service-center/search"
        WITH DESTINATION_TOPIC "fleet/ups/pickup-service-center/search/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/pickup/v2409/servicecenterlocations"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT UploadPaperlessDocument
        WITH SOURCE_TOPIC "fleet/ups/paperless-document/upload"
        WITH DESTINATION_TOPIC "fleet/ups/paperless-document/upload/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/paperlessdocuments/v2/upload"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "ShipperNumber" "{value.json.shipper_number}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT PushPaperlessImage
        WITH SOURCE_TOPIC "fleet/ups/paperless-document/push"
        WITH DESTINATION_TOPIC "fleet/ups/paperless-document/push/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/paperlessdocuments/v2/image"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "ShipperNumber" "{value.json.shipper_number}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT DeletePaperlessDocument
        WITH SOURCE_TOPIC "fleet/ups/paperless-document/delete"
        WITH DESTINATION_TOPIC "fleet/ups/paperless-document/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/api/paperlessdocuments/v2/DocumentId/ShipperNumber"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "ShipperNumber" "{value.json.shipper_number}"
            ADD "DocumentId" "{value.json.document_id}"
    ADD EVENT GetQuantumViewEvents
        WITH SOURCE_TOPIC "fleet/ups/quantum-view/get"
        WITH DESTINATION_TOPIC "fleet/ups/quantum-view/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/quantumview/v3/events"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CheckInterceptEligibility
        WITH SOURCE_TOPIC "fleet/ups/intercept-eligibility/get"
        WITH DESTINATION_TOPIC "fleet/ups/intercept-eligibility/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/deliveryintercept/v2/eligibility/intercept/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "platformType" "XOLT"
            ADD "inquiryType" "U"
            ADD "Content-Type" "application/json"
    ADD EVENT GetInterceptCharges
        WITH SOURCE_TOPIC "fleet/ups/intercept-charges/get"
        WITH DESTINATION_TOPIC "fleet/ups/intercept-charges/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/deliveryintercept/v2/charges/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "platformType" "XOLT"
            ADD "inquiryType" "U"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetChemicalReferenceData
        WITH SOURCE_TOPIC "fleet/ups/dangerous-goods-chemical/get"
        WITH DESTINATION_TOPIC "fleet/ups/dangerous-goods-chemical/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/dangerousgoods/v2409/chemicalreferencedata"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "transId" "{value.json.trans_id}"
            ADD "transactionSrc" "Coreflux-Broker"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `TrackPackage` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'fleet/ups/track/get/response' &
mosquitto_pub -t 'fleet/ups/track/get' -m '{"access_token": "<access_token>", "id": "<id>", "query": "<query>", "trans_id": "<trans_id>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Veeva Vault Api
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/veeva-vault-api

LoT REST API connector for Veeva Vault QMS and QualityDocs: query SOPs and quality events, read documents and audit trails, and raise deviations from alarms

Technical Preview

## Overview

Client-mode REST API connector for Veeva Vault QMS and QualityDocs: query effective SOPs and controlled documents, read document versions, renditions and lifecycle actions, query and read quality events, read object metadata, picklists and audit trails, and turn a line alarm into a deviation, through the Vault REST API v26.2.

This is one of the templates in the Veeva Vault (QMS, QualityDocs) REST API app (`veeva-vault`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Authorization header from payload field authorization: an API access token as 'Bearer veeva-vault-...' (recommended) or a Vault session ID sent as is. Session from VeevaVaultAuth CreateSession (form username + password, reply sessionId / userId / vaultIds) or VeevaVaultLogin CreateOAuthSession (Bearer IdP access token + profile id, form vaultDNS + client\_id). KeepAlive extends a session. DiscoverAuthType (public) tells password vs SSO users apart.

Auth headers used by the template: `Authorization: {value.json.authorization}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Veeva Vault Api connector | no |
| `BaseUrl` | string | Veeva Vault Api base URL without trailing slash (e.g. https\://YOUR\_VAULT\_DNS) | yes |

`BASE_ADDRESS` default: `https://YOUR_VAULT_DNS`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `ValidateSessionUser` | GET | `/api/v26.2/objects/users/me` | `mes/veeva-vault/session-user/get` | `mes/veeva-vault/session-user/get/response` | `authorization` |
| `VqlQuery` | POST | `/api/v26.2/query` | `mes/veeva-vault/query/run` | `mes/veeva-vault/query/run/response` | `authorization`, `q` |
| `QueryDocuments` | POST | `/api/v26.2/query` | `mes/veeva-vault/documents/query` | `mes/veeva-vault/documents/query/response` | `authorization`, `where` |
| `QueryQualityEvents` | POST | `/api/v26.2/query` | `mes/veeva-vault/quality-events/query` | `mes/veeva-vault/quality-events/query/response` | `authorization`, `where` |
| `GetDocument` | GET | `/api/v26.2/objects/documents/{value.json.doc_id}` | `mes/veeva-vault/document/get` | `mes/veeva-vault/document/get/response` | `authorization`, `doc_id` |
| `GetDocumentVersions` | GET | `/api/v26.2/objects/documents/{value.json.doc_id}/versions` | `mes/veeva-vault/document-versions/get` | `mes/veeva-vault/document-versions/get/response` | `authorization`, `doc_id` |
| `GetDocumentVersion` | GET | `/api/v26.2/objects/documents/{value.json.doc_id}/versions/{value.json.major}/{value.json.minor}` | `mes/veeva-vault/document-version/get` | `mes/veeva-vault/document-version/get/response` | `authorization`, `doc_id`, `major`, `minor` |
| `GetDocumentRenditions` | GET | `/api/v26.2/objects/documents/{value.json.doc_id}/renditions` | `mes/veeva-vault/document-renditions/get` | `mes/veeva-vault/document-renditions/get/response` | `authorization`, `doc_id` |
| `GetDocumentAttachments` | GET | `/api/v26.2/objects/documents/{value.json.doc_id}/attachments` | `mes/veeva-vault/document-attachments/get` | `mes/veeva-vault/document-attachments/get/response` | `authorization`, `doc_id` |
| `GetDocumentUserActions` | GET | `/api/v26.2/objects/documents/{value.json.doc_id}/versions/{value.json.major}/{value.json.minor}/lifecycle_actions` | `mes/veeva-vault/document-actions/get` | `mes/veeva-vault/document-actions/get/response` | `authorization`, `doc_id`, `major`, `minor` |
| `ListDocumentTypes` | GET | `/api/v26.2/metadata/objects/documents/types` | `mes/veeva-vault/document-types/list` | `mes/veeva-vault/document-types/list/response` | `authorization` |
| `ListDocumentFields` | GET | `/api/v26.2/metadata/objects/documents/properties` | `mes/veeva-vault/document-fields/list` | `mes/veeva-vault/document-fields/list/response` | `authorization` |
| `ListObjects` | GET | `/api/v26.2/metadata/vobjects` | `mes/veeva-vault/objects/list` | `mes/veeva-vault/objects/list/response` | `authorization` |
| `GetObjectMetadata` | GET | `/api/v26.2/metadata/vobjects/{value.json.object_name}` | `mes/veeva-vault/object-metadata/get` | `mes/veeva-vault/object-metadata/get/response` | `authorization`, `object_name` |
| `GetObjectFieldMetadata` | GET | `/api/v26.2/metadata/vobjects/{value.json.object_name}/fields/{value.json.field_name}` | `mes/veeva-vault/object-field-metadata/get` | `mes/veeva-vault/object-field-metadata/get/response` | `authorization`, `field_name`, `object_name` |
| `GetObjectRecord` | GET | `/api/v26.2/vobjects/{value.json.object_name}/{value.json.record_id}` | `mes/veeva-vault/object-record/get` | `mes/veeva-vault/object-record/get/response` | `authorization`, `object_name`, `record_id` |
| `GetObjectRecordUserActions` | GET | `/api/v26.2/vobjects/{value.json.object_name}/{value.json.record_id}/actions` | `mes/veeva-vault/object-record-actions/get` | `mes/veeva-vault/object-record-actions/get/response` | `authorization`, `object_name`, `record_id` |
| `GetPicklistValues` | GET | `/api/v26.2/objects/picklists/{value.json.picklist_name}` | `mes/veeva-vault/picklist/get` | `mes/veeva-vault/picklist/get/response` | `authorization`, `picklist_name` |
| `ListAuditTypes` | GET | `/api/v26.2/metadata/audittrail` | `mes/veeva-vault/audit-types/list` | `mes/veeva-vault/audit-types/list/response` | `authorization` |
| `GetAuditTrail` | GET | `/api/v26.2/audittrail/{value.json.audit_trail_type}?start_date={value.json.start_date}&end_date={value.json.end_date}` | `mes/veeva-vault/audit-trail/get` | `mes/veeva-vault/audit-trail/get/response` | `audit_trail_type`, `authorization`, `end_date`, `start_date` |
| `CreateQualityEvent` | POST | `/api/v26.2/vobjects/quality_event__qdm` | `mes/veeva-vault/quality-event/create` | `mes/veeva-vault/quality-event/create/response` | `authorization`, `request` |
| `CreateObjectRecords` | POST | `/api/v26.2/vobjects/{value.json.object_name}` | `mes/veeva-vault/object-records/create` | `mes/veeva-vault/object-records/create/response` | `authorization`, `object_name`, `request` |
| `InitiateObjectAction` | POST | `/api/v26.2/vobjects/{value.json.object_name}/{value.json.record_id}/actions/{value.json.action_name}` | `mes/veeva-vault/object-action/run` | `mes/veeva-vault/object-action/run/response` | `action_name`, `authorization`, `form`, `object_name`, `record_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode VEEVA_VAULT"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR VeevaVaultApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_VAULT_DNS"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ValidateSessionUser
        WITH SOURCE_TOPIC "mes/veeva-vault/session-user/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/session-user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT VqlQuery
        WITH SOURCE_TOPIC "mes/veeva-vault/query/run"
        WITH DESTINATION_TOPIC "mes/veeva-vault/query/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v26.2/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "q={value.json.q}"
    ADD EVENT QueryDocuments
        WITH SOURCE_TOPIC "mes/veeva-vault/documents/query"
        WITH DESTINATION_TOPIC "mes/veeva-vault/documents/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v26.2/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "q=SELECT id, document_number__v, name__v, type__v, status__v, major_version_number__v, minor_version_number__v FROM documents WHERE {value.json.where}"
    ADD EVENT QueryQualityEvents
        WITH SOURCE_TOPIC "mes/veeva-vault/quality-events/query"
        WITH DESTINATION_TOPIC "mes/veeva-vault/quality-events/query/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v26.2/query"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "q=SELECT id, name__v, status__v, date_occurred__qdm, severity__qdm FROM quality_event__qdm WHERE {value.json.where}"
    ADD EVENT GetDocument
        WITH SOURCE_TOPIC "mes/veeva-vault/document/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/documents/{value.json.doc_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDocumentVersions
        WITH SOURCE_TOPIC "mes/veeva-vault/document-versions/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document-versions/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/documents/{value.json.doc_id}/versions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDocumentVersion
        WITH SOURCE_TOPIC "mes/veeva-vault/document-version/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document-version/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/documents/{value.json.doc_id}/versions/{value.json.major}/{value.json.minor}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDocumentRenditions
        WITH SOURCE_TOPIC "mes/veeva-vault/document-renditions/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document-renditions/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/documents/{value.json.doc_id}/renditions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDocumentAttachments
        WITH SOURCE_TOPIC "mes/veeva-vault/document-attachments/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document-attachments/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/documents/{value.json.doc_id}/attachments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDocumentUserActions
        WITH SOURCE_TOPIC "mes/veeva-vault/document-actions/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document-actions/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/documents/{value.json.doc_id}/versions/{value.json.major}/{value.json.minor}/lifecycle_actions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListDocumentTypes
        WITH SOURCE_TOPIC "mes/veeva-vault/document-types/list"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document-types/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/metadata/objects/documents/types"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListDocumentFields
        WITH SOURCE_TOPIC "mes/veeva-vault/document-fields/list"
        WITH DESTINATION_TOPIC "mes/veeva-vault/document-fields/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/metadata/objects/documents/properties"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListObjects
        WITH SOURCE_TOPIC "mes/veeva-vault/objects/list"
        WITH DESTINATION_TOPIC "mes/veeva-vault/objects/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/metadata/vobjects"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetObjectMetadata
        WITH SOURCE_TOPIC "mes/veeva-vault/object-metadata/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/object-metadata/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/metadata/vobjects/{value.json.object_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetObjectFieldMetadata
        WITH SOURCE_TOPIC "mes/veeva-vault/object-field-metadata/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/object-field-metadata/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/metadata/vobjects/{value.json.object_name}/fields/{value.json.field_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetObjectRecord
        WITH SOURCE_TOPIC "mes/veeva-vault/object-record/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/object-record/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/vobjects/{value.json.object_name}/{value.json.record_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetObjectRecordUserActions
        WITH SOURCE_TOPIC "mes/veeva-vault/object-record-actions/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/object-record-actions/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/vobjects/{value.json.object_name}/{value.json.record_id}/actions"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetPicklistValues
        WITH SOURCE_TOPIC "mes/veeva-vault/picklist/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/picklist/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/objects/picklists/{value.json.picklist_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListAuditTypes
        WITH SOURCE_TOPIC "mes/veeva-vault/audit-types/list"
        WITH DESTINATION_TOPIC "mes/veeva-vault/audit-types/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/metadata/audittrail"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetAuditTrail
        WITH SOURCE_TOPIC "mes/veeva-vault/audit-trail/get"
        WITH DESTINATION_TOPIC "mes/veeva-vault/audit-trail/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v26.2/audittrail/{value.json.audit_trail_type}?start_date={value.json.start_date}&end_date={value.json.end_date}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateQualityEvent
        WITH SOURCE_TOPIC "mes/veeva-vault/quality-event/create"
        WITH DESTINATION_TOPIC "mes/veeva-vault/quality-event/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v26.2/vobjects/quality_event__qdm"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT CreateObjectRecords
        WITH SOURCE_TOPIC "mes/veeva-vault/object-records/create"
        WITH DESTINATION_TOPIC "mes/veeva-vault/object-records/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v26.2/vobjects/{value.json.object_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.request}"
    ADD EVENT InitiateObjectAction
        WITH SOURCE_TOPIC "mes/veeva-vault/object-action/run"
        WITH DESTINATION_TOPIC "mes/veeva-vault/object-action/run/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v26.2/vobjects/{value.json.object_name}/{value.json.record_id}/actions/{value.json.action_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "Content-Type" "application/x-www-form-urlencoded"
        WITH BODY "{value.json.form}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `ValidateSessionUser` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'mes/veeva-vault/session-user/get/response' &
mosquitto_pub -t 'mes/veeva-vault/session-user/get' -m '{"authorization": "<authorization>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Vertex Ai
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/vertex-ai

LoT REST API connector for Vertex AI: generate content and count tokens with Gemini, create embeddings, and run predictions on your own Vertex AI endpoints

Technical Preview

## Overview

Client-mode REST API connectors for Google Gemini: triage alarms and summarize shift logs with generateContent (structured JSON output), create embeddings, count tokens and list models with a Gemini API key, run Gemini and custom anomaly models on Vertex AI (predict on your endpoint), and get Google OAuth 2.0 access tokens.

This is one of the templates in the Google Gemini API and Vertex AI REST API app (`google-gemini-api-and-vertex-ai`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

## Auth

Gemini API: header x-goog-api-key \{value.json.api\_key} (Google AI Studio / Cloud API key; Hub secret GEMINI\_API\_KEY via GET SECRET). Vertex AI: Authorization: Bearer \{value.json.access\_token}, OAuth 2.0 access token with scope [https://www.googleapis.com/auth/cloud-platform](https://www.googleapis.com/auth/cloud-platform) for an identity with roles/aiplatform.user (\~1 h lifetime); GoogleOAuthToken connector gets it (refresh\_token grant with client id/secret/refresh token, or service-account JWT bearer grant with a JWT signed outside the broker). Hub secrets GEMINI\_API\_KEY, GOOGLE\_OAUTH\_CLIENT\_ID, GOOGLE\_OAUTH\_CLIENT\_SECRET, GOOGLE\_OAUTH\_REFRESH\_TOKEN. Never commit keys, tokens or service-account JSON.

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Vertex Ai connector | no |
| `BaseUrl` | string | Vertex Ai base URL without trailing slash (e.g. [https://YOUR\_REGION-aiplatform.googleapis.com](https://YOUR_REGION-aiplatform.googleapis.com)) | yes |

`BASE_ADDRESS` default: `https://YOUR_REGION-aiplatform.googleapis.com`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `VertexGenerateContent` | POST | `/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/publishers/google/models/{value.json.model}:generateContent` | `ai/gemini/vertex-content/generate` | `ai/gemini/vertex-content/generate/response` | `access_token`, `body`, `model` |
| `VertexCountTokens` | POST | `/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/publishers/google/models/{value.json.model}:countTokens` | `ai/gemini/vertex-tokens/count` | `ai/gemini/vertex-tokens/count/response` | `access_token`, `body`, `model` |
| `VertexEmbedPredict` | POST | `/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/publishers/google/models/{value.json.model}:predict` | `ai/gemini/vertex-embedding/predict` | `ai/gemini/vertex-embedding/predict/response` | `access_token`, `body`, `model` |
| `VertexEndpointPredict` | POST | `/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/endpoints/{value.json.endpoint_id}:predict` | `ai/gemini/vertex-endpoint/predict` | `ai/gemini/vertex-endpoint/predict/response` | `access_token`, `body`, `endpoint_id` |
| `VertexListEndpoints` | GET | `/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/endpoints?pageSize={value.json.page_size}` | `ai/gemini/vertex-endpoint/list` | `ai/gemini/vertex-endpoint/list/response` | `access_token`, `page_size` |
| `VertexGetEndpoint` | GET | `/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/endpoints/{value.json.endpoint_id}` | `ai/gemini/vertex-endpoint/get` | `ai/gemini/vertex-endpoint/get/response` | `access_token`, `endpoint_id` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode VERTEX_AI"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR VertexAiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_REGION-aiplatform.googleapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '120'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT VertexGenerateContent
        WITH SOURCE_TOPIC "ai/gemini/vertex-content/generate"
        WITH DESTINATION_TOPIC "ai/gemini/vertex-content/generate/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/publishers/google/models/{value.json.model}:generateContent"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT VertexCountTokens
        WITH SOURCE_TOPIC "ai/gemini/vertex-tokens/count"
        WITH DESTINATION_TOPIC "ai/gemini/vertex-tokens/count/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/publishers/google/models/{value.json.model}:countTokens"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT VertexEmbedPredict
        WITH SOURCE_TOPIC "ai/gemini/vertex-embedding/predict"
        WITH DESTINATION_TOPIC "ai/gemini/vertex-embedding/predict/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/publishers/google/models/{value.json.model}:predict"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT VertexEndpointPredict
        WITH SOURCE_TOPIC "ai/gemini/vertex-endpoint/predict"
        WITH DESTINATION_TOPIC "ai/gemini/vertex-endpoint/predict/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/endpoints/{value.json.endpoint_id}:predict"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT VertexListEndpoints
        WITH SOURCE_TOPIC "ai/gemini/vertex-endpoint/list"
        WITH DESTINATION_TOPIC "ai/gemini/vertex-endpoint/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/endpoints?pageSize={value.json.page_size}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT VertexGetEndpoint
        WITH SOURCE_TOPIC "ai/gemini/vertex-endpoint/get"
        WITH DESTINATION_TOPIC "ai/gemini/vertex-endpoint/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/projects/YOUR_PROJECT_ID/locations/YOUR_REGION/endpoints/{value.json.endpoint_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

## Usage example

Call `VertexGenerateContent` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'ai/gemini/vertex-content/generate/response' &
mosquitto_pub -t 'ai/gemini/vertex-content/generate' -m '{"access_token": "<access_token>", "body": {}, "model": "<model>"}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Victron VRM API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/victron-vrm-api

LoT REST API connector for the Victron VRM API v2: list installations, read energy, battery and alarm data, manage alarm rules and installation settings

Technical Preview

> [!WARNING]
>
> **Use an access token.** VRM sends the token in the `X-Authorization` header, not in `Authorization`. Victron deprecated `Bearer` login tokens from June 1, 2026. Create a personal access token in the VRM Portal and send it as `Token <access_token>`.

## Overview

Victron GX devices (Cerbo GX, Ekrano GX, Venus GX and other Venus OS devices) upload data from inverters/chargers, MPPT solar chargers, battery monitors, meters and EV chargers to the **VRM Portal**. The **VRM API v2** (`https://vrmapi.victronenergy.com/v2`) gives programmatic access to the same data. Victron publishes it as an OpenAPI 3.1 document on [vrm-api-docs.victronenergy.com](https://vrm-api-docs.victronenergy.com).

The **VictronVrmApi** connector maps 20 MQTT topics onto that API: 13 read events (12 `GET` plus one read-only `POST` lookup) and 7 write events. Typical uses are putting PV yield, battery state of charge and consumption from remote Victron sites (off-grid cabins, telecom shelters, boats, ESS systems) on the broker next to plant data, and turning VRM alarms into broker alarms. Each event publishes the VRM reply on `<topic>/response`.

| Event | Topic | Request | Use |
| - | - | - | - |
| `GetMe` | `energy/victron/user/get` | `GET /v2/users/me` | Who the token belongs to: user.id (idUser), name, email, accessLevel |
| `ListInstallations` | `energy/victron/installation/list` | `GET /v2/users/{user_id}/installations?{query}` | Installations the user can read (records\[].idSite, name, identifier, timezone); query extended=1 and/or idSite=, or "" |
| `SearchInstallations` | `energy/victron/installation/search` | `GET /v2/users/{user_id}/search?{query}` | Full-text search over the user's installations (name, identifier, products); query query=\<text> (required) |
| `GetSiteId` | `energy/victron/site-id/get` | `POST /v2/users/{user_id}/get-site-id` | Read-only lookup (POST): VRM portal id (identifier) -> idSite; body \{"installation\_identifier": "c0619ab27f32"} |
| `GetSystemOverview` | `energy/victron/system-overview/get` | `GET /v2/installations/{id}/system-overview` | Devices connected to the site: GX gateway, Multi/Quattro, MPPT, battery monitor, meters, firmware, last connection |
| `GetStats` | `energy/victron/stats/get` | `GET /v2/installations/{id}/stats?{query}` | Time series (default live\_feed, hours, last 24 h); query type=kwh/venus/consumption/solar\_yield/forecast/custom\&interval=\&start=\&end=\&attributeCodes\[]= |
| `GetOverallStats` | `energy/victron/overall-stats/get` | `GET /v2/installations/{id}/overallstats?{query}` | Totals and percentages for the last year, month, week and day; query type=kwh/custom\&attributeCodes\[]= or "" |
| `ListAlarmRules` | `energy/victron/alarm/list` | `GET /v2/installations/{id}/alarms` | Configured alarm rules (thresholds, recipients, attributes available for new rules); needs full / admin rights on the site |
| `GetAlarmLog` | `energy/victron/alarm-log/get` | `GET /v2/installations/{id}/alarm-log?{query}` | Alarm / fault log: active first, then cleared (started, cleared, description, device); query start=\&end=\&page=\&count= |
| `GetDiagnostics` | `energy/victron/diagnostics/get` | `GET /v2/installations/{id}/diagnostics?{query}` | Logged data per attribute (Device, code, description, formattedValue, rawValue, dbusPath, timestamp); query count=\&page=; needs full rights |
| `GetDynamicEssSettings` | `energy/victron/dynamic-ess-settings/get` | `GET /v2/installations/{id}/dynamic-ess-settings` | Dynamic ESS configuration: battery capacity / costs, charge and discharge power, grid limits, price formulas, isOn |
| `ListTags` | `energy/victron/tag/list` | `GET /v2/installations/{id}/tags?{query}` | Tags of the site; query filter= or ""; needs full rights |
| `GetGpsTrack` | `energy/victron/gps-track/get` | `GET /v2/installations/{id}/gps-download?{query}` | GPS track as KML (vehicles, boats); query start=\&end= (required, Unix seconds) |
| `ClearAlarm` | `energy/victron/alarm/clear` | `POST /v2/installations/{id}/clear-alarm` | WRITE: clear an active alarm and mark it cleared by the user in the event log; body \{"alarmId": \<idAlarm from alarm-log>} |
| `AddAlarmRule` | `energy/victron/alarm/add` | `POST /v2/installations/{id}/alarms` | WRITE: add an alarm rule; float body \{idDataAttribute, instance, AlarmEnabled, NotifyAfterSeconds, highAlarm, ...}, enum body camelCase \{alarmEnabled, notifyAfterSeconds, enumValues} |
| `EditAlarmRule` | `energy/victron/alarm/update` | `PUT /v2/installations/{id}/alarms` | WRITE: edit an alarm rule (same body as alarm/add, keyed by idDataAttribute + instance) |
| `DeleteAlarmRule` | `energy/victron/alarm/delete` | `DELETE /v2/installations/{id}/alarms` | WRITE: delete an alarm rule; DELETE with JSON body \{idDataAttribute, instance} |
| `AddTag` | `energy/victron/tag/add` | `PUT /v2/installations/{id}/tags` | WRITE: add a tag; body \{"tag": "porto-plant", "source": "user"} |
| `RemoveTag` | `energy/victron/tag/remove` | `DELETE /v2/installations/{id}/tags` | WRITE: remove a tag; DELETE with JSON body \{"tag": "porto-plant", "source": "user"} |
| `UpdateInstallationSettings` | `energy/victron/settings/update` | `POST /v2/installations/{id}/settings` | WRITE: update site settings (description = name, notes, phonenumber, noDataAlarmTimeout / noDataAlarmActive, alarmMonitoring, geofence, realtimeUpdates, inverterChargerControl, ...); send only the fields to change |

> [!WARNING]
>
> **Write events change VRM configuration.** `ClearAlarm`, `AddAlarmRule`, `EditAlarmRule`, `DeleteAlarmRule`, `AddTag`, `RemoveTag` and `UpdateInstallationSettings` change portal settings, not the hardware. `UpdateInstallationSettings` can turn `inverterChargerControl` on, which lets VRM users switch the inverter/charger remotely. Restrict who can publish to these topics with a rule. This connector does not include the Dynamic ESS write (it changes how the battery charges and discharges). It also leaves out user, invite and access-token management.

> [!TIP]
>
> For local, low-latency data without the cloud, read the GX device directly: Venus OS runs a local MQTT broker (bridge it with an MQTT bridge connector) and exposes a Modbus TCP register list (use a native Modbus connector). This connector is for VRM cloud data across many sites.

## Prerequisites

* A **VRM Portal** account ([vrm.victronenergy.com](https://vrm.victronenergy.com)) with access to at least one installation. A GX device must upload data to VRM.
* A **personal access token**. In VRM, open **Preferences > Integrations > Access tokens**, create a token, and copy it. VRM shows it only once.
* Your **user id** (`idUser`) for the user-level events. `user/get` returns it as `user.id`.
* The **installation id** (`idSite`) of each site. `installation/list` returns it as `records[].idSite`. It is a number, such as `219742`. It is **not** the VRM portal ID (`identifier`, for example `c0619ab27f32`). `site-id/get` converts a portal ID to `idSite`.
* **Full access** (admin rights) to the site for the alarm rules, diagnostics, tags and write events. Users with read-only access get `403`.
* Outbound HTTPS from the broker to `vrmapi.victronenergy.com`.

## Authentication

Every event sends `X-Authorization: {value.json.authorization}`. Store the full header value as a Hub secret, for example `VRM_AUTHORIZATION` = `Token <access_token>`, and read it with `GET SECRET` in the action that publishes to the connector.

| Format | Source | Notes |
| - | - | - |
| `Token <access_token>` | VRM Preferences > Integrations > Access tokens, or `POST /v2/users/{idUser}/accesstokens` | Recommended. Lasts until you revoke it or it reaches its expiry date |
| `Bearer <jwt>` | `POST /v2/auth/login` (user name and password) | Deprecated from June 1, 2026. Expires after 24 hours |

| Response | Meaning |
| - | - |
| `401` `{"errors":"Login required","error_code":"invalid_credentials"}` | No `X-Authorization` header (a plain `Authorization` header is ignored) |
| `401` `{"errors":"Invalid accesstoken received","error_code":"invalid_token"}` | The `Token` value is unknown or revoked, or a JWT was sent with the `Token` prefix |
| `401` `{"errors":"Token is invalid","error_code":"invalid_token"}` | The `Bearer` JWT is invalid or expired |
| `403` `{"error_code":"forbidden"}` | The token's user has no access, or not enough rights, on that site |
| `429` with `Retry-After` | Rate limit reached; wait that many seconds |

## Configuration

| Setting | Value |
| - | - |
| `BASE_ADDRESS` | `https://vrmapi.victronenergy.com` (endpoints carry `/v2`) |
| `USE_SSL` | `"true"` |
| `DEFAULT_CONTENT_TYPE` | `application/json` |
| Payload fields | `authorization`, `user_id` (`idUser`), `id` (`idSite`), `query` (pre-encoded query string, `""` for none), `body` (JSON object for the `POST`, `PUT` and `DELETE` events) |

Query parameters:

| Event | Parameters | Notes |
| - | - | - |
| `GetStats` | `type`, `interval`, `start`, `end`, `attributeCodes[]`, `show_instance` | `type`: `live_feed` (default), `venus`, `consumption`, `solar_yield`, `kwh`, `generator`, `generator-runtime`, `forecast`, `custom` (needs at least one `attributeCodes[]`, such as `bs` for battery SoC). `interval`: `15mins`, `hours` (default), `2hours`, `days`, `weeks`, `months`, `years`. `start` / `end` are Unix seconds (default: the last 24 hours) |
| `GetOverallStats` | `type`, `attributeCodes[]` | Same `type` values without `forecast`. Returns `year`, `month`, `week` and `today` totals |
| `GetAlarmLog` | `start`, `end`, `page`, `count` | Unix seconds. `count` defaults to 3,000. Active alarms come first |
| `GetDiagnostics` | `count`, `page` | Default 100 records |
| `ListInstallations` | `extended`, `idSite` | `extended=1` adds tags, images, current alarms and more |
| `SearchInstallations` | `query` (required) | Free text, such as `query=ESS` |
| `GetGpsTrack` | `start`, `end` (required) | Unix seconds. Returns KML, not JSON |
| `ListTags` | `filter` | Optional |

Maximum `GetStats` window for each `interval`:

| Interval | Maximum window |
| - | - |
| `15mins`, `hours` | 31 days |
| `days` | 180 days |
| `weeks` | 140 days |
| `months` | 24 months |
| `years` | 5 years |

Stats series come back as `{"success": true, "records": {"<code>": [[timestamp_ms, value, ...], ...]}, "totals": {"<code>": value}}`. The timestamps are in milliseconds. Codes include `Pdc` (PV DC power), `bs` (battery SoC), `bv` (battery voltage), `kwh` and grid / consumption codes. Other responses use `{"success": true, "records": ...}`, and errors use `{"success": false, "errors", "error_code"}`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Victron Energy VRM API v2 (VRM Portal cloud for Victron GX / Cerbo / Venus OS systems):
#   identify the token's user, list and search the installations (sites) it can read, read the device list behind a
#   site (system overview), power / energy / battery / forecast time series (stats), year / month / week / day totals
#   (overall stats), the alarm / fault log, configured alarm rules, diagnostics (logged data per attribute with
#   D-Bus path), Dynamic ESS settings, tags and GPS tracks; and (marked WRITE) clear an active alarm, add / edit /
#   delete alarm rules, add / remove tags and update installation settings.
#   https://vrm-api-docs.victronenergy.com (docs/docs/openapi.yaml + its $ref files, fetched 2026-10-05; bundled and
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/victron-vrm-api
#
# Auth: X-Authorization: {value.json.authorization} on every call. The header is X-Authorization, not Authorization
#   (a plain "Authorization: Bearer ..." answers 401 "Login required"). Two value formats:
#     "Token <access_token>"  personal access token, VRM Portal > Preferences > Integrations > Access tokens (or
#                             POST /v2/users/{idUser}/accesstokens). Recommended. Keep it in Hub secrets (suggested
#                             VRM_AUTHORIZATION = "Token <access_token>") and map it into the payload with GET SECRET.
#     "Bearer <jwt>"          login JWT from POST /v2/auth/login (24 h). Victron deprecates Bearer login tokens from
#                             2026-06-01 onwards; still accepted today (the public demo login returns one).
#   No header: 401 {"success":false,"errors":"Login required","error_code":"invalid_credentials"}; bad access token:
#   401 "Invalid accesstoken received" (invalid_token); no rights on the site: 403 "forbidden".
# Rate limit: rolling window of 200 requests, one slot freed every 0.33 s (about 3 requests per second sustained).
#   429 with JSON carries Retry-After (seconds). VRM data is logged every 1-15 minutes (GX logging interval), so poll
#   stats every 15 minutes or slower.
# Ids: user_id = idUser (from user/get: user.id), id = idSite (from installation/list: records[].idSite). idSite is
#   NOT the VRM portal id ("identifier", e.g. c0619ab27f32); site-id/get maps a portal id to idSite.
# Queries: events with ?{value.json.query} take a pre-encoded query string ("" for none). Unix timestamps in
#   SECONDS for start= / end= (responses use milliseconds in stats series and seconds elsewhere).
#     stats       type=venus|live_feed|consumption|solar_yield|kwh|generator|generator-runtime|custom|forecast,
#                 interval=15mins|hours|2hours|days|weeks|months|years, start=, end=, attributeCodes[]=bs (custom),
#                 show_instance=1. Max window: 31 days (15mins / hours), 180 days (days), 140 days (weeks),
#                 24 months (months), 5 years (years).
#     alarm-log   start=, end=, page=, count= (default 3000); active entries first.
#     installation/list  extended=1 and/or idSite=<idSite>;  installation/search  query=<text> (required)
# Writes (marked WRITE below): ClearAlarm, AddAlarmRule, EditAlarmRule, DeleteAlarmRule, AddTag, RemoveTag,
#   UpdateInstallationSettings. They change VRM portal configuration only (alarm rules, tags, name / notes / alarm and
#   geofence settings); none of them switches an inverter. UpdateInstallationSettings can toggle
#   inverterChargerControl (whether VRM users may remote-control the inverter/charger) and realtimeUpdates, so
#   restrict who can publish to it. Not packaged: Dynamic ESS writes (change battery charge / discharge behaviour),
#   user / invite / access-token / unlink management, reset-forecasts, custom widgets, data-download exports.
# Responses: JSON {"success": true, "records": ...} (dynamic-ess-settings: "data"); errors {"success": false,
#   "errors", "error_code"}. gps-download answers KML (application/vnd.google-earth.kml+xml).
#
# Payload fields: authorization, user_id (idUser), id (idSite), query, body (JSON object for POST / PUT / DELETE)
#     ListInstallations  user_id = "22", query = "extended=1"
#     GetStats           id = "219742", query = "type=kwh&interval=days&start=1790000000&end=1791200000"
#     GetStats           id = "219742", query = "type=custom&attributeCodes[]=bs&interval=hours"
#     GetAlarmLog        id = "151734", query = "count=50"
#     ClearAlarm         id = "219742", body = {"alarmId": 1012027262}
#     AddTag             id = "219742", body = {"tag": "porto-plant", "source": "user"}

DEFINE CONNECTOR VictronVrmApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://vrmapi.victronenergy.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT GetMe
        WITH SOURCE_TOPIC "energy/victron/user/get"
        WITH DESTINATION_TOPIC "energy/victron/user/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users/me"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListInstallations
        WITH SOURCE_TOPIC "energy/victron/installation/list"
        WITH DESTINATION_TOPIC "energy/victron/installation/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users/{value.json.user_id}/installations?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT SearchInstallations
        WITH SOURCE_TOPIC "energy/victron/installation/search"
        WITH DESTINATION_TOPIC "energy/victron/installation/search/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/users/{value.json.user_id}/search?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetSiteId
        WITH SOURCE_TOPIC "energy/victron/site-id/get"
        WITH DESTINATION_TOPIC "energy/victron/site-id/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/users/{value.json.user_id}/get-site-id"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT GetSystemOverview
        WITH SOURCE_TOPIC "energy/victron/system-overview/get"
        WITH DESTINATION_TOPIC "energy/victron/system-overview/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/system-overview"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetStats
        WITH SOURCE_TOPIC "energy/victron/stats/get"
        WITH DESTINATION_TOPIC "energy/victron/stats/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/stats?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetOverallStats
        WITH SOURCE_TOPIC "energy/victron/overall-stats/get"
        WITH DESTINATION_TOPIC "energy/victron/overall-stats/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/overallstats?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListAlarmRules
        WITH SOURCE_TOPIC "energy/victron/alarm/list"
        WITH DESTINATION_TOPIC "energy/victron/alarm/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/alarms"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetAlarmLog
        WITH SOURCE_TOPIC "energy/victron/alarm-log/get"
        WITH DESTINATION_TOPIC "energy/victron/alarm-log/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/alarm-log?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetDiagnostics
        WITH SOURCE_TOPIC "energy/victron/diagnostics/get"
        WITH DESTINATION_TOPIC "energy/victron/diagnostics/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/diagnostics?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetDynamicEssSettings
        WITH SOURCE_TOPIC "energy/victron/dynamic-ess-settings/get"
        WITH DESTINATION_TOPIC "energy/victron/dynamic-ess-settings/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/dynamic-ess-settings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT ListTags
        WITH SOURCE_TOPIC "energy/victron/tag/list"
        WITH DESTINATION_TOPIC "energy/victron/tag/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/tags?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    ADD EVENT GetGpsTrack
        WITH SOURCE_TOPIC "energy/victron/gps-track/get"
        WITH DESTINATION_TOPIC "energy/victron/gps-track/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v2/installations/{value.json.id}/gps-download?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: ClearAlarm changes VRM configuration. Restrict who can publish to energy/victron/alarm/clear.
    ADD EVENT ClearAlarm
        WITH SOURCE_TOPIC "energy/victron/alarm/clear"
        WITH DESTINATION_TOPIC "energy/victron/alarm/clear/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/installations/{value.json.id}/clear-alarm"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: AddAlarmRule changes VRM configuration. Restrict who can publish to energy/victron/alarm/add.
    ADD EVENT AddAlarmRule
        WITH SOURCE_TOPIC "energy/victron/alarm/add"
        WITH DESTINATION_TOPIC "energy/victron/alarm/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/installations/{value.json.id}/alarms"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: EditAlarmRule changes VRM configuration. Restrict who can publish to energy/victron/alarm/update.
    ADD EVENT EditAlarmRule
        WITH SOURCE_TOPIC "energy/victron/alarm/update"
        WITH DESTINATION_TOPIC "energy/victron/alarm/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/installations/{value.json.id}/alarms"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: DeleteAlarmRule changes VRM configuration. Restrict who can publish to energy/victron/alarm/delete.
    ADD EVENT DeleteAlarmRule
        WITH SOURCE_TOPIC "energy/victron/alarm/delete"
        WITH DESTINATION_TOPIC "energy/victron/alarm/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/v2/installations/{value.json.id}/alarms"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: AddTag changes VRM configuration. Restrict who can publish to energy/victron/tag/add.
    ADD EVENT AddTag
        WITH SOURCE_TOPIC "energy/victron/tag/add"
        WITH DESTINATION_TOPIC "energy/victron/tag/add/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/v2/installations/{value.json.id}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: RemoveTag changes VRM configuration. Restrict who can publish to energy/victron/tag/remove.
    ADD EVENT RemoveTag
        WITH SOURCE_TOPIC "energy/victron/tag/remove"
        WITH DESTINATION_TOPIC "energy/victron/tag/remove/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/v2/installations/{value.json.id}/tags"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    # WRITE: UpdateInstallationSettings changes VRM configuration. Restrict who can publish to energy/victron/settings/update.
    ADD EVENT UpdateInstallationSettings
        WITH SOURCE_TOPIC "energy/victron/settings/update"
        WITH DESTINATION_TOPIC "energy/victron/settings/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/installations/{value.json.id}/settings"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "X-Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

## Examples

Publish directly to a connector topic:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Token <access_token>", "id": "219742", "query": "type=kwh&interval=days&start=1790000000&end=1791200000"}
```

to `energy/victron/stats/get`, then read `energy/victron/stats/get/response` for daily energy (`Pc`, `Pb`, `Pg`, `Bc`, `Bg`, `kwh`) for that window.

Clear an active alarm (take `idAlarm` from `alarm-log/get`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization": "Token <access_token>", "id": "219742", "body": {"alarmId": 1012027262}}
```

to `energy/victron/alarm/clear`.

Actions that poll the connector for one site:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the VictronVrmApi route (docs page). Not part of the route template.
# Secret: VRM_AUTHORIZATION = "Token <access_token>" (personal access token from VRM Portal > Preferences >
#   Integrations > Access tokens). The value is sent as the X-Authorization header.
# Installation id 219742 is the "ESS System" of the public VRM demo account. Replace it with your own idSite
#   (from installation/list: records[].idSite).
# Inline JSON object literals are not supported when publishing to a topic, so the request payload is a COLLAPSED
#   model sent with PUBLISH MODEL.
# Budget: these four actions make about 4 + 1 + 0.25 + 0.04 = 5.3 calls per hour, far below the VRM rate limit
#   (rolling window of 200 requests, about 3 per second sustained).

DEFINE MODEL VrmRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "id"
    ADD STRING "query"

DEFINE ACTION VrmLiveFeedEvery15Minutes
ON EVERY 15 MINUTES DO
    PUBLISH MODEL VrmRequest TO "energy/victron/stats/get" WITH
        authorization = (GET SECRET "VRM_AUTHORIZATION")
        id = "219742"
        query = "type=live_feed&interval=15mins"

DEFINE ACTION VrmAlarmLogHourly
ON EVERY 1 HOUR DO
    PUBLISH MODEL VrmRequest TO "energy/victron/alarm-log/get" WITH
        authorization = (GET SECRET "VRM_AUTHORIZATION")
        id = "219742"
        query = "count=20"

DEFINE ACTION VrmSystemOverviewEvery4Hours
ON EVERY 4 HOURS DO
    PUBLISH MODEL VrmRequest TO "energy/victron/system-overview/get" WITH
        authorization = (GET SECRET "VRM_AUTHORIZATION")
        id = "219742"
        query = ""

DEFINE ACTION VrmDailyKwhTotals
ON EVERY 1 DAY DO
    PUBLISH MODEL VrmRequest TO "energy/victron/overall-stats/get" WITH
        authorization = (GET SECRET "VRM_AUTHORIZATION")
        id = "219742"
        query = "type=kwh"
```

Restrict who can publish to `energy/victron/#` with a rule, because these payloads carry the access token.

## Rate limits and polling

VRM rate-limits most endpoints with a rolling window of 200 requests. One request leaves the window every 0.33 seconds, so about 3 requests per second never hit the limit. A `429` with a JSON body has a `Retry-After` header with the seconds to wait. The GX device logs to VRM every 1 to 15 minutes (its logging interval), so polling stats faster than every 15 minutes rarely returns new data. Use one `GetStats` call with `type=custom` and several `attributeCodes[]` instead of many separate calls.

## Notes

* **Demo account:** VRM has a public demo account (user 22) with several sample installations, such as **ESS System** (`219742`), **35ft Yacht** (`151734`) and **Off-grid** (`209689`). The demo is read-only. It answers `403` for alarm rules, diagnostics, tags, the site id lookup and every write.
* **Alarms:** `alarm/list` returns the alarm **rules** configured on a site. `alarm-log/get` returns the alarms that fired, with `started` and `cleared` timestamps. When a site has no log entries, it returns `200` with `{"success": false, "error_code": "no_results_found"}`.
* **Alarm rule bodies:** float alarms use PascalCase `AlarmEnabled` and `NotifyAfterSeconds`; enum alarms use camelCase `alarmEnabled` and `notifyAfterSeconds` with `enumValues`. VRM returns a warning if the case is wrong.
* **DELETE with a body:** `DeleteAlarmRule` and `RemoveTag` send a JSON body with `DELETE`, as the VRM spec requires.
* **Support:** Victron does not offer direct support for the VRM API. Use the Modifications section of the Victron Community.
* Reports and CSV / XLSX exports moved to a separate VRM Reports API and are not covered here.

## Not covered

Dynamic ESS writes, reset forecasts, custom widgets, data and installation-overview downloads, user, invite, group and access-token management, admin endpoints, the deprecated `widgets/*` endpoints, and the login call itself.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API app templates](/latest/lot-language/routes/rest-api-apps/index)
* [SolarEdge Monitoring API](/latest/lot-language/routes/rest-api-apps/solaredge-monitoring-api)
* [Enphase Enlighten API v4](/latest/lot-language/routes/rest-api-apps/enphase-enlighten-api-v4)
* [Fronius Solar API (local)](/latest/lot-language/routes/rest-api-apps/fronius-solar-api)


# WattTime
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/watttime

Client-mode REST API connector for a curated WattTime v3 slice: login and read a region forecast

Technical Preview

# WattTime

Client-mode REST API connector for a curated WattTime v3 slice: login and read a region forecast.

* Hub category: **Energy**.
* Base: `https://api.watttime.org`

## Template reference

Generated from the shipped broker template `watttime` (`-connectorCode WATTTIME`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the WattTime connector | no |
| `BaseUrl` | string | WattTime base URL without trailing slash (e.g. [https://api.watttime.org](https://api.watttime.org)) | yes |

`BASE_ADDRESS` default: `https://api.watttime.org`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Login` | POST | `/v3/login` | `energy/watttime/login` | `energy/watttime/login/response` | `api_token`, `body` |
| `Getforecast` | GET | `/v3/forecast?region={value.json.region}&signal_type=co2_moer` | `energy/watttime/forecast` | `energy/watttime/forecast/response` | `api_token`, `region` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode WATTTIME"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WattTimeRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.watttime.org"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Login
        WITH SOURCE_TOPIC "energy/watttime/login"
        WITH DESTINATION_TOPIC "energy/watttime/login/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v3/login"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getforecast
        WITH SOURCE_TOPIC "energy/watttime/forecast"
        WITH DESTINATION_TOPIC "energy/watttime/forecast/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v3/forecast?region={value.json.region}&signal_type=co2_moer"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Login` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/watttime/login/response' &
mosquitto_pub -t 'energy/watttime/login' -m '{"api_token": "<api_token>", "body": {}}'
```


# Webfleet (Bridgestone)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/webfleet

LoT REST API connector for Webfleet.connect: read vehicle positions, trips, events, drivers, EV and cold chain data, and send orders and text messages

Technical Preview

## Overview

[Webfleet](https://www.webfleet.com/) is Bridgestone's fleet management service (formerly TomTom Telematics). Its integration API, [WEBFLEET.connect](https://www.webfleet.com/static/help/webfleet-connect/en_gb/index.html), is a single HTTPS endpoint, `https://csv.webfleet.com/extern`, where every operation is selected with an `action` parameter. This template asks for JSON output (`outputformat=json`) and ISO 8601 dates in UTC (`useISO8601=true`).

The app has one client-mode connector, `WebfleetConnect`, with 35 events: 21 reads and 14 writes. Typical uses are putting truck and van positions next to plant data (inbound ETAs at the dock, dwell time at the gate), reacting to Webfleet events and cold chain readings in LoT rules, and sending orders or text messages to drivers when a batch is ready. Each event publishes the reply on `<topic>/response`.

### Reads

| Event | Topic | Action | Limit | Use |
| - | - | - | - | - |
| `ShowObjectReport` | `fleet/webfleet/objects/get` | `showObjectReportExtern` (GET) | 6 / min | All objects (vehicles, assets, people) with master data and the latest position, speed, ignition, odometer, driver |
| `ShowVehicleReport` | `fleet/webfleet/vehicles/get` | `showVehicleReportExtern` (GET) | 10 / min | Vehicles: plate, type, VIN (identnumber), dimensions, fuel type and consumption reference values |
| `ShowObjectGroups` | `fleet/webfleet/object-groups/get` | `showObjectGroups` (GET) | 10 / min | Object groups (depots, fleets, sites) |
| `ShowNearestVehicles` | `fleet/webfleet/vehicles/nearest/get` | `showNearestVehicles` (GET) | 10 / min | Vehicles closest to a point; latitude / longitude in micro degrees (41.1579 -> 41157900) (fields: `latitude`, `longitude`) |
| `ShowTracks` | `fleet/webfleet/tracks/get` | `showTracks` (GET) | 10 / min | Position trail of one vehicle (pos\_time, latitude, longitude, speed, course); range at most 2 days (fields: `objectno`, `range`) |
| `ShowTripReport` | `fleet/webfleet/trips/get` | `showTripReportExtern` (GET) | 1 / min | Trips (start / end time and place, distance, duration, fuel, driver) for the date range; filter applies to the trip end time (fields: `range`) |
| `ShowTripSummaryReport` | `fleet/webfleet/trips/summary/get` | `showTripSummaryReportExtern` (GET) | 10 / min | Trip totals for one object over the date range (fields: `objectno`, `range`) |
| `ShowStandStills` | `fleet/webfleet/standstills/get` | `showStandStills` (GET) | 6 / min | Standstills (where and how long a vehicle stopped), e.g. dwell time at a plant gate or dock (fields: `objectno`, `range`) |
| `ShowIOReport` | `fleet/webfleet/io/get` | `showIOReportExtern` (GET) | 10 / min | Digital input on / off periods (PTO, door, reefer, tipper) for one object (fields: `objectno`, `range`) |
| `ShowEventReport` | `fleet/webfleet/events/get` | `showEventReportExtern` (GET) | 1 / min | Event notifications (alarms, warnings, geofence, plugin events) with level, acknowledged / resolved state (fields: `range`) |
| `ShowOrderReport` | `fleet/webfleet/orders/get` | `showOrderReportExtern` (GET) | 6 / min | Orders with current state (accepted, started, arrived, finished), ETA and assigned object (fields: `range`) |
| `ShowDriverReport` | `fleet/webfleet/drivers/get` | `showDriverReportExtern` (GET) | 10 / min | Drivers with master data and the vehicle each is signed on to |
| `GetRemainingDrivingTimesEU` | `fleet/webfleet/drivers/driving-times/get` | `getRemainingDrivingTimesEU` (GET) | 10 / min | Remaining EU driving and rest times per driver (needs Tachograph Manager / TACHO.RDT) |
| `ShowAddressReport` | `fleet/webfleet/addresses/get` | `showAddressReportExtern` (GET) | 6 / min | Addresses (customer sites, plants, depots) with coordinates and radius |
| `GetObjectKPIs` | `fleet/webfleet/kpis/get` | `getObjectKPIs` (GET) | 10 / min | KPI groups (tripstats, ecostats, optidrive, speedingevents, drivingevents, orders) for one object (fields: `objectno`, `range`, `kpinames`) |
| `GetElectricVehicleData` | `fleet/webfleet/ev/get` | `getElectricVehicleData` (GET) | 6 / min | EV battery level (%), range and charging state for every electric vehicle (LINK 740 / 710 / 640 / 610 / 240 / 245 / 210) |
| `GetDiagnosticFaults` | `fleet/webfleet/diagnostics/faults/get` | `getDiagnosticFaults` (GET) | 10 / min | Diagnostic trouble codes reported by the vehicles in the date range (fields: `range`) |
| `GetCurrentTemperatureData` | `fleet/webfleet/temperature/get` | `getCurrentTemperatureData` (GET) | 10 / min | Latest temperature sensor readings (LINK temperature probes) |
| `GetCurrentColdChainSensorData` | `fleet/webfleet/coldchain/get` | `getCurrentColdChainSensorData` (GET) | 10 / min | Latest reefer / cold chain sensor values (Webfleet Cold Chain) |
| `GetTelemetryDeviceBatteryState` | `fleet/webfleet/device-battery/get` | `getTelemetryDeviceBatteryState` (GET) | 10 / min | Battery state of a battery-powered telemetry device (asset trackers) (fields: `objectuid`) |
| `PopQueueMessages` | `fleet/webfleet/queue/pop` | `popQueueMessagesExtern` (GET) | 10 / min | Next batch (up to 500) of queued messages: positions, order / driver / status / text and LINK.connect messages (fields: `msgclass`) |

### Writes and generic calls

| Event | Topic | Action | Limit | Use |
| - | - | - | - | - |
| `AckQueueMessages` | `fleet/webfleet/queue/ack` | `ackQueueMessagesExtern` (GET) | 10 / min | Acknowledge the last popped batch so it is not returned again; serialise with PopQueueMessages (fields: `msgclass`) |
| `CreateQueue` | `fleet/webfleet/queue/create` | `createQueueExtern` (GET) | 10 / 24 h | Create the message queue for a message class (0 all, 2 all but positions, 4 orders, 5 drivers, 7 status, 8 text, 15 third party) (fields: `msgclass`) |
| `DeleteQueue` | `fleet/webfleet/queue/delete` | `deleteQueueExtern` (GET) | 10 / 24 h | Delete the queue for a message class (fields: `msgclass`) |
| `AcknowledgeEvent` | `fleet/webfleet/events/acknowledge` | `acknowledgeEventExtern` (GET) | 300 / 30 min | Acknowledge an alarm-level event (level drops one step) (fields: `eventid`) |
| `ResolveEvent` | `fleet/webfleet/events/resolve` | `resolveEventExtern` (GET) | 300 / 30 min | Resolve an event (fields: `eventid`) |
| `SendOrder` | `fleet/webfleet/orders/send` | `sendOrderExtern` (GET) | 300 / 30 min | Send a text order to the driver terminal; ordertext must be URL-encoded; empty reply on success (fields: `objectno`, `orderid`, `ordertext`) |
| `SendDestinationOrder` | `fleet/webfleet/orders/destination/send` | `sendDestinationOrderExtern` (POST) | 300 / 30 min | Order with a destination (address or coordinates, waypoints, type, date / time) as a form-encoded POST (fields: `form`) |
| `CancelOrder` | `fleet/webfleet/orders/cancel` | `cancelOrderExtern` (GET) | 300 / 30 min | Cancel an order on the terminal (fields: `orderid`) |
| `SendTextMessage` | `fleet/webfleet/messages/send` | `sendTextMessageExtern` (GET) | 300 / 30 min | Text message to the driver terminal (max 500 chars, URL-encoded) (fields: `objectno`, `messagetext`) |
| `SwitchOutput` | `fleet/webfleet/outputs/switch` | `switchOutput` (GET) | 10 / min | Switch a digital output on the LINK device (status 1 / 0); drives real equipment (fields: `objectno`, `status`, `output_name`) |
| `InsertExternalEvent` | `fleet/webfleet/plugin/events/insert` | `insertExternalEvent` (GET) | 5 / min | Raise an own event on a vehicle (e.g. a broker alarm) from URL-encoded JSON; needs a Webfleet Plugin on the API key (fields: `objectno`, `data`) |
| `SetExternalObjectData` | `fleet/webfleet/plugin/object-data/set` | `setExternalObjectData` (GET) | 10 / min | Show broker data (temperature, load, tyre pressure) on a vehicle in Webfleet from URL-encoded JSON; needs a Webfleet Plugin (fields: `objectno`, `data`) |
| `Extern` | `fleet/webfleet/extern` | any (GET) | per action | Any WEBFLEET.connect action: action plus the remaining query string (query, starting with &; may be empty) (fields: `action`, `query`) |
| `ExternPost` | `fleet/webfleet/extern/post` | any (POST) | per action | Any POST-capable action as a form-encoded body (form = action=...&...) (fields: `form`) |

> [!TIP]
>
> For continuous tracking, use the message queue instead of polling `ShowObjectReport`. Create the queue once with `CreateQueue` (message class `0` for everything including positions, `2` for everything except positions), then call `PopQueueMessages` and, after you have stored the batch, `AckQueueMessages`. Pop and ack must not overlap.

## Prerequisites

* A Webfleet account with WEBFLEET.connect enabled and an **API key** (36 characters). Customers request one through the Webfleet support form (product **Integration**, category **API key request**); .connect partners get one during onboarding.
* A dedicated Webfleet **user** for the API, with the access rights the integration needs (for example read access to all objects, edit access to orders). The API acts as that user, so its rights limit what every event can see and change.
* The **account name**, which goes in every request.
* `InsertExternalEvent` and `SetExternalObjectData` also need a registered Webfleet Plugin tied to the API key and the Webfleet Plugin feature booked on the vehicles.

## Connection and security

* **Base address.** `https://csv.webfleet.com` is the same for every account. Only HTTPS is accepted.
* **Auth.** HTTP Basic (RFC 7617) with the Webfleet user name and password, plus `account` and `apikey` as query parameters. User name and password in the URL were removed at the end of June 2026. Store `Basic <base64(user:password)>` in a broker secret (suggested name `WEBFLEET_AUTHORIZATION`) and the key in `WEBFLEET_APIKEY`, and pass both in the payload with `GET SECRET`.
* **Writes.** Events in the writes table change orders, events or vehicle outputs. `SwitchOutput` drives a real output on the LINK device. Each write is marked `# WRITE` in the `.lot` file; restrict who can publish to those topics with an RBAC rule.
* **Encoding.** Values are placed in the query string as they are. URL-encode free text (`ordertext`, `messagetext`, `data`, the `query` and `form` tails) before publishing, for example `Load%20pallets`. Do not send empty values: Webfleet treats an empty parameter as "clear this value" on update actions.

## Pacing and errors

* Request limits are per action and per account and are listed in the tables. `ShowTripReport` and `ShowEventReport` allow **1 request per minute**, `ShowObjectReport` 6 per minute, most other reads 10 per minute, order and message writes 300 per 30 minutes, and creating or deleting a queue 10 per day. Exceeding a limit blocks further calls until a full limit interval passes without requests.
* `ShowTracks` accepts at most 2 days per call. `PopQueueMessages` returns at most 500 messages per call.
* Errors come back with **HTTP 200** and a JSON body `{"errorCode": <n>, "errorMsg": "..."}`, and in the `X-Webfleet-Errorcode` and `X-Webfleet-Errormessage` headers. For example a wrong key answers `{"errorCode":1143,"errorMsg":"API key is invalid"}`. Check for `errorCode` in the response topic rather than relying on the HTTP status.
* Send and update actions answer with an empty body on success. Reads with no data answer `[]`.
* Field names in the JSON output match the CSV column names in the reference. Positions in `ShowTracks`, `ShowNearestVehicles` and the queue are integers in micro degrees (divide by 1,000,000).

## Payload

| Field | Type | Used by | Notes |
| - | - | - | - |
| `authorization` | string | All events | `Basic <base64(user:password)>`, from `GET SECRET "WEBFLEET_AUTHORIZATION"` |
| `account` | string | All events | Webfleet account name |
| `apikey` | string | All events | API key, from `GET SECRET "WEBFLEET_APIKEY"` |
| `objectno` | string | Per-object reads and writes | Object number (case-sensitive) |
| `range` | string | Date-range reads | `range_pattern=d0` (today), `w-1` (last week), or `range_pattern=ud&rangefrom_string=<ISO>&rangeto_string=<ISO>` |
| `msgclass` | string | Queue events | `0` all, `2` all but positions, `4` orders, `5` drivers, `7` status, `8` text, `15` third party |
| `eventid`, `orderid` | string | Event and order writes | Ids from `ShowEventReport` / your own order id (max 20 bytes) |
| `ordertext`, `messagetext`, `data` | string | Orders, messages, plugin data | URL-encoded text or JSON |
| `action`, `query` | string | `Extern` | Any action name, plus the rest of the query starting with `&` (or `""`) |
| `form` | string | `SendDestinationOrder`, `ExternPost` | URL-encoded `name=value&...` body tail (`ExternPost` must include `action=`) |

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"authorization":"Basic <from secret>","account":"myaccount","apikey":"<from secret>"}
{"authorization":"...","account":"myaccount","apikey":"...","objectno":"001","range":"range_pattern=d0"}
{"authorization":"...","account":"myaccount","apikey":"...","msgclass":"2"}
{"authorization":"...","account":"myaccount","apikey":"...","objectno":"001","orderid":"CF-1001","ordertext":"Load%20pallets%20at%20dock%203"}
{"authorization":"...","account":"myaccount","apikey":"...","action":"showObjectReportExtern","query":"&objectgroupname=Porto"}
```

## Example actions

These actions read all objects once a minute, pop the message queue every 30 seconds and acknowledge each batch when the reply arrives, and read today's events every 5 minutes, all inside the request limits. Credentials come from broker secrets. In production, acknowledge only after the batch is stored.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Example actions for the WebfleetConnect route (docs page). Not part of the route template.
# Secrets: WEBFLEET_AUTHORIZATION = "Basic <base64(user:password)>" of the Webfleet API user, WEBFLEET_APIKEY = the
#   36-character API key. Replace "myaccount" with the Webfleet account name.
# Inline JSON object literals are not supported when publishing to a topic, so requests use COLLAPSED models sent
#   with PUBLISH MODEL. Request limits: showObjectReportExtern 6 / min, popQueueMessagesExtern 10 / min,
#   showEventReportExtern 1 / min; these actions stay below them.

DEFINE MODEL WebfleetRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "account"
    ADD STRING "apikey"

DEFINE MODEL WebfleetQueueRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "account"
    ADD STRING "apikey"
    ADD STRING "msgclass"

DEFINE MODEL WebfleetRangeRequest COLLAPSED
    ADD STRING "authorization"
    ADD STRING "account"
    ADD STRING "apikey"
    ADD STRING "range"

DEFINE ACTION WebfleetObjectsEveryMinute
ON EVERY 1 MINUTE DO
    PUBLISH MODEL WebfleetRequest TO "fleet/webfleet/objects/get" WITH
        authorization = (GET SECRET "WEBFLEET_AUTHORIZATION")
        account = "myaccount"
        apikey = (GET SECRET "WEBFLEET_APIKEY")

DEFINE ACTION WebfleetQueuePopEvery30Seconds
ON EVERY 30 SECONDS DO
    PUBLISH MODEL WebfleetQueueRequest TO "fleet/webfleet/queue/pop" WITH
        authorization = (GET SECRET "WEBFLEET_AUTHORIZATION")
        account = "myaccount"
        apikey = (GET SECRET "WEBFLEET_APIKEY")
        msgclass = "2"

DEFINE ACTION WebfleetQueueAckAfterPop
ON TOPIC "fleet/webfleet/queue/pop/response" DO
    PUBLISH MODEL WebfleetQueueRequest TO "fleet/webfleet/queue/ack" WITH
        authorization = (GET SECRET "WEBFLEET_AUTHORIZATION")
        account = "myaccount"
        apikey = (GET SECRET "WEBFLEET_APIKEY")
        msgclass = "2"

DEFINE ACTION WebfleetTodayEventsEvery5Minutes
ON EVERY 5 MINUTES DO
    PUBLISH MODEL WebfleetRangeRequest TO "fleet/webfleet/events/get" WITH
        authorization = (GET SECRET "WEBFLEET_AUTHORIZATION")
        account = "myaccount"
        apikey = (GET SECRET "WEBFLEET_APIKEY")
        range = "range_pattern=d0"
```

## Deployable connector

The base address is already correct for every account. Set the secrets, then deploy.

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Webfleet (Bridgestone) WEBFLEET.connect, CSV/JSON API with JSON output:
#   objects with latest positions, vehicles, groups, nearest vehicles, position tracks, trips and trip summaries,
#   standstills, digital I/O periods, events, orders, drivers and EU remaining driving times, addresses, KPIs,
#   EV battery level, diagnostic faults, temperature and cold chain sensors, asset tracker battery, the message
#   queue (create / pop / ack / delete), and writes (acknowledge / resolve events, send / cancel orders, destination
#   orders, text messages, switch a LINK output, Webfleet Plugin events and object data, generic action).
#   (https://www.webfleet.com/static/help/webfleet-connect/en_gb/index.html), fetched 2026-10-05 into
# Docs: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/webfleet
#
# Every call is GET (or form POST) https://csv.webfleet.com/extern?account=..&apikey=..&action=<operation>&...
#   with outputformat=json, useISO8601=true (dates in and out are ISO 8601, results in UTC) and useUTF8=true.
# Auth: HTTP Basic (RFC 7617) for the Webfleet user that has API rights, plus the account name and a 36-character
#   API key as query parameters. User name and password in the URL were removed end of June 2026.
#   Keep "Basic <base64(user:password)>" in broker secret WEBFLEET_AUTHORIZATION and the key in WEBFLEET_APIKEY,
#   and pass both in the payload with GET SECRET. The API user acts with its own Webfleet access rights.
# Errors: HTTP 200 with {"errorCode": <n>, "errorMsg": "..."} in JSON (also X-Webfleet-Errorcode /
#   X-Webfleet-Errormessage headers), e.g. 1143 "API key is invalid". Empty results are []; send / update
#   actions return an empty body on success.
# Request limits are per action and per account (comment above each event). showTripReportExtern and
#   showEventReportExtern allow 1 call per minute; for continuous tracking use the message queue
#   (CreateQueue once, then PopQueueMessages + AckQueueMessages, serialised) instead of polling ShowObjectReport.
# Writes are marked # WRITE. Restrict who can publish to those topics with an RBAC rule.
#
# Payload fields (JSON on the source topic): authorization, account, apikey on every event, plus:
#   objectno (object number), objectuid, latitude / longitude (micro degrees), range (date range query:
#   "range_pattern=d0" or "range_pattern=ud&rangefrom_string=2026-10-05T00:00:00Z&rangeto_string=2026-10-05T23:59:59Z"),
#   kpinames, msgclass, eventid, orderid, ordertext / messagetext / data (URL-encoded), status, output_name,
#   action + query (Extern; query starts with & or is ""), form (POST body tail, URL-encoded name=value pairs).
#     ShowObjectReport     {"authorization":"Basic ...","account":"myaccount","apikey":"..."}
#     ShowTracks           {..., "objectno":"001", "range":"range_pattern=d0"}
#     PopQueueMessages     {..., "msgclass":"2"}
#     SendOrder            {..., "objectno":"001", "orderid":"CF-1001", "ordertext":"Load%20pallets%20at%20dock%203"}
#     Extern               {..., "action":"showObjectReportExtern", "query":"&objectgroupname=Porto"}

DEFINE CONNECTOR WebfleetConnect WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://csv.webfleet.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # BASE_ADDRESS is fixed for every account (https://csv.webfleet.com, path /extern). Only HTTPS is accepted.
    # Webfleet request limit for showObjectReportExtern: 6 / min.
    ADD EVENT ShowObjectReport
        WITH SOURCE_TOPIC "fleet/webfleet/objects/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/objects/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showObjectReportExtern"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showVehicleReportExtern: 10 / min.
    ADD EVENT ShowVehicleReport
        WITH SOURCE_TOPIC "fleet/webfleet/vehicles/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/vehicles/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showVehicleReportExtern"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showObjectGroups: 10 / min.
    ADD EVENT ShowObjectGroups
        WITH SOURCE_TOPIC "fleet/webfleet/object-groups/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/object-groups/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showObjectGroups"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showNearestVehicles: 10 / min.
    ADD EVENT ShowNearestVehicles
        WITH SOURCE_TOPIC "fleet/webfleet/vehicles/nearest/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/vehicles/nearest/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showNearestVehicles&latitude={value.json.latitude}&longitude={value.json.longitude}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showTracks: 10 / min.
    ADD EVENT ShowTracks
        WITH SOURCE_TOPIC "fleet/webfleet/tracks/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/tracks/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showTracks&objectno={value.json.objectno}&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showTripReportExtern: 1 / min.
    ADD EVENT ShowTripReport
        WITH SOURCE_TOPIC "fleet/webfleet/trips/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/trips/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showTripReportExtern&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showTripSummaryReportExtern: 10 / min.
    ADD EVENT ShowTripSummaryReport
        WITH SOURCE_TOPIC "fleet/webfleet/trips/summary/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/trips/summary/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showTripSummaryReportExtern&objectno={value.json.objectno}&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showStandStills: 6 / min.
    ADD EVENT ShowStandStills
        WITH SOURCE_TOPIC "fleet/webfleet/standstills/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/standstills/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showStandStills&objectno={value.json.objectno}&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showIOReportExtern: 10 / min.
    ADD EVENT ShowIOReport
        WITH SOURCE_TOPIC "fleet/webfleet/io/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/io/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showIOReportExtern&objectno={value.json.objectno}&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showEventReportExtern: 1 / min.
    ADD EVENT ShowEventReport
        WITH SOURCE_TOPIC "fleet/webfleet/events/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/events/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showEventReportExtern&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showOrderReportExtern: 6 / min.
    ADD EVENT ShowOrderReport
        WITH SOURCE_TOPIC "fleet/webfleet/orders/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/orders/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showOrderReportExtern&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showDriverReportExtern: 10 / min.
    ADD EVENT ShowDriverReport
        WITH SOURCE_TOPIC "fleet/webfleet/drivers/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/drivers/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showDriverReportExtern"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for getRemainingDrivingTimesEU: 10 / min.
    ADD EVENT GetRemainingDrivingTimesEU
        WITH SOURCE_TOPIC "fleet/webfleet/drivers/driving-times/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/drivers/driving-times/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=getRemainingDrivingTimesEU"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for showAddressReportExtern: 6 / min.
    ADD EVENT ShowAddressReport
        WITH SOURCE_TOPIC "fleet/webfleet/addresses/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/addresses/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=showAddressReportExtern"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for getObjectKPIs: 10 / min.
    ADD EVENT GetObjectKPIs
        WITH SOURCE_TOPIC "fleet/webfleet/kpis/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/kpis/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=getObjectKPIs&objectno={value.json.objectno}&kpinames={value.json.kpinames}&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for getElectricVehicleData: 6 / min.
    ADD EVENT GetElectricVehicleData
        WITH SOURCE_TOPIC "fleet/webfleet/ev/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/ev/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=getElectricVehicleData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for getDiagnosticFaults: 10 / min.
    ADD EVENT GetDiagnosticFaults
        WITH SOURCE_TOPIC "fleet/webfleet/diagnostics/faults/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/diagnostics/faults/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=getDiagnosticFaults&{value.json.range}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for getCurrentTemperatureData: 10 / min.
    ADD EVENT GetCurrentTemperatureData
        WITH SOURCE_TOPIC "fleet/webfleet/temperature/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/temperature/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=getCurrentTemperatureData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for getCurrentColdChainSensorData: 10 / min.
    ADD EVENT GetCurrentColdChainSensorData
        WITH SOURCE_TOPIC "fleet/webfleet/coldchain/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/coldchain/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=getCurrentColdChainSensorData"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for getTelemetryDeviceBatteryState: 10 / min.
    ADD EVENT GetTelemetryDeviceBatteryState
        WITH SOURCE_TOPIC "fleet/webfleet/device-battery/get"
        WITH DESTINATION_TOPIC "fleet/webfleet/device-battery/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=getTelemetryDeviceBatteryState&objectuid={value.json.objectuid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # Webfleet request limit for popQueueMessagesExtern: 10 / min.
    ADD EVENT PopQueueMessages
        WITH SOURCE_TOPIC "fleet/webfleet/queue/pop"
        WITH DESTINATION_TOPIC "fleet/webfleet/queue/pop/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=popQueueMessagesExtern&msgclass={value.json.msgclass}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: AckQueueMessages changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/queue/ack.
    # Webfleet request limit for ackQueueMessagesExtern: 10 / min.
    ADD EVENT AckQueueMessages
        WITH SOURCE_TOPIC "fleet/webfleet/queue/ack"
        WITH DESTINATION_TOPIC "fleet/webfleet/queue/ack/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=ackQueueMessagesExtern&msgclass={value.json.msgclass}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: CreateQueue changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/queue/create.
    # Webfleet request limit for createQueueExtern: 10 / 24 h.
    ADD EVENT CreateQueue
        WITH SOURCE_TOPIC "fleet/webfleet/queue/create"
        WITH DESTINATION_TOPIC "fleet/webfleet/queue/create/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=createQueueExtern&msgclass={value.json.msgclass}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: DeleteQueue changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/queue/delete.
    # Webfleet request limit for deleteQueueExtern: 10 / 24 h.
    ADD EVENT DeleteQueue
        WITH SOURCE_TOPIC "fleet/webfleet/queue/delete"
        WITH DESTINATION_TOPIC "fleet/webfleet/queue/delete/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=deleteQueueExtern&msgclass={value.json.msgclass}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: AcknowledgeEvent changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/events/acknowledge.
    # Webfleet request limit for acknowledgeEventExtern: 300 / 30 min.
    ADD EVENT AcknowledgeEvent
        WITH SOURCE_TOPIC "fleet/webfleet/events/acknowledge"
        WITH DESTINATION_TOPIC "fleet/webfleet/events/acknowledge/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=acknowledgeEventExtern&eventid={value.json.eventid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: ResolveEvent changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/events/resolve.
    # Webfleet request limit for resolveEventExtern: 300 / 30 min.
    ADD EVENT ResolveEvent
        WITH SOURCE_TOPIC "fleet/webfleet/events/resolve"
        WITH DESTINATION_TOPIC "fleet/webfleet/events/resolve/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=resolveEventExtern&eventid={value.json.eventid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: SendOrder changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/orders/send.
    # Webfleet request limit for sendOrderExtern: 300 / 30 min.
    ADD EVENT SendOrder
        WITH SOURCE_TOPIC "fleet/webfleet/orders/send"
        WITH DESTINATION_TOPIC "fleet/webfleet/orders/send/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=sendOrderExtern&objectno={value.json.objectno}&orderid={value.json.orderid}&ordertext={value.json.ordertext}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: SendDestinationOrder changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/orders/destination/send.
    # Webfleet request limit for sendDestinationOrderExtern: 300 / 30 min.
    ADD EVENT SendDestinationOrder
        WITH SOURCE_TOPIC "fleet/webfleet/orders/destination/send"
        WITH DESTINATION_TOPIC "fleet/webfleet/orders/destination/send/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/extern"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded;charset=UTF-8"
        WITH BODY "account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=sendDestinationOrderExtern&{value.json.form}"
    # WRITE: CancelOrder changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/orders/cancel.
    # Webfleet request limit for cancelOrderExtern: 300 / 30 min.
    ADD EVENT CancelOrder
        WITH SOURCE_TOPIC "fleet/webfleet/orders/cancel"
        WITH DESTINATION_TOPIC "fleet/webfleet/orders/cancel/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=cancelOrderExtern&orderid={value.json.orderid}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: SendTextMessage changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/messages/send.
    # Webfleet request limit for sendTextMessageExtern: 300 / 30 min.
    ADD EVENT SendTextMessage
        WITH SOURCE_TOPIC "fleet/webfleet/messages/send"
        WITH DESTINATION_TOPIC "fleet/webfleet/messages/send/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=sendTextMessageExtern&objectno={value.json.objectno}&messagetext={value.json.messagetext}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: SwitchOutput changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/outputs/switch.
    # Webfleet request limit for switchOutput: 10 / min.
    ADD EVENT SwitchOutput
        WITH SOURCE_TOPIC "fleet/webfleet/outputs/switch"
        WITH DESTINATION_TOPIC "fleet/webfleet/outputs/switch/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=switchOutput&objectno={value.json.objectno}&status={value.json.status}&output_name={value.json.output_name}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: InsertExternalEvent changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/plugin/events/insert.
    # Webfleet request limit for insertExternalEvent: 5 / min.
    ADD EVENT InsertExternalEvent
        WITH SOURCE_TOPIC "fleet/webfleet/plugin/events/insert"
        WITH DESTINATION_TOPIC "fleet/webfleet/plugin/events/insert/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=insertExternalEvent&objectno={value.json.objectno}&data={value.json.data}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: SetExternalObjectData changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/plugin/object-data/set.
    # Webfleet request limit for setExternalObjectData: 10 / min.
    ADD EVENT SetExternalObjectData
        WITH SOURCE_TOPIC "fleet/webfleet/plugin/object-data/set"
        WITH DESTINATION_TOPIC "fleet/webfleet/plugin/object-data/set/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action=setExternalObjectData&objectno={value.json.objectno}&data={value.json.data}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: Extern changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/extern.
    # Webfleet request limit for the chosen action: per action.
    ADD EVENT Extern
        WITH SOURCE_TOPIC "fleet/webfleet/extern"
        WITH DESTINATION_TOPIC "fleet/webfleet/extern/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/extern?account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&action={value.json.action}{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
    # WRITE: ExternPost changes data in Webfleet or on a vehicle. Restrict who can publish to fleet/webfleet/extern/post.
    # Webfleet request limit for the chosen action: per action.
    ADD EVENT ExternPost
        WITH SOURCE_TOPIC "fleet/webfleet/extern/post"
        WITH DESTINATION_TOPIC "fleet/webfleet/extern/post/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/extern"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/x-www-form-urlencoded;charset=UTF-8"
        WITH BODY "account={value.json.account}&apikey={value.json.apikey}&lang=en&outputformat=json&useISO8601=true&useUTF8=true&{value.json.form}"
```


# WhatsApp Business Platform (Meta Cloud API)
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/whatsapp-business-platform

LoT REST API connector for the WhatsApp Cloud API: send text and template messages, check phone numbers, and list WhatsApp Business message templates

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/overview) on Meta Graph **v21.0**:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST messages (template) | `POST /{phone_number_id}/messages` | `type=template` + body params (alarms) |
| POST messages (text) | `POST /{phone_number_id}/messages` | `type=text` within 24h window |
| GET phone number | `GET /{phone_number_id}` | Bearer credential check |
| GET message\_templates | `GET /{whatsapp_business_account_id}/message_templates` | List WABA templates |
| Inbound webhook (secondary) | Meta Cloud API webhooks | Client-mode package; webhook → MQTT out of scope |

Default `BASE_ADDRESS` is `https://graph.facebook.com/v21.0`. Topics use `messaging/whatsapp-business-platform/<object>/<verb>`.

> [!NOTE]
>
> All events send `Authorization: Bearer {access_token}` (system user / permanent token). Prefer Hub secrets (`WHATSAPP_ACCESS_TOKEN` / `WHATSAPP_TOKEN`). Use the WhatsApp **Business phone number ID** in the path — not the customer MSISDN. Graph returns **OAuthException 190** on bad tokens.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — WhatsApp Cloud API Graph v21.0
# Auth: Bearer {value.json.access_token}
# BASE_ADDRESS: https://graph.facebook.com/v21.0

DEFINE CONNECTOR WhatsAppBusinessPlatformRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://graph.facebook.com/v21.0"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getphonenumber
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/phone/get"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/phone/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.phone_number_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Sendtextmessage
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/message/send-text"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/message/send-text/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.phone_number_id}/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Sendtemplatemessage
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/message/send-template"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/message/send-template/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.phone_number_id}/messages"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Listmessagetemplates
        WITH SOURCE_TOPIC "messaging/whatsapp-business-platform/template/list"
        WITH DESTINATION_TOPIC "messaging/whatsapp-business-platform/template/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.whatsapp_business_account_id}/message_templates"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Auth and secrets

1. Create a Meta app with WhatsApp product / Cloud API access and a **system user** (or permanent) token with `whatsapp_business_messaging` (and related) permissions.
2. Store the token as Hub secret `WHATSAPP_ACCESS_TOKEN` (alias `WHATSAPP_TOKEN`).
3. Note your WhatsApp Business **phone\_number\_id** and **WABA** id from Meta Business Suite / WhatsApp Manager.
4. Publish MQTT JSON that includes `access_token` (or inject via Hub) plus path ids.

Never commit real tokens.

## Example payloads

**Phone number**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_WHATSAPP_ACCESS_TOKEN",
  "phone_number_id": "YOUR_PHONE_NUMBER_ID"
}
```

**Text message**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_WHATSAPP_ACCESS_TOKEN",
  "phone_number_id": "YOUR_PHONE_NUMBER_ID",
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "text",
  "text": { "body": "Coreflux alarm: Zone A vibration" }
}
```

**Template (alarm params)**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_WHATSAPP_ACCESS_TOKEN",
  "phone_number_id": "YOUR_PHONE_NUMBER_ID",
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "coreflux_alarm",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Zone A" },
          { "type": "text", "text": "vibration high" }
        ]
      }
    ]
  }
}
```

## Install

1. The template ships with the broker. List it with `-listTemplates` or fetch it from the Hub catalog.
2. Deploy `WhatsAppBusinessPlatformRestApi.lot` only (not `hub-metadata.lot`).
3. Smoke with `GET /{phone_number_id}` → 200 before sending production templates.

## References

* [Cloud API overview](https://developers.facebook.com/docs/whatsapp/cloud-api/overview)
* [Messages reference](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages)
* [Text messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/text-messages)
* Meta Postman: WhatsApp Business Platform collection
* Coreflux: [REST API Connectors](/latest/lot-language/routes/rest-api-routes)


# Workday
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/workday

Client-mode REST API connector for a curated Workday staffing slice: list workers and get one worker

Technical Preview

# Workday

Client-mode REST API connector for a curated Workday staffing slice: list workers and get one worker.

* Hub category: **HR**.
* Base: `https://impl.workday.com`

## Template reference

Generated from the shipped broker template `workday` (`-connectorCode WORKDAY`). It lists every event the template defines.

### Auth

Auth headers used by the template: `Authorization: Bearer {value.json.api_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Workday connector | no |
| `BaseUrl` | string | Workday base URL without trailing slash (e.g. [https://impl.workday.com](https://impl.workday.com)) | yes |

`BASE_ADDRESS` default: `https://impl.workday.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Listworkers` | GET | `/ccx/api/staffing/v6/{value.json.tenant}/workers` | `hr/workday/workers/list` | `hr/workday/workers/list/response` | `api_token`, `tenant` |
| `Getworker` | GET | `/ccx/api/staffing/v6/{value.json.tenant}/workers/{value.json.worker_id}` | `hr/workday/workers/get` | `hr/workday/workers/get/response` | `api_token`, `tenant`, `worker_id` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode WORKDAY"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WorkdayRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://impl.workday.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listworkers
        WITH SOURCE_TOPIC "hr/workday/workers/list"
        WITH DESTINATION_TOPIC "hr/workday/workers/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ccx/api/staffing/v6/{value.json.tenant}/workers"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
    ADD EVENT Getworker
        WITH SOURCE_TOPIC "hr/workday/workers/get"
        WITH DESTINATION_TOPIC "hr/workday/workers/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/ccx/api/staffing/v6/{value.json.tenant}/workers/{value.json.worker_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.api_token}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Listworkers` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'hr/workday/workers/list/response' &
mosquitto_pub -t 'hr/workday/workers/list' -m '{"api_token": "<api_token>", "tenant": "<tenant>"}'
```


# Xero
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/xero

LoT REST API connector for the Xero Accounting API: create and approve invoices from production events, manage inventory items, and query contacts

Technical Preview

## Overview

A client-mode connector for the [Xero Accounting API](https://developer.xero.com/documentation/api/accounting/overview) (`api.xro/2.0`). Use it to connect the shop floor to accounting: raise a sales invoice when a batch ships, keep the item catalogue in step with your MES, and read item stock levels, open invoices or customers into MQTT.

The file holds two connectors. `XeroAccountingRestApi` talks to `https://api.xero.com` (accounting calls and tenant discovery), and `XeroOAuth` gets access tokens from Xero's identity host.

| Event | Request | Notes |
| - | - | - |
| GetConnections | `GET /connections` | Lists the organisations (tenants) the token can reach; gives the `tenantId` |
| GetOrganisation | `GET /api.xro/2.0/Organisation` | Smoke and tenant check |
| GetItems | `GET /api.xro/2.0/Items?where=` | Filter items, URL-encoded (for example `IsTrackedAsInventory==true`) |
| GetItem | `GET /api.xro/2.0/Items/{id}` | One item by `ItemID` (the Xero docs also allow the item `Code`); includes `QuantityOnHand` |
| CreateItems | `PUT /api.xro/2.0/Items` | Create only; fails if the `Code` exists |
| UpdateOrCreateItems | `POST /api.xro/2.0/Items` | Create or update (matched on `ItemID` or `Code`) |
| GetInvoices | `GET /api.xro/2.0/Invoices?where=&page=` | Filter invoices, 100 per page with line items |
| GetInvoice | `GET /api.xro/2.0/Invoices/{id}` | One invoice by `InvoiceID` or `InvoiceNumber` |
| CreateInvoices | `PUT /api.xro/2.0/Invoices` | Create only |
| UpdateOrCreateInvoices | `POST /api.xro/2.0/Invoices` | Create or update, for example approve a draft |
| EmailInvoice | `POST /api.xro/2.0/Invoices/{id}/Email` | Emails an approved sales invoice to the contact; **204** with an empty body |
| GetContacts | `GET /api.xro/2.0/Contacts?where=&page=` | Filter customers and suppliers |
| CreateContacts | `PUT /api.xro/2.0/Contacts` | `Name` must be unique |
| RefreshToken | `POST /connect/token` (on `identity.xero.com`) | `refresh_token` grant; new access token and refresh token |
| ClientCredentialsToken | `POST /connect/token` (on `identity.xero.com`) | `client_credentials` grant for custom connections |

Every accounting call sends `Accept: application/json` (Xero answers XML otherwise) and the `xero-tenant-id` header. Topics use `finance/xero/<object>/<verb>`; replies land on `<topic>/response`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Auth:** Xero uses OAuth 2.0, in one of two ways.
>
> * **Web app (authorization code).** Do the one-time consent outside the broker, asking for `offline_access` plus the accounting scopes you need, to get a refresh token. Then call GetConnections once to find the organisation's `tenantId`. After that the broker can stay connected on its own: publish to RefreshToken to get a fresh access token (valid 30 minutes).
> * **Custom connection (client credentials).** A custom connection is linked to one organisation and has no refresh token. Publish to ClientCredentialsToken with the scopes to get a 30-minute access token. Custom connections are a paid Xero option, but you can try one for free with the Demo Company.
>
> Every accounting call then takes `access_token` and `tenant_id` from the payload. Keep the client id, client secret and refresh token in Hub secrets (suggested names `XERO_CLIENT_ID`, `XERO_CLIENT_SECRET`, `XERO_BASIC_AUTH`, `XERO_REFRESH_TOKEN`, `XERO_TENANT_ID`). Never commit them into the `.lot`.

> [!WARNING]
>
> The refresh token **rotates**. Each refresh returns a new `refresh_token`, and the old one stops working. Always store the latest value. A refresh token that is not used for 60 days expires, and the user has to connect again.

> [!TIP]
>
> **Scopes.** Xero apps created on or after 2 March 2026 only get granular scopes. For this template ask for `accounting.invoices` (invoices and items), `accounting.contacts` and `accounting.settings` (organisation and items), plus `offline_access` for a refresh token. Older apps can keep the broad `accounting.transactions` scope until September 2027. A call without the right scope fails with **401** or **403**.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR XeroAccountingRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://api.xero.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Bearer {value.json.access_token}; tenant {value.json.tenant_id} (from GetConnections). Never commit tokens.
    ADD EVENT GetConnections
        WITH SOURCE_TOPIC "finance/xero/connections/get"
        WITH DESTINATION_TOPIC "finance/xero/connections/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/connections"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT GetOrganisation
        WITH SOURCE_TOPIC "finance/xero/organisation/get"
        WITH DESTINATION_TOPIC "finance/xero/organisation/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api.xro/2.0/Organisation"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
    ADD EVENT GetItems
        WITH SOURCE_TOPIC "finance/xero/item/list"
        WITH DESTINATION_TOPIC "finance/xero/item/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api.xro/2.0/Items?where={value.json.where}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
    ADD EVENT GetItem
        WITH SOURCE_TOPIC "finance/xero/item/get"
        WITH DESTINATION_TOPIC "finance/xero/item/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api.xro/2.0/Items/{value.json.item_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
    ADD EVENT CreateItems
        WITH SOURCE_TOPIC "finance/xero/item/create"
        WITH DESTINATION_TOPIC "finance/xero/item/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api.xro/2.0/Items"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateOrCreateItems
        WITH SOURCE_TOPIC "finance/xero/item/upsert"
        WITH DESTINATION_TOPIC "finance/xero/item/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api.xro/2.0/Items"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetInvoices
        WITH SOURCE_TOPIC "finance/xero/invoice/list"
        WITH DESTINATION_TOPIC "finance/xero/invoice/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api.xro/2.0/Invoices?where={value.json.where}&page={value.json.page}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
    ADD EVENT GetInvoice
        WITH SOURCE_TOPIC "finance/xero/invoice/get"
        WITH DESTINATION_TOPIC "finance/xero/invoice/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api.xro/2.0/Invoices/{value.json.invoice_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
    ADD EVENT CreateInvoices
        WITH SOURCE_TOPIC "finance/xero/invoice/create"
        WITH DESTINATION_TOPIC "finance/xero/invoice/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api.xro/2.0/Invoices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateOrCreateInvoices
        WITH SOURCE_TOPIC "finance/xero/invoice/upsert"
        WITH DESTINATION_TOPIC "finance/xero/invoice/upsert/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api.xro/2.0/Invoices"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
        WITH BODY "{value.json.body}"
    ADD EVENT EmailInvoice
        WITH SOURCE_TOPIC "finance/xero/invoice/email"
        WITH DESTINATION_TOPIC "finance/xero/invoice/email/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api.xro/2.0/Invoices/{value.json.invoice_id}/Email"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
        WITH BODY "{}"
    ADD EVENT GetContacts
        WITH SOURCE_TOPIC "finance/xero/contact/list"
        WITH DESTINATION_TOPIC "finance/xero/contact/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api.xro/2.0/Contacts?where={value.json.where}&page={value.json.page}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
    ADD EVENT CreateContacts
        WITH SOURCE_TOPIC "finance/xero/contact/create"
        WITH DESTINATION_TOPIC "finance/xero/contact/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api.xro/2.0/Contacts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
            ADD "xero-tenant-id" "{value.json.tenant_id}"
        WITH BODY "{value.json.body}"

# OAuth 2.0 token endpoint (different host). basic_auth = base64("<client_id>:<client_secret>") from Hub secrets.
# RefreshToken (auth-code apps): reply {"id_token":..,"access_token":"...","expires_in":1800,"token_type":"Bearer",
#   "refresh_token":"...","scope":"..."}. The refresh token ROTATES: store the returned one every time (60-day expiry).
# ClientCredentialsToken (Custom Connections only): scope is space-separated and URL-encoded by the caller
#   (accounting.invoices%20accounting.contacts%20accounting.settings); reply has access_token + expires_in 1800, no refresh token.
# Errors: 400 invalid_client (bad client id/secret), 400 invalid_grant (refresh token expired/used/revoked), 400 unauthorized_client.
DEFINE CONNECTOR XeroOAuth WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://identity.xero.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/x-www-form-urlencoded"
    ADD EVENT RefreshToken
        WITH SOURCE_TOPIC "finance/xero/oauth/refresh"
        WITH DESTINATION_TOPIC "finance/xero/oauth/refresh/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/connect/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Basic {value.json.basic_auth}"
        WITH BODY "grant_type=refresh_token&refresh_token={value.json.refresh_token}"
    ADD EVENT ClientCredentialsToken
        WITH SOURCE_TOPIC "finance/xero/oauth/token"
        WITH DESTINATION_TOPIC "finance/xero/oauth/token/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/connect/token"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            ADD "Authorization" "Basic {value.json.basic_auth}"
        WITH BODY "grant_type=client_credentials&scope={value.json.scope}"
```

## MQTT examples

Control fields (`access_token`, `tenant_id`, ids, `where`, `page`) only fill the URL and headers. Only `body` is sent as the request body.

**RefreshToken** (`finance/xero/oauth/refresh`). `basic_auth` is the Base64 of `client_id:client_secret`. Expect **200**:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "basic_auth": "<base64 client_id:client_secret>", "refresh_token": "<latest refresh token>" }
```

Response:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "id_token": "eyJhbGciOi...", "access_token": "eyJhbGciOi...", "expires_in": 1800, "token_type": "Bearer", "refresh_token": "a1b2...", "scope": "offline_access accounting.invoices accounting.contacts accounting.settings" }
```

**ClientCredentialsToken** (`finance/xero/oauth/token`), custom connections only. The scope list is space-separated, so URL-encode it:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "basic_auth": "<base64 client_id:client_secret>", "scope": "accounting.invoices%20accounting.contacts%20accounting.settings" }
```

**GetConnections** (`finance/xero/connections/get`) needs only the token. Response:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[ { "id": "7cb59f93-2964-421d-bb5e-a0f7a4572a44", "tenantId": "fe79f7dd-b6d4-4a92-ba7b-538af6289c58", "tenantType": "ORGANISATION", "tenantName": "Demo Company (Global)" } ]
```

**GetItems** (`finance/xero/item/list`). The `where` filter is placed in the URL, so URL-encode it. This asks for tracked inventory items:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access token>",
  "tenant_id": "fe79f7dd-b6d4-4a92-ba7b-538af6289c58",
  "where": "IsTrackedAsInventory%3D%3Dtrue"
}
```

Response (trimmed):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{ "Items": [ { "ItemID": "a1b2c3d4-...", "Code": "PUMP-SEAL", "Name": "Pump Seal Kit", "IsTrackedAsInventory": true, "QuantityOnHand": 10.0 } ] }
```

Other filters: `Code=="PUMP-SEAL"` becomes `Code%3D%3D%22PUMP-SEAL%22`.

**UpdateOrCreateItems** (`finance/xero/item/upsert`). Creates the item, or updates it when the `Code` already exists. Expect **200** with the item:

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access token>",
  "tenant_id": "fe79f7dd-b6d4-4a92-ba7b-538af6289c58",
  "body": {
    "Items": [
      {
        "Code": "PUMP-SEAL",
        "Name": "Pump Seal Kit",
        "IsTrackedAsInventory": true,
        "InventoryAssetAccountCode": "630",
        "PurchaseDetails": { "UnitPrice": 40.0, "COGSAccountCode": "310" },
        "SalesDetails": { "UnitPrice": 75.0, "AccountCode": "200" }
      }
    ]
  }
}
```

A tracked item needs an inventory asset account and a cost of goods sold account. `QuantityOnHand` is read only: stock goes up with approved purchase bills (`ACCPAY`) and down with approved sales invoices (`ACCREC`). Use CreateItems (`PUT`) when a repeated `Code` should fail instead of update.

**CreateInvoices** (`finance/xero/invoice/create`). Bills a customer for two seal kits from batch 4711. Expect **200** with the new invoice (`InvoiceID`, `InvoiceNumber`, `Total`):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "<access token>",
  "tenant_id": "fe79f7dd-b6d4-4a92-ba7b-538af6289c58",
  "body": {
    "Invoices": [
      {
        "Type": "ACCREC",
        "Contact": { "ContactID": "c0ffee00-0000-4000-8000-000000000058" },
        "Date": "2026-10-05",
        "DueDate": "2026-11-04",
        "LineAmountTypes": "Exclusive",
        "Status": "AUTHORISED",
        "Reference": "Batch 4711",
        "LineItems": [
          { "ItemCode": "PUMP-SEAL", "Description": "Pump Seal Kit", "Quantity": 2, "UnitAmount": 75.0, "AccountCode": "200" }
        ]
      }
    ]
  }
}
```

Leave out `Status` (or send `DRAFT`) to create a draft for review, then approve it later with UpdateOrCreateInvoices: `{"Invoices":[{"InvoiceID":"<id>","Status":"AUTHORISED"}]}`.

**EmailInvoice** (`finance/xero/invoice/email`) takes `invoice_id`. The invoice must be an approved sales invoice and the contact needs an email address. Xero answers **204** with an empty body.

**GetInvoices** and **GetContacts** take `where` and `page` (start at `1`), for example `"where": "Status%3D%3D%22AUTHORISED%22", "page": 1`.

## Keeping the token

A pair of small actions can refresh the token from Hub secrets and keep the latest values when the reply arrives:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION XeroRefreshFromSecrets
ON EVERY 25 MINUTES DO
    SET "basic" WITH GET SECRET "XERO_BASIC_AUTH"
    SET "refresh" WITH GET SECRET "XERO_REFRESH_TOKEN"
    PUBLISH TOPIC "finance/xero/oauth/refresh" WITH { "basic_auth": {basic}, "refresh_token": {refresh} }

DEFINE ACTION XeroKeepToken
ON TOPIC "finance/xero/oauth/refresh/response" DO
    SET "access" WITH GET JSON "access_token" IN PAYLOAD AS STRING
    SET "refresh" WITH GET JSON "refresh_token" IN PAYLOAD AS STRING
    IF {refresh} != "null" THEN
        KEEP SECRET "XERO_REFRESH_TOKEN" WITH {refresh}
        KEEP TOPIC "finance/xero/session/access_token" WITH {access}
```

Refresh before the access token expires (it lasts 30 minutes), or when a call returns **401** `AuthenticationUnsuccessful`. Restrict who can read the `finance/xero/#` topics with a rule, because these payloads carry tokens and client credentials.

## Webhooks (companion, not packaged)

Xero [webhooks](https://developer.xero.com/documentation/guides/webhooks/overview) `POST` events (for example invoice or contact created or updated) to an HTTPS URL. Each request carries an `x-xero-signature` header, an HMAC-SHA256 of the body with your webhook key, and Xero first checks the URL with an "intent to receive" handshake. Receiving them needs a separate `ENABLE_SERVER` REST API connector on a publicly reachable HTTPS address. That companion connector is not part of this template. Polling GetInvoices with an `UpdatedDateUTC` filter is the alternative.

## Notes

* Limits per organisation: 5 calls at a time, 60 calls per minute and 5,000 calls per day (1,000 per day on Xero's free Starter developer tier). Across all organisations an app can make 10,000 calls per minute. Above that Xero answers **429** with a `Retry-After` header. Each reply carries `X-MinLimit-Remaining` and `X-DayLimit-Remaining`.
* `PUT` and `POST` take up to 50 records per call. By default one invalid record fails the whole request with **400**.
* Common errors: **401** `AuthenticationUnsuccessful` (expired or invalid token, or a missing scope), **403** (the token is not connected to that `tenant_id`), **400** `ValidationException` with the reason under `Elements[].ValidationErrors`, **404** (unknown id), **429** (rate limit).
* Add an `Idempotency-Key` header to a write event if the broker may retry it; Xero then ignores repeats of the same request.
* Not covered: invoice PDF download (binary), attachments, the Payroll, Projects and Assets APIs, disconnecting a tenant (`DELETE /connections/{id}`) and token revoke (`POST https://identity.xero.com/connect/revocation`).

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Xero Accounting API: Invoices](https://developer.xero.com/documentation/api/accounting/invoices)
* [Xero Accounting API: Items](https://developer.xero.com/documentation/api/accounting/items)
* [Xero OAuth 2.0 auth flow](https://developer.xero.com/documentation/guides/oauth2/auth-flow)
* [Xero custom connections](https://developer.xero.com/documentation/guides/oauth2/custom-connections)
* [Xero OpenAPI specs](https://github.com/XeroAPI/Xero-OpenAPI)


# Zabbix
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/zabbix

LoT REST API connector for the Zabbix JSON-RPC API: read history and problems, acknowledge events, list hosts and check the API version from MQTT

Technical Preview

## Overview

A client-mode connector for a **curated observability / ITSM** slice of the [Zabbix JSON-RPC API](https://www.zabbix.com/documentation/7.4/en/manual/api):

| Catalog connector event | Entity / method | Notes |
| - | - | - |
| POST history.get | `history.get` via `POST …/api_jsonrpc.php` | Item history; Bearer token; expect **200** + `result` |
| POST problem.get | `problem.get` | Unresolved / recent problems; preferred credential check |
| POST event.acknowledge | `event.acknowledge` | Action bitmask (e.g. `6` = ack + message) |
| host.get | `host.get` | Authenticated read |
| apiinfo.version | `apiinfo.version` | No auth; connectivity only — confirms the API answers |
| Webhook media type | inbound HTTP | **ENABLE\_SERVER** companion (not a client EVENT in this template) |

Default `BASE_ADDRESS` is `https://YOUR_ZABBIX_HOST` with ENDPOINT `/zabbix/api_jsonrpc.php`. Topics use `itsm/zabbix/<object>/<verb>`.

> [!NOTE]
>
> Replace `YOUR_ZABBIX_HOST` with your Zabbix frontend host. If the frontend is at web root (not under `/zabbix/`), change ENDPOINT to `/api_jsonrpc.php`.

> [!NOTE]
>
> Prefer Hub secrets for the API token (`ZABBIX_API_TOKEN`) and host.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Zabbix (JSON-RPC 2.0)
# Auth: Authorization: Bearer {value.json.api_token}
# BASE_ADDRESS: https://YOUR_ZABBIX_HOST
# ENDPOINT: /zabbix/api_jsonrpc.php (or /api_jsonrpc.php)

DEFINE CONNECTOR ZabbixRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_ZABBIX_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json-rpc"
    ADD EVENT Historyget
        WITH SOURCE_TOPIC "itsm/zabbix/history/get"
        WITH DESTINATION_TOPIC "itsm/zabbix/history/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/zabbix/api_jsonrpc.php"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json-rpc"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Problemget
        WITH SOURCE_TOPIC "itsm/zabbix/problem/get"
        WITH DESTINATION_TOPIC "itsm/zabbix/problem/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/zabbix/api_jsonrpc.php"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json-rpc"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Eventacknowledge
        WITH SOURCE_TOPIC "itsm/zabbix/event/acknowledge"
        WITH DESTINATION_TOPIC "itsm/zabbix/event/acknowledge/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/zabbix/api_jsonrpc.php"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json-rpc"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Hostget
        WITH SOURCE_TOPIC "itsm/zabbix/host/get"
        WITH DESTINATION_TOPIC "itsm/zabbix/host/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/zabbix/api_jsonrpc.php"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json-rpc"
            ADD "Authorization" "Bearer {value.json.api_token}"
        WITH BODY "{payload}"
    ADD EVENT Apiinfoversion
        WITH SOURCE_TOPIC "itsm/zabbix/apiinfo/version"
        WITH DESTINATION_TOPIC "itsm/zabbix/apiinfo/version/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/zabbix/api_jsonrpc.php"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json-rpc"
        WITH BODY "{payload}"
```

## Authentication

| Mode | How | Notes |
| - | - | - |
| API token / session (modern) | `Authorization: Bearer {value.json.api_token}` | Default in this template (Zabbix 5.4+/6+/7) |
| Legacy session | JSON-RPC body `"auth": "<session id>"` | From `user.login`; omit Bearer |

Store the token in Hub secrets (`ZABBIX_API_TOKEN`) and resolve via `GET SECRET` — never commit credentials. Content-Type: `application/json-rpc` (also `application/json` / `application/jsonrequest`).

## MQTT examples

**problem.get** (checks the token):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "jsonrpc": "2.0",
  "method": "problem.get",
  "params": {
    "output": "extend",
    "recent": true,
    "limit": 10
  },
  "id": 1
}
```

Expect **HTTP 200** with JSON-RPC `result` (not `error`).

**history.get:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "jsonrpc": "2.0",
  "method": "history.get",
  "params": {
    "output": "extend",
    "history": 0,
    "itemids": "23296",
    "sortfield": "clock",
    "sortorder": "DESC",
    "limit": 10
  },
  "id": 1
}
```

**event.acknowledge** (action `6` = acknowledge + message):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "jsonrpc": "2.0",
  "method": "event.acknowledge",
  "params": {
    "eventids": "20427",
    "action": 6,
    "message": "Acknowledged from Coreflux"
  },
  "id": 1
}
```

**apiinfo.version** (no token on this event):

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "jsonrpc": "2.0",
  "method": "apiinfo.version",
  "params": {},
  "id": 1
}
```

Publish pure JSON-RPC as the body. Prefer wiring Bearer from Hub secrets so `api_token` is not embedded in the JSON-RPC object.

## Webhook media type (companion)

Zabbix [Webhook media type](https://www.zabbix.com/documentation/7.4/en/manual/config/notifications/media/webhook) sends notifications to your URL. Use a separate broker connector with `ENABLE_SERVER` to receive those callbacks. Not included as a client EVENT in this package.

## JSON-RPC packaging note

Unlike classic REST connectors, every method shares one POST path. Differentiation is the JSON-RPC `method` field and MQTT topic. This package was **hand-curated** (OpenAPI cache still documents the ops).

## Sources

* [Zabbix API](https://www.zabbix.com/documentation/7.4/en/manual/api)
* [history.get](https://www.zabbix.com/documentation/7.4/en/manual/api/reference/history/get)
* [problem.get](https://www.zabbix.com/documentation/7.4/en/manual/api/reference/problem/get)
* [event.acknowledge](https://www.zabbix.com/documentation/7.4/en/manual/api/reference/event/acknowledge)
* [host.get](https://www.zabbix.com/documentation/7.4/en/manual/api/reference/host/get)
* [Webhook media type](https://www.zabbix.com/documentation/7.4/en/manual/config/notifications/media/webhook)

## Package

Broker template folder: `src/CorefluxCentral/Routes/Templates/RestApiConnectors/zabbix/`

Deployable file: `ZabbixRestApi.lot` (no `ADD METADATA`). Hub icon/status: `hub-metadata.lot`.


# Zendesk Support
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/zendesk-support

Client-mode REST API connector for a curated Zendesk Support Ticketing API v2 slice: create tickets from alarms, update with resolution, list and add comments

Technical Preview

## Overview

A client-mode connector for a **curated Support / ticketing** slice of the [Zendesk Support Ticketing API](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/) under `https://YOUR_SUBDOMAIN.zendesk.com/api/v2/`:

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| (discovery) | `GET /api/v2/tickets` | List tickets the agent can access |
| POST tickets from alarm | `POST /api/v2/tickets` | Create ticket; required `ticket.comment` |
| (show) | `GET /api/v2/tickets/{id}` | Ticket properties (not full comment thread) |
| PUT tickets/\{id} with resolution | `PUT /api/v2/tickets/{id}` | Set `status` (e.g. `solved`) and optional comment |
| GET tickets/\{id}/comments | `GET /api/v2/tickets/{id}/comments` | List comments |
| POST tickets/\{id}/comments | *(maps to PUT)* | **No create-comment endpoint** — add via `PUT` with `ticket.comment` |

`BASE_ADDRESS` is `https://{subdomain}.zendesk.com` (no trailing slash; endpoints already include `/api/v2/...`). Topics use `crm/zendesk/<object>/<verb>`.

> [!NOTE]
>
> Zendesk documents that ticket comments are created with the Tickets API, not a separate POST under `/comments`. Including `comment` on create or update is the supported path. See [Ticket Comments](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/).

> [!NOTE]
>
> Prefer Hub secrets for tokens.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Zendesk Support (Ticketing API v2 curated slice)
# Auth: Bearer {value.json.access_token} (OAuth) or Basic email/token via config
# BASE_ADDRESS: https://YOUR_SUBDOMAIN.zendesk.com

DEFINE CONNECTOR ZendeskSupportRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_SUBDOMAIN.zendesk.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Listtickets
        WITH SOURCE_TOPIC "crm/zendesk/tickets/list"
        WITH DESTINATION_TOPIC "crm/zendesk/tickets/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createticket
        WITH SOURCE_TOPIC "crm/zendesk/tickets/create"
        WITH DESTINATION_TOPIC "crm/zendesk/tickets/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/api/v2/tickets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Showticket
        WITH SOURCE_TOPIC "crm/zendesk/tickets/show"
        WITH DESTINATION_TOPIC "crm/zendesk/tickets/show/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Updateticket
        WITH SOURCE_TOPIC "crm/zendesk/tickets/update"
        WITH DESTINATION_TOPIC "crm/zendesk/tickets/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/api/v2/tickets/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Listticketcomments
        WITH SOURCE_TOPIC "crm/zendesk/tickets/comments/list"
        WITH DESTINATION_TOPIC "crm/zendesk/tickets/comments/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/api/v2/tickets/{value.json.id}/comments"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Listtickets | GET | `/api/v2/tickets` | `crm/zendesk/tickets/list` | `crm/zendesk/tickets/list/response` |
| Createticket | POST | `/api/v2/tickets` | `crm/zendesk/tickets/create` | `crm/zendesk/tickets/create/response` |
| Showticket | GET | `/api/v2/tickets/{id}` | `crm/zendesk/tickets/show` | `crm/zendesk/tickets/show/response` |
| Updateticket | PUT | `/api/v2/tickets/{id}` | `crm/zendesk/tickets/update` | `crm/zendesk/tickets/update/response` |
| Listticketcomments | GET | `/api/v2/tickets/{id}/comments` | `crm/zendesk/tickets/comments/list` | `crm/zendesk/tickets/comments/list/response` |

## Auth

**OAuth 2.0 Bearer — default in the template:**

1. Create an OAuth client in Zendesk Admin for your Support account.
2. Obtain an `access_token`.
3. Set connector `BASE_ADDRESS` to `https://{subdomain}.zendesk.com`.
4. Pass `access_token` on the MQTT request payload so headers resolve:
   * `Authorization: Bearer {value.json.access_token}`
5. Store the token in Hub secrets / `GET SECRET`. Never commit real credentials.

**API token Basic (email/token):**

1. In Zendesk Admin, create an API token for an agent email.
2. Use Basic auth with username `{email}/token` and password = the API token.
3. Prefer `WITH USERNAME "agent@example.com/token"` and `WITH PASSWORD GET SECRET "ZENDESK_API_TOKEN"` on `REST_API_CONFIG` (remove Bearer header lines if using config Basic).

## Example payloads

**Create ticket from alarm:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "ticket": {
    "subject": "Line sensor fault — Zone A",
    "priority": "high",
    "type": "incident",
    "tags": ["iiot", "coreflux", "alarm"],
    "comment": {
      "body": "Vibration above threshold at 2026-10-04T00:00:00Z"
    }
  }
}
```

**Update with resolution:**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "id": 35436,
  "ticket": {
    "status": "solved",
    "comment": {
      "body": "Alarm cleared; sensor back online.",
      "public": true
    }
  }
}
```

**Add comment (catalog POST comments → PUT):**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "id": 35436,
  "ticket": {
    "comment": {
      "body": "Follow-up from Coreflux telemetry.",
      "public": false
    }
  }
}
```

## Deploy notes

* Deploy **`ZendeskSupportRestApi.lot` only** (`-addConnector`). Do **not** deploy `hub-metadata.lot` as a connector — it exists for Hub / `-listTemplates` (`ADD METADATA` + `WITH IMAGE` base64).
* Hub category: **REST API Connectors**.
* Doc link: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/zendesk-support](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/zendesk-support)

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


# Zoho CRM REST API
Source: https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/zoho-crm

Client-mode REST API connector for Zoho CRM v7 (Cases, Accounts, Deals, Tasks)

Technical Preview

## Overview

Client-mode REST API connector for Zoho CRM v7 (Cases, Accounts, Deals, Tasks). `BASE_ADDRESS` defaults to `https://www.zohoapis.com`. Auth: **OAuth 2.0 Bearer**. Pass secrets only at runtime via MQTT JSON placeholders or Hub `GET SECRET` — never commit real credentials.

## Auth

OAuth 2.0 Bearer. Prefer Hub secrets / `GET SECRET`. Never hard-code tokens into the `.lot`.

## Basic Syntax

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}

DEFINE CONNECTOR ZohoCrmRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://www.zohoapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Auth: Authorization Bearer {value.json.access_token} — prefer Hub secrets / GET SECRET.
        # Optional Basic: WITH USERNAME "YOUR_USER" / WITH PASSWORD GET SECRET "APP_PASSWORD"
    ADD EVENT Createcase
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Createcase"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Createcase"
        WITH METHOD "POST"
        WITH ENDPOINT "/crm/v7/Cases"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{payload}"
    ADD EVENT Listcases
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Listcases"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Listcases"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v7/Cases"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Updateaccount
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Updateaccount"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Updateaccount"
        WITH METHOD "PUT"
        WITH ENDPOINT "/crm/v7/Accounts/{value.json.id}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    # ... additional EVENTs in package .lot ...
```

## MQTT topics

Request topics under `integrations/zoho-crm/request/...`; responses on `integrations/zoho-crm/response/...`.

## Template reference

Generated from the shipped broker template `zoho-crm` (`-connectorCode ZOHO_CRM`). It lists every event the template defines.

### Auth

OAuth 2.0 Bearer

Auth headers used by the template: `Authorization: Bearer {value.json.access_token}`.

### Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Zoho CRM connector | no |
| `BaseUrl` | string | Zoho CRM base URL without trailing slash (e.g. [https://www.zohoapis.com](https://www.zohoapis.com)) | yes |

`BASE_ADDRESS` default: `https://www.zohoapis.com`.

### Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `Createcase` | POST | `/crm/v7/Cases` | `integrations/zoho-crm/request/Createcase` | `integrations/zoho-crm/response/Createcase` | `access_token`, `body` |
| `Listcases` | GET | `/crm/v7/Cases` | `integrations/zoho-crm/request/Listcases` | `integrations/zoho-crm/response/Listcases` | `access_token` |
| `Updateaccount` | PUT | `/crm/v7/Accounts/{value.json.id}` | `integrations/zoho-crm/request/Updateaccount` | `integrations/zoho-crm/response/Updateaccount` | `access_token`, `body`, `id` |
| `Getaccount` | GET | `/crm/v7/Accounts/{value.json.id}` | `integrations/zoho-crm/request/Getaccount` | `integrations/zoho-crm/response/Getaccount` | `access_token`, `id` |
| `Searchdeals` | GET | `/crm/v7/Deals/search?criteria={value.json.criteria}` | `integrations/zoho-crm/request/Searchdeals` | `integrations/zoho-crm/response/Searchdeals` | `access_token`, `criteria` |
| `Createtask` | POST | `/crm/v7/Tasks` | `integrations/zoho-crm/request/Createtask` | `integrations/zoho-crm/response/Createtask` | `access_token`, `body` |
| `Listcontacts` | GET | `/crm/v7/Contacts` | `integrations/zoho-crm/request/Listcontacts` | `integrations/zoho-crm/response/Listcontacts` | `access_token` |
| `Createlead` | POST | `/crm/v7/Leads` | `integrations/zoho-crm/request/Createlead` | `integrations/zoho-crm/response/Createlead` | `access_token`, `body` |

### Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-connectorCode ZOHO_CRM"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ZohoCrmRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://www.zohoapis.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Createcase
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Createcase"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Createcase"
        WITH METHOD "POST"
        WITH ENDPOINT "/crm/v7/Cases"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Listcases
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Listcases"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Listcases"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v7/Cases"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Updateaccount
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Updateaccount"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Updateaccount"
        WITH METHOD "PUT"
        WITH ENDPOINT "/crm/v7/Accounts/{value.json.id}"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Getaccount
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Getaccount"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Getaccount"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v7/Accounts/{value.json.id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Searchdeals
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Searchdeals"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Searchdeals"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v7/Deals/search?criteria={value.json.criteria}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createtask
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Createtask"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Createtask"
        WITH METHOD "POST"
        WITH ENDPOINT "/crm/v7/Tasks"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
    ADD EVENT Listcontacts
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Listcontacts"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Listcontacts"
        WITH METHOD "GET"
        WITH ENDPOINT "/crm/v7/Contacts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
    ADD EVENT Createlead
        WITH SOURCE_TOPIC "integrations/zoho-crm/request/Createlead"
        WITH DESTINATION_TOPIC "integrations/zoho-crm/response/Createlead"
        WITH METHOD "POST"
        WITH ENDPOINT "/crm/v7/Leads"
        WITH HEADERS
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.access_token}"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addConnector` (do not include `ADD METADATA`).

### Usage example

Call `Createcase` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'integrations/zoho-crm/response/Createcase' &
mosquitto_pub -t 'integrations/zoho-crm/request/Createcase' -m '{"access_token": "<access_token>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API apps index](/latest/lot-language/routes/rest-api-apps)


# RULE Overview
Source: https://docs.coreflux.org/latest/lot-language/rules/overview

Define access control, permissions, and governance rules for your MQTT infrastructure

## Securing Your Broker

Rules define **who can do what** in your Coreflux broker. They control access to system operations, topic publishing/subscribing, and administrative functions—ensuring only authorized users can perform sensitive actions.

> [!TIP]
>
> **Think of Rules like a security guard at a building entrance.** The guard checks your badge (permissions or group) and decides if you're allowed through the door (the operation). Rules do the same for every broker operation.

***

## When to Use Rules

| Scenario | Rule Type |
| - | - |
| Restrict who can create/delete users | User Management Rules |
| Control who deploys Actions, Models, Connectors | Entity Management Rules |
| Limit access to system configuration | System Configuration Rules |
| Secure MQTT topic access by user or group | Publish/Subscribe Rules + [RBAC](./rbac) |
| Protect administrative `$SYS` topics | System Topic Rules |

For groups, precedence (**lower priority number wins**), default rules, and Visu panel access, see [RBAC with LoT Rules](./rbac).

***

## In This Section

* [Rules Syntax](./syntax) — Conditions, scopes, and patterns
* [RBAC with LoT Rules](./rbac) — Groups, precedence, cookbook, Visu access

***

## How to Deploy a Rule

Rules can be deployed in two ways: through a **LoT Notebook** (recommended) or via **MQTT commands**.

> [!NOTE]
>
> Custom topic and management ACL rules (`-addRule`) require a **Growth or Enterprise** license. Shipped default rules always apply.

**LoT Notebook**

Write your rule definition in a code cell and run it—the extension detects `DEFINE RULE` and sends the proper command to the broker.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE Zone1Access WITH PRIORITY 100 FOR Subscribe TO TOPIC "zone1/#"
    IF USER IN GROUP "zone1-staff" THEN
        ALLOW
    ELSE
        DENY
```

> [!TIP]
>
> Click the **Run** button. The notebook recognizes the LoT code and deploys it instantly.

This approach is ideal for:

* Developing and testing rules interactively
* Documenting your security configuration alongside the code
* Sharing rule sets with your team as `.lotnb` files

**MQTT Command**

Deploy rules by publishing to the broker's command topic using any MQTT client.

**Topic:** `$SYS/Coreflux/Command`

**Payload:**

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addRule DEFINE RULE Zone1Access WITH PRIORITY 100 FOR Subscribe TO TOPIC "zone1/#"
    IF USER IN GROUP "zone1-staff" THEN
        ALLOW
    ELSE
        DENY
```

Subscribe to `$SYS/Coreflux/Command/Output` to receive the response confirming deployment.

***

## Removing Rules

Remove a rule by name using the `-removeRule` command. Publish to `$SYS/Coreflux/Command`:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-removeRule Zone1Access
```

> [!NOTE]
>
> You can also use the **Coreflux Entities** panel in VS Code to view and remove deployed rules. Locked built-in system rules cannot be removed.

***

## Updating Rules

To update an existing rule, deploy a new rule with the **same name**. The new definition replaces the existing one.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Original rule
DEFINE RULE Zone1Access WITH PRIORITY 100 FOR Subscribe TO TOPIC "zone1/#"
    IF USER IN GROUP "zone1-staff" THEN
        ALLOW
    ELSE
        DENY

-- Updated rule (same name, also allow supervisors)
DEFINE RULE Zone1Access WITH PRIORITY 100 FOR Subscribe TO TOPIC "zone1/#"
    IF USER IN GROUP "zone1-staff" OR USER IN GROUP "supervisors" THEN
        ALLOW
    ELSE
        DENY
```

***

## Viewing Active Rules

To see all deployed rules, subscribe to the rules system topic:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SUBSCRIBE "$SYS/Coreflux/Rules/#"
```

Or use the **Coreflux Entities** panel in VS Code if you have the LoT Notebooks extension installed.

***

## Default Rules Reference

Coreflux ships two tiers of defaults:

| Tier | Behavior |
| - | - |
| **Locked system rules** | Management gates and `$SYS` access in the reserved band (`0–99`) — cannot be removed or overridden |
| **Seed catch-alls** | Priority `1 000 000` allow-all for connect, publish, and subscribe so clients keep working; the weakest band, so any custom rule overrides them |
| **Root backstop** | `root` can always recover command and rule management access |

Custom rules use priorities from `100` to `1 000 000`. **Lower priority number wins**; ties deny-wins; no match means deny. Details: [RBAC with LoT Rules](./rbac).

***

## Next Steps

> **[RBAC with LoT Rules](/latest/lot-language/rules/rbac)**
>
> Groups, precedence, cookbook, and Visu panel access.

> **[Rules Syntax](/latest/lot-language/rules/syntax)**
>
> Conditions, scopes, and complete rule patterns.


# RBAC with LoT Rules
Source: https://docs.coreflux.org/latest/lot-language/rules/rbac

Role-based access control with user groups, LoT Rules, permission flags, and Visu panel access

## Control Who Can Do What

Role-based access control (RBAC) in Coreflux combines **user groups**, **LoT Rules**, **permission flags**, and optional **Visu panel** sharing so you can lock down topics, management operations, and dashboards without external ACL servers.

> [!TIP]
>
> **Like badge groups in a factory.** Operators get a badge that opens production doors; supervisors get a badge that also opens the emergency-stop cabinet. Groups name the badges; Rules decide which doors each badge opens.

### When to Use This Guide

| Goal | Use |
| - | - |
| Restrict MQTT publish/subscribe by role | Groups + `DEFINE RULE` with `USER IN GROUP` |
| Gate who can create users, connectors, or rules | Permission flags + management scopes |
| Hide or lock Visu panels/controls | `WITH SHARE TO GROUP` / `WITH INTERACT FOR GROUP` |
| Understand which rule wins | Precedence model below |

> [!NOTE]
>
> Adding custom topic or management ACL rules (`-addRule`) requires a **Growth or Enterprise** license. Shipped default rules always apply. Group membership commands and permission flags are available on all tiers.

***

Write rules with correct layout and conditions in [Rules Syntax](./syntax), then return here for groups, precedence, and operator patterns.

## User Groups

Each broker user can belong to one or more named groups. Group names are **case-insensitive** at evaluation time (`"Operators"` and `"operators"` match the same group). Prefer kebab-case or lowercase identifiers without spaces (`zone1-staff`, not `Zone 1 Staff`).

Groups are created by naming them — assign a user to a group and reference that name in rules or Visu clauses.

### Manage Groups via MQTT

Publish to `$SYS/Coreflux/Command` from a session authorized for user management (`AllowedUserManagement`, `AllowedSystemConfiguration`, or `root`). The requesting identity is the **authenticated MQTT session** — do not pass a requester in the payload.

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addUserToGroup alice operators
-removeUserFromGroup alice operators
-listUserGroups alice
```

Responses arrive on `$SYS/Coreflux/Command/Output`. See [Broker Commands](/latest/mqtt-broker/commands) for the full command set.

***

## Rule Precedence

**Lower priority number wins.** This is the same convention as BACnet write priority and ISA-18.2 alarm priority: the lower the number, the stronger the statement. The very strongest numbers are reserved for the broker's own rules, so `100` is the strongest priority you can write.

For a given operation (and topic, for topic operations), the broker considers only the rules with the **lowest** priority number among those that match. A rule **never abstains** — if an `IF` has no `ELSE`, a false condition returns the opposite verdict (`IF … THEN ALLOW` denies everyone else; `IF … THEN DENY` allows everyone else). Within that winning band:

* If **any** matching rule evaluates to **DENY**, the operation is denied (**deny-wins**)
* Otherwise, if a rule allows, the operation is allowed
* If **no** rule matches at all, the operation is **denied** (default-deny)

Weaker (higher-numbered) rules are consulted only where no stronger rule matches the topic—never as a fallback when a stronger rule's `IF` condition was false.

| Priority | Use case |
| - | - |
| `0–99` | **Reserved** for locked system rules — rejected for user/project rules |
| `100` | The strongest rule you can write — use it for the most specific case |
| `100–999 999` | The user band. Layer exceptions by stepping *down* toward `100` as rules get more specific |
| `1 000 000` | Shipped permissive catch-alls (`AllowPublishTopic` / `AllowSubscribeTopic` / `AllowConnect`) — the weakest band |
| `> 1 000 000` | **Rejected** — weaker than the catch-alls, so the rule could never apply |

Because the catch-alls sit at the weakest priority `1 000 000`, **any** rule you add in the user band overrides them for its topic (or, for Connect, for the whole connection). You do not need to remove or reprioritise a built-in to deny (or further allow) a topic.

> [!TIP]
>
> **Start broad rules high — you can only carve out downwards.** An exception needs a *lower* number than the rule it overrides, and `100` is the floor of the user band. Give a namespace-wide rule a large number (`1000`, or higher if you expect several layers) and keep `100` for the most specific case. A broad rule placed at `100` leaves no room to carve out later without renumbering what is already deployed.

> [!WARNING]
>
> Prefer distinct priorities, or combine conditions with `OR` in one rule. Same-priority ties resolve **deny-wins**.

### Layout requirements

The LoT lexer is indentation-sensitive (one level = 4 spaces):

* Keep the full header on **one line**: `DEFINE RULE Name WITH PRIORITY n FOR …`
* Put each `IF` / `ELSE` / `ALLOW` / `DENY` on its own line (a single-line `THEN ALLOW ELSE DENY` body is rejected)
* Omitting `ELSE` is valid: a rule never abstains, so when the condition is false it returns the opposite verdict (`THEN DENY` allows everyone else, and `THEN ALLOW` denies everyone else in that winning band). An explicit `ELSE` is still the clearer form.
* Rule names are bare identifiers — **no quotes** around the rule name

```lot wrap focus={2-5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE Zone1Access WITH PRIORITY 100 FOR Subscribe TO TOPIC "zone1/#"
    IF USER IN GROUP "zone1-staff" THEN
        ALLOW
    ELSE
        DENY
```

***

## What a denied client sees

A denied publish or subscribe does not go through. On MQTT 5, a QoS 1 or 2 publish that a rule denies is acknowledged with reason code `0x87` (**Not authorized**) in PUBACK or PUBREC. The same publish used to be acknowledged as Success, so the client could not tell the rule had blocked it.

| Situation | What the client receives |
| - | - |
| MQTT 5 publish, QoS 1 or 2, denied by a rule | PUBACK or PUBREC reason code `0x87` Not authorized |
| Subscribe denied by a rule | SUBACK reason code `0x87` Not authorized |
| QoS 0 publish, or a publish from an MQTT 3.1.1 client | The message is dropped and acknowledged as before |

***

## Quick Start

**Restrict a topic to a group**

Only members of `operators` may publish commands under `machines/+/cmd`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE OperatorControl WITH PRIORITY 100 FOR Publish TO TOPIC "machines/+/cmd"
    IF USER IN GROUP "operators" THEN
        ALLOW
    ELSE
        DENY
```

**Allow multiple groups**

Supervisors or operators may subscribe to production topics:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE SupOrOp WITH PRIORITY 100 FOR Subscribe TO TOPIC "production/#"
    IF USER IN GROUP "supervisors" OR USER IN GROUP "operators" THEN
        ALLOW
    ELSE
        DENY
```

**Layer deny then allow**

Deny a config subtree at a coarse priority, then carve out one leaf for supervisors at a stronger (lower) one:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE DenyConfig WITH PRIORITY 1000 FOR Publish TO TOPIC "site/config/#"
    DENY
DEFINE RULE AllowSetpt WITH PRIORITY 100 FOR Publish TO TOPIC "site/config/setpoint"
    IF USER IN GROUP "supervisors" THEN
        ALLOW
    ELSE
        DENY
```

Deploy with `-addRule <definition>` on `$SYS/Coreflux/Command`, or run the cell in a [LoT Notebook](/latest/quick-start/vscode). Remove with `-removeRule <RuleName>`.

***

## Access-Control Cookbook

### Deny a whole subtree

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE DenyRawArea WITH PRIORITY 100 FOR Publish TO TOPIC "factory/raw/#"
    DENY
```

Beats the weakest-band publish catch-all (priority `1 000 000`) for `factory/raw/#`; other topics still fall through to the default allow.

### Restrict a topic to named users

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE ControlWriters WITH PRIORITY 100 FOR Publish TO TOPIC "line1/control/#"
    IF USER IS "operator1" OR USER IS "operator2" THEN
        ALLOW
    ELSE
        DENY
```

### Gate by permission flag

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE DiagnosticsReaders WITH PRIORITY 100 FOR Subscribe TO TOPIC "diagnostics/#"
    IF USER HAS AllowedSystemConfiguration OR USER IS "root" THEN
        ALLOW
    ELSE
        DENY
```

### Confine a device to its own topic subtree

Use `CLIENTID` and `TOPIC POSITION n` (1-based) so each device can only publish or subscribe under its own identifier:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE OwnDeviceSubtree WITH PRIORITY 100 FOR Subscribe TO TOPIC "devices/#"
    IF CLIENTID IS TOPIC POSITION 2 THEN
        ALLOW
    ELSE
        DENY
```

### Gate on a retained or cached allow-list topic

Combine `CLIENTID` with `TOPIC EXISTS` (MQTT retained messages) or `GET TOPIC` (live `KEEP TOPIC` / `PUBLISH TOPIC` cache with retained fallback) to admit only provisioned devices:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE ProvisionedDevices WITH PRIORITY 100 FOR Connect
    IF CLIENTID MATCHES REGEX "^gpay[0-9]{15}$" AND GET TOPIC "coreflux/devices/" + CLIENTID + "/allowed" THEN
        ALLOW
    ELSE
        DENY
```

### Switch a namespace toward default-deny

Blanket-deny at a coarse priority, then allow only what you intend at a stronger (lower) one:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE DenyAllPub WITH PRIORITY 1000 FOR Publish TO TOPIC "#"
    DENY
DEFINE RULE AllowApp WITH PRIORITY 100 FOR Publish TO TOPIC "app/#"
    ALLOW
```

Alternatively, remove the removable publish seed (`-removeRule AllowPublishTopic`) so unmatched publishes fall through to default-deny. Locked system rules and the root backstop still protect recovery. Restore the three shipped seeds later with [`-restoreRules`](/latest/mqtt-broker/commands#restoring-seeded-rules). Do **not** expect `-removeRule AllowConnect` alone to lock CONNECT — see [Connection admission](#connection-admission).

### Precedence walk-through

The table reads top-down in precedence order — the first band that matches decides:

| Rule | Priority | Topic | Decision |
| - | - | - | - |
| `AllowSensors` | 100 | `plant/sensors/#` | ALLOW |
| `DenyArea` | 1 000 | `plant/#` | DENY |
| `AllowPublishTopic` (built-in) | 1 000 000 | `#` | ALLOW |

* Publish to `office/x` → only the catch-all matches → **ALLOW**
* Publish to `plant/motor` → strongest match is `DenyArea` (1 000) → **DENY**
* Publish to `plant/sensors/t1` → strongest match is `AllowSensors` (100) → **ALLOW**

***

## Permission Flags vs Groups

| Mechanism | What it is for |
| - | - |
| **Permission flags** | Coarse system access — checked with `USER HAS` |
| **Groups** | Fine-grained topic and panel access — checked with `USER IN GROUP` |

| Flag | Gates |
| - | - |
| `AllowedSystemConfiguration` | System config, creating connectors/models/actions, many admin paths |
| `AllowedUserManagement` | User CRUD and group membership commands |
| `AllowedLogManagement` | Log access |

Set a flag via MQTT:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-changeUserSettings alice AllowedUserManagement true
```

In Coreflux HUB User Management, **Full Access** maps to `AllowedSystemConfiguration`; **User Management** and **Log Management** map to the matching flags. Manage groups with the MQTT commands above (see also [User Management](/hub/system/user-management)).

| Scenario | Prefer |
| - | - |
| Can this user create LoT actions? | Permission flag |
| Can this user see Zone 1 data/panels? | Group + rule / Visu share |
| Can this user manage other users? | `AllowedUserManagement` |

`USER IN GROUP`, `USER IS` / `USER EQUALS`, and `USER HAS` also work inside LoT Action bodies (for topic-triggered actions). Scheduled actions (`ON EVERY` / `ON START`) have no triggering user — group checks return false there.

***

## Default Rules and System Access

### Locked system rules

Management gates (`CommandCall`, user/rule/connector/action management, and so on) and `$SYS` access rules are **locked** built-ins in the reserved band (`0–99`) — the strongest priorities on the number line. They cannot be removed, cannot be overridden by a same-named rule, and outrank every user rule (which are floored at `100`), so no rule you write can revoke admin access and lock the broker.

The band is split the same way user rules are — more specific means a lower number: base locked rules sit at `10`, and more-specific `$SYS` carve-outs at `1`.

The flip side of that protection: a custom rule on a management scope, or on `$SYS/#` subscribe, never decides either — the locked rule always forms the winning band. Adjust those with permission flags instead. See [Operation Scopes](./syntax#operation-scopes).

### Seed catch-alls

Three permissive defaults sit at priority `1 000 000` — the weakest possible band — so MQTT clients keep working out of the box while losing to every rule an operator writes:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE AllowPublishTopic WITH PRIORITY 1000000 FOR Publish TO TOPIC "#"
    ALLOW
DEFINE RULE AllowSubscribeTopic WITH PRIORITY 1000000 FOR Subscribe TO TOPIC "#"
    ALLOW
DEFINE RULE AllowConnect WITH PRIORITY 1000000 FOR Connect
    ALLOW
```

These are the only defaults an operator may remove or replace via MQTT. To change a seed catch-all's body, `-removeRule` it and then `-addRule` your replacement — rule names must be unique. Project merges skip every built-in name — including these seeds — so redefine them with MQTT commands, not project files.

To put the three seeds back (including resetting an override of those names to the shipped ALLOW body), run [`-restoreRules`](/latest/mqtt-broker/commands#restoring-seeded-rules). That command requires `root` or `AllowedSystemConfiguration` and does not require an RBAC license. Locked built-ins and your other custom rules are left alone.

Loading or unloading a project keeps locked built-ins and operator-authored rules. Only rules the broker attributes to the outgoing project are removed.

### Connection admission

A rule written `FOR Connect` decides whether the broker accepts an MQTT CONNECT after authentication succeeds. Connect rules take no `TO TOPIC` clause. Any user-band Connect rule (`100`–`999 999`) outranks `AllowConnect`. Connect rules can check `USER`, `CLIENTID`, `ENDPOINT` (the client's `ip:port`), `TOPIC EXISTS`, and `GET TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE DenyGuestConnect WITH PRIORITY 100 FOR Connect
    IF USER IS "guest" THEN
        DENY

DEFINE RULE OfficeSubnetOnly WITH PRIORITY 200 FOR Connect
    IF ENDPOINT MATCHES REGEX "^10\.4\.\d+\.\d+:" THEN
        ALLOW
    ELSE
        DENY
```

A rule set with **no** `Connect` rule at all leaves CONNECT ungated — that is how upgrades from brokers that had no Connect operation keep accepting clients. `-removeRule AllowConnect` without adding a replacement therefore does **not** lock the door. To control who may connect, add an explicit `FOR Connect` policy. `root` remains admitted by the anti-lockout backstop.

### Federated accounts

A client that connects with an [OIDC access token](/latest/mqtt-broker/oidc-authentication) is not in the local user store. `USER IS` matches the token subject (`sub` by default). `USER IN GROUP` matches group names carried on the token for this broker's organization, without the organization prefix. Permission flags stay off unless `Oidc.AdminRoles` or `Oidc.AdminGroups` names that role or group — then the session receives `AllowedSystemConfiguration`, `AllowedUserManagement`, and `AllowedLogManagement`. Both lists are empty by default.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE EngineersPublish WITH PRIORITY 200 FOR Publish TO TOPIC "plant/status/#"
    IF USER IN GROUP "engineers" THEN
        ALLOW
    ELSE
        DENY
```

The display name on the token is for logs only. A rule cannot match it. Token groups and local groups do not grant each other. A role or group change applies the next time the client connects with a new token.

### Rejected priorities

`-addRule` and project rule merges reject both ends of the number line, and report the reason per rule:

| Priority | Result |
| - | - |
| `0–99` | **Rejected** — nothing user-defined may tie with or outrank a locked system rule |
| `100–999 999` | Accepted — the user band |
| `1 000 000` | Accepted, so you can re-add a replaced catch-all in its own band |
| `> 1 000 000` | **Rejected** — weaker than the catch-alls, so the rule would never be consulted and would silently fail open |

### Root anti-lockout

Independently of all rules, `root` can always connect, run commands, manage rules, and reach `$SYS/Coreflux/Command` and `$SYS/Coreflux/Command/Output`.

### Upgrade note

**Review any custom rule that used the `1–99` range.** That band is now reserved for locked system rules, so such rules are **clamped to `100`** when the broker loads them (each clamp is logged with its old and new priority). Clamping keeps them in force and keeps them from outranking the locked safety rules, but several rules that used to be distinct can land on `100` together — where ties resolve **deny-wins**. Re-space them deliberately across the user band, putting the *more specific* rule at the *lower* number.

Locked built-ins are rewritten to their canonical definitions and priorities on every start, and a seed catch-all you kept has its body preserved but its priority normalized to `1 000 000`. A seed you deliberately removed stays removed. Fresh brokers also ship `AllowConnect` at `1 000 000`; see [Connection admission](#connection-admission).

***

## Visu Panel RBAC

LoTV panels can restrict who sees content and who can interact with controls.

### Visibility

```lot wrap focus={4-5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL "Zone1Control"
    WITH TITLE "Zone 1 Control"
    WITH VISIBILITY SHARED
    WITH SHARE TO GROUP "zone1-staff"
    WITH SHARE TO GROUP "supervisors"
    WITH STATE PUBLISHED
```

Published shared panels generate Layer 1 subscribe rules so only listed groups (or users via `WITH SHARE TO USER`) receive the panel. Others do not see it in `$Visu/Catalog`.

### Interaction

| Keyword | Who can interact |
| - | - |
| `WITH INTERACT PUBLIC` | Any client who can view the panel |
| `WITH INTERACT FOR GROUP "<g>"` | Members of group `<g>` |
| `WITH INTERACT FOR USER "<u>"` | Named user `<u>` |
| *(omitted)* | View-only — no Interact topic |

Stack multiple `FOR GROUP` lines or multiple `FOR USER` lines. Do **not** mix `FOR GROUP` and `FOR USER` on the same component — only the last scope is enforced. Put named users into a group when both are needed.

Denial modes: `WITH INTERACT_DENY SILENT` (default) or `WITH INTERACT_DENY NOTIFY` (publishes to `$Visu/Session/<id>/Denied`).

### Two-layer enforcement

| Layer | What |
| - | - |
| Layer 1 | MQTT subscribe/publish to `$Visu` topics from panel visibility |
| Layer 2 | Runtime check of `WITH INTERACT FOR GROUP` / `FOR USER` per interaction |

***

## Best Practices

* Start from the shipped defaults; every rule you add already overrides the catch-alls for its topic
* Give namespace-wide rules a coarse number (`1000` or higher) and reserve `100` for the most specific carve-outs
* Prefer groups over hard-coded usernames for topic and panel access
* Keep rule headers on one line; use consistent 4-space indentation
* Keep custom priorities inside the user band (`100`–`1 000 000`)
* Document who owns each group name in your operations runbook

> [!WARNING]
>
> Never attempt to override locked system rules or rely on removing `root` protections. The reserved priority band and root backstop exist so the broker remains recoverable.

***

## Next Steps

> **[Rules Syntax](/latest/lot-language/rules/syntax)**
>
> Conditions, operation scopes, and complete rule patterns.

> **[Broker Commands](/latest/mqtt-broker/commands)**
>
> Group, user, and rule management command reference.


# RULE Syntax
Source: https://docs.coreflux.org/latest/lot-language/rules/syntax

Complete reference for LoT rule syntax, conditions, operation scopes, and access control patterns

## Write Your Broker's Access Policy

Every broker operation—creating users, deploying Actions, publishing to topics—passes through Rules before it executes. This page is the complete syntax reference for writing those rules: the conditions you can check, the scopes you can target, and the patterns that tie them together.

> [!TIP]
>
> **Like writing house rules on a whiteboard.** Each rule says "IF you are on the approved list, THEN you may enter the room—ELSE the door stays locked." LoT rule syntax works the same way: you name the rule, pick the door (scope), and write the condition.

### When You Need This Reference

| Scenario | You'll use |
| - | - |
| Restricting who can create or delete users | User Management scopes |
| Controlling who deploys Actions, Models, or Connectors | Entity Management scopes |
| Locking down MQTT topic access per user or group | Publish / Subscribe scopes with `TO TOPIC` |
| Protecting `$SYS` command topics | System topic scopes |
| Building role-based access across teams | Groups with `USER IN GROUP` — see [RBAC](./rbac) |

> [!NOTE]
>
> **Deploying rules:** In a [LoT Notebook](/latest/quick-start/vscode), write the rule and run the cell. For MQTT clients, use `-addRule` ([broker commands](/latest/mqtt-broker/commands#rules)). Custom ACL rules require a Growth or Enterprise license.

***

## Rule Structure

Every rule follows this structure:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE <RuleName> WITH PRIORITY <number> FOR <Scope> [TO TOPIC "<pattern>"]
    IF <condition> THEN
        ALLOW
    ELSE
        DENY
```

| Component | Description |
| - | - |
| `RuleName` | Bare identifier (letters, digits, underscores) — **do not quote** the name |
| `PRIORITY` | Integer `100`–`1 000 000`; **lower number wins** among matching rules (see [Priority and Evaluation](#priority-and-evaluation)) |
| `Scope` | The operation type this rule controls |
| `TO TOPIC` | Optional topic pattern for Publish/Subscribe (and `$SYS` variants) |
| `condition` | Logic that determines access (user, group, permission flags, `CLIENTID`, `ENDPOINT`, `TOPIC POSITION`, `TOPIC EXISTS`, `GET TOPIC`) |

> [!WARNING]
>
> Keep the entire header on **one line**. Indent the body one level (4 spaces); nest `ALLOW`/`DENY` under `IF`/`ELSE` another level. A single-line `THEN ALLOW ELSE DENY` body is rejected.

Unconditional forms are valid too:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE OpenPublic WITH PRIORITY 100 FOR Subscribe TO TOPIC "public/#"
    ALLOW
```

***

## Conditions

Rules evaluate conditions to decide whether to ALLOW or DENY an operation.

### User Identity Checks

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
USER IS "root"
USER EQUALS "alice"
```

### Group Membership

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
USER IN GROUP "operators"
USER IN GROUP "zone1-staff"
```

Group lookup is case-insensitive. See [RBAC with LoT Rules](./rbac) for group management commands and patterns.

### Permission Flags

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
USER HAS AllowedUserManagement
USER HAS AllowedSystemConfiguration
USER HAS AllowedLogManagement
```

These are the three broker permission flags. Prefer groups for fine-grained topic access rather than inventing custom flag names.

### Client Identity and Endpoint

Rules can inspect the MQTT session's client identifier and network endpoint:

| Keyword | Returns | Where populated |
| - | - | - |
| `CLIENTID` (alias `CLIENT`) | MQTT client ID string | Every session-backed scope (`Connect`, `Publish`, `Subscribe`, `CommandCall`, management scopes) |
| `ENDPOINT` | Remote client address (`ip:port`) | `Connect` |

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE OfficeSubnetOnly WITH PRIORITY 100 FOR Connect
    IF ENDPOINT MATCHES REGEX "^10\.4\.\d+\.\d+:" THEN
        ALLOW
    ELSE
        DENY
```

`CLEANSESSION`, `SUBSCRIBETOPIC`, `SUBSCRIBEQOS`, and `DISCONNECTREASON` also parse in rule conditions (`CLEANSESSION` returns `"true"` or `"false"`, `SUBSCRIBEQOS` returns an integer), though they are primarily populated for [lifecycle action triggers](/latest/lot-language/actions/events#client-lifecycle-triggers).

### Topic Segments (`TOPIC POSITION`)

On topic scopes (`Publish`, `Subscribe`, `PublishSys`, `SubscribeSys`), `TOPIC POSITION n` extracts the 1-based segment *n* of the topic being checked. Use it to bind a client to its own topic subtree:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE OwnDeviceSubtree WITH PRIORITY 100 FOR Publish TO TOPIC "devices/#"
    IF CLIENTID IS TOPIC POSITION 2 THEN
        ALLOW
    ELSE
        DENY
```

With this rule, client `sensor-1` may publish to `devices/sensor-1/telemetry` (position 2 is `"sensor-1"`) and is denied on `devices/sensor-2/telemetry`.

### Topic State (`TOPIC EXISTS` and `GET TOPIC`)

Rules can gate access on broker topic state—for example, a per-device provisioning or allow-list topic built dynamically from `CLIENTID`:

| Expression | Evaluates to true when | Source checked |
| - | - | - |
| `TOPIC EXISTS <expr>` | The topic holds an MQTT **retained** message (any non-empty payload) | MQTT retained store only (`KEEP TOPIC` is not checked) |
| `TOPIC EXISTS <expr> IS "<val>"` | The retained payload equals `<val>` | MQTT retained store |
| `GET TOPIC <expr> IS "<val>"` | The stored payload equals `<val>` | Live broker cache (`KEEP TOPIC` or `PUBLISH TOPIC`), falling back to MQTT retained |
| `GET TOPIC <expr>` | The stored payload is truthy (`"true"`, `"1"`, `"yes"`, `"on"`, or a non-zero number; missing or empty is false) | Live broker cache, falling back to MQTT retained |

Bare `TOPIC EXISTS` checks presence only, so a retained payload of `"false"` still satisfies it. Compare against a value (or use `GET TOPIC`) when the payload itself is the allow/deny flag:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE ProvisionedDevices WITH PRIORITY 100 FOR Connect
    IF CLIENTID MATCHES REGEX "^sensor-\d+$" AND GET TOPIC "allowlist/" + CLIENTID + "/enabled" IS "true" THEN
        ALLOW
    ELSE
        DENY
```

> [!NOTE]
>
> Permission checks have no side effects: unlike `GET TOPIC` in an Action, evaluating `GET TOPIC` inside a rule does not subscribe to or start tracking a missing topic. Write the allow-list value (via `KEEP TOPIC` or a retained publish) before the client requests access.

### MATCHES REGEX

`REGEX` is required. Plain `MATCHES` tests equality. Negate a pattern with `NOT MATCHES REGEX`.

Backslash escapes such as `\d`, `\w`, `\s`, and `\.` reach the regex engine as written, the same way they do in [`FILTER … USING REGEX`](/latest/lot-language/actions/operations#filter). Use `\"` for a double quote inside the pattern. Anchor with `^` and `$` when the whole value must match. An invalid pattern evaluates to false and the broker logs an error. The same operators work in an action `IF`.

Allow only client ids shaped like `sensor-1`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE SensorClients WITH PRIORITY 200 FOR Connect
    IF CLIENTID MATCHES REGEX "^sensor-\d+$" THEN
        ALLOW
    ELSE
        DENY
```

Character classes such as `[0-9]` still work.

### Combining Conditions

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
IF USER HAS AllowedUserManagement OR USER IS "root" THEN
    ALLOW

IF USER IN GROUP "supervisors" AND USER EQUALS "alice" THEN
    ALLOW
```

### Implicit `ELSE` (Rules Never Abstain)

Omitting `ELSE` is valid, but a rule **never abstains**. Every rule in the winning priority band returns either `ALLOW` or `DENY` for every matching request: when the `IF` condition is false and there is no `ELSE`, the rule automatically returns the **opposite** verdict of its `THEN` branch:

* `IF <condition> THEN ALLOW` (no `ELSE`) compiles with an implicit `ELSE DENY` — anyone not matching `<condition>` is **denied** at that priority band.
* `IF <condition> THEN DENY` (no `ELSE`) compiles with an implicit `ELSE ALLOW` — anyone not matching `<condition>` is **allowed** at that priority band.
* An `IF … ELSE IF …` chain without a final `ELSE` likewise returns the opposite of the branch verdict when no condition matches.

Because the winning priority band decides the request and lower-priority bands are not consulted once a stronger band matches, an `IF … THEN ALLOW` rule at priority `100` denies all other users on that topic—it does not fall through to a priority `1000` rule. Combine multiple allowed principals with `OR` in a single rule, or use explicit `ELSE` branches to keep the behavior unmistakable:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE DenyDashboardPublish WITH PRIORITY 120 FOR Publish TO TOPIC "factory/#"
    IF USER IS "dashboard" THEN
        DENY
```

***

## Operation Scopes

Rules control different categories of operations. They split into two groups that behave very differently in practice.

**Topic scopes** — `Publish`, `Subscribe`, `PublishSys`, `SubscribeSys` — are the scopes you write rules for. The only built-ins that compete with you are the permissive catch-alls in the weakest band, so your rules decide.

**Connect** — `FOR Connect` decides whether the broker accepts an MQTT CONNECT after authentication. It takes no `TO TOPIC` clause. See [Connection admission](./rbac#connection-admission).

**Management scopes** — everything below — are already covered by locked built-in rules in the reserved band (`0–99`) that key off [permission flags](#permission-flags). Because your rules are floored at `100` and only the lowest-numbered matching band decides, a rule you write on a management scope is **never** the deciding band.

> [!WARNING]
>
> Do not try to tighten or loosen a management gate with a custom rule. The locked built-in always wins, and `-addRule` rejects both a priority below `100` and any attempt to reuse a built-in rule name. Change who can perform these operations by setting **permission flags** with `-changeUserSettings` instead.

The tables below name each scope and the flags its locked built-in accepts. In every case `root` is also accepted.

### User Management

| Scope | Controls | Built-in gate accepts |
| - | - | - |
| `UserManagementCreation` | Creating new users | `AllowedUserManagement`, `AllowedSystemConfiguration` |
| `UserManagementRemove` | Deleting users | `AllowedUserManagement`, `AllowedSystemConfiguration` |
| `UserManagementUpdate` | Modifying user settings and group membership | `AllowedUserManagement`, `AllowedSystemConfiguration` |
| `UserManagementPasswordChange` | Changing user passwords | `AllowedUserManagement`, `AllowedSystemConfiguration` |

### Entity Management

| Scope | Controls | Built-in gate accepts |
| - | - | - |
| `ActionManagementCreation` | Creating Actions and panels | `AllowedSystemConfiguration`, `admin` |
| `ActionManagementRemove` | Deleting Actions and panels | `AllowedSystemConfiguration`, `admin` |
| `ActionManagementRun` | Manually running Actions | `AllowedSystemConfiguration`, `admin` |
| `ModelManagementCreation` | Creating Models | `AllowedSystemConfiguration`, `admin` |
| `ModelManagementRemove` | Deleting Models | `AllowedSystemConfiguration`, `admin` |
| `ConnectorManagementCreation` (alias `RouteManagementCreation`) | Creating Connectors | `AllowedSystemConfiguration`, `admin` |
| `ConnectorManagementRemove` (alias `RouteManagementRemove`) | Deleting Connectors | `AllowedSystemConfiguration`, `admin` |
| `AgentManagementCreation` | Creating agents (`-addAgent`) | `AllowedSystemConfiguration`, `admin` |
| `AgentManagementRemove` | Deleting agents (`-removeAgent`) | `AllowedSystemConfiguration`, `admin` |
| `ThingManagementCreation` | Adding Things (`-addThing`) | `AllowedSystemConfiguration`, `admin` |
| `ThingManagementRemove` | Removing Things (`-removeThing`) | `AllowedSystemConfiguration`, `admin` |
| `RuleManagementCreation` | Creating Rules (`-addRule`) | `AllowedSystemConfiguration` |
| `RuleManagementRemove` | Deleting Rules (`-removeRule`) | `AllowedSystemConfiguration` |

`RouteManagementCreation` and `RouteManagementRemove` remain supported aliases of the Connector scopes. A rule written with either spelling governs the same commands (`-addConnector` / `-addRoute`, `-removeConnector` / `-removeRoute`).

### System Operations

| Scope | Controls | Built-in gate accepts |
| - | - | - |
| `SystemConfiguration` | Changing broker configuration | `AllowedSystemConfiguration` |
| `McpTokenManagement` | Creating, listing, and revoking MCP bearer tokens | `AllowedUserManagement`, `AllowedSystemConfiguration` |
| `ShellCommand` | Executing shell commands | `AllowedSystemConfiguration` |
| `CommandCall` | Calling broker commands via `$SYS/Coreflux/Command` | `AllowedUserManagement`, `AllowedSystemConfiguration`, `admin` |

### Log Management

| Scope | Controls | Built-in gate accepts |
| - | - | - |
| `LogManagementCreation` | Creating log traces | `AllowedLogManagement`, `AllowedSystemConfiguration` |
| `LogManagementRemove` | Deleting log traces | `AllowedLogManagement`, `AllowedSystemConfiguration` |
| `LogManagementUpdate` | Modifying log traces | `AllowedLogManagement`, `AllowedSystemConfiguration` |

***

## Topic Access Rules

### Standard Topics

Use `Publish` and `Subscribe` with `TO TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE OperatorPublish WITH PRIORITY 100 FOR Publish TO TOPIC "machines/+/cmd"
    IF USER IN GROUP "operators" THEN
        ALLOW
    ELSE
        DENY
```

The broker ships catch-alls at the weakest priority (`1 000 000`) that allow all connect, publish, and subscribe. Any rule you add in the user band already outranks them for its topic — see [RBAC](./rbac).

### System Topics (`$SYS`)

`$SYS` topics use the `PublishSys` and `SubscribeSys` scopes. Most of this namespace is already locked down for you:

| Path | Coverage |
| - | - |
| `SubscribeSys` on `$SYS/#` | Locked built-in — admins only. Cannot be tightened or loosened by a custom rule |
| `PublishSys` on the broker's own command and management topics | Locked built-ins — flag-gated |
| `PublishSys` on any other `$SYS` subtree | No built-in, so **default-deny**. A rule you write is the only candidate and decides |

Because the locked `$SYS` rules sit in the reserved band, a custom rule for `$SYS/#` subscribe never decides. Write `PublishSys` rules only for subtrees the built-ins do not already cover:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE AppStatusWriters WITH PRIORITY 100 FOR PublishSys TO TOPIC "$SYS/MyApp/#"
    IF USER IN GROUP "app-services" THEN
        ALLOW
    ELSE
        DENY
```

> [!WARNING]
>
> System topics (`$SYS/#`) contain sensitive broker information and command interfaces. Rely on the locked built-ins rather than writing your own `$SYS` subscribe rules, and never grant `$SYS` access to untrusted clients.

***

## Permission Flags

| Permission Flag | Grants Access To |
| - | - |
| `AllowedUserManagement` | User creation, removal, updates, group membership |
| `AllowedSystemConfiguration` | System config, many entity management paths, shell/admin |
| `AllowedLogManagement` | Log trace creation, removal, updates, read |

Assign flags with `-changeUserSettings` or in [Coreflux HUB User Management](/hub/system/user-management) (Full Access → `AllowedSystemConfiguration`).

***

## Priority and Evaluation

**Lower priority number wins** — the same convention as BACnet write priority and ISA-18.2 alarm priority. Among rules that match the operation (and topic), only the lowest-numbered band decides:

1. If any rule in that band evaluates to **DENY** → deny (**deny-wins**)
2. Else if any allows → allow
3. If **no** rule matches → **deny** (default-deny)

A rule never abstains: if its `IF` has no `ELSE`, a false condition returns the opposite verdict (`IF … THEN ALLOW` returns `DENY` for non-matching requests in that band). Weaker priority bands are only consulted when no rule at a stronger priority matches the operation and topic.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-- Strongest band for this topic (100) decides first
DEFINE RULE AllowSensors WITH PRIORITY 100 FOR Publish TO TOPIC "plant/sensors/#"
    ALLOW

DEFINE RULE DenyPlant WITH PRIORITY 1000 FOR Publish TO TOPIC "plant/#"
    DENY
```

| Priority band | Guideline |
| - | - |
| `0–99` | Reserved for locked system rules — rejected for your rules |
| `100` | The strongest rule you can write — keep it for the most specific case |
| `100–999 999` | The user band; step *down* toward `100` as rules get more specific |
| `1 000 000` | Shipped connect/publish/subscribe catch-alls — the weakest band |
| `> 1 000 000` | Rejected — weaker than the catch-alls, so the rule could never apply |

> [!TIP]
>
> Use a **lower** priority number than the rule you intend to override. Because the seed catch-alls sit at `1 000 000`, any rule in the user band is already enough to restrict a subtree — start broad rules at `1000` or higher so you have room to carve out exceptions later.

For cookbook patterns, Visu RBAC, and default-rule tiers, see [RBAC with LoT Rules](./rbac).

***

## Complete Examples

**Group-based topic access**

Operators and supervisors share a plant namespace; only supervisors may emergency-stop:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE Zone1Cmd WITH PRIORITY 1000 FOR Publish TO TOPIC "zone1/+/cmd"
    IF USER IN GROUP "operators" OR USER IN GROUP "supervisors" THEN
        ALLOW
    ELSE
        DENY

DEFINE RULE EmergencyStop WITH PRIORITY 100 FOR Publish TO TOPIC "zone1/emergency/stop"
    IF USER IN GROUP "supervisors" THEN
        ALLOW
    ELSE
        DENY
```

**Device topic namespace**

Confine device accounts to their own tree, and deny them everything else with a coarse fallback:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE DenyDeviceElsewhere WITH PRIORITY 1000 FOR Publish TO TOPIC "#"
    IF USER IN GROUP "devices" THEN
        DENY
    ELSE
        ALLOW

DEFINE RULE DevicePublish WITH PRIORITY 100 FOR Publish TO TOPIC "devices/#"
    IF USER IN GROUP "devices" THEN
        ALLOW
    ELSE
        DENY
```

Device accounts need no rule to keep them off `$SYS/Coreflux/Command` — the locked built-in already requires a permission flag, so simply leave all three flags unset on those users.

**Department isolation**

Separate publish access by group:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE RULE EngineeringPublish WITH PRIORITY 100 FOR Publish TO TOPIC "engineering/#"
    IF USER IN GROUP "engineering" THEN
        ALLOW
    ELSE
        DENY

DEFINE RULE OperationsPublish WITH PRIORITY 100 FOR Publish TO TOPIC "operations/#"
    IF USER IN GROUP "operations" THEN
        ALLOW
    ELSE
        DENY

DEFINE RULE SharedTopicAccess WITH PRIORITY 100 FOR Publish TO TOPIC "shared/#"
    IF USER IN GROUP "engineering" OR USER IN GROUP "operations" THEN
        ALLOW
    ELSE
        DENY
```

***

## Best Practices

> **Prefer groups for topic access**
>
> Use `USER IN GROUP` for data and panel access. Reserve permission flags for system-level capabilities.

> **Any user-band rule overrides the catch-alls**
>
> You do not need to remove `AllowPublishTopic` / `AllowSubscribeTopic` / `AllowConnect` to deny a subtree (or a connection). They sit in the weakest band (`1 000 000`), so any rule you write for that pattern already wins.

> **Leave room to carve out exceptions**
>
> Exceptions need a *lower* number than the rule they override, and `100` is the floor. Place namespace-wide rules at `1000` or higher and keep `100` for the most specific case, so you never have to renumber deployed rules.

> **Protect \$SYS topics**
>
> Rely on the locked built-ins — they already gate `$SYS` on permission flags and cannot be overridden. Keep those flags off device and operator accounts rather than writing your own `$SYS` rules.

> **Name rules clearly**
>
> Prefer `DenyRawArea` or `OperatorControl` over `Rule1`.

***

## Next Steps

> **[RBAC with LoT Rules](/latest/lot-language/rules/rbac)**
>
> Groups, precedence deep-dive, cookbook, and Visu access.

> **[Broker Commands](/latest/mqtt-broker/commands)**
>
> Deploy rules and manage groups via MQTT commands.


# Thing Examples
Source: https://docs.coreflux.org/latest/lot-language/things/examples

Ready-to-deploy DEFINE THING examples for manufacturing, energy and smart cities: sensors, PLCs, solar inverters, EV chargers and air quality stations

Preview

> [!WARNING]
>
> `DEFINE THING` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change.

## Why build with Things

Whether you run ten identical sensors on a factory floor, a fleet of solar inverters across a substation, or hundreds of street lights across a city district, copying and pasting separate connectors, models, and actions quickly becomes hard to maintain. With a **Thing**, you describe the asset once as a template and deploy as many instances as you need from a root.

> [!TIP]
>
> **Like a cookie cutter for your equipment.** The template is the cutter that defines the shape once, and each Thing root stamps out a complete, ready-to-run set of connectors, models, and actions for a real asset.

### When to use these patterns

| Example | Pattern | Best for |
| - | - | - |
| [Two sensors on one machine](#two-sensors-on-one-machine) | Template + root with children | Grouping repeated sensors on a single piece of equipment |
| [Reusable PLC template](#reusable-plc-template) | `DEFINE THING <name> OF <template>` | Deploying identical machines that only differ by IP address |
| [Helper action inside a Thing](#helper-action-inside-a-thing) | Sibling `CALL ACTION` reference | Scaling or validating raw values before publishing |
| [Production line with multiple machines](#production-line-with-multiple-machines) | Nested templates (`line` → `press`) | Building site, line, and machine hierarchies |
| [Intelligent Things](#intelligent-things) | `WITH AGENT` + `WITH AGENTS` delegation | Giving assets their own AI assistants and a station supervisor |
| [Energy use cases](#energy-use-cases) | Modbus polling + parameter overrides | Monitoring solar farm inverters and managing EV charging hubs |
| [Smart cities use cases](#smart-cities-use-cases) | Custom `path` prefix + threshold alerts | Automating district street lighting and urban air quality stations |

***

The examples below are complete and ready to deploy. Send each block to `$SYS/Coreflux/Command` with `-addThing`, or test it first with `-addThing --dryRun` to inspect the expanded children without changing the broker.

## Two sensors on one machine

Start with the simplest pattern: a `TempSensor` template with a default alarm limit, and an `Oven` root that creates two sensors (`inlet` and `outlet`). The `outlet` sensor overrides the default `limit` of `80` with `120`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE TempSensor
    WITH PARAM limit 80
    WITH MODEL Reading WITH TOPIC "{{path}}/reading"
        ADD DOUBLE "temperature" WITH TOPIC "{{path}}/temp" AS TRIGGER
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION Overheat
    ON TOPIC "{{path}}/temp" DO
        SET "temp" WITH PAYLOAD AS DOUBLE
        IF {temp} > {{limit}} THEN
            PUBLISH TOPIC "{{path}}/alarm" WITH "overheat " + {temp}

DEFINE THING Oven
    WITH THING inlet OF TempSensor
    WITH THING outlet OF TempSensor
        WITH PARAM limit 120
```

When you deploy both blocks together, `TempSensor` is stored as a template and `Oven` expands into four children:

| Expanded child | Kind | What it does |
| - | - | - |
| `Oven_inlet_Reading` | MODEL | Publishes formatted JSON to `Oven/inlet/reading` when `Oven/inlet/temp` updates |
| `Oven_outlet_Reading` | MODEL | Publishes formatted JSON to `Oven/outlet/reading` when `Oven/outlet/temp` updates |
| `Oven_inlet_Overheat` | ACTION | Publishes an alarm to `Oven/inlet/alarm` when temperature exceeds `80` |
| `Oven_outlet_Overheat` | ACTION | Publishes an alarm to `Oven/outlet/alarm` when temperature exceeds `120` |

> [!NOTE]
>
> Double braces like `{{path}}` and `{{limit}}` are replaced when the broker expands the Thing. Single braces like `{temp}` are runtime action variables and stay untouched.

***

## Reusable PLC template

When a whole machine is one instance of a template, use `DEFINE THING <name> OF <template>` to deploy it directly without an extra nesting level.

Here, the `plc` template bundles a Modbus TCP connector, a status model, a heartbeat action, and an access rule. `press1` and `press2` stamp out two presses with different IP addresses:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE plc
    WITH PARAM ip
    WITH PARAM slave 1
    WITH CONNECTOR modbus WITH TYPE MODBUS_TCP
        ADD MODBUS_CONFIG
            WITH IP "{{ip}}"
            WITH PORT 502
            WITH SLAVE_ID {{slave}}
        ADD MAPPING ReadRegisters
            WITH SOURCE_TOPIC "{{path}}/read"
            WITH EVERY 1 SECONDS
            ADD TAG Temperature
                WITH ADDRESS "40001"
                WITH DATA_TYPE "INT16"
    WITH MODEL Status WITH TOPIC "{{path}}/status"
        ADD DOUBLE "temperature" WITH TOPIC "{{path}}/read/Temperature" AS TRIGGER
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION Heartbeat
    ON EVERY 30 SECONDS DO
        PUBLISH TOPIC "{{path}}/heartbeat" WITH TIMESTAMP "ISO"
    WITH RULE LocalOnly WITH PRIORITY 1000 FOR Publish TO TOPIC "{{path}}/#"
        IF USER IN GROUP "operators" THEN
            ALLOW
        ELSE
            DENY

DEFINE THING press1 OF plc
    WITH PARAM ip "192.168.1.100"

DEFINE THING press2 OF plc
    WITH PARAM ip "192.168.1.101"
```

Because `ip` has no default value in `plc`, every root must pass `WITH PARAM ip`. The `slave` parameter defaults to `1` unless overridden.

| Expanded child | Kind | Resolved settings |
| - | - | - |
| `press1_modbus` | CONNECTOR | Polls `192.168.1.100:502` (slave `1`) into `press1/read/Temperature` |
| `press1_Status` | MODEL | Publishes to `press1/status` when `press1/read/Temperature` updates |
| `press1_Heartbeat` | ACTION | Publishes to `press1/heartbeat` every 30 seconds |
| `press1_LocalOnly` | RULE | Restricts publishes on `press1/#` to the `operators` group |
| `press2_modbus` … `press2_LocalOnly` | ALL | Same 4 children for `192.168.1.101` under `press2/…` |

***

## Helper action inside a Thing

Clauses inside the same Thing can refer to each other by their short local name. The broker rewrites those references to the expanded child names automatically.

In this example, `OnReading` calls the sibling callable action `Normalize` to scale a raw sensor reading by `0.1` before publishing:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE gauge
    WITH ACTION Normalize
    INPUT raw AS DOUBLE
    DO
        SET "scaled" WITH ({raw} * 0.1)
    RETURN
        OUTPUT scaled
    WITH ACTION OnReading
    ON TOPIC "{{path}}/raw" DO
        CALL ACTION Normalize WITH raw = PAYLOAD AS DOUBLE RETURN scaled
        PUBLISH TOPIC "{{path}}/value" WITH {scaled}

DEFINE THING tank1
    WITH THING level OF gauge
```

When `tank1` is deployed, `CALL ACTION Normalize` is rewritten to `CALL ACTION tank1_level_Normalize`. Publishing `250` to `tank1/level/raw` publishes `25` to `tank1/level/value`.

***

## Production line with multiple machines

Templates can instantiate other templates to model physical hierarchies such as `factory` → `line` → `press`.

This example builds on the `plc` template above. Each `line` has two presses, and each press derives its IP address from its line's `baseIp` parameter (`{{baseIp}}.11` and `{{baseIp}}.12`):

```lot wrap focus={24-39} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE plc
    WITH PARAM ip
    WITH PARAM slave 1
    WITH CONNECTOR modbus WITH TYPE MODBUS_TCP
        ADD MODBUS_CONFIG
            WITH IP "{{ip}}"
            WITH PORT 502
            WITH SLAVE_ID {{slave}}
        ADD MAPPING ReadRegisters
            WITH SOURCE_TOPIC "{{path}}/read"
            WITH EVERY 1 SECONDS
            ADD TAG Temperature
                WITH ADDRESS "40001"
                WITH DATA_TYPE "INT16"
    WITH MODEL Status WITH TOPIC "{{path}}/status"
        ADD DOUBLE "temperature" WITH TOPIC "{{path}}/read/Temperature" AS TRIGGER
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION Heartbeat
    ON EVERY 30 SECONDS DO
        PUBLISH TOPIC "{{path}}/heartbeat" WITH TIMESTAMP "ISO"

DEFINE THING TEMPLATE press
    WITH PARAM ip
    WITH THING controller OF plc

DEFINE THING TEMPLATE line
    WITH PARAM baseIp
    WITH THING press1 OF press
        WITH PARAM ip "{{baseIp}}.11"
    WITH THING press2 OF press
        WITH PARAM ip "{{baseIp}}.12"

DEFINE THING factory
    WITH THING line1 OF line
        WITH PARAM baseIp "192.168.1"
    WITH THING line2 OF line
        WITH PARAM baseIp "192.168.2"
```

Notice how `press` declares `WITH PARAM ip` and does not need to pass it to `controller`: required parameters automatically inherit from the nearest enclosing instance that defines them.

| Expanded connector | Resolved IP | Topic prefix (`{{path}}`) |
| - | - | - |
| `factory_line1_press1_controller_modbus` | `192.168.1.11` | `factory/line1/press1/controller` |
| `factory_line1_press2_controller_modbus` | `192.168.1.12` | `factory/line1/press2/controller` |
| `factory_line2_press1_controller_modbus` | `192.168.2.11` | `factory/line2/press1/controller` |
| `factory_line2_press2_controller_modbus` | `192.168.2.12` | `factory/line2/press2/controller` |

***

## Intelligent Things

A Thing can bundle an AI agent (`WITH AGENT`), a diagnostic action (`CALL AGENT`), and a dashboard (`WITH PANEL`) inside the same template, turning a physical machine into an **Intelligent Thing**. When you nest Intelligent Things inside a parent station, a station supervisor agent can delegate to each child's agent using relative dotted paths (`WITH AGENTS "p1.Assistant, p2.Assistant"`).

**Single intelligent asset**

Use `WITH PARAM llm AS CONNECTOR` to pass an existing `TYPE LLM` connector into the template. Before deploying this example, make sure the `PlantLLM` connector and the broker user `agent-north` exist on your broker:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE SmartPump
    WITH PARAM llm AS CONNECTOR
    WITH PARAM agentUser
    WITH AGENT Assistant
        USES LLM CONNECTOR {{llm}}
        WITH DEFAULT_USER "{{agentUser}}"
        WITH INTERACTION_TOPIC "{{path}}/assistant"
        ADD TOOL "read_mqtt"
            WITH TOPICS "{{path}}/#"
    WITH ACTION DiagnoseAlarm
    ON TOPIC "{{path}}/alarm" DO
        CALL AGENT "Assistant.execute"
            WITH (task = "Pump {{thing}} alarm: " + PAYLOAD)
            RETURN AS {advice}
        PUBLISH TOPIC "{{path}}/advice" WITH {advice}
    WITH PANEL Dashboard
        WITH TITLE "Pump {{thing}}"
        WITH LAYOUT "grid" COLUMNS 2
        WITH VISIBILITY PUBLIC
        WITH STATE PUBLISHED
        ADD COMPONENT "Advice" WITH TYPE "text"
            BIND CONTENT TO TOPIC "{{path}}/advice"

DEFINE THING north
    WITH THING p1 OF SmartPump
        WITH PARAM llm "PlantLLM"
        WITH PARAM agentUser "agent-north"
```

Deploying `north` creates:

* **`north_p1_Assistant` (AGENT)**: scoped to read only `north/p1/#` topics, using the shared `PlantLLM` connector.
* **`north_p1_DiagnoseAlarm` (ACTION)**: calls `north_p1_Assistant.execute` whenever an alarm arrives on `north/p1/alarm` and publishes the advice to `north/p1/advice`.
* **`north_p1_Dashboard` (PANEL)**: a published dashboard titled `"Pump p1"` bound to `north/p1/advice`.

**Station supervisor with intelligent assets**

Compose two `SmartPump` instances inside a `SmartStation` template and add a `Supervisor` agent that delegates to `p1.Assistant` and `p2.Assistant`. The Thing expander rewrites those relative names to `north_p1_Assistant` and `north_p2_Assistant` automatically:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE SmartPump
    WITH PARAM llm AS CONNECTOR
    WITH PARAM agentUser
    WITH AGENT Assistant
        USES LLM CONNECTOR {{llm}}
        WITH DEFAULT_USER "{{agentUser}}"
        WITH INTERACTION_TOPIC "{{path}}/assistant"
        ADD TOOL "read_mqtt"
            WITH TOPICS "{{path}}/#"
    WITH ACTION DiagnoseAlarm
    ON TOPIC "{{path}}/alarm" DO
        CALL AGENT "Assistant.execute"
            WITH (task = "Pump {{thing}} alarm: " + PAYLOAD)
            RETURN AS {advice}
        PUBLISH TOPIC "{{path}}/advice" WITH {advice}

DEFINE THING TEMPLATE SmartStation
    WITH PARAM llm AS CONNECTOR
    WITH PARAM agentUser
    WITH THING p1 OF SmartPump
    WITH THING p2 OF SmartPump
    WITH AGENT Supervisor
        USES LLM CONNECTOR {{llm}}
        WITH DEFAULT_USER "{{agentUser}}"
        WITH AGENTS "p1.Assistant, p2.Assistant"
        WITH INTERACTION_TOPIC "{{path}}/supervisor"
        ADD TOOL "read_mqtt"
            WITH TOPICS "{{path}}/#"

DEFINE THING north OF SmartStation
    WITH PARAM path "plant/north"
    WITH PARAM llm "PlantLLM"
    WITH PARAM agentUser "agent-north"
```

| Expanded agent | Interaction topic | Scope & peers |
| - | - | - |
| `north_p1_Assistant` | `plant/north/p1/assistant` | Reads `plant/north/p1/#` |
| `north_p2_Assistant` | `plant/north/p2/assistant` | Reads `plant/north/p2/#` |
| `north_Supervisor` | `plant/north/supervisor` | Reads `plant/north/#` and delegates to `north_p1_Assistant, north_p2_Assistant` |

***

## Energy use cases

Power grids, renewable generation sites, and EV charging hubs all rely on repeated assets that share the same telemetry schema and safety rules.

**Solar farm inverters**

Poll multiple solar inverters over Modbus TCP, publish a unified telemetry model for each inverter, and raise an alarm if grid frequency drops below a safe threshold (`minFreq`, default `49.8` Hz):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE SolarInverter
    WITH PARAM ip
    WITH PARAM minFreq 49.8
    WITH CONNECTOR modbus WITH TYPE MODBUS_TCP
        ADD MODBUS_CONFIG
            WITH IP "{{ip}}"
            WITH PORT 502
            WITH SLAVE_ID 1
        ADD MAPPING ReadInverter
            WITH SOURCE_TOPIC "{{path}}/read"
            WITH EVERY 5 SECONDS
            ADD TAG PowerKw
                WITH ADDRESS "40001"
                WITH DATA_TYPE "INT16"
            ADD TAG GridFrequency
                WITH ADDRESS "40002"
                WITH DATA_TYPE "INT16"
    WITH MODEL Telemetry WITH TOPIC "{{path}}/telemetry"
        ADD DOUBLE "power_kw" WITH TOPIC "{{path}}/read/PowerKw" AS TRIGGER
        ADD DOUBLE "frequency_hz" WITH TOPIC "{{path}}/read/GridFrequency"
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION CheckFrequency
    ON TOPIC "{{path}}/read/GridFrequency" DO
        SET "freq" WITH PAYLOAD AS DOUBLE
        IF {freq} < {{minFreq}} THEN
            PUBLISH TOPIC "{{path}}/alarm" WITH "underfrequency " + {freq}

DEFINE THING solar_west
    WITH PARAM path "grid/solar/west"
    WITH THING inv1 OF SolarInverter
        WITH PARAM ip "10.20.1.10"
    WITH THING inv2 OF SolarInverter
        WITH PARAM ip "10.20.1.11"
```

Setting `WITH PARAM path "grid/solar/west"` on the `solar_west` root places all inverter topics under `grid/solar/west/inv1/…` and `grid/solar/west/inv2/…`:

| Expanded child | Kind | What it does |
| - | - | - |
| `solar_west_inv1_modbus` | CONNECTOR | Polls `10.20.1.10:502` every 5 seconds into `grid/solar/west/inv1/read/*` |
| `solar_west_inv1_Telemetry` | MODEL | Publishes power and frequency to `grid/solar/west/inv1/telemetry` |
| `solar_west_inv1_CheckFrequency` | ACTION | Publishes an alarm to `grid/solar/west/inv1/alarm` below `49.8` Hz |
| `solar_west_inv2_*` | ALL | Same 3 children for `10.20.1.11` under `grid/solar/west/inv2/…` |

**EV charging hub**

Model a charging station with standard AC bays (`32` A default) and a high-power fast-charging bay (`80` A override). If a bay draws more current than its limit, `OvercurrentGuard` publishes a `STOP` command and an alarm:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE EvCharger
    WITH PARAM maxCurrent 32
    WITH MODEL Session WITH TOPIC "{{path}}/session"
        ADD STRING "status" WITH TOPIC "{{path}}/status" AS TRIGGER
        ADD DOUBLE "current_amps" WITH TOPIC "{{path}}/current"
        ADD INT "max_amps" WITH {{maxCurrent}}
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION OvercurrentGuard
    ON TOPIC "{{path}}/current" DO
        SET "amps" WITH PAYLOAD AS DOUBLE
        IF {amps} > {{maxCurrent}} THEN
            PUBLISH TOPIC "{{path}}/command" WITH "STOP"
            PUBLISH TOPIC "{{path}}/alarm" WITH "overcurrent " + {amps}

DEFINE THING station_central
    WITH THING bay1 OF EvCharger
    WITH THING bay2 OF EvCharger
    WITH THING fast_bay OF EvCharger
        WITH PARAM maxCurrent 80
```

Each bay gets its own `Session` model and `OvercurrentGuard` action with its configured amperage limit:

| Instance | Current limit (`maxCurrent`) | Session topic | Command topic on overload |
| - | - | - | - |
| `bay1` | `32` A (default) | `station_central/bay1/session` | `station_central/bay1/command` |
| `bay2` | `32` A (default) | `station_central/bay2/session` | `station_central/bay2/command` |
| `fast_bay` | `80` A (override) | `station_central/fast_bay/session` | `station_central/fast_bay/command` |

***

## Smart cities use cases

Municipal IoT deployments manage identical sensors and controllers across streets, parks, and school zones, where only topic paths or safety thresholds change per location.

**Smart street lighting**

Adjust street light brightness automatically from ambient light (`lux`) readings. Pedestrian crossings or park avenues can override `luxThreshold` to turn on earlier at dusk:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE StreetLight
    WITH PARAM luxThreshold 30
    WITH MODEL LampStatus WITH TOPIC "{{path}}/status"
        ADD DOUBLE "lux" WITH TOPIC "{{path}}/lux" AS TRIGGER
        ADD INT "brightness" WITH TOPIC "{{path}}/brightness"
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION AutoDim
    ON TOPIC "{{path}}/lux" DO
        SET "lux" WITH PAYLOAD AS DOUBLE
        IF {lux} < {{luxThreshold}} THEN
            PUBLISH TOPIC "{{path}}/brightness" WITH 100
        ELSE
            PUBLISH TOPIC "{{path}}/brightness" WITH 20

DEFINE THING downtown_lights
    WITH PARAM path "city/lights/downtown"
    WITH THING main_st OF StreetLight
    WITH THING park_ave OF StreetLight
        WITH PARAM luxThreshold 50
```

When ambient light on `city/lights/downtown/park_ave/lux` drops below `50`, `downtown_lights_park_ave_AutoDim` sets brightness to `100%`; on `main_st`, it waits until light drops below `30`.

| Expanded child | Kind | Topic |
| - | - | - |
| `downtown_lights_main_st_LampStatus` | MODEL | `city/lights/downtown/main_st/status` |
| `downtown_lights_main_st_AutoDim` | ACTION | Reads `…/main_st/lux`, publishes `100` or `20` to `…/main_st/brightness` |
| `downtown_lights_park_ave_LampStatus` | MODEL | `city/lights/downtown/park_ave/status` |
| `downtown_lights_park_ave_AutoDim` | ACTION | Reads `…/park_ave/lux` (threshold `50`), publishes to `…/park_ave/brightness` |

**Urban air quality network**

Deploy environmental monitoring stations across a city with stricter particulate (`PM2.5`) alert thresholds around sensitive areas such as schools and hospitals:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE AirStation
    WITH PARAM pm25Limit 35
    WITH MODEL AirReading WITH TOPIC "{{path}}/reading"
        ADD DOUBLE "pm25" WITH TOPIC "{{path}}/pm25" AS TRIGGER
        ADD DOUBLE "no2" WITH TOPIC "{{path}}/no2"
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION HighPollutionAlert
    ON TOPIC "{{path}}/pm25" DO
        SET "pm25" WITH PAYLOAD AS DOUBLE
        IF {pm25} > {{pm25Limit}} THEN
            PUBLISH TOPIC "{{path}}/alert" WITH "high pm25: " + {pm25}

DEFINE THING city_air
    WITH THING harbor OF AirStation
    WITH THING school_zone OF AirStation
        WITH PARAM pm25Limit 15
```

Both stations share the same `AirStation` template, while `school_zone` alerts at `15` µg/m³ instead of the default `35` µg/m³:

| Instance | `pm25Limit` | Reading topic | Alert topic |
| - | - | - | - |
| `harbor` | `35` (default) | `city_air/harbor/reading` | `city_air/harbor/alert` |
| `school_zone` | `15` (override) | `city_air/school_zone/reading` | `city_air/school_zone/alert` |

***

## Verify your deployment

**1. Preview with a dry run**

Send `-addThing --dryRun <DEFINE THING …>` to `$SYS/Coreflux/Command`. The response on `$SYS/Coreflux/Command/Output` shows every child (`add`, `update`, `adopt`, `remove`, or `unchanged`) and its expanded LoT code without modifying the broker.

**2. Deploy the Thing**

Send `-addThing <DEFINE THING …>` to `$SYS/Coreflux/Command`. All children deploy together as one atomic unit.

**3. Inspect the live tree and status**

Use MQTT Explorer or Coreflux HUB to subscribe to `$SYS/Coreflux/Things/<name>/tree` (the expanded instance tree) and `$SYS/Coreflux/Things/<name>/status` (`ok`, `degraded`, or `error`).

## Best practices

> **Use double braces for parameters and single braces for runtime variables**
>
> Write `{{limit}}` and `{{path}}` for Thing parameters replaced at deploy time. Keep single braces like `{temp}` for runtime action variables and `{payload}` for connector event placeholders.

> **Edit children through their Thing**
>
> Children deployed by a Thing are protected against direct edits. To change a child action, model, or connector, update the `DEFINE THING` source and run `-addThing` again.

> **Keep secrets out of Thing parameters**
>
> Resolved parameter values are published on `$SYS/Coreflux/Things/<name>/tree`. Always read credentials inside clause bodies with `GET SECRET` or `GET ENV` instead of passing them through `WITH PARAM`.

## Next steps

> **[Thing Syntax](/latest/lot-language/things/syntax)**
>
> Full reference for templates, clauses, parameters, references, and permissions.

> **[Things Overview](/latest/lot-language/things/overview)**
>
> Learn how Things group assets and how `-addThing` manages their lifecycle.


# Things Overview
Source: https://docs.coreflux.org/latest/lot-language/things/overview

Group the connectors, models, agents, actions, rules and panels of one asset under a single DEFINE THING (preview)

Preview

> [!WARNING]
>
> `DEFINE THING` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change.

## What a Thing is

A **Thing** groups everything that belongs to one asset (a pump, a PLC, a press, a line, a site) under one name: its connectors, models, agents, actions, rules and panels.

You describe the asset once as a **template**, then deploy it as many times as you need from a **root**. The broker expands each root into ordinary `DEFINE` declarations, called its **children**, deploys them, and keeps owning them.

* **One unit**: a root and all its children deploy together or not at all. If a step fails, every child is rolled back.
* **Live templates**: editing a template redeploys every root that uses it, and only the children whose code changed.
* **Cascading removal**: removing a root removes its children in reverse deploy order.
* **Protected children**: a child can only be changed through its Thing. A direct add or remove is refused.
* **Dry run**: `-addThing --dryRun` returns the full plan and each child's expanded LoT, and changes nothing.
* **Recursive**: templates can use other templates to any depth (site → line → cell → device).

## A first Thing

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE TempSensor
    WITH PARAM limit 80
    WITH MODEL Reading WITH TOPIC "{{path}}/reading"
        ADD DOUBLE "temperature" WITH TOPIC "{{path}}/temp" AS TRIGGER
        ADD STRING "ts" WITH TIMESTAMP "ISO"
    WITH ACTION Overheat
    ON TOPIC "{{path}}/temp" DO
        SET "temp" WITH PAYLOAD AS DOUBLE
        IF {temp} > {{limit}} THEN
            PUBLISH TOPIC "{{path}}/alarm" WITH "overheat " + {temp}

DEFINE THING Oven
    WITH THING inlet OF TempSensor
    WITH THING outlet OF TempSensor
        WITH PARAM limit 120
```

Send both blocks in one `-addThing` command to `$SYS/Coreflux/Command`. `TempSensor` is a template and deploys nothing. `Oven` is a root and deploys four children:

| Child | Kind | Resolved |
| - | - | - |
| `Oven_inlet_Reading` | MODEL | topic `Oven/inlet/reading` |
| `Oven_outlet_Reading` | MODEL | topic `Oven/outlet/reading` |
| `Oven_inlet_Overheat` | ACTION | fires on `Oven/inlet/temp`, alarms above 80 |
| `Oven_outlet_Overheat` | ACTION | fires on `Oven/outlet/temp`, alarms above 120 |

`{{path}}` and `{{limit}}` are filled in when the broker expands the Thing. `{temp}` is an action variable: single braces always belong to the runtime and are never touched.

## When to use a Thing

| Use a Thing when | Use standalone definitions when |
| - | - |
| The same asset repeats (10 pumps, 3 lines) | Each entity is one of a kind |
| Several entities must deploy and be removed together | Entities have independent lifecycles |
| You want one place to change an asset's logic | A quick test or a single action |

## Managing Things

| Command | Does |
| - | - |
| `-addThing <DEFINE THING …>` | Adds or updates every Thing in the payload as one unit |
| `-addThing --dryRun <DEFINE THING …>` | Returns the plan, each child's expanded code and every diagnostic. Changes nothing |
| `-removeThing <name>` | Removes a root and its children, or a template no Thing uses |
| `-listThings` | Lists every Thing with its kind (`root` or `template`), template, users and child count |

Every Thing is published retained on `$SYS/Coreflux/Things/<name>` (the source), `…/tree` (the expanded instance tree) and, for roots, `…/status` (`ok`, `degraded` or `error`, from the children's health). Children keep their own topics.

## Next steps

> **[Thing Examples](/latest/lot-language/things/examples)**
>
> Simple, ready-to-deploy Thing templates for sensors, PLCs, lines, and smart assets.

> **[Thing Syntax](/latest/lot-language/things/syntax)**
>
> Templates, clauses, params, names, references and permissions.


# Thing Syntax
Source: https://docs.coreflux.org/latest/lot-language/things/syntax

DEFINE THING reference: templates and roots, clauses, params and placeholders, names, references, ownership and permissions (preview)

Preview

> [!WARNING]
>
> `DEFINE THING` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change.

For what a Thing is and a first example, see [Things Overview](/latest/lot-language/things/overview).

## Templates and roots

| Declaration | Meaning |
| - | - |
| `DEFINE THING TEMPLATE <name>` | A template. Stored, never deployed by itself |
| `DEFINE THING <name>` | A root. Adding it deploys its whole instance tree |
| `DEFINE THING <name> OF <template>` | A root that is one instance of a template. Only `WITH PARAM` lines may follow |

* `OF` must name a template. Naming a root or an unknown Thing is an error, and so is a cycle.
* Templates are stored on the broker. A root added later, from another cell, notebook or project, can use a template added earlier.
* `DEFINE THING north OF Station` puts `Station`'s clauses directly at `north_<clause>`. A plain root with `WITH THING station OF Station` adds a level: `north_station_<clause>`.

## Clauses

A clause is a standalone declaration with `DEFINE` replaced by `WITH`, indented one level under the Thing. Every kind keeps its full syntax, so you can paste an existing definition into a Thing: indent it one level and change `DEFINE` to `WITH`.

| Clause | Expands to |
| - | - |
| `WITH CONNECTOR <name> WITH TYPE <type>` (or `WITH ROUTE …`) | `DEFINE CONNECTOR` |
| `WITH MODEL <name> …` | `DEFINE MODEL` |
| `WITH ACTION <name>` | `DEFINE ACTION` |
| `WITH RULE <name> WITH PRIORITY n FOR …` | `DEFINE RULE` |
| `WITH AGENT <name>` | `DEFINE AGENT` |
| `WITH PANEL <name>` | `DEFINE PANEL` |
| `WITH THING <child> OF <template>` | One more instance of the template |
| `WITH PARAM <name> [value]` | Nothing. Declares a param |

* An action's trigger, `INPUT`, `DO` and `RETURN` lines sit at the clause's own level, exactly where they sit under a standalone `DEFINE ACTION`.
* Python scripts and themes are not clauses.
* Children deploy in the order connectors → models → agents → actions → rules → panels, and are removed in reverse.

## Params and placeholders

| Where | `WITH PARAM ip "10.0.0.5"` means | `WITH PARAM ip` means |
| - | - | - |
| In a template | A default | A required param |
| In a plain root | Its value | An error: a root param needs a value |
| Under `WITH THING … OF T` or `DEFINE THING r OF T` | An argument to `T` | An error |

For each param, the broker uses, in order: the argument at the call site, then the template's default, then (for a required param) the value in the nearest enclosing instance that has one. Otherwise the deploy fails and names the missing param.

* An argument must name a param the template declares, or `path`.
* An argument can use the caller's placeholders: `WITH PARAM ip "{{baseIp}}.11"`. Defaults are literals.
* A value may not contain `"`, a line break or `{{`.
* Keep secrets in `GET SECRET` and `GET ENV` inside clause bodies, never in params. Params are published with the Thing's tree.

### Reserved placeholders

| Placeholder | Value |
| - | - |
| `{{thing}}` | The instance's own name |
| `{{parent}}` | The parent instance's name. Empty at the root |
| `{{path}}` | A topic prefix. By default the instance chain joined with `/` (`factory/line1/press1`). Set `WITH PARAM path "plant/north"` on a root to change it |

Substitution is textual and happens before a clause is parsed, so a placeholder can sit in a string (`"{{path}}/status"`) or a bare position (`WITH SLAVE_ID {{slave}}`). Placeholders are not allowed in Thing, child, clause or param names. Write `\{{` for a literal `{{`. Single-brace `{x}` (action variables, `{payload}`, `{env.NAME}`) is never touched.

## Names

* Thing, instance and clause names match `[A-Za-z_][A-Za-z0-9_]*`. `TEMPLATE` can't be a Thing name.
* A child is named by the instance chain and the clause name joined with `_`: `factory_line1_press1_modbus`.
* Every expanded name is checked before anything changes. A name owned by another Thing or project is an error.
* An existing standalone entity of the same kind and name is **adopted**: the expanded declaration replaces it and the root owns it from then on.

## References

A clause can refer to a clause of the same instance by its local name, or to a clause of a descendant by a dotted path (`p1.Assistant`). The broker rewrites these to expanded names in `CALL ACTION`, `PUBLISH MODEL`, `GET MODEL`, `STORE IN`, `CALL AGENT`, `CALL LLM`, `CALL MCP`, `USES LLM CONNECTOR`, `WITH AGENTS`, agent tool `WITH TARGET`, and panel bindings.

* A single name that matches no sibling clause passes through unchanged, so a Thing can use a connector deployed outside it.
* A dotted reference must resolve, or the Thing is rejected.
* Topic strings and payloads are never rewritten.

To wire siblings together, declare a **reference param**: `WITH PARAM peer AS AGENT` (or `AS CONNECTOR`, `MODEL`, `ACTION`, `PANEL`). An argument resolves in the caller, so a parent can pass `WITH PARAM peer "south.Lead"` to its `north` child.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE THING TEMPLATE Cell
    WITH PARAM llm AS CONNECTOR
    WITH PARAM agentUser
    WITH PARAM peer AS AGENT
    WITH AGENT Lead
        USES LLM CONNECTOR {{llm}}
        WITH DEFAULT_USER "{{agentUser}}"
        WITH AGENTS "{{peer}}"
        WITH INTERACTION_TOPIC "{{path}}/lead"
        ADD TOOL "read_mqtt"
            WITH TOPICS "{{path}}/#"

DEFINE THING site
    WITH PARAM agentUser "agent-site"
    WITH CONNECTOR Brain WITH TYPE LLM
        ADD LLM_CONFIG
            WITH PROVIDER "anthropic"
            WITH MODEL "claude-sonnet-5-5"
            WITH API_KEY GET SECRET "ANTHROPIC_API_KEY"
    WITH THING north OF Cell
        WITH PARAM llm "Brain"
        WITH PARAM peer "south.Lead"
    WITH THING south OF Cell
        WITH PARAM llm "Brain"
        WITH PARAM peer "north.Lead"
```

`agent-site` must already exist as a broker user. LoT can't create users.

## Ownership

Children run, publish and can be called like any other entity. They are read-only except through their Thing:

```text theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Action 'Oven_inlet_Overheat' is owned by THING Oven (instance Oven/inlet, clause Overheat); edit the Thing instead.
```

`-addAction`, `-removeConnector` and the other per-entity commands are refused on a Thing-owned name. `-removeAllConnectors`, `-removeAllModels` and `-removeAllActions` keep owned children and list them as skipped.

## Permissions

| Operation | Permission |
| - | - |
| `-addThing` | `ThingManagementCreation` |
| `-removeThing` | `ThingManagementRemove` |
| `-listThings` | `CommandCall` |

Every child is also checked against its own kind's permission, as if you added it directly. One missing permission rejects the whole unit. Children also count toward license limits.

## Troubleshooting

| Symptom | Fix |
| - | - |
| `… is owned by THING …; edit the Thing instead.` | Change the clause and redeploy the Thing |
| `Template 'X' is used by …` on `-removeThing` | Remove or change the Things that use it first |
| `OF` error naming a root | Mark the target `DEFINE THING TEMPLATE` |
| Unresolved placeholder | Declare the param, or pass it |
| A child error points at the Thing line | Run `-addThing --dryRun` and read that child's expanded `code` |

## Next steps

> **[Thing Examples](/latest/lot-language/things/examples)**
>
> Copy-and-deploy examples for sensors, PLCs, helper actions, and nested lines.

> **[Things Overview](/latest/lot-language/things/overview)**
>
> Learn what a Thing is and when to group entities under one asset.


# Alarms and monitoring
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/alarms-and-monitoring

Threshold crossings, device and connector liveness, and optional email notifications.

## Reacting to Threshold Crossings

Most alarm logic boils down to "if a value crosses a threshold, alert someone." LoT does this in a handful of lines: read the current value, read the threshold from config, compare, publish if exceeded.

> [!TIP]
>
> **Like a kitchen oven timer.** It does one thing, watches one number, and beeps when the number's wrong. Quiet the rest of the time.

### When to Reach for This

Any time you need to detect that something has gone outside an acceptable range — temperature too high, tank too full, vibration too strong, fill level too low, pollution above a limit. This is one of the first patterns most projects need.

### The Simple Version

A CO2 monitor in a conference room:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION HighCO2Alarm
ON TOPIC "sensors/co2" DO
    SET "current" WITH PAYLOAD AS DOUBLE
    SET "max" WITH (GET TOPIC "config/co2_max" AS DOUBLE)

    IF {current} > {max} THEN
        PUBLISH TOPIC "alerts/co2_high"
            WITH ("CO2 too high: " + {current})
```

That's it. Three things to notice:

1. **The threshold lives in `config/`, not in the Action.** A facilities manager can change it at runtime without redeploying anything. If the limit shifts from 1000 ppm to 1200 ppm, just publish the new value to `config/co2_max` and the next reading uses the new limit.
2. **The alert topic is separate from the data topic.** Anyone subscribing to `alerts/#` gets every alert in the system, regardless of source. Notifiers, on-call systems, and [dashboard `alert` and `indicator` components](/hub/dashboards/components/display) all use the same channel — the visualization end of an alarm pipeline.
3. **No state tracking in this version.** The Action fires every time a reading exceeds the threshold, so you'll get repeated alerts while CO2 stays high. If you have downstream notification infrastructure that handles deduplication, that's fine. If you don't, see the state-tracking variant below.

### Optional: Standardize the Alarm Format with a Model

Plain text alerts work, but as your system grows you'll want consistent structure — every alarm in the same JSON shape so dashboards and databases can parse them uniformly. Define a `COLLAPSED` Model and use `PUBLISH MODEL` instead of `PUBLISH TOPIC`. (`COLLAPSED` means the Model doesn't publish on its own — it only fires when something explicitly calls `PUBLISH MODEL`. See the [Models reference](/latest/lot-language/models/overview) for the full options.)

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL Alarm COLLAPSED
    ADD STRING "type"
    ADD STRING "severity"
    ADD DOUBLE "value"
    ADD DOUBLE "threshold"
    ADD STRING "timestamp"

DEFINE ACTION HighCO2Alarm
ON TOPIC "sensors/co2" DO
    SET "current" WITH PAYLOAD AS DOUBLE
    SET "max" WITH (GET TOPIC "config/co2_max" AS DOUBLE)

    IF {current} > {max} THEN
        PUBLISH MODEL Alarm TO "alerts/co2_high" WITH
            type = "CO2_HIGH"
            severity = "WARNING"
            value = {current}
            threshold = {max}
            timestamp = TIMESTAMP "UTC"
```

Now every alarm — whether it's high CO2, low water level, or door left open — publishes the same JSON shape. A single database table, dashboard panel, or notification rule can handle all of them. This pairs especially well with [model inheritance](/latest/lot-language/usage-patterns/data-layer#standardizing-data-across-device-types).

### Optional: Deduplicate with State Tracking

If you don't have a downstream notifier that deduplicates — or you want a clean audit trail of "alarm started" and "alarm cleared" events — track the previous state in `state/` and only publish on transitions.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION HighCO2Alarm
ON TOPIC "sensors/co2" DO
    SET "current" WITH PAYLOAD AS DOUBLE
    SET "max" WITH (GET TOPIC "config/co2_max" AS DOUBLE)
    SET "previous" WITH (GET TOPIC "state/co2_alarm")

    IF {current} > {max} THEN
        IF {previous} != "active" THEN
            PUBLISH TOPIC "alerts/co2_high"
                WITH ("CO2 too high: " + {current})
            KEEP TOPIC "state/co2_alarm" WITH "active"
    ELSE
        IF {previous} EQUALS "active" THEN
            PUBLISH TOPIC "alerts/co2_normal"
                WITH ("CO2 back to normal: " + {current})
            KEEP TOPIC "state/co2_alarm" WITH "normal"
```

What's happening:

* The action reads three things: current value, threshold, and the previous alarm state stored in `state/co2_alarm`.
* If CO2 is over the threshold **and** the alarm wasn't already active, it fires a "high" alert and marks the state active. Subsequent over-threshold readings while still active produce no extra alerts.
* If CO2 is back below threshold **and** the alarm was active, it fires a "normal" alert and marks the state normal.

The `state/` topic uses `KEEP TOPIC` (not `PUBLISH TOPIC`) so the alarm logic can read it later with `GET TOPIC`. `KEEP TOPIC` stores that value in the broker cache and does not set the MQTT retain flag. Use `PUBLISH TOPIC ... RETAIN` when new subscribers must receive the last payload.

### Optional: Send the Alarm by Email

For alarms that need to reach humans directly, add an `EMAIL` connector that subscribes to your alert topics and sends a templated message via SMTP. The connector does all the work — your Action just publishes to the alert topic as before. (Full reference: [Email Connector](/latest/lot-language/routes/notifications/email).)

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR AlertEmail WITH TYPE EMAIL
    ADD SMTP_CONFIG
        WITH HOST GET ENV "SMTP_HOST"
        WITH PORT '587'
        WITH USE_TLS "true"
        WITH USERNAME GET ENV "SMTP_USER"
        WITH PASSWORD GET SECRET "SMTP_PASSWORD"
    ADD EVENT NotifyOnHighCO2
        WITH SOURCE_TOPIC "alerts/co2_high"
        WITH SUBJECT "CO2 alarm: {value.json.value} ppm"
        WITH RECIPIENT "facilities@acmecorp.com"
        WITH TEMPLATE_PATH "/templates/alarm_email.html"
```

How it fits together:

1. The threshold Action publishes a structured alarm to `alerts/co2_high` (using the Model variant from above).
2. The email connector is subscribed to that topic and fires automatically whenever a new alarm appears.
3. Placeholders like `{value.json.value}` pull fields out of the JSON payload to build the email subject and body.

Credentials come from `ENV` and `SECRET` (see [Keeping Credentials Out of Your Code](/latest/lot-language/usage-patterns/integrations#keeping-credentials-out-of-your-code)). Pair with the **state tracking** variant if you want only one email per alarm transition rather than one per reading.

***

## Knowing When a Device or Connector Goes Offline

Two different things can go silent in a Coreflux system, and you want to know about both.

**Devices** are the sensors, machines, and gateways out in the world. They go offline when their network drops, their battery dies, or they crash. The signal that something's wrong is the *absence of incoming messages*.

**Connectors** are the broker's own connections to databases, cloud brokers, REST APIs, and other external systems. They go offline when credentials change, the remote system is unreachable, or the network between them breaks. The signal here is the *absence of an outbound connection*, which the broker tracks itself using [SYS topics](/latest/mqtt-broker/sys-topics) (the built-in SYS hierarchy).

Both need monitoring. The data sources are different, so the patterns are different.

> [!TIP]
>
> **Like a roll call at the start of class.** Everyone present says "here" — students through the door (devices), staff through the office intercom (broker SYS topics). After a beat of silence on a name, the teacher knows who's missing.

### When to Reach for This

Whenever uptime matters: critical infrastructure, paid telemetry, anything you'd want to dispatch a technician for. Skip it for opportunistic devices where occasional silence is normal (mobile phones, ad-hoc sensors). For connectors, this is almost always worth doing — a silent integration is a silent data loss.

### Approach 1: Heartbeats for Devices

Each device publishes a timestamp to its own status topic at a regular interval. Then a scheduled Action checks for any device whose last timestamp is too old.

If your devices already send data regularly, you can stamp the heartbeat directly from the Action that processes their readings:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION RecordHeartbeat
ON TOPIC "sensors/+/+" DO
    SET "device_id" WITH TOPIC POSITION 2
    KEEP TOPIC "state/" + {device_id} + "/last_seen" WITH TIMESTAMP "UTC"
```

Every time any sensor sends any data, this Action stamps a `last_seen` timestamp for that device. The wildcard means it covers every sensor automatically. `KEEP TOPIC` stores the timestamp in the broker cache for `GET TOPIC` and does not set the MQTT retain flag.

A scheduled Action then wakes up periodically, compares each timestamp to "now," and publishes an alert for anything stale. Time arithmetic is awkward in LoT, so this is a natural place to call a small Python helper (see [Running Python from a LoT Action](/latest/lot-language/usage-patterns/reusable-logic#running-python-from-a-lot-action)):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CheckDeviceLiveness
ON EVERY 60 SECONDS DO
    CALL PYTHON "Liveness.check_all"
        WITH (300)
        RETURN AS {result}

    SET "offline_count" WITH (GET JSON "count" IN {result} AS INT)

    IF {offline_count} > 0 THEN
        PUBLISH MODEL Alarm TO "alerts/devices/offline" WITH
            type = "DEVICES_OFFLINE"
            severity = "WARNING"
            value = {offline_count}
            threshold = 0
            timestamp = TIMESTAMP "UTC"
```

The Python function reads every `state/+/last_seen` topic, compares to the current time, and returns the count and list of devices whose last\_seen is older than 300 seconds.

### Approach 2: SYS topics for Connectors

The broker exposes a live view of itself through [SYS topics](/latest/mqtt-broker/sys-topics) — a built-in dashboard in MQTT form.

For monitoring connector health, read the JSON array published on the topic below. It lists every client currently connected to the broker, with timestamps and connection details. Connectors that maintain MQTT connections (bridges, REST endpoints in client mode, anything with a connected client identity) appear in this list. When one drops, it disappears from the array.

```
$SYS/Coreflux/Comms/Clients
```

The pattern: keep an "expected connectors" list in a config topic, subscribe to that clients topic, and have an Action that flags any expected connector that isn't in the live connection list.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CheckRoutesOnline
ON EVERY 60 SECONDS DO
    SET "expected" WITH (GET TOPIC "config/expected_routes")
    SET "clients" WITH (GET TOPIC "$SYS/Coreflux/Comms/Clients")

    CALL PYTHON "RouteMonitor.find_missing"
        WITH ({expected}, {clients})
        RETURN AS {result}

    SET "missing_count" WITH (GET JSON "count" IN {result} AS INT)

    IF {missing_count} > 0 THEN
        SET "missing_list" WITH (GET JSON "list" IN {result} AS STRING)
        PUBLISH MODEL Alarm TO "alerts/connectors/offline" WITH
            type = "ROUTES_OFFLINE"
            severity = "CRITICAL"
            value = {missing_count}
            threshold = 0
            timestamp = TIMESTAMP "UTC"
        PUBLISH TOPIC "system/offline_routes" WITH {missing_list}
```

The Python helper does the actual list comparison — straightforward in Python, fiddly in LoT:

```python wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# /scripts/RouteMonitor.py
import json

def find_missing(expected_csv, clients_json):
    expected = [name.strip() for name in expected_csv.split(",") if name.strip()]
    try:
        clients = json.loads(clients_json)
        connected_ids = {c.get("Id", "") for c in clients}
    except (json.JSONDecodeError, TypeError):
        connected_ids = set()

    missing = [name for name in expected if name not in connected_ids]
    return {"count": len(missing), "list": ",".join(missing)}
```

What's happening:

1. The expected connector list lives in a config topic — for example, you'd publish `"DatabaseRoute,CloudBridge,WeatherAPI"` to `config/expected_routes`. Operators can update it without redeploying anything.
2. The Action reads the live JSON from `GET TOPIC` on the path above and hands both lists to Python.
3. Python parses the connections, computes the set difference, and returns the count plus a comma-separated list of missing connectors.
4. If anything is missing, the Action publishes a critical alarm and a list of which connectors are down.

### Combining the Two Approaches

A complete monitoring layer runs both Actions side by side: heartbeats catch devices that have stopped reporting even though their network looks fine, and the SYS clients-topic check catches connectors that have lost their integration to the outside world. Both publish into the same `alerts/` branch, so a single subscriber — a dashboard, a notification rule, an [email connector](#optional-send-the-alarm-by-email) — gives you a unified "what's not working right now" view.

Pair either Action with the [state tracking variant](#optional-deduplicate-with-state-tracking) to avoid alert spam: one alert when something disappears, one when it comes back, silence in between.

***

## Next Steps

> **[Email Notifications](/latest/lot-language/routes/notifications/email)**
>
> Send alerts and reports to people from MQTT events.

> **[SYS Topics](/latest/mqtt-broker/sys-topics)**
>
> Built-in broker topics for monitoring clients and comms.


# Anti-patterns
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/anti-patterns

Common LoT mistakes and proven alternatives — for authors and reviewers.

## Common LoT mistakes

These are the most frequent mistakes in LoT development. Avoid them whether you're writing new code or reviewing existing output.

| Anti-Pattern | Why It's Bad | Do This Instead |
| - | - | - |
| Omitting type casts in math | Implicit type handling leads to silent errors | Always cast: `PAYLOAD AS DOUBLE`, `GET TOPIC ... AS DOUBLE` — see [Operations](/latest/lot-language/actions/operations) |
| Triggering models on timestamps | Timestamps update every tick — model fires constantly | Trigger on the primary data field: `AS TRIGGER` on value, not timestamp — see [Schema definition](/latest/lot-language/models/schema-definition) |
| Inconsistent naming across models | `sensorID` in one model, `sensor_id` in another | Standardize on `snake_case` for all field names — see [Naming conventions](./naming-conventions) |
| Using Python for native LoT tasks | Python adds overhead for simple publish/get/if operations | Use Python only for math libraries, ML, API calls, or complex parsing |
| Handing out permission flags to open up `$SYS/#` | `$SYS` carries broker commands and sensitive data, and its access is gated by permission flags — a flag granted for convenience opens the whole namespace | Leave the three flags unset on device and operator accounts; the broker's locked `$SYS` rules then deny them. Custom Rules cannot tighten `$SYS/#` further — see [Rules syntax](/latest/lot-language/rules/syntax#system-topics-sys) |
| Generic entity names | `Action1`, `Rule1`, `MyRoute` are meaningless in a system with 50 entities | Name by purpose: `MonitorPressure`, `ProtectSysTopics`, `SensorDatabase` |
| `PUBLISH` for internal state | Broadcasts data that only your own Actions need | Use `KEEP TOPIC` for internal state; `PUBLISH` for external subscribers — see [Writing reusable logic](./reusable-logic#internal-state-keep-vs-publish) |
| Monolithic Actions | One Action doing 15 things is hard to test and debug | Split into callable Actions with `INPUT`/`OUTPUT` — see [One Action, One Job](./reusable-logic#one-action-one-job) |

***

## Next Steps

> **[Naming conventions](/latest/lot-language/usage-patterns/naming-conventions)**
>
> Entity, variable, and topic naming standards.

> **[Writing reusable logic](/latest/lot-language/usage-patterns/reusable-logic)**
>
> Callables, wildcards, and KEEP vs PUBLISH patterns.


# Designing your data layer
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/data-layer

Topic trees (UNS), payload formats (scalar vs JSON), Models, and inheritance — patterns for how data is shaped and addressed.

## Designing Your Topic Tree

Your topic tree is the backbone of every Coreflux project. It decides how Actions trigger, how Models publish, how Connectors map data into databases, and how dashboards subscribe. Get it right early and the system stays clean as it grows. Get it wrong and you'll be untangling spaghetti for years.

A **Unified Namespace (UNS)** is the idea that every piece of data in your system has one predictable address — a single MQTT topic — that any consumer can subscribe to without knowing or caring where the data physically came from. The concept applies to any domain: a factory floor, an office tower, a solar park, a city's traffic lights, or a fleet of delivery trucks.

> [!TIP]
>
> **Like a postal address that works anywhere in the world.** "Country / State / City / Street / Building / Apartment" lets a letter find any home, even one the postman has never visited. A UNS does the same for your data — a fresh subscriber can read or write to any device without ever being told it exists.

### When to Reach for This

Always — but the deeper hierarchy patterns earn their keep once you have more than a handful of devices, more than one site, or more than one team subscribing to the data. Even a single-device hobby project benefits from a consistent two-level structure.

### Common Principles Across Every UNS

Whatever your domain, a good hierarchy answers three questions:

1. **Who owns this data?** Top levels usually identify the organization or operator.
2. **Where does it physically live?** Middle levels mirror the real-world layout — sites, buildings, zones, machines.
3. **What is it?** The leaves identify the actual measurement, status, or event.

The deeper you go, the more specific the topic. Subscribers can pick exactly the level they care about and ignore the rest.

### Functional namespaces

Organize topics into functional namespaces that reflect the data lifecycle. These prefixes work alongside any domain hierarchy (ISA-95, buildings, fleets):

| Namespace | Purpose | Example Topics |
| - | - | - |
| `sensors/` | Raw incoming sensor data | `sensors/temp001/raw`, `sensors/+/temperature` |
| `processed/` | Transformed or enriched data | `processed/temp001/fahrenheit`, `processed/+/status` |
| `alerts/` | Threshold violations and notifications | `alerts/critical/pump03`, `alerts/+/temperature` |
| `config/` | Configuration values read by Actions | `config/setpoint`, `config/max_temperature` |
| `state/` | Internal persistent state (used with `KEEP`) | `state/counter`, `state/last_run` |
| `cache/` | Cached values for quick reference | `cache/temp001/last_reading` |
| `system/` | Heartbeats, health checks, diagnostics | `system/heartbeat`, `system/status` |
| `commands/` | Inbound instructions from external systems | `commands/devices/+/restart` |

### Designing for Your Domain

Different domains use different hierarchy patterns. Here are five common ones — pick the closest match to yours and adapt.

#### Manufacturing — ISA-95

For factories, the industry standard is **ISA-95**, which divides operations from the enterprise level down to individual machines. The full MQTT path is a single string; the folder view below shows how each **topic level** lines up with **ISA-95** (Enterprise → Site → Area → Line / Cell → Device → **Metric** at the leaf).

`acme/dallas/packaging/line1/filler01/temperature`

```
acme/                               enterprise
└── dallas/                         site
    └── packaging/                  area
        └── line1/                  line / cell
            └── filler01/           device
                └── temperature     metric
```

The ISA-95 levels: **Enterprise / Site / Area / Line / Cell / Device / Metric**. Use it for any project where you have a corporate hierarchy that maps onto a physical plant layout.

#### Smart Buildings

Buildings have a natural physical hierarchy: campus → building → floor → zone → device. The same operator prefix can branch like a folder tree:

```
acmecorp/
└── headquarters/
    ├── floor3/
    │   └── conference_a/
    │       ├── thermostat/
    │       │   └── temperature
    │       └── lighting/
    │           └── state
    └── garage/
        └── level_b1/
            └── sensors/
                └── co2
```

Subscribe to `acmecorp/headquarters/floor3/#` to see every reading on the third floor. Subscribe to `acmecorp/+/+/+/thermostat/temperature` to compare temperatures across every conference room in the company.

#### Energy and Solar Parks

Energy operators typically organize by site, then by physical infrastructure (arrays, strings, inverters). One site can group weather separately from the array:

```
solarop/
└── lisbon-park/
    ├── array-a/
    │   └── string-3/
    │       └── inverter-01/
    │           ├── power
    │           └── voltage
    └── weather/
        └── irradiance

windop/
└── north-sea-cluster/
    └── turbine-12/
        └── rotor_speed
```

A maintenance team subscribes to `solarop/lisbon-park/#` for one park. A fleet operations center subscribes to `solarop/+/+/+/+/power` to monitor every inverter across every park.

#### Smart Cities

Cities organize by district, then by asset type (since asset categories are the meaningful grouping, not departments):

```
lisboa/
├── baixa/
│   ├── traffic_lights/
│   │   └── tl-042/
│   │       └── state
│   └── parking/
│       └── sensor-117/
│           └── occupied
└── parqueeduardo/
    └── air_quality/
        └── aq-03/
            └── pm25

porto/
└── centro/
    └── waste_bins/
        └── bin-218/
            └── fill_level
```

A transport team subscribes to `lisboa/+/traffic_lights/#`. An air quality dashboard subscribes to `+/+/air_quality/#` to see every monitor in every city.

#### Vehicle Fleets

Fleets organize by operator, region, vehicle type, and individual vehicle:

```
deliveryco/
└── iberia/
    ├── vans/
    │   └── v-2840/
    │       ├── location
    │       └── fuel_level
    └── refrigerated/
        └── r-118/
            └── temperature
```

A regional dispatcher subscribes to `deliveryco/iberia/#`. A predictive-maintenance system subscribes to `+/+/+/+/engine/diagnostic_codes` across every fleet.

### Optional: Data Classification

Many UNS designs add a classification segment after the device, splitting **measurements**, **state**, **events**, and **alarms** into separate branches under the same device:

```
acmecorp/
└── headquarters/
    └── floor3/
        └── conference_a/
            └── thermostat/
                ├── metrics/
                │   └── temperature
                ├── state/
                │   └── mode
                ├── alarms/
                │   └── sensor_fault
                └── events/
                    └── setpoint_changed
```

This makes it trivial to subscribe to "all alarms in the building" (`acmecorp/headquarters/+/+/+/alarms/#`) without picking up a flood of ordinary readings. Use it when your project has clearly different *kinds* of data per device.

### Don't Over-Engineer Small Projects

A single-room weather station or a hobby solar setup doesn't need six levels of hierarchy. Even a flat `sensors/<device_id>/<metric>` is fine until you have enough scale to need more. Pick a structure that fits today's complexity, and leave room to grow.

***

## Choosing Data Formats

Your topic tree answers **where** data lives. The next decision is **what shape** each message carries — a single value on the payload, a JSON object, structured JSON produced by a **Model**, or **binary protobuf**. These choices are independent: you can mix scalar topics, JSON ingress, Model output, and protobuf edge topics in the same project.

> [!TIP]
>
> **Like labels on shipping boxes.** The address (topic) tells you which shelf it belongs on; the box contents (payload) tell you what's inside. Sometimes one number on the label is enough; sometimes you need a packing list (JSON); sometimes you standardize the box size (Model) so every downstream handler knows what to expect.

### Scalar payloads (value only)

Use a **plain payload** — one number, string, or boolean with no JSON wrapper — when the **topic name already identifies** the measurement and you only ever send one value per message.

| Best for | Example topic | Payload | In Actions |
| - | - | - | - |
| PLC registers, simple sensors, Modbus/OPC-UA mapped tags | `acme/dallas/line1/filler01/temperature` | `23.5` | `PAYLOAD AS DOUBLE` |
| Status flags, on/off | `.../running` | `true` or `1` | `PAYLOAD AS BOOL` |
| Commands with a single argument | `commands/device/restart` | `now` | `PAYLOAD AS STRING` |

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CheckHighTemperature
ON TOPIC "acme/dallas/+/+/+/temperature" DO
    SET "temp" WITH PAYLOAD AS DOUBLE
    IF {temp} > 80 THEN
        PUBLISH TOPIC "alerts/high_temperature" WITH {temp}
```

**Practices:**

* Put meaning in the **topic path** (site, device, metric) so subscribers do not have to parse the body.
* Prefer scalar leaves under `processed/` or your UNS metric level when data is already normalized at the edge.
* Avoid cramming multiple measurements into one topic without JSON — use separate topics or switch to JSON.

### JSON payloads (structured body)

Use **JSON** when one MQTT message carries **several fields**, nested data, or metadata (timestamps, units, quality flags) that do not belong in the topic string.

| Best for | Example topic | Payload shape |
| - | - | - |
| Devices, gateways, REST/webhook Connectors | `sensors/temp001/telemetry` | `{"temperature":23.5,"humidity":65,"unit":"celsius"}` |
| Partner APIs with variable schemas | `integrations/partner/events` | Nested objects and arrays |

In **Actions**, extract fields with [`GET JSON`](/latest/lot-language/actions/operations#get-json). For nested paths, missing keys, and publishing cleaned JSON from an Action, see **[Working with JSON](/latest/lot-language/usage-patterns/working-with-json)** — that page is the hands-on guide; this section is about when to choose JSON at the data-layer level.

**Practices:**

* Keep **raw JSON** on ingress topics (`sensors/`, `integrations/`) and publish **normalized** data to `processed/` (scalar or Model output) so dashboards and databases see a stable shape.
* Always cast types in Actions (`AS DOUBLE`, `AS STRING`) — do not rely on implicit conversion.
* If many consumers need the same JSON schema, promote the shape with a Model instead of rebuilding JSON manually in every Action.

### Protobuf payloads (binary body)

Use **protobuf** when a gateway or SCADA system already speaks a `.proto` on MQTT. Decode with [`GET PROTO`](/latest/lot-language/actions/operations#get-proto) and emit bytes with `PUBLISH MODEL` on a `WITH FORMAT PROTOBUF` model. Tag topics in the middle can stay JSON. Guide: [Protobuf Models](/latest/lot-language/models/protobuf).

### Models (typed, consistent output)

A **Model** defines the JSON schema your broker publishes — field names, types, and triggers. Use Models when **multiple subscribers** (Connectors, dashboards, other Actions) must see the **same structure** every time.

| Approach | When to use | How it publishes |
| - | - | - |
| **Triggered Model** (`WITH TOPIC` + `AS TRIGGER`) | One device type, automatic publish when a source field updates | Broker builds JSON when the trigger field changes |
| **COLLAPSED Model** + `PUBLISH MODEL` from an Action | You control timing, destination, or merge JSON + scalar sources | Action decides when and where to publish |
| **Base + `FROM` inheritance** | Families of devices share most fields | See [Standardizing data across device types](#standardizing-data-across-device-types) below |

Triggered example — raw scalar in, structured JSON out:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorReading WITH TOPIC "acme/dallas/line1/filler01/formatted"
    ADD STRING "device_id" WITH "filler01"
    ADD DOUBLE "temperature" WITH TOPIC "acme/dallas/line1/filler01/temperature" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

Action-driven example — JSON in, COLLAPSED Model out (full walkthrough in [Working with JSON](/latest/lot-language/usage-patterns/working-with-json#end-to-end-extract-json-and-publish-a-model)):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ProcessedSensorReading COLLAPSED
    ADD STRING "device_id"
    ADD DOUBLE "temperature"
    ADD STRING "unit"
    ADD STRING "timestamp"

DEFINE ACTION NormalizeTelemetry
ON TOPIC "sensors/+/telemetry" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    PUBLISH MODEL ProcessedSensorReading TO "processed/" + {sensor_id} WITH
        device_id = {sensor_id}
        temperature = {temp}
        unit = "celsius"
        timestamp = TIMESTAMP "UTC"
```

**Practices:**

* Use **scalar topics** for simple ingestion; use **Models** for the contract your analytics and APIs depend on.
* Do not hand-build JSON strings in Actions when `PUBLISH MODEL` can do it — fewer quoting bugs and consistent field names.
* Mark the **primary measurement** as `AS TRIGGER`, not timestamps or metadata ([schema definition](/latest/lot-language/models/schema-definition)).
* Exploding incoming JSON into per-field topics (Models overview) helps when other Models or Actions need single fields without `GET JSON` on every step — see [Models overview](/latest/lot-language/models/overview).

### How the three formats work together

A common pipeline:

1. **Ingress** — device sends JSON to `sensors/+/telemetry` (or scalar to `.../temperature`).
2. **Action** — optional `GET JSON`, validation, unit conversion.
3. **Model** — publishes stable JSON to `processed/+/formatted` (or triggered Model from scalar sources).
4. **Connector** — stores `processed/#` or specific leaves in a database.

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart LR
  device[Device or Connector]
  rawTopic[Raw topic scalar or JSON]
  action[Action optional]
  model[Model]
  processed[processed/ topics]
  consumers[Dashboards Connectors Actions]

  device --> rawTopic
  rawTopic --> action
  rawTopic --> model
  action --> model
  model --> processed
  processed --> consumers
```

| If your payload is… | Prefer | Avoid |
| - | - | - |
| One number per topic | Scalar + topic semantics | JSON with a single `"value"` field unless the device forces it |
| Multiple fields per message | JSON ingress + Action or Model | Parsing JSON with string splits in Actions |
| Same schema for many consumers | Model on `processed/` | Copy-pasting JSON templates in five Actions |
| Variant device types | Base Model + `FROM` | Separate unrelated schemas per device |

***

## Standardizing Data Across Device Types

When several devices in your system share most of their data fields but each has a few extras, define the shared fields in a **base Model**, then extend it for each variant. A LoT Model is essentially a typed schema that publishes structured JSON onto a topic. Inheritance works exactly like in object-oriented programming — the base holds what's common, the children add what's specific. Full reference: [Model Inheritance](/latest/lot-language/models/model-inheritance).

> [!TIP]
>
> **Like a base recipe for bread dough.** Sourdough, focaccia, and pizza all start from the same base — they just add their own toppings. Improve the base recipe, and every variant gets the improvement automatically.

### When to Reach for This

When your system has more than one *kind* of device that mostly produces the same data — pumps and chillers, vans and trucks, conference rooms and labs. The break-even point is around three variants: at two it's still tempting to copy-paste, at three the inheritance pays off, at five it's the only sane way.

### The Pattern

A smart-building example: every room in the building has temperature, humidity, and occupancy sensors. But conference rooms also need to track presentation equipment, and labs need extra safety monitoring. Start with the shared base — it's `COLLAPSED`, meaning it doesn't publish on its own and exists only to be inherited:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL BaseRoom COLLAPSED
    ADD STRING "room_id"
    ADD DOUBLE "temperature"
    ADD DOUBLE "humidity"
    ADD INT "occupancy"
    ADD STRING "status"
    ADD STRING "timestamp"
```

A standard office uses the base directly. Specialized rooms extend it using `FROM`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ConferenceRoom FROM BaseRoom
    ADD BOOL "projector_on"
    ADD BOOL "video_call_active"
    ADD INT "scheduled_meetings"

DEFINE MODEL Lab FROM BaseRoom
    ADD BOOL "fume_hood_running"
    ADD DOUBLE "co2_ppm"
    ADD STRING "hazmat_status"
```

`ConferenceRoom` automatically has all six fields from `BaseRoom` plus three of its own. `Lab` gets the six base fields plus three lab-specific ones. If you later add a `last_cleaned` field to `BaseRoom`, every child Model gains it without any edits.

**Two rules of thumb for designing the base:**

* Put a field in the base only if **every variant** truly needs it. Identifiers, timestamps, status, and core measurements belong in the base. Type-specific fields belong in the children.
* Don't put `AS TRIGGER` on a base Model field. The base exists to be inherited — it's the children that decide when and how they publish, either through their own trigger or via `PUBLISH MODEL` from an Action.

The payoff: every team consuming room data — facilities dashboards, energy management, AI agents — sees a consistent shape. They can rely on `room_id`, `temperature`, and `occupancy` being there for any room, and only need to handle the extra fields for variants they actually care about.

The same pattern fits anywhere you have a family of related devices: `BaseInverter` with grid-tied and hybrid variants in solar, `BaseSensor` with temperature, vibration, and pressure variants in industrial, `BaseVehicle` with van, truck, and refrigerated variants in fleets.

For JSON-heavy ingress before you standardize with Models, see [Choosing data formats](#choosing-data-formats) and [Working with JSON](/latest/lot-language/usage-patterns/working-with-json).

***

## Next Steps

> **[Working with JSON](/latest/lot-language/usage-patterns/working-with-json)**
>
> GET JSON patterns, nested payloads, and PUBLISH MODEL workflows.

> **[Model Inheritance](/latest/lot-language/models/model-inheritance)**
>
> Deep dive on `FROM`, base models, and extending schemas.


# Connecting to the outside world
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/integrations

REST server and client Connectors, database KPIs, and ENV/Secrets for integrations.

## Letting Web Apps Send Data to MQTT

Sometimes the data you need isn't coming from a sensor — it's coming from a web app, a mobile app, a partner's webhook, or a system that only speaks HTTP. Coreflux's `REST_API` connector can run in **server mode**, exposing an HTTP endpoint on the broker itself. When something POSTs to that endpoint, the connector publishes the body to an MQTT topic, just like a sensor message.

> [!TIP]
>
> **Like leaving a drop box at the front door.** Anyone with the right key can drop a package in, and once it's inside, it's handled the same way as everything else.

### When to Reach for This

* A web dashboard or mobile app needs to push commands or readings without implementing an MQTT client
* A third-party service (Stripe, GitHub, Slack, your CRM, an IoT vendor's cloud) supports HTTP webhooks but not MQTT
* A legacy system can call HTTP endpoints but doesn't speak MQTT
* You're behind a firewall that allows HTTP but not MQTT

### The Pattern

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WebhookIngest WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH ENABLE_SERVER "true"
        WITH SERVER_PORT '8080'
        WITH USERNAME GET ENV "WEBHOOK_USER"
        WITH PASSWORD GET SECRET "WEBHOOK_TOKEN"
        WITH ENABLE_CORS "true"
    ADD EVENT ReceiveSensorReading
        WITH ENDPOINT "/api/sensors"
        WITH METHOD "POST"
        WITH DESTINATION_TOPIC "sensors/from/http"
```

How it works:

1. The connector opens an HTTP server on port 8080.
2. When something POSTs to `http://your-broker:8080/api/sensors` with the right Basic Auth credentials, the body of the request is published to `sensors/from/http`.
3. From there, any Action subscribed to that topic processes it like a normal MQTT message — type-cast, normalize, publish into your UNS, store in the database.

A web app sending a reading would do something like:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
curl -X POST http://broker.example.com:8080/api/sensors \
  -u "$WEBHOOK_USER:$WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sensor_id": "temp-01", "value": 25.5}'
```

And an Action on the broker normalizes it into the UNS:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION RouteWebhookReading
ON TOPIC "sensors/from/http" DO
    SET "sensor_id" WITH (GET JSON "sensor_id" IN PAYLOAD AS STRING)
    SET "value" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    PUBLISH TOPIC "acmecorp/headquarters/floor3/sensors/" + {sensor_id} + "/temperature" WITH {value}
```

That's the whole pattern. The web app doesn't need an MQTT library, the broker doesn't need an external middleware service, and the credentials sit safely in `ENV` and `SECRET`. Use the same approach for receiving CRM events, payment notifications, AI service callbacks, or anything else the outside world wants to push to you.

***

## Pulling Data from External APIs

The mirror image of webhook ingestion: when *you* need to call out to a third-party API. The same `REST_API` connector in **client mode** turns an MQTT message into an outbound HTTP request, then publishes the response back to MQTT. Combined with `GET ENV` and `GET SECRET`, the credentials never appear in the connector definition.

> [!TIP]
>
> **Like a vending machine.** Drop the right token in (an MQTT request), and the answer pops out a slot below (an MQTT response).

### When to Reach for This

Whenever a Coreflux system needs information that lives outside it: weather forecasts for HVAC control, exchange rates for billing, geocoding for a fleet, traffic data for routing, AI/ML inference, public data feeds.

### The Pattern

Weather data is useful in nearly every domain — solar parks need irradiance forecasts, smart buildings adjust HVAC for outdoor temperature, fleets reroute around storms, agriculture schedules irrigation. Here's a connector that calls a weather API. The base URL and credentials come from environment variables and secrets, so the same connector works in dev and prod:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR WeatherAPI WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS GET ENV "WEATHER_API_URL"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH USERNAME GET ENV "WEATHER_API_USER"
        WITH PASSWORD GET SECRET "WEATHER_API_KEY"
        WITH REQUEST_TIMEOUT '30'
    ADD EVENT GetCurrentWeather
        WITH SOURCE_TOPIC "weather/request"
        WITH DESTINATION_TOPIC "weather/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/current?location={value.json.location}"
```

How it works:

1. Some Action publishes a JSON message like `{"location": "Lisbon"}` to `weather/request`.
2. The connector picks it up, builds the URL with the location filled in, and fires an authenticated HTTP GET.
3. The API responds with the weather data.
4. The connector publishes that response to `weather/response`.

Trigger it from any Action — say, every fifteen minutes:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION FetchWeather
ON EVERY 15 MINUTES DO
    PUBLISH TOPIC "weather/request" WITH '{"location":"Lisbon"}'
```

Then handle the response in another Action that subscribes to `weather/response`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION StoreWeather
ON TOPIC "weather/response" DO
    SET "temp" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    SET "humidity" WITH (GET JSON "humidity" IN PAYLOAD AS DOUBLE)
    PUBLISH TOPIC "processed/weather/temperature" WITH {temp}
    PUBLISH TOPIC "processed/weather/humidity" WITH {humidity}
```

The HTTP credentials sit encrypted in `secrets.json`, the API URL sits in `.env`, and the Connector definition stays portable across deployments. If the API key rotates, you update the secret and nothing else changes.

***

## Live KPIs from a Database

Database connectors are not just for inserting data. The same `EVENT` syntax supports `SELECT` queries — either triggered by an MQTT message or run on a fixed schedule. This is how you turn a historian into a live KPI feed: one query, repeated automatically, results published as ordinary MQTT messages that any consumer can subscribe to.

> [!TIP]
>
> **Like a live scoreboard at a stadium.** The board updates every minute with fresh totals, and everyone in the stadium sees the same numbers without having to do the math themselves.

### When to Reach for This

When you need rolling KPIs (averages, counts, peaks) that consumers should subscribe to like any other topic, or when you need on-demand historical lookups (last hour of readings for a device) triggered by an MQTT request. Skip it for one-off ad-hoc queries — for those, just query the database directly.

### Scheduled Queries: Live Aggregates

A common need in solar operations: publish the **average power output of the last 60 seconds** every minute, for every inverter, with no polling code anywhere.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR InverterKpis WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER GET ENV "DB_HOST"
        WITH PORT GET ENV "DB_PORT"
        WITH DATABASE "energy_data"
        WITH USERNAME GET ENV "DB_USER"
        WITH PASSWORD GET SECRET "DB_PASSWORD"
    ADD EVENT AvgPowerLast60s
        WITH EVERY 60 SECONDS
        WITH DESTINATION_TOPIC "kpi/inverters/avg_power_60s"
        WITH QUERY "SELECT inverter_id, AVG(power_kw) AS avg_power FROM inverter_readings WHERE ts > NOW() - INTERVAL '60 seconds' GROUP BY inverter_id"
```

What happens here:

1. Every 60 seconds, the connector automatically runs the SQL query against your historian.
2. The result set is serialized as JSON and published to `kpi/inverters/avg_power_60s`.
3. Anyone listening — a dashboard, an Action, an AI agent — sees a fresh KPI every minute as a regular MQTT message.

No polling code, no glue script, no scheduler to maintain. The SQL is the schedule.

### On-Demand Queries: Historical Lookups

For queries that should run when *asked* rather than on a clock, swap `WITH EVERY` for `WITH SOURCE_TOPIC`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
    ADD EVENT GetInverterHistory
        WITH SOURCE_TOPIC "kpi/request/history"
        WITH DESTINATION_TOPIC "kpi/result/history"
        WITH QUERY "SELECT ts, power_kw FROM inverter_readings WHERE inverter_id = '{payload}' AND ts > NOW() - INTERVAL '1 hour' ORDER BY ts"
```

Now publishing `inv-01` to `kpi/request/history` returns the last hour of readings on `kpi/result/history`. Operators, AI agents, or other systems can pull historical context on demand.

**The pattern at a glance:** raw data lives in the database, KPIs and historical lookups are exposed as MQTT topics. Whether you're tracking solar inverters, traffic light timings, or refrigerated truck temperatures, your dashboards and downstream consumers don't care where the data physically lives — they just subscribe to topics like everything else.

***

## Keeping Credentials Out of Your Code

Never hardcode database passwords, API keys, or broker credentials in your code. Coreflux gives you two runtime stores — one for ordinary configuration, one for secrets that need to be encrypted.

> [!TIP]
>
> **Like the difference between leaving your keys taped to the front door versus keeping them in a safe.** ENV is the wallet you carry openly (which city, which port, which feature flag). Secrets is the safe you only open when you need it (passwords, API keys, tokens).

### When to Reach for This

The first time you deploy outside your laptop — or earlier if you're committing your notebook to git from day one. Get the habit before you have any real credentials in flight; retrofitting `GET SECRET` into a working system is more painful than starting with it.

### The Two Operations

* `GET ENV "NAME"` reads from a managed `.env` file. Use it for non-sensitive configuration: hostnames, ports, region tags, feature flags. Safe to log.
* `GET SECRET "NAME"` reads from `secrets.json`, which is encrypted at rest with AES-256-GCM. Use it for anything sensitive: passwords, API keys, tokens. Never logged.

Both can be referenced directly inside Connector configurations, which is exactly where you need them most:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ProductionDB WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER GET ENV "DB_HOST"
        WITH PORT GET ENV "DB_PORT"
        WITH DATABASE GET ENV "DB_NAME"
        WITH USERNAME GET ENV "DB_USER"
        WITH PASSWORD GET SECRET "DB_PASSWORD"
        WITH USE_SSL "true"
    ADD EVENT StoreSensorReading
        WITH SOURCE_TOPIC "sensors/+/reading"
        WITH QUERY "INSERT INTO readings (ts, sensor_id, value) VALUES (NOW(), '{sensor_id}', '{value.json}')"
```

The same Connector definition now works in development, staging, and production — only the `.env` file and `secrets.json` differ between environments.

To register a secret, run this once from a notebook or the broker console:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
KEEP SECRET "DB_PASSWORD" WITH "your-actual-password"
```

After that, the password lives encrypted on the broker. Your connector definitions, your git history, your AI assistant transcripts, and your logs all stay clean.

***

## Next Steps

> **[REST API Connectors](/latest/lot-language/routes/rest-api-routes)**
>
> Client and server mode, endpoints, and authentication.

> **[Environment Variables and Secrets](/latest/mqtt-broker/secrets-and-env)**
>
> `.env`, `secrets.json`, and secure deployment.


# Naming conventions
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/naming-conventions

PascalCase entities, snake_case variables and fields, and topic naming basics for maintainable LoT systems.

## Why naming matters

Consistent naming is the single most impactful practice for maintainable LoT systems. These conventions apply to all LoT entities and keep notebooks readable as your project grows.

> [!TIP]
>
> **Like street names in a city.** Predictable patterns let anyone find an address without a map — and let AI assistants generate code that matches your project.

***

## Entity names

All LoT entities use **PascalCase**. Names should be descriptive and purpose-driven.

| Entity | Convention | Good Examples | Bad Examples |
| - | - | - | - |
| Actions | PascalCase, verb-first | `ProcessTemperature`, `MonitorPressure`, `SendDailyReport` | `temp_process`, `action1`, `myAction` |
| Models | PascalCase, noun-based | `SensorReading`, `EquipmentStatus`, `ProductionRecord` | `sensor_model`, `Model1`, `data` |
| Rules | PascalCase, descriptive scope | `AllowAdminActions`, `ProtectSysTopics`, `RestrictDevicePublish` | `Rule1`, `myRule`, `newRule` |
| Connectors | PascalCase, destination-based | `CloudBridge`, `SensorDatabase`, `AlertEmail` | `route1`, `my_route`, `dbRoute` |
| Callable Actions | PascalCase, function-like | `CalculateAverage`, `ConvertCelsiusToFahrenheit` | `calc`, `helper`, `util` |

***

## Variable names

Variables use **snake\_case** inside double quotes for `SET` declarations, and **curly braces** for references.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessSensorData
ON TOPIC "sensors/+/raw" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "raw_value" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    SET "converted_value" WITH ({raw_value} * 1.8 + 32)
    PUBLISH TOPIC "processed/" + {sensor_id} + "/fahrenheit" WITH {converted_value}
```

| Context | Convention | Examples |
| - | - | - |
| Declaration (`SET`) | `snake_case` in double quotes | `"sensor_id"`, `"raw_value"`, `"cycle_time"` |
| Reference | Curly braces | `{sensor_id}`, `{raw_value}`, `{cycle_time}` |
| Model fields | `snake_case` in double quotes | `"equipment_id"`, `"runtime_hours"`, `"last_update"` |
| Action inputs | `snake_case` after keyword | `INPUT value AS DOUBLE`, `INPUT threshold AS DOUBLE` |

***

## Topic names

Topics use **lowercase with forward-slash separators**. Multi-word segments use **snake\_case**.

Whenever possible, follow a **Unified Namespace (UNS)** format for topic naming. This enables readability and scalability as systems grow.

| Pattern | Example | Use Case |
| - | - | - |
| `domain/entity/attribute` | `sensors/temperature/value` | General data |
| `domain/instance/attribute` | `sensors/temp001/raw` | Instance-specific data |
| `domain/category/instance` | `alerts/critical/pump03` | Categorized events |
| Prefixed namespaces | `processed/`, `alerts/`, `config/`, `cache/`, `state/`, `system/` | Functional separation |

For hierarchy design, functional namespaces, and domain-specific UNS patterns, see [Designing your data layer](./data-layer).

***

## Next Steps

> **[Designing your data layer](/latest/lot-language/usage-patterns/data-layer)**
>
> Topic trees, payload formats, and model inheritance.

> **[Anti-patterns](/latest/lot-language/usage-patterns/anti-patterns)**
>
> Common mistakes and what to do instead.


# Production architecture
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/production-architecture

End-to-end ingestion and edge-to-cloud bridges — synthesis patterns that pull everything together.

## From Device to Database, End to End

Putting the patterns together, a full ingestion pipeline has four stages, each one a single LoT entity. This is the canonical recipe for "get data from a real device, normalize it, and store it for analytics."

> [!TIP]
>
> **Like a kitchen production line.** The delivery comes in (sensor), the chef cleans and preps (Action), the dish is plated to the same standard every time (Model), and the waiter takes it to the table (Database).

### When to Reach for This

The first time you need persistent, queryable history of your data — usually somewhere between "it works on my laptop" and "we need to show this to the customer." It's also the natural foundation for [Live KPIs from a Database](/latest/lot-language/usage-patterns/integrations#live-kpis-from-a-database) and any reporting or analytics layer you'll add later.

### The Worked Example

A smart-building HVAC chiller, communicating via Modbus, normalized into a unified schema, and stored in PostgreSQL.

#### Stage 1 — Industrial Connector Ingests from the Device

Pick the connector type that matches your protocol: `MODBUS` for HVAC controllers, `OPCUA` for PLCs, `S7` for Siemens, `ALLEN_BRADLEY` for Rockwell, `BACNET` for building automation. Map each register or tag to a UNS topic.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ChillerGateway WITH TYPE MODBUS
    ADD MODBUS_CONFIG
        WITH HOST GET ENV "CHILLER_HOST"
        WITH PORT '502'
        WITH UNIT_ID '1'
    ADD MAPPING coolingPower
        WITH REGISTER '40001'
        WITH DATA_TYPE "FLOAT32"
        WITH DESTINATION_TOPIC "acmecorp/headquarters/floor3/hvac/chiller-01/metrics/cooling_power"
```

#### Stage 2 — Action Processes and Normalizes

Type-cast, scale, validate, then call a Model to produce structured output. A wildcard trigger means the same Action handles every chiller in every building.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION NormalizeChillerReading
ON TOPIC "acmecorp/+/+/hvac/+/metrics/cooling_power" DO
    SET "building" WITH TOPIC POSITION 2
    SET "floor" WITH TOPIC POSITION 3
    SET "device_id" WITH TOPIC POSITION 5
    SET "raw_kw" WITH PAYLOAD AS DOUBLE

    PUBLISH MODEL ChillerReading TO "acmecorp/" + {building} + "/" + {floor} + "/hvac/" + {device_id} + "/processed" WITH
        device_id = {device_id}
        building = {building}
        cooling_power_kw = {raw_kw}
        timestamp = TIMESTAMP "UTC"
```

#### Stage 3 — Model Standardizes the Schema

One JSON shape for every chiller in every building. Add fields here once, every consumer downstream sees them.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL ChillerReading COLLAPSED
    ADD STRING "device_id"
    ADD STRING "building"
    ADD DOUBLE "cooling_power_kw"
    ADD STRING "timestamp"
```

#### Stage 4 — Database Connector Persists

A single insert per published reading. Credentials come from `ENV` and `SECRET` so the connector is portable between environments.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR ChillerHistorian WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER GET ENV "DB_HOST"
        WITH USERNAME GET ENV "DB_USER"
        WITH PASSWORD GET SECRET "DB_PASSWORD"
        WITH DATABASE "building_data"
    ADD EVENT StoreChillerReading
        WITH SOURCE_TOPIC "acmecorp/+/+/hvac/+/processed"
        WITH QUERY "INSERT INTO chiller_readings (ts, device_id, building, cooling_power_kw) VALUES ('{value.json.timestamp}', '{value.json.device_id}', '{value.json.building}', {value.json.cooling_power_kw})"
```

Four entities, one pipeline. Every chiller in every building flows the same way. Adding a new chiller means adding a Mapping in the gateway connector — nothing else changes. Adding a new field to the schema means adding it to `ChillerReading` and updating the SQL — all the Actions stay untouched.

The same four-stage recipe fits any vertical: a solar inverter via Modbus, a traffic light controller via REST, a delivery van via cellular MQTT. Different devices, different protocols, same shape.

***

## Splitting Edge from Cloud with a Bridge

In a typical production setup, the **edge broker** runs on-site and handles all the high-frequency, device-facing work — every reading, every command, every alarm. The **cloud broker** sits centrally and only sees what the business needs to see — minute aggregates, alerts, cross-site rollups. An `MQTT_BRIDGE` connector is what selectively forwards data between the two.

> [!TIP]
>
> **Like a local newspaper sending a daily summary to head office.** The full story stays in the newsroom; only the headlines and totals make the trip to corporate. Cheaper, safer, faster.

### When to Reach for This

| Reason | What it gives you |
| - | - |
| **Bandwidth and cost** | Raw sensor data at 1 Hz from 100 devices is a lot. Aggregating to one summary per minute can shrink uplink traffic by 99% — and your cloud bill with it. |
| **Edge processing speed** | Local alarms react in milliseconds without waiting for a cloud round-trip. Even if the WAN goes down, the edge keeps running. |
| **Resilience** | If the cloud connection drops, the edge buffers and reconnects automatically. Operations never stop because of a flaky uplink. |
| **Data and security boundary** | Sensitive raw data never leaves the site. Only the summarized, business-relevant information crosses the boundary. |
| **Multi-site rollups** | The cloud sees every site through the same shape (`lisbon-park/...`, `madrid-park/...`), enabling cross-site analytics and dashboards without changing edge logic. |

This is the right pattern when you have **multiple sites**, **strict bandwidth or cost limits**, **regulatory or security requirements** to keep raw data local, or **devices that must keep operating during cloud outages**. For a single-site project with a fast and cheap connection, a single broker is simpler.

### What's Where: A Concrete Example

Imagine an edge broker at a solar park with multiple inverters. Each inverter publishes voltage, current, and power readings several times a second. Here's what each broker actually contains:

| Topic on **edge broker** (at the park) | What it is | Goes to cloud? |
| - | - | - |
| `inverters/inv-01/voltage` | Raw reading every second | ❌ Stays local |
| `inverters/inv-01/current` | Raw reading every second | ❌ Stays local |
| `inverters/inv-01/power` | Raw reading every second | ❌ Stays local |
| `inverters/inv-02/power` | Raw reading from another inverter | ❌ Stays local |
| `state/inv-01/last_seen` | Internal state via `KEEP TOPIC` | ❌ Stays local |
| `aggregates/inv-01/1min` | Computed every 60 seconds by an Action | ✅ Forwarded |
| `aggregates/inv-02/1min` | Same, for the second inverter | ✅ Forwarded |
| `alerts/inv-01/low_output` | Threshold alarm | ✅ Forwarded |

| Topic on **cloud broker** (after bridge) | Source |
| - | - |
| `lisbon-park/aggregates/inv-01/1min` | Forwarded from the Lisbon edge |
| `lisbon-park/aggregates/inv-02/1min` | Forwarded from the Lisbon edge |
| `lisbon-park/alerts/inv-01/low_output` | Forwarded from the Lisbon edge |
| `madrid-park/aggregates/inv-A/1min` | Forwarded from a different site |
| ... | (one prefix per park) |

The cloud sees a clean, aggregated, multi-site view. The edge keeps everything raw, locally and privately.

### Step 1: Create the Aggregate at the Edge

An Action on the edge computes a summary every minute, per inverter. This is what gets sent up.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PublishMinuteAggregate
ON EVERY 60 SECONDS DO
    SET "inverter_id" WITH "inv-01"
    SET "avg_power" WITH (GET TOPIC "cache/" + {inverter_id} + "/power_avg" AS DOUBLE)
    SET "peak_power" WITH (GET TOPIC "cache/" + {inverter_id} + "/power_peak" AS DOUBLE)

    PUBLISH MODEL InverterAggregate TO "aggregates/" + {inverter_id} + "/1min" WITH
        inverter_id = {inverter_id}
        avg_power_kw = {avg_power}
        peak_power_kw = {peak_power}
        timestamp = TIMESTAMP "UTC"
```

(The `cache/` topics get filled by other Actions that consume the raw `inverters/` stream — kept internal to the edge using `KEEP TOPIC`.)

### Step 2: Define the Bridge

Three topic mappings. Aggregates and alerts go up; commands come down. Everything else stays local.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR EdgeToCloud WITH TYPE MQTT_BRIDGE
    ADD SOURCE_CONFIG
        WITH BROKER SELF
    ADD DESTINATION_CONFIG
        WITH BROKER_ADDRESS GET ENV "CLOUD_BROKER_HOST"
        WITH BROKER_PORT '8883'
        WITH CLIENT_ID GET ENV "EDGE_SITE_ID"
        WITH USERNAME GET ENV "CLOUD_BROKER_USER"
        WITH PASSWORD GET SECRET "CLOUD_BROKER_PASSWORD"
        WITH USE_TLS "true"
    ADD MAPPING aggregateUplink
        WITH SOURCE_TOPIC "aggregates/#"
        WITH DESTINATION_TOPIC "lisbon-park/aggregates/#"
        WITH DIRECTION "out"
    ADD MAPPING alertUplink
        WITH SOURCE_TOPIC "alerts/#"
        WITH DESTINATION_TOPIC "lisbon-park/alerts/#"
        WITH DIRECTION "out"
    ADD MAPPING commandsDownlink
        WITH SOURCE_TOPIC "lisbon-park/commands/#"
        WITH DESTINATION_TOPIC "commands/#"
        WITH DIRECTION "in"
```

The site prefix (`lisbon-park`) is added on the cloud side, so multiple parks — or buildings, or cities, or fleet regions — can coexist on the same cloud broker without topic collisions.

### Complementary Patterns on the Cloud

Once the cloud is receiving aggregates and alerts as MQTT topics, you can compose more patterns on top of it:

* **Cloud database connector for central analytics.** Add a PostgreSQL or CrateDB connector on the cloud broker that subscribes to `+/aggregates/#` and inserts into a multi-site table. Now you have one historian with data from every site, queryable for trends, capacity planning, and cross-park benchmarks. The exact same `EVENT ... QUERY` pattern from the [Live KPIs from a Database](/latest/lot-language/usage-patterns/integrations#live-kpis-from-a-database) section works here.
* **Cloud dashboards.** Coreflux HUB Dashboards on the cloud broker subscribe to `+/aggregates/#` and `+/alerts/#` to give corporate or operations teams a unified view of every site.
* **Cross-site KPIs.** A scheduled `EVENT` on the cloud's database can publish company-wide KPIs (`SELECT AVG(...) GROUP BY site_id`) as MQTT topics, just like a single-site KPI — but rolled up across the whole portfolio.
* **AI / MCP connectors on the cloud.** Plug an `AGENT` connector into the cloud broker so an AI assistant can answer questions about the entire fleet without ever needing to touch the edge.

The bridge is the boundary; everything above it is business; everything below it is operations. Each side can evolve independently.

***

## Next Steps

> **[Data Storage Connectors](/latest/lot-language/routes/data-storage/overview)**
>
> Historians, inserts, and scheduled queries across database types.

> **[Connecting to the outside world](/latest/lot-language/usage-patterns/integrations)**
>
> REST, KPIs, and credentials from this guide.


# Project organization
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/project-organization

Keeping LoT notebooks clean, readable, and reviewable — single-file vs multi-file layouts.

## Keeping Notebooks Clean and Readable

A well-organized notebook is living documentation. Six months from now, a teammate (or you) should be able to open the file and immediately understand what every cell does and why.

> [!TIP]
>
> **Like a well-kept recipe binder.** Each chapter has a clear theme, every recipe has a one-line description above the ingredients, and you can find anything in seconds because nothing's jumbled together.

### When to Reach for This

From day one, regardless of project size. Good notebook discipline is cheap to start and expensive to retrofit — by the time your single notebook is hard to navigate, splitting it up means re-reading every cell to figure out where it belongs.

### Single File or Multiple Files?

There's no single right answer — it's a project preference. Both approaches are valid, and both can produce clean, maintainable systems.

| Approach | Best for | Pros | Trade-offs |
| - | - | - | - |
| **Single file** | Small projects, demos, single-concern systems, getting started | Easy to share and review, everything in one place, simple to deploy as a unit | Long files take longer to navigate, harder to deploy parts selectively, awkward for teams editing in parallel |
| **Multiple files in a folder** | Larger projects, multi-concern systems, team collaboration | Easy to find specific concerns, parallel work without conflicts, selective deployment per file | More files to track, requires a clear naming convention |

A small smart-thermostat demo or a single-greenhouse irrigation controller probably belongs in one notebook. A multi-site solar park monitoring platform with industrial connectors, normalization, alarms, and storage usually wants the folder layout. When in doubt, start single-file and split when it stops feeling comfortable.

The discipline below applies to both approaches.

### Cell Discipline (Applies Either Way)

A few habits make notebooks self-explanatory regardless of how many files you have:

* **One markdown cell before every LoT cell.** State what the next cell does, why it exists, and what topics it reads or publishes. The markdown cell is the contract; the LoT cell is the implementation.
* **One definition per LoT cell.** One Action, one Model, or one Connector per cell — never bundled. This makes selective re-deployment trivial and keeps execution traces readable.
* **Section headers as standalone markdown cells.** Use `##` headers to break content into logical sections (`## Inverter Models`, `## Aggregation Actions`, `## Alarm Logic`). VS Code's outline view turns these into a clickable table of contents within the file.
* **An intro markdown cell at the top.** What's in this file, what other notebooks (if any) it depends on, what topics it owns.

### Single-File Layout

When everything lives in one notebook, lean on section headers to keep it navigable:

```
my-thermostat-demo.lotnb
├── # Smart Thermostat Demo (intro markdown cell)
├── ## Models
│   └── (LoT cells: each Model in its own cell, with markdown above)
├── ## Connectors
│   └── (LoT cells: each Connector in its own cell)
├── ## Processing Actions
│   └── (LoT cells: one Action per cell)
└── ## Alarm Actions
    └── (LoT cells: alarm logic with markdown context)
```

Read top to bottom: it's a self-contained tour of your system.

### Multi-File Layout

For larger projects, one notebook per concern. Numbering reflects the deploy order — define Models before the Actions that publish them, define Connectors before the Actions that trigger them.

```
my-solar-park/
├── 00_overview.lotnb           // What this project does, who it's for
├── 01_models.lotnb             // All Model definitions
├── 02_routes_ingestion.lotnb   // Industrial connectors, REST clients
├── 03_actions_processing.lotnb // Normalization, calculations
├── 04_actions_alarms.lotnb     // Threshold detection, alerts
├── 05_routes_storage.lotnb     // Database and bridge connectors
├── 06_rules.lotnb              // Access control
├── AGENTS.md                   // AI assistant conventions
└── README.md                   // How to deploy
```

Inside each file, the same cell discipline applies: section headers, markdown before each LoT cell, one definition per cell.

### What This Looks Like in Practice

A snippet from a Models notebook (or the `## Models` section of a single-file project):

> ## Inverter Models
>
> Standard schemas for every inverter in the fleet. The base model `BaseInverter` is the contract — every inverter variant inherits from it. Used by the processing actions and stored by the historian connector.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL BaseInverter COLLAPSED
    ADD STRING "inverter_id"
    ADD DOUBLE "power_kw"
    ADD DOUBLE "voltage"
    ADD STRING "timestamp"
```

> Hybrid inverter variant — adds battery state for sites with on-site storage.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL HybridInverter FROM BaseInverter
    ADD DOUBLE "battery_soc"
    ADD DOUBLE "battery_power_kw"
```

Each LoT cell has a markdown cell right above it explaining the *why*. Six months from now, you'll thank past-you.

### Treat Notebooks Like Code

`.lotnb` files are text — diff them, branch them, review them. Commit your notebooks to git alongside your `AGENTS.md` and `README.md`. When a teammate joins, the project's git repository is everything they need to understand and reproduce the system.

Pair the notebooks with an `AGENTS.md` at the project root so AI assistants generate code that matches your conventions automatically. See [AI-Assisted Development Best Practices](/ai/best-practices) for the template.

***

## Next Steps

> **[LoT Notebooks Usage](/lot-notebooks/usage)**
>
> Installing and running the VS Code extension.

> **[AI-Assisted Development](/ai/best-practices)**
>
> Conventions for `AGENTS.md` and AI-generated LoT.


# Writing reusable logic
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/reusable-logic

Callable actions, wildcards, counters, and Python — techniques for Actions that scale and stay maintainable.

## Building a Library of Reusable Logic

Any Action without a trigger clause is a **callable** — a reusable function with typed inputs and outputs. Build a small library of utility callables for the calculations and transformations your project does repeatedly, then call them from your trigger-based Actions.

> [!TIP]
>
> **Like saving a custom button on a calculator.** You don't rebuild the multiplication function every time you need to multiply — you press the button. Callables are your custom buttons, named after exactly what they do.

### When to Reach for This

The moment you write the same expression a second time, or any time a logic block deserves its own name to make the parent Action readable. Also useful when several Actions need to share a calculation that might evolve over time — fix it in the callable, and every caller is updated.

### The Pattern

A callable has three parts: declared inputs, the logic that runs, and declared outputs to return:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CalculatePercentage
INPUT value AS DOUBLE
INPUT total AS DOUBLE
DO
    SET "pct" WITH ({value} / {total} * 100)
RETURN
    OUTPUT pct
```

Supported `INPUT` types are `STRING`, `INT`, `DOUBLE`, `BOOL`, and `JSON`. A callable can return one or many `OUTPUT` values — the caller names the return variables in the order they're declared.

Here's a callable that returns three values from one calculation:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION AnalyzeReading
INPUT current AS DOUBLE
INPUT threshold AS DOUBLE
DO
    SET "is_above" WITH ({current} > {threshold})
    SET "difference" WITH ({current} - {threshold})
    SET "percent_of_max" WITH ({current} / {threshold} * 100)
RETURN
    OUTPUT is_above
    OUTPUT difference
    OUTPUT percent_of_max
```

Now a regular trigger-based Action can use both callables instead of duplicating the math itself. Whether you're tracking water tanks on a farm, fuel storage at a depot, or chemical reservoirs at a plant — the logic is the same:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessTankLevel
ON TOPIC "tanks/+/level" DO
    SET "tank_id" WITH TOPIC POSITION 2
    SET "level" WITH PAYLOAD AS DOUBLE
    SET "capacity" WITH (GET TOPIC "config/" + {tank_id} + "/capacity" AS DOUBLE)

    CALL ACTION CalculatePercentage
        WITH value = {level}, total = {capacity}
        RETURN fill_pct

    CALL ACTION AnalyzeReading
        WITH current = {level}, threshold = ({capacity} * 0.9)
        RETURN above, diff, pct_of_max

    PUBLISH TOPIC "processed/" + {tank_id} + "/fill_percent" WITH {fill_pct}
    PUBLISH TOPIC "processed/" + {tank_id} + "/over_threshold" WITH {above}
```

The main Action stays focused on *what to do* (read level, publish results); the callables hold *how to calculate*. If the percentage formula changes, you fix it in one place.

***

## One Action, One Job

Each Action should do **one thing well**. Break complex logic into callable Actions with `INPUT`/`OUTPUT`:

**Good: Modular**

Separate reusable logic into callable Actions, then compose them in a main Action:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ConvertCelsiusToFahrenheit
INPUT celsius AS DOUBLE
DO
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
RETURN
    OUTPUT fahrenheit

DEFINE ACTION ProcessTemperatureReading
ON TOPIC "sensors/+/celsius" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp_c" WITH PAYLOAD AS DOUBLE

    CALL ACTION ConvertCelsiusToFahrenheit
        WITH celsius = {temp_c}
        RETURN temp_f

    PUBLISH TOPIC "sensors/" + {sensor_id} + "/fahrenheit" WITH {temp_f}
```

**Bad: Monolithic**

All logic crammed into one Action, no reuse:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION DoEverything
ON TOPIC "sensors/+/celsius" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp_c" WITH PAYLOAD AS DOUBLE
    SET "temp_f" WITH ({temp_c} * 9 / 5 + 32)
    SET "temp_k" WITH ({temp_c} + 273.15)
    SET "max" WITH (GET TOPIC "config/max_temperature" AS DOUBLE)
    SET "pct" WITH ({temp_c} / {max} * 100)
    IF {temp_c} > {max} THEN
        PUBLISH TOPIC "alerts/" + {sensor_id} WITH "High"
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/fahrenheit" WITH {temp_f}
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/kelvin" WITH {temp_k}
    PUBLISH TOPIC "sensors/" + {sensor_id} + "/capacity" WITH {pct}
```

***

## Internal State: KEEP vs PUBLISH

Use `KEEP TOPIC` for internal persistent state and `PUBLISH TOPIC` for external broadcast. Never use `PUBLISH` for values only your system reads:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION PersistentCounter
ON EVERY 10 SECONDS DO
    SET "current" WITH (GET TOPIC "state/counter")
    IF {current} == EMPTY THEN
        KEEP TOPIC "state/counter" WITH 1
    ELSE
        KEEP TOPIC "state/counter" WITH ({current} + 1)
    PUBLISH TOPIC "stats/count" WITH (GET TOPIC "state/counter")
```

| Operation | Use When |
| - | - |
| `PUBLISH TOPIC` | Other systems or subscribers need to see the value. Add `RETAIN` when new subscribers must receive the last payload |
| `KEEP TOPIC` | Only your own Actions read the value with `GET TOPIC` (broker-internal cache: counters, last-known values). Never sets the MQTT retain flag |

***

## One Action for Many Devices

The moment you find yourself about to copy-paste an Action and change one device ID, stop. Use a **wildcard** — the MQTT character `+` matches exactly one topic level, so `sensors/+/power` matches `sensors/inv-01/power`, `sensors/inv-47/power`, and any other topic with that shape. The broker fires your Action once per matching message, and `TOPIC POSITION` lets you read which device the message came from.

### Wildcard guidelines

| Wildcard | Meaning | Where to Use |
| - | - | - |
| `+` | Matches exactly one level | Action triggers, Model topics, Connector mappings |
| `#` | Matches one or more levels | Connector mappings, Rule topic patterns, broad subscriptions |

Use `+` in **Actions and Models** for precise instance matching. Use `#` in **Connectors and Rules** for broad coverage.

> [!TIP]
>
> **Like writing a form letter that says "Dear customer."** One letter, delivered to thousands, and each recipient feels it's addressed to them.

### When to Reach for This

The moment you have two or more devices that should be processed the same way. Wildcards are also the foundation that makes [Models that publish for every device](/latest/lot-language/usage-patterns/data-layer#standardizing-data-across-device-types) work — and they let new devices join your system without any code changes.

### The Pattern

Imagine a solar park with a hundred inverters, each publishing power readings. One Action handles all of them:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessInverterPower
ON TOPIC "inverters/+/power" DO
    SET "inverter_id" WITH TOPIC POSITION 2
    SET "power_w" WITH PAYLOAD AS DOUBLE
    SET "power_kw" WITH ({power_w} / 1000)

    PUBLISH TOPIC "processed/" + {inverter_id} + "/power_kw" WITH {power_kw}
    KEEP TOPIC "cache/" + {inverter_id} + "/last_seen" WITH TIMESTAMP "UTC"
```

> [!TIP]
>
> **On `KEEP TOPIC` in this example.** The last-seen line uses [`KEEP TOPIC`](/latest/lot-language/actions/operations) instead of `PUBLISH TOPIC`. `KEEP TOPIC` stores a value for `GET TOPIC` in the broker cache and does not set the MQTT retain flag. Use `KEEP` for internal state other Actions read later — counters, last-seen timestamps, alarm flags — not for data every dashboard must see live. Use `PUBLISH TOPIC ... RETAIN` when new subscribers must receive the last payload.

Walk through what's happening:

1. The trigger `inverters/+/power` matches `inverters/inv-01/power`, `inverters/inv-47/power`, and any other topic that fits.
2. `TOPIC POSITION 2` reads whatever the `+` matched — so on one trigger it's `inv-01`, on the next it's `inv-47`. Position counting is 1-based and starts at the topic root.
3. The published outputs use that value to build per-inverter topics, so each inverter gets its own processed reading and last-seen cache.

This is called **wildcard context inheritance**: the same `+` value flows through every `GET TOPIC` and `PUBLISH TOPIC` inside the Action, so you don't have to parse the topic string yourself.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessWithContext
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "humidity" WITH (GET TOPIC "sensors/+/humidity" AS DOUBLE)
    PUBLISH TOPIC "processed/" + {sensor_id} + "/combined" WITH {humidity}
```

If triggered by `sensors/temp001/temperature`, the `GET TOPIC` reads from `sensors/temp001/humidity` — the wildcard resolves to the same instance.

A single Action like this can replace fifty hand-written copies — one for every device. When a new inverter comes online, you don't deploy new code; the existing Action just starts handling it.

The same approach works equally well for hotel rooms (`rooms/+/temperature`), parking sensors (`parking/+/occupied`), or delivery vans (`vans/+/fuel_level`). Anywhere you have many devices doing the same thing, one wildcard Action covers them all.

***

## Counting Things Over Time

Plenty of real-world questions are counting questions. How many cycles has this machine completed today? How many vehicles entered the garage this hour? How many error events has this device emitted this week? LoT has no built-in counter type, but a counter is just a number you keep on a topic and increment whenever something happens.

> [!TIP]
>
> **Like a tally on a bar napkin.** Each time something happens, you make another mark. The napkin keeps the count even after you walk away.

### When to Reach for This

Whenever you need a value that **persists across messages** — not just within a single Action run. Production cycles, error totals, visitor counts, button presses, alarms-this-shift, anything that should keep counting whether you reset the system or not.

### The Pattern

The trick is two-part: on the very first run there's no value yet, so you initialize to zero. On every run after that, you read the current value, add one, and write it back.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CountCycles
ON TOPIC "machines/cycle_complete" DO
    IF GET TOPIC "counters/cycles" == EMPTY THEN
        PUBLISH TOPIC "counters/cycles" WITH 0 RETAIN
    ELSE
        PUBLISH TOPIC "counters/cycles" WITH (GET TOPIC "counters/cycles" + 1) RETAIN
```

What's happening:

1. Every time a `cycle_complete` message arrives, the Action runs.
2. The first time ever, `counters/cycles` doesn't exist yet, so `GET TOPIC` returns `EMPTY`. The Action creates the counter at zero.
3. Every subsequent run reads the current value, adds one, and publishes the new total.

`RETAIN` sets the MQTT retain flag on the published message, so a new subscriber receives the latest count. Omitting `RETAIN` keeps the historical non-retained behaviour: only current subscribers see each update. `KEEP TOPIC` is different: it would store the number for `GET TOPIC` in the broker cache and would not set the MQTT retain flag.

### Counters Per Device

Combine with a [wildcard](#one-action-for-many-devices) to keep one counter per device:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION CountCyclesPerMachine
ON TOPIC "machines/+/cycle_complete" DO
    SET "machine_id" WITH TOPIC POSITION 2
    IF GET TOPIC "counters/" + {machine_id} + "/cycles" == EMPTY THEN
        PUBLISH TOPIC "counters/" + {machine_id} + "/cycles" WITH 0 RETAIN
    ELSE
        PUBLISH TOPIC "counters/" + {machine_id} + "/cycles"
            WITH (GET TOPIC "counters/" + {machine_id} + "/cycles" + 1) RETAIN
```

Now `counters/machine-01/cycles`, `counters/machine-02/cycles`, and so on each track their own machine independently — and one Action handles all of them.

### Resetting on a Schedule

For shift counters or daily totals, use a scheduled Action to reset:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ResetDailyCounter
ON EVERY 24 HOURS DO
    PUBLISH TOPIC "counters/cycles" WITH 0 RETAIN
```

Pair it with a scheduled SQL insert to archive the previous total before resetting, and you've got a daily history with two short Actions.

***

## Running Python from a LoT Action

LoT is great for the operations that 90% of IoT logic actually needs — math, conditionals, JSON extraction, MQTT publishes. But sometimes you need real programming: regex parsing, statistical analysis, calling a Python library, complex validation rules. For those cases, [`CALL PYTHON`](/latest/lot-language/actions/python-integration) lets a LoT Action invoke a Python function and use the result inline.

> [!TIP]
>
> **Like calling a specialist into a routine job.** The general contractor handles the plumbing, framing, and electrical — but when there's something only a specialist can do, they make a phone call.

### When to Stay in LoT vs. Go to Python

**Stay in LoT for** simple math, string concatenation, basic conditionals, MQTT operations, JSON field extraction, connector triggering, scheduled or topic-triggered logic. Anything LoT does natively, do natively — Python adds overhead and complexity.

**Reach for Python when** you need:

* Regex matching or advanced string parsing
* Statistical or scientific calculations (averages over windows, anomaly detection, ML inference)
* Library functions: `numpy`, `pandas`, `scipy`, `scikit-learn`, custom company libraries
* Complex validation rules with many conditional branches
* JSON restructuring beyond simple field extraction

The rule of thumb: **if you can do it in LoT, do it in LoT.** Python is a tool for capabilities LoT genuinely lacks, not a fallback when LoT is unfamiliar.

### When to Reach for This

When your Action has hit the limits of LoT's expressiveness — typically around regex, statistics, ML, or library calls — and the work isn't worth wrapping in an external service.

### The Pattern

A Python script that validates a complex sensor payload using regex and a custom rule:

```python wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# /scripts/Validator.py
import re

def validate_serial(serial):
    pattern = r'^[A-Z]{2}-\d{6}-[A-Z0-9]{4}$'
    if re.match(pattern, serial):
        return {"valid": True, "error": None}
    return {"valid": False, "error": "Serial format invalid"}
```

A LoT Action that uses it:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ValidateAndStore
ON TOPIC "sensors/registration" DO
    SET "serial" WITH (GET JSON "serial" IN PAYLOAD AS STRING)

    CALL PYTHON "Validator.validate_serial"
        WITH ({serial})
        RETURN AS {result}

    SET "valid" WITH (GET JSON "valid" IN {result} AS BOOL)

    IF {valid} EQUALS TRUE THEN
        PUBLISH TOPIC "registry/valid" WITH PAYLOAD
    ELSE
        SET "err" WITH (GET JSON "error" IN {result} AS STRING)
        PUBLISH TOPIC "registry/rejected" WITH ("Rejected: " + {err})
```

What's happening:

1. The Action receives a sensor registration with a serial number.
2. It hands the serial to the Python function, which uses regex (something LoT can't do natively) to validate the format.
3. The function returns a dictionary, which LoT receives as a JSON object.
4. The Action extracts the `valid` and `error` fields with `GET JSON` and connectors the message accordingly.

### Practical Tips

* **Keep Python functions fast** (under \~100ms). They run inline in your Action and block message processing while they execute. For heavy computation, consider an external service.
* **Always handle errors.** Wrap the Python in `try/except` and return structured results — `{"success": false, "error": "..."}` — so the LoT side can branch on it cleanly.
* **Return JSON-friendly values.** Dictionaries, lists, strings, numbers, booleans. Custom objects won't serialize.
* **Convert types explicitly.** Python receives parameters as strings — `float(value)`, `int(count)` at the top of your function.

The full reference is at [Python Integration](/latest/lot-language/actions/python-integration).

***

## Next Steps

> **[Callable ACTIONs](/latest/lot-language/actions/callable-actions)**
>
> Reusable logic, on-demand scripts, and `CALL ACTION`.

> **[Python Integration](/latest/lot-language/actions/python-integration)**
>
> `CALL PYTHON` syntax, deployment, and best practices.


# Working with JSON
Source: https://docs.coreflux.org/latest/lot-language/usage-patterns/working-with-json

Read JSON fields with GET JSON in Actions, handle nested payloads and missing keys, and publish structured output through Models.

## Overview

Most MQTT payloads in IoT systems are JSON — from devices, HTTP webhooks, industrial gateways, and partner APIs. In Actions you **read** fields with `GET JSON` and **write** structured output with [`PUBLISH MODEL`](/latest/lot-language/models/publish-model). Use raw `PAYLOAD AS DOUBLE` only when the message is a single value with no structure. For **binary protobuf**, use [`GET PROTO` and protobuf models](/latest/lot-language/models/protobuf) instead of `GET JSON`.

For when to choose scalar topics, JSON ingress, or Models at the architecture level, see [Choosing data formats](/latest/lot-language/usage-patterns/data-layer#choosing-data-formats) on the data layer page.

> [!TIP]
>
> **Like fishing one specific item out of a packed grocery bag.** You don't unpack the whole bag — you reach in, grab the field by name, and leave the rest where it is.

For the full `GET JSON` syntax table and edge cases in the operations reference, see [Operations — GET JSON](/latest/lot-language/actions/operations#get-json).

***

## When to Use This

Any time an incoming MQTT message is a JSON object. Typical sources:

* Sensors and PLCs publishing JSON over MQTT
* REST or webhook Connectors that forward JSON bodies to topics
* Cloud or SCADA integrations bridged into the broker

***

## Reading JSON Fields

[`GET JSON`](/latest/lot-language/actions/operations#get-json) takes a field name (or a dotted path), the source (almost always `PAYLOAD`), and a target type. It works inside any expression that needs a value:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessReading
ON TOPIC "sensors/reading" DO
    SET "device_id" WITH (GET JSON "id" IN PAYLOAD AS STRING)
    SET "temperature" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    SET "active" WITH (GET JSON "enabled" IN PAYLOAD AS BOOL)

    PUBLISH TOPIC "processed/" + {device_id} + "/temperature" WITH {temperature}
```

Supported target types are `STRING`, `DOUBLE`, `INT`, and `BOOL`. The conversion happens at extraction time, so by the time the value is in your variable it is already typed correctly for comparisons and math.

***

## Nested Paths

For nested objects, use dot notation. For arrays, use bracket notation. Mix them freely:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessNested
ON TOPIC "sensors/payload" DO
    SET "temp" WITH (GET JSON "data.sensors.temperature" IN PAYLOAD AS DOUBLE)
    SET "first_reading" WITH (GET JSON "readings[0].value" IN PAYLOAD AS DOUBLE)
    SET "second_id" WITH (GET JSON "readings[1].sensor_id" IN PAYLOAD AS STRING)
```

For a payload like:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "data": { "sensors": { "temperature": 23.5 } },
  "readings": [
    { "sensor_id": "S1", "value": 100 },
    { "sensor_id": "S2", "value": 200 }
  ]
}
```

`{temp}` becomes `23.5`, `{first_reading}` becomes `100`, `{second_id}` becomes `"S2"`.

***

## Handling Missing Fields

If a field is absent, `GET JSON` returns a type-appropriate default: empty string for `STRING`, `0` for numeric types, `FALSE` for `BOOL`. For optional fields, check explicitly with `EMPTY`:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
SET "battery" WITH (GET JSON "battery_level" IN PAYLOAD AS DOUBLE)
IF {battery} == EMPTY THEN
    PUBLISH TOPIC "alerts/missing_field" WITH "battery_level not reported"
ELSE
    PUBLISH TOPIC "processed/battery" WITH {battery}
```

This pattern matters when you consume data from third parties — webhooks and partner APIs often omit fields rather than send nulls.

***

## End-to-End: Extract JSON and Publish a Model

To publish structured JSON without hand-building strings, define a **COLLAPSED** Model with typed fields and use `PUBLISH MODEL ... TO ... WITH` from an Action. The broker assembles the JSON for you.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SensorDataRecord COLLAPSED
    ADD STRING "sensor_id"
    ADD STRING "sensor_type"
    ADD DOUBLE "temperature"
    ADD DOUBLE "pressure"
    ADD STRING "timestamp"
    ADD STRING "quality_status"

DEFINE ACTION ProcessSensorJSON
ON TOPIC "sensors/+/json_data" DO
    SET "sensor_id" WITH TOPIC POSITION 2

    SET "temperature_val" WITH (GET JSON "temperature" IN PAYLOAD AS DOUBLE)
    SET "pressure_val" WITH (GET JSON "pressure" IN PAYLOAD AS DOUBLE)
    SET "sensor_type" WITH (GET JSON "type" IN PAYLOAD AS STRING)
    SET "quality" WITH (GET JSON "quality_status" IN PAYLOAD AS STRING)

    PUBLISH MODEL SensorDataRecord TO "sensors/processed/" + {sensor_id} WITH
        sensor_id = {sensor_id}
        sensor_type = {sensor_type}
        temperature = {temperature_val}
        pressure = {pressure_val}
        timestamp = TIMESTAMP "UTC"
        quality_status = {quality}
```

| Step | What Happens |
| - | - |
| 1 | Action triggers when any sensor publishes JSON to `sensors/+/json_data` |
| 2 | `GET JSON` extracts each field with the correct type |
| 3 | `PUBLISH MODEL` builds a clean JSON object and publishes it to the processed topic |

See [Publish Model](/latest/lot-language/models/publish-model) for more on COLLAPSED models and field mapping.

***

## Next Steps

> **[Designing your data layer](/latest/lot-language/usage-patterns/data-layer)**
>
> Topic trees, scalar vs JSON payloads, and when to use Models.

> **[Operations — GET JSON](/latest/lot-language/actions/operations#get-json)**
>
> Full syntax reference for GET JSON and related operations.


# How to Debug in LoT Notebooks
Source: https://docs.coreflux.org/lot-notebooks/debug

Debug LoT and MQTT data with a Data Viewer and an Execution _Trace.

![Animated walkthrough of the LoT Data Viewer in VS Code: subscribing to topics and viewing live MQTT traffic](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-basic.gif?s=7124718aa0d1a06105dd56a905f1a177)

Data Viewer: subscribe to topics and watch live MQTT data

## Overview

Debugging in LoT Notebooks means confirming **data is moving on the right topics** and **your logic behaves as intended**. The extension includes a **Data Viewer** and an **Execution Trace** tied to each **LoT cell** so you can see data, replay flows and inspect every related **topic** and **variable**.

> [!TIP]
>
> Without the right view, you are mostly in the **dark** — you write code hoping nothing goes wrong. The **Data Viewer** and the **execution trace** light up the room, **showing what that code actually did**.

***

## Data Viewer

![Animated walkthrough of the LoT extension Data Viewer: topic tree, message history, replay, and payload formatters](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-advanced.gif?s=68e85cdf93ebe2ce5c24a87b66d50544)

Data Viewer: topic tree and replay viewer with live data and history replay

Inside **Coreflux Explorer**, the Data Viewer has two parts that work together:

### Topic Tree Viewer

![LoT MQTT Topic Tree Viewer, showing topic hierarchy and MQTT Payloads](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-topic-tree.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=561af3decf708f1924c73ee7ce92a44a)

LoT MQTT Topic Tree Viewer, showing topic hierarchy and MQTT Payloads

The **topic tree** gives you a **quick glance** at your hierarchy and **live values** as messages arrive—handy for spotting whether a sensor topic or alert is updating, without needing to open a separate tool.

Use **Subscribe to All topics** when you want the tree to show all broker data, and **Subscribe to a topic** when you want to focus on specific information.

### Replay Data Viewer

![LoT Data Viewer showing JSON formatter with syntax highlighting, topic tab, message count, and timeline replay controls](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-json.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=89cb011008958531b30e05dda02a2a14)

Data Viewer: data payload, topic tabs, timeline, and replay controls

**Click a topic in the tree** to open the **full Data Viewer** for that stream. There you get:

* **Message history** and a **multi-topic** layout so you can follow several related topics at once
* **Replay** controls to move through captured messages over time
* A **data formatter** so you can interpret payloads the way they were meant to be read—pick the view that matches how the payload is encoded

Use this when you need to inspect structure, compare payloads, or see the data history — not just see that “something changed” on a topic.

#### Adjust how you see the data

Choose a formatter after opening a topic. The full viewer supports **multiple topics**, a **message history**, **replay** (timeline and playback controls), and **data views** such as raw, JSON, Protobuf, geopoint, image, audio and PDF.

Each topic keeps its last **100** messages by default. Change it with the gear on the timeline, or the `coreflux.dataViewer.historyBufferPerTopic` setting (50 to 2000). Open topics are never pruned, and history holds still while you're scrubbing instead of following **Live**.

![LoT Data Viewer Geopoint formatter showing geographic coordinates plotted on a map](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-map.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=ffd3ec12cd15adcb8f40aa465879ba10)

Data Viewer Geopoint formatter: coordinates on a map

***

## Execution trace

![Animated walkthrough of the LoT extension execution trace showing cell-related topics and variables, timeline, and replay](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lot-trace.gif?s=117a51b175bb962e2f81c13cf341716d)

Execution trace: topics and variables for the LoT cell, with timeline and replay

The **execution trace** lets you **see every topic and variable** the cell touches—publishes, subscriptions, and related state—in one place, follow a **time-ordered history** of messages across them, and use **replay** with playback controls and a **timeline** to play, pause, and scrub the run. That way you can confirm execution order, timing, and which step produced which message when logic spans several topics.

It is scoped to the **LoT cell** you are debugging, so you stay with that cell’s footprint on the broker instead of hunting traffic across the whole system.

***

## Troubleshooting

When the viewer or trace does not match what you expect, open the sections below.

> **Broker connection issues**
>
> If cells fail immediately or never show a response, verify credentials and network first.
>
> 1. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) or use the connection control in the activity bar / status area as shown in your setup.
> 2. Run **LoT Notebook: Change Credentials** and enter your broker URL, username, and password.
> 3. Watch the status bar for a connected state before running cells.
>
> ![Animated walkthrough of entering broker credentials and connecting in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-broker-connect.gif?s=faf63084741fb786ec1807145f691a89)
>
> Updating broker credentials in the LoT Notebooks extension
>
> * Default credentials and TLS notes: [LoT Notebooks setup guide](/latest/quick-start/vscode)
> * Confirm the broker is reachable (host, port, firewall, TLS if using `mqtts://`)

> **Cell run output and errors**
>
> When you click **Run** on a LoT cell, the extension sends the definition to the broker and shows the result directly below the cell.
>
> ![Animated walkthrough of clicking the Run button to deploy the action to the broker](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-deploy-basic-action.gif?s=d7edcd18dc774cad66ff4969543e29ae)
>
> Running a cell to deploy a LoT definition to the broker
>
> | What you see | What it means |
> | - | - |
> | Success message / green check | The broker compiled and registered the entity (Action, Model, Connector, or Rule). |
> | Error text | Often syntax, indentation, or broker-side validation—read the full message for line hints when provided. |

## Related guides

> **[How to Use a LoT Notebook](./usage)**
>
> Cell execution, commands, broker topics, and troubleshooting accordions.

> **[Introduction to LoT](/latest/lot-language/introduction)**
>
> What LoT is, how it runs in the broker, and simple examples to build on.


# File Format
Source: https://docs.coreflux.org/lot-notebooks/file-format

Understand the .lotnb file structure, cell types, and how to create notebooks.

## The .lotnb Format

LoT Notebook files use the `.lotnb` extension and follow a JSON-based structure compatible with VS Code's notebook API. Each file contains an array of cells—documentation and code blocks that make up your notebook.

> [!NOTE]
>
> You don't need to edit the JSON directly. VS Code's notebook interface handles the structure automatically. This page is for understanding what's happening under the hood.

***

## File Structure

A `.lotnb` file is a JSON array where each element represents a cell:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "kind": 1,
    "language": "markdown",
    "value": "# My First Notebook\n\nThis is a markdown cell with documentation."
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION Heartbeat\nON EVERY 10 SECONDS DO\n    PUBLISH TOPIC \"system/heartbeat\" WITH TIMESTAMP \"UTC\""
  },
  {
    "kind": 2,
    "language": "python",
    "value": "# Script Name: DataProcessor\ndef calculate_average(values):\n    return sum(values) / len(values)"
  }
]
```

***

## Cell Properties

Each cell has three required properties:

| Property | Type | Description |
| - | - | - |
| `kind` | integer | Cell type: `1` = Markdown, `2` = Code |
| `language` | string | Cell language: `"markdown"`, `"lot"`, or `"python"` |
| `value` | string | Cell content (use `\n` for line breaks) |

### Kind Values

| Kind | Type | Purpose |
| - | - | - |
| `1` | Markdown | Documentation, explanations, headers |
| `2` | Code | Executable LoT or Python code |

### Language Values

| Language | Cell Kind | Description |
| - | - | - |
| `markdown` | 1 | Rich text documentation |
| `lot` | 2 | LoT definitions (Actions, Models, Connectors, Rules) |
| `python` | 2 | Python scripts for broker execution |

***

## Cell Types in Detail

### Markdown Cells

Markdown cells support standard Markdown syntax plus some extensions:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "kind": 1,
  "language": "markdown",
  "value": "## Temperature Monitoring System\n\nThis notebook implements a complete temperature monitoring solution:\n\n- **Sensors**: Read from `sensors/+/temperature`\n- **Alerts**: Publish to `alerts/high-temp` when threshold exceeded\n- **Logging**: Store all readings in database\n\n### Architecture\n\n| Component | Topic | Purpose |\n|-----------|-------|--------|\n| Sensor Reader | sensors/+/temperature | Ingest data |\n| Alert Generator | alerts/+ | Notify operators |"
}
```

**Supported Markdown features:**

* Headers (`#`, `##`, `###`)
* Bold, italic, code formatting
* Bullet and numbered lists
* Tables
* Code blocks (for examples, not execution)
* Links and images

### LoT Code Cells

LoT cells contain executable Language of Things definitions:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "kind": 2,
  "language": "lot",
  "value": "DEFINE ACTION TemperatureMonitor\nON TOPIC \"sensors/+/temperature\" DO\n    SET \"sensor_id\" WITH TOPIC POSITION 2\n    IF PAYLOAD > 80 THEN\n        PUBLISH TOPIC \"alerts/high-temp/\" + {sensor_id} WITH \"Critical: \" + PAYLOAD + \"°C\""
}
```

**Valid LoT definitions:**

| Definition | Syntax |
| - | - |
| Action | `DEFINE ACTION ActionName` |
| Model | `DEFINE MODEL ModelName WITH TOPIC "..."` |
| Connector | `DEFINE CONNECTOR ConnectorName WITH TYPE ...` (`DEFINE ROUTE` remains an alias) |
| Rule | `DEFINE RULE RuleName` |

### Python Cells

Python cells contain scripts that run inside the broker when called from LoT:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "kind": 2,
  "language": "python",
  "value": "# Script Name: Validators\ndef validate_temperature(value, min_temp, max_temp):\n    \"\"\"Check if temperature is within acceptable range\"\"\"\n    try:\n        temp = float(value)\n        return {\n            \"valid\": min_temp <= temp <= max_temp,\n            \"value\": temp,\n            \"range\": f\"{min_temp}-{max_temp}\"\n        }\n    except (ValueError, TypeError):\n        return {\"valid\": False, \"error\": \"Invalid temperature value\"}"
}
```

> [!WARNING]
>
> **Required format**: Python scripts must start with `# Script Name: YourScriptName` as the first line. This header tells the broker how to register and reference the script.

***

## Creating a New Notebook

### Method 1: VS Code Interface

1. Create a new file with `.lotnb` extension
2. VS Code automatically opens it in notebook mode
3. Use the **+ Code** and **+ Markdown** buttons to add cells
4. Select cell language from the dropdown (lot, python, markdown)

### Method 2: Manual Creation

Create a file with minimal JSON structure:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "kind": 1,
    "language": "markdown",
    "value": "# My Notebook\n\nAdd your documentation here."
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION MyFirstAction\nON EVERY 10 SECONDS DO\n    PUBLISH TOPIC \"test/hello\" WITH \"Hello World\""
  }
]
```

Save with `.lotnb` extension and open in VS Code.

***

## Example: Complete Notebook

Here's a full example showing all cell types working together:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "kind": 1,
    "language": "markdown",
    "value": "# Production Monitoring System\n\nThis notebook implements production line monitoring with:\n- Real-time part counting\n- Quality validation using Python\n- Alert generation for anomalies"
  },
  {
    "kind": 1,
    "language": "markdown",
    "value": "## Python Validators\n\nFirst, we define our validation functions:"
  },
  {
    "kind": 2,
    "language": "python",
    "value": "# Script Name: QualityChecker\ndef check_dimensions(length, width, tolerance=0.5):\n    \"\"\"Validate part dimensions against specifications\"\"\"\n    target_length = 100.0\n    target_width = 50.0\n    \n    length_ok = abs(float(length) - target_length) <= tolerance\n    width_ok = abs(float(width) - target_width) <= tolerance\n    \n    return {\n        \"passed\": length_ok and width_ok,\n        \"length_deviation\": float(length) - target_length,\n        \"width_deviation\": float(width) - target_width\n    }"
  },
  {
    "kind": 1,
    "language": "markdown",
    "value": "## Part Counter Action\n\nCounts produced parts and tracks hourly production:"
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION PartCounter\nON TOPIC \"production/line1/part-complete\" DO\n    SET \"count\" WITH (GET TOPIC \"production/line1/count\" AS INT) + 1\n    PUBLISH TOPIC \"production/line1/count\" WITH {count}\n    PUBLISH TOPIC \"production/line1/last-update\" WITH TIMESTAMP \"UTC\""
  },
  {
    "kind": 1,
    "language": "markdown",
    "value": "## Quality Check Action\n\nValidates each part using our Python function:"
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION QualityValidator\nON TOPIC \"production/line1/measurement\" DO\n    SET \"length\" WITH (GET JSON \"length\" IN PAYLOAD AS DOUBLE)\n    SET \"width\" WITH (GET JSON \"width\" IN PAYLOAD AS DOUBLE)\n    \n    CALL PYTHON \"QualityChecker.check_dimensions\"\n        WITH ({length}, {width})\n        RETURN AS {result}\n    \n    IF (GET JSON \"passed\" IN {result} AS BOOL) EQUALS TRUE THEN\n        PUBLISH TOPIC \"production/line1/quality/passed\" WITH {result}\n    ELSE\n        PUBLISH TOPIC \"production/line1/quality/failed\" WITH {result}\n        PUBLISH TOPIC \"alerts/quality\" WITH \"Part failed inspection\""
  }
]
```

***

## Best Practices

> **Use descriptive markdown headers**
>
> Start notebooks with a title and overview. Use headers to organize sections logically.

> **One definition per code cell**
>
> Keep each Action, Model, Connector, or Rule in its own cell. This makes debugging and selective execution easier.

> **Document before you code**
>
> Write a markdown cell explaining what the next code cell does before writing the code. This helps you think through the logic.

> **Use consistent naming**
>
> Follow a naming convention for your Actions, Models, and Python scripts. Example: `SensorTemperatureMonitor`, `ProductionPartCounter`.

***

## Troubleshooting

> **File won't open as notebook?**
>
> * Verify the file has `.lotnb` extension (not `.lotnb.json`)
> * Check that the LoT Notebooks extension is installed
> * Ensure the file contains valid JSON (use a JSON validator)

> **JSON syntax errors?**
>
> Common issues:
>
> * Missing commas between cells
> * Unescaped quotes in `value` strings (use `\"`)
> * Unescaped newlines (use `\n`)
> * Missing closing brackets

> **Cell showing wrong language?**
>
> Check the `language` property matches the content type. VS Code should auto-detect, but you can manually switch using the language selector in the cell toolbar.

***

## Next Steps

> **[Getting Started](/latest/quick-start/getting-started)**
>
> Create your first LoT Action and verify your setup is working.

> **[LoT Language Reference](/latest/lot-language/introduction)**
>
> Explore the complete LoT syntax for Actions, Models, Connectors, and Rules.


# Tutorials
Source: https://docs.coreflux.org/lot-notebooks/tutorials

Hands-on LoT Notebook tutorials covering Actions, Models, Connectors, and Python integration.

## Learn by Building

The best way to master LoT is through hands-on practice. These tutorials are interactive notebooks you can download and run in VS Code—each one builds your skills progressively.

> [!TIP]
>
> **Start with Basics, then branch out.** Complete the Basics tutorials first to understand LoT fundamentals, then explore the topics most relevant to your projects.

***

## Learning Path

Follow this recommended progression from beginner to advanced:

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart TB
    subgraph Beginner
        direction LR
        A[Timed Actions] --> B[Topic Actions]
    end
    subgraph Intermediate
        direction LR
        C[Conditional Logic] --> D[Basic Models]
        D --> E[Action Models]
        E --> F[Model Inheritance]
    end
    subgraph Advanced
        direction LR
        G[Connectors] --> H[Python]
        H --> I[Architecture]
    end
    Beginner --> Intermediate
    Intermediate --> Advanced
```

***

## Basics

Start here to learn the fundamentals of LoT Actions and event-driven programming.

> **[Timed Actions](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/01-basics/timed-actions.lotnb)**
>
> Create actions that run on schedules—heartbeats, counters, and periodic tasks. Learn `ON EVERY` triggers and state persistence.

> **[Topic Actions](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/01-basics/topic-actions.lotnb)**
>
> React to MQTT messages in real-time. Master `ON TOPIC` triggers, wildcards, and payload processing.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Timed Actions** | `ON EVERY` syntax, time units, `PUBLISH TOPIC`, timestamps, counters |
| **Topic Actions** | `ON TOPIC` triggers, wildcards (`+`, `#`), `PAYLOAD`, topic parsing |

***

## Logic

Build intelligent automation with conditional logic and decision-making.

> **[Conditional Logic](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/02-logic/conditional-logic.lotnb)**
>
> Implement IF/ELSE statements, comparisons, and boolean logic. Build threshold monitors, state machines, and quality control systems.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Conditional Logic** | `IF/ELSE` statements, comparison operators, `AND/OR/NOT`, text matching with `CONTAINS` |

***

## Models

Structure and transform your data with LoT Models.

> **[Basic Models](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/03-models/basic-models.lotnb)**
>
> Define data schemas with typed fields. Create structured sensor readings, equipment status reports, and alarm messages.

> **[Action Models](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/03-models/action-models.lotnb)**
>
> Publish models dynamically from Actions. Combine event-driven logic with structured data output.

> **[Model Inheritance](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/03-models/model-inheritance.lotnb)**
>
> Extend base models to create specialized variants. Build hierarchies for sensors, equipment, and production data.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Basic Models** | `DEFINE MODEL`, field types (STRING, INT, DOUBLE, BOOL), triggers, topic sources |
| **Action Models** | `PUBLISH MODEL`, dynamic field values, combining Actions with Models |
| **Model Inheritance** | `EXTENDS`, base models, field overrides, model hierarchies |

***

## Connectors

Connect your LoT system to external databases and other MQTT brokers.

> **[MQTT Bridge](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/04-routes/mqtt-bridge.lotnb)**
>
> Connect multiple MQTT brokers. Forward messages, sync data between systems, and build distributed architectures.

> **[Database Connectors](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/04-routes/database-routes.lotnb)**
>
> Store MQTT data in SQL databases. Configure connections, map topics to tables, and query historical data.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **MQTT Bridge** | `TYPE MQTT_BRIDGE`, source/destination config, mappings, bidirectional sync |
| **Database Connectors** | `TYPE DATABASE`, connection strings, table mappings, data persistence |

***

## Python Integration

Extend LoT with Python for complex calculations, data processing, and advanced logic.

> **[Simple Python](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/05-python/simple-python.lotnb)**
>
> Get started with Python in LoT. Learn the script format, parameter passing, and return value handling.

> **[Advanced Python](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/05-python/advanced-python.lotnb)**
>
> Build sophisticated data pipelines. Use external libraries, handle JSON, and implement validation logic.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Simple Python** | `CALL PYTHON` syntax, script format, parameters, return values |
| **Advanced Python** | JSON processing, external libraries, error handling, complex transformations |

***

## Showcase

Ready-to-run notebooks that combine every LoT entity type in one realistic project. Each one simulates its own data, so the core cells need only a broker.

> **[Flights tracker](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/showcase/01-flights-tracker.lotnb)**
>
> Airport operations: Python, timer and topic actions, models with inheritance, a REST API server, file storage, an MQTT bridge, rules, a panel and an AI agent.

> **[Bottling Line](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/showcase/02-bottling-line.lotnb)**
>
> Factory line: Modbus and OPC UA servers and clients, OEE in Python, Things, rules, a dashboard and a maintenance agent.

> **[Smart Building](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/showcase/03-smart-building.lotnb)**
>
> Unified namespace with wildcard actions, comfort and energy alarms, a Modbus gateway, a REST webhook, dashboards and two cooperating agents.

> [!NOTE]
>
> In **Bottling Line**, the Thing cells are marked preview: they use `DEFINE THING`, which hasn't shipped yet. Each one has a fallback cell that works on the current broker. Cells under a `[needs: X]` heading are optional and need an extra service, such as Ollama or PostgreSQL.

***

## Quick Reference

Need to review a specific concept? Here's where to find it:

| Concept | Tutorial |
| - | - |
| Time-based triggers | [Timed Actions](#basics) |
| Message triggers | [Topic Actions](#basics) |
| IF/ELSE logic | [Conditional Logic](#logic) |
| Data schemas | [Basic Models](#models) |
| Dynamic publishing | [Action Models](#models) |
| Schema inheritance | [Model Inheritance](#models) |
| Broker bridging | [MQTT Bridge](#connectors) |
| Data storage | [Database Connectors](#connectors) |
| Python scripting | [Simple Python](#python-integration) |
| Advanced processing | [Advanced Python](#python-integration) |
| End-to-end projects | [Flights tracker, Bottling Line, Smart Building](#showcase) |

***

## Download Tutorials

All tutorials are available in the Coreflux Community GitHub repository:

> **[LoT Tutorials Repository](https://github.com/CorefluxCommunity/Language-Of-Things-Training)**
>
> Download complete tutorial notebooks with documentation, examples, and exercises.

### Getting the Tutorials

**1. Clone or Download**

Clone the repository or download as ZIP from GitHub.

**2. Open in VS Code**

Open any `.lotnb` file—VS Code automatically uses the LoT Notebooks extension.

**3. Connect Your Broker**

Configure your broker credentials, then start running cells.

***

## Next Steps

> **[Usage Guide](./usage)**
>
> Master cell execution, broker commands, and troubleshooting.

> **[LoT Language Reference](/latest/lot-language/introduction)**
>
> Explore the complete LoT syntax reference and advanced features.


# How to Use a LoT Notebook
Source: https://docs.coreflux.org/lot-notebooks/usage

Learn how to use LoT Notebooks to run, document and debug your LoT code.

![VS Code with a LoT notebook open showing markdown and LoT code cells, Coreflux Explorer and project tree on the left, Data Viewer below, and MQTT connection in the status bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lotnb.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=9e0cb958c924dad253919f3ff09f828a)

LoT Notebook workspace in VS Code: editor, Coreflux Explorer, Project, and Data Viewer

## The Notebook Workflow

LoT Notebooks combine **Documentation in Markdown** and **LoT code** in a **single file**, so you can both run your code and keep your documentation together, using the notebook as **living documentation** for your project.

> [!TIP]
>
> **Picture a smart kitchen:** **Markdown** is the recipe on the page, each **LoT code** cell is how you run each step of the recipe, and the **Data Viewer** shows you the results of each step.

***

## Install and connect

**1. Install the extension**

![Animated walkthrough: VS Code Extensions view, search for coreflux, install Coreflux LoT, Coreflux icon appears in the Activity Bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-installation.gif?s=3a2aa4cdbaf895e94e9954d6c45b7abf)

Extensions marketplace: search for Coreflux and install LoT Notebooks

1. Open VS Code.
2. Open the Extensions view in the sidebar (or use the shortcut `Ctrl+Shift+X` on Windows/Linux, `Cmd+Shift+X` on macOS).
3. Search for **LoT Notebooks** by **Coreflux** and install it.

**2. Connect to the broker**

![VS Code: connect to MQTT broker via LoT extension; status bar shows MQTT connected](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-broker-connect.gif?s=faf63084741fb786ec1807145f691a89)

Connect to the broker: pick credentials or connect from the Data Viewer

1. Click the **MQTT** connection status in the bottom-left of VS Code, or click **Connect to Broker** in the **Data Viewer** (Coreflux sidebar).
2. Enter your broker **URL**, **username**, and **password**.

> **Example URL and default login credentials**
>
> Use a full URL such as `mqtt://localhost:1883` or `mqtts://your-host:8883` for TLS.
>
> | Setting | Example (local defaults) |
> | - | - |
> | URL | `mqtt://localhost:1883` |
> | Username | `root` |
> | Password | `coreflux` (change immediately in production) |

When you are connected, the status bar shows a green **MQTT: Connected**. If any issues occur, the status bar will become red.

> [!NOTE]
>
> The extension securely stores your credentials. You only need to configure them once per workspace.

***

## Create a new project

![Animated walkthrough: creating a new .lotnb file from the Coreflux PROJECT section in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lotnb-create-new.gif?s=6f76d28d7999e12459a044e460d414bc)

Creating a new LoT Notebook from the Coreflux PROJECT view

1. In the Activity Bar, open the **Coreflux** view. Under **PROJECT**, use **New File** to create a notebook and save it in your workspace (use **New Folder** first if you want a dedicated project folder).
2. In the notebook, add **Markdown** and **LoT** cells from the toolbar as needed.

***

## Add LoT code to a LoT Notebook

![Animated walkthrough: insert a code cell in a LoT Notebook and add LoT definition text in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-basic-action.gif?s=f0a99e24fb50a62f34539d706812f912)

Insert a LoT code cell and add LoT in the notebook editor

1. Open your LoT Notebook in VS Code.
2. From the notebook toolbar, add a **code** cell.
3. Type or paste your LoT code (`DEFINE ACTION`, `DEFINE MODEL`, and so on). For a first example, use the code below.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

***

## What type of cells you can add to LoT Notebooks

LoT Notebooks support three types of cells, each with different behavior:

### Markdown Cells - Documentation

![LoT Notebook markdown cell showing a heading and body text with the cell toolbar for formatting and actions](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-cell-markdown.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=7f8d6580bd483bfd9e9c53c7e6919d1b)

Markdown cell with rich text and the formatting toolbar

Markdown cells are for **documentation only**—they don't execute. Use them to:

* Explain what your code does and why
* Document configuration requirements
* Add diagrams, tables, and formatted text
* Create section headers and navigation

### LoT Code Cells - Runnable Logic

![LoT Notebook LoT cell with TemperatureSimulator action, run button, and status bar showing Upload to broker and LOT cell type](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-cell-LoT.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=3ced495b4d1137b78534bb83cb0a4651)

LoT code cell: syntax highlighting, sync status and upload to broker buttons

LoT cells contain executable **LoT (Language of Things)** code. When you run a LoT cell:

1. The extension parses your code
2. Sends it to the connected broker via MQTT
3. The broker compiles and registers the definition
4. You receive confirmation or error feedback

For what LoT is, how it fits the broker, and more examples, see [Introduction to LoT](/latest/lot-language/introduction).

#### Validate without deploying

**Validate** in the cell status bar, or **LOT Notebook: Validate LOT Cell** and **Validate LOT Notebook** in the Command Palette, asks the broker to check the code without deploying it. The broker's summary and each diagnostic (severity, code, line, and message) appear under the cell and in **Problems** with source `Coreflux`. Notebook validation includes Python cells. Diagnostics clear when you edit the cell. Needs a broker newer than 2.14.

#### Disable an entity

Action, connector, and agent cells have an **Enabled / Disabled** toggle in the cell status bar. It adds `DISABLE true` on the line after `DEFINE`, or removes it; a `DISABLE` inside a comment is left alone. When you're connected, the cell is uploaded right away; offline, upload it once you connect. The broker keeps a disabled entity defined, but doesn't run it. A broker without `DISABLE` support leaves the cell unchanged. The same toggle is **LOT Notebook: Enable / Disable LOT Cell (DISABLE)**. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).

#### THING cells

Running a cell with `DEFINE THING` blocks sends them as typed, with every template they use from the workspace, as one `-addThing`. The broker expands them; the extension doesn't.

* Every run checks first with `-addThing --dryRun`. Problems appear on the cell at the line of the THING source.
* When a template change would redeploy other root Things, the extension lists them and asks first.
* The cell output shows the broker's plan per root: `add`, `update`, `adopt`, `remove`, or `unchanged` for each child.
* **Remove Thing from Broker** sends `-removeThing`. The broker refuses to remove a template that's in use.
* A cell in the older THING syntax offers a quick fix that adds `TEMPLATE` and rewrites `{p}` to `{{p}}`. You can **Apply All**, or **Review in Refactor Preview** first.
* On a broker without THING support, the cell says so and deploys nothing.

The Coreflux Explorer and the Entities panel show each root Thing with its state, its instances, and their read-only children. A Thing that no workspace notebook defines is marked *not in workspace*.

#### Agent cells

A `DEFINE AGENT` cell deploys with `-addAgent` and is removed with `-removeAgent`. The extension checks the agent like the broker does: a missing `USES LLM CONNECTOR` (`USES LLM ROUTE` is still accepted) or `DEFAULT_USER`, unknown clauses or tools, and an `ADD TOOL` without its `TOPICS`, `TARGET`, or `LEVEL "write"` are errors. Agents on the broker appear in the Coreflux Explorer and under **Agents** in the Entities panel.

Agent, Thing, rule, connector, and model checks follow the broker. A connector key such as `SUBJECT`, and a mixed-case name, are not reported as unknown keywords.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE AGENT NightShift
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    ADD TOOL "read_mqtt"
        WITH TOPICS "plant/#"
```

See [LoT Agents](/latest/lot-language/agents/overview).

#### Panel cells

A `DEFINE PANEL` or `DEFINE VISU` cell is checked with the broker's panel parser: component types, `SET`, `BIND`, `ON … DO`, `AT`, `ADD THRESHOLD`, and `MAPPING`. A typo stays an error. Where the broker falls back, the cell shows a warning. Highlighting, hover, and completions cover the panel keywords, and the `DEFINE PANEL` snippet inserts a starter panel.

Running the cell deploys with `-addVisu` (the same command as `-addPanel`). Removing it sends `-removeVisu`. A Thing's `WITH PANEL` body is checked the same way. `DEFINE THEME` and `THEME_VARIANT` are recognized. The cell status bar offers **Open in Coreflux HUB** to view the rendered panel, and a successful upload suggests opening Dashboards there.

See [Defining a Panel](/latest/lot-language/panels/defining-panels).

### Python Cells - Advanced Logic

![LoT Notebook Python cell with Script Name header, function definitions, run button, and Python label in the status bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-cell-python.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=11d0c77c5b03bb46c46c71ae0fcdf3c3)

Python cell with syntax highlighting, sync status and upload to broker buttons

Python cells contain scripts that run inside the broker when called from LoT Actions. The broker's Python runtime executes your functions.

```python wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Script Name: DataProcessor
def calculate_average(values):
    """Calculate average from a list of numbers"""
    if not values:
        return 0
    return sum(values) / len(values)

def format_alert(sensor_id, value, threshold):
    """Generate formatted alert message"""
    return f"ALERT: Sensor {sensor_id} exceeded {threshold} with value {value}"
```

> [!WARNING]
>
> Python scripts require a specific format with `# Script Name: YourScriptName` as the first line. Without this header, the script won't be recognized.

***

## Running LoT

![Animated walkthrough: Run on a LoT notebook cell to deploy the definition to the connected Coreflux broker](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-deploy-lot.gif?s=aa0c88228b7e0db8f7fe4b07c16eb513)

Deploying a LoT or Python code from the notebook to the broker

When you click the **Run** button on a cell, the Extension builds your code, checks for errors and deploys to the broker.
If successful, a simple Green response will appear. If any error is found, the code is not deployed and a error message will appear with the error details.

***

## What else you can do with the LoT extension

![Animated walkthrough of the LoT Data Viewer in VS Code: subscribing to topics and viewing live MQTT traffic](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-basic.gif?s=7124718aa0d1a06105dd56a905f1a177)

Data Viewer basics: subscribe to topics and watch live MQTT data

Use the **Coreflux** view (Activity Bar) for broker connection, entities, secrets, license, clients, and live MQTT—without a separate client for most tasks.

| Capability | Why it helps |
| - | - |
| **See what is running in the Broker** | See what Actions, Models, Connectors, and Rules the broker actually has after a deploy. |
| **Remove LoT code** | On Coreflux Explorer, remove one or more LoT entities. |
| **Manage secrets and variables** | Configure secrets and variables on the broker, to manage secure credentials. Open **Secrets & Variables** from Broker Management |
| **See license usage** | Spot **license limits** when deploy fails—before you debug LoT as a syntax issue. |
| **Activate a license** | Activate, install, enroll, and refresh from the **License** tab. See [License tab](#license-tab) |
| **Configure the MCP server** | Turn on the broker's MCP server, manage its tokens, and install it into AI clients. See [MCP Server tab](#mcp-server-tab) |
| **See connected clients** | See who is connected; useful when a device or app should be online but is not. |
| **MQTT Data Viewer** | Live topics and payloads in the Data Viewer. |
| **Execution Trace** | For a LoT cell, see it's execution history and which topics and variables that run touched. |

For more on the Data Viewer, replay, formatters, and trace, see [How to Debug in LoT Notebooks](./debug).

### License tab

Open **License Management** from Broker Management. The tab shows the plan, expiry, features, and usage from `$SYS/Coreflux/License`, and offers these actions:

| Action | What to enter | Broker command |
| - | - | - |
| **Activate** | An activation code (`CFLX-…`) | `-activateLicense` |
| **Install** | The signed license text, pasted or from a file | `-loadLicense` |
| **Enroll** | An organization enrollment token (`et_…`) | `-enroll` |
| **Refresh** | Nothing: forces a lease refresh | `-refreshLicense` |

You can also load a license file that's already on the broker host by its path. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

### MCP Server tab

**Coreflux: Configure MCP Server** opens the broker's built-in MCP server settings, the same ones as the HUB **MCP** tab:

* **Server** — Enabled, status (**Listening**, **Disabled**, or **Pending restart**), the endpoint URL with Copy, port, bind IP, and endpoint path. Saved changes apply when the broker restarts.
* **Tools** — Expose all tools, or pick an allow-list from the broker's catalog.
* **Tokens** — List, create, and revoke tokens (`-listMcpTokens`, `-createMcpToken`, `-revokeMcpToken`). A new token is shown once.

**Install MCP server** creates a token for the broker user you pick and writes the endpoint and token into each client you tick: Cursor, VS Code, Claude Code, or Claude Desktop (through `npx mcp-remote`). Existing config files are edited in place, keeping comments and other servers. A workspace install also adds the config file to `.gitignore`, so the token isn't committed. See [MCP Server](/latest/mqtt-broker/mcp-server).

### Develop LoT Notebooks with AI

![Animated walkthrough: VS Code with a LoT notebook open and GitHub Copilot chat focused on a notebook cell](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-copilot.gif?s=7fa29fa41a99c3835a27fa55fe1bf46e)

GitHub Copilot with a LoT Notebook: chat in context of the open notebook and cells

Alongside the extension, you can develop with AI using **Copilot**, just like any programming language. For better results, you can add the **Coreflux MCP** server to the agent, so it can read official docs, and add **AGENTS.md** file for LoT coding practices, so it works like a LoT expert.

To connect your AI client to the broker itself, use [Install MCP server](#mcp-server-tab). Nothing is installed automatically on startup. **Install Agent Skills...** lets you pick which skills to install and the target folders: `.agents`, `.claude`, `.cursor`, or `.github` skills folders, in the workspace or in your home folder. The 11 bundled skills come from the public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository. See [Agent Skills](/ai/agent-skills) (broker 2.22 or later) for the skill list and other ways to install them. Older copies from previous versions are offered to move to the trash.

To for more details on how to use AI with LoT, check this page: [Developing with LoT Using AI](/ai/developing-with-lot).

### Version control with Git

![VS Code Source Control showing pending changes across .lotnb notebooks, docker-compose.yml, markdown, and editor config files in the same repo](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-project-git-management.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=fa4ae1c74bc80b882ead08c988631d8c)

Source Control: Git tracks the whole workspace, not just LoT notebooks

Use **Git** on your **workspace folder** like any project: commit **`.lotnb`** files aswell as any other files, like documentation, Docker files and supporting files.

***

## Best Practices

> **Organize with Markdown**
>
> Use markdown cells liberally to explain your code. Future you (and teammates) will appreciate the context.

> **One Definition Per Cell**
>
> Keep each Action, Model, or Connector in its own cell. This makes debugging easier and allows selective execution.

> **Test Incrementally**
>
> Run cells one at a time when developing. This helps isolate issues and understand system behavior.

> **Use Descriptive Names**
>
> Name your Actions, Models, and Connectors clearly. They appear in the broker's entity lists and should be self-explanatory.

***

## Troubleshooting

> **Cell won't run?**
>
> * Check that you're connected to the broker (look for connection status in status bar)
> * Verify your credentials are correct
> * Ensure the broker is running and accessible

> **LoT not deployed — license limits?**
>
> If running a cell shows an **error** and the broker rejects the definition because you have reached a **license limit** (for example on actions, connectors, or another licensed resource), deployment stops and the message under the cell should describe the limit.
> Open the **Coreflux** view in the Activity Bar and check the **Coreflux Explorer** section for your **license** status and usage so you can see what is capped. To raise the plan, see [Licensing and Enrollment](/latest/mqtt-broker/licensing).

> **Python script not recognized?**
>
> * Confirm the first line is `# Script Name: YourScriptName`
> * Check for syntax errors in the Python code
> * Ensure function names match what you're calling from LoT

> **Entity not appearing after deployment?**
>
> * Check the output for error messages
> * Verify no syntax errors in your LoT code
> * Use the Coreflux Entities panel to refresh the list

***

## Next Steps

> **[Debug in VS Code](./debug)**
>
> Use cell output, Coreflux Entities, and live MQTT values to fix issues.

> **[Explore Tutorials](./tutorials)**
>
> Work through hands-on notebooks covering Actions, Models, Connectors, and Python.

> **[Extension Release Notes](/product-updates/release-notes#vs-code-extension)**
>
> See what shipped in each VS Code extension release.


# Fleet
Source: https://docs.coreflux.org/portal/fleet

Add brokers to your Coreflux Portal organization, connect running brokers, and follow their status and performance

## Why Use Fleet?

**Fleet** lists every broker in your organization in one table — where it runs, whether it is online, which version it runs, and which license it uses. You add brokers here, and open any broker to see its performance.

![Coreflux Portal Fleet table listing brokers with their address, status, hosting, alerts, CPU, and throughput](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-fleet-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=587acf689e9fe56d59d440c7c2b34594)

Fleet with brokers in different states

## Add a Broker

Click **Add broker** in Fleet. The first question is **Where will it run?**

| Option | When to choose it |
| - | - |
| **On a computer or server I manage** | Install a new broker on Windows, Linux, or Docker. The Portal walks you through it and renders the install command. |
| **I already have a broker running** | Connect an existing broker with an activation code or a one-time connection code. |
| **In Coreflux Cloud** | Coreflux runs and looks after the broker for you. It joins Fleet like any other broker. |

![Coreflux Portal Add broker dialog asking Where will it run, with options to install on a computer you manage, connect a running broker, or use Coreflux Cloud](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-add-broker-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=d90c879c812a3d7ad28d32a7f31b0d61)

Add broker: Where will it run?

> [!NOTE]
>
> Adding a license to a broker needs a license with a free place. If your organization has none yet, the Portal asks you to get a license first — start a trial or claim one in [Licensing](/portal/licensing).

### Install a New Broker

The Portal shows the commands for your platform — `docker run`, a Linux service, the Windows installer, or `helm install` — with your activation code already filled in. The broker starts with `COREFLUX_ACTIVATION_CODE`, activates its license, and joins your Fleet on its own.

> [!WARNING]
>
> The activation code is shown **once**. The Portal keeps only a hash of it. Later views of the install command show a placeholder instead; replace it with your code, or get a new one from the license page.

> [!TIP]
>
> Keep the broker's data volume (mounted at `/etc/project` in Docker) persistent. The broker stores its identity there. Without it, every restart counts as a new install and uses another license place.

### Connect a Running Broker

For a broker that is already running, choose **I already have a broker running**, pick the license, and click **Get activation command**. The Portal shows the activation code and the command to publish to `$SYS/Coreflux/Command`. The broker picks up your license and joins your Fleet. The code is shown once and is valid for 20 minutes. See [Licensing and Enrollment](/latest/mqtt-broker/licensing) for the broker side.

![Animation of the Add broker dialog: choosing I already have a broker running, picking a license, and getting the activation command](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-add-broker-flow-light.gif?s=5d0025303faf26f4d86236e6cc98fad5)

Connect a running broker and get its activation command

![Coreflux Portal Activate the broker dialog with a redacted activation code and the -activateLicense command for \$SYS/Coreflux/Command](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-activation-command-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=8ebae101627dade6e225a0d1f06fdbc8)

The activation command, shown once

To add a broker without a license, choose **Add to Fleet without a licence**. Name the broker, and the Portal creates a **one-time connection code** for it, with the `-enroll` command to publish to `$SYS/Coreflux/Command`. The code is shown once, works once, and is valid for 20 minutes. You can activate a license on that broker later.

![Animation of the Add broker dialog: choosing Add to Fleet without a licence, naming the broker, and getting a one-time connection code](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-connection-code-flow-light.gif?s=c6013d8ff165ea7766cb6400e703e940)

Add a broker without a license and get a one-time connection code

![Coreflux Portal One-time connection code dialog with a redacted code and the -enroll command for \$SYS/Coreflux/Command](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-connection-code-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=2af58562fbe68f6e5dc800029b013ff9)

The one-time connection code, shown once

### Deploy in Coreflux Cloud

Choose **In Coreflux Cloud** to have Coreflux run the broker. The Portal starts the deployment and shows its progress in Fleet (**Deploying**, or **Deploy failed** with the reason). Only admins and owners can deploy to Cloud.

## Broker Status

| Status | Meaning |
| - | - |
| **Online** | The broker is reporting. |
| **Offline** | The broker stopped reporting. |
| **Offline over a day** | No report for more than a day. |
| **Never reported** / **Not reporting yet** | The broker is in Fleet but has not reported yet. |
| **Never activated** / **Waiting for activation** | The broker was added but has not activated a license or joined with its code yet. |
| **Disconnected** | The broker was disconnected from Fleet. |
| **Deploying** / **Deploy failed** | A Coreflux Cloud broker that is still being created, or that failed. |

Use **Filter brokers** and the column headers to find a broker in a long list.

## Broker Details

Open a broker to see its address, version, license, and last seen time, plus performance: messages, peak throughput, error rate, time seen online, and charts of messages per second, data, and connected clients. Pick the range with **1h**, **24h**, **7d**, or **30d**. Enrolled brokers' [performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics) are charted on this page.

![Coreflux Portal broker page with the broker's status, version, and license, and charts of throughput and resource use](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-broker-detail-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=633ca6b1893056d5ca1e62ff5ef8c738)

Broker details with performance charts

> [!NOTE]
>
> Performance charts need the broker to send telemetry. A broker that has not been activated shows **Available once this broker is activated**.

## Troubleshooting

> **The broker runs but never appears in Fleet**
>
> The broker reports why on `$SYS/Coreflux/License`, under `Enrollment.Reason`. Common causes:
>
> * The broker started without an activation code, so it runs the free edition.
> * The broker cannot reach the platform on port 443. Allow it through your firewall or proxy; the broker retries on its own.
> * The license is not claimed by an organization. Start a trial or claim the license in **Licensing**, then restart the broker.
>
> Until it joins, the broker keeps working for local users.

> **The broker has no internet access**
>
> An activation code needs the license service online. Offline sites use a signed license file instead; ask Coreflux support for one. A broker licensed this way does not appear in Fleet.

> **After a restart the broker appears twice, or a license place is used up**
>
> The data volume was lost, so the broker started as a new install. On the license page in **Licensing**, free up the old broker's place, and keep the volume persistent from then on.

> **A one-time connection code was refused**
>
> One-time connection codes work once and are valid for 20 minutes. Get a new code from the broker in Fleet and use it straight away.


# Getting Started with the Portal
Source: https://docs.coreflux.org/portal/getting-started

Create a Coreflux Portal account, create an organization, and start your 30-day trial

## Why This Matters

Everything in the Portal belongs to an **organization**: brokers, licenses, and members. A new account starts with no organization, so the first steps are to sign up, create one, and start your trial.

## Create an Account

**1. Open the sign-up page**

Go to [portal.coreflux.org](https://portal.coreflux.org/) and choose to create an account.

![Coreflux Portal sign-up page with fields for a new account and the 30-day free trial message](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-sign-up-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=b28df3c45119dd071a365fa710a65e2a)

Create an account on the Coreflux Portal

**2. Confirm your email**

The Portal emails you a confirmation code. Enter it to finish creating the account.

**3. Sign in**

Sign in with your email and password. If you forget the password, use **Forgot password** on the sign-in page to reset it.

> [!NOTE]
>
> The same Coreflux account signs you in to the Coreflux HUB desktop app. See [Account and Fleet](/hub/account-and-fleet).

## Create an Organization

After your first sign-in, the Portal asks you to create an organization. Give it a name; you become its **owner**. You can create more organizations later from the organization switcher.

![Coreflux Portal Create organization form with an Organization name field and a Create organization button](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-create-organization-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=4f98517474de7850dc2f7481f7b87586)

Create an organization

If a colleague invited you, open the invitation link from the email instead. Accepting it adds you to their organization with the role they chose.

## Start Your Trial

**1. Open Overview**

While your organization has no trial and no brokers, **Overview** guides you through the first steps.

**2. Start the trial**

Start the free trial: one broker, free for 30 days, one trial per account.

**3. Keep the activation code**

The Portal shows the trial's activation code **once**. It does not keep a copy. If you lose it, open the license in **Licensing** and choose **Get a new activation code**.

**4. Add your broker**

Continue to **Fleet** → **Add broker** to install and activate the broker. See [Fleet](/portal/fleet).

> [!WARNING]
>
> Only one trial is available per account, even if you delete the organization that held it.

## Download the Broker and HUB

The **Downloads** page lists the published broker and HUB packages. It is public, so you can download before you sign up.

![Coreflux Portal Downloads page listing the Coreflux MQTT Broker and Coreflux HUB packages for each operating system](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-downloads-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=075e2063ceeeceaf89d8b5de17186f7a)

Downloads page with the broker and HUB packages


# Licensing
Source: https://docs.coreflux.org/portal/licensing

See your trial and licenses in the Coreflux Portal, claim a license you bought, request a license, and rotate activation codes

## Why Use Licensing?

**Licensing** shows what your organization is entitled to: your trial and every license, what each one includes, and which brokers use it.

## Licenses List

Each license shows its plan, its status, and how many of its places (activations) are used. A trial reads as **trial**; on the broker it acts as **Growth**. Open a license to see its features, the brokers that use it, and where it came from.

![Coreflux Portal Licensing page listing Growth, trial, and Enterprise licenses with status, broker use, and expiry, and a license request waiting for reply](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-licensing-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=dde02ba3ff2ef41f7cbb8d99c110409e)

Licenses and license requests

![Coreflux Portal license page with plan, status, time left, brokers on the license, and the included features and limits](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-license-detail-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=4d1fda565ae60fe19a696287bb4ab257)

A license and what it includes

> [!NOTE]
>
> Two numbers in the Portal both look like "seats". **Member seats** count the people in your organization. A license's **activations** count broker instances — a trial allows one. They are separate.

## Claim a License You Bought

**1. Open Claim licence**

In **Licensing**, choose **Claim a licence**.

**2. Enter the activation code**

Use the code from your purchase confirmation, or the one Coreflux support sent you.

**3. Claim it**

Click **Claim licence**. The license appears in your organization, and the code keeps working afterwards.

![Coreflux Portal Claim a licence dialog with an Activation code field](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-claim-license-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=9e1e57873642d5ed165d19dd92733732)

Claim a licence

## Request a License

To buy a license, choose **Request a licence** in **Licensing**. Tell Coreflux what it is for, how many brokers you need (leave it blank if you are not sure), a contact email, and anything else they should know, then click **Send request**. The Coreflux team replies at the contact email, usually within 2 business days. Nothing is billed in the Portal. While a request is open, **Licensing** shows **View request** instead.

![Coreflux Portal Request a licence dialog with contact email, purpose, number of brokers, and notes fields](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-request-license-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=d026da756e5a6617a3c4de04542330d4)

Request a licence

## Get a New Activation Code

An activation code is shown only once. If you lose it, open the license and choose **Get a new activation code**. The license itself is not affected, and brokers that are already activated keep running.

## Free Up a Broker's Place

If a broker was reinstalled without its data volume, it counts as a new install and uses another place. On the license page, choose **Free up this broker's place** for the old instance.

> [!TIP]
>
> Managing licenses — starting a trial, claiming, or requesting — needs the **admin** role or above. An engineer can use a license that is already in the organization when adding a broker.


# Coreflux Portal
Source: https://docs.coreflux.org/portal/overview

Start a free trial, license your brokers, and manage your broker fleet and team from portal.coreflux.org

![Coreflux Portal sign-in page with email and password fields, a link to create an account, and the free trial message](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-sign-in-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=5bd8bc50df3dd3d93a2f73a66815a9b2)

Sign in to the Coreflux Portal at portal.coreflux.org

## Why Use the Portal?

Licensing a Coreflux broker used to mean asking your Coreflux contact for a license file. The Portal at [portal.coreflux.org](https://portal.coreflux.org/) makes it self-serve: create an account, start a 30-day trial, get a licensed broker running, and see it report in — without opening a support thread.

> [!TIP]
>
> **Like a control room for your brokers.** The brokers do the work on your machines or in Coreflux Cloud. The Portal is where you see them, license them, and decide who on your team can do what.

## When to Use It

* **Trying Growth features** — Start a 30-day trial that licenses one broker with Growth features
* **Licensing a broker** — Get an activation code and the exact install command for Docker, Linux, Windows, or Helm
* **Keeping an eye on brokers** — See which brokers are online, which version they run, and how they perform in **Fleet**
* **Working as a team** — Invite colleagues into your organization and give each one a role
* **Adding a license you bought** — Claim it with its activation code so it shows up in your organization

## What You Find in the Portal

| Area | What it does |
| - | - |
| **Overview** | The first screen of an organization: fleet status, brokers that need attention, licence use, broker shortcuts, and recent activity. While the organization is empty, it walks you through starting a trial and adding your first broker. |
| **Fleet** | The brokers in your organization, their status, version, hosting, and performance. **Add broker** starts here. |
| **Licensing** | Your trial and licenses, what each one includes, which brokers use it, and license requests. |
| **Team** | Members, pending invitations, and groups. |
| **Settings** | Organization name, the MFA policy, and audit logs. |
| **Downloads** | Public broker and HUB packages. You do not need an account to download. |

![Coreflux Portal Overview page with fleet status counts, a Needs attention card, licence usage, broker shortcuts, and recent activity](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-overview-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=d97b173eca51a5c43b669f0970b9c64b)

Overview of an organization with fleet status, alerts, licences, and recent activity

> [!NOTE]
>
> The broker's free edition runs without an account. You need the Portal only when you want a licensed broker, a trial, or Fleet management.

## Trial and Editions

The trial lasts **30 days**, covers **one broker**, and is limited to **one trial per account**. The Portal shows its plan as **trial**. On the broker it lands as **Growth** entitlement, so Growth features such as custom ACL rules work during the trial. See [Licensing and Enrollment](/latest/mqtt-broker/licensing) for how the broker uses its license.

Licenses are signed, and the broker checks them offline. A licensed broker keeps running when it cannot reach the Portal.

## Next Steps

> **[Getting Started](/portal/getting-started)**
>
> Create an account and an organization, then start your trial.

> **[Fleet](/portal/fleet)**
>
> Add a broker and follow its status.

> **[Licensing](/portal/licensing)**
>
> Claim, request, and manage licenses and activation codes.

> **[Team and Settings](/portal/team-and-settings)**
>
> Invite colleagues, set roles, and turn on MFA.


# Team and Settings
Source: https://docs.coreflux.org/portal/team-and-settings

Invite colleagues to your Coreflux Portal organization, assign roles and groups, require MFA, and review audit logs

## Why This Matters

Not everyone who works with your brokers needs to change them. **Team** lets you invite colleagues and give each one only the access they need. **Settings** holds the organization-wide options.

## Roles

| Role | What it is for |
| - | - |
| **Viewer** | See everything in the organization. |
| **Engineer** | Add and set up brokers. |
| **Admin** | Brokers, licenses, people, and settings. |
| **Owner** | Own the organization. Every organization keeps at least one owner. |

Every role can do everything the one before it can, and a little more.

## Invite a Colleague

**1. Open Team**

Go to **Team** → **Members** and choose **Invite member**.

**2. Choose the role**

Enter their email and pick a role.

**3. Send the invitation**

They receive an email with a link to accept. Pending invitations are listed in **Team** until they are accepted.

> [!NOTE]
>
> Each pending invitation already counts against your organization's member seats.

![Coreflux Portal Team page listing members with their role, groups, and join date, and an Invite member button](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-team-members-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=c1baef6a63e5275c93205b30c0364c9c)

Team members and their roles

## Groups

The **Groups** tab in **Team** lets you create groups and assign members to them. Groups are named sets of members that the broker applies on its next reconnect. Managing groups needs the **admin** role.

![Coreflux Portal Groups tab listing groups with their description, member count, and members](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-team-groups-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=c9944ea43c33bfb541f8fd00c1f8dc1b)

Groups in Team

## Settings

| Setting | What it does |
| - | - |
| **Organization name** | Rename the organization. |
| **MFA policy** | **Require MFA to access organization** for every member. |
| **Audit logs** | Changes to the organization, and who made them. |

Settings has three tabs: **General**, **Security**, and **Audit Logs**. To require MFA, open **Security**, turn on **Require MFA to access organization**, and click **Save**. Members then need an authenticator on their account before they can use Fleet, Licensing, Team, or Settings.

![Coreflux Portal Settings Security tab with the Require MFA to access organization switch turned on](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-settings-security-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=88d17458cc42b43ba1d5727b54f4f8fb)

Require MFA for the organization

![Coreflux Portal Settings Audit Logs tab listing when, who, and what changed in the organization](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/portal/portal-settings-audit-logs-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=53f07d2642221eb1f8726646b24dbff6)

Audit logs


# Coreflux Agent Skills
Source: https://docs.coreflux.org/ai/agent-skills

Install the Coreflux agent skills so coding agents write valid LoT and work with the broker

## Teach Your Agent LoT

Coding agents are good at general-purpose languages but have never seen LoT (Language of Things). The [documentation MCP](/ai/mcp) lets an assistant look syntax up while it works. **Agent skills** go one step further: they put the LoT and broker knowledge in the agent's own skills folder, so the agent loads it whenever a task calls for it.

[coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) is the central, public repository of Coreflux [Agent Skills](https://agentskills.io). Its skills teach Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, and other agents to write LoT and to work with the Coreflux MQTT broker. It is MIT licensed.

> [!NOTE]
>
> The Coreflux agent skills are available for broker **2.22 or later**.

> [!TIP]
>
> **Like handing a new engineer the plant's field manual on day one.** They still ask questions (the MCP), but they already know the vocabulary, the rules, and the safe way to make a change.

### When to Use This

* You write LoT with a coding agent and want it to **get the syntax right the first time**
* You want the agent to **validate before it deploys** LoT through the broker's [MCP Server](/latest/mqtt-broker/mcp-server)
* You want **one source of truth** for Coreflux skills across Claude Code, Cursor, VS Code, and other agents
* You need skills that **match a specific broker release**

***

Pick the skills your work needs, then install them with the method that fits your agent.

## Available Skills

The repository holds one folder per skill under `skills/`. `skills.json` lists them all.

| Skill | Use it for |
| - | - |
| `lot-actions` | Actions: triggers, variables, topic operations, control flow, Python and LLM calls |
| `lot-models` | Models: data schemas, field types, topic bindings, storage, inheritance |
| `lot-routes` | Connectors: databases, OT (Modbus, S7, OPC UA, …), REST, MQTT bridges, AI |
| `lot-rules` | Permission rules: ALLOW/DENY, topic patterns, priorities |
| `lot-agents` | `DEFINE AGENT`: LLM connectors, tool grants, delegation |
| `lot-things` | `DEFINE THING`: templates, parameters, references |
| `lot-panels` | LoTV panels: components, bindings, events |
| `lot-themes` | LoTV themes: design tokens, light and dark modes, variants |
| `python-scripts` | Python scripts the broker runs, and `CALL PYTHON` |
| `broker-tools` | The broker's MCP tools and the safe validate → deploy workflow |
| `broker-operations` | Operating a broker over MQTT: `$SYS/Coreflux/Command` and its replies, the `$SYS/Coreflux` topic map, triage, users and permissions, projects and `.lotnb` notebooks |

## Install the Skills

**Any agent**

Use the skills CLI. It works with any agent that reads Agent Skills:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
npx skills add CorefluxCommunity/coreflux-skills
```

**Claude Code**

Add the repository as a plugin marketplace, then install the `coreflux` plugin:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
/plugin marketplace add CorefluxCommunity/coreflux-skills
/plugin install coreflux@coreflux
```

**VS Code and Cursor**

The [LoT Notebooks extension](/lot-notebooks/usage#develop-lot-notebooks-with-ai) has an **Install Agent Skills...** button in its sidebar. Pick the skills to install and the target folders: the `.agents`, `.claude`, `.cursor`, or `.github` skills folder, in the workspace or in your home folder.

**By hand**

Copy `skills/<name>/` from the repository into your agent's skills folder: `.agents/skills/`, `.claude/skills/`, or `.cursor/skills/`. Use the folder in your project for one project, or the one in your home directory for all of them.

### Match Your Broker Version

Tags in the repository match broker releases: the tag for a release has the same name as its broker version. To match the broker you run, add that version after `#`. For example, for broker 2.22.0:

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
npx skills add CorefluxCommunity/coreflux-skills#2.22.0
```

Without a tag, you get the default branch, which follows the broker's main branch.

## Where Skills Come From

The skills are generated from the Coreflux broker. The broker ships the same skills to its built-in agents, and only the skills meant for external agents are exported to coreflux-skills. The export runs on every change to the broker's main branch and on every broker release tag.

> [!WARNING]
>
> Do not open pull requests against coreflux-skills. The next sync overwrites them. Report a problem as an [issue](https://github.com/CorefluxCommunity/coreflux-skills/issues) instead.

A client connected to the broker's [MCP Server](/latest/mqtt-broker/mcp-server#what-the-tools-do) can also read the broker's skill catalogue from the `coreflux://skills` resource.

***

## Best Practices

> **Pair skills with the MCP**
>
> Skills give the agent the rules up front. The [documentation MCP](/ai/mcp) answers the questions the skills don't cover. Use both.

> **Install only what you use**
>
> An agent that writes Actions and Models does not need the panel and theme skills. Fewer skills keep the agent's context focused.

> **Keep project rules separate**
>
> Skills describe LoT and the broker. Your naming, topic layout, and boundaries belong in an [AGENTS.md](/ai/best-practices#setting-up-your-ai-assistant) file.

> **Pin a tag for production**
>
> When the agent works against a production broker, install from the tag that matches its version so the skills never describe syntax that broker does not have.

***

## Next Steps

> **[Coreflux MCP](/ai/mcp)**
>
> Connect your assistant to the Coreflux documentation for real-time lookups.

> **[MCP Server](/latest/mqtt-broker/mcp-server)**
>
> Let an AI client validate and deploy LoT on a live broker.


# AI-Assisted Development Best Practices
Source: https://docs.coreflux.org/ai/best-practices

Set up your AI coding assistant to generate correct, consistent LoT code using AGENTS.md templates and project rules

## Make Your AI Assistant a LoT Expert

AI coding assistants — in Cursor, VS Code with Copilot, or Claude — can generate excellent LoT (Language of Things) code when they know your project's conventions. The key is giving them the right context upfront through an **AGENTS.md** or project rules file.

This page shows you how to set up that context so your assistant produces LoT code that matches your team's standards from the first prompt.

> [!TIP]
>
> **Like a style guide that your co-pilot actually reads.** Just as a design system keeps a UI consistent across 10 developers, a project rules file keeps your LoT code consistent across humans and AI assistants alike.

### When to Use This

* You want your **AI assistant to generate correct LoT code** without constant corrections
* You're setting up an **AGENTS.md**, `.cursor/rules/`, or `CLAUDE.md` file for your project
* You're onboarding **new team members** (human or AI) and need a single reference
* You're starting a **new Coreflux project** and want AI-ready conventions from day one

> [!NOTE]
>
> This page focuses on **AI assistant configuration**. For the underlying conventions, naming rules, topic architecture, code patterns, and anti-patterns, see [Naming conventions](/latest/lot-language/usage-patterns/naming-conventions), [Working with JSON](/latest/lot-language/usage-patterns/working-with-json), [Designing your data layer](/latest/lot-language/usage-patterns/data-layer), and [Anti-patterns](/latest/lot-language/usage-patterns/anti-patterns) — those standards are the foundation for everything below.

***

## Setting Up Your AI Assistant

An **AGENTS.md** file (or equivalent project rules file) tells your AI assistant how to work with your Coreflux project. It prevents the assistant from generating code with wrong naming, invented syntax, or inconsistent patterns. The conventions defined in [Naming conventions](/latest/lot-language/usage-patterns/naming-conventions) form the content — the structure below tells you how to organize them for your assistant.

### What Is an AGENTS.md?

An AGENTS.md is a markdown file in your project root that AI coding assistants read automatically. It works across tools:

| File / Location | Supported By |
| - | - |
| `AGENTS.md` (project root) | Cursor, GitHub Copilot, OpenAI Codex, Google Jules, Aider |
| `.cursor/rules/*.mdc` | Cursor (native format with glob pattern support) |
| `CLAUDE.md` (project root) | Claude Code |
| `.github/copilot-instructions.md` | GitHub Copilot |

For maximum compatibility, use **AGENTS.md** in your project root. If you use Cursor extensively, you can also maintain `.cursor/rules/` files for features like auto-attaching rules to specific file types.

### The Three-Tier Boundary System

The most effective structure for preventing AI mistakes is a **three-tier permission system**. Define what the assistant should always do, what it should ask about first, and what it should never do:

| Tier | Guideline | LoT Examples |
| - | - | - |
| **Always do** | Follow without asking | Use PascalCase for entities, `snake_case` for variables, `lot` language tag for code blocks |
| **Ask first** | Confirm before proceeding | Adding new Connectors (external connections), modifying Rules (access control), removing Actions |
| **Never do** | Refuse even if asked | Invent LoT syntax that doesn't exist, use `LOT` or `lot` capitalization, mention competitor broker products |

### Starter Template

The following template incorporates the conventions from [Naming conventions](/latest/lot-language/usage-patterns/naming-conventions) and related pattern pages. Copy it into an `AGENTS.md` file at your project root and customize the project-specific sections:

> [!TIP]
>
> **Prefer to grab it from GitHub?** The [Coreflux AI Starter](https://github.com/CorefluxCommunity/coreflux-ai-starter) repository has ready-to-use templates (minimal, full, and industrial), pre-built MCP configs for every editor, and filled-in examples you can clone directly.

> [!NOTE]
>
> AGENTS.md is for **your project's** conventions. For LoT syntax and broker workflows, install the [Coreflux agent skills](/ai/agent-skills) (broker 2.22 or later) instead of pasting reference material into the file.

**AGENTS.md**

A cross-platform template that works with Cursor, Copilot, Claude, and other AI tools:

```markdown wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# AGENTS.md

## Project Overview
This is a Coreflux LoT (Language of Things) project for [describe your system].
Built on the Coreflux MQTT broker with LoT Actions, Models, Rules, and Connectors.

## Tech Stack
- **Platform:** Coreflux MQTT Broker
- **Language:** LoT (Language of Things)
- **Extensions:** Python integration (for complex logic only)
- **IDE:** VS Code with LoT Notebooks extension / Cursor

## LoT Naming Conventions
- **Actions:** PascalCase, verb-first (ProcessTemperature, MonitorPressure)
- **Models:** PascalCase, noun-based (SensorReading, EquipmentStatus)
- **Rules:** PascalCase, descriptive scope (AllowAdminActions, ProtectSysTopics)
- **Connectors:** PascalCase, destination-based (CloudBridge, SensorDatabase)
- **Variables:** snake_case in quotes ("sensor_id", "raw_value")
- **Topics:** lowercase/slash-separated (sensors/+/temperature, alerts/critical/+)
- **Model fields:** snake_case ("equipment_id", "runtime_hours")

## Topic Hierarchy
- sensors/    — Raw incoming data
- processed/  — Transformed data
- alerts/     — Threshold violations
- config/     — Configuration values
- state/      — Internal persistent state (KEEP TOPIC)
- cache/      — Cached values
- system/     — Heartbeats and diagnostics
- commands/   — Inbound instructions

## Code Standards
- Always type-cast in calculations: PAYLOAD AS DOUBLE, GET TOPIC ... AS DOUBLE
- Use KEEP TOPIC for internal state, PUBLISH TOPIC for external broadcast
- Mark the primary data field AS TRIGGER in models — never timestamps
- Use COLLAPSED models when Actions need control over publish timing
- Break complex Actions into callable Actions with INPUT/OUTPUT
- Use LoT for publish, subscribe, conditionals, math — Python only for
  ML, complex parsing, or external library calls

## Do
- Always respect the indentation of 4 spaces per additional level
- Use PascalCase for all entity names
- Use snake_case for all variables and model fields
- Add type casts to every numeric operation
- Use descriptive names that explain purpose
- Use lot as the code block language identifier
- Booleans and integers do not use quotes
- Consult the Coreflux MCP for documentation when unsure
- Connectors that call functions from other protocols (like SQL queries) are not limited to the functionalities listed in this documentation, the full range of that external element is usually functional

## Don't
- Do not invent LoT syntax — only use documented keywords
- Do not use LOT (all caps) or lot (lowercase) — always LoT
- Do not mention competitor products (Mosquitto, HiveMQ, etc.)
- Do not trigger models on timestamp fields
- Do not use PUBLISH for internal-only state
- Do not create monolithic Actions — split into callables

## Ask First
- Before adding or modifying Connectors (external system connections)
- Before modifying Rules (access control changes)
- Before removing any existing Action, Model, Rule, or Connector
- Before using Python — confirm LoT can't handle it natively first

## Never
- Never hardcode credentials in Connector definitions for production
- Never leave $SYS/# topics unrestricted
- Never skip type casting in mathematical operations
- Never generate LoT syntax you haven't verified in the documentation
```

**Cursor Rules (.mdc)**

For Cursor-native rules, create `.cursor/rules/lot-conventions.mdc` in your project:

```markdown wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
---
description: LoT development conventions for Coreflux projects
globs: ["*.lot", "*.lotnb", "*.md"]
---

# LoT Conventions

You are an expert LoT (Language of Things) developer for Coreflux.

## Naming
- Actions: PascalCase, verb-first (ProcessTemperature)
- Models: PascalCase, noun-based (SensorReading)
- Rules: PascalCase, descriptive (ProtectSysTopics)
- Connectors: PascalCase, destination-based (CloudBridge)
- Variables: snake_case in quotes ("sensor_id")
- Topics: lowercase/slash-separated (sensors/+/temperature)

## Code Rules
- Always type-cast: PAYLOAD AS DOUBLE, GET TOPIC ... AS DOUBLE
- KEEP TOPIC for internal state, PUBLISH TOPIC for broadcast
- AS TRIGGER on primary data field, never timestamps
- Use COLLAPSED models when Actions control publish timing
- Use lot as the language tag for code blocks
- Python only for ML, complex parsing, or external libraries

## Prohibited
- Do not invent LoT syntax beyond documented keywords
- Do not use LOT or lot — always LoT
- Do not mention competitor MQTT brokers
- Do not create monolithic Actions — split into callables
```

### Keeping It Effective

The best project rules files share these qualities:

| Quality | Why It Matters |
| - | - |
| **Specific** | "Use PascalCase for Actions" beats "use good naming" |
| **Example-driven** | One code snippet beats three paragraphs of description |
| **Iterative** | Start small, then add rules when you see the AI make a mistake |
| **Current** | Update the file as your project conventions evolve |
| **Concise** | A 50-line focused file outperforms a 500-line generic one |

> [!WARNING]
>
> Do not include credentials, API keys, or sensitive connection strings in your AGENTS.md or rules files. These files are typically committed to version control.

***

## Quick Reference Checklist

Use this checklist when reviewing LoT code — whether written by you or generated by an AI assistant:

* [ ] All entity names are **PascalCase** and descriptive
* [ ] All variables and model fields are **snake\_case**
* [ ] All topics are **lowercase with slash separators**
* [ ] All numeric operations include **explicit type casts** (`AS DOUBLE`, `AS INT`)
* [ ] Models trigger on **primary data fields**, not timestamps
* [ ] Internal state uses **`KEEP TOPIC`**, not `PUBLISH TOPIC`
* [ ] Complex logic is split into **callable Actions** with `INPUT`/`OUTPUT`
* [ ] Rules use **permission tags** (`USER HAS`) over user names (`USER IS`)
* [ ] Python is used only where **LoT can't handle the task natively**
* [ ] `$SYS/#` access is left to the broker's **locked built-in Rules** — no permission flags granted to device or operator accounts
* [ ] Custom Rule priorities sit in the **user band** (`100`–`1 000 000`), with broad rules high and specific carve-outs near `100`

***

## Next Steps

> **[Coreflux MCP](/ai/mcp)**
>
> Connect your AI assistant to the Coreflux documentation for real-time syntax help and guided answers.

> **[Working with JSON](/latest/lot-language/usage-patterns/working-with-json)**
>
> GET JSON patterns and structured output with Models.


# Developing with LoT Using AI
Source: https://docs.coreflux.org/ai/developing-with-lot

A beginner's guide to building IIoT solutions with LoT — let your AI assistant handle the syntax while you focus on what to build

## Build IIoT Solutions Without Memorizing a Single Command

You don't need to be a LoT (Language of Things) expert to build industrial IoT solutions with Coreflux. With an AI assistant connected to the Coreflux MCP, you describe **what** you want in plain English, and the AI writes the LoT code for you — correctly, following best practices, using real syntax from the official documentation.

This page walks you through the entire workflow: from setting up the MCP connection to deploying a working IIoT feature, using only natural language prompts. Whether you're monitoring factory temperatures, logging production data to a database, or bridging sensor networks to the cloud — the process is the same.

> [!TIP]
>
> **Like dictating a blueprint to an expert architect.** You describe the building you want — "a sensor system that alerts when temperatures spike" — and the architect draws up structurally sound plans, handles the engineering codes, and hands you something ready to build.

### When to Use This Guide

* You're **new to Coreflux** and want to build something real without learning LoT syntax first
* You have an **AI coding assistant** (Cursor, Claude, Copilot) and want to use it effectively for IIoT
* You want a **step-by-step walkthrough** of the AI-assisted development workflow
* You're exploring whether Coreflux fits your **industrial automation** or **IoT data pipeline** needs

***

## Prerequisites

Before starting, make sure you have:

| Requirement | Details |
| - | - |
| **Coreflux Broker** | Installed and running. See the [Installation Guide](/latest/quick-start/installation) |
| **AI Assistant with MCP** | Cursor, Claude Desktop, Claude.ai, or VS Code with Copilot — connected to the Coreflux MCP |
| **MQTT Client** | MQTT Explorer or any MQTT client for verifying results |

> [!NOTE]
>
> If you haven't connected the Coreflux MCP to your AI assistant yet, follow the [MCP Setup Guide](/ai/mcp#setup) first. It takes under 5 minutes. To give the assistant LoT knowledge up front, also install the [Coreflux agent skills](/ai/agent-skills) (broker 2.22 or later).

You do **not** need prior experience with LoT syntax, MQTT, or industrial protocols. The AI assistant handles the technical details — you focus on describing your goals.

***

## The AI-Assisted Workflow

Every AI-assisted Coreflux project follows three phases. This isn't a suggestion — it's the workflow that consistently produces working results.

| Phase | You Do | The AI Does |
| - | - | - |
| **1. Plan** | Describe the feature in plain English | Asks clarifying questions, proposes an architecture |
| **2. Build** | Review and approve the AI's output | Writes LoT code using the MCP for accurate syntax |
| **3. Verify** | Test the result in MQTT Explorer | Explains what to check and helps debug issues |

The key insight is that **you are the domain expert** and **the AI is the LoT expert**. You know your factory floor, your sensor layout, your business rules. The AI knows the syntax, the patterns, and the best practices. Together, you build faster than either could alone.

***

## Phase 1: Plan Your Feature

The most important step happens before any code is written. A clear plan gives the AI the context it needs to produce working LoT code on the first try.

### Describe Your Goal, Not Your Code

Tell the AI **what** you want to achieve, not **how** to write it. Let it choose the right LoT building blocks.

> [!TIP]
>
> The more specific you are on the components you are working with (for example: hardware brands, specific protocols,  IP addresses, ports, etc.), the better the end result will tend to be.

**Good Prompt**

A clear, goal-oriented description that gives the AI enough context to make architectural decisions:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
I have temperature sensors from brand Y, using ModBus, publishing readings to MQTT topics like 
sensors/temp001/reading as JSON: {"value": 23.5, "unit": "celsius"}.

I want to:
1. Monitor these readings and trigger an alert when temperature exceeds 75°C
2. Store all readings in a PostgreSQL database
3. Convert Celsius to Fahrenheit and publish the converted value

The alert should publish to an alerts/ topic with the sensor ID and the value.
```

**Bad Prompt**

A vague prompt that forces the AI to guess about critical details:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Make me a temperature action.
```

This tells the AI nothing about your topic structure, thresholds, data format, or what you want to happen. The result will be generic at best.

### The Planning Checklist

Before you prompt your AI assistant, gather answers to these questions. You don't need to answer all of them — but the more you provide, the better the result.

| Question | Why It Matters | Example Answer |
| - | - | - |
| **What data comes in?** | Defines the trigger topics and payload format | `sensors/+/reading` with JSON `{"value": 23.5}` |
| **What should happen to it?** | Determines which LoT building blocks to use | Transform, alert, store, forward |
| **Where should results go?** | Defines output topics, databases, or external systems | PostgreSQL table, alert topic, cloud broker |
| **What are the thresholds or rules?** | Sets up conditionals in Actions | Alert when temp > 75°C |
| **How many sensors/devices?** | Affects topic structure and wildcard usage | 50 sensors, each with a unique ID |

> [!TIP]
>
> You can share this checklist directly with the AI. Paste it into your prompt and fill in the answers — the AI will use them to design the complete system.

### Ask the AI to Propose an Architecture

Once you've described your goal, ask the AI to **plan before coding**. This avoids wasted iteration.

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Before writing any code, propose an architecture for this system. 
Tell me which LoT building blocks you'll use (Actions, Models, Connectors, Rules) 
and why. List the MQTT topics you'll create.
```

The AI will consult the Coreflux MCP documentation and respond with something like:

> *"For this system, I recommend:*
>
> * *An **Action** to monitor temperatures and trigger alerts*
> * *A **Model** to structure sensor readings into consistent JSON*
> * *A **Connector** to store readings in PostgreSQL*
> * *A **callable Action** for the Celsius-to-Fahrenheit conversion (reusable)*
>
> *Topic structure: `sensors/+/reading` (input), `processed/+/fahrenheit` (converted), `alerts/temperature/+` (alerts)"*

Review this before saying "go ahead." It's much easier to adjust a plan than to rewrite code.

***

## Phase 2: Build with AI

Now let's walk through a complete guided demo. We'll build a **temperature monitoring system** that reads sensor data, converts units, triggers alerts, and logs to a database — all by prompting the AI.

### Step 1: Create the Core Logic (Actions)

Start with the Action that processes incoming data. Paste this prompt into your AI assistant:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Using the Coreflux MCP for reference, create a LoT Action called 
ProcessTemperature that:
- Triggers on topic "sensors/+/temperature" 
- Extracts the sensor ID from the topic
- Gets the temperature value from a JSON payload with key "value"
- If the temperature exceeds 75, publishes an alert to 
  "alerts/temperature/" followed by the sensor ID
- Publishes the reading to "processed/" followed by the sensor ID

Use proper LoT syntax with type casting.
```

The AI will consult the Coreflux documentation through the MCP and produce working LoT code. Here is what a correct result looks like:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessTemperature
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {temp} > 75 THEN
        PUBLISH TOPIC "alerts/temperature/" + {sensor_id} WITH "HIGH TEMP: " + {temp} + "°C"
    PUBLISH TOPIC "processed/" + {sensor_id} WITH {temp}
```

> [!NOTE]
>
> The AI uses the MCP's `consult_documentation` and `consult_internal_documentation` tools behind the scenes to look up correct syntax. You don't need to tell it to use the MCP — it does this automatically when it detects a Coreflux-related question.

### Step 2: Add Unit Conversion (Callable Action)

Now ask the AI to add a reusable conversion utility:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Create a callable LoT Action called ConvertToFahrenheit that takes a Celsius 
value as input and returns the Fahrenheit equivalent. Then update 
ProcessTemperature to call it and publish the result to 
"processed/" + sensor ID + "/fahrenheit".
```

The AI will produce two connected Actions:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ConvertToFahrenheit
INPUT celsius AS DOUBLE
DO
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
RETURN
    OUTPUT fahrenheit

DEFINE ACTION ProcessTemperature
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {temp} > 75 THEN
        PUBLISH TOPIC "alerts/temperature/" + {sensor_id} WITH "HIGH TEMP: " + {temp} + "°C"
    PUBLISH TOPIC "processed/" + {sensor_id} WITH {temp}
    CALL ACTION ConvertToFahrenheit
        WITH celsius = {temp}
        RETURN temp_f
    PUBLISH TOPIC "processed/" + {sensor_id} + "/fahrenheit" WITH {temp_f}
```

### Step 3: Structure the Data (Model)

Ask the AI to create a Model that formats raw sensor readings into consistent JSON:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Create a LoT Model called TemperatureReading that publishes structured JSON 
to "sensors/formatted/temperature". It should include the sensor ID as a 
static string "TEMP001", the raw value from the sensor topic as the trigger, 
the unit as "celsius", and a UTC timestamp.
```

The result:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TemperatureReading WITH TOPIC "sensors/formatted/temperature"
    ADD STRING "sensor_id" WITH "TEMP001"
    ADD DOUBLE "value" WITH TOPIC "sensors/raw/temperature" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

### Step 4: Connect to a Database (Connector)

Now bring in a Connector to persist the data. Ask the AI:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Create a LoT Connector called SensorDatabase that stores temperature readings 
in a PostgreSQL database. It should:
- Connect to a PostgreSQL server at "db.example.com" port 5432
- Use database "iot_data" with user "iot_writer" and password "secure_pass"
- Insert readings from "sensors/+/temperature" into a table called 
  "temperature_readings" with columns: timestamp, sensor_id, and value

Use proper LoT connector syntax from the Coreflux documentation.
```

The AI generates:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDatabase WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "db.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_writer"
        WITH PASSWORD "secure_pass"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/+/temperature"
        WITH QUERY "INSERT INTO temperature_readings (timestamp, sensor_id, value) VALUES (NOW(), '{value.topic.2}', '{value.json.value}')"
```

### Step 5: Deploy Everything

Ask the AI how to deploy your code:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
How do I deploy all of these LoT definitions to my Coreflux broker? 
I'm using VS Code with the LoT Notebooks extension.
```

The AI will explain the deployment process:

**VS Code (LoT Notebooks)**

The recommended way to deploy LoT code is through the **LoT Notebooks** extension in VS Code or Cursor.

**1. Create a Notebook**

Create a new `.lotnb` file in your project. Each cell can contain one or more LoT definitions.

**2. Add Your Code**

Paste each definition into its own cell — this lets you deploy and test them individually.

**3. Run Each Cell**

Execute cells in order. The extension sends the LoT code to your connected Coreflux broker.

**4. Verify in MQTT Explorer**

Open MQTT Explorer and subscribe to `#` (all topics). Publish a test payload to `sensors/temp001/temperature` and watch the system respond.

**MQTT Client**

You can deploy LoT code by publishing directly to the broker's command topic using any MQTT client.

Publish to the topic `$SYS/Coreflux/Command` with the `-addAction` prefix followed by your LoT code:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION ProcessTemperature
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {temp} > 75 THEN
        PUBLISH TOPIC "alerts/temperature/" + {sensor_id} WITH "HIGH TEMP: " + {temp} + "°C"
    PUBLISH TOPIC "processed/" + {sensor_id} WITH {temp}
```

Use `-addModel` for Models and `-addConnector` for Connectors.

***

## Phase 3: Verify and Iterate

After deploying, test the system by publishing a simulated sensor reading.

### Test Your System

Open MQTT Explorer (or any MQTT client) and follow these steps:

**1. Subscribe to All Topics**

Subscribe to `#` to see all messages flowing through the broker.

**2. Publish a Test Reading**

Publish to `sensors/temp001/temperature` with this payload:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"value": 82.3}
```

**3. Check the Results**

You should see messages appear on these topics:

| Topic | Expected Value | Source |
| - | - | - |
| `processed/temp001` | `82.3` | ProcessTemperature Action |
| `processed/temp001/fahrenheit` | `180.14` | ConvertToFahrenheit callable |
| `alerts/temperature/temp001` | `HIGH TEMP: 82.3°C` | Alert threshold exceeded |

**4. Test Below Threshold**

Publish to `sensors/temp001/temperature` with `{"value": 45.0}`. Verify that no alert is generated — only the processed and fahrenheit topics should update.

### When Something Doesn't Work

If the output isn't what you expect, describe the problem to the AI:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
I deployed the ProcessTemperature action, but when I publish 
{"value": 82.3} to sensors/temp001/temperature, I don't see 
any alert on alerts/temperature/temp001. What could be wrong?
```

The AI will consult the MCP documentation and help you debug — checking for type casting issues, topic mismatches, or deployment errors. **You don't need to debug LoT syntax yourself.** Describe the symptom, and the AI diagnoses the cause.

***

## Prompt Patterns That Work

After building dozens of IIoT features with AI, these prompt patterns consistently produce the best results.

### Pattern 1: Context → Goal → Constraints

Provide the situation, then state what you want, then add any constraints:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Context: I have 20 pressure sensors publishing to "sensors/pressure/+/psi" 
with numeric payloads.
Goal: Alert when any sensor exceeds 150 PSI and log all readings to a 
PostgreSQL table.
Constraints: Alerts must include sensor ID and timestamp. Use a single 
Action for monitoring and a Connector for database logging.
```

### Pattern 2: Ask for Explanation Before Code

When learning, ask the AI to explain its choices:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
I need to store sensor data in a database. Should I use a Connector or an Action 
for this? Explain the trade-offs, then show me the LoT code for the 
recommended approach. Use the Coreflux documentation for reference.
```

### Pattern 3: Incremental Building

Build complex systems one piece at a time rather than all at once:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Step 1: "Create an Action that reads temperature and publishes to a processed topic"
Step 2: "Now add an alert when temperature exceeds 75"
Step 3: "Add a Connector to store readings in PostgreSQL"
Step 4: "Create a Model to structure the data as JSON with sensor ID and timestamp"
```

Each step is small enough for the AI to get right, and you verify as you go.

### Pattern 4: Reference the MCP Explicitly

When you need maximum accuracy, tell the AI to consult the documentation:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Check the Coreflux documentation: what is the correct syntax for defining 
a Modbus TCP connector that reads holding registers from a PLC at 192.168.1.10?
Give me a complete LoT connector definition.
```

This triggers the AI to call `consult_documentation` or `consult_internal_documentation` through the MCP, ensuring the answer uses real, verified syntax.

***

## Common Pitfalls

These mistakes happen frequently when developers start using AI for LoT development. Knowing them upfront saves hours of debugging.

| Pitfall | Why It Happens | How to Avoid It |
| - | - | - |
| **Vague prompts** | AI fills in gaps with assumptions that may not match your system | Always specify topic structure, payload format, and thresholds |
| **Skipping the plan** | Jumping straight to "write me an Action" without context | Ask the AI to propose an architecture before writing code |
| **Not verifying output** | Trusting AI code without testing it | Always deploy and test with a sample payload in MQTT Explorer |
| **Prompting without MCP** | The AI invents plausible-looking but incorrect LoT syntax | Ensure the Coreflux MCP is connected — check your MCP settings |
| **Building everything at once** | One massive prompt produces code that's hard to debug | Build incrementally: one Action, one Model, one Connector at a time |
| **Ignoring type casting** | Numeric operations fail silently without `AS DOUBLE` or `AS INT` | Ask the AI to always include type casts — or review [Anti-patterns](/latest/lot-language/usage-patterns/anti-patterns) |

> [!WARNING]
>
> If your AI assistant is not connected to the Coreflux MCP, it may generate LoT-like code that **looks** correct but uses invented syntax. Always verify the MCP connection before starting a session. Check that the `consult_documentation` and `consult_internal_documentation` tools appear in your assistant's available tools.

***

## Expanding Your System

Once the basic monitoring system works, you can extend it with a single prompt each. Here are natural next steps:

| Feature | Example Prompt |
| - | - |
| **Email alerts** | *"Add a LoT email connector that sends an email when alerts/temperature/+ receives a message"* |
| **Cloud sync** | *"Create an MQTT bridge connector that forwards all processed/ topics to a cloud broker at cloud.example.com"* |
| **Industrial protocol** | *"Create a Modbus TCP connector to read holding registers 0-10 from a PLC at 192.168.1.50 every 5 seconds"* |
| **Access control** | *"Create a LoT Rule that only allows admin users to publish to config/ topics"* |
| **Data aggregation** | *"Create an Action that calculates a 5-minute rolling average of temperature readings"* |

Each of these is a single prompt that the AI can handle using the MCP documentation. The workflow is always the same: describe → review → deploy → verify.

***

## Next Steps

> **[Coreflux MCP Setup](/ai/mcp)**
>
> Haven't connected the MCP yet? Set up your AI assistant's connection to the Coreflux documentation in under 5 minutes.

> **[Best Practices & AGENTS.md](/ai/best-practices)**
>
> Level up your AI workflow with naming conventions, code patterns, and a project rules template that keeps your assistant consistent.


# AI Assistant
Source: https://docs.coreflux.org/hub/ai-assistant

Chat with the built-in Coreflux HUB assistant to get insights from live data, build dashboards, and develop LoT Actions using plain language

![Animated sequence: opening the AI Assistant from the dock, typing a prompt, and the assistant responding and applying changes in Coreflux HUB](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-demo.gif?s=a21be6b72ad7e94afe95ee1a9afd6bdb)

Ask the AI Assistant to build something — it opens, drafts, and deploys in the same panel

## Your Broker, Now With a Teammate

The AI Assistant lives inside the same Coreflux MQTT broker that already carries your sensor, PLC, and cloud traffic. You describe what you want in everyday language—**ask for insights** from the data already flowing through your broker, **build Dashboards** with live widgets and KPIs, or **develop LoT (Language of Things) Actions** that run on the broker—and the assistant uses the broker’s own tools to answer, draft, refine, and deploy. It is not a separate chat app pasted on top; it works with your live system.

> [!TIP]
>
> **Like a colleague who already sits at your control desk** — they can read the same screens you see, suggest the next step, and (when you allow it) wire up the change for you.

## When to Use the AI Assistant

* **Ship integrations faster** — Describe connections or logic you need; the assistant drafts and deploys Connectors, Actions, and panels where your permissions allow.
* **Explore without guesswork** — Ask what topics exist, which Connectors are healthy, or how a KPI is calculated before you change anything.
* **Hand off safely** — Use read-only mode for operators or auditors who should see answers but not apply changes.

The picker beside the composer has two kinds of target:

| Target | Where the loop runs | Use it when |
| - | - | - |
| **HUB** | In the HUB, over the broker's [MCP Server](/latest/mqtt-broker/mcp-server) | Conversation with an operator. Provider keys stay on the HUB. Every write asks first |
| **Broker agent** | On the broker, as a `DEFINE AGENT` | The assistant must run with the HUB closed, be called by another agent, or be reached by another service |

A broker agent is a [LoT agent](/latest/lot-language/routes/ai-routes) with `WITH HUB_VISIBLE "true"` and an interaction topic. The HUB does not list a legacy `TYPE AGENT` connector as a target.

## Run Models On-Premise or in the Cloud

Where inference runs is an architecture and compliance choice. The AI Assistant supports **edge (on-premise)** models and **cloud** providers so you can keep prompts and payloads on your network when you need to, or use hosted APIs when policy allows.

![AI Setup provider list grouped into Cloud (OpenAI selected, Anthropic) and Local/Private (Ollama with NO API KEY tag)](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-providers.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=5f2755a9981563d9bd1abcddd9c3d86b)

Provider picker in the AI Setup wizard — cloud providers (OpenAI, Anthropic, OpenAI-compatible) and a local/private option (Ollama)

* **On-premise (edge)** — Run models on hardware you control, for example **Ollama** on the same host or LAN as the broker, so data does not leave your site.
* **Cloud providers** — Connect to hosted models such as **OpenAI** or **Anthropic**, or any **OpenAI-compatible** endpoint, when your organization allows traffic to leave the network.

> [!NOTE]
>
> **Local AI prerequisite:** [Install Ollama](https://ollama.com/download) and have it running on the broker host (or a machine your broker can reach) before you pick **Local / Private** in the setup wizard. Pull your model in Ollama first (e.g. `ollama pull llama3.2`) — the name you enter in step 2 must match a model already available in Ollama. The model must support **tool calling** (function calling); the Assistant relies on tools to act on your broker, so models without tool-calling support will not work. Check the model's capabilities on the [Ollama model library](https://ollama.com/search?c=tools) before pulling it. Coreflux connects to your Ollama endpoint; it does not install Ollama or download models for you. Lightweight models may work for a quick test, but often are not capable enough for reliable agent work or good answer quality.
>
> If the broker runs in **Docker**, `localhost` inside the container is not the host. With **Docker Compose**, point at the Ollama service (e.g. `http://ollama:11434`). If Ollama runs on the host, use `http://host.docker.internal:11434` (Docker Desktop) or the host's LAN IP. On the broker path the wizard writes that URL onto a `TYPE LLM` connector. See [Picking a provider](/latest/lot-language/routes/ai-routes#picking-a-provider).

### Ollama requirements

Ollama is supported with requirements: the model must call tools, and its context must hold the HUB assistant's prompt.

> [!NOTE]
>
> HUB 2.12 sets Ollama's context (`num_ctx`) for each run, so the Ollama setting no longer matters. It uses at least `HUB_OLLAMA_MIN_CTX` (default 16384) and up to `HUB_OLLAMA_MAX_CTX` (default 32768), never above the model's own maximum. A prompt too large for the model ends the run with a clear error instead of being truncated. On low-memory or CPU-only hosts, lower `HUB_OLLAMA_MAX_CTX`.
>
> The same release ends a run when the model sends nothing for `HUB_AGENT_FIRST_OUTPUT_TIMEOUT_MS`, or goes silent mid-answer for `HUB_AGENT_IDLE_TIMEOUT_MS`. Both default to 120000 (120 s), and time spent inside broker tools doesn't count. Raise them on slow hardware, where the first answer can take minutes. These are HUB server environment variables.

> [!NOTE]
>
> On a HUB older than 2.12, raise Ollama's **Settings > Context length** yourself. The prompt is about 4.5k tokens in Insight mode and 9k to 15k tokens in Agent mode, and those versions silently cut the start of it when the context is too small. 16k is the minimum; 128k is a safe choice.

> [!TIP]
>
> The same Assistant panel and modes work whether you point at an edge endpoint or a cloud API—you are not choosing a different product, only where the model runs.

***

## Set up the AI Assistant

The first time you open the AI Assistant, a short wizard asks whether it should run **in the HUB** or **on the broker**, then walks through **provider**, **model**, and **API key**. When the broker path is not signed in as a local broker user, it also asks which broker user the agent's `DEFAULT_USER` should be. You only do this once per broker; after that, clicking the Coreflux icon opens the assistant directly.

> [!NOTE]
>
> The screenshots below were taken on the previous wizard, which installed an agent connector and said "Install the Agent route". The current wizard starts with **In the HUB** (the default) or **On the broker**. The provider, model, and key steps are unchanged.

**1. Open the AI Setup wizard**

Click the **Coreflux** icon in the bottom dock. On a fresh broker, the **AI Setup** wizard slides in on the right and asks you to pick where the model will run—a **Cloud** provider (OpenAI, Anthropic, or an OpenAI-compatible endpoint) or **Local / Private** (Ollama). Pick one and click **Continue**.

![Coreflux HUB with the AI Setup wizard open on the right, titled Set up AI Assistant with the note Install the Agent route on your broker to enable the AI assistant, a step indicator, Cloud providers OpenAI (selected) and Anthropic, Local / Private Ollama tagged No API key, and a Continue button](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/ai-assistant/hub-ai-setup-provider-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=6183b5872491bd19d4bddbc16ebb2130)

AI Setup wizard, step 1: pick a cloud provider (OpenAI, Anthropic, OpenAI-compatible) or a local Ollama model, then Continue

**2. Pick a model**

Choose a model from the suggested list, or type the exact model name your provider supports (for example `gpt-5.4-mini`) into the custom field. Click **Continue** when you are ready.

![AI Setup wizard model step listing suggested models such as gpt-5.5, gpt-5.4-mini, and a custom model field with gpt-5.4-mini typed in](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-setup-model.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=def936ab3298db1a916726f2f79d29fa)

AI Setup wizard step 2 — choose a suggested model or type a custom one

**3. Add your API key**

Paste the API key from your chosen provider. The key is stored as an **encrypted secret on the broker** and is never sent back to your browser. The wizard also shows a quick summary of what it is about to install so you know what to expect.

> [!NOTE]
>
> If you picked **Ollama** in the earlier step, the wizard skips this screen entirely—your local Ollama endpoint does not need a key.

![AI Setup wizard API key step with an OpenAI API key input, a note that the key is stored as an encrypted secret on the broker, and an install summary card](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-setup-apikey.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=558bc27b8c12a978a8f523e591a4c681)

AI Setup wizard step 3 — paste your provider API key; the broker stores it as an encrypted secret

> **Where do I get an API key?**
>
> Sign in to the provider you picked in the previous step and follow their docs to create a key:
>
> * **OpenAI** — [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
> * **Anthropic** — [console.anthropic.com](https://console.anthropic.com/)
> * **OpenAI-compatible** — the key your endpoint's operator issues, if it needs one
>
> If you picked **Ollama**, no key is required—the broker talks to your local Ollama endpoint directly.

**4. Install and you're ready**

Finish the wizard. **In the HUB** stores the provider and an MCP token for this connection, then the assistant calls the broker as that token's user. **On the broker** deploys a `TYPE LLM` connector named `BrokerAgentLlm` and a `DEFINE AGENT` named `BrokerAgent` on the interaction topic `hub/assistant`, visible in the picker. A key you paste is stored with `-setSecret` and referenced from the connector. Ollama needs no key. An OpenAI-compatible endpoint gets a key only when you supply one, and the connector is pinned to Chat Completions.

![AI Setup wizard showing a Setting up AI Assistant progress indicator with Setting API key secret status](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-setup-installing.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=020cb3cafaa3d294a32252521f5dd1ed)

AI Setup finishing — the broker provisions the assistant in the background

> [!TIP]
>
> Once the wizard closes, the AI Assistant is live on this broker. From now on, clicking the **Coreflux** icon opens the assistant directly—no more setup.

**On the broker**, the wizard also adds subscribe rules so your user can read `$SYS/Coreflux/Agents/#` and the `hub/assistant/#` replies. `DEFAULT_USER` is your local MQTT login. A Coreflux account session is not a broker user — the wizard asks for a **Broker user** and will not install until you choose one. A tool call succeeds only when both you and that user are allowed to make it.

The installed agent is granted `read_mqtt`, `read_lot`, `write_mqtt`, and `create_lot` for actions, models, connectors, and panels. Writing grants are deployed with `WITH LEVEL "write"`. Re-running setup sends `-addConnector` and `-addAgent` again. Both update in place, so the agent keeps its conversations. The broker refuses to remove an LLM connector an agent still uses.

Agents are their own LoT entity. Connectors Manager lists `BrokerAgentLlm` and leaves `BrokerAgent` out. The LoT Editor deploys an agent cell with `-addAgent` and removes it with `-removeAgent`.

***

## Manage broker agents

The **Agents** app on the dock lists every `DEFINE AGENT` on the broker as a card, next to an **Activity** tab. Each card has **Configure**, **Disable** / **Enable**, **Open in LoT Editor**, **Show activity**, and **Remove**. A card with no status shows offline. `DEFINE AGENT` is a preview feature in broker 2.22.

### Disable an agent

The power icon on a card redeploys the agent with `DISABLE true`, or without it. A disabled agent stays defined but takes no tasks. Its card is dimmed, with a **Disabled** pill and a grey status dot. On a broker without `DISABLE` support, the HUB changes nothing and says so. In a cluster, the change applies on the node you're connected to.

![Coreflux HUB Agents window, Agents tab, 2 agents: the FlightsTrackerAgent card is dimmed with a Disabled pill and a grey status dot and shows LocalOllama and read\_mqtt (1 topic); the GateOpsAgent card has a green status dot and shows LocalOllama, ollama, llama3.2 and read\_mqtt (1 topic), write\_mqtt (1 topic). Each card has Configure, power, LoT, activity, and remove icons](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/ai-assistant/hub-agents-disabled-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=7ba27b4b2ed67ab48576b3795cf7b319)

Agents app with FlightsTrackerAgent disabled and GateOpsAgent running

### Configure an agent

**Configure** and **Add agent** open a form with three tabs:

| Tab | What you set |
| - | - |
| **Configuration** | Name, LLM connector, description, default user, and **Enabled**. Then the system prompt, guardrails, interaction topic, **Hub visible**, memory, and peers, and the limits (max iterations, max tokens, task timeout, max in flight) |
| **Tools** | The `ADD TOOL` grants, with their topics or targets and level |
| **LoT** | The `DEFINE AGENT` source, with live checks |

![Coreflux HUB Configure GateOpsAgent dialog with Configuration, Tools 2, and LoT tabs; the Agent section shows Name GateOpsAgent, LLM connector LocalOllama, Description Suggests gate changes when departures run late, Default user flights-ops, and the Enabled switch on, with Cancel and Save](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/ai-assistant/hub-agent-config-form-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=221a3bee482408c4063915922e1c1df1)

Configure GateOpsAgent: the Configuration tab

The LoT stays the source of truth. The form rewrites only the clauses you change and keeps everything else as written, including comments, `GET SECRET` and `GET ENV` values, and clauses the form has no field for, which it lists under **Kept as written**. **Save** deploys with `-addAgent`. Running tasks and session memory are kept unless you rename the agent. See [Agent syntax](/latest/lot-language/agents/syntax).

***

## Coming from a TYPE AGENT assistant

A `TYPE AGENT` connector from an earlier release is skipped when the broker loads, and the HUB does not list it, install it, or migrate it. There is no in-panel update that rewrites it.

Rewrite it as a `TYPE LLM` connector plus `DEFINE AGENT`, using the table in [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent), or run the wizard again and let it install `BrokerAgentLlm` and `BrokerAgent`. Your previous provider, model, and key are not copied for you.

> [!NOTE]
>
> The setup wizard is how you install the assistant. It is not a settings screen for an assistant that is already there. Once the HUB target is configured, the menu offers **Change Hub provider…**, which updates the provider, key, and model and keeps the same MCP token.

***

## Open the AI Assistant

Use the **Coreflux** icon in the bottom app dock—the first icon on the left. You can peek at the assistant without opening the full side panel, then click when you want the full workspace.

**1. Hover to preview**

Hover the Coreflux icon. A compact **Coreflux AI** bubble appears above the dock with an **Ask anything…** field and **Insight** / **Agent** mode pills so you can send a quick prompt or pick a mode before you commit to the full panel.

![Coreflux HUB dock with the Coreflux icon highlighted and a compact Coreflux AI popover showing Ask anything placeholder and Insight and Agent toggles](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-hover.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=4832f01bd4c40af988f40d1c774d0d31)

Hover the dock Coreflux icon to open the compact Coreflux AI bubble with Ask anything and mode pills

**2. Click to open the full panel**

Click the Coreflux icon to pin the **AI Assistant** on the right. You get suggested prompts (for example **Create a dashboard** or **Calculate a new KPI**), a **Sources** area for dragging in panels such as the LoT Editor, and the full conversation thread with edit and close controls in the header.

![Coreflux HUB with the full AI Assistant panel open showing suggested actions, Sources with LoT Editor, and Ask me anything input](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-open.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=051b1570ab0d0c92aebdee66e0254294)

Full AI Assistant panel — suggested prompts, Sources, and the main chat input

## Agent vs Insight mode

Pick the mode that matches how much change you want the assistant to make. You can switch at the bottom of the panel at any time.

| Mode | What it does | Use it when |
| - | - | - |
| **Agent** | Can read broker state **and** create or update things—Connectors, Actions, Models, panels—subject to your permissions. On the **HUB** target, each write pauses for Approve or Reject. On a **broker agent**, writing tools run when the grant says `WITH LEVEL "write"` and both you and `DEFAULT_USER` are allowed. | You want the assistant to **build or change** integrations, logic, or dashboards. |
| **Insight** | **Read-only.** The HUB target never shows write tools. A broker agent is sent `"mode": "insight"`, and the broker refuses every writing tool as out of scope, including tools a peer agent would have run. | You want **safe exploration**, reporting, or to give users answers **without** deploy rights. |

The mode pills sit below the main input so you always know which behavior you have selected before you send a message.

## What you can do

These are typical starting points—phrase them in your own words; the assistant will ask follow-ups if something is missing.

> **[Build a dashboard](/hub/dashboards/overview)**
>
> Ask for live gauges, KPI tiles, or layouts bound to your MQTT topics; the assistant drafts and wires widgets you can refine in the panel. See [Build Your First Dashboard](/latest/quick-start/building-dashboards).

> **Develop an Action in LoT**
>
> Describe triggers, conditions, and outputs in plain language; the assistant proposes LoT you review and deploy without leaving the conversation.

> **Calculate a new KPI**
>
> Describe the metric or inputs you care about; the assistant drafts logic, confirms details with you, and deploys an Action in Agent mode.

> **Explain your broker state**
>
> Ask what Connectors or topics exist, why something errored, or how signals relate—natural in Insight mode when you want answers before any changes.

***

## Example: Build a KPI with Agent mode

Below is one real flow: you ask for a KPI, the assistant requests the missing pieces, then deploys an Action and offers a shortcut to the LoT Editor. Stay in **Agent** mode for this path.

**1. Ask**

Type a goal such as **Calculate a new KPI**. The assistant loads context and may offer quick actions that match what you said.

![AI Assistant showing Agent mode selected and suggested prompts including Calculate a new KPI](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-open.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=051b1570ab0d0c92aebdee66e0254294)

AI Assistant in Agent mode with suggested prompts including Calculate a new KPI

**2. Clarify**

When the assistant needs a formula, source topic, or rule, it **pauses and asks you directly**—you reply in the thread instead of guessing what to type up front.

![AI Assistant conversation where the assistant asks the user to provide KPI formula or source data with a Type your answer field](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-ask-user.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=8ce9eee3ebf0ebfe0e336b4734dbf7ce)

Assistant asking for KPI formula or source data before continuing

**3. Deploy**

After you supply enough detail, the assistant can draft LoT, deploy an Action, and show a status card. Use **Open in LoT Editor** when you want to inspect or tweak the definition yourself.

![AI Assistant showing deployed CalculateKPI Action with Running status and Open in LoT Editor link](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-action-deployed.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=a84807cf92b4bb27a348a2bc1d9b0f87)

Deployed Action with Running status and Open in LoT Editor link

> [!TIP]
>
> When you see **Running** (or equivalent success state) on the deployment card, the new Action is live on the broker—confirm in the **LoT Editor** if you want to read the exact definition.

***

## Example: Explore safely with Insight mode

Switch to **Insight** before you send if you only want answers—not changes. You can still get structured output such as tables and follow-up suggestions.

![AI Assistant in Insight mode responding to 'Please create a list of connectors I have on broker' with a table showing Name, Type, Status, Description, and Events columns for Terminal, BrokerAgent, and MyS7Route](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/ai-assistant/hub-ai-insight-routes.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=93cc5ba1d07a972a3e4aad3faf1a075a)

Insight mode — list of Connectors returned as a table after a natural-language question

Try questions like **Create me a list of Connectors** or **Which Connectors are in a warning state?** The assistant reads broker state and renders the response in the panel without using write tools.

## Built-in safeguards

* **The HUB target runs as the MCP token's user** — Every call passes the broker's own permission check. Writes pause until you approve them. A request that names no mode is treated as Insight.
* **A broker agent runs as the person who asked, capped by `DEFAULT_USER`** — Both must be allowed. A refusal names the user who lacked the right.
* **Insight mode is read-only** — No deploy, publish, or execute path while Insight is selected.
* **Stop at any time** — Long runs can be cancelled from the UI so you are never stuck waiting on a runaway answer.
* **Same deployment path as humans** — Anything the assistant deploys still goes through the broker’s normal validation and permission checks.
* **A shared web HUB does not call arbitrary hosts**: see [Allowed hosts in a browser HUB](#allowed-hosts-in-a-browser-hub).

### Allowed hosts in a browser HUB

The HUB assistant connects from the HUB server to the broker's MCP endpoint and, for Ollama or an OpenAI-compatible provider, to the model's base URL. On a browser or Docker HUB that other people can reach, the assistant stays off until both of these are true:

1. [Coreflux sign-in](/hub/account-and-fleet#sign-in) is configured on the HUB server, and the user is signed in.
2. `HUB_AGENT_ALLOWED_HOSTS` lists the hosts the assistant may reach.

| Variable | Role |
| - | - |
| `HUB_AGENT_ALLOWED_HOSTS` | Comma-separated list of the broker MCP hosts and Ollama or OpenAI-compatible servers the HUB assistant may connect to. A bare host (`broker.example.com`) matches any port. `host:port` (`10.0.0.5:6278`) matches only that port. Matching is exact and case-insensitive: `evilbroker.example.com` does not match `broker.example.com` |

```bash wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
HUB_AGENT_ALLOWED_HOSTS=broker.example.com,10.0.0.5:6278
```

* **Unset or empty**: the assistant is off and reports **HUB\_AGENT\_ALLOWED\_HOSTS names no broker it may reach.**
* **Sign-in not configured**: the assistant is off and tells you to use a broker agent or the desktop app.
* **Not signed in**: **Sign in with your Coreflux account to use the Hub assistant.**
* **Host not listed**: **This Hub may not reach `<host>`. Add it to HUB\_AGENT\_ALLOWED\_HOSTS.**

OpenAI and Anthropic use their fixed API addresses and need no entry. The desktop app listens only on loopback and ignores this variable. Broker agents run on the broker and are not affected.

***

## Broker agents in the HUB

**LoT → Agents** (also the dock and the status-bar **Agents** widget) is where you manage broker agents and watch them work. Add and configure from that window. Saving an existing agent sends `-addAgent` again, which updates it in place and keeps its conversations. Removing an agent cancels its running tasks and forgets its session memory. The activity view is read-only: it follows the task stream, and a question started by `CALL AGENT` shows up as a short preview.

Connectors Manager lists connectors only. An LLM connector can show how many agents use it. The broker refuses to remove that connector while an agent still names it.

***

## Best practices

> **Start in Insight when you are learning**
>
> Use Insight to map topics, Connectors, and health first. Switch to Agent only when you are ready for the assistant to create or update broker objects.

> **Always review what was deployed**
>
> Open new Actions or Connectors in the **LoT Editor** or **Connectors** app to read names, triggers, and bindings before you rely on them in production.

## Next steps

> **[LoT Editor](/hub/lot-editor)**
>
> Open and refine Actions, Models, and Rules the assistant creates—same editor, full control.

> **[Connectors overview](/hub/routes/overview)**
>
> Add or monitor Connectors the assistant can read and help you configure next.


# Cluster Viewer
Source: https://docs.coreflux.org/hub/cluster-viewer

See the nodes, leader, links, LoT ownership, and partitions of a Coreflux cluster from the broker host you are connected to

## Why Use Cluster Viewer?

A cluster is several broker hosts acting as one system. Cluster Viewer draws that system from the broker host you are already connected to, so you can see who leads, which links are up, which node owns each exclusive piece of LoT, and how partitions are placed — without opening a shell on every host.

> [!NOTE]
>
> Cluster Viewer carries a **Beta** badge on its window. The dock icon is labeled **Cluster**. It appears only while the connected broker host is publishing cluster status.

> [!TIP]
>
> **Like a seating chart that updates itself.** You see who is leading, who is sitting in, and who is holding each shared task — from the one host you opened.

## When to Use It

* **Confirm the cluster is up** — See which members are alive and who the leader is
* **Check a link** — See whether data-plane links between hosts are connected
* **Find who runs an exclusive piece of LoT** — Timers, `ON START` actions, exclusive connectors, and scheduled connector events run on one node
* **See partition placement** — See which host owns each partition and where the copies sit

Clustering is an Enterprise license feature. If the license does not grant it, the broker runs standalone and this icon stays off the dock. See [High-availability clustering](/latest/mqtt-broker/clustering) and [Licensing](/latest/mqtt-broker/licensing).

***

Open **Cluster** on the dock. The window is read-only. It reads the cluster status the connected broker host publishes. It does not elect a leader, move ownership, or change cluster settings.

If clustering is off, the icon is not on the dock. Opening the window another way shows that the connected broker is not publishing cluster status.

## What the Window Shows

A strip across the top summarizes the cluster as this broker host sees it:

| Item | What it tells you |
| - | - |
| **Cluster** | The cluster identity |
| **Leader** | The host that currently leads |
| **Members** | How many members are alive out of the member count |
| **Term** / **Commit** | How far leader election and the committed log have progressed |
| **LoT** | Whether nodes are on the same committed LoT version, or the versions are mixed |
| **Data plane** | How many links between hosts are up |
| **Listeners** | Whether any server-connector listener on a member has failed |

The strip also says the view is **Live** (or how old the status is), which host you are seeing it from, and that it is **read-only**.

The canvas draws each member and the links between them. Select a node to open it on the **Node** tab. Select a link to see each direction. The leader is marked on its node. A host the status names but does not describe yet is drawn as unidentified.

> [!WARNING]
>
> The picture is the view from the broker host you are connected to. It is not a second login to every member.

## Details

**Node**

The selected host: whether it is alive, its role, and its endpoint when the cluster published one.

For the host you are connected to, the tab also shows the term and commit index, and whether that host holds the LoT lease.

**LoT** shows the version this host has applied against the version the cluster has committed, whether those match, and any apply errors. **Connector listeners** lists the server connectors that host reported. **Outgoing data-plane links** lists the links that start on this host.

![Coreflux HUB Cluster Viewer window with the Node tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the node details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-node-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=3304d205524e2aaa61ab65c8148a1547)

Node tab: the selected host, its role, LoT version, connector listeners, and outgoing data-plane links

**Links**

**Replication** on the host you are connected to: connected peers, forward backlog, dropped forwards, quorum failures, and how long the last quorum took.

**Data-plane links** lists every reported link, with its state (connected, connecting, disconnected, or unknown). A stale report is marked stale.

![Coreflux HUB Cluster Viewer window with the Links tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the links details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-links-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=b6c4bc1d5c2b32904f7410f31fd3fc97)

Links tab: replication on the connected host and the state of every data-plane link

**Ownership**

Which host runs each piece of LoT that must run on exactly one node:

| Kind | What it is |
| - | - |
| **Actions (timers, ON START)** | Scheduled actions, and actions that run once when the cluster session starts |
| **Exclusive connectors** | Connectors that hold a device, a serial port, or a server port |
| **Scheduled connector events** | A connector's timed events |

**Owner** is the host that runs it. **Next** is the host that takes it if the owner is lost. **Epoch** goes up each time the entity moves. **Unowned** means no live host can run it, so it runs nowhere until one can. An exclusive connector is defined on every node, but only its owner opens the connection. The others hold it ready.

Select a node on the canvas first if you want the list limited to entities that node owns.

![Coreflux HUB Cluster Viewer window with the Ownership tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the ownership details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-ownership-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=3098b8f9b250f96a0bc10111f13db364)

Ownership tab: which host owns each exclusive action, connector, and scheduled connector event

**Partitions**

The partition map: how many partitions there are, the replication factor, how many are under-replicated, and which host owns each one.

Under-replicated partitions still work. Their replica set is smaller than the factor because there are not enough live hosts to place every copy — for example while a host is down. A healthy cluster shows none.

Pick a host to highlight the partitions it owns, the ones where it only keeps a copy, and the ones it does not hold.

![Coreflux HUB Cluster Viewer window with the Partitions tab selected: the cluster summary strip across the top, the cluster members and links on the canvas, and the partitions details panel](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-partitions-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=08e8a96be261df65232867e5e2f0b2a9)

Partitions tab: the partition map, replication factor, and owner of each partition

**Clients**

The MQTT clients connected to each node right now, with a total across the cluster. A client is connected to one node. Behind a load balancer, the node can change each time it reconnects.

Under **Show the clients of**, pick **All nodes** or one node. Filter by client ID, user, or address, and sort by **Last active**, **Newest connection**, **Most queued**, or **Client id**. The connections the nodes open to each other are hidden unless you turn on **Show the cluster's own connections**.

Each card shows the client ID, user, address, MQTT version, messages in and out, and when it was last active. A **queued** badge counts messages waiting for that client; a number that keeps growing means the client isn't keeping up. Expand a card for when it connected, its last packet, bytes in and out, and how long the broker keeps its session after it disconnects.

Lists refresh every 7 seconds. Other nodes' clients are relayed by those nodes, so they can be a few seconds older. An older broker reports only the clients of the node you're connected to.

![Coreflux HUB Cluster Viewer for cluster acme-plant, leader acme-mqtt-2, 3/3 members alive. The Clients tab shows 9 clients (+12 cluster connections) and 0 queued messages, the node filters All nodes, acme-mqtt-1 4, acme-mqtt-2 3, and acme-mqtt-3 2, the filter box, the Last active sort, and the Show the cluster's own connections checkbox, above cards for hmi-panel-03, the HUB's own connection, line1-plc-gw, and energy-meter-gw, each with node, user, address, MQTT version, messages in and out, and last activity](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/cluster-viewer/hub-cluster-viewer-clients-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=c447f955d698db7e81dfa195823d229a)

Clients tab on a three-node cluster: nine clients across acme-mqtt-1, acme-mqtt-2, and acme-mqtt-3, sorted by last active

An older broker host may publish only part of this view. The window then names what is missing and still shows the status it did receive.

***

## Next Steps

> **[High-Availability Clustering](/latest/mqtt-broker/clustering)**
>
> Turn clustering on, choose discovery, and read what failover does and does not cover.

> **[Connections Manager](/hub/connections)**
>
> Open the broker host whose cluster status this window reads.


# Connections Manager
Source: https://docs.coreflux.org/hub/connections

Save multiple broker connections, switch between them without logging out, and secure each one with its own TLS certificates

![Coreflux HUB login card with Local Connections 2: Coreflux local at mqtt://localhost:18840 tagged Coreflux and Mosquitto local at mqtt://localhost:18830 tagged MQTT, both Online with an anonymous identity and Connect buttons, plus All and Starred filters and New Connection](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/connections/hub-login-screen-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=19b9b3a1e41004e0baee97fcf8ccdf4b)

Coreflux HUB login screen with two saved local connections, their broker type and live status, and a New Connection button

## Why Use the Connections Manager

If you work with more than one broker — a local development instance, a staging cluster, a production site — the HUB remembers each one as a saved connection instead of a single remembered URL. Pick a broker from the list to sign in, probe every saved broker for reachability before you commit, and jump between brokers from the account menu without logging out and re-entering details.

## Adding a Connection

**1. Open New Connection**

On the login screen, click **New Connection** in the header (or click a saved card's edit action to modify an existing one). The connection form opens in the same card.

**2. Fill in the broker details**

Enter a name, the **Protocol** (`mqtt://`, `mqtts://`, `ws://`, or `wss://`), **Host**, and **Port**. For a HUB and broker started together with Docker Compose, use **Host** `broker` rather than `localhost` — the HUB proxies MQTT from inside Docker.

![Coreflux HUB connection form for Coreflux local with protocol mqtt://, host localhost, port 18840, the preview mqtt://localhost:18840, an Authentication row No username or password marked Default, Add user, Advanced options, and Save, Test, and Connect buttons](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/connections/hub-login-setup-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=8a0bc7ffdfd5adeaff1721a8a0c3acf2)

Connection form for Coreflux local: name, protocol, host, port, and its identities

**3. Add an identity**

Add at least one identity: a username and password, or an anonymous identity if the broker allows anonymous access. A connection can hold several identities — see [Identities and Switch User](#identities-and-switch-user) below.

**4. Test, then Save or Connect**

Click **Test** to attempt a throwaway connection with the details you entered, without saving anything. Click **Save** to store the connection for later, or **Connect** to save and sign in immediately.

## Default connection (web / Docker)

A web HUB started with Docker can open **New Connection** with the broker already filled in, so a lab or demo does not make every visitor type the address. Set the variables on the HUB container. The HUB reads them when the container starts. The desktop app ignores them.

Setting `HUB_DEFAULT_CONNECTION_HOST` turns the feature on. The other variables are optional. The values pre-fill the **New Connection** form only. They never create or rewrite a saved connection. The connection is stored when someone clicks **Save** or **Connect**, the same as a form they typed.

| Variable | What it sets |
| - | - |
| `HUB_DEFAULT_CONNECTION_HOST` | Broker host. Setting this turns the feature on |
| `HUB_DEFAULT_CONNECTION_NAME` | Name on the form. When omitted, the name is filled in when the connection is saved |
| `HUB_DEFAULT_CONNECTION_PROTOCOL` | `mqtt`, `mqtts`, `ws`, or `wss`. A trailing `://` is accepted. When omitted, the form uses `ws` |
| `HUB_DEFAULT_CONNECTION_PORT` | Port. When omitted, the usual port for that protocol |
| `HUB_DEFAULT_CONNECTION_PATH` | WebSocket path. When omitted, `mqtt` |
| `HUB_DEFAULT_CONNECTION_USERNAME` | Username on the form. When omitted, the form keeps its usual default identity |
| `HUB_DEFAULT_CONNECTION_PASSWORD` | Password for that username. Ignored when no username is set |

The [Compose example](/latest/quick-start/installation) sets host `broker`, protocol `mqtt`, and port `1883` for a broker on the same Docker network.

> [!WARNING]
>
> The password is delivered to every browser that loads the HUB. Use this only for shared lab or demo credentials.

## Saved Connections

Each saved connection appears as a card on the login screen, showing its name, broker URL, and a reachability status the HUB probes in the background. You can see whether that broker answers before you open it.

| Status | Meaning |
| - | - |
| **Checking** | The HUB is still probing this broker |
| **Online** | The broker answered |
| **Sign-in failed** | The broker answered, and the last sign-in did not succeed |
| **Offline** | The broker did not answer |

* **Favorites** — star a connection to pin it; use the **All / Starred** filter above the list to narrow the view.
* **Reorder** — drag a card to change its position in the list.
* **Connect** — pick an identity from the card's dropdown and click **Connect**. With a card focused, the Enter key does the same.
* **Edit or delete** — open a card to change its details, or remove it entirely.

## Identities and Switch User

A single saved connection can hold more than one identity — for example a day-to-day account and an admin account on the same broker. Mark one identity as the **default** for that connection, and switch between the others from the account pill without leaving the app: choose **Switch user** to reconnect as a different identity on the *current* broker, or **Switch broker** to reconnect to a *different* saved connection (using that connection's default identity). Both close the current session cleanly and reopen it against the new target. The rest of that menu is covered in [Desktop shell](/hub/overview#logo-and-the-account-pill).

## Securing a Connection with TLS

For `mqtts://` and `wss://` connections, open the connection's detail panel to attach TLS material:

* A **CA certificate**, if the broker's certificate isn't already trusted by your system.
* A **client certificate and private key**, for brokers that require mutual TLS.

Server certificate verification is on by default for secure connections; only turn it off for trusted development brokers.

> [!NOTE]
>
> This is separate from **connector** certificate management (trust stores for OPC UA and similar connectors running *on* the broker) — see the connector's own Certificate Management section when you configure a [Connector](/hub/routes/overview).

## When the Broker Is Not Coreflux

The HUB detects the broker when you connect. You do not pick a broker type.

When the connection is a generic MQTT broker, the dock keeps **Data Viewer** and **UNS Viewer**. Connectors, the LoT Editor, LoT Flow, Dashboards, and Cluster stay hidden. The status bar offers **Know more about Coreflux**, which explains what a Coreflux broker adds and links to the docs, the install guide, and [coreflux.org](https://coreflux.org). The account menu does not show **LoT Templates** or broker administration.

While the HUB is still checking, the dock shows those same two apps. **Know more about Coreflux** appears once the check settles on a generic broker.

After that session, the saved card is tagged **MQTT**. A card tagged **Coreflux** means the last session reached a Coreflux broker, and the usual apps are available. The tag is absent until a session has settled.

> [!NOTE]
>
> A Coreflux user without system access is still a Coreflux broker. You keep the usual apps. The LoT Editor still needs system access on that broker host, and the status bar can show **No SYS**. That session is not the generic-broker case, and the card is tagged **Coreflux**.

## Where Credentials Are Stored

* **Desktop app** — passwords and the TLS private key are encrypted at rest using your operating system's secure storage. They are never written to the plain settings file the HUB otherwise syncs to disk.
* **Browser app** — credentials are kept for the session and are not written to disk by the HUB; use your browser's own security practices (a trusted device, a locked profile) when saving connections there.

The broker's TLS **certificate** (the public part) can still be attached to a saved connection either way, since it isn't sensitive.

## Coreflux account and fleet

Saved connections are the **This machine** tab: a host, a port, and a username you store in this HUB. **Coreflux Fleet** is the other tab. It lists brokers your organization registered at [portal.coreflux.org](https://portal.coreflux.org) and connects with your account token instead of a saved password. Fleet rows are not added to this list. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).

***

## Next Steps

> **[Installation](/latest/quick-start/installation)**
>
> Install the broker and HUB, and make your first connection.

> **[Managing Connectors](/hub/routes/overview)**
>
> Configure connectors, including per-connector TLS trust stores.


# Display Components
Source: https://docs.coreflux.org/hub/dashboards/components/display

Read-only widgets: gauges, values, indicators, charts, tables, and alerts.

![A dashboard panel showing several display widgets: a temperature gauge, a pressure readout, a green machine status indicator, a status text line, and a live throughput chart](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/display-showcase.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=348c7d4807b7d8847dcdae57138286c7)

A showcase panel mixing the display widgets on this page: a gauge, a value readout, an indicator, text, and a live chart

Display components show live data without accepting input. Each entry below opens with tabbed examples — the rendered result above the code that produces it — followed by the property reference.

> [!TIP]
>
> **Like instruments on a car dashboard.** Each one reads a signal and shows it its own way — a dial, a number, a warning light — and none of them lets you steer.

***

## Gauge

Circular (radial) or linear gauge for numeric values.

**Basic**

A radial gauge bound to a temperature topic:

![Radial gauge filled about two-thirds with an orange arc, reading 82.0 °C](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/gauge.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=9c3c9dd97bd0c144c93478b5cfbbebb4)

A radial gauge bound to a temperature topic, reading 82.0 °C

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "TempGauge" WITH TYPE "gauge"
    SET RANGE FROM 0 TO 100
    SET UNIT "°C"
    BIND VALUE TO TOPIC "sensor/temperature"
```

**Full example**

A gauge with a label, one decimal place, and two configured thresholds:

![Radial gauge labeled Production Rate showing the live production rate](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/gauge-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=c2fff65712d01bc3505ca6ee6882f1f2)

A labeled production-rate gauge with warning and critical thresholds configured

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ProductionGauge" WITH TYPE "gauge"
    SET STYLE "radial"
    SET RANGE FROM 0 TO 100
    SET UNIT "units/hr"
    SET LABEL "Production Rate"
    SET DECIMALS 1
    BIND VALUE TO TOPIC "factory/production/rate"
    ADD THRESHOLD AT 75 WITH COLOR "warning" LABEL "High"
    ADD THRESHOLD AT 90 WITH COLOR "critical" LABEL "Critical"
```

| Property | Type | Default | Description |
| - | - | - | - |
| `STYLE` | `"radial"` / `"linear"` | `"radial"` | Gauge appearance |
| `RANGE FROM x TO y` | Numbers | required | Min / max values |
| `UNIT` | String | `""` | Unit label |
| `LABEL` | String | `""` | Display label |
| `DECIMALS` | Integer | `0` | Decimal places |

**Bind targets:** `VALUE`, `MIN`, `MAX`

## Value

The simplest read-only display: a number or string, with unit and formatting.

**Basic**

A pressure readout with two decimals:

![Numeric value readout showing 3.42 bar](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/value-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=ce3c932fe08a63c8a6d1528570477a5d)

A numeric readout showing the live pump pressure in bar

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "PressureDisplay" WITH TYPE "value"
    BIND VALUE TO TOPIC "pump/pressure"
    SET UNIT "bar"
    SET DECIMALS 2
```

**A JSON Data example**

Extracting one field from a JSON MQTT payload — `JSON_PATH` and the label are the new parts:

![Large numeric value readout showing 1284.50 Wh extracted from a JSON payload](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/value.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=548c92c9d46401efb14f5eb377c66b9d)

The value widget showing 1284.50 Wh, extracted from a JSON payload field

```lot wrap focus={3,5} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "EnergyDisplay" WITH TYPE "value"
    BIND VALUE TO TOPIC "machines/pump1/data"
    SET JSON_PATH "$.energy_wh"
    SET UNIT "Wh"
    SET LABEL "Energy"
    SET DECIMALS 2
```

| Property | Type | Default | Description |
| - | - | - | - |
| `UNIT` | String | `""` | Unit label |
| `LABEL` | String | `""` | Display label |
| `DECIMALS` | Integer | `0` | Decimal places |
| `JSON_PATH` | String | — | JSONPath to extract from payload |

**Bind targets:** `VALUE`, `MAX`

> [!NOTE]
>
> If your topic carries a JSON object rather than a plain number, set `JSON_PATH` to pick the field — otherwise the widget shows the raw payload. Inspect the payload first in the [Data Viewer](/hub/mqtt/data-viewer).

## Text / Label

Dynamic or static text. `label` is an alias for `text`.

**Basic**

A static heading rendered at large size:

![A large static text line reading Zone 1 Overview](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/text-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=4f14a1b82c246e6d1d6ef0fef794a6d4)

A static section heading rendered at large size

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "SectionTitle" WITH TYPE "label"
    SET LABEL "Zone 1 Overview"
    SET SIZE "large"
```

**Full example**

Dynamic text whose content updates live from the broker — the `BIND CONTENT` line is what makes it live:

![A large text line showing a live status message from the system message topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/text-live.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=2900e1241db40d85f0dcb642093e2b85)

A large status line whose text updates live from the system message topic

```lot wrap focus={2} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StatusText" WITH TYPE "text"
    BIND CONTENT TO TOPIC "system/message"
    SET SIZE "large"
```

| Property | Type | Default | Description |
| - | - | - | - |
| `SIZE` | `"small"` / `"medium"` / `"large"` | `"medium"` | Font size |
| `COLOR` | Color string | `"inherit"` | Text color |
| `MARKDOWN` | Boolean | `false` | Render the content as sanitized markdown. Raw HTML, images, and unsafe links are removed |

`SET MARKDOWN true` formats a bound briefing or note. A full panel is in [Markdown text](/latest/lot-language/panels/defining-panels#markdown-text).

**Bind targets:** `CONTENT`, `COLOR`, `TITLE`, `LABEL`

## Indicator

Maps incoming values to colors — running/stopped/fault at a glance.

**Basic**

A pump-running dot — green when the bound topic reads `true`:

![A green pump status indicator dot](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/indicator-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=74db3c3c0743e148f76a6c05d8234978)

A status dot that turns green while the pump-running topic reads true

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "PumpIndicator" WITH TYPE "indicator"
    BIND STATE TO TOPIC "pump/running"
    SET ON_VALUE "true" WITH COLOR "success"
    SET ON_VALUE "false" WITH COLOR "muted"
```

**Full example**

Three states mapped to three colors, rendered large — the extra mapping and size are highlighted:

![A large green machine status indicator dot for the running state](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/indicator-large.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d03616ddc371adef4b1c5e5fe2c66780)

A large green dot for running; switches to red or yellow as the status topic changes

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MachineStatus" WITH TYPE "indicator"
    BIND STATE TO TOPIC "machine/status"
    SET ON_VALUE "running" WITH COLOR "green"
    SET ON_VALUE "stopped" WITH COLOR "red"
    SET ON_VALUE "maintenance" WITH COLOR "yellow"
    SET SIZE "large"
```

| Property | Type | Default | Description |
| - | - | - | - |
| `ON_VALUE` | `"state" WITH COLOR "color"` | required | One or more value-to-color mappings |
| `SIZE` | `"small"` / `"medium"` / `"large"` | `"medium"` | Indicator dot size |

**Bind targets:** `STATE`

## Realtime Chart

Live streaming chart — it receives **individual data points** from a topic and builds the trend itself.

**Basic**

One topic, one trace — every published value becomes a point:

![A realtime line chart labeled Line Throughput trending as values arrive](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/realtime-chart-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=a44d88f1acd67db81e2173eb9de35619)

A realtime-chart building a live trend point by point from the throughput topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ThroughputTrend" WITH TYPE "realtime-chart"
    SET LABEL "Line Throughput"
    BIND VALUE TO TOPIC "factory/throughput"
```

**Full example**

The same idea with an explicit chart type, a y-axis unit, and a series label — the additions are highlighted:

![A realtime line chart labeled Message Count Trend building a live trend as points arrive](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/realtime-chart-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=5b5353a0f8f39c764ece8f5bd1f10db2)

A fully configured realtime-chart trending the message count

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MessageCountTrend" WITH TYPE "realtime-chart"
    SET LABEL "Message Count Trend"
    SET CHART_TYPE "line"
    SET UNIT "msg"
    BIND VALUE TO TOPIC "kpi/operational/messageCount"
        SET SERIES_LABEL "Message Count"
```

> [!NOTE]
>
> **Multi-series is not working in the current HUB build.** Adding a second `BIND VALUE TO TOPIC` (each with its own indented `SET SERIES_LABEL`) is the documented syntax for multiple traces, but the chart currently renders a single trace and no legend. Use one chart per signal for now.

| Property | Type | Description |
| - | - | - |
| `CHART_TYPE` | `"line"` / `"bar"` | Trace style (the current build renders both as a line) |
| `UNIT` | String | Y-axis unit label |
| `LABEL` | String | Chart heading |
| `SERIES_LABEL` | String | Series name — set **under the BIND, indented** |

**Bind target:** `VALUE`

## Image

Static, dynamic, or camera-fed image.

**Basic**

A static image loaded from a URL:

![An image component on a dashboard panel rendering a remote picture](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/image-url.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=da5b8a9d7ff2ff782a718deb9de8303a)

An image component rendering a remote URL on the panel

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ProductPhoto" WITH TYPE "image"
    SET SRC "https://picsum.photos/320/240"
    SET WIDTH 320
    SET HEIGHT 240
```

**Full example**

A live feed whose source URL is published over MQTT — the `BIND SRC` line replaces the static source:

![An image component rendering a picture whose URL was published to a camera snapshot topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/image-topic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cd78420f09d93731dfb671f9a6e6f0e3)

The image swaps live whenever a new source is published to the snapshot topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "CameraFeed" WITH TYPE "image"
    BIND SRC TO TOPIC "camera/1/snapshot"
    SET WIDTH 320
    SET HEIGHT 240
```

| Property | Type | Description |
| - | - | - |
| `SRC` | String / ENV / URL | Image source path or URL |
| `FALLBACK` | String | Fallback image if source fails |
| `WIDTH`, `HEIGHT` | Integer | Dimensions in pixels |

**Bind targets:** `SRC`, `VISIBLE`

## Table

Tabular data from a JSON array topic or a query result.

**Basic**

Each array element becomes a row; `COLUMNS` picks and orders the fields:

![A table with time, barcode, product, and status columns showing recent scans](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/table.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=623c8fc914491f4a61a47c0e610b972e)

A four-column table populated from a JSON array topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ScanHistory" WITH TYPE "table"
    BIND DATA TO TOPIC "barcode/history"
    SET COLUMNS "time, barcode, product, status"
    SET MAX_ROWS 10
```

| Property | Type | Description |
| - | - | - |
| `COLUMNS` | String | Comma-separated column names |
| `MAX_ROWS` | Integer | Maximum rows to display |

**Bind targets:** `DATA`

## List

Scrollable list of items from a topic or model.

**Basic**

![A list widget showing alarm entries from the zone1 alarms topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/list.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=4995d6e427f28360e88a22108d9ba3b5)

A scrollable list of alarm entries from a topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "AlarmLog" WITH TYPE "list"
    BIND DATA TO TOPIC "zone1/alarms"
```

**Bind targets:** `DATA`

## Alert

Banner for critical messages — typically bound to an alarm flag.

**Basic**

The banner appears while the alarm flag is true and shows the live message:

![An alert banner showing a pump pressure critical message](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/alert.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=e7dcc7473dfdd5371642458dddfb02f6)

A banner that appears while the alarm flag is true and shows the live message

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "AlarmBanner" WITH TYPE "alert"
    BIND VISIBLE TO TOPIC "pump/alarm_active"
    BIND CONTENT TO TOPIC "pump/alarm_message"
    SET VARIANT "critical"
```

> [!NOTE]
>
> In the current HUB build the `critical` variant renders in a neutral/muted style rather than a strong red banner — the message and visibility behaviour work as shown.

| Property | Type | Description |
| - | - | - |
| `TYPE` / `VARIANT` | `"critical"` / `"warning"` / `"info"` | Severity style |

**Bind targets:** `CONTENT`, `VISIBLE`

## Common mistakes

> **A property set with WITH is silently ignored**
>
> Properties use `SET`, never `WITH`. `WITH UNIT "msg"`, `WITH RANGE 0, 200`, and `WITH DECIMALS 2` are silently ignored — write `SET UNIT "msg"`, `SET RANGE FROM 0 TO 200`, `SET DECIMALS 2`.

> **The value widget shows a JSON blob instead of a number**
>
> The topic carries a JSON object — add `SET JSON_PATH "$.field"` to extract the field you want, and confirm the payload shape in the Data Viewer.

## Next Steps

> **[Input & control components](/hub/dashboards/components/inputs)**
>
> Buttons, toggles, sliders, and fields that write back to the broker.

> **[Data binding](/latest/lot-language/panels/data-binding)**
>
> Topics, models, queries, transformations, and JSON extraction.


# Input & Control Components
Source: https://docs.coreflux.org/hub/dashboards/components/inputs

Buttons, toggles, sliders, and fields that write back to your broker.

![A two-column operator panel with Start and Emergency Stop buttons, an Enable Production toggle, a setpoint slider, and device name and pressure fields](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/inputs-overview.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=9507498bcc35f2564a2ced1d606e5b0d)

An operator panel built from the components on this page: buttons, a toggle, a slider, and entry fields

Input components let operators act: start a line, set a speed, type a value. One rule applies to all of them: **input components don't publish by themselves** — the `ON <EVENT> DO` handler does.

> [!TIP]
>
> **Like a steering wheel, not a speedometer.** Display widgets read signals; these widgets send them — every interaction ends in a publish back to the broker.

***

One section per control, each with its rendered result, the code, and then the property reference.

## Button

**Basic**

A button that publishes a command when clicked:

![A Start Production button on a dashboard](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/button.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cd6b3b083b4e42d4d4d0c42ce1976ef1)

A button that publishes a start command when clicked

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StartButton" WITH TYPE "button"
    SET LABEL "Start Production"
    ON CLICK DO
        PUBLISH TOPIC "factory/commands/start" WITH 1
```

**Full example**

A danger-styled emergency stop — the `STYLE` line is the new part:

![A red danger-styled Emergency Stop button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/button-danger.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cf98eec449ec0e9b9bdda516a671b4db)

A red danger-styled Emergency Stop button

```lot wrap focus={3} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StopButton" WITH TYPE "button"
    SET LABEL "Emergency Stop"
    SET STYLE "danger"
    ON CLICK DO
        PUBLISH TOPIC "factory/commands/stop" WITH 1
```

| Property | Type | Default | Description |
| - | - | - | - |
| `LABEL` | String | required | Button text |
| `STYLE` | `"primary"` / `"secondary"` / `"danger"` | `"primary"` | Visual style |
| `DISABLED` | Boolean | `false` | Disable button |
| `AWAIT` | Quoted component ids | — | Comma-separated ids that show a pending indicator until their next message. The button stays busy |
| `AWAIT_TIMEOUT` | Seconds | `120` | How long to wait before a timeout note |

`SET AWAIT "Briefing, StatusLamp"` keeps the button busy and marks those components pending until each one receives its next message. A full panel is in [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button).

**Events:** `ON CLICK DO`

## Toggle / Switch

Binary on/off control. `switch` is an alias for `toggle`.

**Basic**

The toggle reflects the bound topic live — publish `true` or `false` to it and the switch follows:

![An Enable Production toggle switched on](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/toggle.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=4c0f81d53f5c464097468abe793ed9c2)

A labeled toggle reflecting the live state of its bound topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "EnableSwitch" WITH TYPE "switch"
    SET LABEL "Enable Production"
    BIND STATE TO TOPIC "factory/production/enabled"
```

| Property | Type | Description |
| - | - | - |
| `LABEL` | String | Toggle label |

**Bind targets:** `STATE` — **Events:** `ON TOGGLE DO`

> [!WARNING]
>
> **Write-back is broken in the current HUB build.** `ON TOGGLE DO PUBLISH ... WITH STATE` fires, but the message payload is the literal text `{{STATE}}` instead of the toggle state (`WITH VALUE` behaves the same). Until this is fixed, use the toggle as a live state display and trigger commands from a [button](#button).

## Slider

Range input for numeric values.

**Basic**

The slider tracks its bound topic live — the thumb moves as new values arrive:

![A temperature setpoint slider set partway along its 0 to 200 degree range](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/slider-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=182df2e5cbb0cbbef6964d442f81ac6c)

A 0–200 °C setpoint slider tracking the live value of its bound topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "SetpointSlider" WITH TYPE "slider"
    SET RANGE FROM 0 TO 200
    SET UNIT "°C"
    BIND VALUE TO TOPIC "control/setpoint"
```

| Property | Type | Description |
| - | - | - |
| `RANGE FROM x TO y` | Numbers | Min / max |
| `UNIT` | String | Unit label |

**Bind targets:** `VALUE` — **Events:** `ON CHANGE DO`

> [!WARNING]
>
> **Write-back is broken in the current HUB build.** `ON CHANGE DO PUBLISH ... WITH VALUE` sends the literal text `{{VALUE}}` instead of the slider position, and dragging is overridden by the bound topic. Until this is fixed, use the slider as a live numeric display and set values from a [number field](#number-field).

## Text Field / Input

Free text entry.

**Basic**

A labeled field pre-filled from its topic; typing publishes the new value:

![A Device Name text field showing pump-station-1](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/text-field.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=c726cca5e1f6c4fce03fdfa93bc56cfb)

A labeled text field pre-filled with the current value from its topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "NameInput" WITH TYPE "text-field"
    SET LABEL "Device Name"
    SET PLACEHOLDER "Enter name..."
    BIND VALUE TO TOPIC "config/device/name"
    ON CHANGE DO
        PUBLISH TOPIC "config/device/name" WITH VALUE
```

| Property | Type | Description |
| - | - | - |
| `LABEL` | String | Field label |
| `PLACEHOLDER` | String | Placeholder text |

**Bind targets:** `VALUE` — **Events:** `ON CHANGE DO`

## Number Field

Numeric-only entry.

**Basic**

Accepts only numbers and publishes the limit on change:

![A numeric input field for a maximum pressure limit](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/number-field.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d1ed70b5baf478df5766d0fc7c7537f3)

A numeric field that accepts only numbers and publishes the limit on change

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MaxPressure" WITH TYPE "number-field"
    SET LABEL "Max Pressure (bar)"
    SET PLACEHOLDER "0.00"
    BIND VALUE TO TOPIC "config/pressure/max"
    ON CHANGE DO
        PUBLISH TOPIC "config/pressure/max" WITH VALUE
```

| Property | Type | Description |
| - | - | - |
| `LABEL` | String | Field label |
| `PLACEHOLDER` | String | Placeholder text |

**Bind targets:** `VALUE` — **Events:** `ON CHANGE DO`

## Common mistakes

> **I typed in a field but nothing was published**
>
> Text and number fields fire `ON CHANGE` when the value is **committed** — press Enter (or leave the field) after typing. Each keystroke alone does not publish.

> **The toggle flips back on its own**
>
> The toggle reflects its `BIND STATE` topic. If nothing updates that topic, the toggle snaps back to the last bound value — make sure something (device, Action, or a test publish) updates the bound state.

## Next Steps

> **[Actions & events](/latest/lot-language/panels/actions-events)**
>
> Everything a control can do: publish, navigate, invoke, trigger, and branch.

> **[Container components](/hub/dashboards/components/containers)**
>
> Group controls and readouts into cards and tabs.


# Dashboard Manager
Source: https://docs.coreflux.org/hub/dashboards/manager

Create, open, share, and manage dashboard panels in the Coreflux HUB.

![Animation showing dashboard widgets updating in real time as MQTT topic values change on the broker](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-live-update.gif?s=4cc30da855182c2b17ae960b90b4a980)

Live data updates flow into widgets as broker values change

## Opening the Dashboard Manager

The **Dashboard Manager** is an app inside the Coreflux HUB. It lists your **panels** (each panel is one dashboard you can open, share, or refine). From here you add panels, refresh the list, and open a panel to see it live.

![Coreflux HUB Dashboards window in Preview grid view with Panels 1, a live thumbnail card for Solar energy site · Energy twin with Public and Published badges and a timestamp, and the List view, Preview grid, Dashboards Builder, themes, create, and refresh controls](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/dashboard/manager/hub-dashboards-manager-grid-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=aef54227e6a3c8be9758849e570cfeb3)

Dashboard Manager in Preview grid view: each panel shows a live thumbnail with its name, visibility, state, and last update

## How Panels Are Defined

The Dashboard Manager and the AI Assistant both produce the same thing: a **LoT panel definition** (`DEFINE PANEL …`). The Manager shows that definition next to its live result so you can edit either by hand or by asking the assistant. The **LoT PANEL** reference documents every panel keyword, component, binding, and event.

> **[Dashboards in the HUB](/hub/dashboards/overview)**
>
> The widget tour, the 60-second first panel, and what dashboards can do.

> **[Defining a panel](/latest/lot-language/panels/defining-panels)**
>
> Read and write the `DEFINE PANEL` source behind every dashboard.

## How data updates on a Dashboard

Each component is tied to **live data** on your broker—typically a MQTT (Message Queuing Telemetry Transport — lightweight messaging for devices and applications) topic that already carries the signal from your machines, databases, or Connectors. When that topic’s value changes, the widget updates. You do not configure polling or manual refresh for normal operation.

![Coreflux HUB with the Dashboards window in the background and the Solar energy site · Energy twin panel open in a floating window showing a 3D site view with live labels and Site power cards for PV, Site load, Grid, Battery, and Fleet state of charge](https://mintcdn.com/coreflux/9PekAdlvyyrySLnc/images/dashboard/manager/hub-dashboards-panel-window-light.png?fit=max\&auto=format\&n=9PekAdlvyyrySLnc\&q=85\&s=77e8d1a36d6ecb4db50def201f54106a)

A panel opened in its own window above the Dashboard Manager, with the dock still visible

## Viewing a Panel

You can experience the same panel in more than one layout depending on where you need it.

**As a window**

Open the panel as a **floating window** on top of the HUB. That keeps the rest of the HUB—connectors, Data Viewer, configuration—one click away while you watch live values or try layout changes.

![Coreflux HUB with the KPI Operational Dashboard expanded across the workspace, showing Status reading good, a Message Count trend line chart, and a Message Per Minute gauge reading 196](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-panel-window-tab.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=d873dc2aeabab536d9befb54a73c895a)

Panel as a floating window over the HUB — live widgets stay visible while you work elsewhere

**Full screen**

Open the panel in a **dedicated full view** when you want a clean surface for a plant display, a wall-mounted screen, or a link you share with people who only need the dashboard.

![Clean full-screen view of the KPI Operational Dashboard with no HUB chrome, showing Status reading good, a Message Count line chart, and a Message Per Minute gauge reading 174 on a dark background](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-panel-fullscreen.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=1a5638f3918fefa04c4b66f948a4962f)

Panel in full view — a clean surface for wall displays and shared links

## Managing Panels

The toggle in the Panels header switches between **List view** and **Preview grid**. The HUB remembers your choice; the list is the default. In the grid, each card shows a live thumbnail of the dashboard, and hovering it shows the same quick actions. Thumbnails don't run `ON MOUNT` actions, and cameras, microphones, video, web views, and barcode scanners show a placeholder.

Each row in the panel list shows the panel name, a visibility hint (for example **Public**), its publication state (for example **Published**), and when it was last updated. Clicking the row itself opens the panel; hovering reveals a row of quick actions on the right for sharing, inspecting, and deleting.

| Action | How to trigger it | What it does |
| - | - | - |
| **Open as a window** | Click the panel row | Opens the panel as a floating window on top of the HUB so you can keep working while it stays live |
| **Open as a link** | Click the first icon on the right (external link) | Opens the panel in a dedicated shareable view—useful for plant displays, wall screens, or sending a URL to a teammate |
| **View source** | Click the second icon on the right (code) | Shows the panel’s underlying definition so you can inspect or copy it |
| **Delete dashboard** | Click the last icon on the right (trash) | Removes the panel from the list after confirmation |

![Coreflux HUB Dashboards app showing the KPI Operational Dashboard row with Public and Published badges and three icons on the right for opening as a link, viewing source code, and deleting the dashboard](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-manager-actions.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=6fcf9d368243527c211a8c60ffa9ff91)

Panel row with quick actions — open as link, view source, and delete

## Sharing Panels on TVs and External Displays

You can put the same live panel on any screen that runs a browser—control-room wall TVs, lobby KPI boards, shop-floor tablets, or a monitor at a remote site—without installing a separate HMI app or giving everyone full access to the Coreflux HUB. The **shareable panel URL** opens a dedicated view of that dashboard so viewers see only the panel, not connectors, configuration, or other HUB apps.

From the **Dashboard Manager**, hover the panel row and click the **external link** icon (first action on the right). That opens the panel in a dedicated tab or window; copy the URL from the address bar and paste it into a browser on a TV stick, kiosk PC, tablet, or any display you want to keep on the loop.

> [!TIP]
>
> **Same live stream as inside the HUB.** The shareable URL reflects broker data the same way as the floating window—widgets update when topics change, without manual refresh for normal operation.

Typical uses:

* **Control-room and plant walls** — Full-screen dashboards that stay readable from a distance
* **Lobby and office KPI screens** — Management views without exposing operator tools
* **Shop-floor tablets** — Lightweight devices that only need one panel
* **Stakeholders and contractors** — A single URL when someone needs read-only visibility

![Coreflux HUB Dashboard Manager highlighting the external link action on a panel row to open a shareable dashboard URL](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/dashboard/manager/hub-dashboards-external-link.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=828c67a5b2cc460c3f9ef25244116ba3)

Open the panel as a shareable URL for TVs, kiosks, and external displays

> [!WARNING]
>
> Deleting a panel from the list removes that dashboard permanently after confirmation.

## Best Practices

> **Name panels by audience**
>
> Use names that tell you who it is for (for example “Line 3 — Shift Lead”) so the list stays scannable.

> **Start small**
>
> Ship a minimal panel with the three signals people ask for most, then add depth once it is in daily use.

> **Match symbols to reality**
>
> Use pumps, valves, and tanks where operators already think in those terms; use charts where trends matter more than mimic layout.

> **Verify before you share**
>
> Check labels, ranges, and safety-related controls before handing the panel URL to operators — they will rely on this screen.

***

## Next Steps

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Browse topics and payloads so you know what to bind each widget to.

> **[AI Assistant](/hub/ai-assistant)**
>
> Ask the assistant to suggest layouts, bindings, or improvements to a panel.


# Dashboards in the HUB
Source: https://docs.coreflux.org/hub/dashboards/overview

Live panels bound to your broker data — written in the Dashboard Manager or generated by the AI Assistant.

![Coreflux dashboard panel Solar energy site · Energy twin with a 3D site scene labelled with live values for grid, containers, factory load, and PV arrays, and Site power cards for PV, Site load, Grid, Battery, a Fleet state of charge gauge, and Peak import cap](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/dashboard/overview-hero-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=d66a730bd8466d29aa748fa31e47a610)

A published panel running maximized: a live 3D site view next to KPI cards and a gauge, all bound to broker topics

Dashboards in Coreflux are **panels**: live screens assembled from components — gauges, charts, controls — each wired to data flowing through your broker. You write them in the **Coreflux HUB** Dashboard Manager, where the panel definition and its live result sit side by side, or you ask the **AI Assistant** to build one for you and refine it from there.

> [!TIP]
>
> **Like a control room sketched in plain text.** You describe a gauge, point it at a signal, and it shows that signal live from the moment you save — no wiring diagram, no deploy step.

## What you can build

* **KPI walls** — large readouts and trends for supervisors
* **Line and area overviews** — at-a-glance status for a process or zone
* **Machine detail** — gauges, indicators, and controls for a single asset
* **Operator stations** — buttons, toggles, and setpoints where people work the process
* **Shift and mobile views** — simplified layouts for tablets and shared screens

***

Panels are authored as **LoT (Language of Things)** definitions — the syntax is documented under [LoT PANEL](/latest/lot-language/panels/defining-panels), which versions with your broker. The rest of this page is a quick tour of what the HUB renders; every widget has a full reference linked at the end.

## Your first panel in 60 seconds

**In the Dashboard Manager**

Open **Dashboards** in the HUB, click **Create new panel**, and write the definition below. The panel renders live as you save — point a gauge at a topic and the needle starts moving:

![The Sensor Monitor panel rendering a single radial gauge bound to the temperature topic](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/other/first-panel.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=48f432ea78be15567897c387e374eac7)

The saved panel: a live gauge reading 82.0 °C from the temperature topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL SensorMonitor
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Sensor Monitor"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        SET RANGE FROM 0 TO 100
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
```

Every part of a definition is covered step by step in [Defining a Panel](/latest/lot-language/panels/defining-panels).

**Ask the AI Assistant**

Describe what you want in plain language:

> "Build me a panel with a radial temperature gauge on `sensor/temperature`, range 0–100 °C, with a warning threshold at 75."

The assistant creates the panel for you. Open it in the Dashboard Manager to see the definition it wrote — and adjust anything directly. See [AI Assistant](/hub/ai-assistant).

> [!NOTE]
>
> Include `WITH VISIBILITY PUBLIC` **and** `WITH STATE PUBLISHED` in every panel definition — panels saved without them may not appear in the Dashboard Manager list. See [Defining a Panel](/latest/lot-language/panels/defining-panels).

## Tour of the main widgets

A quick taste of each family — every widget has a full reference page.

### Readouts

**Gauge**

A value with context: range, unit, and thresholds.

![A radial temperature gauge reading 82.0 °C](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/gauge-threshold.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=b79957bdaedaf310c62a27d90117ddbb)

A radial gauge bound to the temperature topic, with a 75 °C warning threshold configured

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "TempGauge" WITH TYPE "gauge"
    SET RANGE FROM 0 TO 100
    SET UNIT "°C"
    BIND VALUE TO TOPIC "sensor/temperature"
```

**Value**

The big number — unit, decimals, wall-readable.

![A numeric readout labeled Error Rate showing 1.25 percent](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/value-error-rate.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=06d34f7c733788d3397485f270a01bb9)

A formatted error-rate readout with two decimals

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ErrorRate" WITH TYPE "value"
    SET LABEL "Error Rate"
    SET UNIT "%"
    SET DECIMALS 2
    BIND VALUE TO TOPIC "kpi/operational/errorRate"
```

**Indicator**

State at a glance — values mapped to colors.

![A green machine status indicator dot for the running state](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/indicator-status.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=9553919702a348c0ae388c8b11f18c0f)

A status dot that turns green for running and red for stopped

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MachineStatus" WITH TYPE "indicator"
    BIND STATE TO TOPIC "machine/status"
    SET ON_VALUE "running" WITH COLOR "green"
    SET ON_VALUE "stopped" WITH COLOR "red"
```

**Alert**

A banner that appears when a condition is true.

![An alert banner showing a pump pressure critical message](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/alert.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=e7dcc7473dfdd5371642458dddfb02f6)

An alert banner showing the live alarm message while the alarm flag is true

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "AlarmBanner" WITH TYPE "alert"
    BIND VISIBLE TO TOPIC "pump/alarm_active"
    BIND CONTENT TO TOPIC "pump/alarm_message"
    SET VARIANT "critical"
```

### Charts and tables

**Real-time trend**

Builds a live trend from individual data points on a topic.

![A realtime line chart trending as message count points arrive](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/realtime-chart-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=5b5353a0f8f39c764ece8f5bd1f10db2)

A realtime-chart building a line from values as they arrive

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MessageCountTrend" WITH TYPE "realtime-chart"
    SET LABEL "Message Count Trend"
    SET CHART_TYPE "line"
    SET UNIT "msg"
    BIND VALUE TO TOPIC "kpi/operational/messageCount"
        SET SERIES_LABEL "Message Count"
```

**Table**

Rows from a JSON array topic or query result.

![A table with time, barcode, product, and status columns showing recent scans](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/table.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=623c8fc914491f4a61a47c0e610b972e)

A table populated from a JSON array topic

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "ScanHistory" WITH TYPE "table"
    BIND DATA TO TOPIC "barcode/history"
    SET COLUMNS "time, barcode, product, status"
```

### Controls

**Toggle**

On/off switch that tracks the live state of its bound topic.

![A pump enable toggle switched on](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/toggle-pump.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=7e5aa0ef6d5fa569af39fbca00c45118)

A pump-enable toggle reflecting the live pump state

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "PumpControl" WITH TYPE "toggle"
    SET LABEL "Pump Enable"
    BIND STATE TO TOPIC "zone1/pump/state"
```

**Button**

Click to act — publish a command to any topic, or navigate to another panel.

![A Start Production button on a dashboard](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/button.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=cd6b3b083b4e42d4d4d0c42ce1976ef1)

A button that publishes a start command when clicked

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StartButton" WITH TYPE "button"
    SET LABEL "Start Production"
    ON CLICK DO
        PUBLISH TOPIC "factory/commands/start" WITH 1
```

**Slider**

Numeric value tracked live on a range.

![A conveyor speed slider set to 65 percent](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/slider-speed.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=d28f7e799225dc20c6812dfa4b9b5ead)

A 0–100 % speed slider tracking the live conveyor speed

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "SpeedSlider" WITH TYPE "slider"
    SET RANGE FROM 0 TO 100
    SET UNIT "%"
    BIND VALUE TO TOPIC "zone1/conveyor/speed"
```

## What dashboards can do

* **Live bindings** — bind to MQTT topics, LoT Model fields, or database queries; widgets update the moment values change. See [Data Binding](/latest/lot-language/panels/data-binding).
* **Interactive controls** — buttons and entry fields that publish commands, invoke Actions, and trigger Connectors. See [Actions & Events](/latest/lot-language/panels/actions-events).
* **Multi-page navigation** — buttons and cards that jump between panels with `NAVIGATE`, for overview-to-detail drill-downs. See [Defining a Panel](/latest/lot-language/panels/defining-panels#navigation).
* **Share on any screen** — a panel URL runs full-screen on wall TVs, tablets, and kiosks, no app install. See [Dashboards in the HUB](/hub/dashboards/overview).

## Next Steps

> **[Build your first dashboard](/latest/quick-start/building-dashboards)**
>
> A 10-minute guided walk from topic to published panel.

> **[Component reference](/hub/dashboards/components/display)**
>
> Every widget, every property, every bind target.


# LoT Editor
Source: https://docs.coreflux.org/hub/lot-editor

Author, deploy, and inspect LoT and Python as notebooks and projects in the Coreflux HUB

![Coreflux HUB LoT Editor showing digital-twin-energy-site badged LIVE with energy-site.lotnb, a markdown cell titled Solar energy site · Modbus TCP + BACnet/IP, a DEFINE ROUTE TwinEnergyModbusU1 cell badged DEPLOYED, BROKER RUNTIME with type counts, CONFIGURATION, LIBRARY, a Deployed chip, main branch, and Deploy All](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=99cf12e43faa20ef201525799789f24a)

The LoT Editor with the live project's notebook open: a markdown introduction above deployed connector cells, Projects lists the project badged LIVE, Broker runtime shows its entities, and the header shows Deployed plus Deploy All

## Why Use the LoT Editor?

The LoT Editor brings the **LoT Notebooks** experience from VS Code into the Coreflux HUB. You author LoT and Python in notebook cells, deploy any cell on its own, and see per-cell whether your copy matches what the broker is running — with the broker's live entity list right beside your code, without leaving the browser.

This makes the HUB a single place to develop, manage, and operate your Coreflux solutions.

> [!NOTE]
>
> **This is parity, not a replacement.** Editing LoT from the [VS Code LoT Notebooks extension](/lot-notebooks/usage) remains fully supported, and you never have to choose between the two. The broker is the source of truth: either editor deploys to it, and both read the same project. `Import .lotnb`, `Push to broker`, and `Pull from broker` are what keep the two workflows one.

> [!TIP]
>
> **Like a lab notebook wired to the machine it describes.** The prose, tables, and code live in one document — and each block of code is the thing that is actually running.

## When to Use It

* **Deploying LoT without another tool installed** — Any HUB install, Docker or desktop app, can author and deploy
* **Checking what is really on the broker** — **Broker runtime** is the authoritative list, next to your code
* **Iterating on one definition** — Run a single cell instead of redeploying a whole project
* **Auditing drift** — Per-cell badges and a broker diff show exactly which definitions have moved out of sync
* **Documenting a solution where it lives** — Markdown cells render inline, so the topic conventions and device maps sit beside the code that implements them
* **Putting live visuals next to the LoT that drives them** — Drag Library components into a markdown cell and watch topics such as `demo/sensor/value` update in the notebook
* **Picking up someone else's project** — Open it from the broker and read the notebook top to bottom
* **Publishing or recovering a project** — Push a local draft, Pull or Inspect one already on the broker, or restore an earlier commit
* **Removing without surprises** — A local delete, an entity remove, and a project remove from the broker are three different operations

***

## Opening the Editor

Select **LoT Editor** in the HUB dock — the notebook-and-pen icon, after **Data Viewer** and **Connections**. An orange dot under the icon marks the editor as the active app.

![Animated walkthrough of clicking the LoT Editor icon in the Coreflux HUB dock to open the editor](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-open.gif?s=db008f31858c416cad334d6e604c5daf)

Opening LoT Editor from the HUB dock: the notebook-and-pen icon is fourth from the left, and the editor opens above the dock

The window header carries the current project and notebook plus the controls that act on the whole notebook:

![Coreflux HUB LoT Editor window above the dock, a template project's notebook.lotnb in the breadcrumb, 12 not running chip, orange Deploy All, Projects listing the project as local, Library Components 28, LoT Editor dock icon active](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-opening.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=cc046a052474a3e221d3b07ddd1a867d)

LoT Editor open on a template project with the dock still visible: breadcrumb project › notebook.lotnb, 12 not running, Deploy All, and the notebook-and-pen dock icon lit with an orange dot

| Control | What it does |
| - | - |
| **Breadcrumb** (`project › notebook.lotnb`) | The open project and file. Click either part to rename it |
| **`Deployed`** | Every comparable cell in the open project matches the broker. Drift shows as an orange count such as `N differs` or `N not running` — on a live project, click it to Push |
| **Branch chip** (`main`) | Git branch of the open project on the broker. Missing git is silence — there is no `Local workspace` chip |
| **`Deploy All`** | Deploys every LoT and Python cell in the **open notebook**. The split control also offers **Deploy project**, which stores and loads the whole project |
| **Action Console** (pulse) | Opens the right-hand **Action Console** rail for running and tracing Actions — see [Action Console](#action-console-traces-and-run-once) |
| **Remove entities** | Removes the entities *this notebook* defines from the broker |
| **Undo** / **Redo** | Step cell changes back and forward |
| **Attach notebook to AI chat** | Hands the open notebook to the HUB's AI assistant as context |
| **`…`** | `Import .lotnb file` and `Export open notebook as .lotnb` |

## A Notebook Is Both Document and Deployment

A notebook is an ordered list of cells, and the cell type dropdown decides what each one is:

| Cell type | Contents | Deployed? |
| - | - | - |
| **LoT** | One complete definition — `DEFINE ACTION`, `DEFINE MODEL`, `DEFINE CONNECTOR`, `DEFINE RULE` | Yes, to the broker |
| **Python** | A Python script your Actions call, named in the cell's **Script name** field | Yes, to the broker |
| **Markdown** | Headings, prose, lists, tables, **live visual components**, and links to project documents | Visuals are published as panels; prose is documentation |

Markdown cells render in place between the executable ones. That is not documentation-only: you can drop a gauge, chart, or card from **Library → Components** into a markdown cell and it stays live, bound to MQTT. A project installed from a template can use this for a **live document preview** — widgets on a topic such as `demo/sensor/value` sit in the notebook itself, so you deploy the cells above and watch the gauge, status, and trend update without leaving the editor.

> [!NOTE]
>
> **Adding visuals in the editor is a first-class authoring step**, not a Dashboards-only feature. Drag from Library, or write the component in the markdown cell — the notebook is allowed to *be* the live view. See [Library](#library-visual-components-and-documents).

To add a cell, use the **`+ Code`** and **`+ Markdown`** buttons that appear in the gutter between cells — so a new cell always lands exactly where you point at it.

## Working With Cells

Every cell has its own toolbar, left to right. Hover the cell to reveal the right-hand controls — **Move up** / **Move down**, **Duplicate**, and **Delete** stay hidden until then.

![Coreflux HUB LoT Editor TwinEnergyProjectKpi cell hovered with the DEPLOYED badge and toolbar controls, DEFINE ACTION TwinEnergyProjectKpi ON EVERY 1 SECOND reading energy-site topics, and the strip TwinEnergyProjectKpi Not yet run with Open in Action Console](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-cell-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=b484791c5871dd84fb153a09bb321933)

TwinEnergyProjectKpi hovered and deployed: drag handle, Run cell, LoT, DEPLOYED, then Run or trace, Move up, Move down, Duplicate, and Delete, with the run strip below

| Control | What it does |
| - | - |
| **Drag handle** | Drag to reorder the cell |
| **Run cell** (`Shift`+`Enter`) | Deploys just this cell to the broker |
| **Cell type** | Switch between `LoT`, `Python`, and `Markdown` |
| **Sync badge** | This cell's state against the broker — see below |
| **Enabled** switch (one ACTION, CONNECTOR, or AGENT per cell) | Turns the entity off or on without removing it — see [Disable an entity](#disable-an-entity) |
| **Run or trace** (pulse, Action cells only) | Pin this Action in the [Action Console](#action-console-traces-and-run-once). While a capture is armed it reads as tracing |
| **Compare with broker** | Shown when the cell is not `DEPLOYED` — see [Comparing a cell with the broker](#comparing-a-cell-with-the-broker). Appears on hover |
| **Move up** / **Move down** | Reorder without dragging. Appear on hover |
| **Duplicate** | Copy the cell and its contents. Appears on hover |
| **Delete cell** | Remove the cell from the notebook. Appears on hover |

Action cells also carry a strip under the code. Here it reads **`SummarizeF2Hvac · Not yet run · Tracing`** — expand it for Traces and Run, or choose **Open in Action Console** to pin the same panel in the right-hand rail. **Tracing** (green) means a five-minute capture is already armed for that Action.

Deleting a cell asks **"Delete this cell?"** and warns that the cell and its contents are removed from the notebook and that it cannot be undone. It changes the notebook only — the entity that cell deployed stays on the broker until you remove it there. See [Removal](#removal-four-different-operations).

### Disable an entity

A cell that holds exactly one action, connector, or agent has an **Enabled** switch in its toolbar. Switch it off to write `DISABLE true` on the line after `DEFINE`. Switch it on to remove that line. The broker keeps a disabled entity defined and listed, but doesn't run it.

![Coreflux HUB LoT Editor with the acme-bottling project open on its Plant actions section: the Heartbeat cell, publishing acme/plant/heartbeat every 5 seconds, with its Enabled switch on, and the AlarmRelay cell with its switch off labelled Disabled, the line DISABLE true under DEFINE ACTION AlarmRelay, and the result Action AlarmRelay added successfully (disabled)](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-cell-enabled-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=a739ffa917c06f8dbde8a943695ef557)

Two Action cells: Heartbeat with the Enabled switch on, and AlarmRelay switched off, which writes DISABLE true into its code

* With a broker connected, the cell is redeployed right away, so the notebook and the broker stay in step.
* Offline, the change stays in the cell and goes out with the next deploy.
* Models, rules, and cells with several entities have no switch.
* On a broker that doesn't support `DISABLE`, the switch is locked and its tooltip says **Requires a broker with DISABLE support**.

See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable) for the matching broker commands.

## Action Console: Traces and Run Once

**Run cell** deploys the definition. The console underneath — or pinned from the header pulse — is where you watch and trigger execution: **Traces** records every run for five minutes, and **Run once** fires the Action with a topic and payload you choose.

Every Action cell has the same console in two places — expanded under the cell, or pinned in the header pulse rail. Both have **Traces** and **Run**.

![Coreflux HUB LoT Editor SampleProcessor console on the Traces tab showing no messages yet, timeline playback controls, and copy that traces record every execution for five minutes](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-action-console.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=027470dfafc40dda6eba53940e30548e)

SampleProcessor Traces tab before a capture: timeline chrome and the note that traces last five minutes while a single run lives on the Run tab

| Control | What it does |
| - | - |
| **Traces** tab | A five-minute capture of every execution, including runs triggered elsewhere. Playback sits on the timeline; a single run's result stays on **Run** |
| **Run** tab | Topic and payload (or JSON parameters for callable Actions), then **Run once** |
| **`Use`** | Fill the payload from the last message on that topic, or from the last run |
| **Run once** | Live run — (re)deploys the version in the cell, then executes it. There is no sandbox: anything the Action publishes is published |
| **Open in Action Console** | Pin this Action in the right-hand rail so you can switch Actions without leaving the strip |

![Coreflux HUB LoT Editor SampleProcessor console on the Run tab with topic demo/sensor/value, payload 60, Use dropdown, and Run once play button](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-run-once.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=4ca68d1b354953da18067f01396c08a9)

SampleProcessor Run tab: topic demo/sensor/value, payload 60, Use menu, and the orange Run once control

> [!WARNING]
>
> **Run once is a live run.** It (re)deploys the Action from the cell and executes it on the broker. Downstream topics, databases, and devices see the same publishes they would from a real trigger.

## Is This Cell Running on the Broker?

Each LoT and Python cell reports its own state against the broker, which is the fastest way to tell whether the code you are reading is the code that is running:

| Badge | Meaning | What to do |
| - | - | - |
| **`DEPLOYED`** | The cell matches an entity running on the broker | Nothing |
| **`DIFFERS`** | The entity is running but the source here has changed | Run the cell to update it |
| **`NOT RUNNING`** | Nothing of that name is running on the broker yet | Run the cell to deploy it |
| **`RUNNING`** | Something is running that this project does not declare | Adopt it, or remove it from Broker runtime |

![Coreflux HUB LoT Editor showing notebook cells badged NOT RUNNING with Compare with broker controls, and a header chip reading a not-running count](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-cell-states.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=089fde4d4225dc42e24d8c7ca069c82a)

Cells that are not on the live project are badged NOT RUNNING — the header chip counts them, and Compare with broker is available on each toolbar

> [!NOTE]
>
> `NOT RUNNING` and `DIFFERS` are how the editor answers "why is my Action missing from [LoT Flow](/hub/lot-flow)?" — the graph is drawn from Broker runtime, so a cell that has never been deployed has nothing to draw.

### Comparing a cell with the broker

Whenever a cell is not `DEPLOYED`, a **Compare with broker (Diff)** control appears on its toolbar. It replaces the editor with a line-by-line comparison of the running definition against your local copy, headed `BROKER · <entity> ⟷ LOCAL` with an added/removed line count:

![Coreflux HUB LoT Editor showing SampleMqttBridge in diff mode, header BROKER · SampleMqttBridge vs LOCAL, CLIENT\_ID changed from bridge-client to bridge, PROJECTS Sample LIVE, orange 1 differs chip and main branch](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-cell-diff.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=3de709341eaca5dfc8b572f533da8eb0)

A cell in diff mode with the header 1 differs: BROKER · SampleMqttBridge ⟷ LOCAL, the removed CLIENT\_ID bridge-client in red and the local CLIENT\_ID bridge in green

For a `NOT RUNNING` cell the comparison is against nothing — every line shows as an addition, which is a quick way to review a whole definition before it goes live.

## Deploying

Two granularities, and the difference matters when a project is large:

* **Run cell** deploys that one definition. Use it while iterating — you get the broker's response for that entity alone.
* **Deploy All** deploys every LoT and Python cell in the **open notebook**. Use it while iterating.
* **Deploy project** (the other half of the split button) stores the whole project and loads it, replacing the broker's entity set. It always confirms first.

Either way the cell's badge flips to `DEPLOYED` once the broker confirms it, and the entity appears under **Broker runtime**.

Here is a complete Model as it appears in a cell — the fields the Action fills in are the ones worth reading first:

```lot wrap focus={2-4} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL SampleTableRow COLLAPSED
    ADD DOUBLE "value"
    ADD STRING "status"
    ADD STRING "timestamp"
```

> [!WARNING]
>
> Running a cell writes to the broker immediately. There is no staging step and no separate save — the definition in the cell replaces whatever the broker was running under that name.

***

## Start from a template

A new project starts with an empty `notebook.lotnb`. Worked examples come from **LoT Templates**, which browses the library at [templates.coreflux.org](https://templates.coreflux.org). The built-in Sample notebook is not part of the HUB.

Open **LoT Templates** from **Help → LoT Templates**, or choose **From a template…** in the new-project dialog that `＋ New` opens.

Each template has three tabs:

| Tab | What you see |
| - | - |
| **Overview** | What the template is for |
| **Notebook** | The notebook cells, read-only |
| **Flow** | How the LoT in the template fits together |

Installing a template creates a LoT Editor project on this HUB. It does not deploy to the broker. Change the example values, then deploy the cells the same way you deploy any notebook.

## Clone from git

**＋ New → From git…** copies a public git repository into a new LoT Editor project. The clone copies files only. It does not load the project, and it does not deploy any cell. Open the notebook and run the cells you want on the broker.

| Limit | What it means |
| - | - |
| Public repositories | The HUB does not accept private credentials |
| 30 seconds | The git clone stops if it has not finished |
| Whole repository | The repository root becomes the project root |
| 64 MB | A project download larger than 64 MB is refused |

***

## The Sidebar: Projects and Broker Runtime

There is **one Projects list**, and **Broker runtime** sits under it as its own section — always present, even when nothing is running.

![Coreflux HUB LoT Editor sidebar with PROJECTS listing a template project LIVE, notebook.lotnb, Entities 12, and its models; BROKER RUNTIME listing that project with type counts; CONFIGURATION Variables Secrets Internal Rules 35; LIBRARY Components 28 Resources 0; header Deployed and main](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-sidebar.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6a109a8c2d3c7e1c37fcce28f40c5e2a)

The LoT Editor sidebar: PROJECTS lists a template project badged LIVE with notebook.lotnb and Entities 12, BROKER RUNTIME shows that project with Actions, Models, Rules, Connectors, Python, Themes, and Panels, then CONFIGURATION and LIBRARY

| Section | What it holds |
| - | - |
| **Projects** | Every project you can open — on the broker, local-only drafts, and the one currently **LIVE**. `＋ New` creates a draft with an empty `notebook.lotnb`. **From a template…** opens [LoT Templates](#start-from-a-template). **From git…** clones a public repository ([Clone from git](#clone-from-git)). Hover a name for placement (`On broker · live`, `On broker · idle`, `Local draft`). The row plug is **Activate** or **Deactivate** |
| **Broker runtime** | What is actually running. The group reads **`Project: {name}`** for the live project, or **`Standalone`** when none is. Click the name to open the inspector table |
| **Configuration** | `Variables`, `Secrets`, and `Internal Rules` — the broker's locked built-in permission rules |
| **Library** | Visual components, documents, and images — see [Library](#library-visual-components-and-documents) |

Editing a notebook changes your local copy. Only deploying, Push, Activate, or Deploy project writes to the broker. A colleague on another machine sees the same Broker runtime and the same on-broker projects, not your unpublished local edits — which is why you Push and Pull.

### Broker runtime

Expanding **Broker runtime** groups everything running by type — `Actions`, `Models`, `Rules`, `Connectors`, `Agents`, `Things`, `Python`, `Themes`, `Panels` — each with a count and names beneath. Click **`Project: {name}`** or **Standalone** to open the inspector:

![Coreflux HUB Broker runtime inspector with All 37, Actions 19, Models 9, Rules 0, Routes 9, Python 0, Themes 0, and Panels 0 filters, Filter by name, and a table of running TwinEnergy actions and models, each in project digital-twin-energy-site and notebook energy-site.lotnb](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-broker-runtime-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=b5a941979edc02d71c8aed9a27dc9a4f)

Broker runtime inspector: type filters and a table of STATUS, TYPE, NAME, PROJECT, and NOTEBOOK for every entity running on the broker

The inspector is where mixed ownership is obvious: rows that belong to the open project point at `notebook.lotnb`; a connector you added on its own, outside any project, leaves **Project** and **Notebook** blank. Select a row to read the running source and use **Open notebook**, **Copy to project**, or **Remove**.

A project's own **Entities** folder (under the project in **Projects**) is what that project's notebooks *declare*. Broker runtime is what is *running*. Those counts can disagree — **Connectors (1)** under the project versus **Connectors (2)** on the broker — because a connector added from Connectors Manager is running but not declared in the notebook.

An agent (`DEFINE AGENT`) is its own entity. The editor deploys that cell with `-addAgent` and removes it with `-removeAgent`. It does not appear as a connector. The LLM connector it uses does. See [AI Assistant](/hub/ai-assistant) and [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

### Things in the editor

A cell with `DEFINE THING` blocks deploys as one Thing payload. The broker expands it; the HUB never does. See [LoT THING](/latest/lot-language/things/overview).

* **Run cell** first checks the cell with `-addThing --dryRun`, together with every template it references in the workspace. Problems show as markers in the code. If they pass, the same payload is applied. `-addThing` updates in place, so a Thing is never removed first.
* When you change a template that other Things use, the editor asks **Also redeploy N other Things?** before it applies.
* **Broker runtime → Things** lists each root Thing, its instances, and the entities they own. Owned entities are read-only and leave the per-type folders. The inspector table includes Things. A **Templates** subfolder shows which Things use each template. The project's **Entities** folder has a **Things** group too.
* On a broker without THING support, THING cells show a red chip, **Requires a broker with THING support**, and don't deploy.
* A THING cell in the older syntax offers an update. It previews the changes (`TEMPLATE`, and `{p}` to `{{p}}`) and applies them only when you confirm.

**Flow preview** in the editor toolbar opens a **Flow** pane with the [Things view](/hub/lot-flow#things-tree-and-flat-views) of the open notebook, from the same dry run. Click an entity to bring the cell that owns it into view.

![Coreflux HUB LoT Editor on the acme-bottling notebook. Under Broker runtime, the Things folder lists Acme with 16 entities and its line1 and line2 BottlingLine instances, Utilities with 4, and Templates with 3. The notebook shows the cell with DEFINE THING Acme and DEFINE THING Utilities, and the read-only Flow preview pane, built from the broker's dry run, shows All Things with 2 root Things: MQTT clients feeding the Acme and Utilities cards, and the Acme alarms going to Not in a Thing](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-things-flow-preview-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=8ece8ec2230b2c9213e0906dcf63b9ac)

Broker runtime → Things with the Acme root expanded, and the Flow pane previewing the open notebook's Things

An idle project's declarations can match the running set and still read `NOT RUNNING` on cells — Activate that project before treating those badges as a deploy to-do.

> [!NOTE]
>
> **Connectors and Python scripts deploy from the editor too.** Connectors still have their own [Connectors Manager](/hub/routes/overview) for connection status and templates.

Two counts are easy to misread:

* **`Rules`** under a project counts rules that project owns. Locked built-ins live under **Configuration → Internal Rules**, not here.
* **`Python`** counts *scripts*. [LoT Flow](/hub/lot-flow)'s Python group counts the individual *functions* those scripts expose.

## Library: Visual Components and Documents

**Library** is the bottom of the LoT Editor sidebar. It is how you put *views* and *files* into a project — not a second editor.

![Coreflux HUB LoT Editor sidebar scrolled to the Library with Components expanded, listing Gauge, Indicator, Value, Text, Header, Card, Container, Chart, Realtime Chart, Table, List, Button, Switch, Toggle, Slider, Input, Text Field, Number Field, Select, Date Picker, Map, Markers, Trace, SVG, Image, Video, Camera, Audio, Barcode, Web View, and Twin Controls with group labels, and Resources below](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-library-full-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=f4bd7a802f93c7ad6d703b80687c24dc)

Library open with Components expanded: visual component types listed with their group (display, data viz, input, maps and graphics, media, digital twin), then Resources

### Components

**Components** is the palette of live widgets you can drop onto a **markdown** cell. Each row is a type (Gauge, Chart, Button, Map, …) with its group on the right. Drag a row onto a markdown cell to embed a viewer bound to an MQTT topic. A template project's live preview is this capability in use: a card of gauge, status, and trend sitting in the document.

![Coreflux HUB LoT Editor markdown cell titled Live document preview with a Sensor overview card showing a gauge at 65.0, status normal, and a live trend chart](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-live-preview.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=f56fd16e7097462257c1bcddb944c846)

Live document preview in a template project: Sensor overview card with a gauge at 65.0, status normal, and a live trend on demo/sensor/value

Types you can drop today, by group:

| Group | Components |
| - | - |
| **Display** | Gauge, Indicator, Value, Text, Header |
| **Containers** | Card, Frame |
| **Data viz** | Chart, Realtime Chart, Table, List |
| **Input** | Button, Switch, Toggle, Slider, Input, Text Field, Number Field, Select, Date Picker |
| **Geo / spatial** | Map, Markers, Trace |
| **Media / graphics** | SVG, Image, Video, Camera, Audio, Barcode |

Widgets in the notebook publish as panels when the document is saved, so they are the same component types Dashboards uses — authored next to the LoT that feeds them.

### Resources: documents and images

**Resources** nests **Documents** and **Images**. These are files in the project, not a separate scrapbook you have to remember to Push.

![Coreflux HUB LoT Editor Library Resources with Documents expanded to site-notes.md and Add file, Images collapsed with count 1](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-library.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=a48e3215b3a464fdf2d32b28d696edfb)

Library Resources: Documents lists site-notes.md with Add file…, Images shows a count of 1

| Item | What it holds | How you add it | What drop onto markdown does |
| - | - | - | - |
| **Documents** | `.txt`, `.md`, and `.pdf` files in the **open project** | **Add file…**, or project / folder **Import file…** | Inserts a relative markdown link |
| **Images** | Project images (PNG, JPEG, SVG, GIF, WebP, and similar) | **Add file…** under Images, **Import file…**, or drag an image onto a project | Inserts a relative markdown image |

Click a document or image in Library to open it in the main pane (it replaces the notebook until you go back). Hover **Remove** on a Library leaf to delete that file from the list.

Right-click a project or folder for **Import file…** when you want the file to live under a specific folder rather than the Library picker. Dropping a Library image onto a project copies it into that project.

## Standalone Deployments vs Projects

The broker can run LoT **with** a live project, or **without** one. Broker runtime tells you which:

| Mode | Broker runtime label | What it means |
| - | - | - |
| **Live project** | **`Project: {name}`** (the live project's name) | At most one project is **LIVE**. Deployments from that project auto-commit. **Activate** / **Deactivate** on the project row choose which stored project is active |
| **Standalone** | **`Standalone`** | No project is loaded. Entities can still be running — you deployed cells with nothing live, or leftovers that no project owns. Auto-commit is off |

Standalone is a normal state: a scratchpad, the view after **Deactivate**, or entities deployed outside a project (another editor, an older session, or a cell run with nothing LIVE).

How the two interact:

* **Run cell / Deploy All** with nothing LIVE writes straight into standalone runtime. The toolbar stays a direct action.
* **Deploy All** from an idle project on the broker asks you to **Activate** first — it does not silently load that project.
* **Deploy All** from a local-only draft while another project is LIVE is refused (the toast points you at **Push**). Deploying those cells would write into the other live project.
* **Activate** loads a stored project's declarations. If the broker publishes entity ownership, only that project's entities stop; standalone leftovers stay. Without ownership, the confirm says the current project's entities are replaced.
* **Deactivate** unloads the live project and **removes its entities from running**. Auto-commit stops until you Activate again. Broker runtime then reads **Standalone** (plus anything that was never owned by that project). The confirm is explicit: *Deactivating **BMS** unloads it from the broker and **removes its entities from running**.*
* **Adopt into project** (Broker runtime context menu) writes selected running entities into a notebook and Pushes — that is how you turn a standalone set into a project.

## Moving Work Between Projects and the Broker

Right-click a project under **Projects** for operations on that row. A **LIVE** project and an idle on-broker project do not offer the same items (idle has **Inspect** and **Activate**; live has **Deactivate** and the full create/import set).

![Context menu for the digital-twin-energy-site project in the Coreflux HUB LoT Editor with New notebook, New folder, Import .lotnb, Import file, Push project to broker, Pull project from broker, Version history, Inspect, Activate, Deactivate, Rename, Delete local copy, and Remove project from broker in red](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-project-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=b1de7710d3bd7dbab1546706ab06d1ae)

The project context menu: notebooks and import, Push and Pull, Version history, Inspect, Activate and Deactivate, then Rename, Delete local copy, and Remove project from broker

| Item | What it does |
| - | - |
| **`New notebook`** / **`New folder`** | Add a `.lotnb` file or a folder inside the project |
| **`Push to broker`** | Send the whole project — every notebook and folder — to the broker. This is what links a local project to a broker project and puts it under version control |
| **`Pull from broker`** | Replace your local copy with the broker's. If you have unsaved local changes, a **"Pull from broker?"** prompt warns you first |
| **`Version history`** | Open the broker's git history for this project |
| **`Import .lotnb`** / **`Import file…`** | Bring a notebook or other file from outside into this project |
| **`Inspect`** | Download the broker's copy of an idle on-broker project into the editor (does not Activate) |
| **`Activate`** / **`Deactivate`** | Load or unload the stored project as the live one — see [Standalone vs projects](#standalone-deployments-vs-projects) |
| **`Rename`** | Rename the local project |
| **`Delete local copy`** | Delete the HUB notebooks only |
| **`Remove project from broker`** | Permanently delete the project from the broker |

Click **`Project: {name}`** to open the inspector table (status, type, name, owning project, notebook). A row with empty **Project** / **Notebook** is a standalone leftover — see [Standalone vs projects](#standalone-deployments-vs-projects). Right-click **Broker runtime** for operations on the running set:

![Context menu on the Broker runtime project in the Coreflux HUB LoT Editor with Adopt into project, Open in LoT Flow, Download all entities to notebook, and Remove all entities from broker in red](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-broker-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=4478729d7cf78baf27d769cf01f2b94a)

The Broker runtime context menu: Adopt into project, Open in LoT Flow, Download all entities to notebook, and Remove all entities from broker

| Item | What it does |
| - | - |
| **`Adopt into project`** | Write the selected (or all) running entities into a notebook, then Push |
| **`Open in LoT Flow`** | Open the live graph of this runtime |
| **`Download all entities to notebook…`** | Copy running definitions into a `.lotnb` file |
| **`Remove all entities from broker…`** | Undeploy the running set. Internal Rules stay |

## Version History

Broker projects are git repositories, and the editor exposes enough of that to recover from mistakes without a terminal:

![Coreflux HUB version history dialog for digital-twin-energy-site on main at ba3e485, explaining that history comes from the broker's git repository with auto-commit while active, RECENT COMMITS listing ba3e485 Initial project commit with Restore, a Branch / tag / commit to checkout field, and Checkout, Pull, Push, and refresh buttons](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-version-history-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=2f5e689648b640e271af79f91991accd)

Version history for digital-twin-energy-site on main: the note that history comes from the broker's git repository and that entity changes auto-commit while the project is active, recent commits with Restore, and Checkout, Pull, and Push

The dialog reports the project's branch and current commit, lists recent commits with their messages, and shows any uncommitted changes on the broker. From here you can:

* **Restore a commit** — checks that commit out on the broker and reloads the workspace if the project is active
* **Checkout a branch, tag, or commit** — type a ref and check it out
* **Pull** and **Push** — synchronise with the broker's configured git remote

> [!NOTE]
>
> **Entity changes auto-commit while the project is active.** You do not commit by hand — deploying an entity produces a commit like `Update connector: BacnetPortoHq`, which is why the history reads as a log of deployments.

> [!WARNING]
>
> Restoring a commit can discard uncommitted changes on the broker. Check the **Uncommitted changes** list in the same dialog before restoring.

## Pulling Entities Back Into a Notebook

Deployment is not one-way. Anything running on the broker can be brought back into a notebook, which is how you adopt LoT that was deployed by other means.

Right-click an entity **type group** under **Broker runtime**:

![Context menu on the Models entity type group in the Coreflux HUB LoT Editor Broker runtime showing Download all models to notebook… and Remove all models… in red](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-entity-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=23d5170f2ac72fbff7fbdc6c18350ed1)

The context menu on the Models group offers Download all models to notebook… and a red Remove all models…

Every type group carries its own pair, and the `Entities` group itself carries **`Download all to notebook…`** and **`Remove all from broker…`** for the whole set. Right-clicking a **single entity** offers **`Open in code editor`**, **`Download to notebook…`**, and **`Remove from broker…`**.

Any download asks **"Choose notebook"** — pick an existing `.lotnb` file in the project, or create a new one — and the definitions arrive as cells you can then edit and redeploy.

## Removal: Four Different Operations

Deleting locally and removing from the broker are different operations with different consequences, and the HUB guards them differently on purpose. Read the dialog: it tells you which one you are in.

| Trigger | Dialog | What it destroys | Guard |
| - | - | - | - |
| Workspace project → **`Delete local copy`** | **"Delete project?"** — local notebooks and folders only | Your local copy only | Plain confirm |
| Single entity → **`Remove from broker…`** | **"Remove from broker?"** — *Remove action "SummarizeF2Hvac" from the broker. This cannot be undone.* | One running entity | Plain confirm |
| `Entities` → **`Remove all from broker…`** | **"Remove all from broker?"** — *Remove 3 action(s), 3 model(s), 1 connector(s), 1 python script(s), 0 theme(s), and 0 panel(s) from the broker. Project-owned rules are also cleared; built-in and operator custom rules are preserved.* | Everything loaded on the broker | Plain confirm, but it enumerates live counts — read them |
| Broker project → **`Remove from broker…`** | **"Remove project from broker"** — *This permanently deletes **BMS** from the broker — all its files **and its entire git history**. This cannot be undone.* | The project, its files, and every commit | **Type-to-confirm** — the button stays disabled until you type the project name |

> [!WARNING]
>
> **Deleting a workspace project does not touch the broker, and removing a project from the broker does not touch your workspace.** A local delete leaves every entity running and every commit intact; a broker removal leaves your notebooks on disk but destroys the project's git history. Neither is a substitute for the other, and only the broker removal is guarded by type-to-confirm.

![Coreflux HUB dialog titled Remove project from broker in red, warning that this permanently deletes BMS from the broker including all its files and its entire git history and cannot be undone, with a Type BMS to confirm field and a greyed-out Remove permanently button beside Cancel](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/lot-editor/hub-lot-editor-remove-project.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=dd4382034bd5b27a3afc4c80930feba1)

The broker project removal dialog: the description spells out that the git history goes too, and Remove permanently stays disabled until the project name is typed into the field

The bulk-remove wording also settles a question the sidebar raises: **project-owned rules are cleared, while built-in and operator custom rules are preserved.** That is why the `Rules` count under **Broker runtime** can be small while **Configuration → Internal Rules** lists the broker's locked built-ins separately.

> [!NOTE]
>
> A `.lotnb` file is the safety net worth having before any removal. **`Download all to notebook…`** on the `Entities` group captures everything currently deployed, and **`Export open notebook as .lotnb`** in the header `…` menu writes it out as a file.

## Editing the Same Project From VS Code

The in-HUB editor and VS Code share the same broker-held project and git history: a project pushed from the HUB opens in the VS Code extension and vice versa, and `.lotnb` files move between them directly:

* **`Import .lotnb`** on a project, or **`Import .lotnb file`** in the header `…` menu, brings a notebook from outside into that project
* **`Export open notebook as .lotnb`** takes the open notebook back out
* **`Push to broker`** and **`Pull from broker`** move the whole project, which is how two people using two editors stay on one project

Whichever tool deployed an entity, it appears the same way under **Broker runtime** and is drawn the same way in [LoT Flow](/hub/lot-flow).

***

## Next Steps

> **[LoT Flow](/hub/lot-flow)**
>
> See the entities you just deployed as a live dependency graph.

> **[VS Code LoT Notebooks](/lot-notebooks/usage)**
>
> Edit the same broker-held project from VS Code, then Push and Pull to stay in sync.


# LoT Flow
Source: https://docs.coreflux.org/hub/lot-flow

See the Actions, Models, Connectors, and topics deployed on your broker as a live dependency graph

![Coreflux HUB LoT Flow with the Entities rail listing 19 Actions and 9 Models, and a canvas showing topic groups such as u20/ and u1/ feeding TwinEnergyModbus route nodes badged MODBUS\_TCP, whose output groups connect to Action nodes like TwinEnergyTrackContext ON TOPIC and TwinEnergyProjectKpi ON EVERY 1 SECOND](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-flow/hub-lot-flow-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=a2e62ee81f95645778dd07f7971d8937)

LoT Flow for an energy-site project: write topics feed MODBUS\_TCP connectors, their topic groups fan out to ON TOPIC and ON EVERY Actions, and the Entities rail lists Actions and Models

## Why Use LoT Flow?

Once you have more than a handful of Actions, Models, and Connectors on a broker, the question "what happens when this topic changes?" stops having an obvious answer. Tracing it means opening each definition and following topic names by hand. LoT Flow reads the LoT entities deployed on your broker and draws how they connect — what triggers what, and which topics each one reads and writes — so you can follow the data flow instead of reconstructing it from source.

> [!NOTE]
>
> LoT Flow carries a **`Beta`** badge in its window header. It is available for everyday use, but its controls and layout may still change between releases.

> [!TIP]
>
> **Like a wiring diagram that draws itself.** You never maintain the diagram — it is rebuilt from whatever is actually running on the broker.

## When to Use It

* **Understanding an inherited project** — See the whole entity graph before changing any of it
* **Answering "what does this topic affect?"** — Follow trigger edges from a topic to the Actions it fires
* **Confirming a deployment** — Check that a newly deployed Action appears, and that it is wired to the topics you intended
* **Finding orphans** — Spot entities that nothing triggers and topics that nothing consumes
* **Reviewing an integration** — See which topics a Connector publishes into your namespace and which it writes back out
* **Debugging execution order** — Follow trigger and event edges to understand what runs before what

***

## LoT Flow Reads the Broker, Not Your Workspace

This is the single most important thing to know about LoT Flow: **the graph is built entirely from entities deployed on the connected broker.**

The LoT Editor's sidebar is split into two halves that are easy to conflate:

| Sidebar section | What it holds |
| - | - |
| **Workspace** | Notebook files local to your browser profile. Editing them changes nothing on the broker |
| **Broker** | `Projects`, `Entities`, `Configuration`, and `Library` — shared server state |

A notebook cell you have written but not yet deployed is marked **`NOT RUNNING`** in the editor, and it will **not** appear in LoT Flow. Deploy it — with **Deploy All**, or by running the individual cell — and it appears. Cells already live on the broker are marked **`DEPLOYED`**.

> [!NOTE]
>
> If an entity you just wrote is missing from LoT Flow, check that it was deployed. **Broker runtime** in the LoT Editor is the authoritative list of what is actually running on the broker, and the graph matches that list.

Because the graph reflects the broker rather than any one editor, it does not matter which tool produced the LoT. Entities deployed from the [LoT Editor in the HUB](/hub/lot-editor) and entities deployed from VS Code appear the same way.

***

## Accessing LoT Flow

Select **LoT Flow** in the HUB dock. The window header carries a **`Beta`** badge. The canvas top-right cluster is the layout chrome:

| Control | What it does |
| - | - |
| **Freshness** (`3m ago`) | How long ago the graph was last built from the broker |
| **Reset layout** | Auto-arranges every node from scratch — use it after collapsing topics, after dragging nodes out of place, or whenever the graph looks tangled. Tooltip: *Auto-arrange LoT Flow from scratch* |
| **Open LoT Editor** | Opens the editor so you can change the entities this graph is drawn from |

Zoom, pan, **Fit View**, and **Download image** sit at the bottom-left of the canvas. Fit the view after Reset layout or after changing grouping — a freshly laid-out graph is often off-centre.

## The Entity Rail

The **Entities** tab groups everything deployed, with a count per group and a **Find entity** search for jumping straight to one by name. Groups start collapsed; a search opens every group with a match:

| Group | Contents |
| - | - |
| **Actions** | Event-driven logic, each badged with its trigger type |
| **Models** | Data schemas that map topic values into structured documents |
| **Connectors** | Connections to external systems, badged with the connector type |
| **Agents** | `DEFINE AGENT` agents on the broker |
| **Things** | Root Things and their instances, when the broker has any |
| **Python** | The individual Python functions your Actions call |

Selecting an entity focuses it on the canvas and opens its detail panel.

> [!NOTE]
>
> The **Python** group lists the individual *functions* invoked from Actions, so its count is usually higher than the number of Python *scripts* deployed. A single script exposing four functions appears as one entity under **Broker runtime** in the LoT Editor and as four nodes here.

## Things, Tree, and Flat Views

When the broker has at least one root Thing, a toggle at the top-right of the canvas offers three views. Things is the default, and the HUB remembers your choice.

| View | What it shows |
| - | - |
| **Things** | One card per Thing and one line per pair of parties that exchange data. Drill in one level at a time, for example `All Things › Plant › line1 › oven`. Ports stand for whatever lies outside the current level. Entities that belong to no Thing are grouped as **Not in a Thing** |
| **Tree** | The whole containment tree on one canvas: `All Things`, the roots, then every instance. Each node shows `ROOT` or `OF <template>` and what it holds. Use search, **Depth**, and **Expand all** / **Collapse all** like in the [UNS Viewer](/hub/mqtt/uns-viewer). Switch on **Templates** to add the templates to the tree |
| **Flat** | The graph described below, with every entity and topic |

Select a Thing to open its details below the canvas: its chain, template, path, parameters (an override of a template default is marked), and what it owns. **Open level in Things view**, **Open in UNS Viewer**, and **Open cell in LoT Editor** jump to it. The UNS Viewer focus is temporary and doesn't change your saved root filter.

In the live Things view, panel cards have an expand toggle that grows the card into a watch-only preview of the panel. **Open in window** opens it to interact. See [LoT THING](/latest/lot-language/things/overview).

![Coreflux HUB LoT Flow window in the Things view with the breadcrumb All Things › Acme, root, path acme/plant/, 16/16 ok. Cards for line2 and line1, each OF BottlingLine with filler, capper, and labeler, 4 models, and 4 actions; an MQTT clients port with 8 topics in on the left, and lines labelled alarm ×3 to the Not in a Thing port on the right. The Things, Tree, and Flat toggle is at the top right](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-flow/hub-lot-flow-things-view-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=1b007e9780637beb1686ebbae3e0abb2)

Things view, one level into Acme: the line1 and line2 instances, with ports for the MQTT clients that feed them and for Not in a Thing, where their alarms go

![Coreflux HUB LoT Flow window in the Tree view with Search Things, Depth 3, Collapse all, Expand all, Compact spacing, and the Templates switch off. All Things, with 2 roots and 15 entities not in a Thing, branches to Acme, ROOT with 2 bottling lines, and Utilities, ROOT with 2 temp sensors. line1 and line2, OF BottlingLine, each hold filler OF Filler and capper and labeler OF TempSensor; Utilities holds chiller and compressor OF TempSensor](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/lot-flow/hub-lot-flow-tree-view-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=e1e5c9988c085e846b7971f63d57e3fc)

Tree view with templates hidden: All Things, the Acme and Utilities roots, and every instance with its template

## Reading the Graph

The canvas draws your entities, the topics that wire them together, and the Python they call:

| Node | Meaning |
| - | - |
| **Action** | Event-driven logic, badged with its trigger (for example `ON TOPIC`) |
| **Model** | A data schema, badged `Model` |
| **Connector** | An external connection, badged with its type and a health indicator |
| **Python** | A Python function, badged with the script it belongs to |
| **Topic** | An MQTT topic, showing its current value |
| **Topic group** | Many topics sharing a prefix, collapsed into one node with a count |

Edges are colour-coded by relationship — solid lines are live data flow, muted dashed lines are structure. The vocabulary covers `publish`/`sub`, `trigger`, `write`, `event`, `python call`, `dependency` (a value read but not triggered on), `internal state`, `extends`, and grouping links. Turn on the **Legend** from the Settings tab while you are still learning it.

> [!NOTE]
>
> LoT **Rules** are not drawn on the canvas. Rules govern access control rather than moving data, so the graph focuses on Actions, Models, Connectors, and Python. Rules deployed on your broker still appear under **Broker runtime** in the LoT Editor.

### How a single Action becomes a subgraph

The Action below reads four topics, calls two Python functions, and publishes a Model to a status topic:

```lot wrap focus={7-12} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION SummarizeF2Hvac
ON TOPIC "uns/porto/hq/f2/hvac/temp" DO
    SET "temp" WITH (GET TOPIC "uns/porto/hq/f2/hvac/temp" AS DOUBLE)
    SET "humidity" WITH (GET TOPIC "uns/porto/hq/f2/hvac/humidity" AS DOUBLE)
    SET "occupied" WITH (GET TOPIC "uns/porto/hq/f2/hvac/occupied" AS BOOL)
    SET "setpoint" WITH (GET TOPIC "uns/porto/hq/f2/hvac/setpoint" AS DOUBLE)
    CALL PYTHON "BuildingInsights.comfort_score"
        WITH ({temp}, {humidity}, {setpoint})
        RETURN AS {score}
    CALL PYTHON "BuildingInsights.comfort_label"
        WITH ({score})
        RETURN AS {label}
    PUBLISH MODEL F2HvacModel TO "uns/porto/hq/f2/hvac/status" WITH
        temp = {temp}
        humidity = {humidity}
        occupied = {occupied}
        setpoint = {setpoint}
        comfort_score = {score}
        comfort_label = {label}
        timestamp = TIMESTAMP "ISO"
```

On the canvas that becomes one Action node with a trigger edge from `temp`, dependency edges from the three topics it reads, `python call` edges to both `BuildingInsights` functions, and an edge to the Model that publishes the result. You can read the same relationships from the other direction in the [UNS Viewer](/hub/mqtt/uns-viewer), where each topic reports the Actions and Connectors that produce and consume it.

## Inspecting an Entity

Select any node, or any entity in the rail, to open its detail panel.

![Coreflux HUB LoT Flow with TwinEnergyProjectKpi selected in the Entities rail and highlighted on the canvas; the detail panel shows Receiving data, Trigger ON EVERY 1 SECOND, Enable Trace, Inputs 8, Outputs 1, Internal state, a Publish a test value control, and a LoT Code block beginning DEFINE ACTION TwinEnergyProjectKpi](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-flow/hub-lot-flow-entities-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=213dda03b837e62cb448f90af5bca340)

The detail panel for the TwinEnergyProjectKpi Action: Receiving data, its ON EVERY 1 SECOND trigger, Trace, inputs and outputs, Publish a test value, and the deployed LoT source

Depending on the entity type, the panel reports:

* **Its trigger** and a live status such as `Receiving data`
* **Inputs and outputs** — the topics it consumes and produces, with counts
* **The deployed LoT source**, syntax-highlighted, so you can read what is actually running
* **Connector status** for Connector entities, including connection health
* **Trace** — capture this Action's executions to see it run. Traces auto-expire after five minutes
* **Publish a test value** — send a value to one of the entity's topics to exercise it

> [!TIP]
>
> **Trace answers "did it actually run?"** Rendering a graph proves an Action is deployed and wired up; a trace proves it fired.

## Keeping Large Graphs Readable

The **Settings** tab is the Canvas menu — grouping, look, and collapse live here. Layout itself is the **Reset layout** control at the top-right of the canvas, not in this list.

| Option | What it does |
| - | - |
| **Legend** | Puts a key for node and edge types on the canvas |
| **Minimap** | An overview map. Leave it off on a wide graph — it parks in the bottom-right and can cover real nodes |
| **Topic update flash** | Pulses a topic node when a new value arrives |
| **Edge style** | Smooth step, Bezier, Step, or Straight. This is a persisted preference, not a fixed default |
| **Spacing** | Compact, Comfortable, or Spacious. Also persisted |
| **Group large branches** | Fold sibling topics that share a prefix into one topic-group node with a count |
| **Collapse over** | How many children a branch needs before it groups. `1` groups every sibling set, which is the most readable hero view on a busy namespace. The field accepts `1`–`50` |
| **Collapse all** / **Expand all** | Collapse or expand every grouped branch at once |

After you change grouping, click **Reset layout** (top-right of the canvas) so the remaining nodes are placed again, then **Fit View**. Collapsing without resetting leaves the old positions and a lot of empty space.

Topic grouping is the most effective control on a busy namespace: **Collapse over** `1` folds each floor/device prefix — `…/f2/hvac/` `4/4`, `…/f2/energy/` `2/2` — into one node. The relationships stay on the graph; only the leaf clutter goes.

***

## Next Steps

> **[UNS Viewer](/hub/mqtt/uns-viewer)**
>
> Explore the topic namespace those entities read from and write to.

> **[LoT Editor](/hub/lot-editor)**
>
> Create and deploy the entities that appear in this graph, cell by cell.


# Connected Clients
Source: https://docs.coreflux.org/hub/mqtt/connected-clients

View active MQTT client connections and their status in the Coreflux HUB

![Coreflux HUB Connected Clients view listing two active MQTT v4 connections, coreflux-controller-a4d3f1ef at 127.0.0.1:32946 with 20m duration and 31.31 MB traffic and mqtt-explorer-05b06873 at 127.0.0.1:14107 with 40m duration and 36.23 MB traffic, and an empty detail panel on the right prompting to select a client to view details](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/connected-clients/connected-clients-list.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=9faadc42c50d926edd5fb7930032b751)

Connected Clients view in the Coreflux HUB showing two active MQTT v4 connections with an empty detail panel

## Why View Connected Clients?

You need to know which clients are connected to your broker—devices, applications, or the Coreflux HUB itself. The Connected Clients view shows all active MQTT connections with detailed connection info, traffic statistics, session data, and last activity so you can verify connectivity and troubleshoot disconnections.

## When to Use It

* **Verifying device connections** — Confirm that sensors or gateways are connected
* **Troubleshooting** — Check if a client has disconnected or failed to connect
* **Monitoring** — See how many clients are using the broker and their traffic
* **Debugging** — Inspect session state, pending messages, and last activity timestamps

***

## Connected Clients Interface

The Connected Clients view has two panels: a client list on the left and a detail panel on the right. Select a client to view its connection information.

![Coreflux HUB Connected Clients with 4 clients listed on the left (MQTT v5 and v4, endpoint, connected time, and traffic), and the selected client's Connection Information, Traffic Statistics for received and sent bytes, packets and messages, Session Information with status Connected, and Last Activity](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/connected-clients/connected-clients-detail-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=9ccafcb4161bec7f398c841d7663c85b)

Connected Clients with a client selected: connection information, traffic statistics, session information, and last activity

***

## Client List (Left Panel)

The left panel lists all clients currently connected to the broker. For each client you see:

| Field | Description |
| - | - |
| **Client ID** | Unique identifier for the connection (e.g., `coreflux-controller-0e1e882c`) |
| **Endpoint** | Client IP and port (e.g., `127.0.0.1:62983`) |
| **Connection Duration** | How long the client has been connected (e.g., `40m`) |
| **Total Traffic** | Estimated bytes received and sent combined (e.g., `15.16 MB`) |
| **Protocol** | MQTT version (e.g., `MQTT v4`) |

Select a client to view its detailed information in the right panel.

## Client Details (Right Panel)

When you select a client from the list, the right panel shows four sections:

### Connection Information

| Field | Description |
| - | - |
| **Protocol Version** | MQTT version (e.g., MQTT v4) |
| **Source Port** | Client's source port |
| **Connected** | Timestamp when the client connected |
| **Client IP** | Client IP address |
| **Full Endpoint** | IP:port (e.g., `127.0.0.1:62983`) |
| **Duration** | Connection duration (e.g., `40m`) |

### Traffic Statistics

| Direction | Fields |
| - | - |
| **Received** | Bytes, Packets, Messages |
| **Sent** | Bytes, Packets, Messages |

Use these to see how much data the client has exchanged with the broker.

### Session Information

| Field | Description |
| - | - |
| **Session ID** | Session identifier (typically matches Client ID) |
| **Created** | Timestamp when the session was created |
| **Expiry Interval** | Session expiry (e.g., `0s` for no expiry) |
| **Pending Messages** | Number of messages awaiting delivery to this client |
| **Status** | Connection status (e.g., Connected) |

### Last Activity

| Field | Description |
| - | - |
| **Last Packet Received** | Timestamp of the last packet received from the client |
| **Last Packet Sent** | Timestamp of the last packet sent to the client |
| **Last Non-KeepAlive** | Timestamp of the last non-keepalive packet |

## Refreshing the List

The view updates as clients connect and disconnect. Use the refresh control if you need to force an update of the displayed list. The detail panel shows an "Updated" timestamp indicating when the data was last refreshed.

***

## Next Steps

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Explore topics and publish messages.

> **[MQTT Protocol](/latest/mqtt-broker/protocol)**
>
> Understand MQTT client connections and sessions.


# Data Viewer
Source: https://docs.coreflux.org/hub/mqtt/data-viewer

Subscribe to topics, view the topic tree, listen to raw PCM, and publish messages from the Coreflux HUB

![Coreflux HUB Data Viewer with Publish and Settings icons on the left, a Filter field set to energy-site-01, the topic tree expanded to Modbus units and lot and status branches with live values and JSON previews, and the status/host card on the right with a Live timeline histogram and a parsed payload](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-overview-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=6b410c1ce65cc1f77a640aa79184b898)

Data Viewer with the topic tree filtered to energy-site-01 and expanded with live values, and the status/host topic pinned on the right with its message timeline and payload

## Why Use the Data Viewer?

You need to see what data is flowing through your broker—which topics are active, what payloads look like, and how to send test messages. The built-in Data Viewer in the Coreflux HUB lets you subscribe to topics, browse the topic tree, and publish messages without installing an external MQTT client.

> [!TIP]
>
> **An MQTT data viewer built into your Coreflux.** Designed to feel as intuitive as the popular MQTT Explorer desktop app — but with zero installation, right inside the HUB.

## When to Use It

* **Viewing device data** — Subscribe to sensor or device topics to see live readings (temperature, status, etc.) as they arrive
* **Exploring your topic structure** — Browse the Topic Tree to understand which topics exist and how they are organized
* **Verifying Actions** — Subscribe to output topics to confirm your LoT Actions are publishing correctly
* **Debugging** — Inspect payloads and topic structure in real time
* **Testing** — Publish messages to trigger Actions, test Connectors, or simulate device data
* **Monitoring broker activity** — Watch `$SYS` topics to check broker health, connected clients, and message throughput
* **Listening to audio** — Hear raw PCM on a topic, watch the waveform, and export a WAV clip

***

## Accessing the Data Viewer

1. In the HUB top navigation, select **MQTT**, then **Data Viewer**.
2. The Topic Tree appears on the left, showing topics as they receive messages.
3. Select a topic to view its payloads in the right panel.

![Animated walkthrough showing how to open the Data Viewer from the Coreflux HUB top navigation](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/view-mqtt-data.gif?s=0c0d326259f91e2d49562aff1c27d5ae)

Opening the Data Viewer from the Coreflux HUB dashboard

## Topic Tree

The Topic Tree shows the hierarchical structure of topics. Topics appear as messages are received. Expand branches to navigate and select a topic to view its payload history in the payload viewer.

![Coreflux HUB Data Viewer with the filter energy-site-01/lot, the tree expanded to dt/v1/demo/energy-site-01/lot listing alarm, building, connectivity, kpi, pv, site, and storage with JSON previews, kpi highlighted, and the lot/kpi card with a Live timeline and fields such as source, processed\_at, pv\_kwh, and import\_kwh](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-topic-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=4cd3168e93257369c4f91b31013cd20b)

Topic Tree filtered to energy-site-01/lot with the kpi topic selected: its card on the right shows a live message timeline and the parsed payload

## Exploring Live Data

The Data Viewer is laid out as three vertical panels: **Publish** on the left, the **Topic Tree** in the middle, and a **Detail area** on the right where you build a personal view of the topics you care about right now. You can drag the divider between the tree and the detail area, and collapse the Publish panel into a thin rail to give yourself more room.

> [!TIP]
>
> **Like an instrument panel for your broker.** Instead of reading rows of raw messages, you pin the topics that matter to the right side and watch them update — values, charts, lamps, even maps — in real time.

### Previewing a topic

Get a feel for what is happening on the broker without committing to a layout. Click any topic in the tree and its latest payload appears in the Detail area as a quick preview.

Each row in the tree carries a small **type icon** that tells you at a glance what kind of value the topic currently holds:

| Icon | Meaning |
| - | - |
| Glowing orange dot | Boolean `true` |
| Empty dot | Boolean `false` |
| `#` | Number |
| `{}` | JSON object |
| `[]` | JSON array |
| `"` | Plain string |

Rows briefly **flash orange** whenever a new message arrives, so you can see broker activity without staring at every value. To narrow the list, type any part of a topic path into the **Filter** box at the top of the tree — the filter matches anywhere in the path, and the usual display cap is lifted while you are filtering. For broader monitoring, you can also subscribe with a wildcard pattern such as `sensors/#`, and every matching topic appears in the tree as messages come in.

### Tracking what matters

Once a topic is worth watching, **pin it**: double-click the topic, or drag it from the tree onto the Detail area. A card appears for it, and the card shape adapts to the payload so you don't have to mentally decode raw values:

* **Numbers** render as a large value with a **sparkline** of recent history — perfect for sensor readings like temperature or RPM.
* **Booleans** render as a glowing **lamp** — green when `true`, dim when `false`.
* **JSON and text** render with colored keys and an expandable tree, so nested objects stay readable.
* **Geolocation** payloads (latitude/longitude) render as a small **map** with the current point and a trail of recent positions, plus the raw payload underneath. The map uses OpenStreetMap tiles. In the dark theme those tiles are darkened, while the marker, the trail, and the **© OpenStreetMap contributors** attribution keep their own colours.

Cards can be reordered by dragging them up or down, copied to the clipboard with one click, and removed with the **X** in their corner. Add more topics any time from the dashed **+ Add topic** button at the bottom of the cards, which opens a searchable list of every known topic.

![Coreflux HUB Data Viewer with the Topic Tree on the left expanded to kpi/operational showing messageCount, messagesPerMinute, and status with their inline values; on the right a tracked card for operational/messageCount displays the value 113 with a sparkline trail, a timeline above shows 197 message marks, and an + Add topic button sits below the card](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/mqtt-explorer-tracked-card.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=ca9252f0862b63263046c6777f2d6161)

Tracking kpi/operational/messageCount: the tree on the left shows live values with type icons, while the right panel pins the topic as a card with the current value (113) and a sparkline of recent history, plus a timeline of the last 197 messages above it

### Replaying history with the timeline

As soon as you are tracking topics with more than one message of history, a **timeline** appears at the top of the Detail area. Every tracked topic gets its own color, and every message it has received is drawn as a colored mark on a horizontal track.

From there you can:

* **Click or drag** anywhere on the track to scrub to a moment in time — every card below jumps to the values they had then.
* Step message-by-message with **First / Previous / Next / Last**.
* Hit **Play** to replay the message history like a video, with cards animating through every value.
* Tap **Live** to snap back to the latest message and resume real-time updates (the label turns green when you are caught up).
* Open the gear icon to change the **history buffer** per topic, from 50 up to 2 000 messages — larger buffers give you more scrub range.

While the viewer is focused, the arrow keys step through messages, **Home** jumps to the first, and **End** jumps back to live.

![Coreflux HUB Data Viewer with three tracked topics lot/kpi, lot/pv, and lot/storage as colored chips, a multi-row message timeline with playback controls, Live, and a position counter, and the three topic cards stacked below with their parsed payloads](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-timeline-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=11a166413664ec8113e3586eacc071fd)

Timeline tracking three topics: each topic gets its own chip and row, with playback controls and the Live indicator above the stacked cards

### Drilling into payloads

When a payload is too big to read inline, click its preview in the tree to open the **payload inspector** — a floating window that parses the full payload and lets you expand JSON to any depth. If the payload contains coordinates, the inspector draws the same OpenStreetMap map at the top.

For payloads where you only care about one number, drag a single value out of the inspector (or out of a card's expanded JSON tree) onto the Detail area. That value becomes its own **extraction card** — a small card that tracks just that one field, sparkline included if it's numeric. It's the fastest way to follow `temperature` from a 30-field sensor payload without the surrounding noise.

![Coreflux HUB Data Viewer payload inspector floating over the tree for dt/v1/demo/energy-site-01/lot/kpi, showing the pretty-printed JSON payload with source, processed\_at, telemetry\_sequence, pv\_kwh, import\_kwh, export\_kwh, self\_consumption\_pct, and peak\_import\_kw, view buttons in the header, and a playback timeline with Live at the bottom](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-payload-inspector-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=1b1ed2d645e4fee2da7783596b525bee)

Payload inspector for dt/v1/demo/energy-site-01/lot/kpi in Code view: the payload is pretty-printed, with Graph, Code, Diff, Message list, and Expanded views and a message timeline at the bottom

### Drag-and-drop cheatsheet

Most of the viewer is built around dragging. While you are dragging, valid drop zones light up so you can't miss them.

| Drag this | Onto this | Result |
| - | - | - |
| A topic in the tree | The Detail area | Adds a tracked card for that topic |
| A topic in the tree | The timeline's topic chips | Adds the topic to the timeline only |
| A topic in the tree | The Publish panel's Topic input | Pre-fills the publish topic |
| A topic in the tree | The Publish panel's Payload area | Pastes the topic's current value |
| A JSON value from a payload | The Detail area | Creates an extraction card for that single field |
| A JSON value from a payload | The Publish panel's Payload area | Pastes just that value |

## Publishing Messages

To publish a test message:

1. Click the **Publish** (paper plane) icon in the Data Viewer's left rail to open the Publish panel.
2. Select or enter the target topic.
3. Enter the payload and pick its format (**RAW**, **JSON**, or **XML**), with optional **QoS** and **Retain**.
4. Click **Publish** to send the message.

Use this to trigger Actions, test connector configurations, or simulate device data.

![Coreflux HUB Data Viewer with the Publish panel open showing a Topic field, QoS 0 selector, Retain toggle, an orange Publish button, RAW, JSON, and XML format buttons, and an empty payload editor, next to the topic tree](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-publish-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=c7b230435ce5d99898f4f101ca39bd1d)

The Publish panel open on the left of the Data Viewer: topic, QoS, Retain, the Publish button, payload format, and the payload editor

## Listening to PCM audio

Some topics carry sound as raw bytes — the chunks an [Audio Input](/latest/lot-language/routes/media/audio-input) connector publishes from a microphone, a tone, or a file. When the payload is that raw PCM, the detail area switches to an audio view.

The viewer decides from the payload, not from the topic path. A topic named `sensors/line1/status` is audio if the bytes are PCM. A topic with `audio` in the path stays a normal text or JSON card when the payload is not PCM.

From that view you can:

* Watch a **live waveform** as chunks arrive.
* **Listen** to the stream.
* **Capture** a stretch of audio and **review** it before you keep it.
* **Export WAV** of the captured clip.
* **Scrub the timeline** — the waveform, playback, and the other tracked cards stay on the same moment.

## Open the viewer in its own window

In the HUB, **Open in a new window** opens the Data Viewer in its own window on the broker you are already connected to.

***

## Next Steps

> **[Connected Clients](/hub/mqtt/connected-clients)**
>
> See which clients are connected to your broker.

> **[MQTT Broker Protocol](/latest/mqtt-broker/protocol)**
>
> Learn how MQTT topics and wildcards work.


# MQTT Overview
Source: https://docs.coreflux.org/hub/mqtt/overview

Browse topics, publish messages, and see who's connected — all from your Coreflux HUB

![Coreflux HUB Data Viewer showing the publish panel on the left, the topic tree expanded to \$SYS/Coreflux/Resources, and the Resources/MemoryInfoTotal topic plotted live on the right](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/hub-mqtt-overview.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=eb0667ff8af36d41369915e029c35661)

Data Viewer in Coreflux HUB — topic tree with publish controls

## Your MQTT Dashboard

Welcome to your built-in MQTT toolbox. From here you can browse every topic on your broker, publish test messages, and check which clients are online — all without leaving the Coreflux HUB. Two widgets are ready for you: **Data Viewer** for topics and messages, and **Connected Clients** for monitoring connections.

> [!TIP]
>
> **No need to install external tools** — the Data Viewer is built right into the Coreflux HUB.

## Pick the Right Widget

| Widget | You want to... |
| - | - |
| **Data Viewer** | Browse topics, inspect payloads, or publish test messages |
| **Connected Clients** | See who's connected and check connection health |

***

## Next Steps

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Subscribe to topics, browse the topic tree, and publish messages.

> **[Connected Clients](/hub/mqtt/connected-clients)**
>
> View active MQTT client connections and their status.


# UNS Viewer
Source: https://docs.coreflux.org/hub/mqtt/uns-viewer

Explore your broker's topic namespace as a live hierarchy graph in the Coreflux HUB

![Coreflux HUB UNS Viewer with the Namespace rail on the left showing Root filter #, Include \$ topics, Expand depth 3, Collapse all and Expand all, and Canvas options Legend, Minimap, Edge style Bezier, Spacing Compact; the canvas shows Root 97 branching into dt 96 and spBv1.0 1, then v1, demo 95, twins 1, CorefluxDemo and NDATA, with a 97 topics badge](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/uns-viewer/hub-uns-viewer-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=fd8a60376ed29d0c30d89f6909536a6c)

UNS Viewer showing a namespace of 97 topics: Root splits into dt and spBv1.0, dt expands through v1 into demo and twins, and spBv1.0 into CorefluxDemo and NDATA

## Why Use the UNS Viewer?

You have hundreds or thousands of topics on your broker and you need to understand their *shape* — how the namespace is organised, which levels exist, and where a given device or metric sits in the hierarchy. Reading that structure from a flat list of topic strings is slow and error-prone. The UNS Viewer draws your broker's namespace as a hierarchy graph, so you can see the structure at a glance instead of reconstructing it in your head.

> [!NOTE]
>
> The UNS Viewer carries a **`BETA`** badge in its window header. It is available for everyday use, but its controls and layout may still change between releases.

> [!TIP]
>
> **Like a map of your factory instead of a list of street names.** A topic list tells you what exists; the namespace graph shows you how it all fits together.

## When to Use It

* **Understanding an unfamiliar broker** — Open the namespace and read the hierarchy top-down instead of guessing at topic conventions
* **Reviewing your namespace design** — Check that a new site, line, or device was published under the level you intended
* **Finding where a metric lives** — Search for a name and see which branch of the hierarchy it belongs to
* **Tracing a topic back to your logic** — Each leaf reports which Actions and Connectors produce or consume it
* **Comparing several topics at once** — Select multiple topics and watch their values and history side by side
* **Spotting activity** — Live pulses show which parts of the namespace are actually receiving traffic

***

## Accessing the UNS Viewer

Select **UNS Viewer** in the HUB dock. The window opens with the namespace already built from the topics the HUB has seen, and a `N topics` badge in the top-right corner reports how many leaf topics are currently in scope.

## Reading the Graph

The canvas draws two kinds of node:

| Node | Shape | Meaning |
| - | - | - |
| **Namespace node** | Square | A level in the hierarchy. Carries a count of everything beneath it, and a chevron to expand or collapse its children |
| **Leaf topic** | Rounded | An actual MQTT topic. Shows its current value inline |

Colour and motion carry meaning too, and the **Legend** toggle puts a key on the canvas while you are learning the vocabulary:

* **Live value** — a green pulse means a message just arrived on that topic
* **Activity pulse** — a green glow on a namespace node shows aggregated traffic somewhere below it
* **Search match** — an amber ring marks topics matching your current search

Only leaf topics carry payloads. Selecting a namespace node reports `No message at this time`, because the values live on its children.

## Navigating the Namespace

The **NAMESPACE** section of the left rail controls how much of the tree is drawn:

| Control | What it does |
| - | - |
| **Root filter** | An MQTT filter that scopes the whole view, `#` by default. The `N topics` badge follows the filter |
| **Include \$ topics** | Brings broker-internal `$SYS` and `$Visu` topics into the graph, which are hidden by default |
| **Expand depth** | How many levels are expanded when the graph is built. Defaults to `3` |
| **Collapse all** / **Expand all** | Collapse the whole tree, or expand every level at once |

> [!NOTE]
>
> The **Root filter** applies when you press **Enter** — typing a filter alone does not redraw the graph.

On a large namespace, narrowing the root filter to a subtree such as `uns/porto/hq/f1/#` is the fastest way to keep the graph readable.

The **Search topics** box highlights matching topics in place with an amber ring rather than filtering the graph, so you keep the surrounding structure as context while you locate something.

![Coreflux HUB UNS Viewer with Root filter dt/v1/demo/energy-site-01/#, a 95 topics badge, Expand depth 3, Legend and Minimap switched on, a canvas chain Root, dt, v1, demo, a minimap in the bottom-right, and a legend for Live value, Activity / update pulse, and Search match](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/uns-viewer/hub-uns-viewer-controls-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=8981393eb1aa9810857d5159bdb994d3)

The Namespace rail with the Root filter scoped to dt/v1/demo/energy-site-01/#, which narrows the badge to 95 topics; Legend and Minimap are on, adding a key at the bottom and an overview map in the corner

### Canvas options

The **CANVAS** section changes how the graph is drawn without changing what it contains:

| Option | Choices |
| - | - |
| **Legend** | Show or hide the node and edge key |
| **Minimap** | Show or hide an overview map for staying oriented in large graphs |
| **Edge style** | Smooth step, Bezier, Step, or Straight |
| **Spacing** | Compact, Comfortable, or Spacious |

Zoom, pan, and a **fit-view** control sit at the bottom-left of the canvas. Fit the view after expanding or filtering — a freshly laid-out graph is often off-centre.

***

## Inspecting a Topic

Select a leaf topic to open the inspector on the right. It reports the topic's breadcrumb path, its live value, its history, and how it relates to the LoT running on your broker.

![Coreflux HUB UNS Viewer with the topic inspector open for uns/porto/hq/f2/hvac/temp, showing a breadcrumb of uns, porto, hq, f2, hvac, temp, First/Previous/Play/Next/Last playback controls, a green Live toggle, a timestamp of 23:07:36.790 with position 250 / 250, an orange message histogram running from 23:03:27.788 to 23:07:36.790, a value card reading 20.61 with a sparkline, and three cross-reference rows reading Triggers action SummarizeF2Hvac, Referenced by action SummarizeF2Hvac, and Produced by connector BacnetPortoHq](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/uns-viewer/hub-uns-viewer-inspector.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6083e4aeca9e5f2afd26eca7402d47f8)

The inspector for uns/porto/hq/f2/hvac/temp: a Live indicator, playback controls, a message histogram spanning 23:03:27 to 23:07:36, a position counter reading 250 / 250, a value card showing 20.61 with a sparkline of recent history, and cross-references reporting that the topic triggers and is referenced by action SummarizeF2Hvac and is produced by connector BacnetPortoHq

The inspector gives you:

* **A value card** with the current value and a **sparkline** of recent history
* **A message histogram** with the start and end timestamps of the buffered history
* **Playback controls** — step to first, previous, next, or last message, or play the history back
* **A `Live` toggle** that snaps to the latest message and resumes real-time updates
* **LoT cross-references** — which Actions the topic triggers, which reference it, and which Connector produces it

Those cross-references are the bridge between your namespace and your logic. A topic written by a Connector and consumed by an Action shows all three relationships, and a topic that nothing uses reports `Not referenced by any action or connector.`

> [!TIP]
>
> Cross-references answer "is anything actually using this topic?" — useful when cleaning up a namespace, or when confirming that a newly deployed Action really is wired to the topic you intended.

### Comparing several topics

Turn on **multi-select** in the top-right corner to keep more than one topic selected. Each selection becomes a removable chip carrying its own message count, the inspector header counts them, and the histogram merges every selected topic onto one timeline so you can line their behaviour up against each other. Press `Esc` to leave multi-select.

With multi-select off, a plain click replaces the current selection, while `Shift`, `Ctrl`, or `⌘` click adds to it.

***

## Namespace Best Practices

The UNS Viewer makes the consequences of namespace design visible, and the shape it draws is only as good as the topics you publish:

* **Keep the hierarchy consistent** — model your physical or organisational structure, so the graph reads like your plant
* **Use lowercase, stable, descriptive segment names** — and avoid renaming a level once it is in use
* **Publish state as retained messages** so late subscribers, including this viewer, get the current value
* **Prefer descriptive leaf metrics** over opaque blobs that have to be parsed downstream
* **Narrow the root filter** on large namespaces rather than fighting a graph with thousands of nodes

> [!NOTE]
>
> The viewer builds its tree from the topics the HUB has observed. A topic that has never published, and holds no retained value, cannot appear in the graph.

***

## Next Steps

> **[LoT Flow](/hub/lot-flow)**
>
> See the Actions, Models, and Connectors behind those topics as a dependency graph.

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Read individual payloads, track topics as cards, and publish test messages.


# Coreflux HUB Overview
Source: https://docs.coreflux.org/hub/overview

Manage your Coreflux broker—explore MQTT topics, edit LoT code, configure connectors, and monitor system health from the browser or the standalone desktop app

![Coreflux HUB desktop with wallpaper, the top-right status bar showing 9 Routes, Enterprise, the date and time and the root broker menu, and the bottom dock with Coreflux AI, Data Viewer, Routes, LoT Editor, LoT Flow, UNS Viewer, and Dashboards](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/hub/overview/hub-desktop-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=5bbbc917ee62f5c33515685359a848ed)

Coreflux HUB desktop with the app dock and the status bar (connectors, license, time, and broker menu)

## Why Use the Coreflux HUB?

You need a single place to manage your broker without installing extra tools or connecting via the command line. The Coreflux HUB gives you an interface to explore topics, create and edit LoT (Language of Things) definitions, configure connectors, and monitor system status—all from one dashboard. It is available as a browser app (its own container, via Docker Compose) or as a standalone desktop application for Windows and Linux.

> [!NOTE]
>
> The Coreflux HUB is a **separate container** from the broker — it is not bundled in the broker image. Run it with **Docker** or **Docker Compose** (open `http://localhost:3000`) or as a **standalone desktop application** for Windows x64, Linux x64, and Linux ARM64. See [Installation](/latest/quick-start/installation) for Docker commands, Compose profiles, the HUB desktop app, and the login flow. Download builds from the [Downloads page](https://portal.coreflux.org/downloads). An installed desktop app updates itself — see [Update the HUB desktop app](/latest/updating-coreflux#hub-desktop).

> [!NOTE]
>
> A web HUB (Docker or Docker Compose) can be installed from the browser as an app that opens in its own window. After the page loads, use the browser's install control — often **Install** or **Add to Home Screen**. Browsers offer this on `localhost` and on HTTPS. The desktop app is already installed and does not use this.

> [!TIP]
>
> Serve a web HUB over HTTPS (a reverse proxy that terminates TLS) or open it on `localhost`. Over plain HTTP on a LAN address, browsers block clipboard access, so the HUB's copy buttons fail on current versions. See [Copy buttons don't work](/latest/quick-start/installation#copy-buttons-dont-work-in-the-hub).

> [!TIP]
>
> **Like a control panel for your broker.** The HUB puts Data Viewer, LoT Editor, connector management, and system tools in one place so you can deploy and debug without extra tooling.

## When to Use the HUB

* **Manage everything from the HUB** — Configure your broker, deploy logic, and set up data connectors without installing desktop tools
* **Go from idea to deployment in minutes** — Write and deploy Actions, Models, and Rules directly in the built-in editor
* **Monitor your system in real time** — See device connections, data flow, and system health at a glance
* **Diagnose issues fast** — Inspect live MQTT messages and run broker commands from one interface

## Prerequisites

Install the HUB (and the broker, if you do not already have one) from [Installation](/latest/quick-start/installation). After `docker compose --profile full up`, open `http://localhost:3000`, click **New Connection**, and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`). The desktop app is on the **HUB desktop** tab of that page.

To open brokers your organization registered at [portal.coreflux.org](https://portal.coreflux.org), use **Coreflux Fleet** on the login card instead of **New Connection**. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).

## How the HUB Is Organized

The HUB is built around six apps. Each app groups related tools so you can switch between tasks without leaving the browser. **Cluster Viewer** is Beta. Its dock icon, labeled **Cluster**, appears only when the broker host you are connected to is in a cluster.

> **[MQTT](/hub/mqtt/overview)**
>
> Explore topics, publish messages, and view connected clients.

> **[LoT Editor](/hub/lot-editor)**
>
> Create and edit Actions, Models, and Rules in the browser.

> **[Dashboards](/hub/dashboards/overview)**
>
> Build live panels with gauges, charts, and controls bound to broker data.

> **[Connectors](/hub/routes/overview)**
>
> Add, configure, and monitor connectors with templates or LoT code.

> **[System](/hub/system/overview)**
>
> Broker configuration, user management, trace logs, and command console.

> **[Cluster Viewer](/hub/cluster-viewer)**
>
> See nodes, the leader, links, and ownership on a clustered broker host. Beta.

> [!NOTE]
>
> Connected to a generic MQTT broker, the dock keeps **Data Viewer** and **UNS Viewer**. Coreflux apps stay hidden, and the status bar offers **Know more about Coreflux**. See [When the broker is not Coreflux](/hub/connections#when-the-broker-is-not-coreflux).

### MQTT

Browse live data flowing through your broker. The MQTT app includes a **Data Viewer** for subscribing to topics and publishing test messages, and a **Connected Clients** view to see which devices are online.

![Coreflux HUB Data Viewer maximized, topic tree filtered to energy-site-01 with live values, and the status/host topic pinned on the right with a Live message timeline and a parsed JSON payload](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/mqtt/data-viewer/mqtt-explorer-overview-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=6b410c1ce65cc1f77a640aa79184b898)

Data Viewer: the topic tree filtered to a site, with a topic pinned on the right showing its message timeline and payload

### LoT Editor

Write and deploy logic directly in the HUB. The LoT Editor is a notebook editor: cells hold LoT, Python, or Markdown, each cell deploys on its own, and the sidebar lists everything currently running on the broker — no external tools required.

![Coreflux HUB LoT Editor showing the digital-twin-energy-site project badged LIVE, energy-site.lotnb open with a markdown intro and a DEFINE ROUTE cell badged DEPLOYED, and the Broker runtime tree with Actions, Models, Rules, Routes, Python, Themes, and Panels](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/lot-editor/hub-lot-editor-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=99cf12e43faa20ef201525799789f24a)

LoT Editor with the live project's notebook open: Projects, Broker runtime, Configuration, and Library in the sidebar, with Deployed and Deploy All in the header

### Dashboards

Design operator-facing screens from a component library—gauges, charts, industrial symbols, and controls—and bind each widget to live data on your broker. The **Dashboard Manager** lists your panels; open one to preview or use it full screen for walls and shared links.

![Coreflux HUB panel Solar energy site · Energy twin with a 3D site scene labelled with live power values, and Site power cards for PV, Site load, Grid, Battery, a Fleet state of charge gauge, and Peak import cap](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/dashboard/overview-hero-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=d66a730bd8466d29aa748fa31e47a610)

Dashboards: a published panel with a live 3D site view and KPI cards bound to broker topics

### Connectors

Connect your broker to databases, PLCs, and external systems. The Connectors app shows each connector as a card with a live **status indicator**, and lets you configure connectors visually or in LoT code.

![Coreflux HUB Connectors Manager with connector cards for LegacyLogs and PlantArchive (FILE\_STORAGE), each with a status dot and Configuration, Monitor, Documentation, and Delete icons, an Add connector card, and the status bar Connectors popover](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/routes/overview/connectors-manager-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=6b518a51578d5981f1a1dbae80dbe065)

Connectors Manager: connector cards with type badges, live status dots, and quick actions

### System

Administer the broker itself. The System app provides **Broker Configuration**, **User Management**, a **Command Console** for direct broker commands, and **Broker Logs** for real-time diagnostics.

![Coreflux HUB broker menu opened from the status bar showing Online with the broker version, then Broker items Connected Clients, Broker Settings, User Management, Command Console, Broker Logs, HUB items Themes and Hub Settings, Help items, and Log out](https://mintcdn.com/coreflux/Uf6-R5aKoVdKVLMM/images/hub/overview/hub-system-menu-light.png?fit=max\&auto=format\&n=Uf6-R5aKoVdKVLMM\&q=85\&s=a3a37badfbbd20a8f97e5fbdef5dbf09)

The broker menu in the status bar: broker tools, HUB settings, and help

### Cluster Viewer

See how the broker hosts in a cluster fit together: who leads, which links are up, which node owns each exclusive piece of LoT, and how partitions are placed. Open **Cluster** on the dock. The window carries a **Beta** badge, and the icon is there only while that broker host publishes cluster status. See [Cluster Viewer](/hub/cluster-viewer).

***

## Desktop shell

The desktop layout keeps a Coreflux logo at the top left, a status bar at the top right, and the app dock along one edge of the screen. The logo returns you to the desktop. The account pill on the status bar opens broker tools and settings for this HUB install. You get this layout in the standalone app and in a desktop browser. A phone keeps a full-width bar and leaves these saved preferences unchanged.

### Logo and the account pill

Click the Coreflux logo to show the desktop. Every open window minimizes. The logo hides and returns together with the status bar.

The account pill shows your display name while you are connected, and **Disconnected** when you are not. Open it for the sections below.

| Section | What you open |
| - | - |
| **Broker** | **Connected Clients**, **Broker Settings**, **User Management**, **Command Console**, and **Broker Logs**. This section appears when you have system access on the broker host. **Broker Settings** opens [System Configuration](/hub/system/configuration). |
| **Hub** | **Themes** and **Hub Settings**. This section stays available without system access on the broker host, including an anonymous sign-in. These choices stay on this HUB install. |
| **Help** | **Documentation**, **LoT Templates**, **What's New**, **Send Feedback**, **About**, and **Walkthroughs**. |

**Switch user** appears when the current connection has more than one identity. **Switch broker** appears when this HUB has another saved connection. **Log out** ends the session. See [Connections Manager](/hub/connections) for identities and saved connections.

### First-run walkthroughs

The first time you open the HUB, a Hub tour walks the desktop. The first time you open an app, a short tour of that app runs. **Help → Walkthroughs** replays a tour, and the same menu offers **Mark all walkthroughs done** and **Reset all walkthroughs**. Whether you have already seen a tour is stored for this browser profile, or for this desktop install.

### Hub Settings

Open the account pill, choose **Hub**, then **Hub Settings**. The window configures this HUB install, and you can open it without system access on the broker host. Changes apply as you make them.

| Section | What you set |
| - | - |
| **Profile** | A **Default** or **Optimized** preset for the sections below |
| **Desktop** | Dock position, dock auto-hide, and status-bar auto-hide. A phone leaves the saved values unchanged |
| **Diagnostics** | Memory and CPU for this HUB, and **Prune now** to drop idle topics from the local cache |
| **MQTT store** | How many topics, and how much history, the HUB keeps in memory |
| **Subscriptions** | Which topics Data Viewer and UNS Viewer subscribe to |
| **Viewers** | How often UNS Viewer and LoT Flow refresh, and whether they pause while minimized or while the HUB is in the background |
| **Look & motion** | **Performance mode**, and whether video wallpapers keep playing |

### Dock and status bar

Right-click the dock bar — the strip behind the icons — to set its layout. Right-click an app icon to open that window's own menu.

| Dock | Choices | Default |
| - | - | - |
| **Position** | **Bottom**, **Left**, **Right** | **Bottom** |
| **Auto-hide** | **Always**, **Never**, **When fullscreen** | **When fullscreen** |

**Left** and **Right** turn the dock into a vertical column. The dock draws over your windows, and the workspace keeps its full size.

Right-click the status bar to set when it hides.

| Status bar | Choices | Default |
| - | - | - |
| **Auto-hide** | **Always**, **Never**, **When fullscreen** | **Never** |

The same three controls are under **Hub Settings → Desktop**. The HUB saves them for this install. When a bar is hidden, move the pointer to its edge to bring it back.

**When fullscreen** hides that bar while a window is fullscreen. A zoomed window leaves the dock and status bar where they are.

### Zoom and fullscreen

| Gesture | What happens |
| - | - |
| Double-click the title bar | The window zooms to fill the area under the status bar. |
| Maximize, with status-bar auto-hide **Never** | The window zooms, the same as a double-click. **Never** is the default, so the status bar stays on screen. |
| Maximize, with status-bar auto-hide **Always** or **When fullscreen** | The window fills the screen. The dock and status bar then follow their own auto-hide settings. **Escape** restores the previous size. Move the pointer to the top edge to reveal the title bar and the status bar together. |

A dock set to **Never** stays on screen during fullscreen. **When fullscreen** on the dock hides the dock only in that state.

***

## Next Steps

> **[Installation](/latest/quick-start/installation)**
>
> Run the HUB with Docker, Compose, or the desktop app — then connect from New Connection.

> **[Connections Manager](/hub/connections)**
>
> Save multiple brokers, secure them with TLS, and switch between them.

> **[Data Viewer](/hub/mqtt/data-viewer)**
>
> Subscribe to topics and publish messages from the browser.


# Release Notes
Source: https://docs.coreflux.org/product-updates/release-notes

New features, improvements, and fixes in each release of the Coreflux MQTT broker and HUB.

Product

**MQTT Broker**

**2.22**

August–October 2026

> [!WARNING]
>
> **Breaking Changes** in this release (2.15–2.22):
>
> **`TYPE MCP_SERVER` is gone** — The MCP server is now broker configuration, not a LoT connector, and a project that still defines `TYPE MCP_SERVER` fails to load. Enable `Mcp.Enabled` (or `COREFLUX_MCP_ENABLED=1`), mint a token with `-createMcpToken`, and point the client at Streamable HTTP `/mcp`. Legacy SSE URLs stop working. The MCP client connector (`TYPE MCP` / `CALL MCP`) is unchanged. **Action:** remove old `TYPE MCP_SERVER` definitions and follow [MCP Server](/latest/mqtt-broker/mcp-server).
>
> **`TYPE AGENT` connectors are removed** — `-addConnector` refuses them and stored ones are skipped at load, with their topics. Rewrite each as a `TYPE LLM` connector plus `DEFINE AGENT … USES LLM CONNECTOR`; nothing is granted until `ADD TOOL`, and writes need `WITH LEVEL "write"`. There is no automatic migration. **Action:** rewrite agents before you upgrade. See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).
>
> **No built-in trial** — A broker with no license runs as **Community**. Get a 30-day Growth-type license at [portal.coreflux.org](https://portal.coreflux.org), where you also manage your fleet.

### 2.22.0 - Things, Agents, licensing, and a built-in MCP server

This release lets you model devices once and reuse them (Things), build AI agents that only do what you allow, and connect tools like Cursor or Claude Desktop straight to the broker. It also adds signed licensing with fleet enrollment, certificate management, and clustering that runs your LoT on every node.

#### Highlights

* **Model a device once, then reuse it (Things, preview)** — Describe a pump, a line, or a sensor type once. Each copy gets its own topics, and you add as many as you need without copying LoT. See [Things](/latest/lot-language/things/overview).
* **Let AI act only where you allow it (Agents, preview)** — An agent starts with no tools. You grant each read or write, and a question-only mode never changes the broker. See [Agents](/latest/lot-language/agents/overview).
* **Work on the broker from Cursor or Claude** — A built-in MCP server lets those tools run broker commands, with tokens you create and revoke. See [MCP Server](/latest/mqtt-broker/mcp-server).
* **Keep every cluster node on the same LoT** (**Beta**) — Deploy to any node and the whole cluster runs it. A device connector can stay on the node that can reach the equipment. See [LoT in a cluster](/latest/mqtt-broker/clustering#lot-in-a-cluster).
* **License a broker and add it to your fleet** — An unlicensed broker runs as Community. Activate online, use a signed file where there is no internet, and enroll the broker in your organization. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).
* **Replace certificates without a restart** — Update the certificate the broker presents, choose which clients to trust, and see which certificates are about to expire. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Sign in with your identity provider** — Clients can use an OIDC access token as the MQTT password. Local passwords still work. See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Pause logic without deleting it** — Turn an action, connector, or agent off, keep the definition, and turn it back on when you are ready. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **See when a device is actually down** — Industrial connectors show Reconnecting when a PLC stops answering, and the last good tag values stay in place through a short disconnect. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **Bring in audio, gRPC, and hundreds of APIs** — Capture microphone audio onto MQTT, call gRPC services, and start from 220+ REST API app templates (technical preview). See [REST API Apps](/latest/lot-language/routes/rest-api-apps/index).

#### Things and Agents (preview)

* **Define a device once** — A Thing is a typed device with `{{placeholder}}` topics. Add instances with `-addThing` (use `--dryRun` to validate first), and manage them with `-removeThing` and `-listThings`, or the MCP tools `add_thing`, `list_things`, and `remove_thing`. Each Thing publishes its source, tree, and health under `$SYS/Coreflux/Things/<name>`. See [Things commands](/latest/mqtt-broker/commands#things).
* **Agents with limited access** — An agent uses a `TYPE LLM` connector for its provider, model, key, and price, and starts with no tools. It gets only what `ADD TOOL` grants. Agents can ask each other for help with `WITH AGENTS`, and actions call them with `CALL AGENT`. Each agent publishes its card and status under `$SYS/Coreflux/Agents/<name>/`.
* **Read-only questions** — Ask an agent with `"mode": "insight"` and it only reads, including any agents it delegates to. `TYPE LLM` also accepts `REASONING_EFFORT` (`none` to `extra_high`).

#### New connectors

* **Audio Input** — Capture a microphone, test tone, silence, or a file as 16-bit PCM audio on MQTT (`TYPE AUDIO_INPUT`). See [Audio Input](/latest/lot-language/routes/media/audio-input).
* **gRPC** — Call gRPC services from MQTT with `TYPE GRPC`, including streaming. See [gRPC Connector](/latest/lot-language/routes/streaming/grpc).
* **REST API apps** — 220+ ready-made `TYPE REST_API` templates for cloud, ERP, MES, messaging, and IIoT services, in technical preview. See [REST API Apps](/latest/lot-language/routes/rest-api-apps).

#### MQTT and LoT

* **Connectors naming** — `DEFINE CONNECTOR` and the `-addConnector`, `-removeConnector`, `-listConnectors`, `-removeAllConnectors`, and `-checkConnectorConnection` commands are the new names. `DEFINE ROUTE` and the `-…Route…` commands keep working as aliases.
* **Turn things off without deleting them** — Put `DISABLE true` under `DEFINE` on an action, connector, or agent to keep it stored but not running. Switch it back on with `-disableAction`, `-disableConnector`, `-disableAgent` and the matching `-enable…` commands, or with MCP tools. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **Publish with retain and QoS** — `PUBLISH TOPIC` accepts `RETAIN` and `QOS0` / `QOS1` / `QOS2` (default QoS 0). `KEEP TOPIC` still only stores a value for `GET TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#publish-topic).
* **Shared subscriptions** — Turn on `SharedSubscriptions` and `$share/{group}/{filter}` delivers each message to one member of the group. Off by default. See [Shared subscriptions](/latest/mqtt-broker/protocol#shared-subscriptions).
* **Predictable topic triggers** — `ON TOPIC` actions, models, and connector events run on the exact message that fired them, in publish order per topic. Different topics still run in parallel. See [Action Triggers](/latest/lot-language/actions/events).
* **Every publish in an action is sent** — Each `PUBLISH TOPIC` or `KEEP TOPIC` in one run is delivered, in the order written, with that line's own retain, QoS, and keep settings. A later `GET TOPIC` in the same run reads the value just written. In a cluster, only the last `KEEP` of each topic is replicated. See [PUBLISH TOPIC](/latest/lot-language/actions/operations#publish-topic).
* **Panel wait and markdown** — A button accepts `SET AWAIT "Id, Id"` and `SET AWAIT_TIMEOUT` (seconds, default 120). A text component accepts `SET MARKDOWN true`. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button) and [Markdown text](/latest/lot-language/panels/defining-panels#markdown-text).

#### Licensing and enrollment

* **Plans** — Community, Growth, and Enterprise, with limits on artifacts and connectors. Status is on retained `$SYS/Coreflux/License` and, on the ops port, `GET /license` (port `9100`, keep it private).
* **Three ways to license** — Activate online with `COREFLUX_ACTIVATION_CODE` or `-activateLicense CFLX-…` (limits apply without a restart, the lease refreshes daily, `-refreshLicense` forces it). Or install a signed license file (`config/license.jws`, `COREFLUX_LICENSE_FILE`, `COREFLUX_LICENSE_TOKEN`, or `-loadLicense`), which the broker verifies locally with no network. For air-gapped hosts, send the `--show-fingerprint` value to Coreflux and install the hardware-bound license you get back.
* **Enroll in your organization** — `-enroll et_…` (or `--enroll`, or `config/enrollment-token`) binds the broker to your Coreflux organization, separately from its plan. An activation code enrolls it too. A broker waiting for enrollment still starts: local users work, and logins that need the organization are refused until it succeeds. `$SYS/Coreflux/License` explains why it is pending. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

#### MCP server

* **Connect AI tools to the broker** — Cursor, Claude Desktop, and other MCP clients connect to the broker's built-in server, configured in the `Mcp` block (port `6278`, bound to `127.0.0.1`, path `/mcp`). Manage tokens with `-createMcpToken`, `-listMcpTokens`, and `-revokeMcpToken`, or from the HUB **MCP** tab. In Docker or Kubernetes, bind to `0.0.0.0`, publish `6278`, and route `/mcp` behind TLS. See [MCP Server](/latest/mqtt-broker/mcp-server#docker-and-kubernetes).
* **Install agent skills** — The public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository is generated from the broker, and the broker exposes the same pack as the `coreflux://skills` MCP resource. Coding agents that install it write LoT the broker accepts. They need broker 2.22 or later. See [Agent skills](/ai/agent-skills).

#### Security

* **Sign in with OIDC** — With `Oidc.Enabled`, a client sends an OIDC access token as its MQTT password. The broker validates it, checks the organization, and authorizes by the token's groups. Local passwords still work. A client is disconnected when its token expires (30-second grace). See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Manage certificates from a command** — `-brokerCertificates` (admin only) shows and replaces the server certificate and Root CA, and manages the mTLS trust store: list, import, export, revoke, settings. A new server certificate applies without a restart and keeps a `.bak-` copy. Revocation is immediate and every change is audit-logged. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Know when certificates expire** — Retained `$SYS/Coreflux/Certificates/Summary` counts valid, expiring, expired, and unreadable certificates. `CertificateExpiryThresholdDays` (default 30) sets the warning window. See [`$SYS/Coreflux/Certificates/Summary`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary).
* **Easier trust store** — `ClientCertificateSourcePath` loads `.pem`, `.crt`, `.cer`, `.der`, and unprotected `.p12`/`.pfx` files, skips anything in `revoked/`, and refuses keys and CSRs (install a server key with `replaceServer`). `$SYS/Coreflux/Config` shows `ServerCertificatePassword` as `********`.

#### Clustering and operations

* **LoT works across a cluster** (**Beta**) — Definitions replicate through the leader, so you can send LoT to any node and every node runs the same version. Each message runs LoT once, on the node it entered. Timers, `ON START`, and device connectors run on one owner and move to another node within about 10 seconds if it fails. Pin a device connector to a node with `CLUSTER_NODE` in `ROUTE_CONFIG`. **Action:** upgrade every node before you change LoT, and create users on every node.
* **Faster Kubernetes scaling** (**Beta**) — A pod that the headless Service no longer lists leaves the cluster about 2 minutes after its cluster port stops answering (`MemberAbsentFromDiscoverySeconds`, 120 seconds by default; it used to wait 5 minutes). New pods are found within seconds. See [How a cluster works](/latest/mqtt-broker/clustering#one-leader-automatic-membership).
* **More metrics** — New `/metrics` series for delivered messages, CPU, auth failures, ACL denials, rate limits, connector drops, and errors. See [Metrics](/latest/mqtt-broker/operational-endpoints#metrics).
* **Fleet health reporting** — An enrolled broker reports CPU, memory, clients, traffic, refusals, drops, and scrubbed error signatures to the Coreflux Portal. It never sends topics, payloads, hostnames, or IPs. Turn it off in the portal, or with `COREFLUX_FLEET_METRICS=off` or `DO_NOT_TRACK=1`. See [Fleet performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics).

#### Bug fixes

**Industrial connectors**

* **Connection status tells the truth** — Modbus, S7, OPC UA, EtherNet/IP, ADS, Allen-Bradley, FINS, and BACnet no longer wipe retained tag values on a disconnect or failed read, and a restarted connector polls again. A connector no longer shows Connected while its device is unreachable: after 3 failed read cycles it reports Reconnecting and rebuilds the connection. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **No more hangs on silent devices** — A PLC that accepts a connection but never answers no longer freezes S7 (`READ_TIMEOUT` now limits the connect) or EtherNet/IP (`READ_WRITE_TIMEOUT` now bounds every exchange). **Action:** raise `READ_WRITE_TIMEOUT` for slow EtherNet/IP devices.
* **Modbus TCP** — Each connection runs one request at a time, so tags no longer go BAD with "Response was not of expected transaction ID". See [Modbus TCP Client](/latest/lot-language/routes/industrial/modbus-tcp-client#one-request-at-a-time).
* **FINS** — A slow reply no longer shifts later reads onto the previous command's value, and a lost PLC goes to Reconnecting after 2 unanswered commands. Replies must now match the request and come from the addressed node. **Action:** gateways that swap client and server nodes now time out; check `LOCAL_NODE` / `REMOTE_NODE`. See [FINS](/latest/lot-language/routes/industrial/fins).
* **Allen-Bradley** — A slow but healthy PLC no longer reconnects every cycle, and a timed-out write publishes `"outcome": "unknown"`. See [Write results](/latest/lot-language/routes/industrial/overview#write-results).
* **ADS** — `TIMEOUT` now applies to every request (it was ignored and fixed at 5 s), and an unreachable PLC makes the connector reconnect. See [ADS](/latest/lot-language/routes/industrial/ads).
* **OPC UA** — A read or write that races a reconnect marks the tags BAD and backs off instead of counting as success, and sessions no longer leak.
* **BACnet** — Integer writes of any size send the right value (out-of-range 64-bit values fail instead of being cut off), and reads queued on a dropped connection no longer break the new one.
* **Tag values** — Negative `OFFSET`, `MIN_VALUE`, and `MAX_VALUE` now parse. See [Common TAG parameters](/latest/lot-language/routes/industrial/overview#common-tag-parameters).

**Other connectors**

* **Kafka** — A `"in"` event commits its offset only after the message is published, so a crash no longer drops records. `WITH EVERY` on a Kafka event is now rejected when you add the connector. **Action:** publish on a schedule with `ON EVERY` in a LoT action. See [Kafka Connector](/latest/lot-language/routes/streaming/kafka).
* **Kafka and gRPC start** — A connector that fails to start is retried in the background (2 to 60 seconds) until it starts or you remove it.
* **Ollama** — A `TYPE LLM` connector with `PROVIDER ollama` takes `CONTEXT_WINDOW` (a fixed `num_ctx`, sized per call and capped at the model's maximum), `MAX_CONTEXT_WINDOW` (default 32768, minimum 16384), `FIRST_OUTPUT_TIMEOUT` (default 120 s), and `IDLE_TIMEOUT` (default 60 s). Agent tasks fail with a clear error (`llm_timeout`, `llm_unreachable`, `model_not_found`, `context_overflow`) instead of hanging. See [Ollama context and timeouts](/latest/lot-language/routes/ai-routes#ollama-context-and-timeouts).
* **Email and CrateDB** — Email `ADD EVENT` blocks now send and publish their status. CrateDB `ADD EVENT` blocks run, `STORE IN` writes rows, and the connector reconnects after a CrateDB restart.
* **REST API** — A reply published right away on `REPLY_TOPIC` reaches the HTTP client instead of a 504, and concurrent requests no longer cancel each other. A value in `ENDPOINT` can no longer send the request and its credentials to another host; the broker refuses it and publishes `RequestRejected`. See [Placeholder Support](/latest/lot-language/routes/rest-api-routes#placeholder-support).
* **MQTT bridge** — A bridge without `CLIENT_ID` forwards inbound messages and no longer clashes with other bridges, and a removed bridge stops forwarding at once.
* **Sparkplug B** — The Primary Host tracks `seq` per edge node and no longer floods Rebirth requests, and DATA metrics without a datatype decode using the birth certificate.
* **`TRIGGER` on LLM, AGENT, and MCP** — MCP calls the named tool, and LLM and AGENT results go to the mapping's `DESTINATION_TOPIC` or the default response topic instead of being discarded.

**LoT and MQTT**

* **`GET MODEL`** — `SET … WITH GET MODEL` no longer fails on the action's first run, `PUBLISH TOPIC … WITH GET MODEL` parses, and `WHERE` conditions joined with `AND` accept any mix of text and numbers. See [GET MODEL](/latest/lot-language/actions/operations#get-model).
* **`STORE IN … WHEN`** — Conditional model storage works instead of failing on first evaluation, and an unknown field is rejected at deploy. See [Store data with models](/latest/lot-language/routes/data-storage/overview#step-2-store-data).
* **`MATCHES REGEX`** — Patterns with `\d`, `\w`, `\s`, or `\.` work as written. See [MATCHES REGEX](/latest/lot-language/rules/syntax#matches-regex).
* **`TRIGGER` statements** — The line after a `TRIGGER` is no longer dropped. Examples now use `TRIGGER "<connector>" TO <data> FOR "<event>"`; code copied from the old order (`WITH "<event>" FOR <data>`) still deploys but swaps the data and the event. See [TRIGGER Statement](/latest/lot-language/actions/operations#trigger-statement).
* **MQTT 5 denials** — A denied publish now gets `0x87 Not authorized` and a rate-limited one `0x97 Quota exceeded`, instead of Success. See [What a denied client sees](/latest/lot-language/rules/rbac#what-a-denied-client-sees).
* **Callable actions from panels** — Object, array, and `null` arguments no longer cause a compile error; objects and arrays arrive as JSON text.
* **Protobuf `float` and nested `GET PROTO`** — `ADD FLOAT` (alias `ADD SINGLE`) decodes proto `float`, and dotted `GET PROTO` paths read nested messages. A field with the wrong type is skipped instead of stopping the whole message. See [Protobuf Models](/latest/lot-language/models/protobuf).

**Panels, projects, and platform**

* **Panels** — Boolean CSS bindings (`BIND CSS … AS BOOLEAN`) convert correctly in the HUB. SVG markup from `SET INLINE` and `data:` sources is rebuilt from an allow-list so scripts, event handlers, and external links can't run in viewers' browsers; what was removed is listed as a deploy warning.
* **Projects** — A live project's history records only the edited cell, not the whole notebook. After a restart, the broker also loads connectors added outside the project and the connectors of Things, and publishes Thing status from boot. See [LoT THING](/latest/lot-language/things/overview).
* **Metrics** — Published-message and byte counters no longer reset at UTC midnight, so `rate()` works across it. `coreflux_messages_published_total` now counts client publishes; deliveries moved to `coreflux_messages_delivered_total`.
* **Linux packages** — APT and DNF units run the broker as the user `coreflux` with `CAP_NET_BIND_SERVICE`, so they can bind ports below 1024. See [Ports below 1024](/latest/mqtt-broker/startup-options#ports-below-1024).

**Configuration**

* **Partial config is merged** — A partial JSON object published to `$SYS/Coreflux/Config/New` is merged into the live configuration. Fields you omit, including bind addresses, stay as they are. See [Applying Configuration](/latest/mqtt-broker/configuration#via-mqtt-topic).

**2.14**

August 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.14.3 - Default rules and Visu panel publishing

#### Bug fixes

* **Default rules load with an active project; Visu panels can be published** — When a project is already active at startup or after `-loadProject`, the broker's seeded permission rules now apply correctly so internal clients retain `$SYS` access and panels publish to `$Visu/...` topics again after project activation.

### 2.14.2 - Sparkplug B connector, MQTT & LoT performance improvements

Sparkplug B Support, MQTT client lifecycle action triggers, better OT master/client visibility in broker logs, a banded Rules precedence model, project lifecycle improvements, and faster publish, LoT, and connector dispatch.

#### Improvements

* **Rules priorities are now banded** — The rule priority number line is split into bands: `0`–`99` is reserved for the broker's immutable system rules, `100`–`999 999` is your band, and the permissive catch-alls `AllowPublishTopic` / `AllowSubscribeTopic` now sit at `1 000 000`. Only the strongest matching band decides an operation, where a DENY beats an ALLOW (deny-wins) and nothing matching means denied (default-deny). Moving the catch-alls to the weakest band **fixes a topic-visibility bypass**: they previously shipped tied with everything else, so a specific access rule could not reliably override the allow-all fallback — which left Visu panel view topics effectively public. `-addRule` now rejects priorities outside `100`–`1 000 000`. **Action:** custom rules written in the old `1`–`99` range are clamped to `100` on load and logged individually. Clamping keeps them in force, but several rules can land on `100` together, where ties resolve deny-wins — re-space them across the user band, putting the more specific rule at the lower number. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac#rule-precedence).
* **`AllowConnect` seed and `FOR Connect` rules** — Fresh brokers now ship a third permissive catch-all, `AllowConnect`, at priority `1 000 000` (the same weakest band as `AllowPublishTopic` / `AllowSubscribeTopic`). Write `FOR Connect` rules in the user band to decide who may connect after authentication; they outrank the seed. Brokers with no Connect rule at all still leave CONNECT ungated. `-restoreRules` puts all three seeds back to their shipped ALLOW definitions. See [RBAC](/latest/lot-language/rules/rbac#connection-admission) and [`-restoreRules`](/latest/mqtt-broker/commands#restoring-seeded-rules).
* **Project manifests, entity ownership, and ad-hoc entities** — Each stored project publishes a retained content manifest on `$SYS/Coreflux/Projects/{name}/manifest` (SHA-256 of exact file bytes, plus entities declared in `.lotnb` cells). `-projectManifest` returns the same JSON on demand. Running entities are attributed on `$SYS/Coreflux/Entities/ownership` and in the `-listEntities` / `-loadProject` `origin` field. **Loading or unloading a project no longer deletes ad-hoc entities** added with `-addAction` and similar commands while no project was active. **Action:** if you relied on Activate to wipe the whole runtime, remove those entities explicitly before loading a project. See [Project Commands](/latest/mqtt-broker/commands#project-commands) and [Project Topics](/latest/mqtt-broker/sys-topics#project-topics).
* **Loaded projects stay active after a restart** — After `-loadProject` (or `--project`), the last loaded project is remembered and re-activated on the next start unless you pass `--project`. `-unloadProject` returns to standalone mode on the next restart. See [Startup Options](/latest/mqtt-broker/startup-options#loading-a-project-at-startup).
* **`ON START` runs on deploy; action publishes are no longer blocked by user ACL** — Deploying an `ON START` action on a live broker executes the body immediately (cold start still runs once after the MQTT broker is ready). Action `PUBLISH` / `KEEP` still put messages on MQTT for any subscriber; they are no longer denied by user publish rules, so bootstrap topics from actions are not silently dropped. Clients still need subscribe permission to receive those messages. See [Initialization Triggers](/latest/lot-language/actions/events#initialization-triggers).
* **OT string sizing — `LENGTH` is the preferred keyword** — Across OT connectors that support configurable string sizing, `WITH LENGTH` is now the documented primary keyword; `STRING_SIZE` remains accepted as a parser alias. See the shared [String sizing by Connector](/latest/lot-language/routes/industrial/overview#string-sizing-by-connector) reference on the industrial connectors overview.
* **Modbus Server STRING defaults and cap** — Unsized `STRING` tags no longer reserve a single register (which silently truncated barcodes and caused Illegal Data Address on FC16 writes). The server now defaults to **40 bytes (20 registers)** and warns when size is omitted. Connector validation rejects `LENGTH` values above **246 bytes (123 registers)**, the FC16 write cap. See the [Modbus TCP Server Connector guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **Modbus Server and OPC UA Server activity logging** — Modbus Server connectors log accepted and rejected master writes (plus rejected reads), with bank-aware function-code labels and `LENGTH` guidance when an undeclared holding-register range is the cause; connection open/close counts are logged from the existing watchdog (**the master's source IP is not available**). OPC UA Server connectors log client session create/close events and accepted external writes on tags and STRUCT fields.
* **MQTT client lifecycle action triggers** — New `ON CONNECT DO`, `ON DISCONNECT DO`, and `ON SUBSCRIBE ["pattern"] DO` triggers run LoT automation when clients connect, disconnect, or subscribe. Action bodies expose session context via `CLIENTID`, `USER`, `ENDPOINT`, `CLEANSESSION`, `DISCONNECTREASON`, `SUBSCRIBETOPIC`, and `SUBSCRIBEQOS`. The broker only evaluates lifecycle hooks when at least one action defines them. See [Action Triggers](/latest/lot-language/actions/events#client-lifecycle-triggers).
* **Improved command response handling** — Broker command responses are now consistently structured as JSON. Each command may include a `requestId` field, allowing you to easily correlate requests and responses.
* **Sparkplug B connectors (beta)** — Decode Sparkplug B protobuf into readable JSON, publish Coreflux topics as an edge node, or run Coreflux as the Primary Host Application with namespace state, commands, and automatic rebirth requests. See the [Sparkplug B Connector](/latest/lot-language/routes/system/sparkplug-b) and [Sparkplug Host Connector](/latest/lot-language/routes/system/sparkplug-host) guides.

#### Performance

* **MQTT between clients** — More messages complete per second, the slowest publishes finish sooner (about 10% lower p99 latency). Messages that update connector topics stay in the order they arrived.
* **LoT rules and actions** — Permission checks, topic triggers, timers, and dashboard invokes no longer slow down as more distinct topics exist on the broker. LoT-heavy traffic that was about **10× slower at 30,000 topics** — and about **70× slower at 100,000** — now stays as fast as it was on a nearly empty broker. `USER HAS` and `USER IN GROUP` checks stay fast as the user list grows.
* **Connector mappings** — Adding mappings no longer makes every publish more expensive, including on topics that no mapping uses. Exact-topic mappings (the common case) keep up with tens of thousands of messages per second at **sub-millisecond** latency with **no loss** — the same flood previously took around **25 seconds** and dropped some messages. Wildcard mappings (`+` / `#`) now deliver fully as well. When a connector cannot keep up, memory stays bounded: the broker waits, then drops the **newest** arriving message rather than older ones already in flight. Set `ADD ROUTE_CONFIG` on a connector (`OVERLOAD_POLICY`, `OVERLOAD_TIMEOUT`, `OVERLOAD_CAPACITY`) when that connector needs a different wait-or-drop contract. See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward).

#### Bug fixes

* **Rules with `IF` and no `ELSE` now compile** — `IF USER IS "dashboard" THEN DENY` (no `ELSE`) previously failed compilation on first evaluation and was treated as a deny for every matching publish or subscribe. The missing branch is now the opposite of the `THEN` decision. See [Rules Syntax](/latest/lot-language/rules/syntax#combining-conditions).
* **Python scripts no longer lose their code on restart** — Scripts that contained blank lines were truncated down to the `# Script Name:` header after a reboot, so `CALL PYTHON` failed even though the script still appeared in listings. Complete scripts now persist across restarts. See [Python Integration](/latest/lot-language/actions/python-integration#writing-python-scripts).
* **Built-in rules survive project add/load/unload** — Adding or switching a project no longer wipes the broker's default permission rules, so internal clients keep `$SYS` access. See [RBAC](/latest/lot-language/rules/rbac#seed-catch-alls).

**2.2**

July 2026

### 2.2.0 - Kafka, OPC UA Server & Modbus Server routes

* **Kafka route** — Connect Coreflux directly to Kafka as a producer or consumer, with support for security protocols and configurable batching and compression. See the [Kafka Route guide](/latest/lot-language/routes/streaming/kafka).
* **OPC UA Server route** — Expose Coreflux data to OPC UA clients with a secure-by-default setup, including support for array and struct nodes. See the [OPC UA Server Route guide](/latest/lot-language/routes/industrial/opcua-server).
* **Modbus Server route** — Serve Modbus data over TCP, with experimental support for Serial (RTU) connections. See the [Modbus TCP Server Route guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **OT route persistence** — Server routes (OPC UA Server, Modbus Server) persist their state and recover automatically after a restart, so data isn't lost on reconnect. See [OPC UA Server persistence](/latest/lot-language/routes/industrial/opcua-server#data-persistence--recovery) and [Modbus Server persistence](/latest/lot-language/routes/industrial/modbus-tcp-server#data-persistence--recovery).
* **OPC UA client certificate authentication** — Authenticate OPC UA client connections using PKI certificates for more secure deployments.
* **Modbus one-based addressing** — Set `WITH ONE_BASED_ADDRESSES true` on Modbus client and server routes so tag addresses match device manuals that label registers starting at 1. See [Modbus addressing](/latest/lot-language/routes/industrial/modbus-tcp-client#modbus-addressing) (client) and [Address notation](/latest/lot-language/routes/industrial/modbus-tcp-server#address-notation) (server).
* **Publish payload as bytes** — Forward or retain binary MQTT payloads bit-for-bit with `PAYLOAD AS BYTES` on `PUBLISH TOPIC` and `KEEP TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#binary-passthrough--payload-as-bytes).
* **EtherNet/IP route** — Joined attribute reads (`ENABLE_JOIN_ATTRIBUTE`), bit extraction (`BIT_ADDRESS`), ARRAY/STRUCT decoding from assembly buffers, bidirectional `WRITABLE` tags, and legacy Hub Asset field mapping for migrations. See the [EtherNet/IP Route guide](/latest/lot-language/routes/industrial/ethernetip).
* **Allen-Bradley route** — Symbolic tag-name access (`Program:MainProgram.Tag` format), `AB`/`ALLENBRADLEY` route aliases, `PATH` vs `SLOT` routing, family-specific STRING/TIME encoding, and cross-link to EtherNet/IP for explicit CIP paths. See the [Allen-Bradley Route guide](/latest/lot-language/routes/industrial/allen-bradley).
* **Bug fixes** — Fixed BACnet alarm retention, EtherNet/IP connection parameters and legacy-style compatibility, a Modbus TCP word-order issue, an OPC UA client connection issue, and a licensing load-order.

**2.1**

June 2026

### 2.1.0 - BACnet route (building automation) and Protobuf models

* **BACnet route** — Connect Coreflux to building automation systems (HVAC, lighting, metering) and bridge them to MQTT
  * Read live values and write setpoints to BACnet controllers
  * Get instant updates on change, without constant polling
  * Receive alarms and event notifications directly in MQTT

See the [BACnet Route guide](/v2.1/lot-language/routes/industrial/bacnet) to get started.

* **Protobuf LoT models (beta)** — Decode and encode binary protobuf on MQTT from LoT: `WITH FORMAT PROTOBUF` (or `BOTH`), `PROTO_TAG` to match vendor `.proto` field numbers, `ADD MODEL` for nested messages on publish, `GET PROTO` / `GET PROTOBUF` to read top-level fields, and `PUBLISH MODEL` to emit real protobuf bytes (not JSON-in-bytes). `WITH FORMAT BOTH` keeps JSON on the main topic and binary on a `/protobuf` sidecar topic.

See [Protobuf Models](/latest/lot-language/models/protobuf) for more details.

**2.0**

April–June 2026

### 2.0.3 - OT tags & route stability

* **OT tag JSON publish** — Message payload now includes the `unit` field
* **Modbus and EthernetIP routes** — Stability improvements

### 2.0.2 - ON CHANGE trigger and bug fixes

* **`ON CHANGE` trigger for LoT actions** — Run actions only when the message payload on a topic is different from the last message on that same topic. Use it for high-frequency telemetry, historians, and forwarding when you do not need to process duplicate values; `ON TOPIC` still runs on every matching publish.
* **Bug fixes** — Stability and correctness improvements across the broker, LoT, and HUB

### 2.0.0 - AI Agent route in the broker

* **AI Agent route** — Create custom agents usable within LoT for AI-driven steps and logic
* **Cloud and local LLMs** — Support for both on AI features

**1.10**

March 2026

### 1.10.0 - Protobuf & REST API route

Support for environment variables and secrets on LoT

* **Protobuf** support
* **REST API route** with OAuth and JWT support
* **Default project on boot** — Load a default project to a Coreflux broker when the broker starts

**HUB**

**2.12**

September–October 2026

### 2.12.0 - Things, Agents, certificates, fleet sign-in, and Cluster Viewer

This release brings the new broker features into the HUB: build and monitor Things and Agents, manage certificates and licenses without leaving the app, sign in with your Coreflux account, and see your cluster at a glance.

#### Highlights

* **Build and watch Things and Agents in the HUB** — Edit them in the LoT Editor, see how they connect in LoT Flow, and turn an action, connector, or agent off without deleting it. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Renew certificates from the app** — Replace the server certificate, trust or revoke a client, and see what is about to expire, without a restart or a shell. See [Certificates](/hub/system/certificates).
* **Open the brokers in your organization** — Sign in with a Coreflux account and connect to your fleet from the login screen. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Activate and enroll without leaving the HUB** — Paste an activation code or a signed license, or enroll the broker in your organization. See [License](/hub/system/configuration#license).
* **See the cluster from the host you already opened (Beta)** — Members, the leader, which links are up, which node owns each piece of LoT, and the clients on each node. See [Cluster Viewer](/hub/cluster-viewer).
* **Start from a template or a public git repo** — Install a Coreflux template as a project, or copy a public repository into the LoT Editor. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Hear live audio and wait on a button** — Data Viewer plays a raw audio topic. A dashboard button stays busy until the work it started finishes. See [Listening to PCM audio](/hub/mqtt/data-viewer#listening-to-pcm-audio).

#### Things and Agents (preview)

* **Things in the LoT Editor** — Deploy THING cells as one payload, checked first with `-addThing --dryRun`. **Broker runtime → Things** lists roots, instances, and their read-only entities, and **Flow preview** draws the notebook's Things. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Things, Tree, and Flat views in LoT Flow** — Switch views to drill into one level at a time, see the whole containment tree, or see everything flat. Panel cards expand into live previews, and the sidebar adds **Agents** and **Things** groups (collapsed at first). See [Things, Tree, and Flat views](/hub/lot-flow#things-tree-and-flat-views).
* **Agent configuration form** — **Configure** and **Add agent** open a form with **Configuration**, **Tools**, and **LoT** tabs. It rewrites only the clauses you change and keeps the rest as written. See [Configure an agent](/hub/ai-assistant#configure-an-agent).
* **Enable and disable** — Switch an action, connector, or agent off and on from its LoT Editor cell, connector card, or agent card. The HUB adds or removes `DISABLE true` and redeploys. The connector Monitor also has **Start** / **Stop**. Disabled cards are dimmed and marked **Disabled**. See [Disable an entity](/hub/lot-editor#disable-an-entity).

#### Certificates and security

* **Certificates tab** — A new System Config tab shows the server certificate and Root CA and replaces them without a restart. It also sets the trust store path and expiry alert, and uploads, searches, and revokes client certificates. Needs broker 2.22. See [Certificates](/hub/system/certificates).
* **Safer uploads** — The client drop zone accepts `.crt`, `.pem`, `.cer`, `.der`, `.p12`, and `.pfx`, and refuses keys and CSRs. Install a server key with **Replace** on the broker certificate.
* **Status bar indicator** — A certificate count with a red, yellow, or green dot. Hover for details, or click to open the tab filtered to certificates that need attention.

#### Account, fleet, and license

* **Sign in with Coreflux** — The login screen adds a **Coreflux Fleet** tab next to **This machine**. The desktop HUB signs in with no setup; a browser HUB needs `COREFLUX_OIDC_CLIENT_ID`, `HUB_PUBLIC_URL`, and `HUB_SESSION_SECRET`. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Fleet brokers** — Read-only rows for your organizations' brokers, with status, license, and **Cloud** / **Self-hosted** badges. **Connect** uses your account; portal actions open [portal.coreflux.org](https://portal.coreflux.org).
* **Cloud mode** — Set `HUB_CLOUD_MODE` on a shared regional HUB to accept only `mqtts://` brokers in `HUB_CLOUD_BASE_DOMAIN`. Leave it unset on desktop and self-hosted installs.
* **License tab** — Paste a `CFLX-…` code to activate, or drop a signed `.jws` file bound to the hardware fingerprint. Limits apply without a restart, and **Refresh** renews the lease. The tab doesn't start a trial.
* **Organization enrollment** — Paste an `et_…` token to enroll. The card shows **Enrolled**, **Not enrolled**, or **Enrollment pending** with the broker's reason. See [System Configuration — License](/hub/system/configuration#license).
* **MCP tab** — System Config → **MCP** turns on the broker's MCP listener, limits its tools, and creates or revokes tokens. See [System Configuration — MCP](/hub/system/configuration#mcp).

#### AI Assistant

* **Choose who answers** — Pick the HUB assistant, which calls the broker over MCP and asks before every write, or any `DEFINE AGENT` marked visible in the HUB. Installing on the broker creates a `TYPE LLM` connector and a `DEFINE AGENT`; legacy `TYPE AGENT` connectors are not listed or migrated. See [AI Assistant](/hub/ai-assistant).
* **Ollama works out of the box** — The assistant sizes Ollama's context per run (`HUB_OLLAMA_MIN_CTX` 16k to `HUB_OLLAMA_MAX_CTX` 32k), so the 4k default no longer truncates prompts. A silent model ends with a clear error after `HUB_AGENT_FIRST_OUTPUT_TIMEOUT_MS` or `HUB_AGENT_IDLE_TIMEOUT_MS` (120 s). See [Ollama requirements](/hub/ai-assistant#ollama-requirements).

#### Cluster Viewer (Beta)

* **See your cluster** — A read-only **Cluster** app shows members, the leader, data-plane links, LoT ownership, and partitions. It appears only while the host publishes cluster status. See [Cluster Viewer](/hub/cluster-viewer).
* **Clients tab** — Lists the MQTT clients on each node with user, address, traffic, last activity, queued messages, and session expiry. Filter, sort, and show the cluster's own connections on request. See [Cluster Viewer — Clients](/hub/cluster-viewer#details).

#### LoT Templates

* **Start from a template** — **Help → LoT Templates**, or **From a template…** in the LoT Editor, browses [templates.coreflux.org](https://templates.coreflux.org) and previews a template before installing it as a project. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Clone from git** — **＋ New → From git…** copies a public git repository into a new LoT Editor project. Cloning copies files only: it does not load or deploy the project. The HUB does not accept private credentials. The clone stops after 30 seconds, the whole repository becomes the project root, and a project download above 64 MB is refused. See [Clone from git](/hub/lot-editor#clone-from-git).

#### Connections

* **Generic MQTT brokers** — On a broker that isn't Coreflux, the dock keeps **Data Viewer** and **UNS Viewer** and hides Coreflux apps. Saved cards are tagged **MQTT** or **Coreflux**. See [When the broker is not Coreflux](/hub/connections#when-the-broker-is-not-coreflux).
* **Default connection** — In the web HUB, `HUB_DEFAULT_CONNECTION_HOST` and optional `HUB_DEFAULT_CONNECTION_*` variables pre-fill **New Connection**. Every browser receives the password, so use shared demo credentials only. See [Default connection (web / Docker)](/hub/connections#default-connection-web-docker).

#### Data Viewer and dashboards

* **Audio topics** — Raw PCM topics, such as an [Audio Input](/latest/lot-language/routes/media/audio-input) stream, show a live waveform you can play, clip, export to WAV, and scrub. See [Data Viewer](/hub/mqtt/data-viewer).
* **Busy buttons and markdown text** — A button with `SET AWAIT` stays busy, and each named component shows a pending indicator until its next message. The wait is 120 seconds unless `SET AWAIT_TIMEOUT` says otherwise, and then the panel shows a timeout note. `SET MARKDOWN true` on a text component renders sanitized markdown: no raw HTML, images, or unsafe links. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button).
* **Own window** — **Open in a new window** opens the Data Viewer on the current broker. See [Open the viewer in its own window](/hub/mqtt/data-viewer#open-the-viewer-in-its-own-window).
* **Panels grid** — A toggle in the Panels header switches to a grid of live dashboard thumbnails. The list stays the default. See [Managing Panels](/hub/dashboards/manager#managing-panels).

#### Desktop and settings

* **Desktop shell** — Click the logo to show the desktop. The account pill groups **Broker** administration, **Hub** (Themes and Hub Settings), and **Help**. See [Desktop shell](/hub/overview#desktop-shell).
* **Dock and status bar** — Right-click to set the dock position and auto-hide, and double-click a title bar to zoom. The same controls are in **Hub Settings → Desktop**. See [Dock and status bar](/hub/overview#dock-and-status-bar).
* **Hub Settings** — Memory limits, viewer refresh, and video wallpaper moved from System Config to **Hub Settings**. See [Hub Settings](/hub/overview#hub-settings).
* **Install and update** — Install the browser HUB as an app from `localhost` or HTTPS. The installed desktop app updates itself. See [Updating Your Coreflux](/latest/updating-coreflux#hub-desktop).
* **Walkthroughs** — Short tours on first launch and on each app's first open. Replay or reset them from **Help → Walkthroughs**. See [First-run walkthroughs](/hub/overview#first-run-walkthroughs).

#### Bug fixes

* **Maps show streets again** — Geolocation maps in the Data Viewer use keyless OpenStreetMap tiles, darkened in the dark theme, with the attribution **© OpenStreetMap contributors**. A build can set `VITE_CARTO_BASEMAPS_KEY` to use CARTO Dark Matter, or `VITE_MAP_TILE_URL` and `VITE_MAP_TILE_ATTRIBUTION` for another tile source. See [Tracking what matters](/hub/mqtt/data-viewer#tracking-what-matters).

**2.3**

August–September 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.3.4 - Login, Deploy, and Data Viewer fixes

#### Bug fixes

* **Non-admin users no longer get bounced back to the login screen** — Signing in as a user without full system access could loop back to login instead of opening the HUB in Limited Mode. The HUB now recognizes a denied `$SYS` subscription for what it is and opens Limited Mode as designed.
* **Deploy project shows accurate status** — Deploying a project via [Connections Manager](/hub/connections) no longer surfaces the broker's success response as a false warning, and the project header no longer gets stuck on **Updating** after the deploy completes.
* **LoT Editor keeps dropped files on the project** — Images and other files dropped into a project (from the Finder, Explorer, or a mixed-OS drag) now stay attached instead of being lost.
* **Data Viewer confirms whether a publish actually landed** — Sending a message no longer shows **Published** when the broker silently rejected it for lacking a publish ACL; Data Viewer now waits for the topic echo before confirming.

### 2.3.0 - LoT Editor, Connections Manager, LoT Flow wiring

#### LoT Editor

* **Visual Studio Code-style editor** — An intuitive notebookeditor with a familiar interface inside the HUB.
* **Unified Projects view** — One Projects list covering every project stored on the broker and every draft held in the HUB. The live project is marked, local-only drafts stay distinct, and each row carries its own sync state: clean, unsaved edits, changed on the broker, or diverged.
* **Push only what changed** — Push stores the working copy and deploys just the drift, instead of redeploying a whole project.
* **Broker Runtime inspector** — A table of what is actually running on the broker, with read-only source for each entity, and a jump from any running entity to the notebook that declares it.
* **Documents alongside notebooks** — Open and store Markdown, text, PDF, and images in a project, import files from disk, and reference them in LoT notebook cells.
* **Copy entities between notebooks** — Copy or drag a declared or deployed entity into another notebook.
* **Version history** Git based version control for project files.
* **Activate and Deactivate projects** from the project tree.

#### Connections Manager

* **More than one broker** — The HUB keeps a named list of broker connections with favorites, replacing the single remembered URL. Each is shown as a card on the login screen.
* **Change Broker** — Switch the whole HUB to another saved connection from the account menu, without logging out and reconfiguring.
* **Per-connection TLS** — Store a CA certificate and a client certificate against an individual connection.
* **Credentials kept off the connection record** — Passwords and client keys live in a separate store; the desktop app encrypts it using the operating system's secure storage, and the browser app never writes them to disk.
* **Live reachability on the login list** — Saved connections are probed so you can see which brokers answer before you pick one.

#### LoT Flow

* **Cleaner connections between nodes** — `KEEP`-topic edges and "matches" edges no longer clutter the canvas, and `MODEL` nodes are drawn as terminals, so the remaining edges show real data flow.
* **Topics grouped by role** — Command and telemetry topics are grouped by the role they play, with disambiguated group labels, prefix hubs backed by a topic-set panel, and wildcard subscriptions expanded to the topics they match.
* **Topic pulse toggle** — Turn live topic activity animation on or off.
* **Export the canvas as an image** — Download the current flow as a PNG.

**2.2**

July 2026

### 2.2.0 - UNS viewer & LoT Flow

* **LoT Flow** — A new interactive view of your LoT data flows, showing entity, topic, and Python nodes alongside live topic values, action traces, and route status.
* **UNS viewer** — Browse your Unified Namespace as a tree, with search, live payload previews, and a graph layout.
* **Data Viewer overhaul** — A refreshed explorer with a detailed topic view, timeline, faster topic indexing, and better subscription management.
* **In-app release notes** — A "What's New" dialog in the HUB so you can see what's changed without leaving the app.
* **Refreshed HUB styling** — Updated visual design and dock layout.
* **AI chat improvements** — A setup wizard, an artifact panel, and a generally expanded chat experience.
* **Expanded dashboard panels** — More display components, gauge options, and model-binding support for building richer dashboards.
* **Bug fixes** — Fixed the LoT compiler and dashboard rendering for `ON KEY PRESS`, `ON THRESHOLD BREACH`, conditional handlers, `WITH THEME`, numeric decimals and suffixes, threshold zones on gauges/charts, and callable actions. Fixed `INVOKE ACTION`, `BIND TO MODEL`, the accordion "Add Section," and tab titles in dashboards. Fixed real-time charts to show both traces with a legend and to correctly distinguish bar vs. line modes. Fixed select/dropdown interactions, topic-to-widget data binding (previously showing a single point instead of the full array), slider and toggle controls publishing incorrect values, icon visibility, multi-panel layouts, and events not being recognized on mount. Fixed the AI agent to properly detect uninstalled routes, and corrected its confirmation prompts. General mobile layout improvements.

**2.0**

April 2026

### 2.0.0 - UI/UX overhaul, standalone installer, AI Agent

![Coreflux HUB Data Viewer showing MQTT topic tree with live data values and real-time charts](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/hub-data-viewer.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=634b8986391a76e82ef3f03574338cb6)

Coreflux HUB Data Viewer with live MQTT topic data and charts

* **UI/UX improvements**
* **Standalone installer** — Windows and Linux
* **AI Agent**
  * **Insights mode** — Ask questions about running data, using project information as context
  * **Agent mode** — Build LoT, routes, and dashboards with an AI copilot

**VS Code Extension**

**1.0**

August–October 2026

These notes are VS Code extension **1.0**. Features that use the broker's new commands need broker **2.22**.

### 1.0.0 - Things, Agents, Validate, MCP, and licensing

This release lets you write Things and Agents in notebooks, check your LoT on the broker before deploying, connect your AI tools to the broker's MCP server, and manage licensing, all from VS Code.

#### Highlights

* **Write Things and Agents where you already write LoT** — Check them against the broker and deploy them from the notebook, the same way as any other cell. See [THING cells](/lot-notebooks/usage#thing-cells).
* **Check before you deploy** — Validate a cell or the whole notebook on the broker. Problems show on the cell, and nothing is deployed until you run it. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Switch a cell off without deleting it** — Disable an action, connector, or agent from the cell status bar, and turn it back on when you want it running. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **Connect your AI tools in one step** — The MCP Server tab writes the broker endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Teach your coding agent LoT** — Install the Coreflux skills so the agent writes valid LoT and works with the broker. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **License and enroll from VS Code** — Activate with a code, install a signed license, or enroll the broker, from the License tab. See [License tab](/lot-notebooks/usage#license-tab).

#### LoT cells

* **Things** — A run sends the cell's `DEFINE THING` blocks and their workspace templates as one `-addThing`, after a `--dryRun` whose problems show on the cell. **Remove Thing from Broker** sends `-removeThing`, and a quick fix updates older THING syntax (`TEMPLATE`, and `{p}` to `{{p}}`). See [THING cells](/lot-notebooks/usage#thing-cells).
* **Agents** — `DEFINE AGENT` cells are checked like the broker checks them and deploy with `-addAgent`. Broker agents appear in the Coreflux Explorer and the Entities panel. See [Agent cells](/lot-notebooks/usage#agent-cells).
* **Validate** — Check a cell or the whole notebook on the broker without deploying it. Results appear under the cell and in Problems. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Enabled / Disabled toggle** — Switch `DISABLE true` on and off for action, connector, and agent cells from the cell status bar, and the change uploads. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **`DEFINE CONNECTOR`** — Recognized in checks, completions, and hovers, with `DEFINE ROUTE` as its alias. Connector cells upload from the cell, and Deploy Project includes them.
* **`RETURN AS` under `CALL`** — A `RETURN AS` line under a `CALL` no longer reports an indentation error.
* **Panels and themes** — `DEFINE PANEL` and `DEFINE VISU` cells, and a Thing's `WITH PANEL` body, are checked with the broker's panel parser. Highlighting, hover, completions, and a `DEFINE PANEL` snippet are included. Running the cell sends `-addVisu`; removing it sends `-removeVisu`. `DEFINE THEME` and `THEME_VARIANT` are recognized. The cell status bar offers **Open in Coreflux HUB** to view the rendered panel, and a successful upload suggests opening Dashboards there. See [Panel cells](/lot-notebooks/usage#panel-cells).
* **Agent and Thing checks match the broker** — Valid agent, thing, rule, connector, and model syntax is no longer flagged, including connector keys such as `SUBJECT` and mixed-case names. See [Agent cells](/lot-notebooks/usage#agent-cells).

#### Broker management

* **License tab** — Activate with a `CFLX-…` code, install signed license text, enroll with an `et_…` token, and refresh the lease. The Instance Key field is gone. See [License tab](/lot-notebooks/usage#license-tab).
* **MCP Server tab** — Turn on the broker's MCP server, pick its tools, and manage tokens. **Install MCP server** writes the endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop, and keeps workspace config files out of Git. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Install Agent Skills** — **Install Agent Skills...** lets you pick which of the 11 bundled skills to install and where (the `.agents`, `.claude`, `.cursor`, or `.github` skills folder, in the workspace or your home folder). Skills come from the public [coreflux-skills](/ai/agent-skills) repository (broker 2.22 or later), and older copies from previous versions are offered for removal. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **Remove All Things / Templates** — Two new commands clear every Thing or every template from the broker.
* **Variables** — "Environment Vars" is now "Variables" everywhere, including **Secrets & Variables**.

#### Data Viewer and workspace

* **Bounded history** — Each topic keeps its last 100 messages by default (`coreflux.dataViewer.historyBufferPerTopic`, 50 to 2000), set from the timeline gear. The timeline draws again, and pausing or scrubbing stays steady while messages arrive. See [Adjust how you see the data](/lot-notebooks/debug#adjust-how-you-see-the-data).
* **Apps in the editor area** — Data Viewer, Logs Viewer, and Secrets & Variables open as tabs next to your notebooks.
* **Connection Manager** — Save several broker connections and switch between them.
* **Entities table** — See the LoT entities running on the broker in their own table.
* **LoT projects** — Create, edit, and deploy LoT projects.

**beta**

April 2026

![Screen recording of creating and deploying LoT in the Coreflux VS Code extension](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-and-deploy-lot.gif?s=5cd139e03cbf0b5109848b498d7c65eb)

Create and deploy LoT from the Coreflux VS Code extension

* **Improved VS Code extension (beta)**
  * License usage
  * Live MQTT data (topic tree)
  * **Data Viewer** — View and replay historical and live data for MQTT topics, with viewers for raw, JSON, PDF, GeoJSON (map), audio, and more
  * **Execution trace** — View and replay historical and live data from LoT execution, including success and error states, published topics, and internal variables
  * Manage secrets and environment variables


# AI-Assisted Development Best Practices
Source: https://docs.coreflux.org/ai/best-practices

Set up your AI coding assistant to generate correct, consistent LoT code using AGENTS.md templates and project rules

## Make Your AI Assistant a LoT Expert

AI coding assistants — in Cursor, VS Code with Copilot, or Claude — can generate excellent LoT (Language of Things) code when they know your project's conventions. The key is giving them the right context upfront through an **AGENTS.md** or project rules file.

This page shows you how to set up that context so your assistant produces LoT code that matches your team's standards from the first prompt.

> [!TIP]
>
> **Like a style guide that your co-pilot actually reads.** Just as a design system keeps a UI consistent across 10 developers, a project rules file keeps your LoT code consistent across humans and AI assistants alike.

### When to Use This

* You want your **AI assistant to generate correct LoT code** without constant corrections
* You're setting up an **AGENTS.md**, `.cursor/rules/`, or `CLAUDE.md` file for your project
* You're onboarding **new team members** (human or AI) and need a single reference
* You're starting a **new Coreflux project** and want AI-ready conventions from day one

> [!NOTE]
>
> This page focuses on **AI assistant configuration**. For the underlying conventions, naming rules, topic architecture, code patterns, and anti-patterns, see [Naming conventions](/latest/lot-language/usage-patterns/naming-conventions), [Working with JSON](/latest/lot-language/usage-patterns/working-with-json), [Designing your data layer](/latest/lot-language/usage-patterns/data-layer), and [Anti-patterns](/latest/lot-language/usage-patterns/anti-patterns) — those standards are the foundation for everything below.

***

## Setting Up Your AI Assistant

An **AGENTS.md** file (or equivalent project rules file) tells your AI assistant how to work with your Coreflux project. It prevents the assistant from generating code with wrong naming, invented syntax, or inconsistent patterns. The conventions defined in [Naming conventions](/latest/lot-language/usage-patterns/naming-conventions) form the content — the structure below tells you how to organize them for your assistant.

### What Is an AGENTS.md?

An AGENTS.md is a markdown file in your project root that AI coding assistants read automatically. It works across tools:

| File / Location | Supported By |
| - | - |
| `AGENTS.md` (project root) | Cursor, GitHub Copilot, OpenAI Codex, Google Jules, Aider |
| `.cursor/rules/*.mdc` | Cursor (native format with glob pattern support) |
| `CLAUDE.md` (project root) | Claude Code |
| `.github/copilot-instructions.md` | GitHub Copilot |

For maximum compatibility, use **AGENTS.md** in your project root. If you use Cursor extensively, you can also maintain `.cursor/rules/` files for features like auto-attaching rules to specific file types.

### The Three-Tier Boundary System

The most effective structure for preventing AI mistakes is a **three-tier permission system**. Define what the assistant should always do, what it should ask about first, and what it should never do:

| Tier | Guideline | LoT Examples |
| - | - | - |
| **Always do** | Follow without asking | Use PascalCase for entities, `snake_case` for variables, `lot` language tag for code blocks |
| **Ask first** | Confirm before proceeding | Adding new Connectors (external connections), modifying Rules (access control), removing Actions |
| **Never do** | Refuse even if asked | Invent LoT syntax that doesn't exist, use `LOT` or `lot` capitalization, mention competitor broker products |

### Starter Template

The following template incorporates the conventions from [Naming conventions](/latest/lot-language/usage-patterns/naming-conventions) and related pattern pages. Copy it into an `AGENTS.md` file at your project root and customize the project-specific sections:

> [!TIP]
>
> **Prefer to grab it from GitHub?** The [Coreflux AI Starter](https://github.com/CorefluxCommunity/coreflux-ai-starter) repository has ready-to-use templates (minimal, full, and industrial), pre-built MCP configs for every editor, and filled-in examples you can clone directly.

> [!NOTE]
>
> AGENTS.md is for **your project's** conventions. For LoT syntax and broker workflows, install the [Coreflux agent skills](/ai/agent-skills) (broker 2.22 or later) instead of pasting reference material into the file.

**AGENTS.md**

A cross-platform template that works with Cursor, Copilot, Claude, and other AI tools:

```markdown wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# AGENTS.md

## Project Overview
This is a Coreflux LoT (Language of Things) project for [describe your system].
Built on the Coreflux MQTT broker with LoT Actions, Models, Rules, and Connectors.

## Tech Stack
- **Platform:** Coreflux MQTT Broker
- **Language:** LoT (Language of Things)
- **Extensions:** Python integration (for complex logic only)
- **IDE:** VS Code with LoT Notebooks extension / Cursor

## LoT Naming Conventions
- **Actions:** PascalCase, verb-first (ProcessTemperature, MonitorPressure)
- **Models:** PascalCase, noun-based (SensorReading, EquipmentStatus)
- **Rules:** PascalCase, descriptive scope (AllowAdminActions, ProtectSysTopics)
- **Connectors:** PascalCase, destination-based (CloudBridge, SensorDatabase)
- **Variables:** snake_case in quotes ("sensor_id", "raw_value")
- **Topics:** lowercase/slash-separated (sensors/+/temperature, alerts/critical/+)
- **Model fields:** snake_case ("equipment_id", "runtime_hours")

## Topic Hierarchy
- sensors/    — Raw incoming data
- processed/  — Transformed data
- alerts/     — Threshold violations
- config/     — Configuration values
- state/      — Internal persistent state (KEEP TOPIC)
- cache/      — Cached values
- system/     — Heartbeats and diagnostics
- commands/   — Inbound instructions

## Code Standards
- Always type-cast in calculations: PAYLOAD AS DOUBLE, GET TOPIC ... AS DOUBLE
- Use KEEP TOPIC for internal state, PUBLISH TOPIC for external broadcast
- Mark the primary data field AS TRIGGER in models — never timestamps
- Use COLLAPSED models when Actions need control over publish timing
- Break complex Actions into callable Actions with INPUT/OUTPUT
- Use LoT for publish, subscribe, conditionals, math — Python only for
  ML, complex parsing, or external library calls

## Do
- Always respect the indentation of 4 spaces per additional level
- Use PascalCase for all entity names
- Use snake_case for all variables and model fields
- Add type casts to every numeric operation
- Use descriptive names that explain purpose
- Use lot as the code block language identifier
- Booleans and integers do not use quotes
- Consult the Coreflux MCP for documentation when unsure
- Connectors that call functions from other protocols (like SQL queries) are not limited to the functionalities listed in this documentation, the full range of that external element is usually functional

## Don't
- Do not invent LoT syntax — only use documented keywords
- Do not use LOT (all caps) or lot (lowercase) — always LoT
- Do not mention competitor products (Mosquitto, HiveMQ, etc.)
- Do not trigger models on timestamp fields
- Do not use PUBLISH for internal-only state
- Do not create monolithic Actions — split into callables

## Ask First
- Before adding or modifying Connectors (external system connections)
- Before modifying Rules (access control changes)
- Before removing any existing Action, Model, Rule, or Connector
- Before using Python — confirm LoT can't handle it natively first

## Never
- Never hardcode credentials in Connector definitions for production
- Never leave $SYS/# topics unrestricted
- Never skip type casting in mathematical operations
- Never generate LoT syntax you haven't verified in the documentation
```

**Cursor Rules (.mdc)**

For Cursor-native rules, create `.cursor/rules/lot-conventions.mdc` in your project:

```markdown wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
---
description: LoT development conventions for Coreflux projects
globs: ["*.lot", "*.lotnb", "*.md"]
---

# LoT Conventions

You are an expert LoT (Language of Things) developer for Coreflux.

## Naming
- Actions: PascalCase, verb-first (ProcessTemperature)
- Models: PascalCase, noun-based (SensorReading)
- Rules: PascalCase, descriptive (ProtectSysTopics)
- Connectors: PascalCase, destination-based (CloudBridge)
- Variables: snake_case in quotes ("sensor_id")
- Topics: lowercase/slash-separated (sensors/+/temperature)

## Code Rules
- Always type-cast: PAYLOAD AS DOUBLE, GET TOPIC ... AS DOUBLE
- KEEP TOPIC for internal state, PUBLISH TOPIC for broadcast
- AS TRIGGER on primary data field, never timestamps
- Use COLLAPSED models when Actions control publish timing
- Use lot as the language tag for code blocks
- Python only for ML, complex parsing, or external libraries

## Prohibited
- Do not invent LoT syntax beyond documented keywords
- Do not use LOT or lot — always LoT
- Do not mention competitor MQTT brokers
- Do not create monolithic Actions — split into callables
```

### Keeping It Effective

The best project rules files share these qualities:

| Quality | Why It Matters |
| - | - |
| **Specific** | "Use PascalCase for Actions" beats "use good naming" |
| **Example-driven** | One code snippet beats three paragraphs of description |
| **Iterative** | Start small, then add rules when you see the AI make a mistake |
| **Current** | Update the file as your project conventions evolve |
| **Concise** | A 50-line focused file outperforms a 500-line generic one |

> [!WARNING]
>
> Do not include credentials, API keys, or sensitive connection strings in your AGENTS.md or rules files. These files are typically committed to version control.

***

## Quick Reference Checklist

Use this checklist when reviewing LoT code — whether written by you or generated by an AI assistant:

* [ ] All entity names are **PascalCase** and descriptive
* [ ] All variables and model fields are **snake\_case**
* [ ] All topics are **lowercase with slash separators**
* [ ] All numeric operations include **explicit type casts** (`AS DOUBLE`, `AS INT`)
* [ ] Models trigger on **primary data fields**, not timestamps
* [ ] Internal state uses **`KEEP TOPIC`**, not `PUBLISH TOPIC`
* [ ] Complex logic is split into **callable Actions** with `INPUT`/`OUTPUT`
* [ ] Rules use **permission tags** (`USER HAS`) over user names (`USER IS`)
* [ ] Python is used only where **LoT can't handle the task natively**
* [ ] `$SYS/#` access is left to the broker's **locked built-in Rules** — no permission flags granted to device or operator accounts
* [ ] Custom Rule priorities sit in the **user band** (`100`–`1 000 000`), with broad rules high and specific carve-outs near `100`

***

## Next Steps

> **[Coreflux MCP](/ai/mcp)**
>
> Connect your AI assistant to the Coreflux documentation for real-time syntax help and guided answers.

> **[Working with JSON](/latest/lot-language/usage-patterns/working-with-json)**
>
> GET JSON patterns and structured output with Models.


# Developing with LoT Using AI
Source: https://docs.coreflux.org/ai/developing-with-lot

A beginner's guide to building IIoT solutions with LoT — let your AI assistant handle the syntax while you focus on what to build

## Build IIoT Solutions Without Memorizing a Single Command

You don't need to be a LoT (Language of Things) expert to build industrial IoT solutions with Coreflux. With an AI assistant connected to the Coreflux MCP, you describe **what** you want in plain English, and the AI writes the LoT code for you — correctly, following best practices, using real syntax from the official documentation.

This page walks you through the entire workflow: from setting up the MCP connection to deploying a working IIoT feature, using only natural language prompts. Whether you're monitoring factory temperatures, logging production data to a database, or bridging sensor networks to the cloud — the process is the same.

> [!TIP]
>
> **Like dictating a blueprint to an expert architect.** You describe the building you want — "a sensor system that alerts when temperatures spike" — and the architect draws up structurally sound plans, handles the engineering codes, and hands you something ready to build.

### When to Use This Guide

* You're **new to Coreflux** and want to build something real without learning LoT syntax first
* You have an **AI coding assistant** (Cursor, Claude, Copilot) and want to use it effectively for IIoT
* You want a **step-by-step walkthrough** of the AI-assisted development workflow
* You're exploring whether Coreflux fits your **industrial automation** or **IoT data pipeline** needs

***

## Prerequisites

Before starting, make sure you have:

| Requirement | Details |
| - | - |
| **Coreflux Broker** | Installed and running. See the [Installation Guide](/latest/quick-start/installation) |
| **AI Assistant with MCP** | Cursor, Claude Desktop, Claude.ai, or VS Code with Copilot — connected to the Coreflux MCP |
| **MQTT Client** | MQTT Explorer or any MQTT client for verifying results |

> [!NOTE]
>
> If you haven't connected the Coreflux MCP to your AI assistant yet, follow the [MCP Setup Guide](/ai/mcp#setup) first. It takes under 5 minutes. To give the assistant LoT knowledge up front, also install the [Coreflux agent skills](/ai/agent-skills) (broker 2.22 or later).

You do **not** need prior experience with LoT syntax, MQTT, or industrial protocols. The AI assistant handles the technical details — you focus on describing your goals.

***

## The AI-Assisted Workflow

Every AI-assisted Coreflux project follows three phases. This isn't a suggestion — it's the workflow that consistently produces working results.

| Phase | You Do | The AI Does |
| - | - | - |
| **1. Plan** | Describe the feature in plain English | Asks clarifying questions, proposes an architecture |
| **2. Build** | Review and approve the AI's output | Writes LoT code using the MCP for accurate syntax |
| **3. Verify** | Test the result in MQTT Explorer | Explains what to check and helps debug issues |

The key insight is that **you are the domain expert** and **the AI is the LoT expert**. You know your factory floor, your sensor layout, your business rules. The AI knows the syntax, the patterns, and the best practices. Together, you build faster than either could alone.

***

## Phase 1: Plan Your Feature

The most important step happens before any code is written. A clear plan gives the AI the context it needs to produce working LoT code on the first try.

### Describe Your Goal, Not Your Code

Tell the AI **what** you want to achieve, not **how** to write it. Let it choose the right LoT building blocks.

> [!TIP]
>
> The more specific you are on the components you are working with (for example: hardware brands, specific protocols,  IP addresses, ports, etc.), the better the end result will tend to be.

**Good Prompt**

A clear, goal-oriented description that gives the AI enough context to make architectural decisions:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
I have temperature sensors from brand Y, using ModBus, publishing readings to MQTT topics like 
sensors/temp001/reading as JSON: {"value": 23.5, "unit": "celsius"}.

I want to:
1. Monitor these readings and trigger an alert when temperature exceeds 75°C
2. Store all readings in a PostgreSQL database
3. Convert Celsius to Fahrenheit and publish the converted value

The alert should publish to an alerts/ topic with the sensor ID and the value.
```

**Bad Prompt**

A vague prompt that forces the AI to guess about critical details:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Make me a temperature action.
```

This tells the AI nothing about your topic structure, thresholds, data format, or what you want to happen. The result will be generic at best.

### The Planning Checklist

Before you prompt your AI assistant, gather answers to these questions. You don't need to answer all of them — but the more you provide, the better the result.

| Question | Why It Matters | Example Answer |
| - | - | - |
| **What data comes in?** | Defines the trigger topics and payload format | `sensors/+/reading` with JSON `{"value": 23.5}` |
| **What should happen to it?** | Determines which LoT building blocks to use | Transform, alert, store, forward |
| **Where should results go?** | Defines output topics, databases, or external systems | PostgreSQL table, alert topic, cloud broker |
| **What are the thresholds or rules?** | Sets up conditionals in Actions | Alert when temp > 75°C |
| **How many sensors/devices?** | Affects topic structure and wildcard usage | 50 sensors, each with a unique ID |

> [!TIP]
>
> You can share this checklist directly with the AI. Paste it into your prompt and fill in the answers — the AI will use them to design the complete system.

### Ask the AI to Propose an Architecture

Once you've described your goal, ask the AI to **plan before coding**. This avoids wasted iteration.

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Before writing any code, propose an architecture for this system. 
Tell me which LoT building blocks you'll use (Actions, Models, Connectors, Rules) 
and why. List the MQTT topics you'll create.
```

The AI will consult the Coreflux MCP documentation and respond with something like:

> *"For this system, I recommend:*
>
> * *An **Action** to monitor temperatures and trigger alerts*
> * *A **Model** to structure sensor readings into consistent JSON*
> * *A **Connector** to store readings in PostgreSQL*
> * *A **callable Action** for the Celsius-to-Fahrenheit conversion (reusable)*
>
> *Topic structure: `sensors/+/reading` (input), `processed/+/fahrenheit` (converted), `alerts/temperature/+` (alerts)"*

Review this before saying "go ahead." It's much easier to adjust a plan than to rewrite code.

***

## Phase 2: Build with AI

Now let's walk through a complete guided demo. We'll build a **temperature monitoring system** that reads sensor data, converts units, triggers alerts, and logs to a database — all by prompting the AI.

### Step 1: Create the Core Logic (Actions)

Start with the Action that processes incoming data. Paste this prompt into your AI assistant:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Using the Coreflux MCP for reference, create a LoT Action called 
ProcessTemperature that:
- Triggers on topic "sensors/+/temperature" 
- Extracts the sensor ID from the topic
- Gets the temperature value from a JSON payload with key "value"
- If the temperature exceeds 75, publishes an alert to 
  "alerts/temperature/" followed by the sensor ID
- Publishes the reading to "processed/" followed by the sensor ID

Use proper LoT syntax with type casting.
```

The AI will consult the Coreflux documentation through the MCP and produce working LoT code. Here is what a correct result looks like:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ProcessTemperature
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {temp} > 75 THEN
        PUBLISH TOPIC "alerts/temperature/" + {sensor_id} WITH "HIGH TEMP: " + {temp} + "°C"
    PUBLISH TOPIC "processed/" + {sensor_id} WITH {temp}
```

> [!NOTE]
>
> The AI uses the MCP's `consult_documentation` and `consult_internal_documentation` tools behind the scenes to look up correct syntax. You don't need to tell it to use the MCP — it does this automatically when it detects a Coreflux-related question.

### Step 2: Add Unit Conversion (Callable Action)

Now ask the AI to add a reusable conversion utility:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Create a callable LoT Action called ConvertToFahrenheit that takes a Celsius 
value as input and returns the Fahrenheit equivalent. Then update 
ProcessTemperature to call it and publish the result to 
"processed/" + sensor ID + "/fahrenheit".
```

The AI will produce two connected Actions:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION ConvertToFahrenheit
INPUT celsius AS DOUBLE
DO
    SET "fahrenheit" WITH ({celsius} * 9 / 5 + 32)
RETURN
    OUTPUT fahrenheit

DEFINE ACTION ProcessTemperature
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {temp} > 75 THEN
        PUBLISH TOPIC "alerts/temperature/" + {sensor_id} WITH "HIGH TEMP: " + {temp} + "°C"
    PUBLISH TOPIC "processed/" + {sensor_id} WITH {temp}
    CALL ACTION ConvertToFahrenheit
        WITH celsius = {temp}
        RETURN temp_f
    PUBLISH TOPIC "processed/" + {sensor_id} + "/fahrenheit" WITH {temp_f}
```

### Step 3: Structure the Data (Model)

Ask the AI to create a Model that formats raw sensor readings into consistent JSON:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Create a LoT Model called TemperatureReading that publishes structured JSON 
to "sensors/formatted/temperature". It should include the sensor ID as a 
static string "TEMP001", the raw value from the sensor topic as the trigger, 
the unit as "celsius", and a UTC timestamp.
```

The result:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE MODEL TemperatureReading WITH TOPIC "sensors/formatted/temperature"
    ADD STRING "sensor_id" WITH "TEMP001"
    ADD DOUBLE "value" WITH TOPIC "sensors/raw/temperature" AS TRIGGER
    ADD STRING "unit" WITH "celsius"
    ADD STRING "timestamp" WITH TIMESTAMP "UTC"
```

### Step 4: Connect to a Database (Connector)

Now bring in a Connector to persist the data. Ask the AI:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Create a LoT Connector called SensorDatabase that stores temperature readings 
in a PostgreSQL database. It should:
- Connect to a PostgreSQL server at "db.example.com" port 5432
- Use database "iot_data" with user "iot_writer" and password "secure_pass"
- Insert readings from "sensors/+/temperature" into a table called 
  "temperature_readings" with columns: timestamp, sensor_id, and value

Use proper LoT connector syntax from the Coreflux documentation.
```

The AI generates:

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR SensorDatabase WITH TYPE POSTGRESQL
    ADD SQL_CONFIG
        WITH SERVER "db.example.com"
        WITH PORT '5432'
        WITH DATABASE "iot_data"
        WITH USERNAME "iot_writer"
        WITH PASSWORD "secure_pass"
    ADD EVENT StoreReading
        WITH SOURCE_TOPIC "sensors/+/temperature"
        WITH QUERY "INSERT INTO temperature_readings (timestamp, sensor_id, value) VALUES (NOW(), '{value.topic.2}', '{value.json.value}')"
```

### Step 5: Deploy Everything

Ask the AI how to deploy your code:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
How do I deploy all of these LoT definitions to my Coreflux broker? 
I'm using VS Code with the LoT Notebooks extension.
```

The AI will explain the deployment process:

**VS Code (LoT Notebooks)**

The recommended way to deploy LoT code is through the **LoT Notebooks** extension in VS Code or Cursor.

**1. Create a Notebook**

Create a new `.lotnb` file in your project. Each cell can contain one or more LoT definitions.

**2. Add Your Code**

Paste each definition into its own cell — this lets you deploy and test them individually.

**3. Run Each Cell**

Execute cells in order. The extension sends the LoT code to your connected Coreflux broker.

**4. Verify in MQTT Explorer**

Open MQTT Explorer and subscribe to `#` (all topics). Publish a test payload to `sensors/temp001/temperature` and watch the system respond.

**MQTT Client**

You can deploy LoT code by publishing directly to the broker's command topic using any MQTT client.

Publish to the topic `$SYS/Coreflux/Command` with the `-addAction` prefix followed by your LoT code:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
-addAction DEFINE ACTION ProcessTemperature
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    SET "temp" WITH (GET JSON "value" IN PAYLOAD AS DOUBLE)
    IF {temp} > 75 THEN
        PUBLISH TOPIC "alerts/temperature/" + {sensor_id} WITH "HIGH TEMP: " + {temp} + "°C"
    PUBLISH TOPIC "processed/" + {sensor_id} WITH {temp}
```

Use `-addModel` for Models and `-addConnector` for Connectors.

***

## Phase 3: Verify and Iterate

After deploying, test the system by publishing a simulated sensor reading.

### Test Your System

Open MQTT Explorer (or any MQTT client) and follow these steps:

**1. Subscribe to All Topics**

Subscribe to `#` to see all messages flowing through the broker.

**2. Publish a Test Reading**

Publish to `sensors/temp001/temperature` with this payload:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{"value": 82.3}
```

**3. Check the Results**

You should see messages appear on these topics:

| Topic | Expected Value | Source |
| - | - | - |
| `processed/temp001` | `82.3` | ProcessTemperature Action |
| `processed/temp001/fahrenheit` | `180.14` | ConvertToFahrenheit callable |
| `alerts/temperature/temp001` | `HIGH TEMP: 82.3°C` | Alert threshold exceeded |

**4. Test Below Threshold**

Publish to `sensors/temp001/temperature` with `{"value": 45.0}`. Verify that no alert is generated — only the processed and fahrenheit topics should update.

### When Something Doesn't Work

If the output isn't what you expect, describe the problem to the AI:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
I deployed the ProcessTemperature action, but when I publish 
{"value": 82.3} to sensors/temp001/temperature, I don't see 
any alert on alerts/temperature/temp001. What could be wrong?
```

The AI will consult the MCP documentation and help you debug — checking for type casting issues, topic mismatches, or deployment errors. **You don't need to debug LoT syntax yourself.** Describe the symptom, and the AI diagnoses the cause.

***

## Prompt Patterns That Work

After building dozens of IIoT features with AI, these prompt patterns consistently produce the best results.

### Pattern 1: Context → Goal → Constraints

Provide the situation, then state what you want, then add any constraints:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Context: I have 20 pressure sensors publishing to "sensors/pressure/+/psi" 
with numeric payloads.
Goal: Alert when any sensor exceeds 150 PSI and log all readings to a 
PostgreSQL table.
Constraints: Alerts must include sensor ID and timestamp. Use a single 
Action for monitoring and a Connector for database logging.
```

### Pattern 2: Ask for Explanation Before Code

When learning, ask the AI to explain its choices:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
I need to store sensor data in a database. Should I use a Connector or an Action 
for this? Explain the trade-offs, then show me the LoT code for the 
recommended approach. Use the Coreflux documentation for reference.
```

### Pattern 3: Incremental Building

Build complex systems one piece at a time rather than all at once:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Step 1: "Create an Action that reads temperature and publishes to a processed topic"
Step 2: "Now add an alert when temperature exceeds 75"
Step 3: "Add a Connector to store readings in PostgreSQL"
Step 4: "Create a Model to structure the data as JSON with sensor ID and timestamp"
```

Each step is small enough for the AI to get right, and you verify as you go.

### Pattern 4: Reference the MCP Explicitly

When you need maximum accuracy, tell the AI to consult the documentation:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Check the Coreflux documentation: what is the correct syntax for defining 
a Modbus TCP connector that reads holding registers from a PLC at 192.168.1.10?
Give me a complete LoT connector definition.
```

This triggers the AI to call `consult_documentation` or `consult_internal_documentation` through the MCP, ensuring the answer uses real, verified syntax.

***

## Common Pitfalls

These mistakes happen frequently when developers start using AI for LoT development. Knowing them upfront saves hours of debugging.

| Pitfall | Why It Happens | How to Avoid It |
| - | - | - |
| **Vague prompts** | AI fills in gaps with assumptions that may not match your system | Always specify topic structure, payload format, and thresholds |
| **Skipping the plan** | Jumping straight to "write me an Action" without context | Ask the AI to propose an architecture before writing code |
| **Not verifying output** | Trusting AI code without testing it | Always deploy and test with a sample payload in MQTT Explorer |
| **Prompting without MCP** | The AI invents plausible-looking but incorrect LoT syntax | Ensure the Coreflux MCP is connected — check your MCP settings |
| **Building everything at once** | One massive prompt produces code that's hard to debug | Build incrementally: one Action, one Model, one Connector at a time |
| **Ignoring type casting** | Numeric operations fail silently without `AS DOUBLE` or `AS INT` | Ask the AI to always include type casts — or review [Anti-patterns](/latest/lot-language/usage-patterns/anti-patterns) |

> [!WARNING]
>
> If your AI assistant is not connected to the Coreflux MCP, it may generate LoT-like code that **looks** correct but uses invented syntax. Always verify the MCP connection before starting a session. Check that the `consult_documentation` and `consult_internal_documentation` tools appear in your assistant's available tools.

***

## Expanding Your System

Once the basic monitoring system works, you can extend it with a single prompt each. Here are natural next steps:

| Feature | Example Prompt |
| - | - |
| **Email alerts** | *"Add a LoT email connector that sends an email when alerts/temperature/+ receives a message"* |
| **Cloud sync** | *"Create an MQTT bridge connector that forwards all processed/ topics to a cloud broker at cloud.example.com"* |
| **Industrial protocol** | *"Create a Modbus TCP connector to read holding registers 0-10 from a PLC at 192.168.1.50 every 5 seconds"* |
| **Access control** | *"Create a LoT Rule that only allows admin users to publish to config/ topics"* |
| **Data aggregation** | *"Create an Action that calculates a 5-minute rolling average of temperature readings"* |

Each of these is a single prompt that the AI can handle using the MCP documentation. The workflow is always the same: describe → review → deploy → verify.

***

## Next Steps

> **[Coreflux MCP Setup](/ai/mcp)**
>
> Haven't connected the MCP yet? Set up your AI assistant's connection to the Coreflux documentation in under 5 minutes.

> **[Best Practices & AGENTS.md](/ai/best-practices)**
>
> Level up your AI workflow with naming conventions, code patterns, and a project rules template that keeps your assistant consistent.


# Model Context Protocol (MCP)
Source: https://docs.coreflux.org/ai/mcp

Connect AI assistants to the Coreflux knowledge base using the Model Context Protocol

## The Bridge Between AI and Your Coreflux Environment

Modern AI assistants are powerful — but they don't natively understand LoT (Language of Things) syntax, Coreflux broker configuration, or the nuances of industrial IoT architecture. Without access to the official documentation, an AI assistant will guess, often producing code that looks plausible but uses invented syntax.

The **Model Context Protocol (MCP)** solves this. MCP is an open standard that lets AI assistants — like Claude, GitHub Copilot, or any MCP-compatible client — call external tools during a conversation. The **Coreflux MCP Server** exposes the entire Coreflux documentation as a set of tools your assistant can query in real time. When you ask "how do I create a time-based LoT Action?", your assistant doesn't guess — it looks up the answer in the official docs and responds with verified syntax and working examples.

The result: you stay in your editor, describe what you want in plain English, and get accurate LoT code grounded in real documentation.

> [!WARNING]
>
> This page is the **documentation MCP** at `https://docs.coreflux.org/mcp` — it searches official docs for your assistant. It does **not** start or control a broker.
>
> To let an assistant run broker commands and LoT Actions on a live broker, enable the [MCP Server](/latest/mqtt-broker/mcp-server) (`Mcp.Enabled`). To call *external* MCP tools from LoT, use an [MCP connector](/latest/lot-language/routes/mcp-routes) (`TYPE MCP` / `CALL MCP`).

> [!TIP]
>
> **Like giving your AI assistant a library card for Coreflux.** Instead of guessing about LoT syntax or broker configuration, your assistant can look it up directly in the official docs and give you an accurate, sourced answer.

### When to Use This

* You want your AI assistant to **answer Coreflux questions accurately** using official documentation
* You need **LoT syntax help** while coding in an AI-powered editor (Cursor, VS Code with Copilot)
* You want to **search the documentation** through natural language without leaving your workflow
* You're building with Coreflux and want your assistant to have **up-to-date reference material**

***

## How It Works

MCP (Model Context Protocol) is a standard created by Anthropic that defines how AI assistants communicate with external services. It works like a plugin system: an MCP **server** exposes a set of tools, and an MCP **client** (your AI assistant) discovers and calls those tools during conversation.

Here is what happens when you ask your AI assistant a Coreflux question:

| Step | What Happens |
| - | - |
| **1. You ask** | You type a question in natural language — *"Create a LoT Action that monitors temperature sensors"* |
| **2. AI recognizes the domain** | Your assistant detects this is a Coreflux question and decides to consult the MCP tools |
| **3. MCP tool call** | The assistant calls the Coreflux MCP Server — searching the documentation or asking the docs assistant |
| **4. Documentation responds** | The MCP server returns relevant documentation snippets, syntax references, and code examples |
| **5. AI synthesizes** | Your assistant combines the documentation with your specific requirements to produce accurate, grounded LoT code |
| **6. You review** | You receive a response with correct syntax, proper patterns, and source references you can verify |

This loop happens automatically once the MCP is connected. You don't need to tell your assistant to "use the MCP" — it discovers the available tools and calls them whenever your question relates to Coreflux.

| Component | Role |
| - | - |
| **MCP Server** | Coreflux's hosted service that exposes documentation tools |
| **MCP Client** | Your AI assistant (Claude, Copilot, etc.) that calls those tools |
| **Transport** | HTTP connection between client and server |

***

## Setup

Connect your AI assistant to the Coreflux documentation MCP server. Choose **Native** to install from the contextual menu on any documentation page, or **Manual** to paste the server URL into your editor's configuration file.

**Native**

The fastest way to connect is through the **contextual menu** at the top of every documentation page. It copies the hosted MCP server URL or installs the server directly in supported editors — no JSON editing required.

![Documentation page contextual menu expanded, showing Copy page, View as Markdown, Open in ChatGPT, Open in Claude, Copy MCP Server, Copy MCP install command, Connect to Cursor, and Connect to VS Code](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/action-menu-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=ab62d6ffe924c7ef063007d4fc93c08b)

Open the contextual menu from Copy page on any documentation page

| Menu option | What it does |
| - | - |
| **Copy MCP Server** | Copies the hosted MCP server URL to your clipboard |
| **Copy MCP install command** | Copies the `npx add-mcp` command to install the server |
| **Connect to Cursor** | Opens Cursor and installs the MCP server |
| **Connect to VS Code** | Opens VS Code and installs the MCP server |

**VS Code**

**1. Open the contextual menu**

On any Coreflux documentation page, click **Copy page** (top right) to expand the menu.

**2. Connect to VS Code**

Select **Connect to VS Code**. VS Code opens the MCP server installation flow for **Coreflux Documentation**.

**3. Install the server**

On the MCP server page, click **Install** (current window) or **Install in Workspace** (project only). Confirm trust if prompted.

![VS Code MCP Server tab for Coreflux Documentation showing Install and Install in Workspace buttons and configuration with Type http and the MCP server URL](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/vscode-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=e83435c5b09e548d23b3b3ef1cb90b4a)

VS Code MCP server page after Connect to VS Code

**4. Enable tools in Copilot**

Reload the window if needed, then open Copilot Chat in **Agent** mode and enable the Coreflux tools in the tool picker.

**Cursor**

**1. Open the contextual menu**

On any Coreflux documentation page, click **Copy page** (top right) to expand the menu.

**2. Connect to Cursor**

Select **Connect to Cursor**. Cursor opens the MCP server installation flow for **Coreflux Documentation**.

**3. Install the server**

In **Settings → Tools & MCPs**, review the pre-filled **Install MCP Server?** form (name, type, and URL), then click **Install**.

![Cursor Settings Tools page showing Install MCP Server dialog for Coreflux Documentation with Name, Type streamableHttp, URL, and Install button](https://mintcdn.com/coreflux/2Qlxw_T8xvkddvBy/images/MCP/cursor-install-mcp.png?fit=max\&auto=format\&n=2Qlxw_T8xvkddvBy\&q=85\&s=4ba9395dd8281d8683178457bfcb5f20)

Cursor Tools settings after Connect to Cursor

**4. Confirm in Cursor**

Verify **Coreflux Documentation** appears under **Installed MCP Servers** with tools enabled.

> [!NOTE]
>
> To install manually in Cursor instead, use **Copy MCP Server** or **Copy MCP install command**, then switch to the **Manual** tab and follow the **Cursor** steps.

**Other clients**

For Claude Desktop, Claude.ai, or other MCP clients that are not in the menu:

**1. Copy the server URL**

Open the contextual menu and choose **Copy MCP Server**. Paste the URL into your client's MCP configuration.

**2. Or use the install command**

Choose **Copy MCP install command** and run the copied `npx add-mcp` command in your terminal, then follow the prompts for your editor.

**3. Finish setup in your client**

Restart the client and confirm the **Coreflux Documentation** server is connected. See the **Manual** tab for editor-specific configuration examples.

**Manual**

Add the Coreflux MCP server URL to your client's configuration file. Use this method when you need full control over the config or when the contextual menu is unavailable.

**Coreflux MCP Server URL:**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
https://docs.coreflux.org/mcp
```

> [!TIP]
>
> The [Coreflux AI Starter](https://github.com/CorefluxCommunity/coreflux-ai-starter) repository has pre-built MCP config files for Cursor, VS Code, and Claude Desktop — copy the file for your editor instead of writing JSON by hand.

**Cursor**

Cursor supports MCP servers natively. Add the Coreflux MCP to your global configuration or to a specific project.

**1. Open MCP Configuration**

Navigate to your Cursor MCP configuration file. You can use the global configuration at `~/.cursor/mcp.json`, or create a project-level `.cursor/mcp.json` in your workspace root.

**2. Add the Coreflux MCP Server**

Add the following entry to the `mcpServers` object:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux": {
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

**3. Restart Cursor**

Restart Cursor or reload the window for the MCP server to be detected. You should see the Coreflux tools become available in your AI assistant's tool list.

**4. Verify the Connection**

Open Cursor Settings and navigate to the **MCP** section. You should see `coreflux` listed as a connected server with its tools available.

> [!NOTE]
>
> If you already have other MCP servers configured, simply add the `"coreflux"` entry alongside them inside the existing `mcpServers` object.

**Claude Desktop**

Claude Desktop supports MCP servers through its configuration file.

**1. Locate the Configuration File**

Open the Claude Desktop configuration file at:

**Windows**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
%APPDATA%\Claude\claude_desktop_config.json
```

**macOS**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Linux**

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
~/.config/Claude/claude_desktop_config.json
```

If the file doesn't exist, create it.

**2. Add the Coreflux MCP Server**

Add or merge the following configuration:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcpServers": {
    "coreflux": {
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

**3. Restart Claude Desktop**

Fully quit and reopen Claude Desktop. The Coreflux tools will appear in Claude's tool picker (the hammer icon) when starting a new conversation.

**Claude.ai**

Claude.ai (the web interface) supports remote MCP server connections through its Integrations settings.

**1. Open Claude.ai Settings**

Go to [claude.ai](https://claude.ai), click your profile icon, and navigate to **Settings**.

**2. Navigate to Integrations**

Select the **Integrations** section in the settings panel.

**3. Add the Coreflux MCP Server**

Click **Add Integration** (or **Add MCP Server**), and enter the Coreflux MCP Server URL:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
https://docs.coreflux.org/mcp
```

Give it a name like **Coreflux** and confirm.

**4. Start a Conversation**

Open a new conversation. The Coreflux tools will be available for Claude to use when relevant to your prompts.

> [!NOTE]
>
> Remote MCP server support on Claude.ai may require a Pro or Team plan. Check your plan's feature availability.

**VS Code**

VS Code supports MCP servers through GitHub Copilot's agent mode. Ensure you have the **GitHub Copilot** extension installed and updated.

**1. Open MCP Configuration**

Create or open the `.vscode/mcp.json` file in your workspace root. Alternatively, you can configure MCP servers globally in your VS Code `settings.json`.

**2. Add the Coreflux MCP Server**

In `.vscode/mcp.json`, add:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "servers": {
    "coreflux": {
      "type": "sse",
      "url": "https://docs.coreflux.org/mcp"
    }
  }
}
```

Or in your global `settings.json`:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "mcp": {
    "servers": {
      "coreflux": {
        "type": "sse",
        "url": "https://docs.coreflux.org/mcp"
      }
    }
  }
}
```

**3. Reload VS Code**

Reload the window (`Ctrl+Shift+P` → **Developer: Reload Window**). The Coreflux MCP tools will become available in Copilot's agent mode.

**4. Confirm trust and enable tools**

After reloading, confirm trust if prompted and open the "Configure Tools" button in the Chat input to verify the tools are enabled in the tool picker before proceeding.

**5. Use in Copilot Chat**

Open the Copilot Chat panel and switch to **Agent** mode. The Coreflux tools will be available for Copilot to call when relevant.

***

## Verify Your Connection

After setup, confirm the MCP is working by sending a test prompt to your AI assistant. The specific prompt doesn't matter — what matters is that the assistant **calls the Coreflux MCP tools** rather than answering from memory.

### Quick Test

Send this prompt to your AI assistant:

```text wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
Using the Coreflux documentation, show me the correct syntax for 
a LoT Action that triggers every 30 seconds and publishes a 
heartbeat message.
```

> [!TIP]
>
> It's working if your assistant calls one of the MCP tools during its response. In Cursor, you'll see the tool calls in the assistant's output. In Claude Desktop, look for the hammer icon indicating tool usage.

> [!WARNING]
>
> **It's not working** if the assistant answers from general knowledge without calling any Coreflux tools. Double-check your MCP configuration and restart your client.

### What a Connected Response Looks Like

When the MCP is active, your assistant's response will:

* Reference **specific LoT syntax** from the documentation (not invented patterns)
* Include **working code examples** that match the official docs
* Cite **source pages** you can open to verify the information
* Use **correct terminology** — LoT, Actions, Models, Rules, Connectors — exactly as defined in the documentation

Without the MCP, the assistant might still produce LoT-like code, but it will be based on general training data rather than the official Coreflux documentation. Always verify the connection before starting a development session.

***

## Best Practices

> **Be Specific with Your Questions**
>
> The more specific your question, the better the results. Instead of asking "tell me about connectors," try "how do I configure a PostgreSQL data storage connector with authentication." Specific queries help the tools return more relevant documentation.

> **Ask for Source References**
>
> When you need to verify information, ask your assistant to include documentation source links. The Coreflux MCP tools can return references to official pages so you can open and verify the answer yourself.

> **Use for Code Review**
>
> Before deploying LoT code, ask your assistant to validate the syntax against the documentation. For example: *"Check the Coreflux docs — is this the correct syntax for a Modbus TCP connector?"* This ensures your code follows the latest documented patterns.

> **Add the Agent Skills**
>
> The MCP answers questions on demand. On broker 2.22 or later, the [Coreflux agent skills](/ai/agent-skills) give your assistant LoT and broker knowledge before it asks. Install both for the most reliable LoT.

> **Leverage Conversation Context**
>
> The documentation assistant supports multi-turn conversations. Ask follow-up questions to drill deeper into a topic without repeating context — the assistant remembers what you discussed previously in the same conversation.

> [!WARNING]
>
> The Coreflux MCP Server is currently in **beta**. The server URL may change as the service evolves. Check this page for the latest configuration instructions.

***

## Next Steps

> **[Developing LoT Using AI](/ai/developing-with-lot)**
>
> A guide on utilizing AI agents to write, debug, and deploy LoT scripts directly through the MCP interface.

> **[AI-Assisted Development Best Practices](/ai/best-practices)**
>
> Strategic advice on prompt engineering, security guardrails, and maintaining consistency when using AI to manage industrial assets.


# Container Components
Source: https://docs.coreflux.org/hub/dashboards/components/containers

Group dashboard components with cards and tabs to structure larger panels in the Coreflux HUB.

![A titled Zone 1 Status card containing a temperature readout, a status indicator, and a Details button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/card-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=6f70e4f99fc925a6f366c02adce28287)

A card grouping an asset's readout, status, and action into one unit on the panel grid

Containers group other components. Use them when a panel grows beyond a simple grid — to cluster a machine's readouts under one title or split a screen into tabs.

> [!TIP]
>
> **Like trays on a workbench.** The bench grid holds the trays in place; each tray keeps one job's tools together so they move as a unit.

***

Two containers are available today: `card` for grouping, `tabs` for splitting.

## Card

Groups child components under a title.

**Basic**

A titled card with one readout inside:

![A titled Zone 1 Status card containing a temperature readout](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/card-basic.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=35f61413a5bb1c975c70b82b6ed1fdb0)

A titled card grouping a single temperature readout

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StatusCard" WITH TYPE "card"
    SET TITLE "Zone 1 Status"

    ADD COMPONENT "TempReading" WITH TYPE "value"
        BIND VALUE TO TOPIC "zone1/temperature"
        SET UNIT "°C"
```

**Full example**

A card combining a readout, an indicator, and a navigation button — the two extra children are the new parts:

![A titled Zone 1 Status card with a temperature value, a status indicator, and a Details button](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/card-full.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=6f70e4f99fc925a6f366c02adce28287)

A Zone 1 Status card with a temperature readout, a status indicator, and a Details button

```lot wrap focus={9-17} theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "StatusCard" WITH TYPE "card"
    SET TITLE "Zone 1 Status"

    ADD COMPONENT "TempReading" WITH TYPE "value"
        BIND VALUE TO TOPIC "zone1/temperature"
        SET UNIT "°C"

    ADD COMPONENT "StatusIndicator" WITH TYPE "indicator"
        BIND STATE TO TOPIC "zone1/status"
        SET ON_VALUE "running" WITH COLOR "green"
        SET ON_VALUE "stopped" WITH COLOR "red"

    ADD COMPONENT "DetailsButton" WITH TYPE "button"
        SET LABEL "Details"
        ON CLICK DO NAVIGATE TO PANEL "Zone1Details"
```

| Property | Type | Description |
| - | - | - |
| `TITLE` | String | Card heading |

## Tabs

Each tab holds its own components — useful for Overview / Analytics / Settings splits on one screen.

> [!NOTE]
>
> In the current HUB build, tab headers show the **inner component name** rather than the `ADD TAB` title. The structure below matches the spec syntax; tab labelling is tracked as a known issue.

**Basic**

![A tabbed container switching between sub-views on one panel](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/components/tabs.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=190e1e6a76ff7681e1b9e88d412482db)

A tab strip switching between sub-views on one panel (current build labels tabs from their content)

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
ADD COMPONENT "MainTabs" WITH TYPE "tabs"

    ADD TAB "Overview"
        ADD COMPONENT "OvTemp" WITH TYPE "value"
            BIND VALUE TO TOPIC "zone1/temperature"
            SET UNIT "°C"

    ADD TAB "Analytics"
        ADD COMPONENT "OvGauge" WITH TYPE "gauge"
            SET RANGE FROM 0 TO 100
            BIND VALUE TO TOPIC "zone1/temperature"

    ADD TAB "Settings"
        ADD COMPONENT "OvText" WITH TYPE "text"
            SET LABEL "Settings go here"
```

## Card vs. grid position?

Use **grid positioning** (`AT COLUMN/ROW`) when components are independent readouts. Use a **card** when components belong to the same asset and should travel together — a card moves as one unit when you rearrange the panel. See [Mixing layouts with cards](/latest/lot-language/panels/defining-panels#mixing-layouts-with-cards) for a complete panel that combines both.

## Next Steps

> **[Display components](/hub/dashboards/components/display)**
>
> The readouts you place inside cards and tabs.

> **[Common patterns](/hub/dashboards/patterns)**
>
> Full panels that combine containers with live data.


# Common Patterns
Source: https://docs.coreflux.org/hub/dashboards/patterns

Ready-to-adapt panel recipes for the most frequent dashboard jobs.

![A KPI dashboard with a Message Count gauge, a rising Message Count Trend line chart, and an Error Rate readout](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/overview-hero.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=269c34293a365f1c597cbcd399f12cb8)

The Live KPI dashboard recipe from this page, running with live data

Each recipe is a complete, working panel. Copy it, swap the topics for yours, and adjust ranges and labels.

> [!TIP]
>
> **Like starter dough.** Each recipe already works as-is — you don't build from scratch, you season: your topics, your ranges, your labels.

***

Five recipes, ordered from the smallest useful panel to data-layer integrations.

## Minimal monitoring panel

**Goal:** one signal, one status — the smallest useful dashboard.

![A dashboard with a temperature gauge reading 82 °C and a green running status indicator](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/patterns/minimal-monitoring.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=5b513f764cd48a4f2b056f1424912b00)

Two-column panel: a temperature gauge on the left, a running status indicator on the right

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL SensorMonitor
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Sensor Monitor"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "TempGauge" WITH TYPE "gauge"
        AT COLUMN 1 ROW 1
        SET RANGE FROM 0 TO 150
        SET UNIT "°C"
        BIND VALUE TO TOPIC "sensor/temperature"
        ADD THRESHOLD AT 100 WITH COLOR "warning"
        ADD THRESHOLD AT 130 WITH COLOR "critical"

    ADD COMPONENT "StatusIndicator" WITH TYPE "indicator"
        AT COLUMN 2 ROW 1
        BIND STATE TO TOPIC "machine/status"
        SET ON_VALUE "running" WITH COLOR "green"
        SET ON_VALUE "stopped" WITH COLOR "red"
        SET SIZE "large"
```

**Adapt:** your topic names, the gauge range, the threshold levels.

## Live KPI dashboard

**Goal:** a wall screen with a headline number, its trend, and a secondary KPI.

![A KPI dashboard with a Message Count gauge at 135 msg, a rising Message Count Trend line chart, and an Error Rate readout of 1.25 percent](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/patterns/live-kpi-dashboard.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=69894d551b403fd7d46c5e3b612ac7af)

Three-column KPI wall: a message-count gauge, its live trend, and the error-rate readout

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL KpiDashboard
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Operational KPI Dashboard"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "MessageCountGauge" WITH TYPE "gauge"
        SET LABEL "Message Count"
        SET RANGE FROM 0 TO 200
        SET UNIT "msg"
        BIND VALUE TO TOPIC "kpi/operational/messageCount"

    ADD COMPONENT "MessageCountTrend" WITH TYPE "realtime-chart"
        SET LABEL "Message Count Trend"
        SET CHART_TYPE "line"
        SET UNIT "msg"
        BIND VALUE TO TOPIC "kpi/operational/messageCount"
            SET SERIES_LABEL "Message Count"

    ADD COMPONENT "ErrorRate" WITH TYPE "value"
        SET LABEL "Error Rate"
        SET UNIT "%"
        SET DECIMALS 2
        BIND VALUE TO TOPIC "kpi/operational/errorRate"
```

**Adapt:** share it on a TV via the panel URL — see [Dashboards in the HUB](/hub/dashboards/overview).

## Control panel

**Goal:** drive the line from the dashboard — buttons publish commands, a number field sets the speed, and a slider tracks the live feedback.

![A two-column operator panel with Start and Stop Conveyor buttons, a speed setpoint number field, and a conveyor speed slider](https://mintcdn.com/coreflux/ry-30sFxFVWzN72U/images/dashboard/patterns/control-panel.png?fit=max\&auto=format\&n=ry-30sFxFVWzN72U\&q=85\&s=7bf104e56761bbaae30067a2eab551dc)

Operator panel with start/stop buttons, a speed setpoint field, and a live conveyor speed slider

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL Zone1Control
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Zone 1 Control"
WITH LAYOUT "grid" COLUMNS 2

    ADD COMPONENT "StartButton" WITH TYPE "button"
        AT COLUMN 1 ROW 1
        SET LABEL "Start Conveyor"
        ON CLICK DO
            PUBLISH TOPIC "zone1/conveyor/cmd/start" WITH 1

    ADD COMPONENT "StopButton" WITH TYPE "button"
        AT COLUMN 2 ROW 1
        SET LABEL "Stop Conveyor"
        SET STYLE "danger"
        ON CLICK DO
            PUBLISH TOPIC "zone1/conveyor/cmd/stop" WITH 1

    ADD COMPONENT "SpeedSetpoint" WITH TYPE "number-field"
        AT COLUMN 1 ROW 2
        SET LABEL "Speed Setpoint (%)"
        SET PLACEHOLDER "0"
        ON CHANGE DO
            PUBLISH TOPIC "zone1/conveyor/cmd/speed" WITH VALUE

    ADD COMPONENT "LiveSpeed" WITH TYPE "slider"
        AT COLUMN 2 ROW 2
        SET RANGE FROM 0 TO 100
        SET UNIT "%"
        BIND VALUE TO TOPIC "zone1/conveyor/speed"
```

**Adapt:** the command topics (`cmd/...`) and the feedback topic (`speed`) — keeping them separate means the slider reflects what the line is actually doing, not just the last setpoint sent.

## Panel backed by a LoT Model

**Goal:** when a [Model](/latest/lot-language/models/overview) already aggregates your data layer, bind to its fields instead of raw topics.

> [!WARNING]
>
> **Known issue (current HUB build).** `BIND … TO MODEL` bindings do not receive data yet, and `SET MODEL … WITH VALUE` write-back from panel handlers does not update model fields — so this recipe cannot be shown rendering live values and the setpoint field cannot write back. The syntax below follows the spec; in the meantime, bind widgets to the model's source topics (or its output topic with `JSON_PATH`) and publish setpoints to those topics directly.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE PANEL PumpDashboard
WITH VISIBILITY PUBLIC
WITH STATE PUBLISHED
WITH TITLE "Pump System"
WITH LAYOUT "grid" COLUMNS 3

    ADD COMPONENT "FlowGauge" WITH TYPE "gauge"
        BIND VALUE TO MODEL "PumpSystem.flow_rate"
        SET UNIT "L/min"
        SET RANGE FROM 0 TO 500

    ADD COMPONENT "PressureDisplay" WITH TYPE "value"
        BIND VALUE TO MODEL "PumpSystem.pressure"
        SET UNIT "bar"
        SET DECIMALS 2

    ADD COMPONENT "PumpStatus" WITH TYPE "indicator"
        BIND STATE TO MODEL "PumpSystem.running"
        SET ON_VALUE "true" WITH COLOR "success"
        SET ON_VALUE "false" WITH COLOR "muted"
        SET SIZE "large"

    ADD COMPONENT "FlowSetpoint" WITH TYPE "number-field"
        SET LABEL "Flow Setpoint (L/min)"
        SET PLACEHOLDER "0"
        BIND VALUE TO MODEL "PumpSystem.setpoint"
```

## Next Steps

> **[Build your first dashboard](/latest/quick-start/building-dashboards)**
>
> Walk through one of these panels end to end with live data.

> **[Dashboards in the HUB](/hub/dashboards/overview)**
>
> Publish, share, and put any of these on a wall screen.


# Connector Configuration
Source: https://docs.coreflux.org/hub/routes/configuration

Edit connector configuration, events, mappings, and tags in Visual or LoT mode

![Coreflux HUB Connector Configuration panel showing Visual Mode and LoT Mode toggle with configuration, events, and mappings tabs](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-configuration.gif?s=d642fb924e3ae9df150f67ca8925cbc2)

Connector Configuration panel in the Coreflux HUB — edit settings, events, mappings, and tags in Visual or LoT mode

## Why Configure Connectors in the Coreflux HUB?

You need to adjust connector settings—connection parameters, events, mappings, and tags—without editing files or publishing MQTT commands. The Connector Configuration in the HUB lets you edit connectors with a form-based Visual Mode or switch to LoT Mode to modify the raw LoT code by hand.

## When to Use It

* **Updating connection settings** — Change IP, port, credentials, or other config fields
* **Adding events or mappings** — Extend a connector with new events, mappings, or tags
* **Switching modes** — Use Visual Mode for guided editing or LoT Mode for full control

For an overview of how to add connectors, select connector types, and use templates, see [Connectors Overview](/hub/routes/overview).

***

## Visual Mode vs LoT Mode

| Mode | Best For |
| - | - |
| **Visual Mode** | Form-based editing with add/remove fields, modals, and validation |
| **LoT Mode** | Direct LoT code editing for power users who prefer hand-editing |

Toggle between modes using the **Visual Mode** / **LoT Mode** toggle at the top of the connector configuration panel. Changes in either mode are applied when you click **Save Changes**.

### LoT Mode

Switch to **LoT Mode** to view and edit the full connector definition as LoT code. This gives you direct control over the syntax and is useful for copying configurations or making bulk changes.

![Coreflux HUB Connector Configuration LoT source editor for SiemensS7Route showing syntax-highlighted DEFINE ROUTE SiemensS7Route WITH TYPE SIEMENS\_S7 with an S7\_CONFIG block (IP, CPU\_TYPE, RACK, SLOT), a MAPPING TestPLC block with SOURCE\_TOPIC, EVERY, and a Real TAG with ADDRESS, ADDRESS\_TYPE, and DATA\_TYPE, plus Cancel and Save Changes buttons in the bottom bar](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-lot-mode.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=da2702726190777943ddd601f5a4c751)

LoT source editor in Config: SiemensS7Route showing the full connector definition as editable LoT code with Cancel and Save Changes controls

The editor shows the keyword you wrote. A connector defined with `DEFINE CONNECTOR` keeps that spelling when you edit and save it, and one defined with `DEFINE ROUTE` keeps `DEFINE ROUTE`.

![Coreflux HUB Config: PlantArchive window open over the Connectors Manager, with the LoT tab selected showing DEFINE CONNECTOR PlantArchive WITH TYPE FILE\_STORAGE, an ADD FILE\_STORAGE\_CONFIG block with STORAGE\_DIR and FILE\_PATTERN, and an ADD EVENT StoreReading block with SOURCE\_TOPIC and DESTINATION\_TOPIC, plus Cancel and Save Changes](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/configuration/connector-lot-mode-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=c5159970c47c3e52dc9a6e5d13ce1e47)

LoT tab in Config: PlantArchive, a connector written with DEFINE CONNECTOR

### Renaming Elements

You can rename connectors, events, mappings, and tags directly from the configuration panel. Click the **pencil icon** next to any element name to turn it into an editable text field, type the new name, and press **Enter** to confirm. A **Renamed** badge appears briefly to confirm the change.

This works the same way for all element types:

* **Connector name** — Displayed at the top of the configuration panel
* **Event name** — Displayed in the Events tab header for each event
* **Mapping name** — Displayed in the Mappings tab header for each mapping
* **Tag name** — Displayed in the tag header within a mapping

> [!NOTE]
>
> Renaming takes effect when you click **Save Changes**. If you cancel without saving, the original names are restored.

***

## Configuration Tab

The **Configuration** tab shows the connector's connection and protocol settings (e.g., `S7_CONFIG`, `SQL_CONFIG`, `MODBUS_CONFIG`). Each field displays its name, whether it is required or optional, its data type, and a description.

![Coreflux HUB Connector Configuration tab for Connector: SiemensS7Route with Configuration, Events, and Mappings tabs; Configuration is selected showing the S7 Configuration section with four fields — IP required string set to 127.0.0.1, CPU\_TYPE string set to S71200, RACK int set to 0, and SLOT int set to 1 — plus an + Add Field button and Cancel and Save Changes buttons at the bottom](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-config-tab.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=78d5d3fc3a7628636fdee3aa03e74aee)

Configuration tab for Connector: SiemensS7Route showing the S7 Configuration fields with types, descriptions, and current values

* **View fields** — See all configuration fields with their types and descriptions
* **Edit field** — Change values in the input fields
* **Add field** — Click **+ Add Field** to add optional fields from a list of available parameters
* **Delete field** — Use the delete icon on a field to remove it

### Adding a Configuration Field

Click **+ Add Field** to open the **Add Configuration Field** modal. This shows all optional fields available for the connector type, along with their data types and descriptions.

![Coreflux HUB Add Configuration Field modal prompting to select an optional field to add to the connector configuration, listing PORT int for the TCP port for S7 connection (default 102), CONNECTION\_TYPE string with four options PG, OP, S7BASIC, and S7\_BASIC (default PG), RETRY\_ATTEMPTS int for number of retry attempts (default 3), RETRY\_TIME\_SECONDS int for seconds to wait between retries (default 5), REFRESH\_TIME\_MS int for refresh time in milliseconds (default 1000), and a partially visible READ\_TIMEOUT int field](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-config-add-field.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=36ebef56014dff425241204b5189e21b)

Add Configuration Field modal listing the optional parameters available for a Siemens S7 connector

***

## Events Tab

The **Events** tab manages event definitions for the connector. Events define how the connector reacts to MQTT messages—typically by reading from or writing to the connected device or service.

![Coreflux HUB Connector Configuration Events tab for Connector: SiemensS7Route showing Event ONDEMANDREAD with 3 fields — SOURCE\_TOPIC string set to s7sim/event/read, DESTINATION\_TOPIC string set to s7sim/event/read/result, and QUERY string containing a JSON S7 operation with operation, address, data\_type, and count placeholders — plus + Add Event and + Add Field controls and Cancel and Save Changes buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-events-tab.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=ff69ae3999f7ff6cccaf9dbf965fde0d)

Events tab for Connector: SiemensS7Route showing the OnDemandRead event with SOURCE\_TOPIC, DESTINATION\_TOPIC, and QUERY fields

* **Add Event** — Click **+ Add Event** to create a new event with a name and fields
* **Rename event** — Click the pencil icon next to the event name to rename it
* **Edit event** — Expand an event to view and edit its fields (e.g., `SOURCE_TOPIC`, `DESTINATION_TOPIC`, `QUERY`)
* **Add field** — Use **+ Add Field** within an event to add optional fields

### Adding an Event Field

Click **+ Add Field** inside an event to open the **Add Event Field** modal. This shows the optional fields available for the event.

![Coreflux HUB Add Event Field modal prompting to select an optional field to add to the event, showing a single option DESTINATION\_TOPIC string described as MQTT topic to publish S7 results](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-events-add-field.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=280372399c9f896a6ad1ed8592ade5b5)

Add Event Field modal showing the optional DESTINATION\_TOPIC field available for the event

***

## Mappings Tab

The **Mappings** tab manages mapping definitions and tags. Mappings define periodic data polling from a connected device—reading tags at a set interval and publishing the data to MQTT topics.

![Coreflux HUB Connector Configuration Mappings tab for Connector: SiemensS7Route showing Mapping TESTPLC with Mapping Configuration (SOURCE\_TOPIC string set to plc, EVERY string set to 1 SECOND) and a Tags section containing the Real tag with ADDRESS string set to DB1.DBD28, ADDRESS\_TYPE string set to DATABLOCK, and DATA\_TYPE string set to REAL, plus + Add Mapping, + Add Field, + Add Tag, and + Field controls and Cancel and Save Changes buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-mappings-tab.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=fca2b2f2d4c4b7f2dce91c29f84dbad1)

Mappings tab for Connector: SiemensS7Route showing the TestPLC mapping with SOURCE\_TOPIC and EVERY fields and a Real tag with address and data type properties

* **Add Mapping** — Click **+ Add Mapping** to create a new mapping with a name, mapping fields, and tags
* **Rename mapping** — Click the pencil icon next to the mapping name to rename it
* **Edit mapping** — Expand a mapping to edit its configuration (e.g., `EVERY`, `SOURCE_TOPIC`) and tags
* **Add Tag** — Use **+ Add Tag** within a mapping to add tags with address, data type, and other properties

### Adding a New Mapping

Click **+ Add Mapping** to open the **Add New Mapping** modal. Enter a mapping name, then use **+ Add Field** and **+ Add Tag** to build the mapping.

![Coreflux HUB Add New Mapping modal titled Create a new mapping with optional fields and tags, showing a Mapping Name input with an e.g., MyMapping placeholder, a Mapping Fields (0) section with an + Add Field button, a Tags (0) section with an + Add Tag button and a No tags added yet placeholder, plus Cancel and Create Mapping buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-add-mapping.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=2b97467ace88ce3402d5fbd3a92a6625)

Add New Mapping modal with a name field, a mapping fields section, and a tags section, plus Cancel and Create Mapping actions

### Adding a Mapping Field

Click **+ Add Field** inside a mapping to open the **Add Mapping Field** modal. This shows the optional fields available for the mapping, such as `DESTINATION_TOPIC` and `QUERY`.

![Coreflux HUB Add Mapping Field modal prompting to select an optional field to add to the mapping, showing DESTINATION\_TOPIC string described as MQTT topic to publish polled data (legacy mode) and QUERY string described as S7 read operation in JSON format (legacy mode)](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/configuration/routes-mapping-add-field.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6170698bccf06b927d26da081cf399c2)

Add Mapping Field modal showing the optional DESTINATION\_TOPIC and QUERY fields available for the mapping

#### Tags

Tags are defined inside mappings. Each tag represents a data point to read from the connected device. You can add, edit, rename, and remove tags and their properties (address, address type, data type, scaling, unit, etc.) from the Mappings tab. To rename a tag, click the pencil icon next to the tag name.

#### Saving and Canceling

* **Save Changes** — Applies all edits to the broker
* **Cancel** — Discards unsaved changes and closes the configuration panel

***

## Next Steps

> **[Connectors Overview](/hub/routes/overview)**
>
> Create new connectors with templates or LoT code.

> **[Connectors Monitoring](/hub/routes/monitoring)**
>
> View and export connector-specific logs and status.


# Connectors Monitoring
Source: https://docs.coreflux.org/hub/routes/monitoring

View real-time connector status and logs — monitor connection health, message counts, and export logs

![Coreflux HUB connector card titled MyS7Route with a green status dot in the top-right corner and a row of action icons at the bottom — a gear for Configuration, a monitor icon currently hovered showing a Connector Monitor tooltip, a globe for Documentation, and a trash can for Delete](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/monitoring/route-card-monitor.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=6c79ac2bb8b22e0de12ec2fdc8e3b5e2)

Connector card for MyS7Route with the monitor icon highlighted and a Connector Monitor tooltip

## Why Monitor Connectors?

You need to know whether a connector is running correctly — whether it is connected, how many messages it has processed, and whether there are errors. The Monitor window gives you live status metrics and real-time logs filtered to a single connector, so you can troubleshoot without searching through broker-wide output.

## When to Use It

* **Verifying connectivity** — Confirm that a connector is connected to its target system after creation or configuration changes
* **Tracking activity** — Check message counts and error rates to validate that events and mappings are executing
* **Troubleshooting connections** — See why a connector failed to connect using status details and log entries
* **Exporting for analysis** — Download filtered logs as JSON, CSV, or LOG for offline review

***

## Accessing the Monitor

Open the Connectors Manager, click on a connector card, and select **Monitor**. The Monitor window opens with two tabs: **Status** and **Logs**.

![Coreflux HUB Connectors Manager showing how to click a connector card and select Monitor to open the monitoring window](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/monitoring/access-monitoring.gif?s=dd2b6994e11dd9a6ae6bbd6ec7dd2399)

Opening the Monitor from a connector card in the Connectors Manager

***

## Status Tab

The Status tab displays live metrics from the broker for the selected connector.

![Coreflux HUB Monitor window for the BACNET connector TwinEnergyBms with Connection Connected, Health Green, and Uptime in the header; the Status tab shows Overview cards for Connection, Health, Messages, and Errors, and an Activity Timeline with Last Activity, Last Success, and Last Error](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/monitoring/route-monitor-status-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=f61f98c5fa654e5252b651211d08faee)

Monitor window, Status tab: connection, health, and uptime in the header, then the Overview cards and the Activity Timeline

| Field | Description |
| - | - |
| **Connection** | Whether the connector is currently connected to its target |
| **Health** | Health indicator (Green, Yellow, Red) based on error rates |
| **Messages** | Total messages processed, with success and failure counts |
| **Errors** | Total and consecutive error counts |

The **Activity Timeline** shows timestamps for last activity, last success, and last error. When the connector has recent failures, a **Recent Errors** list appears below the timeline with a link to view them all in the Logs tab. Uptime is shown in the window header.

### Start and Stop

The header has a **Stop** button while the connector runs, and **Start** while it's stopped. **Stop** saves the connector with `DISABLE true`, the same as **Disable** on its card. The connector stays defined but doesn't run, and the header says so. **Start** removes the line. The button follows changes made elsewhere, such as in the LoT Editor.

![Coreflux HUB Monitor window for the FILE\_STORAGE connector FlightLog, with the header text Stopped. The connector stays defined but does not run. and a Start button, above the Status tab with Connection Disconnected, Health Red, Messages 12 with 12 ok and 0 failed, Errors 0, and the activity timeline](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/monitoring/connector-monitor-stopped-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=f6fde9f2b49338803896202dafaa6d46)

Monitor window for a stopped FILE\_STORAGE connector, with Start in the header

***

## Logs Tab

The Logs tab shows real-time log entries filtered to the selected connector.

![Coreflux HUB Monitor window for the TwinFillerPlc OPCUA connector with the Logs tab selected: ALL, Fatal, Error, WARN, and INFO level filters, a JSON format selector and export button, an ERROR entry for CheckRouteConnection, and an INFO entry for RouteCertificates](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/monitoring/route-monitor-logs-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=9ce2d08745e4011559af9873d19fdb17)

Monitor window — Logs tab with level filters, JSON format selector, and export controls

### Filter by Level

Use the filter buttons to show only certain log levels:

| Filter | Description |
| - | - |
| **ALL** | Show all log entries |
| **FATAL** | Fatal errors only |
| **ERROR** | Errors only |
| **WARN** | Warnings only |
| **INFO** | Informational messages only |

### Log Entry Fields

Each log entry displays:

| Field | Description |
| - | - |
| **Timestamp** | When the event occurred |
| **Log level** | FATAL, ERROR, WARN, or INFO |
| **Category** | Event category (e.g., Action, Event) |
| **Name** | Event or action name |
| **Outcome** | Success or failure |
| **Description** | Detailed message or structured data |

### Export

Use the export dropdown to choose a format:

* **JSON** — Structured export for parsing or integration
* **CSV** — Spreadsheet-friendly format
* **LOG** — Plain text log file

Click **Export** to download the filtered logs.

![Coreflux HUB Monitor: SiemensS7Route Logs tab displaying the three INFO ProcessCloudCLICommand entries and a Logs Exported toast in the top-right corner confirming Exported 3 logs as JSON, with level filters, JSON format selector, and export controls still visible](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/monitoring/route-logs-export.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=28d8c1b127124585efb66f1c2bbea7ec)

Exporting SiemensS7Route logs as JSON with a Logs Exported confirmation toast in the top-right corner

### Clear Logs

Use **Clear Logs** to remove displayed entries from the view. This does not affect the broker — it only clears the HUB display.

***

## Next Steps

> **[Connectors Configuration](/hub/routes/configuration)**
>
> Edit connector settings if status or logs show connection or configuration issues.

> **[Broker Logs](/hub/system/broker-logs)**
>
> View broker-wide logs for system-level troubleshooting.


# Connectors Overview
Source: https://docs.coreflux.org/hub/routes/overview

Add, configure, and monitor Connectors in the Coreflux HUB—view status, edit configuration, and inspect connector logs

![Coreflux HUB Connectors Manager with a 2 connectors count, delete and add buttons, connector cards for LegacyLogs and PlantArchive (FILE\_STORAGE), each with a red status dot and Configuration, Monitor, Documentation, and Delete icons, an Add connector card, and the status bar Connectors popover listing both connectors as Disconnected with an Open Connectors Manager link](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/routes/overview/connectors-manager-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=6b518a51578d5981f1a1dbae80dbe065)

Connectors Manager: connector cards with live connection status, configuration, and monitoring tools

## Why Use the Connectors Section?

You need to manage Connectors from the browser—add new connectors, edit configuration, check connection status, and troubleshoot with logs. The Connectors section of the Coreflux HUB lets you configure connectors with a visual editor or LoT code, view connected and disconnected connectors, and inspect connector-specific logs.

## When to Use It

* **Adding connectors** — Create connectors from templates (PostgreSQL, MongoDB, Modbus, etc.) or write LoT code directly
* **Configuring connectors** — Edit configuration, events, mappings, and tags in Visual or LoT mode
* **Monitoring** — See which connectors are connected and which are not, and view real-time status metrics
* **Troubleshooting** — View connector logs, filter by level, and export for analysis

***

## Connectors Tools

> **[Connectors Configuration](/hub/routes/configuration)**
>
> Edit connectors, view status (connected/not connected), and delete connectors.

> **[Connectors Monitoring](/hub/routes/monitoring)**
>
> View real-time status metrics and logs filtered by connector, export as JSON/CSV/LOG.

***

## Connector List and Status

The Connectors Manager displays all defined connectors as cards. Each connector card shows the connector name, type (e.g., `SIEMENS_S7`), and a **status indicator** dot in the top-right corner. The dot color tells you the current connection state at a glance:

| Color | Status |
| - | - |
| **Green** | Connected |
| **Red** | Not connected |
| **Gray** | Unknown status |
| **Yellow** | Reconnecting |

![Coreflux HUB connector card titled SiemensS7Route with the SIEMENS\_S7 type badge, a green status dot in the top-right corner indicating a connected connector, and four action icons along the bottom for configuration, monitor, documentation, and delete](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/overview/route-card-status.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=db53f51d8830d4e9a06115e91104829e)

Connector card for SiemensS7Route with a green status dot in the top-right indicating the connector is connected

Use the controls at the top to **sort** connectors by name and **filter** by type. The **Delete All** button removes all connectors, and the **Add a connector +** button opens the connector creation options.

## Connector Card Actions

Click on a connector card to open its context menu with three options:

![Coreflux HUB SiemensS7Route card with the SIEMENS\_S7 type badge and a row of four action icons at the bottom — a gear for Configuration, a monitor for Monitor, a globe for Documentation, and a trash can for Delete](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/overview/routes-card-menu.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=36825ce968d967294732d3246fca19cd)

Connector card action icons — gear for Configuration, monitor for Monitor, globe for Documentation, and trash for Delete

| Action | Description |
| - | - |
| **Configuration** | Opens the [Connectors Configuration](/hub/routes/configuration) panel to edit settings, events, mappings, and tags |
| **Monitor** | Opens the [Connectors Monitoring](/hub/routes/monitoring) window with a **Status** tab (connection, health, messages, errors) and a **Logs** tab (real-time connector logs) |
| **Documentation** | Opens the Coreflux documentation for the connector type directly inside the HUB |
| **Disable** / **Enable** | Turns the connector off or on without deleting it. See [Disable a connector](#disable-a-connector) |

### Disable a connector

**Disable** saves the connector's definition with `DISABLE true`, and **Enable** removes it. A disabled connector stays defined but doesn't run: its card is dimmed, with a grey status dot and a **Disabled** chip. No connection check runs while it's disabled.

![Coreflux HUB Connectors Manager with 3 connectors: the FILE\_STORAGE connector FlightLog dimmed with a grey status dot, a DISABLED chip, and the Enable tooltip over its power icon; the REST\_API connector FlightsTrackerApi and the LLM connector LocalOllama, used by 2 agents, both with green status dots; and an Add connector card](https://mintcdn.com/coreflux/XJTFSRrz8BZ00-5F/images/routes/overview/connectors-manager-disabled-light.png?fit=max\&auto=format\&n=XJTFSRrz8BZ00-5F\&q=85\&s=3ebddad645e53b3f870bc2c472fe7a7e)

FlightLog is disabled, with its Enable action hovered. FlightsTrackerApi and LocalOllama are enabled

The broker refuses to disable a `TYPE LLM` connector that agents still use: disable those agents first. On a broker without `DISABLE` support, the HUB changes nothing and says so. The **Start** / **Stop** button in the [Monitor window](/hub/routes/monitoring#start-and-stop) does the same thing.

### Connector Documentation

The Documentation option opens the Coreflux docs page for the connector type in an embedded viewer inside the HUB. This gives you quick access to syntax reference, configuration parameters, and examples without leaving the interface.

![Coreflux HUB embedded Docs window titled SiemensS7Route loading the Siemens S7 Connector page from docs.coreflux.org with Connectors navigation on the left, Siemens S7 Overview and Basic Syntax content in the center, and an On this page outline on the right, plus Refresh and Open in Browser controls](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/routes/overview/route-documentation.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=55472cee084ba947719f458fbed8a658)

Embedded Docs window showing the Siemens S7 Connector page from the Coreflux documentation inside the HUB

***

## Adding a Connector

Click **Add connector** (the last card) or the **+** button in the Connectors Manager toolbar. The **New connector** window opens with everything in one place: the connector type catalog on the left and the connector editor on the right.

![Coreflux HUB New connector window with a Search 301 connector types field, All plans, Available, Community, and Licensed filters, an All categories dropdown, the Industrial Connectors list with Beckhoff ADS selected, and Configuration, Events, Mappings, and LoT tabs showing the ADS configuration fields, plus Cancel and Create Connector](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/routes/overview/new-connector-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=d47a51a6874a37a2be824bee8b490be7)

New connector window: pick a connector type on the left, then fill in its configuration, events, mappings, or LoT on the right

**1. Pick a connector type**

Use the **Search connector types...** field, the plan filter (**All plans**, **Available**, **Community**, **Licensed**), or the **All categories** list (for example **Industrial Connectors**, **Data Storage Connectors**, or **AI Connectors**) to narrow the catalog, then click a type. Types still in preview carry a **Beta** badge. The editor on the right fills in with that type's template. The AI category includes the **LLM** connector. An agent is not a connector type: add the LLM connector here, then define the agent in LoT. See [AI Connectors and Agents](/latest/lot-language/routes/ai-routes).

**2. Fill in the configuration**

The **Configuration** tab lists the type's fields with a short description each. Required fields are marked **Required**, and secrets such as passwords are masked. Use **+ Add Field** to include optional parameters.

**3. Add events and mappings**

Use the **Events** tab for actions triggered by MQTT messages (for example, a query on each message), and the **Mappings** tab for the tags or points the connector polls and publishes.

**4. Review the LoT**

The **LoT** tab shows the generated LoT definition. You can edit the definition directly there if you prefer writing LoT.

**5. Name and create**

The connector gets a generated name such as `NewBeckhoffADS_<timestamp>` at the bottom of the window. Click the pencil to rename it, then click **Create Connector** to deploy it to the broker. **Cancel** closes the window; if you have unsaved changes, the HUB asks before discarding them.

For example, a PostgreSQL connector written in the **LoT** tab looks like this (`DEFINE ROUTE` remains a supported alias):

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE CONNECTOR MyPostgres WITH TYPE POSTGRESQL
  ADD SQL_CONFIG
    WITH SERVER "localhost"
    WITH PORT '5432'
    WITH DATABASE "iot_data"
    WITH USERNAME "admin"
    WITH PASSWORD "your_password"
  ADD EVENT StoreSensor
    WITH SOURCE_TOPIC "sensors/#"
    WITH QUERY "INSERT INTO readings (topic, value) VALUES ('{topic}', '{value.json}')"
```

Every supported connector type has a template in the catalog, including the [gRPC connector](/latest/lot-language/routes/streaming/grpc). See the [Connectors Overview](/latest/lot-language/routes/overview) for the full list of types and their documentation.

***

## Next Steps

> **[Connectors Configuration](/hub/routes/configuration)**
>
> Edit connectors with Visual or LoT mode.

> **[LoT Connectors](/latest/lot-language/routes/overview)**
>
> Learn connector syntax and available connector types.


# Broker Logs
Source: https://docs.coreflux.org/hub/system/broker-logs

View broker logs, filter by level and date, search, and export as JSON or LOG

![Coreflux HUB Broker Logs window with an entries count, a Level dropdown set to All, a Search logs field, From and To date pickers, refresh, download and clear icons, and a table with Level, Time, and Description showing an Info entry](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/broker-logs-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=db46094ae91877df9c37d0c2fccaf995)

Broker Logs with level filter, search, date range, and refresh, export, and clear controls

## Why Use Broker Logs?

You need to see what the broker is doing—startup messages, connection events, errors, warnings. The Broker Logs in the Coreflux HUB show broker-wide logs with filtering, search, and export so you can troubleshoot and audit broker activity.

## When to Use It

* **Troubleshooting** — Find errors or warnings related to broker startup or connections
* **Auditing** — Review broker activity over a date range
* **Exporting** — Save logs as JSON or LOG for offline analysis or support

***

## Filter by Level

Use the **All Levels** dropdown to filter logs by severity:

| Level | Description |
| - | - |
| **All Levels** | Show all log entries |
| **Information** | Informational messages |
| **Warning** | Warnings |
| **Error** | Errors |
| **Critical** | Critical failures |

## Search for Keyword

Use the **Search logs...** field to search for specific text in log messages. Enter a keyword or phrase to filter the displayed logs.

## Export

Export logs in two formats:

* **JSON** — Structured export for parsing or integration
* **LOG** — Plain text log file

Click **Export** to download the filtered logs.

## Control Refresh Rate

Use the refresh control to set how often logs update:

| Option | Description |
| - | - |
| **Sync** | Real-time updates (continuous) |
| **1s** | Refresh every 1 second |
| **5s** | Refresh every 5 seconds |
| **10s** | Refresh every 10 seconds |

## Filter by Date

Use the **From** and **To** date fields to limit logs to a specific time range. Enter dates (and optionally times) to filter the displayed entries.

## Status Indicators

The Broker Logs view shows status such as:

* **Connected** — HUB is connected to the broker
* **Logging Initialized** — Logging is active

## Clear Logs

Use **Clear** to remove displayed logs from the view. This does not affect the broker—it only clears the HUB display.

***

## Next Steps

> **[MQTT Broker](/latest/mqtt-broker/overview)**
>
> Learn about the Coreflux MQTT Broker.

> **[Introduction to LoT](/latest/lot-language/introduction)**
>
> Learn the fundamentals of the Language of Things and how it works.


# Command Console
Source: https://docs.coreflux.org/hub/system/command-console

Execute broker commands directly from the Coreflux HUB

![Navigating to the Command Console in the Coreflux HUB by selecting System in the top navigation and clicking Command Console](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/command-console/open-command-console.gif?s=c904f3e9adcf5549f006772cc8e3e28f)

Opening the Command Console from the Coreflux HUB System menu

## Why Use the Command Console?

You need to run broker commands—add Actions, remove Connectors, or perform other operations—without connecting an external MQTT client. The Command Console lets you execute broker commands directly from the Coreflux HUB.

## When to Use It

* **Adding entities** — Send `-addAction`, `-addConnector` (or `-addRoute`), or similar commands
* **Removing entities** — Send `-removeAction`, `-removeConnector` (or `-removeRoute`), etc.
* **Other operations** — Any command supported by the broker's command topic

***

## How It Works

The Command Console sends your input to `$SYS/Coreflux/Command`. The broker replies with a JSON envelope on `$SYS/Coreflux/Command/Output`, which the HUB displays.

You do not need to:

* Subscribe to the command topic yourself
* Use an external MQTT client (for example, MQTT Explorer)
* Publish from the command line

Use `-requestId` when you send several commands in a row and need to tell the replies apart. The full command list is in [Broker Commands](/latest/mqtt-broker/commands).

![Coreflux HUB Command Console window with Connected and Output subscribed in the header, the Coreflux Command Console v1.0 banner, a timestamped Broker output JSON response and Subscribed to command output topic line, and the Enter command input with a send button](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/command-console/command-console-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=3249ddb1694a4e4df02c2066a1ad3564)

Command Console with a connected status, a broker response, and the command input at the bottom

## Entering Commands

1. In the HUB top navigation, select **System**, then **Command Console**.
2. Enter the command in the input field (e.g., `-addAction DEFINE ACTION ...`).
3. Send the command. The broker processes it and returns a result.

***

## Next Steps

> **[MQTT Broker Commands](/latest/mqtt-broker/commands)**
>
> Learn available broker commands and syntax.

> **[Broker Logs](/hub/system/broker-logs)**
>
> View command execution logs.


# System Configuration
Source: https://docs.coreflux.org/hub/system/configuration

Edit broker settings, environment variables, secrets, licenses, and the MCP Server in the Coreflux HUB

![Navigating to System Configuration in the Coreflux HUB by selecting System in the top navigation and clicking System Config](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/configuration/open-system-configuration.gif?s=ffa83aea0901586d1be5c6913918342f)

Opening System Configuration from the Coreflux HUB System menu

## Why Use System Configuration?

You need to change broker settings—ports, TLS, connection limits, or other parameters—without editing configuration files. The System Configuration in the Coreflux HUB lets you view and modify broker settings from the browser.

## When to Use It

* **Adjusting ports** — Change MQTT, TLS, or WebSocket ports
* **TLS configuration** — Enable or configure TLS for secure connections
* **Binding settings** — Control which IP addresses the broker listens on
* **License and enrollment** — Activate with a code or signed file, refresh a lease, enroll the broker in an organization. Register at [portal.coreflux.org](https://portal.coreflux.org) for a 30-day Growth-type license and to manage your fleet
* **MCP Server** — Enable the listener, restrict advertised tools, and mint client tokens
* **Other broker options** — Any configurable broker parameter exposed in the UI

> [!WARNING]
>
> Changes made here are sent to `$SYS/Coreflux/Config/New`. The broker processes these changes, and some may require a manual restart or sysadmin intervention to apply. The displayed configuration reflects `$SYS/Coreflux/Config`.

***

## Accessing System Configuration

In the HUB top navigation, select **System**, then **System Configuration**. The configuration panel shows available settings grouped by category.

## Configuration Panel

The **Broker Settings** window groups settings into tabs: **General**, **Certificates** (HUB 2.12 with broker 2.22, see [Certificates](/hub/system/certificates)), **Variables & Secrets**, **License**, and **MCP Server**. The **General** tab displays broker settings as editable form fields, organized into groups.

> [!NOTE]
>
> Dock layout, memory limits, viewer refresh, and video wallpaper belong to this HUB install. Open **Hub Settings** from the account pill. See [Desktop shell](/hub/overview#hub-settings).

![Coreflux HUB Broker Settings window with General, Variables & Secrets, License, and MCP Server tabs; the General tab shows Broker Name, MQTT, TLS, WebSocket and WebSocket TLS ports, Allow persistent sessions and Max pending messages, bind IPs, and Security toggles for Allow Anonymous Login, Full Debug Logging, and Resend Retained Topics](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/configuration/broker-settings-general-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=c1e0f8a28487a2c9d14a0092930c50f6)

Broker Settings: General tab with Identity, Network, MQTT Sessions, Binding, and Security groups

| Group | Settings |
| - | - |
| **Identity** | Broker Name |
| **Network** | MQTT Port, TLS Port, WebSocket Port, WebSocket TLS Port |
| **MQTT Sessions** | Require clean sessions, Max pending messages |
| **Binding** | MQTT Bind IP, MQTT TLS Bind IP, WebSocket Bind IP, WebSocket TLS Bind IP |

Edit values as needed and click the save button to apply changes. Use the import and export icons in the top-right of the General group to upload or download the configuration.

***

## ENV Variables & Secrets

The **ENV & Secrets** tab is where you keep reusable values out of your Actions and Connectors. Instead of typing the same database address or API key in every place that needs it, you save it once here and reference it by name. When the value changes, you update it in one spot.

> [!TIP]
>
> **Like a notebook and a vault.** ENV Variables are the notebook -- quick to read and easy to update for things like a server address. Secrets are the vault -- locked away and only used by the broker, perfect for passwords and API keys.

> [!NOTE]
>
> For advanced topics like encryption keys, Docker and Kubernetes deployment, CLI commands, and the full LoT (Language of Things) syntax, see [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env).

### ENV Variables

ENV Variables hold plain text values that anyone with access to the HUB can read. Use them for things that change between environments but aren't sensitive -- a database hostname, a port number, an API base URL, or a feature flag.

![Variables & Secrets tab in the Coreflux HUB Broker Settings window with the Variables sub-tab selected, the GET ENV hint, a NAME and VALUE table of variables, and an inline row at the bottom with e.g. DB\_HOST and e.g. postgres.example.com placeholders](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/configuration/broker-settings-variables-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=0aa4cf0e93a4d6d37fe3aeeae2c5f3e6)

Variables list in the Variables & Secrets tab, with the inline add row at the bottom

#### Adding a Variable

**1. Use the inline row**

The last row of the Variables table is always an empty add row, with `e.g. DB_HOST` and `e.g. postgres.example.com` as placeholders.

**2. Fill in the name and value**

Type a clear name like `DB_HOST` in the first field and its value, for example `postgres.example.com`, in the second.

**3. Save**

Press **Enter** or click the check mark at the end of the row. The variable is saved to the broker and shows up in the list.

#### Managing Existing Variables

Hover over any row in the list to reveal three quick actions on the right side:

| Action | What it does |
| - | - |
| **Copy value** | Copies the current value to your clipboard so you can paste it elsewhere. |
| **Edit** | Reopens the form so you can change the value. The name stays the same. |
| **Delete** | Permanently removes the variable. Anything that uses it stops finding the value. |

> [!TIP]
>
> The hint at the top of the list -- *In LoT: GET ENV "NAME" -- Drag onto a Storage card field* -- shows you how to use the variable later when you build Actions or Connectors.

### Secrets

Secrets hold sensitive values that should never be shown again after you save them. The HUB encrypts them at rest, so even an administrator looking at the list only sees dots where the value should be. Use Secrets for passwords, API keys, tokens, and any other credentials.

![Variables & Secrets tab in the Coreflux HUB Broker Settings window with the Secrets sub-tab selected, 0 secrets, the note This broker has no secrets, an inline row with e.g. API\_KEY and New value — press Enter, and the AES-256-GCM encrypted at rest notice](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/configuration/broker-settings-secrets-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=7d0be9ff0fa7a76be7926f66b1dfd1a6)

Secrets list in the Variables & Secrets tab: values are never readable again after saving

#### Adding a Secret

**1. Use the inline row**

Switch to the **Secrets** sub-tab. The last row of the table is an empty add row with `e.g. API_KEY` as the name placeholder and a hidden value field.

**2. Fill in the name and value**

Type a clear name like `API_KEY` and paste the value into the hidden field. The note below the table reminds you that values are *AES-256-GCM encrypted at rest* and *never readable again after saving*.

**3. Save**

Press **Enter**. The secret shows up in the list with its value masked.

#### Managing Existing Secrets

Hover over any row in the list to reveal two quick actions on the right side:

| Action | What it does |
| - | - |
| **Set a new value** | Opens the form so you can overwrite the secret with a new value. There is no way to view the current one. |
| **Delete** | Permanently removes the secret. Anything that uses it stops finding the value. |

> [!WARNING]
>
> Once a secret is saved or deleted its original value cannot be recovered -- not even by an administrator. If you lose a credential, set a new value or remove it and create it again with the correct value.

***

## MCP

The **MCP** tab turns the broker's [MCP Server](/latest/mqtt-broker/mcp-server) on, edits its listen settings, and mints access tokens so Cursor, Claude Code, or Claude Desktop can call broker tools as a broker user.

HUB itself is **not** an MCP client. This tab writes the `Mcp` block through the same save-and-restart path as the System tab, and runs `-createMcpToken` / `-listMcpTokens` / `-revokeMcpToken` over the command envelope.

> [!NOTE]
>
> Older brokers have no `Mcp` key in `$SYS/Coreflux/Config` and no retained `$SYS/Coreflux/MCP/Info`. The tab explains that the feature is absent and does not write a block the broker would drop. Update the broker first.

### Server

The tab shows **Enabled**, a status dot (**Listening**, **Disabled**, or **Pending restart**), the endpoint URL with a copy button, plus **Port**, **Bind IP**, and **Endpoint**.

The broker applies the `Mcp` block at **startup**. Saving **Enabled** does nothing until you restart the broker. HUB cannot restart it for you.

A bind outside loopback shows an amber note: bearer tokens cross the network in clear text, so put TLS in front. HUB does not configure TLS for this listener.

### Tools

**Expose all tools** maps to `Mcp.EnableAllTools`. When it is off, only the allow-list is advertised. The picker is seeded from the advertised Streamable HTTP catalogue (not only `$SYS/Coreflux/MCP/Tools`, which lists tools the *running* server currently exposes and can be empty). Use advertised names (`get_route_template`), not command tokens (`route_code`). Add `action_*` names with **Custom tool**.

**Token lifetime** is the default TTL in days for new tokens (`0` never expires). **Advanced** holds **Server name** and **Server version**.

### Tokens

When the server is enabled and no active token exists, the tab warns that every request is `401` while the listener stays up.

**1. Create a token**

Click **Create token**. Pick a broker user (tool calls run with that user's RBAC — prefer a least-privilege account), a name **without whitespace**, and an optional lifetime in days.

**2. Copy the value immediately**

The plaintext is returned **once**. Copy it from the dialog. HUB does not write it to the connection log, a store, or disk. Closing the dialog clears it.

**3. Paste a client snippet**

The result view offers **Claude Code** (`.mcp.json`), **Cursor** (`.cursor/mcp.json`), and **Claude Desktop** snippets. Every snippet includes `"type": "http"` and `Authorization: Bearer …`. Claude Code and Claude Desktop skip an entry that has a `url` but no `type`, with no error.

When the broker binds `0.0.0.0`, the URL on `$SYS/Coreflux/MCP/Info` is not reachable as written. HUB substitutes the host it is itself connected to; a loopback bind is used verbatim.

The token table shows name, user, created, expires, last used, and state. **Revoke** refuses clients immediately. Filter the list by user if needed.

Broker refusals (`McpTokenManagement`, unknown user, already-revoked) are shown verbatim. Timeouts say the broker did not respond — token commands use `McpTokenManagement`, not `AllowedSystemConfiguration` alone.

***

## License

The **License** tab reads the retained `$SYS/Coreflux/License` topic and sends the four broker commands: `-activateLicense`, `-loadLicense`, `-refreshLicense`, and `-enroll`. The HUB never verifies a license itself — it displays what the broker reports.

The status bar, this tab, and the fleet pills share one set of labels: **Trial**, **Trial (Growth)**, and **Licensed (Growth)**.

The broker always starts. With no license it runs as **Community**. The HUB does **not** start a trial. Register at [portal.coreflux.org](https://portal.coreflux.org) for a **30-day Growth-type license**, then paste the activation code (or drop the signed file) on this tab. Use the same portal to **manage your fleet of brokers**, and open that fleet from the HUB login card after you [sign in with a Coreflux account](/hub/account-and-fleet).

Cards, top to bottom:

| Card | What you see |
| - | - |
| **Status** | The license label (**Trial**, **Trial (Growth)**, or **Licensed (Growth)** — the plan in parentheses), plus licensed-to and expiry. An **online lease** also shows last-validated age, lease expiry, seat mode, and a **Refresh** button (`-refreshLicense`). An **offline license** shows the source the broker used. With no license the card reads **Running as Community** with the artifact and connector limits from `EffectiveLimits`. |
| **Usage** | Progress bars for **Artifacts** (Models, Actions, Scripts, Panels, Rules) and **Connectors** versus the license limit. |
| **Features** | Premium features with a check when the license unlocks them (advanced connectors, RBAC, cluster, and related gates). |
| **Activate** | A two-option switch. **Activation code** is a `CFLX-…` field and an **Activate** button (`-activateLicense`). **License file** shows the broker host's hardware fingerprint (copy button) and a drop zone that accepts `.jws`, `.license`, and `.txt` — the contents must be a signed compact JWS, which the HUB sends as `-loadLicense`. |
| **Organization enrollment** | **Enrolled**, plus the bound organization id, when `Enrollment.Enrolled` is true or `Enrollment.BoundOrg` is set. **Not enrolled** when `Enrolled` is `false`. **Enrollment pending**, with the broker's reason sentence, while enrollment is pending. **Enrollment not reported** on older payloads that only have `{ Pending, Reason }`. The `et_…` token field (`-enroll`) stays available in every state. |

> [!NOTE]
>
> `Enrollment.Pending: false` means the broker has not recorded a problem — not that it is bound to an organization. The card uses `Enrollment.Enrolled` and `Enrollment.BoundOrg` as the source of truth for **Enrolled**. Manage the fleet at [portal.coreflux.org](https://portal.coreflux.org). The token field stays available until the card shows **Enrolled**.

### Activate with a code (online)

**1. Get an activation code**

Register at [portal.coreflux.org](https://portal.coreflux.org) for a license — including a 30-day Growth-type trial. Then paste the `CFLX-…` activation code on this tab. The broker must be able to reach `https://license.coreflux.org`.

**2. Paste and activate**

On the License tab, choose **Activation code**, paste the code, and click **Activate**. Limits apply immediately — no broker restart.

**3. Confirm status**

The status card refreshes from the next retained `$SYS/Coreflux/License` payload. Use **Refresh** later to pick up a plan change without waiting for the daily lease timer.

### Install a signed file (offline)

**1. Copy the fingerprint**

On the **License file** option, copy the hardware fingerprint shown above the drop zone. Send it to Coreflux so the signed license can be bound to that broker host. If the source is `hostname+mac` (typical in containers), the fingerprint can change when the container is recreated.

**2. Drop the signed file**

Save the signed license Coreflux issued. Drop a `.jws` file (`.license` and `.txt` extensions are accepted for the same JWS text). The HUB strips wrapping whitespace and sends the token to the broker.

**3. Confirm binding**

Status should show an offline license. If the broker replies that the license file was not found and the path starts with `eyJ`, this broker is too old to accept JWS text over MQTT — update the broker, or install on the host with `--load-license`.

### Enroll in an organization

Enrollment is separate from the plan. Paste a one-shot `et_…` token. Treat it as done when the card shows **Enrolled** and the bound organization — `Enrollment.Pending` clearing is not enough. **Not enrolled** means the broker published `Enrolled: false`. **Enrollment pending** shows the broker's reason sentence. **Enrollment not reported** means this payload only has `{ Pending, Reason }` (typical of an older broker). The token field stays reachable in every state. Local users keep working while enrollment is pending; federated logins that need an org binding are refused. Manage the fleet at [portal.coreflux.org](https://portal.coreflux.org).

Full operator reference, including `GET /license` and process environment variables: [Licensing and Enrollment](/latest/mqtt-broker/licensing).

> [!WARNING]
>
> If a feature you need stays disabled after activation, the license does not include it — refresh the lease, or contact Coreflux for a different plan. A signature-valid license the broker refused to honour (`BindingOk` false or tampering detected) looks like Community until you fix the binding.

***

## Next Steps

> **[Licensing and Enrollment](/latest/mqtt-broker/licensing)**
>
> Activation codes, signed licenses, enrollment, and `GET /license`.

> **[MCP Server](/latest/mqtt-broker/mcp-server)**
>
> Enablement, endpoints, tokens, and `$SYS/Coreflux/MCP` topics.


# System Overview
Source: https://docs.coreflux.org/hub/system/overview

Broker administration, user management, command console, and broker logs

![Animated overview of the Coreflux HUB System section showing System Configuration, User Management, Command Console, and Broker Logs tools](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/system-overview.gif?s=0368e951dcbd30549346ecd0e8227094)

System section in the Coreflux HUB — broker administration, user management, command console, and logs

## Why Use the System Section?

You need to administer your broker—configure settings, manage users, run commands, and view broker logs. The System section of the Coreflux HUB provides tools for broker administration, monitoring, and debugging in one place.

## When to Use Each Tool

| Tool | Use When |
| - | - |
| **System Configuration** | Changing broker settings, connection parameters, ENV/secrets, license, or the MCP Server |
| **User management** | Creating, editing, or deleting users; managing credentials and access control |
| **Command Console** | Sending commands directly to `$SYS/Coreflux/Command` without an external MQTT client |
| **Broker Logs** | Viewing broker-wide logs, filtering by level, searching, and exporting |

***

## System Tools

> **[System Configuration](/hub/system/configuration)**
>
> Broker settings, ENV and secrets, license, and the MCP Server.

> **[User Management](/hub/system/user-management)**
>
> Create, edit, and delete users; manage credentials.

> **[Command Console](/hub/system/command-console)**
>
> Execute broker commands via the HUB.

> **[Broker Logs](/hub/system/broker-logs)**
>
> View broker logs, filter by level and date, export.

***

## Next Steps

> **[System Configuration](/hub/system/configuration)**
>
> Configure broker settings.

> **[MQTT Broker Configuration](/latest/mqtt-broker/configuration)**
>
> Learn broker configuration options.


# User Management
Source: https://docs.coreflux.org/hub/system/user-management

Create, edit, and delete broker users; manage credentials and access control

![Navigating to User Management in the Coreflux HUB by selecting System in the top navigation and clicking User Management](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/user-management/open-user-management.gif?s=eda7d906fd1b830ab2f547da307bc216)

Opening User Management from the Coreflux HUB System menu

## Why Use User Management?

You need to control who can connect to your broker—add users, set passwords, and manage access. The User Management in the Coreflux HUB lets you create, edit, and delete users without editing configuration files or using command-line tools.

## When to Use It

* **Adding users** — Create new users for devices, applications, or operators
* **Updating credentials** — Change passwords
* **Managing permissions** — Control which features each user can access
* **Removing access** — Delete users who no longer need broker access

For topic-level and group-based access control with LoT Rules, see [RBAC with LoT Rules](/latest/lot-language/rules/rbac).

***

## Accessing User Management

In the HUB top navigation, select **System**, then **User Management**. The user accounts table shows all configured users with their permissions.

![Coreflux HUB User Management window with a 1 user badge, Search users, refresh and add buttons, and a table listing root (You) with Full Access, User Management, and Log Management Enabled plus edit and change password actions, and the note Permission edits apply only after Save](https://mintcdn.com/coreflux/3mb0wROxLOvLuS2Q/images/system/user-management/user-management-light.png?fit=max\&auto=format\&n=3mb0wROxLOvLuS2Q\&q=85\&s=8b3bcf7850921fc5d7fd9da35e59e6fa)

User Management showing the user accounts table with permission badges and action buttons

## User Permissions

Each user has permission flags. The HUB table exposes three toggles that map to broker flags:

| HUB toggle | Broker flag | Description |
| - | - | - |
| **Full Access** | `AllowedSystemConfiguration` | System configuration and broad administrative access |
| **User Management** | `AllowedUserManagement` | Create, edit, and delete other users; manage group membership via MQTT |
| **Log Management** | `AllowedLogManagement` | Access to broker logs, trace logs, and log export |

Toggle permissions on or off for each user. The `root` user has special permissions that cannot be fully modified.

### Groups

Users can belong to named groups used by LoT Rules (`USER IN GROUP`) and Visu panel sharing. Manage groups with MQTT commands (`-addUserToGroup`, `-removeUserFromGroup`, `-listUserGroups`) — see [Broker Commands](/latest/mqtt-broker/commands) and [RBAC](/latest/lot-language/rules/rbac).

## Creating a User

1. Click the **+** button in the top-right corner.
2. The **Add New User** modal opens.

![Coreflux HUB Add New User modal overlaid on the User Management window with the description Create a new user account; the user will be created with default permissions, and three input fields — Username with placeholder Enter username highlighted, Password with placeholder Enter password and a visibility toggle, and Confirm Password with placeholder Confirm password and a visibility toggle — plus Cancel and Add User buttons](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/user-management/user-management-add-user.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=cb276e551ab3b53898123e71231083e6)

Add New User modal with Username, Password, and Confirm Password fields and a Create a new user account description

3. Enter a username and password (with confirmation).
4. Click **Add User**. The user is created with default permissions and can now connect to the broker.

## Editing a User

Toggle permission switches directly in the user table to modify access. When you change a permission, the user row shows a **Modified** badge and action buttons appear:

![Coreflux HUB User Management window with an Important Notice at the top and a System Configuration Updated banner explaining that the system user configuration has been updated while editing and offering to refresh; the User Accounts table shows root with Full Access Enabled and User Management and Log Management Disabled, and test with a Modified badge, Full Access toggled off with an Original: true note, and save, cancel, change password, and delete action icons on the right](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/system/user-management/user-management-modified.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=b6ac9b2093682ebed9db8383271c641c)

User Management with a modified user row and a System Configuration Updated banner, showing save, cancel, change password, and delete actions

| Action | Icon | Description |
| - | - | - |
| **Save** | Floppy disk | Save the modified permissions to the broker |
| **Cancel** | X | Revert unsaved changes |
| **Change Password** | Key | Update the user's password |
| **Delete** | Trash | Remove the user from the broker |

The header bar shows badges for **modified** users and **System Updated** status when the broker configuration changes while you are editing.

## Deleting a User

Click the delete (trash) icon next to a user and confirm the deletion. The `root` user cannot be deleted.

***

## Next Steps

> **[RBAC with LoT Rules](/latest/lot-language/rules/rbac)**
>
> Groups, permission flags, and topic access rules.

> **[MQTT Broker Configuration](/latest/mqtt-broker/configuration)**
>
> Learn about authentication and security options.


# How to Debug in LoT Notebooks
Source: https://docs.coreflux.org/lot-notebooks/debug

Debug LoT and MQTT data with a Data Viewer and an Execution _Trace.

![Animated walkthrough of the LoT Data Viewer in VS Code: subscribing to topics and viewing live MQTT traffic](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-basic.gif?s=7124718aa0d1a06105dd56a905f1a177)

Data Viewer: subscribe to topics and watch live MQTT data

## Overview

Debugging in LoT Notebooks means confirming **data is moving on the right topics** and **your logic behaves as intended**. The extension includes a **Data Viewer** and an **Execution Trace** tied to each **LoT cell** so you can see data, replay flows and inspect every related **topic** and **variable**.

> [!TIP]
>
> Without the right view, you are mostly in the **dark** — you write code hoping nothing goes wrong. The **Data Viewer** and the **execution trace** light up the room, **showing what that code actually did**.

***

## Data Viewer

![Animated walkthrough of the LoT extension Data Viewer: topic tree, message history, replay, and payload formatters](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-advanced.gif?s=68e85cdf93ebe2ce5c24a87b66d50544)

Data Viewer: topic tree and replay viewer with live data and history replay

Inside **Coreflux Explorer**, the Data Viewer has two parts that work together:

### Topic Tree Viewer

![LoT MQTT Topic Tree Viewer, showing topic hierarchy and MQTT Payloads](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-topic-tree.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=561af3decf708f1924c73ee7ce92a44a)

LoT MQTT Topic Tree Viewer, showing topic hierarchy and MQTT Payloads

The **topic tree** gives you a **quick glance** at your hierarchy and **live values** as messages arrive—handy for spotting whether a sensor topic or alert is updating, without needing to open a separate tool.

Use **Subscribe to All topics** when you want the tree to show all broker data, and **Subscribe to a topic** when you want to focus on specific information.

### Replay Data Viewer

![LoT Data Viewer showing JSON formatter with syntax highlighting, topic tab, message count, and timeline replay controls](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-json.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=89cb011008958531b30e05dda02a2a14)

Data Viewer: data payload, topic tabs, timeline, and replay controls

**Click a topic in the tree** to open the **full Data Viewer** for that stream. There you get:

* **Message history** and a **multi-topic** layout so you can follow several related topics at once
* **Replay** controls to move through captured messages over time
* A **data formatter** so you can interpret payloads the way they were meant to be read—pick the view that matches how the payload is encoded

Use this when you need to inspect structure, compare payloads, or see the data history — not just see that “something changed” on a topic.

#### Adjust how you see the data

Choose a formatter after opening a topic. The full viewer supports **multiple topics**, a **message history**, **replay** (timeline and playback controls), and **data views** such as raw, JSON, Protobuf, geopoint, image, audio and PDF.

Each topic keeps its last **100** messages by default. Change it with the gear on the timeline, or the `coreflux.dataViewer.historyBufferPerTopic` setting (50 to 2000). Open topics are never pruned, and history holds still while you're scrubbing instead of following **Live**.

![LoT Data Viewer Geopoint formatter showing geographic coordinates plotted on a map](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-map.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=ffd3ec12cd15adcb8f40aa465879ba10)

Data Viewer Geopoint formatter: coordinates on a map

***

## Execution trace

![Animated walkthrough of the LoT extension execution trace showing cell-related topics and variables, timeline, and replay](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lot-trace.gif?s=117a51b175bb962e2f81c13cf341716d)

Execution trace: topics and variables for the LoT cell, with timeline and replay

The **execution trace** lets you **see every topic and variable** the cell touches—publishes, subscriptions, and related state—in one place, follow a **time-ordered history** of messages across them, and use **replay** with playback controls and a **timeline** to play, pause, and scrub the run. That way you can confirm execution order, timing, and which step produced which message when logic spans several topics.

It is scoped to the **LoT cell** you are debugging, so you stay with that cell’s footprint on the broker instead of hunting traffic across the whole system.

***

## Troubleshooting

When the viewer or trace does not match what you expect, open the sections below.

> **Broker connection issues**
>
> If cells fail immediately or never show a response, verify credentials and network first.
>
> 1. Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`) or use the connection control in the activity bar / status area as shown in your setup.
> 2. Run **LoT Notebook: Change Credentials** and enter your broker URL, username, and password.
> 3. Watch the status bar for a connected state before running cells.
>
> ![Animated walkthrough of entering broker credentials and connecting in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-broker-connect.gif?s=faf63084741fb786ec1807145f691a89)
>
> Updating broker credentials in the LoT Notebooks extension
>
> * Default credentials and TLS notes: [LoT Notebooks setup guide](/latest/quick-start/vscode)
> * Confirm the broker is reachable (host, port, firewall, TLS if using `mqtts://`)

> **Cell run output and errors**
>
> When you click **Run** on a LoT cell, the extension sends the definition to the broker and shows the result directly below the cell.
>
> ![Animated walkthrough of clicking the Run button to deploy the action to the broker](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-deploy-basic-action.gif?s=d7edcd18dc774cad66ff4969543e29ae)
>
> Running a cell to deploy a LoT definition to the broker
>
> | What you see | What it means |
> | - | - |
> | Success message / green check | The broker compiled and registered the entity (Action, Model, Connector, or Rule). |
> | Error text | Often syntax, indentation, or broker-side validation—read the full message for line hints when provided. |

## Related guides

> **[How to Use a LoT Notebook](./usage)**
>
> Cell execution, commands, broker topics, and troubleshooting accordions.

> **[Introduction to LoT](/latest/lot-language/introduction)**
>
> What LoT is, how it runs in the broker, and simple examples to build on.


# File Format
Source: https://docs.coreflux.org/lot-notebooks/file-format

Understand the .lotnb file structure, cell types, and how to create notebooks.

## The .lotnb Format

LoT Notebook files use the `.lotnb` extension and follow a JSON-based structure compatible with VS Code's notebook API. Each file contains an array of cells—documentation and code blocks that make up your notebook.

> [!NOTE]
>
> You don't need to edit the JSON directly. VS Code's notebook interface handles the structure automatically. This page is for understanding what's happening under the hood.

***

## File Structure

A `.lotnb` file is a JSON array where each element represents a cell:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "kind": 1,
    "language": "markdown",
    "value": "# My First Notebook\n\nThis is a markdown cell with documentation."
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION Heartbeat\nON EVERY 10 SECONDS DO\n    PUBLISH TOPIC \"system/heartbeat\" WITH TIMESTAMP \"UTC\""
  },
  {
    "kind": 2,
    "language": "python",
    "value": "# Script Name: DataProcessor\ndef calculate_average(values):\n    return sum(values) / len(values)"
  }
]
```

***

## Cell Properties

Each cell has three required properties:

| Property | Type | Description |
| - | - | - |
| `kind` | integer | Cell type: `1` = Markdown, `2` = Code |
| `language` | string | Cell language: `"markdown"`, `"lot"`, or `"python"` |
| `value` | string | Cell content (use `\n` for line breaks) |

### Kind Values

| Kind | Type | Purpose |
| - | - | - |
| `1` | Markdown | Documentation, explanations, headers |
| `2` | Code | Executable LoT or Python code |

### Language Values

| Language | Cell Kind | Description |
| - | - | - |
| `markdown` | 1 | Rich text documentation |
| `lot` | 2 | LoT definitions (Actions, Models, Connectors, Rules) |
| `python` | 2 | Python scripts for broker execution |

***

## Cell Types in Detail

### Markdown Cells

Markdown cells support standard Markdown syntax plus some extensions:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "kind": 1,
  "language": "markdown",
  "value": "## Temperature Monitoring System\n\nThis notebook implements a complete temperature monitoring solution:\n\n- **Sensors**: Read from `sensors/+/temperature`\n- **Alerts**: Publish to `alerts/high-temp` when threshold exceeded\n- **Logging**: Store all readings in database\n\n### Architecture\n\n| Component | Topic | Purpose |\n|-----------|-------|--------|\n| Sensor Reader | sensors/+/temperature | Ingest data |\n| Alert Generator | alerts/+ | Notify operators |"
}
```

**Supported Markdown features:**

* Headers (`#`, `##`, `###`)
* Bold, italic, code formatting
* Bullet and numbered lists
* Tables
* Code blocks (for examples, not execution)
* Links and images

### LoT Code Cells

LoT cells contain executable Language of Things definitions:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "kind": 2,
  "language": "lot",
  "value": "DEFINE ACTION TemperatureMonitor\nON TOPIC \"sensors/+/temperature\" DO\n    SET \"sensor_id\" WITH TOPIC POSITION 2\n    IF PAYLOAD > 80 THEN\n        PUBLISH TOPIC \"alerts/high-temp/\" + {sensor_id} WITH \"Critical: \" + PAYLOAD + \"°C\""
}
```

**Valid LoT definitions:**

| Definition | Syntax |
| - | - |
| Action | `DEFINE ACTION ActionName` |
| Model | `DEFINE MODEL ModelName WITH TOPIC "..."` |
| Connector | `DEFINE CONNECTOR ConnectorName WITH TYPE ...` (`DEFINE ROUTE` remains an alias) |
| Rule | `DEFINE RULE RuleName` |

### Python Cells

Python cells contain scripts that run inside the broker when called from LoT:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
{
  "kind": 2,
  "language": "python",
  "value": "# Script Name: Validators\ndef validate_temperature(value, min_temp, max_temp):\n    \"\"\"Check if temperature is within acceptable range\"\"\"\n    try:\n        temp = float(value)\n        return {\n            \"valid\": min_temp <= temp <= max_temp,\n            \"value\": temp,\n            \"range\": f\"{min_temp}-{max_temp}\"\n        }\n    except (ValueError, TypeError):\n        return {\"valid\": False, \"error\": \"Invalid temperature value\"}"
}
```

> [!WARNING]
>
> **Required format**: Python scripts must start with `# Script Name: YourScriptName` as the first line. This header tells the broker how to register and reference the script.

***

## Creating a New Notebook

### Method 1: VS Code Interface

1. Create a new file with `.lotnb` extension
2. VS Code automatically opens it in notebook mode
3. Use the **+ Code** and **+ Markdown** buttons to add cells
4. Select cell language from the dropdown (lot, python, markdown)

### Method 2: Manual Creation

Create a file with minimal JSON structure:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "kind": 1,
    "language": "markdown",
    "value": "# My Notebook\n\nAdd your documentation here."
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION MyFirstAction\nON EVERY 10 SECONDS DO\n    PUBLISH TOPIC \"test/hello\" WITH \"Hello World\""
  }
]
```

Save with `.lotnb` extension and open in VS Code.

***

## Example: Complete Notebook

Here's a full example showing all cell types working together:

```json wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
[
  {
    "kind": 1,
    "language": "markdown",
    "value": "# Production Monitoring System\n\nThis notebook implements production line monitoring with:\n- Real-time part counting\n- Quality validation using Python\n- Alert generation for anomalies"
  },
  {
    "kind": 1,
    "language": "markdown",
    "value": "## Python Validators\n\nFirst, we define our validation functions:"
  },
  {
    "kind": 2,
    "language": "python",
    "value": "# Script Name: QualityChecker\ndef check_dimensions(length, width, tolerance=0.5):\n    \"\"\"Validate part dimensions against specifications\"\"\"\n    target_length = 100.0\n    target_width = 50.0\n    \n    length_ok = abs(float(length) - target_length) <= tolerance\n    width_ok = abs(float(width) - target_width) <= tolerance\n    \n    return {\n        \"passed\": length_ok and width_ok,\n        \"length_deviation\": float(length) - target_length,\n        \"width_deviation\": float(width) - target_width\n    }"
  },
  {
    "kind": 1,
    "language": "markdown",
    "value": "## Part Counter Action\n\nCounts produced parts and tracks hourly production:"
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION PartCounter\nON TOPIC \"production/line1/part-complete\" DO\n    SET \"count\" WITH (GET TOPIC \"production/line1/count\" AS INT) + 1\n    PUBLISH TOPIC \"production/line1/count\" WITH {count}\n    PUBLISH TOPIC \"production/line1/last-update\" WITH TIMESTAMP \"UTC\""
  },
  {
    "kind": 1,
    "language": "markdown",
    "value": "## Quality Check Action\n\nValidates each part using our Python function:"
  },
  {
    "kind": 2,
    "language": "lot",
    "value": "DEFINE ACTION QualityValidator\nON TOPIC \"production/line1/measurement\" DO\n    SET \"length\" WITH (GET JSON \"length\" IN PAYLOAD AS DOUBLE)\n    SET \"width\" WITH (GET JSON \"width\" IN PAYLOAD AS DOUBLE)\n    \n    CALL PYTHON \"QualityChecker.check_dimensions\"\n        WITH ({length}, {width})\n        RETURN AS {result}\n    \n    IF (GET JSON \"passed\" IN {result} AS BOOL) EQUALS TRUE THEN\n        PUBLISH TOPIC \"production/line1/quality/passed\" WITH {result}\n    ELSE\n        PUBLISH TOPIC \"production/line1/quality/failed\" WITH {result}\n        PUBLISH TOPIC \"alerts/quality\" WITH \"Part failed inspection\""
  }
]
```

***

## Best Practices

> **Use descriptive markdown headers**
>
> Start notebooks with a title and overview. Use headers to organize sections logically.

> **One definition per code cell**
>
> Keep each Action, Model, Connector, or Rule in its own cell. This makes debugging and selective execution easier.

> **Document before you code**
>
> Write a markdown cell explaining what the next code cell does before writing the code. This helps you think through the logic.

> **Use consistent naming**
>
> Follow a naming convention for your Actions, Models, and Python scripts. Example: `SensorTemperatureMonitor`, `ProductionPartCounter`.

***

## Troubleshooting

> **File won't open as notebook?**
>
> * Verify the file has `.lotnb` extension (not `.lotnb.json`)
> * Check that the LoT Notebooks extension is installed
> * Ensure the file contains valid JSON (use a JSON validator)

> **JSON syntax errors?**
>
> Common issues:
>
> * Missing commas between cells
> * Unescaped quotes in `value` strings (use `\"`)
> * Unescaped newlines (use `\n`)
> * Missing closing brackets

> **Cell showing wrong language?**
>
> Check the `language` property matches the content type. VS Code should auto-detect, but you can manually switch using the language selector in the cell toolbar.

***

## Next Steps

> **[Getting Started](/latest/quick-start/getting-started)**
>
> Create your first LoT Action and verify your setup is working.

> **[LoT Language Reference](/latest/lot-language/introduction)**
>
> Explore the complete LoT syntax for Actions, Models, Connectors, and Rules.


# Tutorials
Source: https://docs.coreflux.org/lot-notebooks/tutorials

Hands-on LoT Notebook tutorials covering Actions, Models, Connectors, and Python integration.

## Learn by Building

The best way to master LoT is through hands-on practice. These tutorials are interactive notebooks you can download and run in VS Code—each one builds your skills progressively.

> [!TIP]
>
> **Start with Basics, then branch out.** Complete the Basics tutorials first to understand LoT fundamentals, then explore the topics most relevant to your projects.

***

## Learning Path

Follow this recommended progression from beginner to advanced:

```mermaid theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
flowchart TB
    subgraph Beginner
        direction LR
        A[Timed Actions] --> B[Topic Actions]
    end
    subgraph Intermediate
        direction LR
        C[Conditional Logic] --> D[Basic Models]
        D --> E[Action Models]
        E --> F[Model Inheritance]
    end
    subgraph Advanced
        direction LR
        G[Connectors] --> H[Python]
        H --> I[Architecture]
    end
    Beginner --> Intermediate
    Intermediate --> Advanced
```

***

## Basics

Start here to learn the fundamentals of LoT Actions and event-driven programming.

> **[Timed Actions](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/01-basics/timed-actions.lotnb)**
>
> Create actions that run on schedules—heartbeats, counters, and periodic tasks. Learn `ON EVERY` triggers and state persistence.

> **[Topic Actions](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/01-basics/topic-actions.lotnb)**
>
> React to MQTT messages in real-time. Master `ON TOPIC` triggers, wildcards, and payload processing.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Timed Actions** | `ON EVERY` syntax, time units, `PUBLISH TOPIC`, timestamps, counters |
| **Topic Actions** | `ON TOPIC` triggers, wildcards (`+`, `#`), `PAYLOAD`, topic parsing |

***

## Logic

Build intelligent automation with conditional logic and decision-making.

> **[Conditional Logic](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/02-logic/conditional-logic.lotnb)**
>
> Implement IF/ELSE statements, comparisons, and boolean logic. Build threshold monitors, state machines, and quality control systems.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Conditional Logic** | `IF/ELSE` statements, comparison operators, `AND/OR/NOT`, text matching with `CONTAINS` |

***

## Models

Structure and transform your data with LoT Models.

> **[Basic Models](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/03-models/basic-models.lotnb)**
>
> Define data schemas with typed fields. Create structured sensor readings, equipment status reports, and alarm messages.

> **[Action Models](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/03-models/action-models.lotnb)**
>
> Publish models dynamically from Actions. Combine event-driven logic with structured data output.

> **[Model Inheritance](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/03-models/model-inheritance.lotnb)**
>
> Extend base models to create specialized variants. Build hierarchies for sensors, equipment, and production data.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Basic Models** | `DEFINE MODEL`, field types (STRING, INT, DOUBLE, BOOL), triggers, topic sources |
| **Action Models** | `PUBLISH MODEL`, dynamic field values, combining Actions with Models |
| **Model Inheritance** | `EXTENDS`, base models, field overrides, model hierarchies |

***

## Connectors

Connect your LoT system to external databases and other MQTT brokers.

> **[MQTT Bridge](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/04-routes/mqtt-bridge.lotnb)**
>
> Connect multiple MQTT brokers. Forward messages, sync data between systems, and build distributed architectures.

> **[Database Connectors](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/04-routes/database-routes.lotnb)**
>
> Store MQTT data in SQL databases. Configure connections, map topics to tables, and query historical data.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **MQTT Bridge** | `TYPE MQTT_BRIDGE`, source/destination config, mappings, bidirectional sync |
| **Database Connectors** | `TYPE DATABASE`, connection strings, table mappings, data persistence |

***

## Python Integration

Extend LoT with Python for complex calculations, data processing, and advanced logic.

> **[Simple Python](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/05-python/simple-python.lotnb)**
>
> Get started with Python in LoT. Learn the script format, parameter passing, and return value handling.

> **[Advanced Python](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/05-python/advanced-python.lotnb)**
>
> Build sophisticated data pipelines. Use external libraries, handle JSON, and implement validation logic.

### What You'll Learn

| Tutorial | Key Concepts |
| - | - |
| **Simple Python** | `CALL PYTHON` syntax, script format, parameters, return values |
| **Advanced Python** | JSON processing, external libraries, error handling, complex transformations |

***

## Showcase

Ready-to-run notebooks that combine every LoT entity type in one realistic project. Each one simulates its own data, so the core cells need only a broker.

> **[Flights tracker](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/showcase/01-flights-tracker.lotnb)**
>
> Airport operations: Python, timer and topic actions, models with inheritance, a REST API server, file storage, an MQTT bridge, rules, a panel and an AI agent.

> **[Bottling Line](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/showcase/02-bottling-line.lotnb)**
>
> Factory line: Modbus and OPC UA servers and clients, OEE in Python, Things, rules, a dashboard and a maintenance agent.

> **[Smart Building](https://github.com/CorefluxCommunity/Language-Of-Things-Training/blob/main/showcase/03-smart-building.lotnb)**
>
> Unified namespace with wildcard actions, comfort and energy alarms, a Modbus gateway, a REST webhook, dashboards and two cooperating agents.

> [!NOTE]
>
> In **Bottling Line**, the Thing cells are marked preview: they use `DEFINE THING`, which hasn't shipped yet. Each one has a fallback cell that works on the current broker. Cells under a `[needs: X]` heading are optional and need an extra service, such as Ollama or PostgreSQL.

***

## Quick Reference

Need to review a specific concept? Here's where to find it:

| Concept | Tutorial |
| - | - |
| Time-based triggers | [Timed Actions](#basics) |
| Message triggers | [Topic Actions](#basics) |
| IF/ELSE logic | [Conditional Logic](#logic) |
| Data schemas | [Basic Models](#models) |
| Dynamic publishing | [Action Models](#models) |
| Schema inheritance | [Model Inheritance](#models) |
| Broker bridging | [MQTT Bridge](#connectors) |
| Data storage | [Database Connectors](#connectors) |
| Python scripting | [Simple Python](#python-integration) |
| Advanced processing | [Advanced Python](#python-integration) |
| End-to-end projects | [Flights tracker, Bottling Line, Smart Building](#showcase) |

***

## Download Tutorials

All tutorials are available in the Coreflux Community GitHub repository:

> **[LoT Tutorials Repository](https://github.com/CorefluxCommunity/Language-Of-Things-Training)**
>
> Download complete tutorial notebooks with documentation, examples, and exercises.

### Getting the Tutorials

**1. Clone or Download**

Clone the repository or download as ZIP from GitHub.

**2. Open in VS Code**

Open any `.lotnb` file—VS Code automatically uses the LoT Notebooks extension.

**3. Connect Your Broker**

Configure your broker credentials, then start running cells.

***

## Next Steps

> **[Usage Guide](./usage)**
>
> Master cell execution, broker commands, and troubleshooting.

> **[LoT Language Reference](/latest/lot-language/introduction)**
>
> Explore the complete LoT syntax reference and advanced features.


# How to Use a LoT Notebook
Source: https://docs.coreflux.org/lot-notebooks/usage

Learn how to use LoT Notebooks to run, document and debug your LoT code.

![VS Code with a LoT notebook open showing markdown and LoT code cells, Coreflux Explorer and project tree on the left, Data Viewer below, and MQTT connection in the status bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lotnb.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=9e0cb958c924dad253919f3ff09f828a)

LoT Notebook workspace in VS Code: editor, Coreflux Explorer, Project, and Data Viewer

## The Notebook Workflow

LoT Notebooks combine **Documentation in Markdown** and **LoT code** in a **single file**, so you can both run your code and keep your documentation together, using the notebook as **living documentation** for your project.

> [!TIP]
>
> **Picture a smart kitchen:** **Markdown** is the recipe on the page, each **LoT code** cell is how you run each step of the recipe, and the **Data Viewer** shows you the results of each step.

***

## Install and connect

**1. Install the extension**

![Animated walkthrough: VS Code Extensions view, search for coreflux, install Coreflux LoT, Coreflux icon appears in the Activity Bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-installation.gif?s=3a2aa4cdbaf895e94e9954d6c45b7abf)

Extensions marketplace: search for Coreflux and install LoT Notebooks

1. Open VS Code.
2. Open the Extensions view in the sidebar (or use the shortcut `Ctrl+Shift+X` on Windows/Linux, `Cmd+Shift+X` on macOS).
3. Search for **LoT Notebooks** by **Coreflux** and install it.

**2. Connect to the broker**

![VS Code: connect to MQTT broker via LoT extension; status bar shows MQTT connected](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-broker-connect.gif?s=faf63084741fb786ec1807145f691a89)

Connect to the broker: pick credentials or connect from the Data Viewer

1. Click the **MQTT** connection status in the bottom-left of VS Code, or click **Connect to Broker** in the **Data Viewer** (Coreflux sidebar).
2. Enter your broker **URL**, **username**, and **password**.

> **Example URL and default login credentials**
>
> Use a full URL such as `mqtt://localhost:1883` or `mqtts://your-host:8883` for TLS.
>
> | Setting | Example (local defaults) |
> | - | - |
> | URL | `mqtt://localhost:1883` |
> | Username | `root` |
> | Password | `coreflux` (change immediately in production) |

When you are connected, the status bar shows a green **MQTT: Connected**. If any issues occur, the status bar will become red.

> [!NOTE]
>
> The extension securely stores your credentials. You only need to configure them once per workspace.

***

## Create a new project

![Animated walkthrough: creating a new .lotnb file from the Coreflux PROJECT section in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-lotnb-create-new.gif?s=6f76d28d7999e12459a044e460d414bc)

Creating a new LoT Notebook from the Coreflux PROJECT view

1. In the Activity Bar, open the **Coreflux** view. Under **PROJECT**, use **New File** to create a notebook and save it in your workspace (use **New Folder** first if you want a dedicated project folder).
2. In the notebook, add **Markdown** and **LoT** cells from the toolbar as needed.

***

## Add LoT code to a LoT Notebook

![Animated walkthrough: insert a code cell in a LoT Notebook and add LoT definition text in VS Code](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-basic-action.gif?s=f0a99e24fb50a62f34539d706812f912)

Insert a LoT code cell and add LoT in the notebook editor

1. Open your LoT Notebook in VS Code.
2. From the notebook toolbar, add a **code** cell.
3. Type or paste your LoT code (`DEFINE ACTION`, `DEFINE MODEL`, and so on). For a first example, use the code below.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"
```

***

## What type of cells you can add to LoT Notebooks

LoT Notebooks support three types of cells, each with different behavior:

### Markdown Cells - Documentation

![LoT Notebook markdown cell showing a heading and body text with the cell toolbar for formatting and actions](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-cell-markdown.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=7f8d6580bd483bfd9e9c53c7e6919d1b)

Markdown cell with rich text and the formatting toolbar

Markdown cells are for **documentation only**—they don't execute. Use them to:

* Explain what your code does and why
* Document configuration requirements
* Add diagrams, tables, and formatted text
* Create section headers and navigation

### LoT Code Cells - Runnable Logic

![LoT Notebook LoT cell with TemperatureSimulator action, run button, and status bar showing Upload to broker and LOT cell type](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-cell-LoT.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=3ced495b4d1137b78534bb83cb0a4651)

LoT code cell: syntax highlighting, sync status and upload to broker buttons

LoT cells contain executable **LoT (Language of Things)** code. When you run a LoT cell:

1. The extension parses your code
2. Sends it to the connected broker via MQTT
3. The broker compiles and registers the definition
4. You receive confirmation or error feedback

For what LoT is, how it fits the broker, and more examples, see [Introduction to LoT](/latest/lot-language/introduction).

#### Validate without deploying

**Validate** in the cell status bar, or **LOT Notebook: Validate LOT Cell** and **Validate LOT Notebook** in the Command Palette, asks the broker to check the code without deploying it. The broker's summary and each diagnostic (severity, code, line, and message) appear under the cell and in **Problems** with source `Coreflux`. Notebook validation includes Python cells. Diagnostics clear when you edit the cell. Needs a broker newer than 2.14.

#### Disable an entity

Action, connector, and agent cells have an **Enabled / Disabled** toggle in the cell status bar. It adds `DISABLE true` on the line after `DEFINE`, or removes it; a `DISABLE` inside a comment is left alone. When you're connected, the cell is uploaded right away; offline, upload it once you connect. The broker keeps a disabled entity defined, but doesn't run it. A broker without `DISABLE` support leaves the cell unchanged. The same toggle is **LOT Notebook: Enable / Disable LOT Cell (DISABLE)**. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).

#### THING cells

Running a cell with `DEFINE THING` blocks sends them as typed, with every template they use from the workspace, as one `-addThing`. The broker expands them; the extension doesn't.

* Every run checks first with `-addThing --dryRun`. Problems appear on the cell at the line of the THING source.
* When a template change would redeploy other root Things, the extension lists them and asks first.
* The cell output shows the broker's plan per root: `add`, `update`, `adopt`, `remove`, or `unchanged` for each child.
* **Remove Thing from Broker** sends `-removeThing`. The broker refuses to remove a template that's in use.
* A cell in the older THING syntax offers a quick fix that adds `TEMPLATE` and rewrites `{p}` to `{{p}}`. You can **Apply All**, or **Review in Refactor Preview** first.
* On a broker without THING support, the cell says so and deploys nothing.

The Coreflux Explorer and the Entities panel show each root Thing with its state, its instances, and their read-only children. A Thing that no workspace notebook defines is marked *not in workspace*.

#### Agent cells

A `DEFINE AGENT` cell deploys with `-addAgent` and is removed with `-removeAgent`. The extension checks the agent like the broker does: a missing `USES LLM CONNECTOR` (`USES LLM ROUTE` is still accepted) or `DEFAULT_USER`, unknown clauses or tools, and an `ADD TOOL` without its `TOPICS`, `TARGET`, or `LEVEL "write"` are errors. Agents on the broker appear in the Coreflux Explorer and under **Agents** in the Entities panel.

Agent, Thing, rule, connector, and model checks follow the broker. A connector key such as `SUBJECT`, and a mixed-case name, are not reported as unknown keywords.

```lot wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
DEFINE AGENT NightShift
    USES LLM CONNECTOR LocalLlama
    WITH DEFAULT_USER "agent_svc"
    ADD TOOL "read_mqtt"
        WITH TOPICS "plant/#"
```

See [LoT Agents](/latest/lot-language/agents/overview).

#### Panel cells

A `DEFINE PANEL` or `DEFINE VISU` cell is checked with the broker's panel parser: component types, `SET`, `BIND`, `ON … DO`, `AT`, `ADD THRESHOLD`, and `MAPPING`. A typo stays an error. Where the broker falls back, the cell shows a warning. Highlighting, hover, and completions cover the panel keywords, and the `DEFINE PANEL` snippet inserts a starter panel.

Running the cell deploys with `-addVisu` (the same command as `-addPanel`). Removing it sends `-removeVisu`. A Thing's `WITH PANEL` body is checked the same way. `DEFINE THEME` and `THEME_VARIANT` are recognized. The cell status bar offers **Open in Coreflux HUB** to view the rendered panel, and a successful upload suggests opening Dashboards there.

See [Defining a Panel](/latest/lot-language/panels/defining-panels).

### Python Cells - Advanced Logic

![LoT Notebook Python cell with Script Name header, function definitions, run button, and Python label in the status bar](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-cell-python.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=11d0c77c5b03bb46c46c71ae0fcdf3c3)

Python cell with syntax highlighting, sync status and upload to broker buttons

Python cells contain scripts that run inside the broker when called from LoT Actions. The broker's Python runtime executes your functions.

```python wrap theme={"theme":{"light":"css-variables","dark":"css-variables"},"languages":{"custom":["/languages/lot.json"]}}
# Script Name: DataProcessor
def calculate_average(values):
    """Calculate average from a list of numbers"""
    if not values:
        return 0
    return sum(values) / len(values)

def format_alert(sensor_id, value, threshold):
    """Generate formatted alert message"""
    return f"ALERT: Sensor {sensor_id} exceeded {threshold} with value {value}"
```

> [!WARNING]
>
> Python scripts require a specific format with `# Script Name: YourScriptName` as the first line. Without this header, the script won't be recognized.

***

## Running LoT

![Animated walkthrough: Run on a LoT notebook cell to deploy the definition to the connected Coreflux broker](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-deploy-lot.gif?s=aa0c88228b7e0db8f7fe4b07c16eb513)

Deploying a LoT or Python code from the notebook to the broker

When you click the **Run** button on a cell, the Extension builds your code, checks for errors and deploys to the broker.
If successful, a simple Green response will appear. If any error is found, the code is not deployed and a error message will appear with the error details.

***

## What else you can do with the LoT extension

![Animated walkthrough of the LoT Data Viewer in VS Code: subscribing to topics and viewing live MQTT traffic](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-data-viewer-basic.gif?s=7124718aa0d1a06105dd56a905f1a177)

Data Viewer basics: subscribe to topics and watch live MQTT data

Use the **Coreflux** view (Activity Bar) for broker connection, entities, secrets, license, clients, and live MQTT—without a separate client for most tasks.

| Capability | Why it helps |
| - | - |
| **See what is running in the Broker** | See what Actions, Models, Connectors, and Rules the broker actually has after a deploy. |
| **Remove LoT code** | On Coreflux Explorer, remove one or more LoT entities. |
| **Manage secrets and variables** | Configure secrets and variables on the broker, to manage secure credentials. Open **Secrets & Variables** from Broker Management |
| **See license usage** | Spot **license limits** when deploy fails—before you debug LoT as a syntax issue. |
| **Activate a license** | Activate, install, enroll, and refresh from the **License** tab. See [License tab](#license-tab) |
| **Configure the MCP server** | Turn on the broker's MCP server, manage its tokens, and install it into AI clients. See [MCP Server tab](#mcp-server-tab) |
| **See connected clients** | See who is connected; useful when a device or app should be online but is not. |
| **MQTT Data Viewer** | Live topics and payloads in the Data Viewer. |
| **Execution Trace** | For a LoT cell, see it's execution history and which topics and variables that run touched. |

For more on the Data Viewer, replay, formatters, and trace, see [How to Debug in LoT Notebooks](./debug).

### License tab

Open **License Management** from Broker Management. The tab shows the plan, expiry, features, and usage from `$SYS/Coreflux/License`, and offers these actions:

| Action | What to enter | Broker command |
| - | - | - |
| **Activate** | An activation code (`CFLX-…`) | `-activateLicense` |
| **Install** | The signed license text, pasted or from a file | `-loadLicense` |
| **Enroll** | An organization enrollment token (`et_…`) | `-enroll` |
| **Refresh** | Nothing: forces a lease refresh | `-refreshLicense` |

You can also load a license file that's already on the broker host by its path. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

### MCP Server tab

**Coreflux: Configure MCP Server** opens the broker's built-in MCP server settings, the same ones as the HUB **MCP** tab:

* **Server** — Enabled, status (**Listening**, **Disabled**, or **Pending restart**), the endpoint URL with Copy, port, bind IP, and endpoint path. Saved changes apply when the broker restarts.
* **Tools** — Expose all tools, or pick an allow-list from the broker's catalog.
* **Tokens** — List, create, and revoke tokens (`-listMcpTokens`, `-createMcpToken`, `-revokeMcpToken`). A new token is shown once.

**Install MCP server** creates a token for the broker user you pick and writes the endpoint and token into each client you tick: Cursor, VS Code, Claude Code, or Claude Desktop (through `npx mcp-remote`). Existing config files are edited in place, keeping comments and other servers. A workspace install also adds the config file to `.gitignore`, so the token isn't committed. See [MCP Server](/latest/mqtt-broker/mcp-server).

### Develop LoT Notebooks with AI

![Animated walkthrough: VS Code with a LoT notebook open and GitHub Copilot chat focused on a notebook cell](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-copilot.gif?s=7fa29fa41a99c3835a27fa55fe1bf46e)

GitHub Copilot with a LoT Notebook: chat in context of the open notebook and cells

Alongside the extension, you can develop with AI using **Copilot**, just like any programming language. For better results, you can add the **Coreflux MCP** server to the agent, so it can read official docs, and add **AGENTS.md** file for LoT coding practices, so it works like a LoT expert.

To connect your AI client to the broker itself, use [Install MCP server](#mcp-server-tab). Nothing is installed automatically on startup. **Install Agent Skills...** lets you pick which skills to install and the target folders: `.agents`, `.claude`, `.cursor`, or `.github` skills folders, in the workspace or in your home folder. The 11 bundled skills come from the public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository. See [Agent Skills](/ai/agent-skills) (broker 2.22 or later) for the skill list and other ways to install them. Older copies from previous versions are offered to move to the trash.

To for more details on how to use AI with LoT, check this page: [Developing with LoT Using AI](/ai/developing-with-lot).

### Version control with Git

![VS Code Source Control showing pending changes across .lotnb notebooks, docker-compose.yml, markdown, and editor config files in the same repo](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-project-git-management.png?fit=max\&auto=format\&n=XSOUAWqOWS4Y2_FQ\&q=85\&s=fa4ae1c74bc80b882ead08c988631d8c)

Source Control: Git tracks the whole workspace, not just LoT notebooks

Use **Git** on your **workspace folder** like any project: commit **`.lotnb`** files aswell as any other files, like documentation, Docker files and supporting files.

***

## Best Practices

> **Organize with Markdown**
>
> Use markdown cells liberally to explain your code. Future you (and teammates) will appreciate the context.

> **One Definition Per Cell**
>
> Keep each Action, Model, or Connector in its own cell. This makes debugging easier and allows selective execution.

> **Test Incrementally**
>
> Run cells one at a time when developing. This helps isolate issues and understand system behavior.

> **Use Descriptive Names**
>
> Name your Actions, Models, and Connectors clearly. They appear in the broker's entity lists and should be self-explanatory.

***

## Troubleshooting

> **Cell won't run?**
>
> * Check that you're connected to the broker (look for connection status in status bar)
> * Verify your credentials are correct
> * Ensure the broker is running and accessible

> **LoT not deployed — license limits?**
>
> If running a cell shows an **error** and the broker rejects the definition because you have reached a **license limit** (for example on actions, connectors, or another licensed resource), deployment stops and the message under the cell should describe the limit.
> Open the **Coreflux** view in the Activity Bar and check the **Coreflux Explorer** section for your **license** status and usage so you can see what is capped. To raise the plan, see [Licensing and Enrollment](/latest/mqtt-broker/licensing).

> **Python script not recognized?**
>
> * Confirm the first line is `# Script Name: YourScriptName`
> * Check for syntax errors in the Python code
> * Ensure function names match what you're calling from LoT

> **Entity not appearing after deployment?**
>
> * Check the output for error messages
> * Verify no syntax errors in your LoT code
> * Use the Coreflux Entities panel to refresh the list

***

## Next Steps

> **[Debug in VS Code](./debug)**
>
> Use cell output, Coreflux Entities, and live MQTT values to fix issues.

> **[Explore Tutorials](./tutorials)**
>
> Work through hands-on notebooks covering Actions, Models, Connectors, and Python.

> **[Extension Release Notes](/product-updates/release-notes#vs-code-extension)**
>
> See what shipped in each VS Code extension release.


# Release Notes
Source: https://docs.coreflux.org/product-updates/release-notes

New features, improvements, and fixes in each release of the Coreflux MQTT broker and HUB.

Product

**MQTT Broker**

**2.22**

August–October 2026

> [!WARNING]
>
> **Breaking Changes** in this release (2.15–2.22):
>
> **`TYPE MCP_SERVER` is gone** — The MCP server is now broker configuration, not a LoT connector, and a project that still defines `TYPE MCP_SERVER` fails to load. Enable `Mcp.Enabled` (or `COREFLUX_MCP_ENABLED=1`), mint a token with `-createMcpToken`, and point the client at Streamable HTTP `/mcp`. Legacy SSE URLs stop working. The MCP client connector (`TYPE MCP` / `CALL MCP`) is unchanged. **Action:** remove old `TYPE MCP_SERVER` definitions and follow [MCP Server](/latest/mqtt-broker/mcp-server).
>
> **`TYPE AGENT` connectors are removed** — `-addConnector` refuses them and stored ones are skipped at load, with their topics. Rewrite each as a `TYPE LLM` connector plus `DEFINE AGENT … USES LLM CONNECTOR`; nothing is granted until `ADD TOOL`, and writes need `WITH LEVEL "write"`. There is no automatic migration. **Action:** rewrite agents before you upgrade. See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).
>
> **No built-in trial** — A broker with no license runs as **Community**. Get a 30-day Growth-type license at [portal.coreflux.org](https://portal.coreflux.org), where you also manage your fleet.

### 2.22.0 - Things, Agents, licensing, and a built-in MCP server

This release lets you model devices once and reuse them (Things), build AI agents that only do what you allow, and connect tools like Cursor or Claude Desktop straight to the broker. It also adds signed licensing with fleet enrollment, certificate management, and clustering that runs your LoT on every node.

#### Highlights

* **Model a device once, then reuse it (Things, preview)** — Describe a pump, a line, or a sensor type once. Each copy gets its own topics, and you add as many as you need without copying LoT. See [Things](/latest/lot-language/things/overview).
* **Let AI act only where you allow it (Agents, preview)** — An agent starts with no tools. You grant each read or write, and a question-only mode never changes the broker. See [Agents](/latest/lot-language/agents/overview).
* **Work on the broker from Cursor or Claude** — A built-in MCP server lets those tools run broker commands, with tokens you create and revoke. See [MCP Server](/latest/mqtt-broker/mcp-server).
* **Keep every cluster node on the same LoT** (**Beta**) — Deploy to any node and the whole cluster runs it. A device connector can stay on the node that can reach the equipment. See [LoT in a cluster](/latest/mqtt-broker/clustering#lot-in-a-cluster).
* **License a broker and add it to your fleet** — An unlicensed broker runs as Community. Activate online, use a signed file where there is no internet, and enroll the broker in your organization. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).
* **Replace certificates without a restart** — Update the certificate the broker presents, choose which clients to trust, and see which certificates are about to expire. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Sign in with your identity provider** — Clients can use an OIDC access token as the MQTT password. Local passwords still work. See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Pause logic without deleting it** — Turn an action, connector, or agent off, keep the definition, and turn it back on when you are ready. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **See when a device is actually down** — Industrial connectors show Reconnecting when a PLC stops answering, and the last good tag values stay in place through a short disconnect. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **Bring in audio, gRPC, and hundreds of APIs** — Capture microphone audio onto MQTT, call gRPC services, and start from 220+ REST API app templates (technical preview). See [REST API Apps](/latest/lot-language/routes/rest-api-apps/index).

#### Things and Agents (preview)

* **Define a device once** — A Thing is a typed device with `{{placeholder}}` topics. Add instances with `-addThing` (use `--dryRun` to validate first), and manage them with `-removeThing` and `-listThings`, or the MCP tools `add_thing`, `list_things`, and `remove_thing`. Each Thing publishes its source, tree, and health under `$SYS/Coreflux/Things/<name>`. See [Things commands](/latest/mqtt-broker/commands#things).
* **Agents with limited access** — An agent uses a `TYPE LLM` connector for its provider, model, key, and price, and starts with no tools. It gets only what `ADD TOOL` grants. Agents can ask each other for help with `WITH AGENTS`, and actions call them with `CALL AGENT`. Each agent publishes its card and status under `$SYS/Coreflux/Agents/<name>/`.
* **Read-only questions** — Ask an agent with `"mode": "insight"` and it only reads, including any agents it delegates to. `TYPE LLM` also accepts `REASONING_EFFORT` (`none` to `extra_high`).

#### New connectors

* **Audio Input** — Capture a microphone, test tone, silence, or a file as 16-bit PCM audio on MQTT (`TYPE AUDIO_INPUT`). See [Audio Input](/latest/lot-language/routes/media/audio-input).
* **gRPC** — Call gRPC services from MQTT with `TYPE GRPC`, including streaming. See [gRPC Connector](/latest/lot-language/routes/streaming/grpc).
* **REST API apps** — 220+ ready-made `TYPE REST_API` templates for cloud, ERP, MES, messaging, and IIoT services, in technical preview. See [REST API Apps](/latest/lot-language/routes/rest-api-apps).

#### MQTT and LoT

* **Connectors naming** — `DEFINE CONNECTOR` and the `-addConnector`, `-removeConnector`, `-listConnectors`, `-removeAllConnectors`, and `-checkConnectorConnection` commands are the new names. `DEFINE ROUTE` and the `-…Route…` commands keep working as aliases.
* **Turn things off without deleting them** — Put `DISABLE true` under `DEFINE` on an action, connector, or agent to keep it stored but not running. Switch it back on with `-disableAction`, `-disableConnector`, `-disableAgent` and the matching `-enable…` commands, or with MCP tools. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **Publish with retain and QoS** — `PUBLISH TOPIC` accepts `RETAIN` and `QOS0` / `QOS1` / `QOS2` (default QoS 0). `KEEP TOPIC` still only stores a value for `GET TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#publish-topic).
* **Shared subscriptions** — Turn on `SharedSubscriptions` and `$share/{group}/{filter}` delivers each message to one member of the group. Off by default. See [Shared subscriptions](/latest/mqtt-broker/protocol#shared-subscriptions).
* **Predictable topic triggers** — `ON TOPIC` actions, models, and connector events run on the exact message that fired them, in publish order per topic. Different topics still run in parallel. See [Action Triggers](/latest/lot-language/actions/events).
* **Every publish in an action is sent** — Each `PUBLISH TOPIC` or `KEEP TOPIC` in one run is delivered, in the order written, with that line's own retain, QoS, and keep settings. A later `GET TOPIC` in the same run reads the value just written. In a cluster, only the last `KEEP` of each topic is replicated. See [PUBLISH TOPIC](/latest/lot-language/actions/operations#publish-topic).
* **Panel wait and markdown** — A button accepts `SET AWAIT "Id, Id"` and `SET AWAIT_TIMEOUT` (seconds, default 120). A text component accepts `SET MARKDOWN true`. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button) and [Markdown text](/latest/lot-language/panels/defining-panels#markdown-text).

#### Licensing and enrollment

* **Plans** — Community, Growth, and Enterprise, with limits on artifacts and connectors. Status is on retained `$SYS/Coreflux/License` and, on the ops port, `GET /license` (port `9100`, keep it private).
* **Three ways to license** — Activate online with `COREFLUX_ACTIVATION_CODE` or `-activateLicense CFLX-…` (limits apply without a restart, the lease refreshes daily, `-refreshLicense` forces it). Or install a signed license file (`config/license.jws`, `COREFLUX_LICENSE_FILE`, `COREFLUX_LICENSE_TOKEN`, or `-loadLicense`), which the broker verifies locally with no network. For air-gapped hosts, send the `--show-fingerprint` value to Coreflux and install the hardware-bound license you get back.
* **Enroll in your organization** — `-enroll et_…` (or `--enroll`, or `config/enrollment-token`) binds the broker to your Coreflux organization, separately from its plan. An activation code enrolls it too. A broker waiting for enrollment still starts: local users work, and logins that need the organization are refused until it succeeds. `$SYS/Coreflux/License` explains why it is pending. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

#### MCP server

* **Connect AI tools to the broker** — Cursor, Claude Desktop, and other MCP clients connect to the broker's built-in server, configured in the `Mcp` block (port `6278`, bound to `127.0.0.1`, path `/mcp`). Manage tokens with `-createMcpToken`, `-listMcpTokens`, and `-revokeMcpToken`, or from the HUB **MCP** tab. In Docker or Kubernetes, bind to `0.0.0.0`, publish `6278`, and route `/mcp` behind TLS. See [MCP Server](/latest/mqtt-broker/mcp-server#docker-and-kubernetes).
* **Install agent skills** — The public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository is generated from the broker, and the broker exposes the same pack as the `coreflux://skills` MCP resource. Coding agents that install it write LoT the broker accepts. They need broker 2.22 or later. See [Agent skills](/ai/agent-skills).

#### Security

* **Sign in with OIDC** — With `Oidc.Enabled`, a client sends an OIDC access token as its MQTT password. The broker validates it, checks the organization, and authorizes by the token's groups. Local passwords still work. A client is disconnected when its token expires (30-second grace). See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Manage certificates from a command** — `-brokerCertificates` (admin only) shows and replaces the server certificate and Root CA, and manages the mTLS trust store: list, import, export, revoke, settings. A new server certificate applies without a restart and keeps a `.bak-` copy. Revocation is immediate and every change is audit-logged. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Know when certificates expire** — Retained `$SYS/Coreflux/Certificates/Summary` counts valid, expiring, expired, and unreadable certificates. `CertificateExpiryThresholdDays` (default 30) sets the warning window. See [`$SYS/Coreflux/Certificates/Summary`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary).
* **Easier trust store** — `ClientCertificateSourcePath` loads `.pem`, `.crt`, `.cer`, `.der`, and unprotected `.p12`/`.pfx` files, skips anything in `revoked/`, and refuses keys and CSRs (install a server key with `replaceServer`). `$SYS/Coreflux/Config` shows `ServerCertificatePassword` as `********`.

#### Clustering and operations

* **LoT works across a cluster** (**Beta**) — Definitions replicate through the leader, so you can send LoT to any node and every node runs the same version. Each message runs LoT once, on the node it entered. Timers, `ON START`, and device connectors run on one owner and move to another node within about 10 seconds if it fails. Pin a device connector to a node with `CLUSTER_NODE` in `ROUTE_CONFIG`. **Action:** upgrade every node before you change LoT, and create users on every node.
* **Faster Kubernetes scaling** (**Beta**) — A pod that the headless Service no longer lists leaves the cluster about 2 minutes after its cluster port stops answering (`MemberAbsentFromDiscoverySeconds`, 120 seconds by default; it used to wait 5 minutes). New pods are found within seconds. See [How a cluster works](/latest/mqtt-broker/clustering#one-leader-automatic-membership).
* **More metrics** — New `/metrics` series for delivered messages, CPU, auth failures, ACL denials, rate limits, connector drops, and errors. See [Metrics](/latest/mqtt-broker/operational-endpoints#metrics).
* **Fleet health reporting** — An enrolled broker reports CPU, memory, clients, traffic, refusals, drops, and scrubbed error signatures to the Coreflux Portal. It never sends topics, payloads, hostnames, or IPs. Turn it off in the portal, or with `COREFLUX_FLEET_METRICS=off` or `DO_NOT_TRACK=1`. See [Fleet performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics).

#### Bug fixes

**Industrial connectors**

* **Connection status tells the truth** — Modbus, S7, OPC UA, EtherNet/IP, ADS, Allen-Bradley, FINS, and BACnet no longer wipe retained tag values on a disconnect or failed read, and a restarted connector polls again. A connector no longer shows Connected while its device is unreachable: after 3 failed read cycles it reports Reconnecting and rebuilds the connection. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **No more hangs on silent devices** — A PLC that accepts a connection but never answers no longer freezes S7 (`READ_TIMEOUT` now limits the connect) or EtherNet/IP (`READ_WRITE_TIMEOUT` now bounds every exchange). **Action:** raise `READ_WRITE_TIMEOUT` for slow EtherNet/IP devices.
* **Modbus TCP** — Each connection runs one request at a time, so tags no longer go BAD with "Response was not of expected transaction ID". See [Modbus TCP Client](/latest/lot-language/routes/industrial/modbus-tcp-client#one-request-at-a-time).
* **FINS** — A slow reply no longer shifts later reads onto the previous command's value, and a lost PLC goes to Reconnecting after 2 unanswered commands. Replies must now match the request and come from the addressed node. **Action:** gateways that swap client and server nodes now time out; check `LOCAL_NODE` / `REMOTE_NODE`. See [FINS](/latest/lot-language/routes/industrial/fins).
* **Allen-Bradley** — A slow but healthy PLC no longer reconnects every cycle, and a timed-out write publishes `"outcome": "unknown"`. See [Write results](/latest/lot-language/routes/industrial/overview#write-results).
* **ADS** — `TIMEOUT` now applies to every request (it was ignored and fixed at 5 s), and an unreachable PLC makes the connector reconnect. See [ADS](/latest/lot-language/routes/industrial/ads).
* **OPC UA** — A read or write that races a reconnect marks the tags BAD and backs off instead of counting as success, and sessions no longer leak.
* **BACnet** — Integer writes of any size send the right value (out-of-range 64-bit values fail instead of being cut off), and reads queued on a dropped connection no longer break the new one.
* **Tag values** — Negative `OFFSET`, `MIN_VALUE`, and `MAX_VALUE` now parse. See [Common TAG parameters](/latest/lot-language/routes/industrial/overview#common-tag-parameters).

**Other connectors**

* **Kafka** — A `"in"` event commits its offset only after the message is published, so a crash no longer drops records. `WITH EVERY` on a Kafka event is now rejected when you add the connector. **Action:** publish on a schedule with `ON EVERY` in a LoT action. See [Kafka Connector](/latest/lot-language/routes/streaming/kafka).
* **Kafka and gRPC start** — A connector that fails to start is retried in the background (2 to 60 seconds) until it starts or you remove it.
* **Ollama** — A `TYPE LLM` connector with `PROVIDER ollama` takes `CONTEXT_WINDOW` (a fixed `num_ctx`, sized per call and capped at the model's maximum), `MAX_CONTEXT_WINDOW` (default 32768, minimum 16384), `FIRST_OUTPUT_TIMEOUT` (default 120 s), and `IDLE_TIMEOUT` (default 60 s). Agent tasks fail with a clear error (`llm_timeout`, `llm_unreachable`, `model_not_found`, `context_overflow`) instead of hanging. See [Ollama context and timeouts](/latest/lot-language/routes/ai-routes#ollama-context-and-timeouts).
* **Email and CrateDB** — Email `ADD EVENT` blocks now send and publish their status. CrateDB `ADD EVENT` blocks run, `STORE IN` writes rows, and the connector reconnects after a CrateDB restart.
* **REST API** — A reply published right away on `REPLY_TOPIC` reaches the HTTP client instead of a 504, and concurrent requests no longer cancel each other. A value in `ENDPOINT` can no longer send the request and its credentials to another host; the broker refuses it and publishes `RequestRejected`. See [Placeholder Support](/latest/lot-language/routes/rest-api-routes#placeholder-support).
* **MQTT bridge** — A bridge without `CLIENT_ID` forwards inbound messages and no longer clashes with other bridges, and a removed bridge stops forwarding at once.
* **Sparkplug B** — The Primary Host tracks `seq` per edge node and no longer floods Rebirth requests, and DATA metrics without a datatype decode using the birth certificate.
* **`TRIGGER` on LLM, AGENT, and MCP** — MCP calls the named tool, and LLM and AGENT results go to the mapping's `DESTINATION_TOPIC` or the default response topic instead of being discarded.

**LoT and MQTT**

* **`GET MODEL`** — `SET … WITH GET MODEL` no longer fails on the action's first run, `PUBLISH TOPIC … WITH GET MODEL` parses, and `WHERE` conditions joined with `AND` accept any mix of text and numbers. See [GET MODEL](/latest/lot-language/actions/operations#get-model).
* **`STORE IN … WHEN`** — Conditional model storage works instead of failing on first evaluation, and an unknown field is rejected at deploy. See [Store data with models](/latest/lot-language/routes/data-storage/overview#step-2-store-data).
* **`MATCHES REGEX`** — Patterns with `\d`, `\w`, `\s`, or `\.` work as written. See [MATCHES REGEX](/latest/lot-language/rules/syntax#matches-regex).
* **`TRIGGER` statements** — The line after a `TRIGGER` is no longer dropped. Examples now use `TRIGGER "<connector>" TO <data> FOR "<event>"`; code copied from the old order (`WITH "<event>" FOR <data>`) still deploys but swaps the data and the event. See [TRIGGER Statement](/latest/lot-language/actions/operations#trigger-statement).
* **MQTT 5 denials** — A denied publish now gets `0x87 Not authorized` and a rate-limited one `0x97 Quota exceeded`, instead of Success. See [What a denied client sees](/latest/lot-language/rules/rbac#what-a-denied-client-sees).
* **Callable actions from panels** — Object, array, and `null` arguments no longer cause a compile error; objects and arrays arrive as JSON text.
* **Protobuf `float` and nested `GET PROTO`** — `ADD FLOAT` (alias `ADD SINGLE`) decodes proto `float`, and dotted `GET PROTO` paths read nested messages. A field with the wrong type is skipped instead of stopping the whole message. See [Protobuf Models](/latest/lot-language/models/protobuf).

**Panels, projects, and platform**

* **Panels** — Boolean CSS bindings (`BIND CSS … AS BOOLEAN`) convert correctly in the HUB. SVG markup from `SET INLINE` and `data:` sources is rebuilt from an allow-list so scripts, event handlers, and external links can't run in viewers' browsers; what was removed is listed as a deploy warning.
* **Projects** — A live project's history records only the edited cell, not the whole notebook. After a restart, the broker also loads connectors added outside the project and the connectors of Things, and publishes Thing status from boot. See [LoT THING](/latest/lot-language/things/overview).
* **Metrics** — Published-message and byte counters no longer reset at UTC midnight, so `rate()` works across it. `coreflux_messages_published_total` now counts client publishes; deliveries moved to `coreflux_messages_delivered_total`.
* **Linux packages** — APT and DNF units run the broker as the user `coreflux` with `CAP_NET_BIND_SERVICE`, so they can bind ports below 1024. See [Ports below 1024](/latest/mqtt-broker/startup-options#ports-below-1024).

**Configuration**

* **Partial config is merged** — A partial JSON object published to `$SYS/Coreflux/Config/New` is merged into the live configuration. Fields you omit, including bind addresses, stay as they are. See [Applying Configuration](/latest/mqtt-broker/configuration#via-mqtt-topic).

**2.14**

August 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.14.3 - Default rules and Visu panel publishing

#### Bug fixes

* **Default rules load with an active project; Visu panels can be published** — When a project is already active at startup or after `-loadProject`, the broker's seeded permission rules now apply correctly so internal clients retain `$SYS` access and panels publish to `$Visu/...` topics again after project activation.

### 2.14.2 - Sparkplug B connector, MQTT & LoT performance improvements

Sparkplug B Support, MQTT client lifecycle action triggers, better OT master/client visibility in broker logs, a banded Rules precedence model, project lifecycle improvements, and faster publish, LoT, and connector dispatch.

#### Improvements

* **Rules priorities are now banded** — The rule priority number line is split into bands: `0`–`99` is reserved for the broker's immutable system rules, `100`–`999 999` is your band, and the permissive catch-alls `AllowPublishTopic` / `AllowSubscribeTopic` now sit at `1 000 000`. Only the strongest matching band decides an operation, where a DENY beats an ALLOW (deny-wins) and nothing matching means denied (default-deny). Moving the catch-alls to the weakest band **fixes a topic-visibility bypass**: they previously shipped tied with everything else, so a specific access rule could not reliably override the allow-all fallback — which left Visu panel view topics effectively public. `-addRule` now rejects priorities outside `100`–`1 000 000`. **Action:** custom rules written in the old `1`–`99` range are clamped to `100` on load and logged individually. Clamping keeps them in force, but several rules can land on `100` together, where ties resolve deny-wins — re-space them across the user band, putting the more specific rule at the lower number. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac#rule-precedence).
* **`AllowConnect` seed and `FOR Connect` rules** — Fresh brokers now ship a third permissive catch-all, `AllowConnect`, at priority `1 000 000` (the same weakest band as `AllowPublishTopic` / `AllowSubscribeTopic`). Write `FOR Connect` rules in the user band to decide who may connect after authentication; they outrank the seed. Brokers with no Connect rule at all still leave CONNECT ungated. `-restoreRules` puts all three seeds back to their shipped ALLOW definitions. See [RBAC](/latest/lot-language/rules/rbac#connection-admission) and [`-restoreRules`](/latest/mqtt-broker/commands#restoring-seeded-rules).
* **Project manifests, entity ownership, and ad-hoc entities** — Each stored project publishes a retained content manifest on `$SYS/Coreflux/Projects/{name}/manifest` (SHA-256 of exact file bytes, plus entities declared in `.lotnb` cells). `-projectManifest` returns the same JSON on demand. Running entities are attributed on `$SYS/Coreflux/Entities/ownership` and in the `-listEntities` / `-loadProject` `origin` field. **Loading or unloading a project no longer deletes ad-hoc entities** added with `-addAction` and similar commands while no project was active. **Action:** if you relied on Activate to wipe the whole runtime, remove those entities explicitly before loading a project. See [Project Commands](/latest/mqtt-broker/commands#project-commands) and [Project Topics](/latest/mqtt-broker/sys-topics#project-topics).
* **Loaded projects stay active after a restart** — After `-loadProject` (or `--project`), the last loaded project is remembered and re-activated on the next start unless you pass `--project`. `-unloadProject` returns to standalone mode on the next restart. See [Startup Options](/latest/mqtt-broker/startup-options#loading-a-project-at-startup).
* **`ON START` runs on deploy; action publishes are no longer blocked by user ACL** — Deploying an `ON START` action on a live broker executes the body immediately (cold start still runs once after the MQTT broker is ready). Action `PUBLISH` / `KEEP` still put messages on MQTT for any subscriber; they are no longer denied by user publish rules, so bootstrap topics from actions are not silently dropped. Clients still need subscribe permission to receive those messages. See [Initialization Triggers](/latest/lot-language/actions/events#initialization-triggers).
* **OT string sizing — `LENGTH` is the preferred keyword** — Across OT connectors that support configurable string sizing, `WITH LENGTH` is now the documented primary keyword; `STRING_SIZE` remains accepted as a parser alias. See the shared [String sizing by Connector](/latest/lot-language/routes/industrial/overview#string-sizing-by-connector) reference on the industrial connectors overview.
* **Modbus Server STRING defaults and cap** — Unsized `STRING` tags no longer reserve a single register (which silently truncated barcodes and caused Illegal Data Address on FC16 writes). The server now defaults to **40 bytes (20 registers)** and warns when size is omitted. Connector validation rejects `LENGTH` values above **246 bytes (123 registers)**, the FC16 write cap. See the [Modbus TCP Server Connector guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **Modbus Server and OPC UA Server activity logging** — Modbus Server connectors log accepted and rejected master writes (plus rejected reads), with bank-aware function-code labels and `LENGTH` guidance when an undeclared holding-register range is the cause; connection open/close counts are logged from the existing watchdog (**the master's source IP is not available**). OPC UA Server connectors log client session create/close events and accepted external writes on tags and STRUCT fields.
* **MQTT client lifecycle action triggers** — New `ON CONNECT DO`, `ON DISCONNECT DO`, and `ON SUBSCRIBE ["pattern"] DO` triggers run LoT automation when clients connect, disconnect, or subscribe. Action bodies expose session context via `CLIENTID`, `USER`, `ENDPOINT`, `CLEANSESSION`, `DISCONNECTREASON`, `SUBSCRIBETOPIC`, and `SUBSCRIBEQOS`. The broker only evaluates lifecycle hooks when at least one action defines them. See [Action Triggers](/latest/lot-language/actions/events#client-lifecycle-triggers).
* **Improved command response handling** — Broker command responses are now consistently structured as JSON. Each command may include a `requestId` field, allowing you to easily correlate requests and responses.
* **Sparkplug B connectors (beta)** — Decode Sparkplug B protobuf into readable JSON, publish Coreflux topics as an edge node, or run Coreflux as the Primary Host Application with namespace state, commands, and automatic rebirth requests. See the [Sparkplug B Connector](/latest/lot-language/routes/system/sparkplug-b) and [Sparkplug Host Connector](/latest/lot-language/routes/system/sparkplug-host) guides.

#### Performance

* **MQTT between clients** — More messages complete per second, the slowest publishes finish sooner (about 10% lower p99 latency). Messages that update connector topics stay in the order they arrived.
* **LoT rules and actions** — Permission checks, topic triggers, timers, and dashboard invokes no longer slow down as more distinct topics exist on the broker. LoT-heavy traffic that was about **10× slower at 30,000 topics** — and about **70× slower at 100,000** — now stays as fast as it was on a nearly empty broker. `USER HAS` and `USER IN GROUP` checks stay fast as the user list grows.
* **Connector mappings** — Adding mappings no longer makes every publish more expensive, including on topics that no mapping uses. Exact-topic mappings (the common case) keep up with tens of thousands of messages per second at **sub-millisecond** latency with **no loss** — the same flood previously took around **25 seconds** and dropped some messages. Wildcard mappings (`+` / `#`) now deliver fully as well. When a connector cannot keep up, memory stays bounded: the broker waits, then drops the **newest** arriving message rather than older ones already in flight. Set `ADD ROUTE_CONFIG` on a connector (`OVERLOAD_POLICY`, `OVERLOAD_TIMEOUT`, `OVERLOAD_CAPACITY`) when that connector needs a different wait-or-drop contract. See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward).

#### Bug fixes

* **Rules with `IF` and no `ELSE` now compile** — `IF USER IS "dashboard" THEN DENY` (no `ELSE`) previously failed compilation on first evaluation and was treated as a deny for every matching publish or subscribe. The missing branch is now the opposite of the `THEN` decision. See [Rules Syntax](/latest/lot-language/rules/syntax#combining-conditions).
* **Python scripts no longer lose their code on restart** — Scripts that contained blank lines were truncated down to the `# Script Name:` header after a reboot, so `CALL PYTHON` failed even though the script still appeared in listings. Complete scripts now persist across restarts. See [Python Integration](/latest/lot-language/actions/python-integration#writing-python-scripts).
* **Built-in rules survive project add/load/unload** — Adding or switching a project no longer wipes the broker's default permission rules, so internal clients keep `$SYS` access. See [RBAC](/latest/lot-language/rules/rbac#seed-catch-alls).

**2.2**

July 2026

### 2.2.0 - Kafka, OPC UA Server & Modbus Server routes

* **Kafka route** — Connect Coreflux directly to Kafka as a producer or consumer, with support for security protocols and configurable batching and compression. See the [Kafka Route guide](/latest/lot-language/routes/streaming/kafka).
* **OPC UA Server route** — Expose Coreflux data to OPC UA clients with a secure-by-default setup, including support for array and struct nodes. See the [OPC UA Server Route guide](/latest/lot-language/routes/industrial/opcua-server).
* **Modbus Server route** — Serve Modbus data over TCP, with experimental support for Serial (RTU) connections. See the [Modbus TCP Server Route guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **OT route persistence** — Server routes (OPC UA Server, Modbus Server) persist their state and recover automatically after a restart, so data isn't lost on reconnect. See [OPC UA Server persistence](/latest/lot-language/routes/industrial/opcua-server#data-persistence--recovery) and [Modbus Server persistence](/latest/lot-language/routes/industrial/modbus-tcp-server#data-persistence--recovery).
* **OPC UA client certificate authentication** — Authenticate OPC UA client connections using PKI certificates for more secure deployments.
* **Modbus one-based addressing** — Set `WITH ONE_BASED_ADDRESSES true` on Modbus client and server routes so tag addresses match device manuals that label registers starting at 1. See [Modbus addressing](/latest/lot-language/routes/industrial/modbus-tcp-client#modbus-addressing) (client) and [Address notation](/latest/lot-language/routes/industrial/modbus-tcp-server#address-notation) (server).
* **Publish payload as bytes** — Forward or retain binary MQTT payloads bit-for-bit with `PAYLOAD AS BYTES` on `PUBLISH TOPIC` and `KEEP TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#binary-passthrough--payload-as-bytes).
* **EtherNet/IP route** — Joined attribute reads (`ENABLE_JOIN_ATTRIBUTE`), bit extraction (`BIT_ADDRESS`), ARRAY/STRUCT decoding from assembly buffers, bidirectional `WRITABLE` tags, and legacy Hub Asset field mapping for migrations. See the [EtherNet/IP Route guide](/latest/lot-language/routes/industrial/ethernetip).
* **Allen-Bradley route** — Symbolic tag-name access (`Program:MainProgram.Tag` format), `AB`/`ALLENBRADLEY` route aliases, `PATH` vs `SLOT` routing, family-specific STRING/TIME encoding, and cross-link to EtherNet/IP for explicit CIP paths. See the [Allen-Bradley Route guide](/latest/lot-language/routes/industrial/allen-bradley).
* **Bug fixes** — Fixed BACnet alarm retention, EtherNet/IP connection parameters and legacy-style compatibility, a Modbus TCP word-order issue, an OPC UA client connection issue, and a licensing load-order.

**2.1**

June 2026

### 2.1.0 - BACnet route (building automation) and Protobuf models

* **BACnet route** — Connect Coreflux to building automation systems (HVAC, lighting, metering) and bridge them to MQTT
  * Read live values and write setpoints to BACnet controllers
  * Get instant updates on change, without constant polling
  * Receive alarms and event notifications directly in MQTT

See the [BACnet Route guide](/v2.1/lot-language/routes/industrial/bacnet) to get started.

* **Protobuf LoT models (beta)** — Decode and encode binary protobuf on MQTT from LoT: `WITH FORMAT PROTOBUF` (or `BOTH`), `PROTO_TAG` to match vendor `.proto` field numbers, `ADD MODEL` for nested messages on publish, `GET PROTO` / `GET PROTOBUF` to read top-level fields, and `PUBLISH MODEL` to emit real protobuf bytes (not JSON-in-bytes). `WITH FORMAT BOTH` keeps JSON on the main topic and binary on a `/protobuf` sidecar topic.

See [Protobuf Models](/latest/lot-language/models/protobuf) for more details.

**2.0**

April–June 2026

### 2.0.3 - OT tags & route stability

* **OT tag JSON publish** — Message payload now includes the `unit` field
* **Modbus and EthernetIP routes** — Stability improvements

### 2.0.2 - ON CHANGE trigger and bug fixes

* **`ON CHANGE` trigger for LoT actions** — Run actions only when the message payload on a topic is different from the last message on that same topic. Use it for high-frequency telemetry, historians, and forwarding when you do not need to process duplicate values; `ON TOPIC` still runs on every matching publish.
* **Bug fixes** — Stability and correctness improvements across the broker, LoT, and HUB

### 2.0.0 - AI Agent route in the broker

* **AI Agent route** — Create custom agents usable within LoT for AI-driven steps and logic
* **Cloud and local LLMs** — Support for both on AI features

**1.10**

March 2026

### 1.10.0 - Protobuf & REST API route

Support for environment variables and secrets on LoT

* **Protobuf** support
* **REST API route** with OAuth and JWT support
* **Default project on boot** — Load a default project to a Coreflux broker when the broker starts

**HUB**

**2.12**

September–October 2026

### 2.12.0 - Things, Agents, certificates, fleet sign-in, and Cluster Viewer

This release brings the new broker features into the HUB: build and monitor Things and Agents, manage certificates and licenses without leaving the app, sign in with your Coreflux account, and see your cluster at a glance.

#### Highlights

* **Build and watch Things and Agents in the HUB** — Edit them in the LoT Editor, see how they connect in LoT Flow, and turn an action, connector, or agent off without deleting it. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Renew certificates from the app** — Replace the server certificate, trust or revoke a client, and see what is about to expire, without a restart or a shell. See [Certificates](/hub/system/certificates).
* **Open the brokers in your organization** — Sign in with a Coreflux account and connect to your fleet from the login screen. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Activate and enroll without leaving the HUB** — Paste an activation code or a signed license, or enroll the broker in your organization. See [License](/hub/system/configuration#license).
* **See the cluster from the host you already opened (Beta)** — Members, the leader, which links are up, which node owns each piece of LoT, and the clients on each node. See [Cluster Viewer](/hub/cluster-viewer).
* **Start from a template or a public git repo** — Install a Coreflux template as a project, or copy a public repository into the LoT Editor. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Hear live audio and wait on a button** — Data Viewer plays a raw audio topic. A dashboard button stays busy until the work it started finishes. See [Listening to PCM audio](/hub/mqtt/data-viewer#listening-to-pcm-audio).

#### Things and Agents (preview)

* **Things in the LoT Editor** — Deploy THING cells as one payload, checked first with `-addThing --dryRun`. **Broker runtime → Things** lists roots, instances, and their read-only entities, and **Flow preview** draws the notebook's Things. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Things, Tree, and Flat views in LoT Flow** — Switch views to drill into one level at a time, see the whole containment tree, or see everything flat. Panel cards expand into live previews, and the sidebar adds **Agents** and **Things** groups (collapsed at first). See [Things, Tree, and Flat views](/hub/lot-flow#things-tree-and-flat-views).
* **Agent configuration form** — **Configure** and **Add agent** open a form with **Configuration**, **Tools**, and **LoT** tabs. It rewrites only the clauses you change and keeps the rest as written. See [Configure an agent](/hub/ai-assistant#configure-an-agent).
* **Enable and disable** — Switch an action, connector, or agent off and on from its LoT Editor cell, connector card, or agent card. The HUB adds or removes `DISABLE true` and redeploys. The connector Monitor also has **Start** / **Stop**. Disabled cards are dimmed and marked **Disabled**. See [Disable an entity](/hub/lot-editor#disable-an-entity).

#### Certificates and security

* **Certificates tab** — A new System Config tab shows the server certificate and Root CA and replaces them without a restart. It also sets the trust store path and expiry alert, and uploads, searches, and revokes client certificates. Needs broker 2.22. See [Certificates](/hub/system/certificates).
* **Safer uploads** — The client drop zone accepts `.crt`, `.pem`, `.cer`, `.der`, `.p12`, and `.pfx`, and refuses keys and CSRs. Install a server key with **Replace** on the broker certificate.
* **Status bar indicator** — A certificate count with a red, yellow, or green dot. Hover for details, or click to open the tab filtered to certificates that need attention.

#### Account, fleet, and license

* **Sign in with Coreflux** — The login screen adds a **Coreflux Fleet** tab next to **This machine**. The desktop HUB signs in with no setup; a browser HUB needs `COREFLUX_OIDC_CLIENT_ID`, `HUB_PUBLIC_URL`, and `HUB_SESSION_SECRET`. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Fleet brokers** — Read-only rows for your organizations' brokers, with status, license, and **Cloud** / **Self-hosted** badges. **Connect** uses your account; portal actions open [portal.coreflux.org](https://portal.coreflux.org).
* **Cloud mode** — Set `HUB_CLOUD_MODE` on a shared regional HUB to accept only `mqtts://` brokers in `HUB_CLOUD_BASE_DOMAIN`. Leave it unset on desktop and self-hosted installs.
* **License tab** — Paste a `CFLX-…` code to activate, or drop a signed `.jws` file bound to the hardware fingerprint. Limits apply without a restart, and **Refresh** renews the lease. The tab doesn't start a trial.
* **Organization enrollment** — Paste an `et_…` token to enroll. The card shows **Enrolled**, **Not enrolled**, or **Enrollment pending** with the broker's reason. See [System Configuration — License](/hub/system/configuration#license).
* **MCP tab** — System Config → **MCP** turns on the broker's MCP listener, limits its tools, and creates or revokes tokens. See [System Configuration — MCP](/hub/system/configuration#mcp).

#### AI Assistant

* **Choose who answers** — Pick the HUB assistant, which calls the broker over MCP and asks before every write, or any `DEFINE AGENT` marked visible in the HUB. Installing on the broker creates a `TYPE LLM` connector and a `DEFINE AGENT`; legacy `TYPE AGENT` connectors are not listed or migrated. See [AI Assistant](/hub/ai-assistant).
* **Ollama works out of the box** — The assistant sizes Ollama's context per run (`HUB_OLLAMA_MIN_CTX` 16k to `HUB_OLLAMA_MAX_CTX` 32k), so the 4k default no longer truncates prompts. A silent model ends with a clear error after `HUB_AGENT_FIRST_OUTPUT_TIMEOUT_MS` or `HUB_AGENT_IDLE_TIMEOUT_MS` (120 s). See [Ollama requirements](/hub/ai-assistant#ollama-requirements).

#### Cluster Viewer (Beta)

* **See your cluster** — A read-only **Cluster** app shows members, the leader, data-plane links, LoT ownership, and partitions. It appears only while the host publishes cluster status. See [Cluster Viewer](/hub/cluster-viewer).
* **Clients tab** — Lists the MQTT clients on each node with user, address, traffic, last activity, queued messages, and session expiry. Filter, sort, and show the cluster's own connections on request. See [Cluster Viewer — Clients](/hub/cluster-viewer#details).

#### LoT Templates

* **Start from a template** — **Help → LoT Templates**, or **From a template…** in the LoT Editor, browses [templates.coreflux.org](https://templates.coreflux.org) and previews a template before installing it as a project. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Clone from git** — **＋ New → From git…** copies a public git repository into a new LoT Editor project. Cloning copies files only: it does not load or deploy the project. The HUB does not accept private credentials. The clone stops after 30 seconds, the whole repository becomes the project root, and a project download above 64 MB is refused. See [Clone from git](/hub/lot-editor#clone-from-git).

#### Connections

* **Generic MQTT brokers** — On a broker that isn't Coreflux, the dock keeps **Data Viewer** and **UNS Viewer** and hides Coreflux apps. Saved cards are tagged **MQTT** or **Coreflux**. See [When the broker is not Coreflux](/hub/connections#when-the-broker-is-not-coreflux).
* **Default connection** — In the web HUB, `HUB_DEFAULT_CONNECTION_HOST` and optional `HUB_DEFAULT_CONNECTION_*` variables pre-fill **New Connection**. Every browser receives the password, so use shared demo credentials only. See [Default connection (web / Docker)](/hub/connections#default-connection-web-docker).

#### Data Viewer and dashboards

* **Audio topics** — Raw PCM topics, such as an [Audio Input](/latest/lot-language/routes/media/audio-input) stream, show a live waveform you can play, clip, export to WAV, and scrub. See [Data Viewer](/hub/mqtt/data-viewer).
* **Busy buttons and markdown text** — A button with `SET AWAIT` stays busy, and each named component shows a pending indicator until its next message. The wait is 120 seconds unless `SET AWAIT_TIMEOUT` says otherwise, and then the panel shows a timeout note. `SET MARKDOWN true` on a text component renders sanitized markdown: no raw HTML, images, or unsafe links. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button).
* **Own window** — **Open in a new window** opens the Data Viewer on the current broker. See [Open the viewer in its own window](/hub/mqtt/data-viewer#open-the-viewer-in-its-own-window).
* **Panels grid** — A toggle in the Panels header switches to a grid of live dashboard thumbnails. The list stays the default. See [Managing Panels](/hub/dashboards/manager#managing-panels).

#### Desktop and settings

* **Desktop shell** — Click the logo to show the desktop. The account pill groups **Broker** administration, **Hub** (Themes and Hub Settings), and **Help**. See [Desktop shell](/hub/overview#desktop-shell).
* **Dock and status bar** — Right-click to set the dock position and auto-hide, and double-click a title bar to zoom. The same controls are in **Hub Settings → Desktop**. See [Dock and status bar](/hub/overview#dock-and-status-bar).
* **Hub Settings** — Memory limits, viewer refresh, and video wallpaper moved from System Config to **Hub Settings**. See [Hub Settings](/hub/overview#hub-settings).
* **Install and update** — Install the browser HUB as an app from `localhost` or HTTPS. The installed desktop app updates itself. See [Updating Your Coreflux](/latest/updating-coreflux#hub-desktop).
* **Walkthroughs** — Short tours on first launch and on each app's first open. Replay or reset them from **Help → Walkthroughs**. See [First-run walkthroughs](/hub/overview#first-run-walkthroughs).

#### Bug fixes

* **Maps show streets again** — Geolocation maps in the Data Viewer use keyless OpenStreetMap tiles, darkened in the dark theme, with the attribution **© OpenStreetMap contributors**. A build can set `VITE_CARTO_BASEMAPS_KEY` to use CARTO Dark Matter, or `VITE_MAP_TILE_URL` and `VITE_MAP_TILE_ATTRIBUTION` for another tile source. See [Tracking what matters](/hub/mqtt/data-viewer#tracking-what-matters).

**2.3**

August–September 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.3.4 - Login, Deploy, and Data Viewer fixes

#### Bug fixes

* **Non-admin users no longer get bounced back to the login screen** — Signing in as a user without full system access could loop back to login instead of opening the HUB in Limited Mode. The HUB now recognizes a denied `$SYS` subscription for what it is and opens Limited Mode as designed.
* **Deploy project shows accurate status** — Deploying a project via [Connections Manager](/hub/connections) no longer surfaces the broker's success response as a false warning, and the project header no longer gets stuck on **Updating** after the deploy completes.
* **LoT Editor keeps dropped files on the project** — Images and other files dropped into a project (from the Finder, Explorer, or a mixed-OS drag) now stay attached instead of being lost.
* **Data Viewer confirms whether a publish actually landed** — Sending a message no longer shows **Published** when the broker silently rejected it for lacking a publish ACL; Data Viewer now waits for the topic echo before confirming.

### 2.3.0 - LoT Editor, Connections Manager, LoT Flow wiring

#### LoT Editor

* **Visual Studio Code-style editor** — An intuitive notebookeditor with a familiar interface inside the HUB.
* **Unified Projects view** — One Projects list covering every project stored on the broker and every draft held in the HUB. The live project is marked, local-only drafts stay distinct, and each row carries its own sync state: clean, unsaved edits, changed on the broker, or diverged.
* **Push only what changed** — Push stores the working copy and deploys just the drift, instead of redeploying a whole project.
* **Broker Runtime inspector** — A table of what is actually running on the broker, with read-only source for each entity, and a jump from any running entity to the notebook that declares it.
* **Documents alongside notebooks** — Open and store Markdown, text, PDF, and images in a project, import files from disk, and reference them in LoT notebook cells.
* **Copy entities between notebooks** — Copy or drag a declared or deployed entity into another notebook.
* **Version history** Git based version control for project files.
* **Activate and Deactivate projects** from the project tree.

#### Connections Manager

* **More than one broker** — The HUB keeps a named list of broker connections with favorites, replacing the single remembered URL. Each is shown as a card on the login screen.
* **Change Broker** — Switch the whole HUB to another saved connection from the account menu, without logging out and reconfiguring.
* **Per-connection TLS** — Store a CA certificate and a client certificate against an individual connection.
* **Credentials kept off the connection record** — Passwords and client keys live in a separate store; the desktop app encrypts it using the operating system's secure storage, and the browser app never writes them to disk.
* **Live reachability on the login list** — Saved connections are probed so you can see which brokers answer before you pick one.

#### LoT Flow

* **Cleaner connections between nodes** — `KEEP`-topic edges and "matches" edges no longer clutter the canvas, and `MODEL` nodes are drawn as terminals, so the remaining edges show real data flow.
* **Topics grouped by role** — Command and telemetry topics are grouped by the role they play, with disambiguated group labels, prefix hubs backed by a topic-set panel, and wildcard subscriptions expanded to the topics they match.
* **Topic pulse toggle** — Turn live topic activity animation on or off.
* **Export the canvas as an image** — Download the current flow as a PNG.

**2.2**

July 2026

### 2.2.0 - UNS viewer & LoT Flow

* **LoT Flow** — A new interactive view of your LoT data flows, showing entity, topic, and Python nodes alongside live topic values, action traces, and route status.
* **UNS viewer** — Browse your Unified Namespace as a tree, with search, live payload previews, and a graph layout.
* **Data Viewer overhaul** — A refreshed explorer with a detailed topic view, timeline, faster topic indexing, and better subscription management.
* **In-app release notes** — A "What's New" dialog in the HUB so you can see what's changed without leaving the app.
* **Refreshed HUB styling** — Updated visual design and dock layout.
* **AI chat improvements** — A setup wizard, an artifact panel, and a generally expanded chat experience.
* **Expanded dashboard panels** — More display components, gauge options, and model-binding support for building richer dashboards.
* **Bug fixes** — Fixed the LoT compiler and dashboard rendering for `ON KEY PRESS`, `ON THRESHOLD BREACH`, conditional handlers, `WITH THEME`, numeric decimals and suffixes, threshold zones on gauges/charts, and callable actions. Fixed `INVOKE ACTION`, `BIND TO MODEL`, the accordion "Add Section," and tab titles in dashboards. Fixed real-time charts to show both traces with a legend and to correctly distinguish bar vs. line modes. Fixed select/dropdown interactions, topic-to-widget data binding (previously showing a single point instead of the full array), slider and toggle controls publishing incorrect values, icon visibility, multi-panel layouts, and events not being recognized on mount. Fixed the AI agent to properly detect uninstalled routes, and corrected its confirmation prompts. General mobile layout improvements.

**2.0**

April 2026

### 2.0.0 - UI/UX overhaul, standalone installer, AI Agent

![Coreflux HUB Data Viewer showing MQTT topic tree with live data values and real-time charts](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/hub-data-viewer.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=634b8986391a76e82ef3f03574338cb6)

Coreflux HUB Data Viewer with live MQTT topic data and charts

* **UI/UX improvements**
* **Standalone installer** — Windows and Linux
* **AI Agent**
  * **Insights mode** — Ask questions about running data, using project information as context
  * **Agent mode** — Build LoT, routes, and dashboards with an AI copilot

**VS Code Extension**

**1.0**

August–October 2026

These notes are VS Code extension **1.0**. Features that use the broker's new commands need broker **2.22**.

### 1.0.0 - Things, Agents, Validate, MCP, and licensing

This release lets you write Things and Agents in notebooks, check your LoT on the broker before deploying, connect your AI tools to the broker's MCP server, and manage licensing, all from VS Code.

#### Highlights

* **Write Things and Agents where you already write LoT** — Check them against the broker and deploy them from the notebook, the same way as any other cell. See [THING cells](/lot-notebooks/usage#thing-cells).
* **Check before you deploy** — Validate a cell or the whole notebook on the broker. Problems show on the cell, and nothing is deployed until you run it. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Switch a cell off without deleting it** — Disable an action, connector, or agent from the cell status bar, and turn it back on when you want it running. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **Connect your AI tools in one step** — The MCP Server tab writes the broker endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Teach your coding agent LoT** — Install the Coreflux skills so the agent writes valid LoT and works with the broker. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **License and enroll from VS Code** — Activate with a code, install a signed license, or enroll the broker, from the License tab. See [License tab](/lot-notebooks/usage#license-tab).

#### LoT cells

* **Things** — A run sends the cell's `DEFINE THING` blocks and their workspace templates as one `-addThing`, after a `--dryRun` whose problems show on the cell. **Remove Thing from Broker** sends `-removeThing`, and a quick fix updates older THING syntax (`TEMPLATE`, and `{p}` to `{{p}}`). See [THING cells](/lot-notebooks/usage#thing-cells).
* **Agents** — `DEFINE AGENT` cells are checked like the broker checks them and deploy with `-addAgent`. Broker agents appear in the Coreflux Explorer and the Entities panel. See [Agent cells](/lot-notebooks/usage#agent-cells).
* **Validate** — Check a cell or the whole notebook on the broker without deploying it. Results appear under the cell and in Problems. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Enabled / Disabled toggle** — Switch `DISABLE true` on and off for action, connector, and agent cells from the cell status bar, and the change uploads. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **`DEFINE CONNECTOR`** — Recognized in checks, completions, and hovers, with `DEFINE ROUTE` as its alias. Connector cells upload from the cell, and Deploy Project includes them.
* **`RETURN AS` under `CALL`** — A `RETURN AS` line under a `CALL` no longer reports an indentation error.
* **Panels and themes** — `DEFINE PANEL` and `DEFINE VISU` cells, and a Thing's `WITH PANEL` body, are checked with the broker's panel parser. Highlighting, hover, completions, and a `DEFINE PANEL` snippet are included. Running the cell sends `-addVisu`; removing it sends `-removeVisu`. `DEFINE THEME` and `THEME_VARIANT` are recognized. The cell status bar offers **Open in Coreflux HUB** to view the rendered panel, and a successful upload suggests opening Dashboards there. See [Panel cells](/lot-notebooks/usage#panel-cells).
* **Agent and Thing checks match the broker** — Valid agent, thing, rule, connector, and model syntax is no longer flagged, including connector keys such as `SUBJECT` and mixed-case names. See [Agent cells](/lot-notebooks/usage#agent-cells).

#### Broker management

* **License tab** — Activate with a `CFLX-…` code, install signed license text, enroll with an `et_…` token, and refresh the lease. The Instance Key field is gone. See [License tab](/lot-notebooks/usage#license-tab).
* **MCP Server tab** — Turn on the broker's MCP server, pick its tools, and manage tokens. **Install MCP server** writes the endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop, and keeps workspace config files out of Git. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Install Agent Skills** — **Install Agent Skills...** lets you pick which of the 11 bundled skills to install and where (the `.agents`, `.claude`, `.cursor`, or `.github` skills folder, in the workspace or your home folder). Skills come from the public [coreflux-skills](/ai/agent-skills) repository (broker 2.22 or later), and older copies from previous versions are offered for removal. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **Remove All Things / Templates** — Two new commands clear every Thing or every template from the broker.
* **Variables** — "Environment Vars" is now "Variables" everywhere, including **Secrets & Variables**.

#### Data Viewer and workspace

* **Bounded history** — Each topic keeps its last 100 messages by default (`coreflux.dataViewer.historyBufferPerTopic`, 50 to 2000), set from the timeline gear. The timeline draws again, and pausing or scrubbing stays steady while messages arrive. See [Adjust how you see the data](/lot-notebooks/debug#adjust-how-you-see-the-data).
* **Apps in the editor area** — Data Viewer, Logs Viewer, and Secrets & Variables open as tabs next to your notebooks.
* **Connection Manager** — Save several broker connections and switch between them.
* **Entities table** — See the LoT entities running on the broker in their own table.
* **LoT projects** — Create, edit, and deploy LoT projects.

**beta**

April 2026

![Screen recording of creating and deploying LoT in the Coreflux VS Code extension](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-and-deploy-lot.gif?s=5cd139e03cbf0b5109848b498d7c65eb)

Create and deploy LoT from the Coreflux VS Code extension

* **Improved VS Code extension (beta)**
  * License usage
  * Live MQTT data (topic tree)
  * **Data Viewer** — View and replay historical and live data for MQTT topics, with viewers for raw, JSON, PDF, GeoJSON (map), audio, and more
  * **Execution trace** — View and replay historical and live data from LoT execution, including success and error states, published topics, and internal variables
  * Manage secrets and environment variables


# Release Notes
Source: https://docs.coreflux.org/product-updates/release-notes

New features, improvements, and fixes in each release of the Coreflux MQTT broker and HUB.

Product

**MQTT Broker**

**2.22**

August–October 2026

> [!WARNING]
>
> **Breaking Changes** in this release (2.15–2.22):
>
> **`TYPE MCP_SERVER` is gone** — The MCP server is now broker configuration, not a LoT connector, and a project that still defines `TYPE MCP_SERVER` fails to load. Enable `Mcp.Enabled` (or `COREFLUX_MCP_ENABLED=1`), mint a token with `-createMcpToken`, and point the client at Streamable HTTP `/mcp`. Legacy SSE URLs stop working. The MCP client connector (`TYPE MCP` / `CALL MCP`) is unchanged. **Action:** remove old `TYPE MCP_SERVER` definitions and follow [MCP Server](/latest/mqtt-broker/mcp-server).
>
> **`TYPE AGENT` connectors are removed** — `-addConnector` refuses them and stored ones are skipped at load, with their topics. Rewrite each as a `TYPE LLM` connector plus `DEFINE AGENT … USES LLM CONNECTOR`; nothing is granted until `ADD TOOL`, and writes need `WITH LEVEL "write"`. There is no automatic migration. **Action:** rewrite agents before you upgrade. See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).
>
> **No built-in trial** — A broker with no license runs as **Community**. Get a 30-day Growth-type license at [portal.coreflux.org](https://portal.coreflux.org), where you also manage your fleet.

### 2.22.0 - Things, Agents, licensing, and a built-in MCP server

This release lets you model devices once and reuse them (Things), build AI agents that only do what you allow, and connect tools like Cursor or Claude Desktop straight to the broker. It also adds signed licensing with fleet enrollment, certificate management, and clustering that runs your LoT on every node.

#### Highlights

* **Model a device once, then reuse it (Things, preview)** — Describe a pump, a line, or a sensor type once. Each copy gets its own topics, and you add as many as you need without copying LoT. See [Things](/latest/lot-language/things/overview).
* **Let AI act only where you allow it (Agents, preview)** — An agent starts with no tools. You grant each read or write, and a question-only mode never changes the broker. See [Agents](/latest/lot-language/agents/overview).
* **Work on the broker from Cursor or Claude** — A built-in MCP server lets those tools run broker commands, with tokens you create and revoke. See [MCP Server](/latest/mqtt-broker/mcp-server).
* **Keep every cluster node on the same LoT** (**Beta**) — Deploy to any node and the whole cluster runs it. A device connector can stay on the node that can reach the equipment. See [LoT in a cluster](/latest/mqtt-broker/clustering#lot-in-a-cluster).
* **License a broker and add it to your fleet** — An unlicensed broker runs as Community. Activate online, use a signed file where there is no internet, and enroll the broker in your organization. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).
* **Replace certificates without a restart** — Update the certificate the broker presents, choose which clients to trust, and see which certificates are about to expire. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Sign in with your identity provider** — Clients can use an OIDC access token as the MQTT password. Local passwords still work. See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Pause logic without deleting it** — Turn an action, connector, or agent off, keep the definition, and turn it back on when you are ready. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **See when a device is actually down** — Industrial connectors show Reconnecting when a PLC stops answering, and the last good tag values stay in place through a short disconnect. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **Bring in audio, gRPC, and hundreds of APIs** — Capture microphone audio onto MQTT, call gRPC services, and start from 220+ REST API app templates (technical preview). See [REST API Apps](/latest/lot-language/routes/rest-api-apps/index).

#### Things and Agents (preview)

* **Define a device once** — A Thing is a typed device with `{{placeholder}}` topics. Add instances with `-addThing` (use `--dryRun` to validate first), and manage them with `-removeThing` and `-listThings`, or the MCP tools `add_thing`, `list_things`, and `remove_thing`. Each Thing publishes its source, tree, and health under `$SYS/Coreflux/Things/<name>`. See [Things commands](/latest/mqtt-broker/commands#things).
* **Agents with limited access** — An agent uses a `TYPE LLM` connector for its provider, model, key, and price, and starts with no tools. It gets only what `ADD TOOL` grants. Agents can ask each other for help with `WITH AGENTS`, and actions call them with `CALL AGENT`. Each agent publishes its card and status under `$SYS/Coreflux/Agents/<name>/`.
* **Read-only questions** — Ask an agent with `"mode": "insight"` and it only reads, including any agents it delegates to. `TYPE LLM` also accepts `REASONING_EFFORT` (`none` to `extra_high`).

#### New connectors

* **Audio Input** — Capture a microphone, test tone, silence, or a file as 16-bit PCM audio on MQTT (`TYPE AUDIO_INPUT`). See [Audio Input](/latest/lot-language/routes/media/audio-input).
* **gRPC** — Call gRPC services from MQTT with `TYPE GRPC`, including streaming. See [gRPC Connector](/latest/lot-language/routes/streaming/grpc).
* **REST API apps** — 220+ ready-made `TYPE REST_API` templates for cloud, ERP, MES, messaging, and IIoT services, in technical preview. See [REST API Apps](/latest/lot-language/routes/rest-api-apps).

#### MQTT and LoT

* **Connectors naming** — `DEFINE CONNECTOR` and the `-addConnector`, `-removeConnector`, `-listConnectors`, `-removeAllConnectors`, and `-checkConnectorConnection` commands are the new names. `DEFINE ROUTE` and the `-…Route…` commands keep working as aliases.
* **Turn things off without deleting them** — Put `DISABLE true` under `DEFINE` on an action, connector, or agent to keep it stored but not running. Switch it back on with `-disableAction`, `-disableConnector`, `-disableAgent` and the matching `-enable…` commands, or with MCP tools. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **Publish with retain and QoS** — `PUBLISH TOPIC` accepts `RETAIN` and `QOS0` / `QOS1` / `QOS2` (default QoS 0). `KEEP TOPIC` still only stores a value for `GET TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#publish-topic).
* **Shared subscriptions** — Turn on `SharedSubscriptions` and `$share/{group}/{filter}` delivers each message to one member of the group. Off by default. See [Shared subscriptions](/latest/mqtt-broker/protocol#shared-subscriptions).
* **Predictable topic triggers** — `ON TOPIC` actions, models, and connector events run on the exact message that fired them, in publish order per topic. Different topics still run in parallel. See [Action Triggers](/latest/lot-language/actions/events).
* **Every publish in an action is sent** — Each `PUBLISH TOPIC` or `KEEP TOPIC` in one run is delivered, in the order written, with that line's own retain, QoS, and keep settings. A later `GET TOPIC` in the same run reads the value just written. In a cluster, only the last `KEEP` of each topic is replicated. See [PUBLISH TOPIC](/latest/lot-language/actions/operations#publish-topic).
* **Panel wait and markdown** — A button accepts `SET AWAIT "Id, Id"` and `SET AWAIT_TIMEOUT` (seconds, default 120). A text component accepts `SET MARKDOWN true`. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button) and [Markdown text](/latest/lot-language/panels/defining-panels#markdown-text).

#### Licensing and enrollment

* **Plans** — Community, Growth, and Enterprise, with limits on artifacts and connectors. Status is on retained `$SYS/Coreflux/License` and, on the ops port, `GET /license` (port `9100`, keep it private).
* **Three ways to license** — Activate online with `COREFLUX_ACTIVATION_CODE` or `-activateLicense CFLX-…` (limits apply without a restart, the lease refreshes daily, `-refreshLicense` forces it). Or install a signed license file (`config/license.jws`, `COREFLUX_LICENSE_FILE`, `COREFLUX_LICENSE_TOKEN`, or `-loadLicense`), which the broker verifies locally with no network. For air-gapped hosts, send the `--show-fingerprint` value to Coreflux and install the hardware-bound license you get back.
* **Enroll in your organization** — `-enroll et_…` (or `--enroll`, or `config/enrollment-token`) binds the broker to your Coreflux organization, separately from its plan. An activation code enrolls it too. A broker waiting for enrollment still starts: local users work, and logins that need the organization are refused until it succeeds. `$SYS/Coreflux/License` explains why it is pending. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

#### MCP server

* **Connect AI tools to the broker** — Cursor, Claude Desktop, and other MCP clients connect to the broker's built-in server, configured in the `Mcp` block (port `6278`, bound to `127.0.0.1`, path `/mcp`). Manage tokens with `-createMcpToken`, `-listMcpTokens`, and `-revokeMcpToken`, or from the HUB **MCP** tab. In Docker or Kubernetes, bind to `0.0.0.0`, publish `6278`, and route `/mcp` behind TLS. See [MCP Server](/latest/mqtt-broker/mcp-server#docker-and-kubernetes).
* **Install agent skills** — The public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository is generated from the broker, and the broker exposes the same pack as the `coreflux://skills` MCP resource. Coding agents that install it write LoT the broker accepts. They need broker 2.22 or later. See [Agent skills](/ai/agent-skills).

#### Security

* **Sign in with OIDC** — With `Oidc.Enabled`, a client sends an OIDC access token as its MQTT password. The broker validates it, checks the organization, and authorizes by the token's groups. Local passwords still work. A client is disconnected when its token expires (30-second grace). See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Manage certificates from a command** — `-brokerCertificates` (admin only) shows and replaces the server certificate and Root CA, and manages the mTLS trust store: list, import, export, revoke, settings. A new server certificate applies without a restart and keeps a `.bak-` copy. Revocation is immediate and every change is audit-logged. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Know when certificates expire** — Retained `$SYS/Coreflux/Certificates/Summary` counts valid, expiring, expired, and unreadable certificates. `CertificateExpiryThresholdDays` (default 30) sets the warning window. See [`$SYS/Coreflux/Certificates/Summary`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary).
* **Easier trust store** — `ClientCertificateSourcePath` loads `.pem`, `.crt`, `.cer`, `.der`, and unprotected `.p12`/`.pfx` files, skips anything in `revoked/`, and refuses keys and CSRs (install a server key with `replaceServer`). `$SYS/Coreflux/Config` shows `ServerCertificatePassword` as `********`.

#### Clustering and operations

* **LoT works across a cluster** (**Beta**) — Definitions replicate through the leader, so you can send LoT to any node and every node runs the same version. Each message runs LoT once, on the node it entered. Timers, `ON START`, and device connectors run on one owner and move to another node within about 10 seconds if it fails. Pin a device connector to a node with `CLUSTER_NODE` in `ROUTE_CONFIG`. **Action:** upgrade every node before you change LoT, and create users on every node.
* **Faster Kubernetes scaling** (**Beta**) — A pod that the headless Service no longer lists leaves the cluster about 2 minutes after its cluster port stops answering (`MemberAbsentFromDiscoverySeconds`, 120 seconds by default; it used to wait 5 minutes). New pods are found within seconds. See [How a cluster works](/latest/mqtt-broker/clustering#one-leader-automatic-membership).
* **More metrics** — New `/metrics` series for delivered messages, CPU, auth failures, ACL denials, rate limits, connector drops, and errors. See [Metrics](/latest/mqtt-broker/operational-endpoints#metrics).
* **Fleet health reporting** — An enrolled broker reports CPU, memory, clients, traffic, refusals, drops, and scrubbed error signatures to the Coreflux Portal. It never sends topics, payloads, hostnames, or IPs. Turn it off in the portal, or with `COREFLUX_FLEET_METRICS=off` or `DO_NOT_TRACK=1`. See [Fleet performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics).

#### Bug fixes

**Industrial connectors**

* **Connection status tells the truth** — Modbus, S7, OPC UA, EtherNet/IP, ADS, Allen-Bradley, FINS, and BACnet no longer wipe retained tag values on a disconnect or failed read, and a restarted connector polls again. A connector no longer shows Connected while its device is unreachable: after 3 failed read cycles it reports Reconnecting and rebuilds the connection. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **No more hangs on silent devices** — A PLC that accepts a connection but never answers no longer freezes S7 (`READ_TIMEOUT` now limits the connect) or EtherNet/IP (`READ_WRITE_TIMEOUT` now bounds every exchange). **Action:** raise `READ_WRITE_TIMEOUT` for slow EtherNet/IP devices.
* **Modbus TCP** — Each connection runs one request at a time, so tags no longer go BAD with "Response was not of expected transaction ID". See [Modbus TCP Client](/latest/lot-language/routes/industrial/modbus-tcp-client#one-request-at-a-time).
* **FINS** — A slow reply no longer shifts later reads onto the previous command's value, and a lost PLC goes to Reconnecting after 2 unanswered commands. Replies must now match the request and come from the addressed node. **Action:** gateways that swap client and server nodes now time out; check `LOCAL_NODE` / `REMOTE_NODE`. See [FINS](/latest/lot-language/routes/industrial/fins).
* **Allen-Bradley** — A slow but healthy PLC no longer reconnects every cycle, and a timed-out write publishes `"outcome": "unknown"`. See [Write results](/latest/lot-language/routes/industrial/overview#write-results).
* **ADS** — `TIMEOUT` now applies to every request (it was ignored and fixed at 5 s), and an unreachable PLC makes the connector reconnect. See [ADS](/latest/lot-language/routes/industrial/ads).
* **OPC UA** — A read or write that races a reconnect marks the tags BAD and backs off instead of counting as success, and sessions no longer leak.
* **BACnet** — Integer writes of any size send the right value (out-of-range 64-bit values fail instead of being cut off), and reads queued on a dropped connection no longer break the new one.
* **Tag values** — Negative `OFFSET`, `MIN_VALUE`, and `MAX_VALUE` now parse. See [Common TAG parameters](/latest/lot-language/routes/industrial/overview#common-tag-parameters).

**Other connectors**

* **Kafka** — A `"in"` event commits its offset only after the message is published, so a crash no longer drops records. `WITH EVERY` on a Kafka event is now rejected when you add the connector. **Action:** publish on a schedule with `ON EVERY` in a LoT action. See [Kafka Connector](/latest/lot-language/routes/streaming/kafka).
* **Kafka and gRPC start** — A connector that fails to start is retried in the background (2 to 60 seconds) until it starts or you remove it.
* **Ollama** — A `TYPE LLM` connector with `PROVIDER ollama` takes `CONTEXT_WINDOW` (a fixed `num_ctx`, sized per call and capped at the model's maximum), `MAX_CONTEXT_WINDOW` (default 32768, minimum 16384), `FIRST_OUTPUT_TIMEOUT` (default 120 s), and `IDLE_TIMEOUT` (default 60 s). Agent tasks fail with a clear error (`llm_timeout`, `llm_unreachable`, `model_not_found`, `context_overflow`) instead of hanging. See [Ollama context and timeouts](/latest/lot-language/routes/ai-routes#ollama-context-and-timeouts).
* **Email and CrateDB** — Email `ADD EVENT` blocks now send and publish their status. CrateDB `ADD EVENT` blocks run, `STORE IN` writes rows, and the connector reconnects after a CrateDB restart.
* **REST API** — A reply published right away on `REPLY_TOPIC` reaches the HTTP client instead of a 504, and concurrent requests no longer cancel each other. A value in `ENDPOINT` can no longer send the request and its credentials to another host; the broker refuses it and publishes `RequestRejected`. See [Placeholder Support](/latest/lot-language/routes/rest-api-routes#placeholder-support).
* **MQTT bridge** — A bridge without `CLIENT_ID` forwards inbound messages and no longer clashes with other bridges, and a removed bridge stops forwarding at once.
* **Sparkplug B** — The Primary Host tracks `seq` per edge node and no longer floods Rebirth requests, and DATA metrics without a datatype decode using the birth certificate.
* **`TRIGGER` on LLM, AGENT, and MCP** — MCP calls the named tool, and LLM and AGENT results go to the mapping's `DESTINATION_TOPIC` or the default response topic instead of being discarded.

**LoT and MQTT**

* **`GET MODEL`** — `SET … WITH GET MODEL` no longer fails on the action's first run, `PUBLISH TOPIC … WITH GET MODEL` parses, and `WHERE` conditions joined with `AND` accept any mix of text and numbers. See [GET MODEL](/latest/lot-language/actions/operations#get-model).
* **`STORE IN … WHEN`** — Conditional model storage works instead of failing on first evaluation, and an unknown field is rejected at deploy. See [Store data with models](/latest/lot-language/routes/data-storage/overview#step-2-store-data).
* **`MATCHES REGEX`** — Patterns with `\d`, `\w`, `\s`, or `\.` work as written. See [MATCHES REGEX](/latest/lot-language/rules/syntax#matches-regex).
* **`TRIGGER` statements** — The line after a `TRIGGER` is no longer dropped. Examples now use `TRIGGER "<connector>" TO <data> FOR "<event>"`; code copied from the old order (`WITH "<event>" FOR <data>`) still deploys but swaps the data and the event. See [TRIGGER Statement](/latest/lot-language/actions/operations#trigger-statement).
* **MQTT 5 denials** — A denied publish now gets `0x87 Not authorized` and a rate-limited one `0x97 Quota exceeded`, instead of Success. See [What a denied client sees](/latest/lot-language/rules/rbac#what-a-denied-client-sees).
* **Callable actions from panels** — Object, array, and `null` arguments no longer cause a compile error; objects and arrays arrive as JSON text.
* **Protobuf `float` and nested `GET PROTO`** — `ADD FLOAT` (alias `ADD SINGLE`) decodes proto `float`, and dotted `GET PROTO` paths read nested messages. A field with the wrong type is skipped instead of stopping the whole message. See [Protobuf Models](/latest/lot-language/models/protobuf).

**Panels, projects, and platform**

* **Panels** — Boolean CSS bindings (`BIND CSS … AS BOOLEAN`) convert correctly in the HUB. SVG markup from `SET INLINE` and `data:` sources is rebuilt from an allow-list so scripts, event handlers, and external links can't run in viewers' browsers; what was removed is listed as a deploy warning.
* **Projects** — A live project's history records only the edited cell, not the whole notebook. After a restart, the broker also loads connectors added outside the project and the connectors of Things, and publishes Thing status from boot. See [LoT THING](/latest/lot-language/things/overview).
* **Metrics** — Published-message and byte counters no longer reset at UTC midnight, so `rate()` works across it. `coreflux_messages_published_total` now counts client publishes; deliveries moved to `coreflux_messages_delivered_total`.
* **Linux packages** — APT and DNF units run the broker as the user `coreflux` with `CAP_NET_BIND_SERVICE`, so they can bind ports below 1024. See [Ports below 1024](/latest/mqtt-broker/startup-options#ports-below-1024).

**Configuration**

* **Partial config is merged** — A partial JSON object published to `$SYS/Coreflux/Config/New` is merged into the live configuration. Fields you omit, including bind addresses, stay as they are. See [Applying Configuration](/latest/mqtt-broker/configuration#via-mqtt-topic).

**2.14**

August 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.14.3 - Default rules and Visu panel publishing

#### Bug fixes

* **Default rules load with an active project; Visu panels can be published** — When a project is already active at startup or after `-loadProject`, the broker's seeded permission rules now apply correctly so internal clients retain `$SYS` access and panels publish to `$Visu/...` topics again after project activation.

### 2.14.2 - Sparkplug B connector, MQTT & LoT performance improvements

Sparkplug B Support, MQTT client lifecycle action triggers, better OT master/client visibility in broker logs, a banded Rules precedence model, project lifecycle improvements, and faster publish, LoT, and connector dispatch.

#### Improvements

* **Rules priorities are now banded** — The rule priority number line is split into bands: `0`–`99` is reserved for the broker's immutable system rules, `100`–`999 999` is your band, and the permissive catch-alls `AllowPublishTopic` / `AllowSubscribeTopic` now sit at `1 000 000`. Only the strongest matching band decides an operation, where a DENY beats an ALLOW (deny-wins) and nothing matching means denied (default-deny). Moving the catch-alls to the weakest band **fixes a topic-visibility bypass**: they previously shipped tied with everything else, so a specific access rule could not reliably override the allow-all fallback — which left Visu panel view topics effectively public. `-addRule` now rejects priorities outside `100`–`1 000 000`. **Action:** custom rules written in the old `1`–`99` range are clamped to `100` on load and logged individually. Clamping keeps them in force, but several rules can land on `100` together, where ties resolve deny-wins — re-space them across the user band, putting the more specific rule at the lower number. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac#rule-precedence).
* **`AllowConnect` seed and `FOR Connect` rules** — Fresh brokers now ship a third permissive catch-all, `AllowConnect`, at priority `1 000 000` (the same weakest band as `AllowPublishTopic` / `AllowSubscribeTopic`). Write `FOR Connect` rules in the user band to decide who may connect after authentication; they outrank the seed. Brokers with no Connect rule at all still leave CONNECT ungated. `-restoreRules` puts all three seeds back to their shipped ALLOW definitions. See [RBAC](/latest/lot-language/rules/rbac#connection-admission) and [`-restoreRules`](/latest/mqtt-broker/commands#restoring-seeded-rules).
* **Project manifests, entity ownership, and ad-hoc entities** — Each stored project publishes a retained content manifest on `$SYS/Coreflux/Projects/{name}/manifest` (SHA-256 of exact file bytes, plus entities declared in `.lotnb` cells). `-projectManifest` returns the same JSON on demand. Running entities are attributed on `$SYS/Coreflux/Entities/ownership` and in the `-listEntities` / `-loadProject` `origin` field. **Loading or unloading a project no longer deletes ad-hoc entities** added with `-addAction` and similar commands while no project was active. **Action:** if you relied on Activate to wipe the whole runtime, remove those entities explicitly before loading a project. See [Project Commands](/latest/mqtt-broker/commands#project-commands) and [Project Topics](/latest/mqtt-broker/sys-topics#project-topics).
* **Loaded projects stay active after a restart** — After `-loadProject` (or `--project`), the last loaded project is remembered and re-activated on the next start unless you pass `--project`. `-unloadProject` returns to standalone mode on the next restart. See [Startup Options](/latest/mqtt-broker/startup-options#loading-a-project-at-startup).
* **`ON START` runs on deploy; action publishes are no longer blocked by user ACL** — Deploying an `ON START` action on a live broker executes the body immediately (cold start still runs once after the MQTT broker is ready). Action `PUBLISH` / `KEEP` still put messages on MQTT for any subscriber; they are no longer denied by user publish rules, so bootstrap topics from actions are not silently dropped. Clients still need subscribe permission to receive those messages. See [Initialization Triggers](/latest/lot-language/actions/events#initialization-triggers).
* **OT string sizing — `LENGTH` is the preferred keyword** — Across OT connectors that support configurable string sizing, `WITH LENGTH` is now the documented primary keyword; `STRING_SIZE` remains accepted as a parser alias. See the shared [String sizing by Connector](/latest/lot-language/routes/industrial/overview#string-sizing-by-connector) reference on the industrial connectors overview.
* **Modbus Server STRING defaults and cap** — Unsized `STRING` tags no longer reserve a single register (which silently truncated barcodes and caused Illegal Data Address on FC16 writes). The server now defaults to **40 bytes (20 registers)** and warns when size is omitted. Connector validation rejects `LENGTH` values above **246 bytes (123 registers)**, the FC16 write cap. See the [Modbus TCP Server Connector guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **Modbus Server and OPC UA Server activity logging** — Modbus Server connectors log accepted and rejected master writes (plus rejected reads), with bank-aware function-code labels and `LENGTH` guidance when an undeclared holding-register range is the cause; connection open/close counts are logged from the existing watchdog (**the master's source IP is not available**). OPC UA Server connectors log client session create/close events and accepted external writes on tags and STRUCT fields.
* **MQTT client lifecycle action triggers** — New `ON CONNECT DO`, `ON DISCONNECT DO`, and `ON SUBSCRIBE ["pattern"] DO` triggers run LoT automation when clients connect, disconnect, or subscribe. Action bodies expose session context via `CLIENTID`, `USER`, `ENDPOINT`, `CLEANSESSION`, `DISCONNECTREASON`, `SUBSCRIBETOPIC`, and `SUBSCRIBEQOS`. The broker only evaluates lifecycle hooks when at least one action defines them. See [Action Triggers](/latest/lot-language/actions/events#client-lifecycle-triggers).
* **Improved command response handling** — Broker command responses are now consistently structured as JSON. Each command may include a `requestId` field, allowing you to easily correlate requests and responses.
* **Sparkplug B connectors (beta)** — Decode Sparkplug B protobuf into readable JSON, publish Coreflux topics as an edge node, or run Coreflux as the Primary Host Application with namespace state, commands, and automatic rebirth requests. See the [Sparkplug B Connector](/latest/lot-language/routes/system/sparkplug-b) and [Sparkplug Host Connector](/latest/lot-language/routes/system/sparkplug-host) guides.

#### Performance

* **MQTT between clients** — More messages complete per second, the slowest publishes finish sooner (about 10% lower p99 latency). Messages that update connector topics stay in the order they arrived.
* **LoT rules and actions** — Permission checks, topic triggers, timers, and dashboard invokes no longer slow down as more distinct topics exist on the broker. LoT-heavy traffic that was about **10× slower at 30,000 topics** — and about **70× slower at 100,000** — now stays as fast as it was on a nearly empty broker. `USER HAS` and `USER IN GROUP` checks stay fast as the user list grows.
* **Connector mappings** — Adding mappings no longer makes every publish more expensive, including on topics that no mapping uses. Exact-topic mappings (the common case) keep up with tens of thousands of messages per second at **sub-millisecond** latency with **no loss** — the same flood previously took around **25 seconds** and dropped some messages. Wildcard mappings (`+` / `#`) now deliver fully as well. When a connector cannot keep up, memory stays bounded: the broker waits, then drops the **newest** arriving message rather than older ones already in flight. Set `ADD ROUTE_CONFIG` on a connector (`OVERLOAD_POLICY`, `OVERLOAD_TIMEOUT`, `OVERLOAD_CAPACITY`) when that connector needs a different wait-or-drop contract. See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward).

#### Bug fixes

* **Rules with `IF` and no `ELSE` now compile** — `IF USER IS "dashboard" THEN DENY` (no `ELSE`) previously failed compilation on first evaluation and was treated as a deny for every matching publish or subscribe. The missing branch is now the opposite of the `THEN` decision. See [Rules Syntax](/latest/lot-language/rules/syntax#combining-conditions).
* **Python scripts no longer lose their code on restart** — Scripts that contained blank lines were truncated down to the `# Script Name:` header after a reboot, so `CALL PYTHON` failed even though the script still appeared in listings. Complete scripts now persist across restarts. See [Python Integration](/latest/lot-language/actions/python-integration#writing-python-scripts).
* **Built-in rules survive project add/load/unload** — Adding or switching a project no longer wipes the broker's default permission rules, so internal clients keep `$SYS` access. See [RBAC](/latest/lot-language/rules/rbac#seed-catch-alls).

**2.2**

July 2026

### 2.2.0 - Kafka, OPC UA Server & Modbus Server routes

* **Kafka route** — Connect Coreflux directly to Kafka as a producer or consumer, with support for security protocols and configurable batching and compression. See the [Kafka Route guide](/latest/lot-language/routes/streaming/kafka).
* **OPC UA Server route** — Expose Coreflux data to OPC UA clients with a secure-by-default setup, including support for array and struct nodes. See the [OPC UA Server Route guide](/latest/lot-language/routes/industrial/opcua-server).
* **Modbus Server route** — Serve Modbus data over TCP, with experimental support for Serial (RTU) connections. See the [Modbus TCP Server Route guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **OT route persistence** — Server routes (OPC UA Server, Modbus Server) persist their state and recover automatically after a restart, so data isn't lost on reconnect. See [OPC UA Server persistence](/latest/lot-language/routes/industrial/opcua-server#data-persistence--recovery) and [Modbus Server persistence](/latest/lot-language/routes/industrial/modbus-tcp-server#data-persistence--recovery).
* **OPC UA client certificate authentication** — Authenticate OPC UA client connections using PKI certificates for more secure deployments.
* **Modbus one-based addressing** — Set `WITH ONE_BASED_ADDRESSES true` on Modbus client and server routes so tag addresses match device manuals that label registers starting at 1. See [Modbus addressing](/latest/lot-language/routes/industrial/modbus-tcp-client#modbus-addressing) (client) and [Address notation](/latest/lot-language/routes/industrial/modbus-tcp-server#address-notation) (server).
* **Publish payload as bytes** — Forward or retain binary MQTT payloads bit-for-bit with `PAYLOAD AS BYTES` on `PUBLISH TOPIC` and `KEEP TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#binary-passthrough--payload-as-bytes).
* **EtherNet/IP route** — Joined attribute reads (`ENABLE_JOIN_ATTRIBUTE`), bit extraction (`BIT_ADDRESS`), ARRAY/STRUCT decoding from assembly buffers, bidirectional `WRITABLE` tags, and legacy Hub Asset field mapping for migrations. See the [EtherNet/IP Route guide](/latest/lot-language/routes/industrial/ethernetip).
* **Allen-Bradley route** — Symbolic tag-name access (`Program:MainProgram.Tag` format), `AB`/`ALLENBRADLEY` route aliases, `PATH` vs `SLOT` routing, family-specific STRING/TIME encoding, and cross-link to EtherNet/IP for explicit CIP paths. See the [Allen-Bradley Route guide](/latest/lot-language/routes/industrial/allen-bradley).
* **Bug fixes** — Fixed BACnet alarm retention, EtherNet/IP connection parameters and legacy-style compatibility, a Modbus TCP word-order issue, an OPC UA client connection issue, and a licensing load-order.

**2.1**

June 2026

### 2.1.0 - BACnet route (building automation) and Protobuf models

* **BACnet route** — Connect Coreflux to building automation systems (HVAC, lighting, metering) and bridge them to MQTT
  * Read live values and write setpoints to BACnet controllers
  * Get instant updates on change, without constant polling
  * Receive alarms and event notifications directly in MQTT

See the [BACnet Route guide](/v2.1/lot-language/routes/industrial/bacnet) to get started.

* **Protobuf LoT models (beta)** — Decode and encode binary protobuf on MQTT from LoT: `WITH FORMAT PROTOBUF` (or `BOTH`), `PROTO_TAG` to match vendor `.proto` field numbers, `ADD MODEL` for nested messages on publish, `GET PROTO` / `GET PROTOBUF` to read top-level fields, and `PUBLISH MODEL` to emit real protobuf bytes (not JSON-in-bytes). `WITH FORMAT BOTH` keeps JSON on the main topic and binary on a `/protobuf` sidecar topic.

See [Protobuf Models](/latest/lot-language/models/protobuf) for more details.

**2.0**

April–June 2026

### 2.0.3 - OT tags & route stability

* **OT tag JSON publish** — Message payload now includes the `unit` field
* **Modbus and EthernetIP routes** — Stability improvements

### 2.0.2 - ON CHANGE trigger and bug fixes

* **`ON CHANGE` trigger for LoT actions** — Run actions only when the message payload on a topic is different from the last message on that same topic. Use it for high-frequency telemetry, historians, and forwarding when you do not need to process duplicate values; `ON TOPIC` still runs on every matching publish.
* **Bug fixes** — Stability and correctness improvements across the broker, LoT, and HUB

### 2.0.0 - AI Agent route in the broker

* **AI Agent route** — Create custom agents usable within LoT for AI-driven steps and logic
* **Cloud and local LLMs** — Support for both on AI features

**1.10**

March 2026

### 1.10.0 - Protobuf & REST API route

Support for environment variables and secrets on LoT

* **Protobuf** support
* **REST API route** with OAuth and JWT support
* **Default project on boot** — Load a default project to a Coreflux broker when the broker starts

**HUB**

**2.12**

September–October 2026

### 2.12.0 - Things, Agents, certificates, fleet sign-in, and Cluster Viewer

This release brings the new broker features into the HUB: build and monitor Things and Agents, manage certificates and licenses without leaving the app, sign in with your Coreflux account, and see your cluster at a glance.

#### Highlights

* **Build and watch Things and Agents in the HUB** — Edit them in the LoT Editor, see how they connect in LoT Flow, and turn an action, connector, or agent off without deleting it. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Renew certificates from the app** — Replace the server certificate, trust or revoke a client, and see what is about to expire, without a restart or a shell. See [Certificates](/hub/system/certificates).
* **Open the brokers in your organization** — Sign in with a Coreflux account and connect to your fleet from the login screen. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Activate and enroll without leaving the HUB** — Paste an activation code or a signed license, or enroll the broker in your organization. See [License](/hub/system/configuration#license).
* **See the cluster from the host you already opened (Beta)** — Members, the leader, which links are up, which node owns each piece of LoT, and the clients on each node. See [Cluster Viewer](/hub/cluster-viewer).
* **Start from a template or a public git repo** — Install a Coreflux template as a project, or copy a public repository into the LoT Editor. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Hear live audio and wait on a button** — Data Viewer plays a raw audio topic. A dashboard button stays busy until the work it started finishes. See [Listening to PCM audio](/hub/mqtt/data-viewer#listening-to-pcm-audio).

#### Things and Agents (preview)

* **Things in the LoT Editor** — Deploy THING cells as one payload, checked first with `-addThing --dryRun`. **Broker runtime → Things** lists roots, instances, and their read-only entities, and **Flow preview** draws the notebook's Things. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Things, Tree, and Flat views in LoT Flow** — Switch views to drill into one level at a time, see the whole containment tree, or see everything flat. Panel cards expand into live previews, and the sidebar adds **Agents** and **Things** groups (collapsed at first). See [Things, Tree, and Flat views](/hub/lot-flow#things-tree-and-flat-views).
* **Agent configuration form** — **Configure** and **Add agent** open a form with **Configuration**, **Tools**, and **LoT** tabs. It rewrites only the clauses you change and keeps the rest as written. See [Configure an agent](/hub/ai-assistant#configure-an-agent).
* **Enable and disable** — Switch an action, connector, or agent off and on from its LoT Editor cell, connector card, or agent card. The HUB adds or removes `DISABLE true` and redeploys. The connector Monitor also has **Start** / **Stop**. Disabled cards are dimmed and marked **Disabled**. See [Disable an entity](/hub/lot-editor#disable-an-entity).

#### Certificates and security

* **Certificates tab** — A new System Config tab shows the server certificate and Root CA and replaces them without a restart. It also sets the trust store path and expiry alert, and uploads, searches, and revokes client certificates. Needs broker 2.22. See [Certificates](/hub/system/certificates).
* **Safer uploads** — The client drop zone accepts `.crt`, `.pem`, `.cer`, `.der`, `.p12`, and `.pfx`, and refuses keys and CSRs. Install a server key with **Replace** on the broker certificate.
* **Status bar indicator** — A certificate count with a red, yellow, or green dot. Hover for details, or click to open the tab filtered to certificates that need attention.

#### Account, fleet, and license

* **Sign in with Coreflux** — The login screen adds a **Coreflux Fleet** tab next to **This machine**. The desktop HUB signs in with no setup; a browser HUB needs `COREFLUX_OIDC_CLIENT_ID`, `HUB_PUBLIC_URL`, and `HUB_SESSION_SECRET`. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Fleet brokers** — Read-only rows for your organizations' brokers, with status, license, and **Cloud** / **Self-hosted** badges. **Connect** uses your account; portal actions open [portal.coreflux.org](https://portal.coreflux.org).
* **Cloud mode** — Set `HUB_CLOUD_MODE` on a shared regional HUB to accept only `mqtts://` brokers in `HUB_CLOUD_BASE_DOMAIN`. Leave it unset on desktop and self-hosted installs.
* **License tab** — Paste a `CFLX-…` code to activate, or drop a signed `.jws` file bound to the hardware fingerprint. Limits apply without a restart, and **Refresh** renews the lease. The tab doesn't start a trial.
* **Organization enrollment** — Paste an `et_…` token to enroll. The card shows **Enrolled**, **Not enrolled**, or **Enrollment pending** with the broker's reason. See [System Configuration — License](/hub/system/configuration#license).
* **MCP tab** — System Config → **MCP** turns on the broker's MCP listener, limits its tools, and creates or revokes tokens. See [System Configuration — MCP](/hub/system/configuration#mcp).

#### AI Assistant

* **Choose who answers** — Pick the HUB assistant, which calls the broker over MCP and asks before every write, or any `DEFINE AGENT` marked visible in the HUB. Installing on the broker creates a `TYPE LLM` connector and a `DEFINE AGENT`; legacy `TYPE AGENT` connectors are not listed or migrated. See [AI Assistant](/hub/ai-assistant).
* **Ollama works out of the box** — The assistant sizes Ollama's context per run (`HUB_OLLAMA_MIN_CTX` 16k to `HUB_OLLAMA_MAX_CTX` 32k), so the 4k default no longer truncates prompts. A silent model ends with a clear error after `HUB_AGENT_FIRST_OUTPUT_TIMEOUT_MS` or `HUB_AGENT_IDLE_TIMEOUT_MS` (120 s). See [Ollama requirements](/hub/ai-assistant#ollama-requirements).

#### Cluster Viewer (Beta)

* **See your cluster** — A read-only **Cluster** app shows members, the leader, data-plane links, LoT ownership, and partitions. It appears only while the host publishes cluster status. See [Cluster Viewer](/hub/cluster-viewer).
* **Clients tab** — Lists the MQTT clients on each node with user, address, traffic, last activity, queued messages, and session expiry. Filter, sort, and show the cluster's own connections on request. See [Cluster Viewer — Clients](/hub/cluster-viewer#details).

#### LoT Templates

* **Start from a template** — **Help → LoT Templates**, or **From a template…** in the LoT Editor, browses [templates.coreflux.org](https://templates.coreflux.org) and previews a template before installing it as a project. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Clone from git** — **＋ New → From git…** copies a public git repository into a new LoT Editor project. Cloning copies files only: it does not load or deploy the project. The HUB does not accept private credentials. The clone stops after 30 seconds, the whole repository becomes the project root, and a project download above 64 MB is refused. See [Clone from git](/hub/lot-editor#clone-from-git).

#### Connections

* **Generic MQTT brokers** — On a broker that isn't Coreflux, the dock keeps **Data Viewer** and **UNS Viewer** and hides Coreflux apps. Saved cards are tagged **MQTT** or **Coreflux**. See [When the broker is not Coreflux](/hub/connections#when-the-broker-is-not-coreflux).
* **Default connection** — In the web HUB, `HUB_DEFAULT_CONNECTION_HOST` and optional `HUB_DEFAULT_CONNECTION_*` variables pre-fill **New Connection**. Every browser receives the password, so use shared demo credentials only. See [Default connection (web / Docker)](/hub/connections#default-connection-web-docker).

#### Data Viewer and dashboards

* **Audio topics** — Raw PCM topics, such as an [Audio Input](/latest/lot-language/routes/media/audio-input) stream, show a live waveform you can play, clip, export to WAV, and scrub. See [Data Viewer](/hub/mqtt/data-viewer).
* **Busy buttons and markdown text** — A button with `SET AWAIT` stays busy, and each named component shows a pending indicator until its next message. The wait is 120 seconds unless `SET AWAIT_TIMEOUT` says otherwise, and then the panel shows a timeout note. `SET MARKDOWN true` on a text component renders sanitized markdown: no raw HTML, images, or unsafe links. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button).
* **Own window** — **Open in a new window** opens the Data Viewer on the current broker. See [Open the viewer in its own window](/hub/mqtt/data-viewer#open-the-viewer-in-its-own-window).
* **Panels grid** — A toggle in the Panels header switches to a grid of live dashboard thumbnails. The list stays the default. See [Managing Panels](/hub/dashboards/manager#managing-panels).

#### Desktop and settings

* **Desktop shell** — Click the logo to show the desktop. The account pill groups **Broker** administration, **Hub** (Themes and Hub Settings), and **Help**. See [Desktop shell](/hub/overview#desktop-shell).
* **Dock and status bar** — Right-click to set the dock position and auto-hide, and double-click a title bar to zoom. The same controls are in **Hub Settings → Desktop**. See [Dock and status bar](/hub/overview#dock-and-status-bar).
* **Hub Settings** — Memory limits, viewer refresh, and video wallpaper moved from System Config to **Hub Settings**. See [Hub Settings](/hub/overview#hub-settings).
* **Install and update** — Install the browser HUB as an app from `localhost` or HTTPS. The installed desktop app updates itself. See [Updating Your Coreflux](/latest/updating-coreflux#hub-desktop).
* **Walkthroughs** — Short tours on first launch and on each app's first open. Replay or reset them from **Help → Walkthroughs**. See [First-run walkthroughs](/hub/overview#first-run-walkthroughs).

#### Bug fixes

* **Maps show streets again** — Geolocation maps in the Data Viewer use keyless OpenStreetMap tiles, darkened in the dark theme, with the attribution **© OpenStreetMap contributors**. A build can set `VITE_CARTO_BASEMAPS_KEY` to use CARTO Dark Matter, or `VITE_MAP_TILE_URL` and `VITE_MAP_TILE_ATTRIBUTION` for another tile source. See [Tracking what matters](/hub/mqtt/data-viewer#tracking-what-matters).

**2.3**

August–September 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.3.4 - Login, Deploy, and Data Viewer fixes

#### Bug fixes

* **Non-admin users no longer get bounced back to the login screen** — Signing in as a user without full system access could loop back to login instead of opening the HUB in Limited Mode. The HUB now recognizes a denied `$SYS` subscription for what it is and opens Limited Mode as designed.
* **Deploy project shows accurate status** — Deploying a project via [Connections Manager](/hub/connections) no longer surfaces the broker's success response as a false warning, and the project header no longer gets stuck on **Updating** after the deploy completes.
* **LoT Editor keeps dropped files on the project** — Images and other files dropped into a project (from the Finder, Explorer, or a mixed-OS drag) now stay attached instead of being lost.
* **Data Viewer confirms whether a publish actually landed** — Sending a message no longer shows **Published** when the broker silently rejected it for lacking a publish ACL; Data Viewer now waits for the topic echo before confirming.

### 2.3.0 - LoT Editor, Connections Manager, LoT Flow wiring

#### LoT Editor

* **Visual Studio Code-style editor** — An intuitive notebookeditor with a familiar interface inside the HUB.
* **Unified Projects view** — One Projects list covering every project stored on the broker and every draft held in the HUB. The live project is marked, local-only drafts stay distinct, and each row carries its own sync state: clean, unsaved edits, changed on the broker, or diverged.
* **Push only what changed** — Push stores the working copy and deploys just the drift, instead of redeploying a whole project.
* **Broker Runtime inspector** — A table of what is actually running on the broker, with read-only source for each entity, and a jump from any running entity to the notebook that declares it.
* **Documents alongside notebooks** — Open and store Markdown, text, PDF, and images in a project, import files from disk, and reference them in LoT notebook cells.
* **Copy entities between notebooks** — Copy or drag a declared or deployed entity into another notebook.
* **Version history** Git based version control for project files.
* **Activate and Deactivate projects** from the project tree.

#### Connections Manager

* **More than one broker** — The HUB keeps a named list of broker connections with favorites, replacing the single remembered URL. Each is shown as a card on the login screen.
* **Change Broker** — Switch the whole HUB to another saved connection from the account menu, without logging out and reconfiguring.
* **Per-connection TLS** — Store a CA certificate and a client certificate against an individual connection.
* **Credentials kept off the connection record** — Passwords and client keys live in a separate store; the desktop app encrypts it using the operating system's secure storage, and the browser app never writes them to disk.
* **Live reachability on the login list** — Saved connections are probed so you can see which brokers answer before you pick one.

#### LoT Flow

* **Cleaner connections between nodes** — `KEEP`-topic edges and "matches" edges no longer clutter the canvas, and `MODEL` nodes are drawn as terminals, so the remaining edges show real data flow.
* **Topics grouped by role** — Command and telemetry topics are grouped by the role they play, with disambiguated group labels, prefix hubs backed by a topic-set panel, and wildcard subscriptions expanded to the topics they match.
* **Topic pulse toggle** — Turn live topic activity animation on or off.
* **Export the canvas as an image** — Download the current flow as a PNG.

**2.2**

July 2026

### 2.2.0 - UNS viewer & LoT Flow

* **LoT Flow** — A new interactive view of your LoT data flows, showing entity, topic, and Python nodes alongside live topic values, action traces, and route status.
* **UNS viewer** — Browse your Unified Namespace as a tree, with search, live payload previews, and a graph layout.
* **Data Viewer overhaul** — A refreshed explorer with a detailed topic view, timeline, faster topic indexing, and better subscription management.
* **In-app release notes** — A "What's New" dialog in the HUB so you can see what's changed without leaving the app.
* **Refreshed HUB styling** — Updated visual design and dock layout.
* **AI chat improvements** — A setup wizard, an artifact panel, and a generally expanded chat experience.
* **Expanded dashboard panels** — More display components, gauge options, and model-binding support for building richer dashboards.
* **Bug fixes** — Fixed the LoT compiler and dashboard rendering for `ON KEY PRESS`, `ON THRESHOLD BREACH`, conditional handlers, `WITH THEME`, numeric decimals and suffixes, threshold zones on gauges/charts, and callable actions. Fixed `INVOKE ACTION`, `BIND TO MODEL`, the accordion "Add Section," and tab titles in dashboards. Fixed real-time charts to show both traces with a legend and to correctly distinguish bar vs. line modes. Fixed select/dropdown interactions, topic-to-widget data binding (previously showing a single point instead of the full array), slider and toggle controls publishing incorrect values, icon visibility, multi-panel layouts, and events not being recognized on mount. Fixed the AI agent to properly detect uninstalled routes, and corrected its confirmation prompts. General mobile layout improvements.

**2.0**

April 2026

### 2.0.0 - UI/UX overhaul, standalone installer, AI Agent

![Coreflux HUB Data Viewer showing MQTT topic tree with live data values and real-time charts](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/hub-data-viewer.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=634b8986391a76e82ef3f03574338cb6)

Coreflux HUB Data Viewer with live MQTT topic data and charts

* **UI/UX improvements**
* **Standalone installer** — Windows and Linux
* **AI Agent**
  * **Insights mode** — Ask questions about running data, using project information as context
  * **Agent mode** — Build LoT, routes, and dashboards with an AI copilot

**VS Code Extension**

**1.0**

August–October 2026

These notes are VS Code extension **1.0**. Features that use the broker's new commands need broker **2.22**.

### 1.0.0 - Things, Agents, Validate, MCP, and licensing

This release lets you write Things and Agents in notebooks, check your LoT on the broker before deploying, connect your AI tools to the broker's MCP server, and manage licensing, all from VS Code.

#### Highlights

* **Write Things and Agents where you already write LoT** — Check them against the broker and deploy them from the notebook, the same way as any other cell. See [THING cells](/lot-notebooks/usage#thing-cells).
* **Check before you deploy** — Validate a cell or the whole notebook on the broker. Problems show on the cell, and nothing is deployed until you run it. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Switch a cell off without deleting it** — Disable an action, connector, or agent from the cell status bar, and turn it back on when you want it running. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **Connect your AI tools in one step** — The MCP Server tab writes the broker endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Teach your coding agent LoT** — Install the Coreflux skills so the agent writes valid LoT and works with the broker. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **License and enroll from VS Code** — Activate with a code, install a signed license, or enroll the broker, from the License tab. See [License tab](/lot-notebooks/usage#license-tab).

#### LoT cells

* **Things** — A run sends the cell's `DEFINE THING` blocks and their workspace templates as one `-addThing`, after a `--dryRun` whose problems show on the cell. **Remove Thing from Broker** sends `-removeThing`, and a quick fix updates older THING syntax (`TEMPLATE`, and `{p}` to `{{p}}`). See [THING cells](/lot-notebooks/usage#thing-cells).
* **Agents** — `DEFINE AGENT` cells are checked like the broker checks them and deploy with `-addAgent`. Broker agents appear in the Coreflux Explorer and the Entities panel. See [Agent cells](/lot-notebooks/usage#agent-cells).
* **Validate** — Check a cell or the whole notebook on the broker without deploying it. Results appear under the cell and in Problems. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Enabled / Disabled toggle** — Switch `DISABLE true` on and off for action, connector, and agent cells from the cell status bar, and the change uploads. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **`DEFINE CONNECTOR`** — Recognized in checks, completions, and hovers, with `DEFINE ROUTE` as its alias. Connector cells upload from the cell, and Deploy Project includes them.
* **`RETURN AS` under `CALL`** — A `RETURN AS` line under a `CALL` no longer reports an indentation error.
* **Panels and themes** — `DEFINE PANEL` and `DEFINE VISU` cells, and a Thing's `WITH PANEL` body, are checked with the broker's panel parser. Highlighting, hover, completions, and a `DEFINE PANEL` snippet are included. Running the cell sends `-addVisu`; removing it sends `-removeVisu`. `DEFINE THEME` and `THEME_VARIANT` are recognized. The cell status bar offers **Open in Coreflux HUB** to view the rendered panel, and a successful upload suggests opening Dashboards there. See [Panel cells](/lot-notebooks/usage#panel-cells).
* **Agent and Thing checks match the broker** — Valid agent, thing, rule, connector, and model syntax is no longer flagged, including connector keys such as `SUBJECT` and mixed-case names. See [Agent cells](/lot-notebooks/usage#agent-cells).

#### Broker management

* **License tab** — Activate with a `CFLX-…` code, install signed license text, enroll with an `et_…` token, and refresh the lease. The Instance Key field is gone. See [License tab](/lot-notebooks/usage#license-tab).
* **MCP Server tab** — Turn on the broker's MCP server, pick its tools, and manage tokens. **Install MCP server** writes the endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop, and keeps workspace config files out of Git. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Install Agent Skills** — **Install Agent Skills...** lets you pick which of the 11 bundled skills to install and where (the `.agents`, `.claude`, `.cursor`, or `.github` skills folder, in the workspace or your home folder). Skills come from the public [coreflux-skills](/ai/agent-skills) repository (broker 2.22 or later), and older copies from previous versions are offered for removal. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **Remove All Things / Templates** — Two new commands clear every Thing or every template from the broker.
* **Variables** — "Environment Vars" is now "Variables" everywhere, including **Secrets & Variables**.

#### Data Viewer and workspace

* **Bounded history** — Each topic keeps its last 100 messages by default (`coreflux.dataViewer.historyBufferPerTopic`, 50 to 2000), set from the timeline gear. The timeline draws again, and pausing or scrubbing stays steady while messages arrive. See [Adjust how you see the data](/lot-notebooks/debug#adjust-how-you-see-the-data).
* **Apps in the editor area** — Data Viewer, Logs Viewer, and Secrets & Variables open as tabs next to your notebooks.
* **Connection Manager** — Save several broker connections and switch between them.
* **Entities table** — See the LoT entities running on the broker in their own table.
* **LoT projects** — Create, edit, and deploy LoT projects.

**beta**

April 2026

![Screen recording of creating and deploying LoT in the Coreflux VS Code extension](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-and-deploy-lot.gif?s=5cd139e03cbf0b5109848b498d7c65eb)

Create and deploy LoT from the Coreflux VS Code extension

* **Improved VS Code extension (beta)**
  * License usage
  * Live MQTT data (topic tree)
  * **Data Viewer** — View and replay historical and live data for MQTT topics, with viewers for raw, JSON, PDF, GeoJSON (map), audio, and more
  * **Execution trace** — View and replay historical and live data from LoT execution, including success and error states, published topics, and internal variables
  * Manage secrets and environment variables


# Release Notes
Source: https://docs.coreflux.org/product-updates/release-notes

New features, improvements, and fixes in each release of the Coreflux MQTT broker and HUB.

Product

**MQTT Broker**

**2.22**

August–October 2026

> [!WARNING]
>
> **Breaking Changes** in this release (2.15–2.22):
>
> **`TYPE MCP_SERVER` is gone** — The MCP server is now broker configuration, not a LoT connector, and a project that still defines `TYPE MCP_SERVER` fails to load. Enable `Mcp.Enabled` (or `COREFLUX_MCP_ENABLED=1`), mint a token with `-createMcpToken`, and point the client at Streamable HTTP `/mcp`. Legacy SSE URLs stop working. The MCP client connector (`TYPE MCP` / `CALL MCP`) is unchanged. **Action:** remove old `TYPE MCP_SERVER` definitions and follow [MCP Server](/latest/mqtt-broker/mcp-server).
>
> **`TYPE AGENT` connectors are removed** — `-addConnector` refuses them and stored ones are skipped at load, with their topics. Rewrite each as a `TYPE LLM` connector plus `DEFINE AGENT … USES LLM CONNECTOR`; nothing is granted until `ADD TOOL`, and writes need `WITH LEVEL "write"`. There is no automatic migration. **Action:** rewrite agents before you upgrade. See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).
>
> **No built-in trial** — A broker with no license runs as **Community**. Get a 30-day Growth-type license at [portal.coreflux.org](https://portal.coreflux.org), where you also manage your fleet.

### 2.22.0 - Things, Agents, licensing, and a built-in MCP server

This release lets you model devices once and reuse them (Things), build AI agents that only do what you allow, and connect tools like Cursor or Claude Desktop straight to the broker. It also adds signed licensing with fleet enrollment, certificate management, and clustering that runs your LoT on every node.

#### Highlights

* **Model a device once, then reuse it (Things, preview)** — Describe a pump, a line, or a sensor type once. Each copy gets its own topics, and you add as many as you need without copying LoT. See [Things](/latest/lot-language/things/overview).
* **Let AI act only where you allow it (Agents, preview)** — An agent starts with no tools. You grant each read or write, and a question-only mode never changes the broker. See [Agents](/latest/lot-language/agents/overview).
* **Work on the broker from Cursor or Claude** — A built-in MCP server lets those tools run broker commands, with tokens you create and revoke. See [MCP Server](/latest/mqtt-broker/mcp-server).
* **Keep every cluster node on the same LoT** (**Beta**) — Deploy to any node and the whole cluster runs it. A device connector can stay on the node that can reach the equipment. See [LoT in a cluster](/latest/mqtt-broker/clustering#lot-in-a-cluster).
* **License a broker and add it to your fleet** — An unlicensed broker runs as Community. Activate online, use a signed file where there is no internet, and enroll the broker in your organization. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).
* **Replace certificates without a restart** — Update the certificate the broker presents, choose which clients to trust, and see which certificates are about to expire. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Sign in with your identity provider** — Clients can use an OIDC access token as the MQTT password. Local passwords still work. See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Pause logic without deleting it** — Turn an action, connector, or agent off, keep the definition, and turn it back on when you are ready. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **See when a device is actually down** — Industrial connectors show Reconnecting when a PLC stops answering, and the last good tag values stay in place through a short disconnect. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **Bring in audio, gRPC, and hundreds of APIs** — Capture microphone audio onto MQTT, call gRPC services, and start from 220+ REST API app templates (technical preview). See [REST API Apps](/latest/lot-language/routes/rest-api-apps/index).

#### Things and Agents (preview)

* **Define a device once** — A Thing is a typed device with `{{placeholder}}` topics. Add instances with `-addThing` (use `--dryRun` to validate first), and manage them with `-removeThing` and `-listThings`, or the MCP tools `add_thing`, `list_things`, and `remove_thing`. Each Thing publishes its source, tree, and health under `$SYS/Coreflux/Things/<name>`. See [Things commands](/latest/mqtt-broker/commands#things).
* **Agents with limited access** — An agent uses a `TYPE LLM` connector for its provider, model, key, and price, and starts with no tools. It gets only what `ADD TOOL` grants. Agents can ask each other for help with `WITH AGENTS`, and actions call them with `CALL AGENT`. Each agent publishes its card and status under `$SYS/Coreflux/Agents/<name>/`.
* **Read-only questions** — Ask an agent with `"mode": "insight"` and it only reads, including any agents it delegates to. `TYPE LLM` also accepts `REASONING_EFFORT` (`none` to `extra_high`).

#### New connectors

* **Audio Input** — Capture a microphone, test tone, silence, or a file as 16-bit PCM audio on MQTT (`TYPE AUDIO_INPUT`). See [Audio Input](/latest/lot-language/routes/media/audio-input).
* **gRPC** — Call gRPC services from MQTT with `TYPE GRPC`, including streaming. See [gRPC Connector](/latest/lot-language/routes/streaming/grpc).
* **REST API apps** — 220+ ready-made `TYPE REST_API` templates for cloud, ERP, MES, messaging, and IIoT services, in technical preview. See [REST API Apps](/latest/lot-language/routes/rest-api-apps).

#### MQTT and LoT

* **Connectors naming** — `DEFINE CONNECTOR` and the `-addConnector`, `-removeConnector`, `-listConnectors`, `-removeAllConnectors`, and `-checkConnectorConnection` commands are the new names. `DEFINE ROUTE` and the `-…Route…` commands keep working as aliases.
* **Turn things off without deleting them** — Put `DISABLE true` under `DEFINE` on an action, connector, or agent to keep it stored but not running. Switch it back on with `-disableAction`, `-disableConnector`, `-disableAgent` and the matching `-enable…` commands, or with MCP tools. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **Publish with retain and QoS** — `PUBLISH TOPIC` accepts `RETAIN` and `QOS0` / `QOS1` / `QOS2` (default QoS 0). `KEEP TOPIC` still only stores a value for `GET TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#publish-topic).
* **Shared subscriptions** — Turn on `SharedSubscriptions` and `$share/{group}/{filter}` delivers each message to one member of the group. Off by default. See [Shared subscriptions](/latest/mqtt-broker/protocol#shared-subscriptions).
* **Predictable topic triggers** — `ON TOPIC` actions, models, and connector events run on the exact message that fired them, in publish order per topic. Different topics still run in parallel. See [Action Triggers](/latest/lot-language/actions/events).
* **Every publish in an action is sent** — Each `PUBLISH TOPIC` or `KEEP TOPIC` in one run is delivered, in the order written, with that line's own retain, QoS, and keep settings. A later `GET TOPIC` in the same run reads the value just written. In a cluster, only the last `KEEP` of each topic is replicated. See [PUBLISH TOPIC](/latest/lot-language/actions/operations#publish-topic).
* **Panel wait and markdown** — A button accepts `SET AWAIT "Id, Id"` and `SET AWAIT_TIMEOUT` (seconds, default 120). A text component accepts `SET MARKDOWN true`. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button) and [Markdown text](/latest/lot-language/panels/defining-panels#markdown-text).

#### Licensing and enrollment

* **Plans** — Community, Growth, and Enterprise, with limits on artifacts and connectors. Status is on retained `$SYS/Coreflux/License` and, on the ops port, `GET /license` (port `9100`, keep it private).
* **Three ways to license** — Activate online with `COREFLUX_ACTIVATION_CODE` or `-activateLicense CFLX-…` (limits apply without a restart, the lease refreshes daily, `-refreshLicense` forces it). Or install a signed license file (`config/license.jws`, `COREFLUX_LICENSE_FILE`, `COREFLUX_LICENSE_TOKEN`, or `-loadLicense`), which the broker verifies locally with no network. For air-gapped hosts, send the `--show-fingerprint` value to Coreflux and install the hardware-bound license you get back.
* **Enroll in your organization** — `-enroll et_…` (or `--enroll`, or `config/enrollment-token`) binds the broker to your Coreflux organization, separately from its plan. An activation code enrolls it too. A broker waiting for enrollment still starts: local users work, and logins that need the organization are refused until it succeeds. `$SYS/Coreflux/License` explains why it is pending. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

#### MCP server

* **Connect AI tools to the broker** — Cursor, Claude Desktop, and other MCP clients connect to the broker's built-in server, configured in the `Mcp` block (port `6278`, bound to `127.0.0.1`, path `/mcp`). Manage tokens with `-createMcpToken`, `-listMcpTokens`, and `-revokeMcpToken`, or from the HUB **MCP** tab. In Docker or Kubernetes, bind to `0.0.0.0`, publish `6278`, and route `/mcp` behind TLS. See [MCP Server](/latest/mqtt-broker/mcp-server#docker-and-kubernetes).
* **Install agent skills** — The public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository is generated from the broker, and the broker exposes the same pack as the `coreflux://skills` MCP resource. Coding agents that install it write LoT the broker accepts. They need broker 2.22 or later. See [Agent skills](/ai/agent-skills).

#### Security

* **Sign in with OIDC** — With `Oidc.Enabled`, a client sends an OIDC access token as its MQTT password. The broker validates it, checks the organization, and authorizes by the token's groups. Local passwords still work. A client is disconnected when its token expires (30-second grace). See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Manage certificates from a command** — `-brokerCertificates` (admin only) shows and replaces the server certificate and Root CA, and manages the mTLS trust store: list, import, export, revoke, settings. A new server certificate applies without a restart and keeps a `.bak-` copy. Revocation is immediate and every change is audit-logged. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Know when certificates expire** — Retained `$SYS/Coreflux/Certificates/Summary` counts valid, expiring, expired, and unreadable certificates. `CertificateExpiryThresholdDays` (default 30) sets the warning window. See [`$SYS/Coreflux/Certificates/Summary`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary).
* **Easier trust store** — `ClientCertificateSourcePath` loads `.pem`, `.crt`, `.cer`, `.der`, and unprotected `.p12`/`.pfx` files, skips anything in `revoked/`, and refuses keys and CSRs (install a server key with `replaceServer`). `$SYS/Coreflux/Config` shows `ServerCertificatePassword` as `********`.

#### Clustering and operations

* **LoT works across a cluster** (**Beta**) — Definitions replicate through the leader, so you can send LoT to any node and every node runs the same version. Each message runs LoT once, on the node it entered. Timers, `ON START`, and device connectors run on one owner and move to another node within about 10 seconds if it fails. Pin a device connector to a node with `CLUSTER_NODE` in `ROUTE_CONFIG`. **Action:** upgrade every node before you change LoT, and create users on every node.
* **Faster Kubernetes scaling** (**Beta**) — A pod that the headless Service no longer lists leaves the cluster about 2 minutes after its cluster port stops answering (`MemberAbsentFromDiscoverySeconds`, 120 seconds by default; it used to wait 5 minutes). New pods are found within seconds. See [How a cluster works](/latest/mqtt-broker/clustering#one-leader-automatic-membership).
* **More metrics** — New `/metrics` series for delivered messages, CPU, auth failures, ACL denials, rate limits, connector drops, and errors. See [Metrics](/latest/mqtt-broker/operational-endpoints#metrics).
* **Fleet health reporting** — An enrolled broker reports CPU, memory, clients, traffic, refusals, drops, and scrubbed error signatures to the Coreflux Portal. It never sends topics, payloads, hostnames, or IPs. Turn it off in the portal, or with `COREFLUX_FLEET_METRICS=off` or `DO_NOT_TRACK=1`. See [Fleet performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics).

#### Bug fixes

**Industrial connectors**

* **Connection status tells the truth** — Modbus, S7, OPC UA, EtherNet/IP, ADS, Allen-Bradley, FINS, and BACnet no longer wipe retained tag values on a disconnect or failed read, and a restarted connector polls again. A connector no longer shows Connected while its device is unreachable: after 3 failed read cycles it reports Reconnecting and rebuilds the connection. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **No more hangs on silent devices** — A PLC that accepts a connection but never answers no longer freezes S7 (`READ_TIMEOUT` now limits the connect) or EtherNet/IP (`READ_WRITE_TIMEOUT` now bounds every exchange). **Action:** raise `READ_WRITE_TIMEOUT` for slow EtherNet/IP devices.
* **Modbus TCP** — Each connection runs one request at a time, so tags no longer go BAD with "Response was not of expected transaction ID". See [Modbus TCP Client](/latest/lot-language/routes/industrial/modbus-tcp-client#one-request-at-a-time).
* **FINS** — A slow reply no longer shifts later reads onto the previous command's value, and a lost PLC goes to Reconnecting after 2 unanswered commands. Replies must now match the request and come from the addressed node. **Action:** gateways that swap client and server nodes now time out; check `LOCAL_NODE` / `REMOTE_NODE`. See [FINS](/latest/lot-language/routes/industrial/fins).
* **Allen-Bradley** — A slow but healthy PLC no longer reconnects every cycle, and a timed-out write publishes `"outcome": "unknown"`. See [Write results](/latest/lot-language/routes/industrial/overview#write-results).
* **ADS** — `TIMEOUT` now applies to every request (it was ignored and fixed at 5 s), and an unreachable PLC makes the connector reconnect. See [ADS](/latest/lot-language/routes/industrial/ads).
* **OPC UA** — A read or write that races a reconnect marks the tags BAD and backs off instead of counting as success, and sessions no longer leak.
* **BACnet** — Integer writes of any size send the right value (out-of-range 64-bit values fail instead of being cut off), and reads queued on a dropped connection no longer break the new one.
* **Tag values** — Negative `OFFSET`, `MIN_VALUE`, and `MAX_VALUE` now parse. See [Common TAG parameters](/latest/lot-language/routes/industrial/overview#common-tag-parameters).

**Other connectors**

* **Kafka** — A `"in"` event commits its offset only after the message is published, so a crash no longer drops records. `WITH EVERY` on a Kafka event is now rejected when you add the connector. **Action:** publish on a schedule with `ON EVERY` in a LoT action. See [Kafka Connector](/latest/lot-language/routes/streaming/kafka).
* **Kafka and gRPC start** — A connector that fails to start is retried in the background (2 to 60 seconds) until it starts or you remove it.
* **Ollama** — A `TYPE LLM` connector with `PROVIDER ollama` takes `CONTEXT_WINDOW` (a fixed `num_ctx`, sized per call and capped at the model's maximum), `MAX_CONTEXT_WINDOW` (default 32768, minimum 16384), `FIRST_OUTPUT_TIMEOUT` (default 120 s), and `IDLE_TIMEOUT` (default 60 s). Agent tasks fail with a clear error (`llm_timeout`, `llm_unreachable`, `model_not_found`, `context_overflow`) instead of hanging. See [Ollama context and timeouts](/latest/lot-language/routes/ai-routes#ollama-context-and-timeouts).
* **Email and CrateDB** — Email `ADD EVENT` blocks now send and publish their status. CrateDB `ADD EVENT` blocks run, `STORE IN` writes rows, and the connector reconnects after a CrateDB restart.
* **REST API** — A reply published right away on `REPLY_TOPIC` reaches the HTTP client instead of a 504, and concurrent requests no longer cancel each other. A value in `ENDPOINT` can no longer send the request and its credentials to another host; the broker refuses it and publishes `RequestRejected`. See [Placeholder Support](/latest/lot-language/routes/rest-api-routes#placeholder-support).
* **MQTT bridge** — A bridge without `CLIENT_ID` forwards inbound messages and no longer clashes with other bridges, and a removed bridge stops forwarding at once.
* **Sparkplug B** — The Primary Host tracks `seq` per edge node and no longer floods Rebirth requests, and DATA metrics without a datatype decode using the birth certificate.
* **`TRIGGER` on LLM, AGENT, and MCP** — MCP calls the named tool, and LLM and AGENT results go to the mapping's `DESTINATION_TOPIC` or the default response topic instead of being discarded.

**LoT and MQTT**

* **`GET MODEL`** — `SET … WITH GET MODEL` no longer fails on the action's first run, `PUBLISH TOPIC … WITH GET MODEL` parses, and `WHERE` conditions joined with `AND` accept any mix of text and numbers. See [GET MODEL](/latest/lot-language/actions/operations#get-model).
* **`STORE IN … WHEN`** — Conditional model storage works instead of failing on first evaluation, and an unknown field is rejected at deploy. See [Store data with models](/latest/lot-language/routes/data-storage/overview#step-2-store-data).
* **`MATCHES REGEX`** — Patterns with `\d`, `\w`, `\s`, or `\.` work as written. See [MATCHES REGEX](/latest/lot-language/rules/syntax#matches-regex).
* **`TRIGGER` statements** — The line after a `TRIGGER` is no longer dropped. Examples now use `TRIGGER "<connector>" TO <data> FOR "<event>"`; code copied from the old order (`WITH "<event>" FOR <data>`) still deploys but swaps the data and the event. See [TRIGGER Statement](/latest/lot-language/actions/operations#trigger-statement).
* **MQTT 5 denials** — A denied publish now gets `0x87 Not authorized` and a rate-limited one `0x97 Quota exceeded`, instead of Success. See [What a denied client sees](/latest/lot-language/rules/rbac#what-a-denied-client-sees).
* **Callable actions from panels** — Object, array, and `null` arguments no longer cause a compile error; objects and arrays arrive as JSON text.
* **Protobuf `float` and nested `GET PROTO`** — `ADD FLOAT` (alias `ADD SINGLE`) decodes proto `float`, and dotted `GET PROTO` paths read nested messages. A field with the wrong type is skipped instead of stopping the whole message. See [Protobuf Models](/latest/lot-language/models/protobuf).

**Panels, projects, and platform**

* **Panels** — Boolean CSS bindings (`BIND CSS … AS BOOLEAN`) convert correctly in the HUB. SVG markup from `SET INLINE` and `data:` sources is rebuilt from an allow-list so scripts, event handlers, and external links can't run in viewers' browsers; what was removed is listed as a deploy warning.
* **Projects** — A live project's history records only the edited cell, not the whole notebook. After a restart, the broker also loads connectors added outside the project and the connectors of Things, and publishes Thing status from boot. See [LoT THING](/latest/lot-language/things/overview).
* **Metrics** — Published-message and byte counters no longer reset at UTC midnight, so `rate()` works across it. `coreflux_messages_published_total` now counts client publishes; deliveries moved to `coreflux_messages_delivered_total`.
* **Linux packages** — APT and DNF units run the broker as the user `coreflux` with `CAP_NET_BIND_SERVICE`, so they can bind ports below 1024. See [Ports below 1024](/latest/mqtt-broker/startup-options#ports-below-1024).

**Configuration**

* **Partial config is merged** — A partial JSON object published to `$SYS/Coreflux/Config/New` is merged into the live configuration. Fields you omit, including bind addresses, stay as they are. See [Applying Configuration](/latest/mqtt-broker/configuration#via-mqtt-topic).

**2.14**

August 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.14.3 - Default rules and Visu panel publishing

#### Bug fixes

* **Default rules load with an active project; Visu panels can be published** — When a project is already active at startup or after `-loadProject`, the broker's seeded permission rules now apply correctly so internal clients retain `$SYS` access and panels publish to `$Visu/...` topics again after project activation.

### 2.14.2 - Sparkplug B connector, MQTT & LoT performance improvements

Sparkplug B Support, MQTT client lifecycle action triggers, better OT master/client visibility in broker logs, a banded Rules precedence model, project lifecycle improvements, and faster publish, LoT, and connector dispatch.

#### Improvements

* **Rules priorities are now banded** — The rule priority number line is split into bands: `0`–`99` is reserved for the broker's immutable system rules, `100`–`999 999` is your band, and the permissive catch-alls `AllowPublishTopic` / `AllowSubscribeTopic` now sit at `1 000 000`. Only the strongest matching band decides an operation, where a DENY beats an ALLOW (deny-wins) and nothing matching means denied (default-deny). Moving the catch-alls to the weakest band **fixes a topic-visibility bypass**: they previously shipped tied with everything else, so a specific access rule could not reliably override the allow-all fallback — which left Visu panel view topics effectively public. `-addRule` now rejects priorities outside `100`–`1 000 000`. **Action:** custom rules written in the old `1`–`99` range are clamped to `100` on load and logged individually. Clamping keeps them in force, but several rules can land on `100` together, where ties resolve deny-wins — re-space them across the user band, putting the more specific rule at the lower number. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac#rule-precedence).
* **`AllowConnect` seed and `FOR Connect` rules** — Fresh brokers now ship a third permissive catch-all, `AllowConnect`, at priority `1 000 000` (the same weakest band as `AllowPublishTopic` / `AllowSubscribeTopic`). Write `FOR Connect` rules in the user band to decide who may connect after authentication; they outrank the seed. Brokers with no Connect rule at all still leave CONNECT ungated. `-restoreRules` puts all three seeds back to their shipped ALLOW definitions. See [RBAC](/latest/lot-language/rules/rbac#connection-admission) and [`-restoreRules`](/latest/mqtt-broker/commands#restoring-seeded-rules).
* **Project manifests, entity ownership, and ad-hoc entities** — Each stored project publishes a retained content manifest on `$SYS/Coreflux/Projects/{name}/manifest` (SHA-256 of exact file bytes, plus entities declared in `.lotnb` cells). `-projectManifest` returns the same JSON on demand. Running entities are attributed on `$SYS/Coreflux/Entities/ownership` and in the `-listEntities` / `-loadProject` `origin` field. **Loading or unloading a project no longer deletes ad-hoc entities** added with `-addAction` and similar commands while no project was active. **Action:** if you relied on Activate to wipe the whole runtime, remove those entities explicitly before loading a project. See [Project Commands](/latest/mqtt-broker/commands#project-commands) and [Project Topics](/latest/mqtt-broker/sys-topics#project-topics).
* **Loaded projects stay active after a restart** — After `-loadProject` (or `--project`), the last loaded project is remembered and re-activated on the next start unless you pass `--project`. `-unloadProject` returns to standalone mode on the next restart. See [Startup Options](/latest/mqtt-broker/startup-options#loading-a-project-at-startup).
* **`ON START` runs on deploy; action publishes are no longer blocked by user ACL** — Deploying an `ON START` action on a live broker executes the body immediately (cold start still runs once after the MQTT broker is ready). Action `PUBLISH` / `KEEP` still put messages on MQTT for any subscriber; they are no longer denied by user publish rules, so bootstrap topics from actions are not silently dropped. Clients still need subscribe permission to receive those messages. See [Initialization Triggers](/latest/lot-language/actions/events#initialization-triggers).
* **OT string sizing — `LENGTH` is the preferred keyword** — Across OT connectors that support configurable string sizing, `WITH LENGTH` is now the documented primary keyword; `STRING_SIZE` remains accepted as a parser alias. See the shared [String sizing by Connector](/latest/lot-language/routes/industrial/overview#string-sizing-by-connector) reference on the industrial connectors overview.
* **Modbus Server STRING defaults and cap** — Unsized `STRING` tags no longer reserve a single register (which silently truncated barcodes and caused Illegal Data Address on FC16 writes). The server now defaults to **40 bytes (20 registers)** and warns when size is omitted. Connector validation rejects `LENGTH` values above **246 bytes (123 registers)**, the FC16 write cap. See the [Modbus TCP Server Connector guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **Modbus Server and OPC UA Server activity logging** — Modbus Server connectors log accepted and rejected master writes (plus rejected reads), with bank-aware function-code labels and `LENGTH` guidance when an undeclared holding-register range is the cause; connection open/close counts are logged from the existing watchdog (**the master's source IP is not available**). OPC UA Server connectors log client session create/close events and accepted external writes on tags and STRUCT fields.
* **MQTT client lifecycle action triggers** — New `ON CONNECT DO`, `ON DISCONNECT DO`, and `ON SUBSCRIBE ["pattern"] DO` triggers run LoT automation when clients connect, disconnect, or subscribe. Action bodies expose session context via `CLIENTID`, `USER`, `ENDPOINT`, `CLEANSESSION`, `DISCONNECTREASON`, `SUBSCRIBETOPIC`, and `SUBSCRIBEQOS`. The broker only evaluates lifecycle hooks when at least one action defines them. See [Action Triggers](/latest/lot-language/actions/events#client-lifecycle-triggers).
* **Improved command response handling** — Broker command responses are now consistently structured as JSON. Each command may include a `requestId` field, allowing you to easily correlate requests and responses.
* **Sparkplug B connectors (beta)** — Decode Sparkplug B protobuf into readable JSON, publish Coreflux topics as an edge node, or run Coreflux as the Primary Host Application with namespace state, commands, and automatic rebirth requests. See the [Sparkplug B Connector](/latest/lot-language/routes/system/sparkplug-b) and [Sparkplug Host Connector](/latest/lot-language/routes/system/sparkplug-host) guides.

#### Performance

* **MQTT between clients** — More messages complete per second, the slowest publishes finish sooner (about 10% lower p99 latency). Messages that update connector topics stay in the order they arrived.
* **LoT rules and actions** — Permission checks, topic triggers, timers, and dashboard invokes no longer slow down as more distinct topics exist on the broker. LoT-heavy traffic that was about **10× slower at 30,000 topics** — and about **70× slower at 100,000** — now stays as fast as it was on a nearly empty broker. `USER HAS` and `USER IN GROUP` checks stay fast as the user list grows.
* **Connector mappings** — Adding mappings no longer makes every publish more expensive, including on topics that no mapping uses. Exact-topic mappings (the common case) keep up with tens of thousands of messages per second at **sub-millisecond** latency with **no loss** — the same flood previously took around **25 seconds** and dropped some messages. Wildcard mappings (`+` / `#`) now deliver fully as well. When a connector cannot keep up, memory stays bounded: the broker waits, then drops the **newest** arriving message rather than older ones already in flight. Set `ADD ROUTE_CONFIG` on a connector (`OVERLOAD_POLICY`, `OVERLOAD_TIMEOUT`, `OVERLOAD_CAPACITY`) when that connector needs a different wait-or-drop contract. See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward).

#### Bug fixes

* **Rules with `IF` and no `ELSE` now compile** — `IF USER IS "dashboard" THEN DENY` (no `ELSE`) previously failed compilation on first evaluation and was treated as a deny for every matching publish or subscribe. The missing branch is now the opposite of the `THEN` decision. See [Rules Syntax](/latest/lot-language/rules/syntax#combining-conditions).
* **Python scripts no longer lose their code on restart** — Scripts that contained blank lines were truncated down to the `# Script Name:` header after a reboot, so `CALL PYTHON` failed even though the script still appeared in listings. Complete scripts now persist across restarts. See [Python Integration](/latest/lot-language/actions/python-integration#writing-python-scripts).
* **Built-in rules survive project add/load/unload** — Adding or switching a project no longer wipes the broker's default permission rules, so internal clients keep `$SYS` access. See [RBAC](/latest/lot-language/rules/rbac#seed-catch-alls).

**2.2**

July 2026

### 2.2.0 - Kafka, OPC UA Server & Modbus Server routes

* **Kafka route** — Connect Coreflux directly to Kafka as a producer or consumer, with support for security protocols and configurable batching and compression. See the [Kafka Route guide](/latest/lot-language/routes/streaming/kafka).
* **OPC UA Server route** — Expose Coreflux data to OPC UA clients with a secure-by-default setup, including support for array and struct nodes. See the [OPC UA Server Route guide](/latest/lot-language/routes/industrial/opcua-server).
* **Modbus Server route** — Serve Modbus data over TCP, with experimental support for Serial (RTU) connections. See the [Modbus TCP Server Route guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **OT route persistence** — Server routes (OPC UA Server, Modbus Server) persist their state and recover automatically after a restart, so data isn't lost on reconnect. See [OPC UA Server persistence](/latest/lot-language/routes/industrial/opcua-server#data-persistence--recovery) and [Modbus Server persistence](/latest/lot-language/routes/industrial/modbus-tcp-server#data-persistence--recovery).
* **OPC UA client certificate authentication** — Authenticate OPC UA client connections using PKI certificates for more secure deployments.
* **Modbus one-based addressing** — Set `WITH ONE_BASED_ADDRESSES true` on Modbus client and server routes so tag addresses match device manuals that label registers starting at 1. See [Modbus addressing](/latest/lot-language/routes/industrial/modbus-tcp-client#modbus-addressing) (client) and [Address notation](/latest/lot-language/routes/industrial/modbus-tcp-server#address-notation) (server).
* **Publish payload as bytes** — Forward or retain binary MQTT payloads bit-for-bit with `PAYLOAD AS BYTES` on `PUBLISH TOPIC` and `KEEP TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#binary-passthrough--payload-as-bytes).
* **EtherNet/IP route** — Joined attribute reads (`ENABLE_JOIN_ATTRIBUTE`), bit extraction (`BIT_ADDRESS`), ARRAY/STRUCT decoding from assembly buffers, bidirectional `WRITABLE` tags, and legacy Hub Asset field mapping for migrations. See the [EtherNet/IP Route guide](/latest/lot-language/routes/industrial/ethernetip).
* **Allen-Bradley route** — Symbolic tag-name access (`Program:MainProgram.Tag` format), `AB`/`ALLENBRADLEY` route aliases, `PATH` vs `SLOT` routing, family-specific STRING/TIME encoding, and cross-link to EtherNet/IP for explicit CIP paths. See the [Allen-Bradley Route guide](/latest/lot-language/routes/industrial/allen-bradley).
* **Bug fixes** — Fixed BACnet alarm retention, EtherNet/IP connection parameters and legacy-style compatibility, a Modbus TCP word-order issue, an OPC UA client connection issue, and a licensing load-order.

**2.1**

June 2026

### 2.1.0 - BACnet route (building automation) and Protobuf models

* **BACnet route** — Connect Coreflux to building automation systems (HVAC, lighting, metering) and bridge them to MQTT
  * Read live values and write setpoints to BACnet controllers
  * Get instant updates on change, without constant polling
  * Receive alarms and event notifications directly in MQTT

See the [BACnet Route guide](/v2.1/lot-language/routes/industrial/bacnet) to get started.

* **Protobuf LoT models (beta)** — Decode and encode binary protobuf on MQTT from LoT: `WITH FORMAT PROTOBUF` (or `BOTH`), `PROTO_TAG` to match vendor `.proto` field numbers, `ADD MODEL` for nested messages on publish, `GET PROTO` / `GET PROTOBUF` to read top-level fields, and `PUBLISH MODEL` to emit real protobuf bytes (not JSON-in-bytes). `WITH FORMAT BOTH` keeps JSON on the main topic and binary on a `/protobuf` sidecar topic.

See [Protobuf Models](/latest/lot-language/models/protobuf) for more details.

**2.0**

April–June 2026

### 2.0.3 - OT tags & route stability

* **OT tag JSON publish** — Message payload now includes the `unit` field
* **Modbus and EthernetIP routes** — Stability improvements

### 2.0.2 - ON CHANGE trigger and bug fixes

* **`ON CHANGE` trigger for LoT actions** — Run actions only when the message payload on a topic is different from the last message on that same topic. Use it for high-frequency telemetry, historians, and forwarding when you do not need to process duplicate values; `ON TOPIC` still runs on every matching publish.
* **Bug fixes** — Stability and correctness improvements across the broker, LoT, and HUB

### 2.0.0 - AI Agent route in the broker

* **AI Agent route** — Create custom agents usable within LoT for AI-driven steps and logic
* **Cloud and local LLMs** — Support for both on AI features

**1.10**

March 2026

### 1.10.0 - Protobuf & REST API route

Support for environment variables and secrets on LoT

* **Protobuf** support
* **REST API route** with OAuth and JWT support
* **Default project on boot** — Load a default project to a Coreflux broker when the broker starts

**HUB**

**2.12**

September–October 2026

### 2.12.0 - Things, Agents, certificates, fleet sign-in, and Cluster Viewer

This release brings the new broker features into the HUB: build and monitor Things and Agents, manage certificates and licenses without leaving the app, sign in with your Coreflux account, and see your cluster at a glance.

#### Highlights

* **Build and watch Things and Agents in the HUB** — Edit them in the LoT Editor, see how they connect in LoT Flow, and turn an action, connector, or agent off without deleting it. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Renew certificates from the app** — Replace the server certificate, trust or revoke a client, and see what is about to expire, without a restart or a shell. See [Certificates](/hub/system/certificates).
* **Open the brokers in your organization** — Sign in with a Coreflux account and connect to your fleet from the login screen. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Activate and enroll without leaving the HUB** — Paste an activation code or a signed license, or enroll the broker in your organization. See [License](/hub/system/configuration#license).
* **See the cluster from the host you already opened (Beta)** — Members, the leader, which links are up, which node owns each piece of LoT, and the clients on each node. See [Cluster Viewer](/hub/cluster-viewer).
* **Start from a template or a public git repo** — Install a Coreflux template as a project, or copy a public repository into the LoT Editor. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Hear live audio and wait on a button** — Data Viewer plays a raw audio topic. A dashboard button stays busy until the work it started finishes. See [Listening to PCM audio](/hub/mqtt/data-viewer#listening-to-pcm-audio).

#### Things and Agents (preview)

* **Things in the LoT Editor** — Deploy THING cells as one payload, checked first with `-addThing --dryRun`. **Broker runtime → Things** lists roots, instances, and their read-only entities, and **Flow preview** draws the notebook's Things. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Things, Tree, and Flat views in LoT Flow** — Switch views to drill into one level at a time, see the whole containment tree, or see everything flat. Panel cards expand into live previews, and the sidebar adds **Agents** and **Things** groups (collapsed at first). See [Things, Tree, and Flat views](/hub/lot-flow#things-tree-and-flat-views).
* **Agent configuration form** — **Configure** and **Add agent** open a form with **Configuration**, **Tools**, and **LoT** tabs. It rewrites only the clauses you change and keeps the rest as written. See [Configure an agent](/hub/ai-assistant#configure-an-agent).
* **Enable and disable** — Switch an action, connector, or agent off and on from its LoT Editor cell, connector card, or agent card. The HUB adds or removes `DISABLE true` and redeploys. The connector Monitor also has **Start** / **Stop**. Disabled cards are dimmed and marked **Disabled**. See [Disable an entity](/hub/lot-editor#disable-an-entity).

#### Certificates and security

* **Certificates tab** — A new System Config tab shows the server certificate and Root CA and replaces them without a restart. It also sets the trust store path and expiry alert, and uploads, searches, and revokes client certificates. Needs broker 2.22. See [Certificates](/hub/system/certificates).
* **Safer uploads** — The client drop zone accepts `.crt`, `.pem`, `.cer`, `.der`, `.p12`, and `.pfx`, and refuses keys and CSRs. Install a server key with **Replace** on the broker certificate.
* **Status bar indicator** — A certificate count with a red, yellow, or green dot. Hover for details, or click to open the tab filtered to certificates that need attention.

#### Account, fleet, and license

* **Sign in with Coreflux** — The login screen adds a **Coreflux Fleet** tab next to **This machine**. The desktop HUB signs in with no setup; a browser HUB needs `COREFLUX_OIDC_CLIENT_ID`, `HUB_PUBLIC_URL`, and `HUB_SESSION_SECRET`. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Fleet brokers** — Read-only rows for your organizations' brokers, with status, license, and **Cloud** / **Self-hosted** badges. **Connect** uses your account; portal actions open [portal.coreflux.org](https://portal.coreflux.org).
* **Cloud mode** — Set `HUB_CLOUD_MODE` on a shared regional HUB to accept only `mqtts://` brokers in `HUB_CLOUD_BASE_DOMAIN`. Leave it unset on desktop and self-hosted installs.
* **License tab** — Paste a `CFLX-…` code to activate, or drop a signed `.jws` file bound to the hardware fingerprint. Limits apply without a restart, and **Refresh** renews the lease. The tab doesn't start a trial.
* **Organization enrollment** — Paste an `et_…` token to enroll. The card shows **Enrolled**, **Not enrolled**, or **Enrollment pending** with the broker's reason. See [System Configuration — License](/hub/system/configuration#license).
* **MCP tab** — System Config → **MCP** turns on the broker's MCP listener, limits its tools, and creates or revokes tokens. See [System Configuration — MCP](/hub/system/configuration#mcp).

#### AI Assistant

* **Choose who answers** — Pick the HUB assistant, which calls the broker over MCP and asks before every write, or any `DEFINE AGENT` marked visible in the HUB. Installing on the broker creates a `TYPE LLM` connector and a `DEFINE AGENT`; legacy `TYPE AGENT` connectors are not listed or migrated. See [AI Assistant](/hub/ai-assistant).
* **Ollama works out of the box** — The assistant sizes Ollama's context per run (`HUB_OLLAMA_MIN_CTX` 16k to `HUB_OLLAMA_MAX_CTX` 32k), so the 4k default no longer truncates prompts. A silent model ends with a clear error after `HUB_AGENT_FIRST_OUTPUT_TIMEOUT_MS` or `HUB_AGENT_IDLE_TIMEOUT_MS` (120 s). See [Ollama requirements](/hub/ai-assistant#ollama-requirements).

#### Cluster Viewer (Beta)

* **See your cluster** — A read-only **Cluster** app shows members, the leader, data-plane links, LoT ownership, and partitions. It appears only while the host publishes cluster status. See [Cluster Viewer](/hub/cluster-viewer).
* **Clients tab** — Lists the MQTT clients on each node with user, address, traffic, last activity, queued messages, and session expiry. Filter, sort, and show the cluster's own connections on request. See [Cluster Viewer — Clients](/hub/cluster-viewer#details).

#### LoT Templates

* **Start from a template** — **Help → LoT Templates**, or **From a template…** in the LoT Editor, browses [templates.coreflux.org](https://templates.coreflux.org) and previews a template before installing it as a project. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Clone from git** — **＋ New → From git…** copies a public git repository into a new LoT Editor project. Cloning copies files only: it does not load or deploy the project. The HUB does not accept private credentials. The clone stops after 30 seconds, the whole repository becomes the project root, and a project download above 64 MB is refused. See [Clone from git](/hub/lot-editor#clone-from-git).

#### Connections

* **Generic MQTT brokers** — On a broker that isn't Coreflux, the dock keeps **Data Viewer** and **UNS Viewer** and hides Coreflux apps. Saved cards are tagged **MQTT** or **Coreflux**. See [When the broker is not Coreflux](/hub/connections#when-the-broker-is-not-coreflux).
* **Default connection** — In the web HUB, `HUB_DEFAULT_CONNECTION_HOST` and optional `HUB_DEFAULT_CONNECTION_*` variables pre-fill **New Connection**. Every browser receives the password, so use shared demo credentials only. See [Default connection (web / Docker)](/hub/connections#default-connection-web-docker).

#### Data Viewer and dashboards

* **Audio topics** — Raw PCM topics, such as an [Audio Input](/latest/lot-language/routes/media/audio-input) stream, show a live waveform you can play, clip, export to WAV, and scrub. See [Data Viewer](/hub/mqtt/data-viewer).
* **Busy buttons and markdown text** — A button with `SET AWAIT` stays busy, and each named component shows a pending indicator until its next message. The wait is 120 seconds unless `SET AWAIT_TIMEOUT` says otherwise, and then the panel shows a timeout note. `SET MARKDOWN true` on a text component renders sanitized markdown: no raw HTML, images, or unsafe links. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button).
* **Own window** — **Open in a new window** opens the Data Viewer on the current broker. See [Open the viewer in its own window](/hub/mqtt/data-viewer#open-the-viewer-in-its-own-window).
* **Panels grid** — A toggle in the Panels header switches to a grid of live dashboard thumbnails. The list stays the default. See [Managing Panels](/hub/dashboards/manager#managing-panels).

#### Desktop and settings

* **Desktop shell** — Click the logo to show the desktop. The account pill groups **Broker** administration, **Hub** (Themes and Hub Settings), and **Help**. See [Desktop shell](/hub/overview#desktop-shell).
* **Dock and status bar** — Right-click to set the dock position and auto-hide, and double-click a title bar to zoom. The same controls are in **Hub Settings → Desktop**. See [Dock and status bar](/hub/overview#dock-and-status-bar).
* **Hub Settings** — Memory limits, viewer refresh, and video wallpaper moved from System Config to **Hub Settings**. See [Hub Settings](/hub/overview#hub-settings).
* **Install and update** — Install the browser HUB as an app from `localhost` or HTTPS. The installed desktop app updates itself. See [Updating Your Coreflux](/latest/updating-coreflux#hub-desktop).
* **Walkthroughs** — Short tours on first launch and on each app's first open. Replay or reset them from **Help → Walkthroughs**. See [First-run walkthroughs](/hub/overview#first-run-walkthroughs).

#### Bug fixes

* **Maps show streets again** — Geolocation maps in the Data Viewer use keyless OpenStreetMap tiles, darkened in the dark theme, with the attribution **© OpenStreetMap contributors**. A build can set `VITE_CARTO_BASEMAPS_KEY` to use CARTO Dark Matter, or `VITE_MAP_TILE_URL` and `VITE_MAP_TILE_ATTRIBUTION` for another tile source. See [Tracking what matters](/hub/mqtt/data-viewer#tracking-what-matters).

**2.3**

August–September 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.3.4 - Login, Deploy, and Data Viewer fixes

#### Bug fixes

* **Non-admin users no longer get bounced back to the login screen** — Signing in as a user without full system access could loop back to login instead of opening the HUB in Limited Mode. The HUB now recognizes a denied `$SYS` subscription for what it is and opens Limited Mode as designed.
* **Deploy project shows accurate status** — Deploying a project via [Connections Manager](/hub/connections) no longer surfaces the broker's success response as a false warning, and the project header no longer gets stuck on **Updating** after the deploy completes.
* **LoT Editor keeps dropped files on the project** — Images and other files dropped into a project (from the Finder, Explorer, or a mixed-OS drag) now stay attached instead of being lost.
* **Data Viewer confirms whether a publish actually landed** — Sending a message no longer shows **Published** when the broker silently rejected it for lacking a publish ACL; Data Viewer now waits for the topic echo before confirming.

### 2.3.0 - LoT Editor, Connections Manager, LoT Flow wiring

#### LoT Editor

* **Visual Studio Code-style editor** — An intuitive notebookeditor with a familiar interface inside the HUB.
* **Unified Projects view** — One Projects list covering every project stored on the broker and every draft held in the HUB. The live project is marked, local-only drafts stay distinct, and each row carries its own sync state: clean, unsaved edits, changed on the broker, or diverged.
* **Push only what changed** — Push stores the working copy and deploys just the drift, instead of redeploying a whole project.
* **Broker Runtime inspector** — A table of what is actually running on the broker, with read-only source for each entity, and a jump from any running entity to the notebook that declares it.
* **Documents alongside notebooks** — Open and store Markdown, text, PDF, and images in a project, import files from disk, and reference them in LoT notebook cells.
* **Copy entities between notebooks** — Copy or drag a declared or deployed entity into another notebook.
* **Version history** Git based version control for project files.
* **Activate and Deactivate projects** from the project tree.

#### Connections Manager

* **More than one broker** — The HUB keeps a named list of broker connections with favorites, replacing the single remembered URL. Each is shown as a card on the login screen.
* **Change Broker** — Switch the whole HUB to another saved connection from the account menu, without logging out and reconfiguring.
* **Per-connection TLS** — Store a CA certificate and a client certificate against an individual connection.
* **Credentials kept off the connection record** — Passwords and client keys live in a separate store; the desktop app encrypts it using the operating system's secure storage, and the browser app never writes them to disk.
* **Live reachability on the login list** — Saved connections are probed so you can see which brokers answer before you pick one.

#### LoT Flow

* **Cleaner connections between nodes** — `KEEP`-topic edges and "matches" edges no longer clutter the canvas, and `MODEL` nodes are drawn as terminals, so the remaining edges show real data flow.
* **Topics grouped by role** — Command and telemetry topics are grouped by the role they play, with disambiguated group labels, prefix hubs backed by a topic-set panel, and wildcard subscriptions expanded to the topics they match.
* **Topic pulse toggle** — Turn live topic activity animation on or off.
* **Export the canvas as an image** — Download the current flow as a PNG.

**2.2**

July 2026

### 2.2.0 - UNS viewer & LoT Flow

* **LoT Flow** — A new interactive view of your LoT data flows, showing entity, topic, and Python nodes alongside live topic values, action traces, and route status.
* **UNS viewer** — Browse your Unified Namespace as a tree, with search, live payload previews, and a graph layout.
* **Data Viewer overhaul** — A refreshed explorer with a detailed topic view, timeline, faster topic indexing, and better subscription management.
* **In-app release notes** — A "What's New" dialog in the HUB so you can see what's changed without leaving the app.
* **Refreshed HUB styling** — Updated visual design and dock layout.
* **AI chat improvements** — A setup wizard, an artifact panel, and a generally expanded chat experience.
* **Expanded dashboard panels** — More display components, gauge options, and model-binding support for building richer dashboards.
* **Bug fixes** — Fixed the LoT compiler and dashboard rendering for `ON KEY PRESS`, `ON THRESHOLD BREACH`, conditional handlers, `WITH THEME`, numeric decimals and suffixes, threshold zones on gauges/charts, and callable actions. Fixed `INVOKE ACTION`, `BIND TO MODEL`, the accordion "Add Section," and tab titles in dashboards. Fixed real-time charts to show both traces with a legend and to correctly distinguish bar vs. line modes. Fixed select/dropdown interactions, topic-to-widget data binding (previously showing a single point instead of the full array), slider and toggle controls publishing incorrect values, icon visibility, multi-panel layouts, and events not being recognized on mount. Fixed the AI agent to properly detect uninstalled routes, and corrected its confirmation prompts. General mobile layout improvements.

**2.0**

April 2026

### 2.0.0 - UI/UX overhaul, standalone installer, AI Agent

![Coreflux HUB Data Viewer showing MQTT topic tree with live data values and real-time charts](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/hub-data-viewer.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=634b8986391a76e82ef3f03574338cb6)

Coreflux HUB Data Viewer with live MQTT topic data and charts

* **UI/UX improvements**
* **Standalone installer** — Windows and Linux
* **AI Agent**
  * **Insights mode** — Ask questions about running data, using project information as context
  * **Agent mode** — Build LoT, routes, and dashboards with an AI copilot

**VS Code Extension**

**1.0**

August–October 2026

These notes are VS Code extension **1.0**. Features that use the broker's new commands need broker **2.22**.

### 1.0.0 - Things, Agents, Validate, MCP, and licensing

This release lets you write Things and Agents in notebooks, check your LoT on the broker before deploying, connect your AI tools to the broker's MCP server, and manage licensing, all from VS Code.

#### Highlights

* **Write Things and Agents where you already write LoT** — Check them against the broker and deploy them from the notebook, the same way as any other cell. See [THING cells](/lot-notebooks/usage#thing-cells).
* **Check before you deploy** — Validate a cell or the whole notebook on the broker. Problems show on the cell, and nothing is deployed until you run it. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Switch a cell off without deleting it** — Disable an action, connector, or agent from the cell status bar, and turn it back on when you want it running. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **Connect your AI tools in one step** — The MCP Server tab writes the broker endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Teach your coding agent LoT** — Install the Coreflux skills so the agent writes valid LoT and works with the broker. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **License and enroll from VS Code** — Activate with a code, install a signed license, or enroll the broker, from the License tab. See [License tab](/lot-notebooks/usage#license-tab).

#### LoT cells

* **Things** — A run sends the cell's `DEFINE THING` blocks and their workspace templates as one `-addThing`, after a `--dryRun` whose problems show on the cell. **Remove Thing from Broker** sends `-removeThing`, and a quick fix updates older THING syntax (`TEMPLATE`, and `{p}` to `{{p}}`). See [THING cells](/lot-notebooks/usage#thing-cells).
* **Agents** — `DEFINE AGENT` cells are checked like the broker checks them and deploy with `-addAgent`. Broker agents appear in the Coreflux Explorer and the Entities panel. See [Agent cells](/lot-notebooks/usage#agent-cells).
* **Validate** — Check a cell or the whole notebook on the broker without deploying it. Results appear under the cell and in Problems. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Enabled / Disabled toggle** — Switch `DISABLE true` on and off for action, connector, and agent cells from the cell status bar, and the change uploads. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **`DEFINE CONNECTOR`** — Recognized in checks, completions, and hovers, with `DEFINE ROUTE` as its alias. Connector cells upload from the cell, and Deploy Project includes them.
* **`RETURN AS` under `CALL`** — A `RETURN AS` line under a `CALL` no longer reports an indentation error.
* **Panels and themes** — `DEFINE PANEL` and `DEFINE VISU` cells, and a Thing's `WITH PANEL` body, are checked with the broker's panel parser. Highlighting, hover, completions, and a `DEFINE PANEL` snippet are included. Running the cell sends `-addVisu`; removing it sends `-removeVisu`. `DEFINE THEME` and `THEME_VARIANT` are recognized. The cell status bar offers **Open in Coreflux HUB** to view the rendered panel, and a successful upload suggests opening Dashboards there. See [Panel cells](/lot-notebooks/usage#panel-cells).
* **Agent and Thing checks match the broker** — Valid agent, thing, rule, connector, and model syntax is no longer flagged, including connector keys such as `SUBJECT` and mixed-case names. See [Agent cells](/lot-notebooks/usage#agent-cells).

#### Broker management

* **License tab** — Activate with a `CFLX-…` code, install signed license text, enroll with an `et_…` token, and refresh the lease. The Instance Key field is gone. See [License tab](/lot-notebooks/usage#license-tab).
* **MCP Server tab** — Turn on the broker's MCP server, pick its tools, and manage tokens. **Install MCP server** writes the endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop, and keeps workspace config files out of Git. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Install Agent Skills** — **Install Agent Skills...** lets you pick which of the 11 bundled skills to install and where (the `.agents`, `.claude`, `.cursor`, or `.github` skills folder, in the workspace or your home folder). Skills come from the public [coreflux-skills](/ai/agent-skills) repository (broker 2.22 or later), and older copies from previous versions are offered for removal. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **Remove All Things / Templates** — Two new commands clear every Thing or every template from the broker.
* **Variables** — "Environment Vars" is now "Variables" everywhere, including **Secrets & Variables**.

#### Data Viewer and workspace

* **Bounded history** — Each topic keeps its last 100 messages by default (`coreflux.dataViewer.historyBufferPerTopic`, 50 to 2000), set from the timeline gear. The timeline draws again, and pausing or scrubbing stays steady while messages arrive. See [Adjust how you see the data](/lot-notebooks/debug#adjust-how-you-see-the-data).
* **Apps in the editor area** — Data Viewer, Logs Viewer, and Secrets & Variables open as tabs next to your notebooks.
* **Connection Manager** — Save several broker connections and switch between them.
* **Entities table** — See the LoT entities running on the broker in their own table.
* **LoT projects** — Create, edit, and deploy LoT projects.

**beta**

April 2026

![Screen recording of creating and deploying LoT in the Coreflux VS Code extension](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-and-deploy-lot.gif?s=5cd139e03cbf0b5109848b498d7c65eb)

Create and deploy LoT from the Coreflux VS Code extension

* **Improved VS Code extension (beta)**
  * License usage
  * Live MQTT data (topic tree)
  * **Data Viewer** — View and replay historical and live data for MQTT topics, with viewers for raw, JSON, PDF, GeoJSON (map), audio, and more
  * **Execution trace** — View and replay historical and live data from LoT execution, including success and error states, published topics, and internal variables
  * Manage secrets and environment variables


# Release Notes
Source: https://docs.coreflux.org/product-updates/release-notes

New features, improvements, and fixes in each release of the Coreflux MQTT broker and HUB.

Product

**MQTT Broker**

**2.22**

August–October 2026

> [!WARNING]
>
> **Breaking Changes** in this release (2.15–2.22):
>
> **`TYPE MCP_SERVER` is gone** — The MCP server is now broker configuration, not a LoT connector, and a project that still defines `TYPE MCP_SERVER` fails to load. Enable `Mcp.Enabled` (or `COREFLUX_MCP_ENABLED=1`), mint a token with `-createMcpToken`, and point the client at Streamable HTTP `/mcp`. Legacy SSE URLs stop working. The MCP client connector (`TYPE MCP` / `CALL MCP`) is unchanged. **Action:** remove old `TYPE MCP_SERVER` definitions and follow [MCP Server](/latest/mqtt-broker/mcp-server).
>
> **`TYPE AGENT` connectors are removed** — `-addConnector` refuses them and stored ones are skipped at load, with their topics. Rewrite each as a `TYPE LLM` connector plus `DEFINE AGENT … USES LLM CONNECTOR`; nothing is granted until `ADD TOOL`, and writes need `WITH LEVEL "write"`. There is no automatic migration. **Action:** rewrite agents before you upgrade. See [Coming from TYPE AGENT](/latest/lot-language/agents/overview#coming-from-type-agent).
>
> **No built-in trial** — A broker with no license runs as **Community**. Get a 30-day Growth-type license at [portal.coreflux.org](https://portal.coreflux.org), where you also manage your fleet.

### 2.22.0 - Things, Agents, licensing, and a built-in MCP server

This release lets you model devices once and reuse them (Things), build AI agents that only do what you allow, and connect tools like Cursor or Claude Desktop straight to the broker. It also adds signed licensing with fleet enrollment, certificate management, and clustering that runs your LoT on every node.

#### Highlights

* **Model a device once, then reuse it (Things, preview)** — Describe a pump, a line, or a sensor type once. Each copy gets its own topics, and you add as many as you need without copying LoT. See [Things](/latest/lot-language/things/overview).
* **Let AI act only where you allow it (Agents, preview)** — An agent starts with no tools. You grant each read or write, and a question-only mode never changes the broker. See [Agents](/latest/lot-language/agents/overview).
* **Work on the broker from Cursor or Claude** — A built-in MCP server lets those tools run broker commands, with tokens you create and revoke. See [MCP Server](/latest/mqtt-broker/mcp-server).
* **Keep every cluster node on the same LoT** (**Beta**) — Deploy to any node and the whole cluster runs it. A device connector can stay on the node that can reach the equipment. See [LoT in a cluster](/latest/mqtt-broker/clustering#lot-in-a-cluster).
* **License a broker and add it to your fleet** — An unlicensed broker runs as Community. Activate online, use a signed file where there is no internet, and enroll the broker in your organization. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).
* **Replace certificates without a restart** — Update the certificate the broker presents, choose which clients to trust, and see which certificates are about to expire. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Sign in with your identity provider** — Clients can use an OIDC access token as the MQTT password. Local passwords still work. See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Pause logic without deleting it** — Turn an action, connector, or agent off, keep the definition, and turn it back on when you are ready. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **See when a device is actually down** — Industrial connectors show Reconnecting when a PLC stops answering, and the last good tag values stay in place through a short disconnect. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **Bring in audio, gRPC, and hundreds of APIs** — Capture microphone audio onto MQTT, call gRPC services, and start from 220+ REST API app templates (technical preview). See [REST API Apps](/latest/lot-language/routes/rest-api-apps/index).

#### Things and Agents (preview)

* **Define a device once** — A Thing is a typed device with `{{placeholder}}` topics. Add instances with `-addThing` (use `--dryRun` to validate first), and manage them with `-removeThing` and `-listThings`, or the MCP tools `add_thing`, `list_things`, and `remove_thing`. Each Thing publishes its source, tree, and health under `$SYS/Coreflux/Things/<name>`. See [Things commands](/latest/mqtt-broker/commands#things).
* **Agents with limited access** — An agent uses a `TYPE LLM` connector for its provider, model, key, and price, and starts with no tools. It gets only what `ADD TOOL` grants. Agents can ask each other for help with `WITH AGENTS`, and actions call them with `CALL AGENT`. Each agent publishes its card and status under `$SYS/Coreflux/Agents/<name>/`.
* **Read-only questions** — Ask an agent with `"mode": "insight"` and it only reads, including any agents it delegates to. `TYPE LLM` also accepts `REASONING_EFFORT` (`none` to `extra_high`).

#### New connectors

* **Audio Input** — Capture a microphone, test tone, silence, or a file as 16-bit PCM audio on MQTT (`TYPE AUDIO_INPUT`). See [Audio Input](/latest/lot-language/routes/media/audio-input).
* **gRPC** — Call gRPC services from MQTT with `TYPE GRPC`, including streaming. See [gRPC Connector](/latest/lot-language/routes/streaming/grpc).
* **REST API apps** — 220+ ready-made `TYPE REST_API` templates for cloud, ERP, MES, messaging, and IIoT services, in technical preview. See [REST API Apps](/latest/lot-language/routes/rest-api-apps).

#### MQTT and LoT

* **Connectors naming** — `DEFINE CONNECTOR` and the `-addConnector`, `-removeConnector`, `-listConnectors`, `-removeAllConnectors`, and `-checkConnectorConnection` commands are the new names. `DEFINE ROUTE` and the `-…Route…` commands keep working as aliases.
* **Turn things off without deleting them** — Put `DISABLE true` under `DEFINE` on an action, connector, or agent to keep it stored but not running. Switch it back on with `-disableAction`, `-disableConnector`, `-disableAgent` and the matching `-enable…` commands, or with MCP tools. See [Disable and Enable](/latest/mqtt-broker/commands#disable-and-enable).
* **Publish with retain and QoS** — `PUBLISH TOPIC` accepts `RETAIN` and `QOS0` / `QOS1` / `QOS2` (default QoS 0). `KEEP TOPIC` still only stores a value for `GET TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#publish-topic).
* **Shared subscriptions** — Turn on `SharedSubscriptions` and `$share/{group}/{filter}` delivers each message to one member of the group. Off by default. See [Shared subscriptions](/latest/mqtt-broker/protocol#shared-subscriptions).
* **Predictable topic triggers** — `ON TOPIC` actions, models, and connector events run on the exact message that fired them, in publish order per topic. Different topics still run in parallel. See [Action Triggers](/latest/lot-language/actions/events).
* **Every publish in an action is sent** — Each `PUBLISH TOPIC` or `KEEP TOPIC` in one run is delivered, in the order written, with that line's own retain, QoS, and keep settings. A later `GET TOPIC` in the same run reads the value just written. In a cluster, only the last `KEEP` of each topic is replicated. See [PUBLISH TOPIC](/latest/lot-language/actions/operations#publish-topic).
* **Panel wait and markdown** — A button accepts `SET AWAIT "Id, Id"` and `SET AWAIT_TIMEOUT` (seconds, default 120). A text component accepts `SET MARKDOWN true`. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button) and [Markdown text](/latest/lot-language/panels/defining-panels#markdown-text).

#### Licensing and enrollment

* **Plans** — Community, Growth, and Enterprise, with limits on artifacts and connectors. Status is on retained `$SYS/Coreflux/License` and, on the ops port, `GET /license` (port `9100`, keep it private).
* **Three ways to license** — Activate online with `COREFLUX_ACTIVATION_CODE` or `-activateLicense CFLX-…` (limits apply without a restart, the lease refreshes daily, `-refreshLicense` forces it). Or install a signed license file (`config/license.jws`, `COREFLUX_LICENSE_FILE`, `COREFLUX_LICENSE_TOKEN`, or `-loadLicense`), which the broker verifies locally with no network. For air-gapped hosts, send the `--show-fingerprint` value to Coreflux and install the hardware-bound license you get back.
* **Enroll in your organization** — `-enroll et_…` (or `--enroll`, or `config/enrollment-token`) binds the broker to your Coreflux organization, separately from its plan. An activation code enrolls it too. A broker waiting for enrollment still starts: local users work, and logins that need the organization are refused until it succeeds. `$SYS/Coreflux/License` explains why it is pending. See [Licensing and Enrollment](/latest/mqtt-broker/licensing).

#### MCP server

* **Connect AI tools to the broker** — Cursor, Claude Desktop, and other MCP clients connect to the broker's built-in server, configured in the `Mcp` block (port `6278`, bound to `127.0.0.1`, path `/mcp`). Manage tokens with `-createMcpToken`, `-listMcpTokens`, and `-revokeMcpToken`, or from the HUB **MCP** tab. In Docker or Kubernetes, bind to `0.0.0.0`, publish `6278`, and route `/mcp` behind TLS. See [MCP Server](/latest/mqtt-broker/mcp-server#docker-and-kubernetes).
* **Install agent skills** — The public [coreflux-skills](https://github.com/CorefluxCommunity/coreflux-skills) repository is generated from the broker, and the broker exposes the same pack as the `coreflux://skills` MCP resource. Coding agents that install it write LoT the broker accepts. They need broker 2.22 or later. See [Agent skills](/ai/agent-skills).

#### Security

* **Sign in with OIDC** — With `Oidc.Enabled`, a client sends an OIDC access token as its MQTT password. The broker validates it, checks the organization, and authorizes by the token's groups. Local passwords still work. A client is disconnected when its token expires (30-second grace). See [OIDC and Bearer Authentication](/latest/mqtt-broker/oidc-authentication).
* **Manage certificates from a command** — `-brokerCertificates` (admin only) shows and replaces the server certificate and Root CA, and manages the mTLS trust store: list, import, export, revoke, settings. A new server certificate applies without a restart and keeps a `.bak-` copy. Revocation is immediate and every change is audit-logged. See [Broker Certificates](/latest/mqtt-broker/commands#broker-certificates).
* **Know when certificates expire** — Retained `$SYS/Coreflux/Certificates/Summary` counts valid, expiring, expired, and unreadable certificates. `CertificateExpiryThresholdDays` (default 30) sets the warning window. See [`$SYS/Coreflux/Certificates/Summary`](/latest/mqtt-broker/sys-topics#syscorefluxcertificatessummary).
* **Easier trust store** — `ClientCertificateSourcePath` loads `.pem`, `.crt`, `.cer`, `.der`, and unprotected `.p12`/`.pfx` files, skips anything in `revoked/`, and refuses keys and CSRs (install a server key with `replaceServer`). `$SYS/Coreflux/Config` shows `ServerCertificatePassword` as `********`.

#### Clustering and operations

* **LoT works across a cluster** (**Beta**) — Definitions replicate through the leader, so you can send LoT to any node and every node runs the same version. Each message runs LoT once, on the node it entered. Timers, `ON START`, and device connectors run on one owner and move to another node within about 10 seconds if it fails. Pin a device connector to a node with `CLUSTER_NODE` in `ROUTE_CONFIG`. **Action:** upgrade every node before you change LoT, and create users on every node.
* **Faster Kubernetes scaling** (**Beta**) — A pod that the headless Service no longer lists leaves the cluster about 2 minutes after its cluster port stops answering (`MemberAbsentFromDiscoverySeconds`, 120 seconds by default; it used to wait 5 minutes). New pods are found within seconds. See [How a cluster works](/latest/mqtt-broker/clustering#one-leader-automatic-membership).
* **More metrics** — New `/metrics` series for delivered messages, CPU, auth failures, ACL denials, rate limits, connector drops, and errors. See [Metrics](/latest/mqtt-broker/operational-endpoints#metrics).
* **Fleet health reporting** — An enrolled broker reports CPU, memory, clients, traffic, refusals, drops, and scrubbed error signatures to the Coreflux Portal. It never sends topics, payloads, hostnames, or IPs. Turn it off in the portal, or with `COREFLUX_FLEET_METRICS=off` or `DO_NOT_TRACK=1`. See [Fleet performance metrics](/latest/mqtt-broker/licensing#fleet-performance-metrics).

#### Bug fixes

**Industrial connectors**

* **Connection status tells the truth** — Modbus, S7, OPC UA, EtherNet/IP, ADS, Allen-Bradley, FINS, and BACnet no longer wipe retained tag values on a disconnect or failed read, and a restarted connector polls again. A connector no longer shows Connected while its device is unreachable: after 3 failed read cycles it reports Reconnecting and rebuilds the connection. See [Connection status](/latest/lot-language/routes/industrial/overview#connection-status).
* **No more hangs on silent devices** — A PLC that accepts a connection but never answers no longer freezes S7 (`READ_TIMEOUT` now limits the connect) or EtherNet/IP (`READ_WRITE_TIMEOUT` now bounds every exchange). **Action:** raise `READ_WRITE_TIMEOUT` for slow EtherNet/IP devices.
* **Modbus TCP** — Each connection runs one request at a time, so tags no longer go BAD with "Response was not of expected transaction ID". See [Modbus TCP Client](/latest/lot-language/routes/industrial/modbus-tcp-client#one-request-at-a-time).
* **FINS** — A slow reply no longer shifts later reads onto the previous command's value, and a lost PLC goes to Reconnecting after 2 unanswered commands. Replies must now match the request and come from the addressed node. **Action:** gateways that swap client and server nodes now time out; check `LOCAL_NODE` / `REMOTE_NODE`. See [FINS](/latest/lot-language/routes/industrial/fins).
* **Allen-Bradley** — A slow but healthy PLC no longer reconnects every cycle, and a timed-out write publishes `"outcome": "unknown"`. See [Write results](/latest/lot-language/routes/industrial/overview#write-results).
* **ADS** — `TIMEOUT` now applies to every request (it was ignored and fixed at 5 s), and an unreachable PLC makes the connector reconnect. See [ADS](/latest/lot-language/routes/industrial/ads).
* **OPC UA** — A read or write that races a reconnect marks the tags BAD and backs off instead of counting as success, and sessions no longer leak.
* **BACnet** — Integer writes of any size send the right value (out-of-range 64-bit values fail instead of being cut off), and reads queued on a dropped connection no longer break the new one.
* **Tag values** — Negative `OFFSET`, `MIN_VALUE`, and `MAX_VALUE` now parse. See [Common TAG parameters](/latest/lot-language/routes/industrial/overview#common-tag-parameters).

**Other connectors**

* **Kafka** — A `"in"` event commits its offset only after the message is published, so a crash no longer drops records. `WITH EVERY` on a Kafka event is now rejected when you add the connector. **Action:** publish on a schedule with `ON EVERY` in a LoT action. See [Kafka Connector](/latest/lot-language/routes/streaming/kafka).
* **Kafka and gRPC start** — A connector that fails to start is retried in the background (2 to 60 seconds) until it starts or you remove it.
* **Ollama** — A `TYPE LLM` connector with `PROVIDER ollama` takes `CONTEXT_WINDOW` (a fixed `num_ctx`, sized per call and capped at the model's maximum), `MAX_CONTEXT_WINDOW` (default 32768, minimum 16384), `FIRST_OUTPUT_TIMEOUT` (default 120 s), and `IDLE_TIMEOUT` (default 60 s). Agent tasks fail with a clear error (`llm_timeout`, `llm_unreachable`, `model_not_found`, `context_overflow`) instead of hanging. See [Ollama context and timeouts](/latest/lot-language/routes/ai-routes#ollama-context-and-timeouts).
* **Email and CrateDB** — Email `ADD EVENT` blocks now send and publish their status. CrateDB `ADD EVENT` blocks run, `STORE IN` writes rows, and the connector reconnects after a CrateDB restart.
* **REST API** — A reply published right away on `REPLY_TOPIC` reaches the HTTP client instead of a 504, and concurrent requests no longer cancel each other. A value in `ENDPOINT` can no longer send the request and its credentials to another host; the broker refuses it and publishes `RequestRejected`. See [Placeholder Support](/latest/lot-language/routes/rest-api-routes#placeholder-support).
* **MQTT bridge** — A bridge without `CLIENT_ID` forwards inbound messages and no longer clashes with other bridges, and a removed bridge stops forwarding at once.
* **Sparkplug B** — The Primary Host tracks `seq` per edge node and no longer floods Rebirth requests, and DATA metrics without a datatype decode using the birth certificate.
* **`TRIGGER` on LLM, AGENT, and MCP** — MCP calls the named tool, and LLM and AGENT results go to the mapping's `DESTINATION_TOPIC` or the default response topic instead of being discarded.

**LoT and MQTT**

* **`GET MODEL`** — `SET … WITH GET MODEL` no longer fails on the action's first run, `PUBLISH TOPIC … WITH GET MODEL` parses, and `WHERE` conditions joined with `AND` accept any mix of text and numbers. See [GET MODEL](/latest/lot-language/actions/operations#get-model).
* **`STORE IN … WHEN`** — Conditional model storage works instead of failing on first evaluation, and an unknown field is rejected at deploy. See [Store data with models](/latest/lot-language/routes/data-storage/overview#step-2-store-data).
* **`MATCHES REGEX`** — Patterns with `\d`, `\w`, `\s`, or `\.` work as written. See [MATCHES REGEX](/latest/lot-language/rules/syntax#matches-regex).
* **`TRIGGER` statements** — The line after a `TRIGGER` is no longer dropped. Examples now use `TRIGGER "<connector>" TO <data> FOR "<event>"`; code copied from the old order (`WITH "<event>" FOR <data>`) still deploys but swaps the data and the event. See [TRIGGER Statement](/latest/lot-language/actions/operations#trigger-statement).
* **MQTT 5 denials** — A denied publish now gets `0x87 Not authorized` and a rate-limited one `0x97 Quota exceeded`, instead of Success. See [What a denied client sees](/latest/lot-language/rules/rbac#what-a-denied-client-sees).
* **Callable actions from panels** — Object, array, and `null` arguments no longer cause a compile error; objects and arrays arrive as JSON text.
* **Protobuf `float` and nested `GET PROTO`** — `ADD FLOAT` (alias `ADD SINGLE`) decodes proto `float`, and dotted `GET PROTO` paths read nested messages. A field with the wrong type is skipped instead of stopping the whole message. See [Protobuf Models](/latest/lot-language/models/protobuf).

**Panels, projects, and platform**

* **Panels** — Boolean CSS bindings (`BIND CSS … AS BOOLEAN`) convert correctly in the HUB. SVG markup from `SET INLINE` and `data:` sources is rebuilt from an allow-list so scripts, event handlers, and external links can't run in viewers' browsers; what was removed is listed as a deploy warning.
* **Projects** — A live project's history records only the edited cell, not the whole notebook. After a restart, the broker also loads connectors added outside the project and the connectors of Things, and publishes Thing status from boot. See [LoT THING](/latest/lot-language/things/overview).
* **Metrics** — Published-message and byte counters no longer reset at UTC midnight, so `rate()` works across it. `coreflux_messages_published_total` now counts client publishes; deliveries moved to `coreflux_messages_delivered_total`.
* **Linux packages** — APT and DNF units run the broker as the user `coreflux` with `CAP_NET_BIND_SERVICE`, so they can bind ports below 1024. See [Ports below 1024](/latest/mqtt-broker/startup-options#ports-below-1024).

**Configuration**

* **Partial config is merged** — A partial JSON object published to `$SYS/Coreflux/Config/New` is merged into the live configuration. Fields you omit, including bind addresses, stay as they are. See [Applying Configuration](/latest/mqtt-broker/configuration#via-mqtt-topic).

**2.14**

August 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.14.3 - Default rules and Visu panel publishing

#### Bug fixes

* **Default rules load with an active project; Visu panels can be published** — When a project is already active at startup or after `-loadProject`, the broker's seeded permission rules now apply correctly so internal clients retain `$SYS` access and panels publish to `$Visu/...` topics again after project activation.

### 2.14.2 - Sparkplug B connector, MQTT & LoT performance improvements

Sparkplug B Support, MQTT client lifecycle action triggers, better OT master/client visibility in broker logs, a banded Rules precedence model, project lifecycle improvements, and faster publish, LoT, and connector dispatch.

#### Improvements

* **Rules priorities are now banded** — The rule priority number line is split into bands: `0`–`99` is reserved for the broker's immutable system rules, `100`–`999 999` is your band, and the permissive catch-alls `AllowPublishTopic` / `AllowSubscribeTopic` now sit at `1 000 000`. Only the strongest matching band decides an operation, where a DENY beats an ALLOW (deny-wins) and nothing matching means denied (default-deny). Moving the catch-alls to the weakest band **fixes a topic-visibility bypass**: they previously shipped tied with everything else, so a specific access rule could not reliably override the allow-all fallback — which left Visu panel view topics effectively public. `-addRule` now rejects priorities outside `100`–`1 000 000`. **Action:** custom rules written in the old `1`–`99` range are clamped to `100` on load and logged individually. Clamping keeps them in force, but several rules can land on `100` together, where ties resolve deny-wins — re-space them across the user band, putting the more specific rule at the lower number. See [RBAC with LoT Rules](/latest/lot-language/rules/rbac#rule-precedence).
* **`AllowConnect` seed and `FOR Connect` rules** — Fresh brokers now ship a third permissive catch-all, `AllowConnect`, at priority `1 000 000` (the same weakest band as `AllowPublishTopic` / `AllowSubscribeTopic`). Write `FOR Connect` rules in the user band to decide who may connect after authentication; they outrank the seed. Brokers with no Connect rule at all still leave CONNECT ungated. `-restoreRules` puts all three seeds back to their shipped ALLOW definitions. See [RBAC](/latest/lot-language/rules/rbac#connection-admission) and [`-restoreRules`](/latest/mqtt-broker/commands#restoring-seeded-rules).
* **Project manifests, entity ownership, and ad-hoc entities** — Each stored project publishes a retained content manifest on `$SYS/Coreflux/Projects/{name}/manifest` (SHA-256 of exact file bytes, plus entities declared in `.lotnb` cells). `-projectManifest` returns the same JSON on demand. Running entities are attributed on `$SYS/Coreflux/Entities/ownership` and in the `-listEntities` / `-loadProject` `origin` field. **Loading or unloading a project no longer deletes ad-hoc entities** added with `-addAction` and similar commands while no project was active. **Action:** if you relied on Activate to wipe the whole runtime, remove those entities explicitly before loading a project. See [Project Commands](/latest/mqtt-broker/commands#project-commands) and [Project Topics](/latest/mqtt-broker/sys-topics#project-topics).
* **Loaded projects stay active after a restart** — After `-loadProject` (or `--project`), the last loaded project is remembered and re-activated on the next start unless you pass `--project`. `-unloadProject` returns to standalone mode on the next restart. See [Startup Options](/latest/mqtt-broker/startup-options#loading-a-project-at-startup).
* **`ON START` runs on deploy; action publishes are no longer blocked by user ACL** — Deploying an `ON START` action on a live broker executes the body immediately (cold start still runs once after the MQTT broker is ready). Action `PUBLISH` / `KEEP` still put messages on MQTT for any subscriber; they are no longer denied by user publish rules, so bootstrap topics from actions are not silently dropped. Clients still need subscribe permission to receive those messages. See [Initialization Triggers](/latest/lot-language/actions/events#initialization-triggers).
* **OT string sizing — `LENGTH` is the preferred keyword** — Across OT connectors that support configurable string sizing, `WITH LENGTH` is now the documented primary keyword; `STRING_SIZE` remains accepted as a parser alias. See the shared [String sizing by Connector](/latest/lot-language/routes/industrial/overview#string-sizing-by-connector) reference on the industrial connectors overview.
* **Modbus Server STRING defaults and cap** — Unsized `STRING` tags no longer reserve a single register (which silently truncated barcodes and caused Illegal Data Address on FC16 writes). The server now defaults to **40 bytes (20 registers)** and warns when size is omitted. Connector validation rejects `LENGTH` values above **246 bytes (123 registers)**, the FC16 write cap. See the [Modbus TCP Server Connector guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **Modbus Server and OPC UA Server activity logging** — Modbus Server connectors log accepted and rejected master writes (plus rejected reads), with bank-aware function-code labels and `LENGTH` guidance when an undeclared holding-register range is the cause; connection open/close counts are logged from the existing watchdog (**the master's source IP is not available**). OPC UA Server connectors log client session create/close events and accepted external writes on tags and STRUCT fields.
* **MQTT client lifecycle action triggers** — New `ON CONNECT DO`, `ON DISCONNECT DO`, and `ON SUBSCRIBE ["pattern"] DO` triggers run LoT automation when clients connect, disconnect, or subscribe. Action bodies expose session context via `CLIENTID`, `USER`, `ENDPOINT`, `CLEANSESSION`, `DISCONNECTREASON`, `SUBSCRIBETOPIC`, and `SUBSCRIBEQOS`. The broker only evaluates lifecycle hooks when at least one action defines them. See [Action Triggers](/latest/lot-language/actions/events#client-lifecycle-triggers).
* **Improved command response handling** — Broker command responses are now consistently structured as JSON. Each command may include a `requestId` field, allowing you to easily correlate requests and responses.
* **Sparkplug B connectors (beta)** — Decode Sparkplug B protobuf into readable JSON, publish Coreflux topics as an edge node, or run Coreflux as the Primary Host Application with namespace state, commands, and automatic rebirth requests. See the [Sparkplug B Connector](/latest/lot-language/routes/system/sparkplug-b) and [Sparkplug Host Connector](/latest/lot-language/routes/system/sparkplug-host) guides.

#### Performance

* **MQTT between clients** — More messages complete per second, the slowest publishes finish sooner (about 10% lower p99 latency). Messages that update connector topics stay in the order they arrived.
* **LoT rules and actions** — Permission checks, topic triggers, timers, and dashboard invokes no longer slow down as more distinct topics exist on the broker. LoT-heavy traffic that was about **10× slower at 30,000 topics** — and about **70× slower at 100,000** — now stays as fast as it was on a nearly empty broker. `USER HAS` and `USER IN GROUP` checks stay fast as the user list grows.
* **Connector mappings** — Adding mappings no longer makes every publish more expensive, including on topics that no mapping uses. Exact-topic mappings (the common case) keep up with tens of thousands of messages per second at **sub-millisecond** latency with **no loss** — the same flood previously took around **25 seconds** and dropped some messages. Wildcard mappings (`+` / `#`) now deliver fully as well. When a connector cannot keep up, memory stays bounded: the broker waits, then drops the **newest** arriving message rather than older ones already in flight. Set `ADD ROUTE_CONFIG` on a connector (`OVERLOAD_POLICY`, `OVERLOAD_TIMEOUT`, `OVERLOAD_CAPACITY`) when that connector needs a different wait-or-drop contract. See [Store and Forward Configuration](/latest/lot-language/routes/store-and-forward).

#### Bug fixes

* **Rules with `IF` and no `ELSE` now compile** — `IF USER IS "dashboard" THEN DENY` (no `ELSE`) previously failed compilation on first evaluation and was treated as a deny for every matching publish or subscribe. The missing branch is now the opposite of the `THEN` decision. See [Rules Syntax](/latest/lot-language/rules/syntax#combining-conditions).
* **Python scripts no longer lose their code on restart** — Scripts that contained blank lines were truncated down to the `# Script Name:` header after a reboot, so `CALL PYTHON` failed even though the script still appeared in listings. Complete scripts now persist across restarts. See [Python Integration](/latest/lot-language/actions/python-integration#writing-python-scripts).
* **Built-in rules survive project add/load/unload** — Adding or switching a project no longer wipes the broker's default permission rules, so internal clients keep `$SYS` access. See [RBAC](/latest/lot-language/rules/rbac#seed-catch-alls).

**2.2**

July 2026

### 2.2.0 - Kafka, OPC UA Server & Modbus Server routes

* **Kafka route** — Connect Coreflux directly to Kafka as a producer or consumer, with support for security protocols and configurable batching and compression. See the [Kafka Route guide](/latest/lot-language/routes/streaming/kafka).
* **OPC UA Server route** — Expose Coreflux data to OPC UA clients with a secure-by-default setup, including support for array and struct nodes. See the [OPC UA Server Route guide](/latest/lot-language/routes/industrial/opcua-server).
* **Modbus Server route** — Serve Modbus data over TCP, with experimental support for Serial (RTU) connections. See the [Modbus TCP Server Route guide](/latest/lot-language/routes/industrial/modbus-tcp-server).
* **OT route persistence** — Server routes (OPC UA Server, Modbus Server) persist their state and recover automatically after a restart, so data isn't lost on reconnect. See [OPC UA Server persistence](/latest/lot-language/routes/industrial/opcua-server#data-persistence--recovery) and [Modbus Server persistence](/latest/lot-language/routes/industrial/modbus-tcp-server#data-persistence--recovery).
* **OPC UA client certificate authentication** — Authenticate OPC UA client connections using PKI certificates for more secure deployments.
* **Modbus one-based addressing** — Set `WITH ONE_BASED_ADDRESSES true` on Modbus client and server routes so tag addresses match device manuals that label registers starting at 1. See [Modbus addressing](/latest/lot-language/routes/industrial/modbus-tcp-client#modbus-addressing) (client) and [Address notation](/latest/lot-language/routes/industrial/modbus-tcp-server#address-notation) (server).
* **Publish payload as bytes** — Forward or retain binary MQTT payloads bit-for-bit with `PAYLOAD AS BYTES` on `PUBLISH TOPIC` and `KEEP TOPIC`. See [ACTION Operations](/latest/lot-language/actions/operations#binary-passthrough--payload-as-bytes).
* **EtherNet/IP route** — Joined attribute reads (`ENABLE_JOIN_ATTRIBUTE`), bit extraction (`BIT_ADDRESS`), ARRAY/STRUCT decoding from assembly buffers, bidirectional `WRITABLE` tags, and legacy Hub Asset field mapping for migrations. See the [EtherNet/IP Route guide](/latest/lot-language/routes/industrial/ethernetip).
* **Allen-Bradley route** — Symbolic tag-name access (`Program:MainProgram.Tag` format), `AB`/`ALLENBRADLEY` route aliases, `PATH` vs `SLOT` routing, family-specific STRING/TIME encoding, and cross-link to EtherNet/IP for explicit CIP paths. See the [Allen-Bradley Route guide](/latest/lot-language/routes/industrial/allen-bradley).
* **Bug fixes** — Fixed BACnet alarm retention, EtherNet/IP connection parameters and legacy-style compatibility, a Modbus TCP word-order issue, an OPC UA client connection issue, and a licensing load-order.

**2.1**

June 2026

### 2.1.0 - BACnet route (building automation) and Protobuf models

* **BACnet route** — Connect Coreflux to building automation systems (HVAC, lighting, metering) and bridge them to MQTT
  * Read live values and write setpoints to BACnet controllers
  * Get instant updates on change, without constant polling
  * Receive alarms and event notifications directly in MQTT

See the [BACnet Route guide](/v2.1/lot-language/routes/industrial/bacnet) to get started.

* **Protobuf LoT models (beta)** — Decode and encode binary protobuf on MQTT from LoT: `WITH FORMAT PROTOBUF` (or `BOTH`), `PROTO_TAG` to match vendor `.proto` field numbers, `ADD MODEL` for nested messages on publish, `GET PROTO` / `GET PROTOBUF` to read top-level fields, and `PUBLISH MODEL` to emit real protobuf bytes (not JSON-in-bytes). `WITH FORMAT BOTH` keeps JSON on the main topic and binary on a `/protobuf` sidecar topic.

See [Protobuf Models](/latest/lot-language/models/protobuf) for more details.

**2.0**

April–June 2026

### 2.0.3 - OT tags & route stability

* **OT tag JSON publish** — Message payload now includes the `unit` field
* **Modbus and EthernetIP routes** — Stability improvements

### 2.0.2 - ON CHANGE trigger and bug fixes

* **`ON CHANGE` trigger for LoT actions** — Run actions only when the message payload on a topic is different from the last message on that same topic. Use it for high-frequency telemetry, historians, and forwarding when you do not need to process duplicate values; `ON TOPIC` still runs on every matching publish.
* **Bug fixes** — Stability and correctness improvements across the broker, LoT, and HUB

### 2.0.0 - AI Agent route in the broker

* **AI Agent route** — Create custom agents usable within LoT for AI-driven steps and logic
* **Cloud and local LLMs** — Support for both on AI features

**1.10**

March 2026

### 1.10.0 - Protobuf & REST API route

Support for environment variables and secrets on LoT

* **Protobuf** support
* **REST API route** with OAuth and JWT support
* **Default project on boot** — Load a default project to a Coreflux broker when the broker starts

**HUB**

**2.12**

September–October 2026

### 2.12.0 - Things, Agents, certificates, fleet sign-in, and Cluster Viewer

This release brings the new broker features into the HUB: build and monitor Things and Agents, manage certificates and licenses without leaving the app, sign in with your Coreflux account, and see your cluster at a glance.

#### Highlights

* **Build and watch Things and Agents in the HUB** — Edit them in the LoT Editor, see how they connect in LoT Flow, and turn an action, connector, or agent off without deleting it. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Renew certificates from the app** — Replace the server certificate, trust or revoke a client, and see what is about to expire, without a restart or a shell. See [Certificates](/hub/system/certificates).
* **Open the brokers in your organization** — Sign in with a Coreflux account and connect to your fleet from the login screen. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Activate and enroll without leaving the HUB** — Paste an activation code or a signed license, or enroll the broker in your organization. See [License](/hub/system/configuration#license).
* **See the cluster from the host you already opened (Beta)** — Members, the leader, which links are up, which node owns each piece of LoT, and the clients on each node. See [Cluster Viewer](/hub/cluster-viewer).
* **Start from a template or a public git repo** — Install a Coreflux template as a project, or copy a public repository into the LoT Editor. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Hear live audio and wait on a button** — Data Viewer plays a raw audio topic. A dashboard button stays busy until the work it started finishes. See [Listening to PCM audio](/hub/mqtt/data-viewer#listening-to-pcm-audio).

#### Things and Agents (preview)

* **Things in the LoT Editor** — Deploy THING cells as one payload, checked first with `-addThing --dryRun`. **Broker runtime → Things** lists roots, instances, and their read-only entities, and **Flow preview** draws the notebook's Things. See [Things in the editor](/hub/lot-editor#things-in-the-editor).
* **Things, Tree, and Flat views in LoT Flow** — Switch views to drill into one level at a time, see the whole containment tree, or see everything flat. Panel cards expand into live previews, and the sidebar adds **Agents** and **Things** groups (collapsed at first). See [Things, Tree, and Flat views](/hub/lot-flow#things-tree-and-flat-views).
* **Agent configuration form** — **Configure** and **Add agent** open a form with **Configuration**, **Tools**, and **LoT** tabs. It rewrites only the clauses you change and keeps the rest as written. See [Configure an agent](/hub/ai-assistant#configure-an-agent).
* **Enable and disable** — Switch an action, connector, or agent off and on from its LoT Editor cell, connector card, or agent card. The HUB adds or removes `DISABLE true` and redeploys. The connector Monitor also has **Start** / **Stop**. Disabled cards are dimmed and marked **Disabled**. See [Disable an entity](/hub/lot-editor#disable-an-entity).

#### Certificates and security

* **Certificates tab** — A new System Config tab shows the server certificate and Root CA and replaces them without a restart. It also sets the trust store path and expiry alert, and uploads, searches, and revokes client certificates. Needs broker 2.22. See [Certificates](/hub/system/certificates).
* **Safer uploads** — The client drop zone accepts `.crt`, `.pem`, `.cer`, `.der`, `.p12`, and `.pfx`, and refuses keys and CSRs. Install a server key with **Replace** on the broker certificate.
* **Status bar indicator** — A certificate count with a red, yellow, or green dot. Hover for details, or click to open the tab filtered to certificates that need attention.

#### Account, fleet, and license

* **Sign in with Coreflux** — The login screen adds a **Coreflux Fleet** tab next to **This machine**. The desktop HUB signs in with no setup; a browser HUB needs `COREFLUX_OIDC_CLIENT_ID`, `HUB_PUBLIC_URL`, and `HUB_SESSION_SECRET`. See [Account, fleet, and Cloud mode](/hub/account-and-fleet).
* **Fleet brokers** — Read-only rows for your organizations' brokers, with status, license, and **Cloud** / **Self-hosted** badges. **Connect** uses your account; portal actions open [portal.coreflux.org](https://portal.coreflux.org).
* **Cloud mode** — Set `HUB_CLOUD_MODE` on a shared regional HUB to accept only `mqtts://` brokers in `HUB_CLOUD_BASE_DOMAIN`. Leave it unset on desktop and self-hosted installs.
* **License tab** — Paste a `CFLX-…` code to activate, or drop a signed `.jws` file bound to the hardware fingerprint. Limits apply without a restart, and **Refresh** renews the lease. The tab doesn't start a trial.
* **Organization enrollment** — Paste an `et_…` token to enroll. The card shows **Enrolled**, **Not enrolled**, or **Enrollment pending** with the broker's reason. See [System Configuration — License](/hub/system/configuration#license).
* **MCP tab** — System Config → **MCP** turns on the broker's MCP listener, limits its tools, and creates or revokes tokens. See [System Configuration — MCP](/hub/system/configuration#mcp).

#### AI Assistant

* **Choose who answers** — Pick the HUB assistant, which calls the broker over MCP and asks before every write, or any `DEFINE AGENT` marked visible in the HUB. Installing on the broker creates a `TYPE LLM` connector and a `DEFINE AGENT`; legacy `TYPE AGENT` connectors are not listed or migrated. See [AI Assistant](/hub/ai-assistant).
* **Ollama works out of the box** — The assistant sizes Ollama's context per run (`HUB_OLLAMA_MIN_CTX` 16k to `HUB_OLLAMA_MAX_CTX` 32k), so the 4k default no longer truncates prompts. A silent model ends with a clear error after `HUB_AGENT_FIRST_OUTPUT_TIMEOUT_MS` or `HUB_AGENT_IDLE_TIMEOUT_MS` (120 s). See [Ollama requirements](/hub/ai-assistant#ollama-requirements).

#### Cluster Viewer (Beta)

* **See your cluster** — A read-only **Cluster** app shows members, the leader, data-plane links, LoT ownership, and partitions. It appears only while the host publishes cluster status. See [Cluster Viewer](/hub/cluster-viewer).
* **Clients tab** — Lists the MQTT clients on each node with user, address, traffic, last activity, queued messages, and session expiry. Filter, sort, and show the cluster's own connections on request. See [Cluster Viewer — Clients](/hub/cluster-viewer#details).

#### LoT Templates

* **Start from a template** — **Help → LoT Templates**, or **From a template…** in the LoT Editor, browses [templates.coreflux.org](https://templates.coreflux.org) and previews a template before installing it as a project. See [Start from a template](/hub/lot-editor#start-from-a-template).
* **Clone from git** — **＋ New → From git…** copies a public git repository into a new LoT Editor project. Cloning copies files only: it does not load or deploy the project. The HUB does not accept private credentials. The clone stops after 30 seconds, the whole repository becomes the project root, and a project download above 64 MB is refused. See [Clone from git](/hub/lot-editor#clone-from-git).

#### Connections

* **Generic MQTT brokers** — On a broker that isn't Coreflux, the dock keeps **Data Viewer** and **UNS Viewer** and hides Coreflux apps. Saved cards are tagged **MQTT** or **Coreflux**. See [When the broker is not Coreflux](/hub/connections#when-the-broker-is-not-coreflux).
* **Default connection** — In the web HUB, `HUB_DEFAULT_CONNECTION_HOST` and optional `HUB_DEFAULT_CONNECTION_*` variables pre-fill **New Connection**. Every browser receives the password, so use shared demo credentials only. See [Default connection (web / Docker)](/hub/connections#default-connection-web-docker).

#### Data Viewer and dashboards

* **Audio topics** — Raw PCM topics, such as an [Audio Input](/latest/lot-language/routes/media/audio-input) stream, show a live waveform you can play, clip, export to WAV, and scrub. See [Data Viewer](/hub/mqtt/data-viewer).
* **Busy buttons and markdown text** — A button with `SET AWAIT` stays busy, and each named component shows a pending indicator until its next message. The wait is 120 seconds unless `SET AWAIT_TIMEOUT` says otherwise, and then the panel shows a timeout note. `SET MARKDOWN true` on a text component renders sanitized markdown: no raw HTML, images, or unsafe links. See [Wait on a button](/latest/lot-language/panels/actions-events#wait-on-a-button).
* **Own window** — **Open in a new window** opens the Data Viewer on the current broker. See [Open the viewer in its own window](/hub/mqtt/data-viewer#open-the-viewer-in-its-own-window).
* **Panels grid** — A toggle in the Panels header switches to a grid of live dashboard thumbnails. The list stays the default. See [Managing Panels](/hub/dashboards/manager#managing-panels).

#### Desktop and settings

* **Desktop shell** — Click the logo to show the desktop. The account pill groups **Broker** administration, **Hub** (Themes and Hub Settings), and **Help**. See [Desktop shell](/hub/overview#desktop-shell).
* **Dock and status bar** — Right-click to set the dock position and auto-hide, and double-click a title bar to zoom. The same controls are in **Hub Settings → Desktop**. See [Dock and status bar](/hub/overview#dock-and-status-bar).
* **Hub Settings** — Memory limits, viewer refresh, and video wallpaper moved from System Config to **Hub Settings**. See [Hub Settings](/hub/overview#hub-settings).
* **Install and update** — Install the browser HUB as an app from `localhost` or HTTPS. The installed desktop app updates itself. See [Updating Your Coreflux](/latest/updating-coreflux#hub-desktop).
* **Walkthroughs** — Short tours on first launch and on each app's first open. Replay or reset them from **Help → Walkthroughs**. See [First-run walkthroughs](/hub/overview#first-run-walkthroughs).

#### Bug fixes

* **Maps show streets again** — Geolocation maps in the Data Viewer use keyless OpenStreetMap tiles, darkened in the dark theme, with the attribution **© OpenStreetMap contributors**. A build can set `VITE_CARTO_BASEMAPS_KEY` to use CARTO Dark Matter, or `VITE_MAP_TILE_URL` and `VITE_MAP_TILE_ATTRIBUTION` for another tile source. See [Tracking what matters](/hub/mqtt/data-viewer#tracking-what-matters).

**2.3**

August–September 2026

> [!WARNING]
>
> **Breaking Changes** in this release:
>
> **HUB is not in the broker image** — `coreflux/coreflux-mqtt-broker` is broker-only. The HUB is `coreflux/coreflux-hub`, always in its own container.
>
> **HUB URL is `http://localhost:3000`** — broker ports `8080` (HTTP) and `8443` (HTTPS) are no longer HUB endpoints. Bookmarks and reverse proxies that pointed at those ports will not reach the HUB.
>
> **Action:** use [Docker Compose](/latest/quick-start/installation) (the default `full` profile starts broker + HUB on one network) or run the HUB image beside the broker. Open `http://localhost:3000`. When both services share the Compose network, click **New Connection** and set **Host** to `broker` (**Protocol** `mqtt://`, **Port** `1883`, or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`) — not `localhost`. See [Installation](/latest/quick-start/installation) and [Updating Your Coreflux](/latest/updating-coreflux).

### 2.3.4 - Login, Deploy, and Data Viewer fixes

#### Bug fixes

* **Non-admin users no longer get bounced back to the login screen** — Signing in as a user without full system access could loop back to login instead of opening the HUB in Limited Mode. The HUB now recognizes a denied `$SYS` subscription for what it is and opens Limited Mode as designed.
* **Deploy project shows accurate status** — Deploying a project via [Connections Manager](/hub/connections) no longer surfaces the broker's success response as a false warning, and the project header no longer gets stuck on **Updating** after the deploy completes.
* **LoT Editor keeps dropped files on the project** — Images and other files dropped into a project (from the Finder, Explorer, or a mixed-OS drag) now stay attached instead of being lost.
* **Data Viewer confirms whether a publish actually landed** — Sending a message no longer shows **Published** when the broker silently rejected it for lacking a publish ACL; Data Viewer now waits for the topic echo before confirming.

### 2.3.0 - LoT Editor, Connections Manager, LoT Flow wiring

#### LoT Editor

* **Visual Studio Code-style editor** — An intuitive notebookeditor with a familiar interface inside the HUB.
* **Unified Projects view** — One Projects list covering every project stored on the broker and every draft held in the HUB. The live project is marked, local-only drafts stay distinct, and each row carries its own sync state: clean, unsaved edits, changed on the broker, or diverged.
* **Push only what changed** — Push stores the working copy and deploys just the drift, instead of redeploying a whole project.
* **Broker Runtime inspector** — A table of what is actually running on the broker, with read-only source for each entity, and a jump from any running entity to the notebook that declares it.
* **Documents alongside notebooks** — Open and store Markdown, text, PDF, and images in a project, import files from disk, and reference them in LoT notebook cells.
* **Copy entities between notebooks** — Copy or drag a declared or deployed entity into another notebook.
* **Version history** Git based version control for project files.
* **Activate and Deactivate projects** from the project tree.

#### Connections Manager

* **More than one broker** — The HUB keeps a named list of broker connections with favorites, replacing the single remembered URL. Each is shown as a card on the login screen.
* **Change Broker** — Switch the whole HUB to another saved connection from the account menu, without logging out and reconfiguring.
* **Per-connection TLS** — Store a CA certificate and a client certificate against an individual connection.
* **Credentials kept off the connection record** — Passwords and client keys live in a separate store; the desktop app encrypts it using the operating system's secure storage, and the browser app never writes them to disk.
* **Live reachability on the login list** — Saved connections are probed so you can see which brokers answer before you pick one.

#### LoT Flow

* **Cleaner connections between nodes** — `KEEP`-topic edges and "matches" edges no longer clutter the canvas, and `MODEL` nodes are drawn as terminals, so the remaining edges show real data flow.
* **Topics grouped by role** — Command and telemetry topics are grouped by the role they play, with disambiguated group labels, prefix hubs backed by a topic-set panel, and wildcard subscriptions expanded to the topics they match.
* **Topic pulse toggle** — Turn live topic activity animation on or off.
* **Export the canvas as an image** — Download the current flow as a PNG.

**2.2**

July 2026

### 2.2.0 - UNS viewer & LoT Flow

* **LoT Flow** — A new interactive view of your LoT data flows, showing entity, topic, and Python nodes alongside live topic values, action traces, and route status.
* **UNS viewer** — Browse your Unified Namespace as a tree, with search, live payload previews, and a graph layout.
* **Data Viewer overhaul** — A refreshed explorer with a detailed topic view, timeline, faster topic indexing, and better subscription management.
* **In-app release notes** — A "What's New" dialog in the HUB so you can see what's changed without leaving the app.
* **Refreshed HUB styling** — Updated visual design and dock layout.
* **AI chat improvements** — A setup wizard, an artifact panel, and a generally expanded chat experience.
* **Expanded dashboard panels** — More display components, gauge options, and model-binding support for building richer dashboards.
* **Bug fixes** — Fixed the LoT compiler and dashboard rendering for `ON KEY PRESS`, `ON THRESHOLD BREACH`, conditional handlers, `WITH THEME`, numeric decimals and suffixes, threshold zones on gauges/charts, and callable actions. Fixed `INVOKE ACTION`, `BIND TO MODEL`, the accordion "Add Section," and tab titles in dashboards. Fixed real-time charts to show both traces with a legend and to correctly distinguish bar vs. line modes. Fixed select/dropdown interactions, topic-to-widget data binding (previously showing a single point instead of the full array), slider and toggle controls publishing incorrect values, icon visibility, multi-panel layouts, and events not being recognized on mount. Fixed the AI agent to properly detect uninstalled routes, and corrected its confirmation prompts. General mobile layout improvements.

**2.0**

April 2026

### 2.0.0 - UI/UX overhaul, standalone installer, AI Agent

![Coreflux HUB Data Viewer showing MQTT topic tree with live data values and real-time charts](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/hub-data-viewer.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=634b8986391a76e82ef3f03574338cb6)

Coreflux HUB Data Viewer with live MQTT topic data and charts

* **UI/UX improvements**
* **Standalone installer** — Windows and Linux
* **AI Agent**
  * **Insights mode** — Ask questions about running data, using project information as context
  * **Agent mode** — Build LoT, routes, and dashboards with an AI copilot

**VS Code Extension**

**1.0**

August–October 2026

These notes are VS Code extension **1.0**. Features that use the broker's new commands need broker **2.22**.

### 1.0.0 - Things, Agents, Validate, MCP, and licensing

This release lets you write Things and Agents in notebooks, check your LoT on the broker before deploying, connect your AI tools to the broker's MCP server, and manage licensing, all from VS Code.

#### Highlights

* **Write Things and Agents where you already write LoT** — Check them against the broker and deploy them from the notebook, the same way as any other cell. See [THING cells](/lot-notebooks/usage#thing-cells).
* **Check before you deploy** — Validate a cell or the whole notebook on the broker. Problems show on the cell, and nothing is deployed until you run it. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Switch a cell off without deleting it** — Disable an action, connector, or agent from the cell status bar, and turn it back on when you want it running. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **Connect your AI tools in one step** — The MCP Server tab writes the broker endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Teach your coding agent LoT** — Install the Coreflux skills so the agent writes valid LoT and works with the broker. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **License and enroll from VS Code** — Activate with a code, install a signed license, or enroll the broker, from the License tab. See [License tab](/lot-notebooks/usage#license-tab).

#### LoT cells

* **Things** — A run sends the cell's `DEFINE THING` blocks and their workspace templates as one `-addThing`, after a `--dryRun` whose problems show on the cell. **Remove Thing from Broker** sends `-removeThing`, and a quick fix updates older THING syntax (`TEMPLATE`, and `{p}` to `{{p}}`). See [THING cells](/lot-notebooks/usage#thing-cells).
* **Agents** — `DEFINE AGENT` cells are checked like the broker checks them and deploy with `-addAgent`. Broker agents appear in the Coreflux Explorer and the Entities panel. See [Agent cells](/lot-notebooks/usage#agent-cells).
* **Validate** — Check a cell or the whole notebook on the broker without deploying it. Results appear under the cell and in Problems. See [Validate without deploying](/lot-notebooks/usage#validate-without-deploying).
* **Enabled / Disabled toggle** — Switch `DISABLE true` on and off for action, connector, and agent cells from the cell status bar, and the change uploads. See [Disable an entity](/lot-notebooks/usage#disable-an-entity).
* **`DEFINE CONNECTOR`** — Recognized in checks, completions, and hovers, with `DEFINE ROUTE` as its alias. Connector cells upload from the cell, and Deploy Project includes them.
* **`RETURN AS` under `CALL`** — A `RETURN AS` line under a `CALL` no longer reports an indentation error.
* **Panels and themes** — `DEFINE PANEL` and `DEFINE VISU` cells, and a Thing's `WITH PANEL` body, are checked with the broker's panel parser. Highlighting, hover, completions, and a `DEFINE PANEL` snippet are included. Running the cell sends `-addVisu`; removing it sends `-removeVisu`. `DEFINE THEME` and `THEME_VARIANT` are recognized. The cell status bar offers **Open in Coreflux HUB** to view the rendered panel, and a successful upload suggests opening Dashboards there. See [Panel cells](/lot-notebooks/usage#panel-cells).
* **Agent and Thing checks match the broker** — Valid agent, thing, rule, connector, and model syntax is no longer flagged, including connector keys such as `SUBJECT` and mixed-case names. See [Agent cells](/lot-notebooks/usage#agent-cells).

#### Broker management

* **License tab** — Activate with a `CFLX-…` code, install signed license text, enroll with an `et_…` token, and refresh the lease. The Instance Key field is gone. See [License tab](/lot-notebooks/usage#license-tab).
* **MCP Server tab** — Turn on the broker's MCP server, pick its tools, and manage tokens. **Install MCP server** writes the endpoint and a new token into Cursor, VS Code, Claude Code, or Claude Desktop, and keeps workspace config files out of Git. See [MCP Server tab](/lot-notebooks/usage#mcp-server-tab).
* **Install Agent Skills** — **Install Agent Skills...** lets you pick which of the 11 bundled skills to install and where (the `.agents`, `.claude`, `.cursor`, or `.github` skills folder, in the workspace or your home folder). Skills come from the public [coreflux-skills](/ai/agent-skills) repository (broker 2.22 or later), and older copies from previous versions are offered for removal. See [Develop LoT Notebooks with AI](/lot-notebooks/usage#develop-lot-notebooks-with-ai).
* **Remove All Things / Templates** — Two new commands clear every Thing or every template from the broker.
* **Variables** — "Environment Vars" is now "Variables" everywhere, including **Secrets & Variables**.

#### Data Viewer and workspace

* **Bounded history** — Each topic keeps its last 100 messages by default (`coreflux.dataViewer.historyBufferPerTopic`, 50 to 2000), set from the timeline gear. The timeline draws again, and pausing or scrubbing stays steady while messages arrive. See [Adjust how you see the data](/lot-notebooks/debug#adjust-how-you-see-the-data).
* **Apps in the editor area** — Data Viewer, Logs Viewer, and Secrets & Variables open as tabs next to your notebooks.
* **Connection Manager** — Save several broker connections and switch between them.
* **Entities table** — See the LoT entities running on the broker in their own table.
* **LoT projects** — Create, edit, and deploy LoT projects.

**beta**

April 2026

![Screen recording of creating and deploying LoT in the Coreflux VS Code extension](https://mintcdn.com/coreflux/XSOUAWqOWS4Y2_FQ/images/extension/extension-create-and-deploy-lot.gif?s=5cd139e03cbf0b5109848b498d7c65eb)

Create and deploy LoT from the Coreflux VS Code extension

* **Improved VS Code extension (beta)**
  * License usage
  * Live MQTT data (topic tree)
  * **Data Viewer** — View and replay historical and live data for MQTT topics, with viewers for raw, JSON, PDF, GeoJSON (map), audio, and more
  * **Execution trace** — View and replay historical and live data from LoT execution, including success and error states, published topics, and internal variables
  * Manage secrets and environment variables