# 03 Mit Variablen arbeiten

In diesem Tutorial erstellst du Dropdown-Variablen für Standort und Maschine und setzt sie in Queries, Filtern und Panel-Titeln ein:

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-21ed7897e7f44dbb3e71bcadac861ace5eeeea5a%2Fgrafana-var-hero-01.png?alt=media" alt=""><figcaption></figcaption></figure>

## Was du lernst

* Was Dashboard-Variablen sind und wann du sie brauchst
* Standort-Dropdown aus der ENLYZE API erstellen
* Verkettetes Maschinen-Dropdown mit API-Filter
* Variablen in URLs, Query-Parametern und Panel-Titeln einsetzen
* Debug-Technik: Variablenwerte als Tabelle anzeigen
* Variablen-Syntax (`${var}`, `${var:text}`, `${var:csv}`)

## Voraussetzungen

* [Einführung in die ENLYZE API](https://docs.enlyze.com/integrations/grafana/advanced-api/01-introduction) und [API abfragen](https://docs.enlyze.com/integrations/grafana/advanced-api/02-api-queries) abgeschlossen
* Verständnis von GET-Anfragen, Root Selectors und JSONata

***

## Was sind Dashboard-Variablen?

Variablen sind Platzhalter, die zur Laufzeit durch einen konkreten Wert ersetzt werden. Statt eine Maschinen-UUID fest in jede Query zu schreiben, verwendest du `${machine}`. Wechselst du die Maschine im Dropdown, aktualisieren sich alle Panels automatisch.

Variablen lassen sich einsetzen in:

* **URL-Pfaden**: `machines/${machine}`
* **Query-Parametern**: `machine=${machine}`
* **Root Selectors**: JSONata-Filter mit `${site}`
* **Panel-Titeln**: `Machines at ${site:text}`

***

## Standort-Variable erstellen

1. Erstelle ein neues Dashboard und öffne **Dashboard Settings** (Zahnrad oben rechts)
2. Wechsle zum Tab **Variables** und klicke **+ New variable**
3. Konfiguriere die Variable:

| Einstellung   | Wert              |
| ------------- | ----------------- |
| Variable type | Query             |
| Name          | `site`            |
| Label         | Site              |
| Data source   | ENLYZE API        |
| Query type    | Infinity          |
| Type          | JSON              |
| Parser        | JSONata (Backend) |
| Source        | URL               |
| Method        | GET               |
| URL           | `sites`           |
| Root selector | `$.data`          |

4. Klappe **Parsing options & Result fields** auf und füge unter **Columns** hinzu:

| Selector | Title (as) | Type (format as) |
| -------- | ---------- | ---------------- |
| `name`   | Name       | String           |
| `uuid`   | UUID       | String           |

Die erste Spalte wird zum Anzeigenamen im Dropdown, die zweite zum gespeicherten Wert (UUID).

5. Stelle unter **Selection options** ein:
   * **Sort**: Alphabetical (asc)
   * **Refresh**: On dashboard load
6. Klicke **Apply** und dann **Save dashboard**

Zurück auf dem Dashboard siehst du oben ein **Site**-Dropdown mit den verfügbaren Standorten.

***

## Verkettetes Dropdown: Maschine nach Standort

Das Maschinen-Dropdown soll nur Maschinen des gewählten Standorts anzeigen. Dafür übergibst du die `site`-Variable als Query-Parameter an die API.

1. Öffne erneut **Dashboard Settings** > **Variables** > **+ New variable**
2. Konfiguriere die Variable:

| Einstellung   | Wert       |
| ------------- | ---------- |
| Variable type | Query      |
| Name          | `machine`  |
| Label         | Machine    |
| URL           | `machines` |
| Root selector | `$.data`   |

3. Füge unter **URL Query Params** hinzu:

| Key    | Value     |
| ------ | --------- |
| `site` | `${site}` |

4. Columns wie bei `site`: `name` (Name), `uuid` (UUID)
5. Sort: **Alphabetical (asc)**, Refresh: **On dashboard load**

Die API filtert serverseitig und liefert nur Maschinen des gewählten Standorts zurück. Wechselst du den Standort, aktualisiert sich die Maschinenliste automatisch.

{% hint style="info" %}
Die Reihenfolge der Variablen ist wichtig: `machine` hängt von `site` ab. Grafana wertet Variablen in der Reihenfolge aus, in der sie definiert sind. `site` muss vor `machine` stehen.
{% endhint %}

***

## Variablen in Panels einsetzen

Erstelle Panels, die die Variablen nutzen. Hier drei typische Muster:

### URL-Pfad: Ausgewählte Site anzeigen

Erstelle ein **Stat**-Panel mit der Query:

| Einstellung   | Wert            |
| ------------- | --------------- |
| URL           | `sites/${site}` |
| Root selector | (leer)          |

Unter **Stat** > **Value options** setze **Fields** auf `/^name$/`. Das Panel zeigt den Namen des gewählten Standorts.

### JSONata-Filter im Root Selector

Nicht jede API unterstützt serverseitiges Filtern. In solchen Fällen kannst du die Antwort client-seitig mit JSONata filtern. Erstelle ein **Table**-Panel, das alle Maschinen lädt und im Root Selector nach Standort filtert:

| Einstellung   | Wert                                                   |
| ------------- | ------------------------------------------------------ |
| URL           | `machines`                                             |
| Root selector | `$filter($.data, function($v){ $v.site = "${site}" })` |

Füge Columns hinzu: `name` (Machine Name), `uuid` (UUID), `genesis_date` (Connected Since).

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-bf9aa14ae2c7e3123ca229637cb43be9d055d8b3%2Fgrafana-var-machine-filter-01.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Wenn die API einen passenden Filter-Parameter anbietet (wie `site` beim `machines`-Endpunkt), nutze diesen statt JSONata. Das ist effizienter, weil weniger Daten übertragen werden. JSONata-Filter im Root Selector sind dann nützlich, wenn kein serverseitiger Filter verfügbar ist.
{% endhint %}

### Query-Parameter: Produktionsdaten

Erstelle ein **Table**-Panel für Aufträge:

| Einstellung   | Wert              |
| ------------- | ----------------- |
| URL           | `production-runs` |
| Root selector | `$.data`          |

Füge unter **URL Query Params** hinzu:

| Key       | Value                |
| --------- | -------------------- |
| `machine` | `${machine}`         |
| `start`   | `${__from:date:iso}` |
| `end`     | `${__to:date:iso}`   |

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-e022984123148a6c02fcc320d8754f6a199f9530%2Fgrafana-var-production-data-01.png?alt=media" alt=""><figcaption></figcaption></figure>

### Panel-Titel mit Variablen

Du kannst Variablen auch im Panel-Titel verwenden. Setze den Titel auf `Machines at ${site:text}`. Der Platzhalter `${site:text}` wird durch den Anzeigenamen (z.B. "Köln") ersetzt, nicht durch die UUID.

***

## Debug-Tipp: Variablenwerte anzeigen

Im Dropdown siehst du den Anzeigenamen, aber die Query verwendet die UUID. Um beide Werte nebeneinander zu sehen, erstelle ein **Table**-Panel mit Inline-Daten:

1. Erstelle ein neues Panel mit Visualisierung **Table**
2. Wähle als Source **Inline** statt URL
3. Gib folgendes JSON ein:

```json
[
  {"Variable": "site", "UUID": "${site}", "Name": "${site:text}"},
  {"Variable": "machine", "UUID": "${machine}", "Name": "${machine:text}"}
]
```

<figure><img src="https://3556205377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fn6Jn6Re8NNPSKD1jGZyL%2Fuploads%2Fgit-blob-e267b471f43c97de3a593b38876d9f49f867a782%2Fgrafana-var-debug-table-01.png?alt=media" alt=""><figcaption></figcaption></figure>

Die Tabelle zeigt dir genau, welche Werte Grafana einsetzt. Das ist besonders hilfreich, wenn eine Query nicht funktioniert und du prüfen willst, ob die richtige UUID übergeben wird.

***

## Variablen-Syntax

| Syntax        | Ergebnis                       | Beispiel            |
| ------------- | ------------------------------ | ------------------- |
| `${var}`      | Wert (UUID)                    | `a5eae328-d880-...` |
| `${var:text}` | Anzeigename                    | `Köln`              |
| `${var:csv}`  | Komma-separiert (Multi-Select) | `uuid1,uuid2`       |
| `${var:json}` | JSON-Array (Multi-Select)      | `["uuid1","uuid2"]` |
| `${var:pipe}` | Pipe-separiert (Multi-Select)  | `uuid1\|uuid2`      |

Die Formate `:csv`, `:json` und `:pipe` sind besonders bei Multi-Select-Variablen relevant. Diese lernst du im nächsten Tutorial.

***

## Tipps

* **Variablen benennen**: Verwende kurze, beschreibende Namen wie `site`, `machine`, `product`. Vermeide Leerzeichen und Sonderzeichen.
* **Refresh-Strategie**: Verwende "On dashboard load" für Variablen, die sich selten ändern (Standorte, Maschinen). Verwende "On time range change" für zeitabhängige Werte.
* **Reihenfolge = Abhängigkeit**: Variablen werden in der definierten Reihenfolge ausgewertet. Abhängige Variablen müssen nach ihren Abhängigkeiten stehen.
* **Debug zuerst**: Wenn eine Query nicht das erwartete Ergebnis zeigt, prüfe zuerst die Variablenwerte mit der Debug-Tabelle.

***

## Nächste Schritte

* [**Fortgeschrittene Variablen**](https://docs.enlyze.com/integrations/grafana/advanced-api/03b-advanced-variables) — Multi-Select, Repeat-Panels und versteckte Variablen für OEE pro Maschine