# CRM/NMS Integrations

## Page Purpose

Use this page to choose and configure supported CRM/NMS integrations. Use per-integration pages for specific setup details.

Need definitions for overwrite/persistence terms? See the [Glossary](glossary.md).

Most operators use built-in integrations.
If you have not selected a deployment path yet, start with [Quickstart](quickstart.md).

```{mermaid}
flowchart LR
    A[CRM/NMS] --> B[LibreQoS Integration Job]
    B --> C[ShapedDevices.csv]
    B --> D[network.json]
    C --> E[lqos_scheduler]
    D --> E
    E --> F[Shaping Updates]
    E --> G[WebUI Status / Urgent Issues]
```

## Choose Your Integration Path

| Path | Best fit | Primary source of truth |
|---|---|---|
| Built-in integration | Most operators using supported systems | CRM/NMS via LibreQoS integration jobs |
| Custom source of truth | Operators with in-house CRM/NMS sync logic | External generated files (`network.json`, `ShapedDevices.csv`) |

## Where in WebUI

- Integration defaults/common behavior: `Configuration -> Integrations`
- Per-integration configuration fields: `Configuration -> Integrations`
- Operational health checks after sync changes: `WebUI -> Scheduler Status` and `WebUI -> Urgent Issues`
- Topology/result validation: `WebUI -> Network Tree Overview` and `Flow Globe`

## Built-In Integrations

- [Splynx Integration](integrations-splynx.md)
- [UISP Integration](integrations-uisp.md)
- [Netzur Integration](integrations-netzur.md)
- [VISP Integration](integrations-visp.md)
- [WISPGate Integration](integrations-wispgate.md)
- [Powercode Integration](integrations-powercode.md)
- [Sonar Integration](integrations-sonar.md)

## Important Overwrite Behavior

When integrations are enabled:
- `ShapedDevices.csv` is typically regenerated by integration sync jobs.
- `network.json` may also be overwritten depending on integration settings (for example `always_overwrite_network_json`).
- Manual edits may be overwritten on the next refresh cycle.

## Topology Node ID Support

LibreQoS supports an optional generic `"id"` field on `network.json` nodes. This field is intended to carry stable node identifiers from the integration source where possible.

Current behavior:
- node IDs are the preferred match key for operator-owned site bandwidth overrides and tree-page node override editing when an ID is present
- legacy name-only matching is still supported as a fallback for older data
- topology names still need to remain globally unique in `network.json`

| Integration | `network.json` node ID support | Notes |
|---|---|---|
| UISP | Yes | Real UISP sites/devices export generic `id` plus existing `uisp_site` / `uisp_device` metadata. Synthetic LibreQoS nodes use stable generated IDs. |
| Splynx | Yes | Network sites and AP/site topology nodes export generic `id`. |
| Sonar | Yes | Site and AP topology nodes export generic `id`. |
| Netzur | Partial | Exported only when the upstream zone payload includes a stable zone ID. |
| VISP | No | Current importer shapes services/devices but does not build topology nodes in `network.json`. |
| Powercode | No | Current importer does not build topology nodes in `network.json`. |
| WISPGate | No | Current importer does not build topology nodes from stable upstream topology identifiers. |

## Common Client Rate Handling

For built-in integrations that import raw subscriber plan speeds, LibreQoS applies the same shared client-rate rule before writing `ShapedDevices.csv`:

- effective client max rate = `max(plan_rate * bandwidth_overhead_factor, plan_rate * client_bandwidth_multiplier)`

Integrations that already ingest effective shaped rates keep those values as-is rather than applying the multiplier a second time.

## Related Pages

- [Quickstart](quickstart.md)
- [Operating Modes and Source of Truth](operating-modes.md)
- [Configure LibreQoS](configuration.md)
- [Scale Planning and Topology Design](scale-topology.md)
- [Troubleshooting](troubleshooting.md)