Berichte-Referenz

Der Bereich „Berichte" erstellt eigene PDF-Berichte aus einer Bibliothek von Widgets. Diese Seite dokumentiert die Verhaltensweisen, Berechtigungen, das Layout-Raster und den Widget-Katalog, die das Schema allein nicht ausdrücken kann.

Die vollständige, stets aktuelle Liste der Endpoints, Parameter und Antwortfelder für die Version, die du betreibst, findest du in der interaktiven OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html.

Für eine durchgängige Anleitung zum Erstellen einer Vorlage und zum Erzeugen eines PDFs siehe Berichtsvorlage erstellen.

REST-Endpunkte

Alle Berichts-Endpunkte liegen unter /api/reports/. Die Spalte Hinweise nennt die benötigte Berechtigung (octoja nutzt eigene Berechtigungs-Policies, die nicht alle in Swagger abgebildet sind) sowie das nicht offensichtliche Verhalten.

Wichtige Verhaltensweisen

• Klonen beim Erstellen: cloneFromTemplateId muss, wenn angegeben, eine GUID-formatierte Zeichenkette sein; die neue Vorlage ist eine tiefe Kopie der rows + widgets der Quelle.
• UpdateValue-Wrapper: der Update-Body kapselt jedes Feld, z. B. { name?: { hasValue: true, value }, rows?: { hasValue: true, value }, orientation?: { hasValue: true, value } }. Die Aktualisierung ist partiell — Felder, die im Body weggelassen werden (oder ohne hasValue: true gesendet werden), bleiben in der gespeicherten Vorlage unverändert und werden nicht gelöscht.
• Erzeugungs-Zeitraum: die optionalen rangeStart / rangeEnd (ISO-Daten) beschränken zeitfensterbezogene Widgets auf einen Berichtszeitraum — gib beide oder keinen an; lass sie weg für einen Gesamtbericht.

Schema und Felder

Die vollständige Feldliste und die Typen für ReportTemplate, ReportRow und ReportWidget findest du in Swagger. Die folgenden Felder tragen Verhalten, das das Schema nicht vermitteln kann.

• name — bei eingebauten Vorlagen ist dies ein i18n-Schlüssel (z. B. pages.reports.builtIns.executiveSnapshot.name), bei Anzeige lokalisiert; bei eigenen Vorlagen ist es die wörtliche Benutzereingabe.
• isBuiltIn — nur Antwort / abgeleitet. Wird serverseitig aus einer Allowlist eingebauter IDs berechnet und nicht auf der Entität gespeichert; true für Vorlagen, die mit octoja ausgeliefert werden, false für mandanteneigene Vorlagen.
• slug — Basis für den PDF-Download-Dateinamen. Nur eingebaut — executive-snapshot erzeugt executive-snapshot-2026-04-20.pdf; eigene Vorlagen fallen auf einen slugifizierten name zurück (Standard null).
• iconName — Lucide-Icon-Komponentenname auf der Vorlagenkarte. Nur eingebaut (Standard null).
• orientation — Portrait (Standard) oder Landscape. Landscape passt breite Tabellen wie das Hardware-Inventar; ein ungültiger Wert liefert 400 Bad Request.
• columnSpan (Widget) — Anzahl belegter Raster-Spalten (Standard 1). Pro Widget begrenzt; jeder Widget-Typ deklariert seinen eigenen minColumnSpan, maxColumnSpan und defaultColumnSpan, die der Editor durchsetzt.
• rowSpan (Widget) — Höhe in Editor-Zeilen; 0 (Standard) bedeutet „Standardhöhe des Widgets verwenden".
• config (Widget) — widget-spezifische Einstellungen, deren Form vom Widget-type abhängt; die verfügbaren Optionen findest du im Eigenschaften-Panel des Editors.
• backgroundColor (Widget) — einer aus einem festen Satz von Färbungen (Indigo, Emerald, Amber, Sky, Rose, Slate); die Hinweisbox verwendet denselben Satz.
• autoStatusColor (Widget) — bei true färben sich datengetriebene Widgets (KPI-Karten, Tachos) selbst nach Schweregrad des Wertes ein (grün OK, orange Warnung, rot Kritisch). Hat keine Wirkung auf Widgets, die keine Auto-Status-Schwellen deklarieren.

Eine ReportRow hat keine eigenen konfigurierbaren Eigenschaften — sie gruppiert Widgets horizontal und löst einen natürlichen Seitenumbruch aus, wenn das Raster keinen Platz mehr hat.

Das Vier-Spalten-Raster

Die Berichts-Leinwand ist ein festes Vier-Spalten-Raster. Der columnSpan eines Widgets gibt an, wie viele der vier Spalten es belegt. Eine Zeile kann jede Kombination von Widgets enthalten, deren columnSpan-Werte in Summe höchstens vier ergeben. Fügst du ein fünftes Widget zu einer Zeile hinzu, deren Summe bereits vier ist, platziert octoja es in einer neuen Zeile.

Typische Spans: 1 = viertelbreit (KPI-Karten, kleine Tachos); 2 = halbbreit (Info-Karten, Diagramme); 3 = drei Viertel (breite Tabelle neben einer schmalen Karte); 4 = vollbreit (Hero-Diagramme, Tabellen, die jede Spalte brauchen).

Widget-Katalog

Widgets sind in sechs Kategorien gruppiert — KPI-Karten, Diagramme, Tabellen, Info-Karten, Layout und Checks. Die Hinweise unten erfassen die Geltungsbereich-Sensitivität jedes Widgets und nicht offensichtliches Verhalten; GET /api/reports/widgets/available liefert den verbindlichen Live-Katalog für den aktuellen Build. Sofern nicht anders vermerkt, ist jedes Daten-Widget geltungsbereich-sensitiv (es berücksichtigt die Kunde-/Standort-Filter des Berichts).

KPI-Karten (Kpi)

Einzelwert-Indikatoren mit farbiger Kopfzeile und optionaler Auto-Status-Färbung. Der Katalog ist umfangreich und wächst mit dem Produkt — Beispiele sind Geräte gesamt, Online-Geräte, Offene Meldungen (Anzahl nicht geschlossener Meldungen — jeder Status außer Closed), Health Score, Geräte mit wenig Speicher, Patch-Compliance, Zertifikate ≤30 Tage, Check-Erfolgsrate, sowie KPIs für Aktivität, Backup, Monitoring, Lywand, Software-Inventar und Vorfälle. Alle KPI-Karten sind geltungsbereich-sensitiv.

Diagramme (Chart)

• Gerätealter (Balkendiagramm) — Histogramm der Geräte nach Altersband (z. B. < 1 J, 1–3 J, 3–5 J, > 5 J).
• Betriebssystemverteilung (Balkendiagramm) — Geräte gruppiert nach Betriebssystem-Familie.
• Gerätetypen (Donut) — Geräte gruppiert nach Typ (Workstation, Server usw.).
• Festplattennutzung (Donut) — Geräte gruppiert nach Gesamt-Festplattennutzungs-Bucket.
• Meldungen nach Priorität (Donut) — nicht geschlossene Meldungen gruppiert nach Priorität. Geschlossene Meldungen sind ausgeschlossen, passend zur KPI „Offene Meldungen".
• Aktivität nach Quelle (Donut) — Aktivitätsereignisse gruppiert nach Quelle.
• Check-Statusverteilung (Donut) — Ergebnisverteilung eines ausgewählten Checks (Ok / Warnung / Kritisch / Unbekannt).
• Check-Statusverlauf (Diagramm) — Zeitreihe des Ergebnisverlaufs eines ausgewählten Checks über den Geltungsbereich.

Tabellen (Table)

• Alle Geräte — Geräte mit Name, OS, Zuletzt gesehen und Zustand.
• Neueste Meldungen — neueste Meldungen mit Titel, Status, Priorität, Kunde und Datum.
• Zertifikate-Ablaufliste — Zertifikate, die bald ablaufen, gruppiert nach verbleibenden Tagen.
• Festplattenbelegung — Geräte sortiert nach geringstem freien Speicher.
• Top-Hersteller — Geräte gruppiert nach Hardware-Hersteller.
• Check-Ergebnisse — Pro-Gerät-Ergebnisse für einen ausgewählten Check (Status, Wert, zuletzt ausgewertet).
• Incident-Zeitleiste — chronologische Liste der Vorfälle innerhalb des Geltungsbereichs.
• Backup-Status — Läufe von Backup-Jobs mit Ziel, Status und letztem Erfolg.
• Lokale Benutzer — lokale Konten auf den Geräten des Geltungsbereichs.
• Schwachstellen — Schwachstellen-Funde, die über die Lywand-Integration eingespielt werden.
• Monitoring-Übersicht — Monitoring-Check-Status über die Geräte.
• Meistinstallierte Software — die am häufigsten installierten Software-Titel über die Geräte des Geltungsbereichs.
• Hardware-Inventar — eine Zeile pro Gerät mit einer konfigurierbaren Auswahl an Hardware-Feldern, gruppiert in System, Identität, CPU, Speicher, Datenträger und Netzwerk.
• Patch-Verlauf — installierte Updates pro Gerät, mit KB-Nummer und Installationsdatum.
• Ausstehende Patches — pro Gerät noch ausstehende Updates.

Info-Karten (Info)

• Geräteübersicht — serverseitig aufgelöste Übersicht der Geräte im Geltungsbereich (Summen + Aufschlüsselung).
• Kundenaufschlüsselung — serverseitig aufgelöste Kunden-Übersicht (Namen + Anzahl), gefiltert nach Kunde und Standort des Berichts.
• Tacho (statisch) — einzelner Tacho mit konfigurierbarem Wertebereich und Schweregrad-Schwellen. Vom Autor bereitgestellter Wert — fragt keine Live-Daten ab und ist nicht geltungsbereich-sensitiv.

Checks (Checks)

• Check-Detail — Detail-Karte für einen einzelnen Check (aktueller Status, letztes Ergebnis, Konfigurations-Zusammenfassung).
• Check-Verlauf (pro Gerät) — Ergebnisverlauf eines einzelnen Checks pro Gerät, ein Eintrag je Gerät mit seinem jüngsten Trend. Lässt sich auf bestimmte Geräte oder Status einschränken.
• Check-Status-Timeline — Zeitleiste der Status-Übergänge eines einzelnen Checks über den Geltungsbereich.

Layout (Layout)

Strukturelle Widgets — keine Live-Daten und nicht geltungsbereich-sensitiv.

• Überschrift — Text einer Abschnittsüberschrift.
• Absatz — Fließtext.
• Hinweisbox — farbige Callout-Box mit einer der sechs Hintergrundfarben.
• Stichpunktliste — Stichpunktliste mit Markierungs-Stil Dot, Check oder Dash.
• Trennlinie — horizontale Linie.
• Abstand — vertikaler Leerraum.
• Seitenumbruch — erzwingt an dieser Stelle einen Seitenumbruch im PDF.
• Ampel-Gitter — vom Autor gepflegtes Gitter aus Status-Zellen (Ok / Warning / Critical / Unknown).

Geltungsbereich-Semantik

Beim Erzeugen eines Berichts trägt das Request-Payload customerId? und siteId? — beide optional, eine siteId ist nur sinnvoll in Kombination mit einer customerId. Der Renderer schränkt die Datenabfrage jedes geltungsbereich-sensitiven Widgets auf diesen Kunden (und optional den Standort) ein.

Widgets, die nicht geltungsbereich-sensitiv sind (Tacho und alle Layout-Widgets), ignorieren den Geltungsbereich — ihr Inhalt ist vom Autor vorgegeben und rendert unabhängig von customerId / siteId gleich.

Der Geltungsbereich wird nicht in der Vorlage gespeichert. Er ist ein Parameter zur Erzeugungszeit — dieselbe Vorlage kann je nach übergebenen Werten einen mandantenweiten, einen kundenbezogenen oder einen standortbezogenen Bericht erzeugen.

Eingebaute vs. eigene Vorlagen

Beide Typen teilen sich Schema und Editor-Erfahrung. Die Unterschiede sind verhaltensbezogen:

• Erstellt von — eingebaut wird mit octoja geliefert; eigen wird von dir erstellt.
• name — eingebaut ist ein i18n-Schlüssel (bei Anzeige lokalisiert); eigen ist die wörtliche Benutzereingabe.
• slug / iconName — bei eingebauten gesetzt (slug steuert den PDF-Dateinamen, iconName das Kartensymbol); bei eigenen null (Dateiname aus name slugifiziert, generisches Vorlagensymbol).
• Bearbeiten — eingebaute sind schreibgeschützt; vorher klonen, um anzupassen. Eigene Vorlagen sind bearbeitbar.
• Löschen — eingebaute sind serverseitig geschützt; eigene Vorlagen sind löschbar.
• Duplizieren — für beide erlaubt und erzeugt stets eine neue eigene Vorlage.

Berechtigung

reports.manage — Erstellen, Bearbeiten, Löschen und Umbenennen von eigenen Vorlagen. Berichte erzeugen und die Vorlagenliste ansehen erfordern sie nicht.

Vergeben über Gruppen unter Administration → Gruppen.

PDF-Dateiname

Der Dateiname des erzeugten PDFs wird durch den content-disposition-Header der Antwort gesetzt:

• Eingebaute Vorlage: <slug>-<jjjj-mm-tt>.pdf (z. B. executive-snapshot-2026-04-20.pdf).
• Eigene Vorlage: <slugifizierter-name>-<jjjj-mm-tt>.pdf (z. B. quarterly-customer-review-2026-04-20.pdf).

Das Datum ist das Erzeugungsdatum. Das Datenfenster des Berichts ist eine separate Einstellung: der optionale Berichtszeitraum rangeStart / rangeEnd beim Erzeugen-Aufruf (der Zeitraum-Wähler in der UI, mit den Vorgaben Gesamter Zeitraum, Aktueller Monat, Letzter Monat und Benutzerdefiniert). Zeitfensterbezogene Widgets berücksichtigen ihn; Momentaufnahme-Widgets wie die Inventar-Tabellen zeigen stets den aktuellen Stand.

PDF-Sprache

Die PDF-Sprache folgt dem Request-Header Accept-Language. octoja setzt diesen immer auf die aktuelle UI-Sprache des Benutzers zum Zeitpunkt des Klicks auf „Erstellen". Um aus einer englischen UI ein deutsches PDF zu erzeugen, schalte zuerst die Sprachauswahl um und klicke dann auf „Erstellen" — der nächste Klick erzeugt ein deutsches PDF.

Zeitpläne

Berichte können automatisch und wiederkehrend zugestellt werden. Ein Zeitplan bündelt eine oder mehrere Berichtsvorlagen mit einem Cron-Ausdruck und einer Menge von Empfängern; wird der Zeitplan ausgelöst, erzeugt octoja jede Vorlage als PDF und versendet sie per E-Mail an die Empfänger. Die Berichtsseite hat einen Eintrag Zeitplanung, der diesen Verwaltungsbereich öffnet.

• cron — ein standardmäßiger 5-Feld-Cron-Ausdruck, ausgewertet in UTC. Er wird beim Speichern geprüft; ein ungültiger Ausdruck liefert 400 Bad Request.
• receivers — ein oder mehrere Einträge, jeder mit einer customerId (erforderlich), einer optionalen siteId (nur sinnvoll mit einem Kunden) und einer Liste von Empfänger-emails. Jeder Empfänger legt den Berichts-Geltungsbereich für die PDFs fest, die er erhält — dieselbe Kunde-/Standort-Einschränkung wie unter Geltungsbereich-Semantik beschrieben.
• enabled — ein deaktivierter Zeitplan bleibt erhalten, wird aber nie ausgelöst; die nächste Ausführungszeit wird nur berechnet, solange er aktiviert ist.
• subject — optionale eigene Betreffzeile für die Zustell-E-Mail; leer lassen für den Standard.

Zeitpläne erstellen, aktualisieren und löschen — sowie einen sofort ausführen — erfordert reports.manage. Zeitpläne auflisten und ansehen erfordert nur reports.view.

Verwandte Artikel

• Berichtsvorlage erstellen — durchgängige Anleitung.