Daten aus dem HQ mit Power BI auswerten

Mit helloHQ haben unsere Kunden den gesamten Prozess ihrer Agentur an einer zentralen Stelle im Griff. Natürlich bietet diese Integration grenzenlose Möglichkeiten für gutes Controlling und Auswertungen aller Art. Mit unseren integrierten Controlling-Modulen bietet helloHQ bereits eine Vielzahl unterschiedlicher Berichts- und Auswertungsmöglichkeiten “Out-of-the-Box”. Die konkreten Anforderungen an das Unternehmenscontrolling unserer Kunden sind aber so vielfältig, wie es die Agenturlandschaft ist. Natürlich können wir nicht jede noch so ausgefallene Berichtsidee in helloHQ umsetzen – aber wir können die passenden Daten bereit stellen.

Mit Power BI bietet Microsoft seit einiger Zeit ein sehr mächtiges – und kostenfreies – Controllingwerkzeug an, das Daten aus den unterschiedlichsten Quellen aggregieren und aufbereiten kann. Aufgrund seiner Nähe zu Excel sind die zu verwendenden DAX-Formeln (DAX von Data-Analytics-Expressions, nicht von Deutscher Aktien Index) vielen Office-Nutzern außerdem schon bekannt.

Einer der wichtigsten Schritte bei der Erstellung von Berichten in Power BI ist das richtige Anbinden der Datenquelle. Klassiker wie Excel-Tabellen oder SQL-Datenbanken sind kein Problem, bei komplexen Datenstrukturen wie sie helloHQ zugrunde liegen, ist etwas mehr Denkarbeit notwendig. Hier kommt unsere offene REST-API (Daten- und Programmierschnittstelle) zur Hilfe.

Wir verwenden den verbreiteten OData Standard zur Übertragung von Daten aus und in das HQ. Dieser Standard wird auch von Power BI unterstützt und erleichtert uns das Leben. Los geht es also:

Als erstes öffnen wir Power BI und beginnen, indem wir über die Schaltfläche “Daten abrufen” eine neue Datenquelle anlegen.

ezgif-5-85a204e84d

Wir wählen “Sonstige” –> “Leere Abfrage” aus der langen Liste der Verfügbaren Datenquellen aus.

Screen2

Ein leeres Abfragefenster wird geöffnet. Um uns mit der helloHQ-API zu verbinden, öffnen wir den erweiterten Editor.

Screen3

Nun folgt der etwas technischere Teil unserer Übung. Unser Entwickler Mark hat Gott sei Dank etwas Vorarbeit für uns geleistet und das technische Prinzip zur Ansprache der helloHQ-API aus Power BI für uns geknackt. Die technischen Details hat er für Interessierte hier zusammen gefasst. Wir werden es an dieser Stelle etwas vereinfachen.

Der folgende Code ruft Daten aus helloHQ ab. Um dies in Power BI zu verwenden, kopieren wir einfach den vollständigen Code in unser leeres “erweiterter Editor” Fenster in Power BI.

let 
BaseUrl = "https://api.hellohq.io/v1/<<<HIER OBJEKT EINFÜGEN>>>?",
Token = "<<<HIER API TOKEN EINFÜGEN>>>",
EntitiesPerPage = 1000,

GetJson = (Url) =>
let Options = [Headers=[ #"Authorization" = "Bearer " & Token ]],
RawData = Web.Contents(Url, Options),
Json = Json.Document(RawData)
in Json,

GetEntityCount = () =>
let Url = BaseUrl & "$count=true&$top=0",
Json = GetJson(Url),
Count = Json[#"@odata.count"]
in Count,

GetPage = (Index) =>
let Skip = "$skip=" & Text.From(Index * EntitiesPerPage),
Top = "$top=" & Text.From(EntitiesPerPage),
Url = BaseUrl & Skip & "&" & Top,
Json = GetJson(Url),
Value = Json[#"value"]
in Value,

EntityCount = List.Max({ EntitiesPerPage, GetEntityCount() }),
PageCount = Number.RoundUp(EntityCount / EntitiesPerPage),
PageIndices = { 0 .. PageCount - 1 },
Pages = List.Transform(PageIndices, each GetPage(_)),
Entities = List.Union(Pages),
Table = Table.FromList(Entities, Splitter.SplitByNothing(), null, null, ExtraValues.Error)
in
Table

WICHTIG: Bei gewissen Entitäten, wie zum Beispiel Rechnungen oder Eingangsrechnungen, muss für den Wert 'EntitiesPerPage' statt 1000 eine 100 eingetragen werden, damit alle Daten angezeigt werden.

Achtung: Wenn mehrere Elemente Abgefragt werden sollen, kann der Inhalt der BaseUrl wie folgt angepasst werden (Beispielabfrage): "https://api.hqlabs.de/v1/UserReportings?$expand=Project,User,Task&",

Nun sind noch 2 kleine Anpassungen notwendig. Erstens, müssen wir uns authentifizieren. Dies passiert über den “API Token”, den wir uns direkt aus helloHQ holen. Unter Admin/ API Clients ist dieser Token zu finden, den wir nun in unser Skript statt <<<HIER API TOKEN EINFÜGEN>>> einsetzen.

Screen4

Nun müssen wir der API noch sagen, welche Objekte wir eigentlich abrufen wollen (z.B. Leads, Unternehmen, Projekte usw.). Das gewünschte Objekt fügen wir dann in unseren Code statt <<<HIER OBJEKT EINFÜGEN>>> ein. Die Liste aller verfügbaren Objekte finden wir auch unter developer.helloHQ.io , hier ein Auszug:

Screen5

Für unser Beispiel rufen wir als erstes alle Leads aus unserem Testsystem ab. nachdem wir das Code-Fenster geschlossen haben, erscheint als erstes folgende Fehlermeldung:

Screen6

Nach einem Klick auf “Anmeldeinformationen bearbeiten” wählen wir im folgenden Fenster die Option “Anonym” und bestätigen mit “Verbinden”.

Screen7

Jetzt werden die ersten Daten aus dem HQ abgerufen. Das folgende Fenster sieht allerdings noch nicht besonders spektakulär aus, so in etwa wie der folgende Screenshot. Wir müssen nun noch die richtigen Spalten unserer Daten einblenden. Das funktioniert mit einem Klick auf den kleinen “Expand” Button wie auf dem Screenshot gezeigt.

Screen8

Es öffnet sich ein kleines Fenster, in dem bereits die einzelnen Informationen unseres Datensatzes angezeigt werden. Theoretisch könnten wir nun auswählen, welche Spalten wir wirklich benötigen – wir können aber auch einfach alle aktiviert lassen.

Wichtig:
Das Häkchen “Ursprüngliche Spaltennamen…” unbedingt deaktivieren.

Screen9

Jetzt kommen wir der Sache schon sehr nahe, wir sehen schon die tatsächlichen Daten aus helloHQ. Damit später z.B. ein Datum auch als solches erkannt wird und wir hübsche Zeitfilter etc. verwenden können, müssen wir die Spalten noch entsprechend markieren. Dazu einfach auf eine betroffene Spalte mit einer Datumsangabe oder z.B. einer Zahl klicken und auf “Datentyp erkennen” klicken. Nun wird automatisch der passende Datentyp zugewiesen.

Screen10

Zu guter Letzt geben wir unserer Abfrage noch einen passenden Namen (in diesem Fall “Leads”) und schließen den Editor.

Screen11

Das war der schwierige Teil! Jetzt stehen uns alle Daten unserer Abfrage in Power BI zur Verfügung. Per einfachem Drag & Drop bewegen wir die Spalten in unseren Bericht. Fertig ist das interaktive Dashboard. Ein Klick auf “Aktualisieren” holt die neuesten Daten aus helloHQ.

Screen12

Meistens wollen wir natürlich nicht “nur” Leads auswerten, sondern diese mit vielen anderen Informationen aus helloHQ verbinden. Das ist jetzt garkein Problem mehr – wir wiederholen einfach die oben gezeigten Schritte und rufen statt “Leads” jetzt eben noch “Unternehmen” oder “Projekte” oder irgendein anderes Objekt aus der API ab. Power BI bietet jede Menge Werkzeuge, um diese zu verknüpfen, Berechnungen anzustellen und auszuwerten. Inspiration bietet Microsoft direkt auf der Power-BI-Seite.