Berichte in Workflows & Dashboards

Ein gespeicherter Bericht wird nicht nur auf seiner eigenen Seite betrachtet. Er ist zugleich eine Datenquelle für Dashboards, für HTML-Berichte, für Workflow-Schritte und (über die API) für externe Systeme.

Ein Bericht als Dashboard-Widget

Das zweite Leben eines gespeicherten Berichts beginnt meist als Widget auf einem Dashboard. Jeder veröffentlichte Bericht steht automatisch als Widget-Typ zur Verfügung. Sie müssen dafür nichts Besonderes tun. Fügen Sie einem Dashboard ein Widget hinzu, wählen Sie den Bericht aus und legen Sie fest, wie er dargestellt werden soll.

Ein Bericht-Widget lässt sich auf sechs Arten anzeigen:

• Einzelwert: Greifen Sie eine Zelle aus einer Spalte für eine große Kennzahl-Kachel ab.
• Einzelne Zahl: Alias für Einzelwert.
• Liniendiagramm: Stellen Sie zwei Spalten als X und Y dar.
• Balkendiagramm: Stellen Sie zwei Spalten als Kategorie und Wert dar.
• Tortendiagramm: Stellen Sie zwei Spalten als Beschriftung und Segmentwert dar.
• Tabelle: das vollständige Ergebnis des Berichts als kleine Tabelle innerhalb des Widgets.

Die vollständige Konfiguration (Achsen, Beschriftungs- oder Wertspalten, Einzelwert-Spalte, optionales Limit) ist unter Bericht-Widgets beschrieben.

Welche Arten von Berichten als Widgets funktionieren

• Data-Grid-Berichte funktionieren als Tabellen-, Linien-, Balken-, Torten- oder Einzelwert-Widget. Die Abfrage des Berichts ist die Datenquelle; das Widget legt fest, wie sie dargestellt wird.
• HTML-Berichte funktionieren als Custom-HTML-Widgets. Die gesamte gerenderte Vorlage erscheint als Inhalt des Widgets. Siehe Custom-HTML-Widgets. Das ist der Weg zum „jedem nur denkbaren Widget".

Berichtsdaten aus einem Flexie-Scripting-Kontext abrufen

Wenn Sie die Daten eines Berichts innerhalb von etwas anderem verwenden möchten (einem HTML-Bericht, der mehrere Berichte zusammenführt, einer E-Mail-Vorlage, einem Automatisierungsschritt), können Sie die Daten des gespeicherten Berichts mit der Funktion getReportData(...) abrufen.

Ob getReportData(...) genau verfügbar ist, hängt davon ab, in welchem Flexie-Scripting-Kontext Sie sich befinden. Verfügbar ist es innerhalb von HTML-Berichten und im Render-Pfad des Berichts. Wenn Sie es aus einer allgemeinen Workflow-Aktion aufrufen und es nicht erkannt wird, weichen Sie auf das gleichwertige query("SELECT ...") in Ihrem Skript aus; query(...) funktioniert überall dort, wo Flexie Scripting läuft.

Signatur

getReportData(reportId, userId?, filters?, templateData?)

Argument	Bedeutung
reportId	Die numerische ID eines gespeicherten Berichts.
userId	Optional. Wenn angegeben, werden die Platzhaltervariablen des Berichts ({user_id}, {group_id}, {role_id}, {timezone}) gegen diesen Nutzer statt gegen den angemeldeten Nutzer aufgelöst.
filters	Optional. Ein Array von { alias, operator, value }-Objekten, das programmatische Gegenstück zu dem, was ein Nutzer in die Filterzeile des Berichts eintragen würde.
templateData	Optional. Zusätzliche Flexie-Scripting-Tokens, die Sie innerhalb der Berichtsabfrage aufgelöst haben möchten, bevor sie ausgeführt wird.

Die Funktion gibt ein Array von Zeilen zurück, in derselben Form, wie sie das Data Grid anzeigen würde; jede Zeile ist eine Key-Value-Zuordnung von Spaltennamen zu Werten. Begrenzt auf 1.000 Zeilen, wie überall sonst auch.

Verwendung innerhalb eines HTML-Berichts

Das einfachste Muster: einen vorhandenen aggregierten Bericht als Datenzulieferer wiederverwenden.

{% set rows = getReportData(42) %}

<table>
  <tr><th>Owner</th><th>Total won</th></tr>
  {% for r in rows %}
    <tr><td>{{ r.owner_name }}</td><td>{{ r.total | number_format(0) }}</td></tr>
  {% endfor %}
</table>

…vorausgesetzt, Bericht 42 ist ein gespeicherter Data-Grid-Bericht, dessen Abfrage die Spalten owner_name und total erzeugt.

Filter programmatisch anwenden

{% set rows = getReportData(
    42,
    user_id,
    [
      { "alias": "status",  "operator": "eq", "value": "finalized" },
      { "alias": "country", "operator": "eq", "value": "DE" }
    ]
) %}

Die Filter-Aliase sind dieselben, die im Filter-JSON des gespeicherten Berichts definiert sind.

Workflows, die einen gespeicherten Bericht lesen

Workflows erreichen Berichte auf zwei Wegen.

In den Flexie-Scripting-Feldern einer Workflow-Aktion

Die Wert-, Vorlagen- oder Bedingungsfelder jedes Schritts sind Flexie Scripting. Dort können Sie Berichtsdaten mit query(...) abrufen und darauf reagieren.

{# Compute today's pipeline value for the contact's owner #}
{% set rows = query("
  SELECT SUM(amount) AS total
  FROM deals
  WHERE owner_id = " ~ owner_id ~ "
    AND is_won = 0 AND is_lost = 0
") %}

{% set pipelineValue = rows[0].total | default(0) %}

Streng genommen verwenden Sie hier keinen gespeicherten Bericht; Sie führen eine Ad-hoc-Abfrage aus. Doch dieselben Zugriffsfunktionen stehen zur Verfügung.

Die API über einen Webhook aufrufen

Die Webhook-Aktion eines Workflows kann Ihr eigenes Back-End aufrufen, das wiederum /api/reports/{id}/data anspricht. Nützlich, wenn der Bericht etwas Aufwendiges tut, das Sie nicht inline neu berechnen möchten.

Berichte als Zulieferer für andere Systeme

Externe Systeme können einen Bericht über die API lesen:

• GET /api/reports/{id}/data gibt die Zeilen des Berichts zurück.
• Übergeben Sie Filterwerte als Query-Parameter, um sie anzuwenden.
• Die Grenze von 1.000 Zeilen und die schreibgeschützten Einschränkungen gelten weiterhin.

Nutzen Sie dies, wenn ein anderes Team oder ein Partner einen Snapshot Ihrer Daten benötigt: Es authentifiziert sich mit einem Flexie-API-Token, ruft die Zeilen des Berichts ab und lädt sie in das eigene System.

Muster, die häufig vorkommen

Ein KPI-Zulieferer für ein externes Dashboard

1. Bauen Sie einen kleinen Data-Grid-Bericht: eine Zeile, eine Handvoll Spalten. SELECT (count_query) AS deals, (sum_query) AS pipeline, ....
2. Markieren Sie den Bericht als veröffentlicht und geben Sie ihm eine stabile ID.
3. Lassen Sie das externe Dashboard /api/reports/{id}/data in seinem Aktualisierungszyklus aufrufen.

Ein größerer Bericht, der mehrere kleinere Widgets speist

1. Bauen Sie einen Data-Grid-Bericht, der alle Spalten erzeugt, die Sie je benötigen könnten (zum Beispiel owner_id, owner_name, won_count, won_total, open_count).
2. Fügen Sie ihn einem Dashboard als fünf verschiedene Widgets hinzu: einen Einzelwert für jede Kennzahl, ein Balkendiagramm für das Ranking.
3. Jedes Widget teilt sich eine Abfrage, eine Datenquelle, eine Aktualisierung. Schnell und konsistent.

Ein HTML-Bericht, der mehrere Quellen zusammenführt

1. Bauen Sie einen HTML-Bericht, der query(...) (oder getReportData(...)) mehrmals für die verschiedenen Abschnitte einer einzigen Seite aufruft.
2. Rendern Sie die Ergebnisse als Ihr eigenes individuelles Layout: KPI-Karten oben, Tabellen in der Mitte, ein Diagramm unten.
3. Legen Sie diesen HTML-Bericht als Custom-HTML-Widget auf einem Dashboard ab. Siehe Custom-HTML-Widgets.

Nächste Schritte

• Dashboards: wo Berichte üblicherweise landen.
• Dashboards: Bericht-Widgets: die sechs Visualisierungs-Untertypen im Detail.
• Dashboards: Custom-HTML-Widgets: einen HTML-Bericht als vollständig individuelles Widget verwenden.