> For the complete documentation index, see [llms.txt](https://docs.enlyze.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enlyze.com/integrations/grafana/advanced-api/03-variables.md).

# 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="/files/pnAuXOJsrmzrMMxE8OKc" 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](/integrations/grafana/advanced-api/01-introduction.md) und [API abfragen](/integrations/grafana/advanced-api/02-api-queries.md) 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="/files/n50yBtAyCLq4V4LjPy53" 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="/files/CTLxxXpAaFpx0EaV6dDB" 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="/files/UV5g60EfOoWNfl5Cw3vz" 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**](/integrations/grafana/advanced-api/03b-advanced-variables.md) — Multi-Select, Repeat-Panels und versteckte Variablen für OEE pro Maschine


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enlyze.com/integrations/grafana/advanced-api/03-variables.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.