Liquid Templating

Liquid ist eine Templatesprache die in 42°OS überall dort eingesetzt wird, wo du Texte dynamisch mit Werten aus der aktuellen Nachricht befüllen willst — in SQL-Statements des Internal Storage Agents, in Message Formatting Agents, in E-Mail-Texten und an vielen weiteren Stellen.

Das Grundprinzip: du schreibst einen Text mit Platzhaltern, und Liquid setzt beim Ausführen die echten Werte ein.

Grundsyntax

Werte ausgeben: `{{ }}`

Doppelte geschweifte Klammern geben den Wert einer Variable aus:

Guten Morgen, {{ name }}!

Wenn die Nachricht {"name": "Jonas"} enthält, ergibt das:

Guten Morgen, Jonas!

Verschachtelte Objekte werden mit Punkt navigiert:

{{ supplier.name }}
{{ supplier.address.city }}

Array-Elemente mit Index (beginnt bei 0):

{{ positions[0].bezeichnung }}

Logik: `{% %}`

Geschweifte Klammern mit Prozentzeichen enthalten Logik — Bedingungen, Schleifen, Zuweisungen. Sie geben keinen Text aus.

Bedingungen

{% if amount > 1000 %}
Großauftrag — bitte Freigabe einholen.
{% elsif amount > 500 %}
Standardauftrag.
{% else %}
Kleinauftrag.
{% endif %}

Vergleichsoperatoren: ==, !=, >, <, >=, <=

Logische Operatoren: and, or

{% if level == "ERROR" or level == "CRITICAL" %}
⚠️ Kritischer Eintrag: {{ info }}
{% endif %}

Prüfen ob ein Wert vorhanden ist:

{% if customer_number != null and customer_number != "" %}
Kundennummer: {{ customer_number }}
{% endif %}

Schleifen

{% for position in positions %}
- {{ position.bezeichnung }}: {{ position.betrag }} €
{% endfor %}

Wenn positions ein Array ist, wird der Block für jedes Element wiederholt. Mit forloop-Hilfsvariablen:

{% for entry in log_entries %}
{% if forloop.first %}### Log-Einträge{% endif %}
{{ forloop.index }}. {{ entry.level }} — {{ entry.info }}
{% endfor %}

Variable	Bedeutung
`forloop.index`	Aktueller Index, beginnt bei 1
`forloop.index0`	Aktueller Index, beginnt bei 0
`forloop.first`	`true` beim ersten Durchlauf
`forloop.last`	`true` beim letzten Durchlauf
`forloop.length`	Gesamtanzahl der Elemente

Filter

Filter verändern einen Wert bei der Ausgabe. Sie werden mit | angehängt:

{{ name | upcase }}              → JONAS
{{ name | downcase }}            → jonas
{{ name | capitalize }}          → Jonas
{{ amount | round: 2 }}          → 1190.00
{{ invoice_date | date: "%d.%m.%Y" }}   → 10.03.2026
{{ text | strip }}               → Leerzeichen am Anfang/Ende entfernen
{{ text | replace: "GmbH", "GmbH & Co. KG" }}
{{ array | size }}               → Anzahl der Elemente
{{ array | first }}              → erstes Element
{{ array | last }}               → letztes Element
{{ array | join: ", " }}         → Elemente mit Komma verbinden

Variablen zuweisen

{% assign total = 0 %}
{% for position in positions %}
  {% assign total = total | plus: position.betrag %}
{% endfor %}
Gesamtbetrag: {{ total }} €

Credentials einbinden

Credentials sind account-spezifische Werte die in 42°OS zentral hinterlegt werden — vergleichbar mit globalen Variablen. Sie werden über einen speziellen Liquid-Befehl abgerufen:

{% credential Credential-Name %}

Dieser Befehl gibt den gespeicherten Wert des Credentials mit dem angegebenen Namen aus. Der Wert selbst ist verschlüsselt gespeichert und erscheint nie im Klartext in der Agent-Konfiguration.

Wofür werden Credentials genutzt?

1. Vordefinierte Strukturen für Agents

Manche Agents erwarten Credentials in einem bestimmten JSON-Format. Der SMB File Manager Agent benötigt z. B. Server, Share-Name, Benutzername und Passwort als strukturiertes JSON-Objekt (→ siehe SMB Share korrekt verbinden). Für E-Mail-Agents gelten ähnliche Vorgaben. In diesen Fällen konfigurierst du den Credential-Namen direkt in den Agent-Optionen — Liquid ist hier nicht nötig.

2. Eigene globale Variablen

Du kannst Credentials aber auch frei nutzen, um beliebige Werte zentral zu verwalten und per Liquid in Agents einzusetzen. Ein typisches Beispiel: ein Bearer-Token für die Authentifizierung bei REST API-Aufrufen:

Authorization: Bearer {% credential api_bearer_token %}

Oder ein API Key in einem Post Agent:

{
  "headers": {
    "X-API-Key": "{% credential mein_api_key %}"
  }
}

Weitere Beispiele für die Nutzung von Credentials in REST-API-Anfragen findest du in der Lerneinheit REST APIs ansprechen.

Credentials automatisch aktualisieren: der Credentials Agent

Manche Werte ändern sich regelmäßig — z. B. OAuth-Tokens mit begrenzter Gültigkeit. Statt sie manuell zu erneuern, kannst du einen separaten Workflow einrichten, der das Token periodisch neu abruft und in die Credentials schreibt.

Dafür steht der Credentials Agent zur Verfügung. Er speichert einen Wert aus einer eingehenden Nachricht in den Credentials des Benutzers:

Option	Typ	Beschreibung	Standard
`credential_name`	String	Name des anzulegenden oder zu aktualisierenden Credentials	`token`
`value_path`	String	JsonPath-/Liquid-Ausdruck zum Wert in der Payload	`token`

Der Agent schreibt bzw. aktualisiert genau einen Credential-Eintrag pro Nachricht. Er erzeugt keine eigenen Nachrichten und löst keine Workflows aus — er ist daher gefahrlos in bestehende Workflows integrierbar.

Beispiel: automatische Token-Rotation

Schedule Agent  (z. B. alle 55 Minuten)
      ↓
Post Agent  (Token-Endpoint der API aufrufen)
      ↓
Credentials Agent  (credential_name: "api_bearer_token", value_path: "access_token")

Der Schedule Agent triggert den Workflow regelmäßig, der Post Agent holt ein neues Token vom OAuth-Endpoint, und der Credentials Agent schreibt den erhaltenen Wert unter dem Namen api_bearer_token in die Credentials. Alle nachfolgenden Workflows die {% credential api_bearer_token %} verwenden, nutzen automatisch das aktuelle Token.

Praxisbeispiele in 42°OS

SQL-Statement mit Liquid (Internal Storage Agent)

INSERT INTO logs (log_entry_id, log_date, log_time, level, source, info, reported_state, created_at)
VALUES (
  '{{ log_date }}-{{ log_time }}-{{ source }}',
  '{{ log_date }}',
  '{{ log_time }}',
  '{{ level }}',
  '{{ source }}',
  '{{ info }}',
  'unreported',
  datetime('now')
)

Markdown-Tabelle aus Array (Message Formatting Agent)

| Level | Quelle | Info | Anzahl |
|---|---|---|---|
{% for entry in log_entries %}
| {{ entry.level }} | {{ entry.source }} | {{ entry.info }} | {{ entry.anzahl }} |
{% endfor %}

E-Mail mit Bedingung

Betreff: {% if level == "ERROR" %}⚠️ Fehler{% else %}Info{% endif %} — {{ source }}

Hallo,

im Schichtbericht vom {{ report_date }} wurde folgender Eintrag erfasst:

**Level:** {{ level }}
**Quelle:** {{ source }}
**Beschreibung:** {{ info }}
**Erstes Auftreten:** {{ erstes_auftreten }}
**Anzahl:** {{ anzahl }}

{% if anzahl > 10 %}
⚠️ Dieser Fehler tritt häufig auf. Bitte prüfen.
{% endif %}

Häufige Fehler

Variable existiert nicht — wenn ein Schlüssel in der Nachricht fehlt, gibt {{ schluessel }} einen leeren String zurück (kein Fehler, aber leise). Mit {% if schluessel != null %} absichern wenn der Wert zwingend gebraucht wird.

Array vs. einzelner Wert — {% for x in y %} funktioniert nur wenn y ein Array ist. Wenn y ein einzelnes Objekt ist, gibt es einen Fehler oder keine Ausgabe.

Zahlen als Strings — {{ amount | plus: 100 }} funktioniert nur wenn amount eine Number ist. Strings müssen erst mit | plus: 0 in Zahlen umgewandelt werden.

Weiterführend

Die vollständige Liquid-Dokumentation mit allen Filtern und Tags: shopify.github.io/liquid — 42°OS nutzt den Liquid-Standard, alle dort dokumentierten Funktionen funktionieren auch hier.

Grundsyntax​

Werte ausgeben: {{ }}​

Logik: {% %}​

Bedingungen​

Schleifen​

Filter​

Variablen zuweisen​

Credentials einbinden​

Wofür werden Credentials genutzt?​

Credentials automatisch aktualisieren: der Credentials Agent​

Praxisbeispiele in 42°OS​

SQL-Statement mit Liquid (Internal Storage Agent)​

Markdown-Tabelle aus Array (Message Formatting Agent)​

E-Mail mit Bedingung​

Häufige Fehler​

Weiterführend​