⚠️ Dieser Artikel wird gerade überarbeitet.
In der Zwischenzeit findest du aktuelle Informationen in unserem neuen API-Artikel: "Die koppla API nutzen". Bei Fragen zur Power BI-Integration melde dich gerne direkt bei uns – wir helfen dir weiter!
Hinweis: Die Integration von koppla-Daten in Power BI ist technisch anspruchsvoll. Dieser Artikel gibt einen Überblick über die notwendigen Schritte, erklärt aber nicht die Grundlagen, die für die Anbindung notwendig sind.
Informationen zur koppla API und zur Erstellung von Zugangsdaten findest du in unserem API-Artikel: "Die koppla API nutzen"
Power BI Integration
koppla Endpunkte
Um alle Daten eines Projekt aus koppla in Power BI zugänglich zu machen, müssen die verschiedenen Endpunkte der koppla API angesprochen werden. In der GraphQL API von koppla gibt es individuelle Endpunkte für alle Funktionalitäten des koppla Terminplans - z.B. Vorgänge, Meilensteine, Tickets, Statusmeldungen, .... Eine vollständige Dokumentation zu allen Endpunkten (inklusive der zur Verfügung stehenden Parametern und Filtermöglichkeiten) ist hier zu finden:
Um eine ganzheitliche Übersicht über das Projekt zu bekommen, müssen, je nach Anwendungsfall, mehrere dieser Endpunkte kombiniert und zu einer Tabelle zusammengeführt werden. Die Verknüpfung der jeweiligen Tabellen erfolgt anhand der IDs.
In anderen Fällen reicht es möglicherweise aus einen Endpunkt mit allen zur Verfügungen stehenden Knoten zu verwenden.
Beispiel:
Der Endpunkt für Vorgänge erlaubt es, zusätzlich zu allen Vorgangsdaten (Name, Datum, Gewerk) die jeweils letzte Statusmeldung der Vorgänge abzufragen. Dadurch ist es möglich, eine Übersicht über die letzten Statusmeldungen der Vorgänge nach Gewerke zu erstellen.
Power Query
Weil GraphQL nicht nativ von Power BI unterstützt wird, ist es notwendig die koppla Schnittstelle mittels Power Query anzusprechen. Power Query ist ein in Power BI eingebauter Editor, der es erlaubt Daten aus verschiedenen Quellen abzufragen, zu verändern oder zu transformieren und anschließend in verschiedenen Formaten zur Verfügung zu stellen.
Im folgenden Kapitel koppla Power BI Template stellen wir ein Template zur Verfügung, das die wichtigsten Endpunkte bereits enthält, wir können aber nicht versichern, dass tatsächlich alle notwendigen Attribute abgedeckt sind. Es ist also ratsam, das Grundprinzip zu verstehen, um die Abfragen erweitern oder sogar verändern zu können.
koppla Power BI Template
Um den initialen Prozess zu verkürzen, stellt koppla ein Power BI Template zur Verfügung, welches bereits die wichtigsten Endpunkte sowie die entsprechenden Datentransformationen enthält.
Lade dir das Template unter folgendem Link herunter: https://drive.google.com/drive/folders/1UXyJu7z_9jA1byTEmY9zb8uOCO5sZ6Em?usp=drive_link
Öffne das Dokument in Power BI
Öffne die Einstellungen für Parameter. Gehe dafür zum Tab Start, klicke mit der Maus auf den Pfeil Daten transformieren und klicke anschließend auf Parameter bearbeiten
In dem sich nun öffnenden Fenster musst du die Platzhalter mit deinen Projekt- bzw. Zugangsdaten ersetzen.
ClientID: Entspricht der ID deines Unternehmens
Die ID deines Unternehmens kannst du beispielsweise aus der URL (Internet Adresse) von koppla entnehmen. Gehe dafür in deinen Terminplan und kopiere die markierten Stellen aus der URL:
https://my.koppla.de/zY61H24JMuw6BI0G7fgy/projects/xxx/scheduleProjektID: Entspricht der ID des Projekts für das du einen Report erstellen möchtest.
Die Projekt ID kannst du ebenfalls aus der URL von koppla entnehmen: https://my.koppla.de/xxx/projects/cnkaWZFsIRM79xHh6KQV/scheduleXApiKey & Authorization: Deine persönlichen Zugangsdaten – siehe API-Artikel.
Klicke nun auf OK. Nachdem sich das Parameter Fenster geschlossen hat, sollte sich ein weiteres Fenster öffnen, das dich darüber in Kenntnis setzt, dass verschiedene Abfragen aktuell ausgeführt werden.
Sind alle Daten richtig eingegeben worden, sollte ein erster Report für das angegebene Projekt auftauchen. Wird dir eine Fehlermeldung angezeigt, wiederhole die Schritte 4. a-d. Bleibt der Fehler weiterhin bestehen, setze dich mit dem koppla Support-Team in Verbindung.
Alternativ: Power BI für die koppla Integration von Grund auf einrichten
Unter Start, klicke auf Daten transformieren
Im sich öffnenden Power Query-Editor, klicke auf Neue Quelle -> Leere Abfrage
Anschließend auf Erweiterter Editor
In das sich nun öffnende Textfeld muss folgender Code kopiert werden. ACHTUNG: Die Platzhalter für "XApiKey", "Authorization" und "ProjektID" musst du in diesem Fall händisch anpassen.
let
url = "https://api.koppla.de/api/graphql/v1/",
headers = [
#"Method" = "POST",
#"Content-Type" = "application/json",
#"X-Api-Key" = XApiKey,
#"Authorization" = "Bearer " & Authorization
],
body = "{""query"":""query ProjectOrders($project: ID!) { projectOrders(project: $project) { edges { node { id name startAt finishAt tenantTradeVariation { id name color } latestStatusReport { status progress reason comment } } } } }"",""variables"":{""project"":""" & ProjektID & """}}",
response = Web.Contents(url, [
Headers = headers,
Content = Text.ToBinary(body)
]),
Source = Json.Document(response),
data = Source[data],
projectOrders = data[projectOrders],
edges = projectOrders[edges],
// Convert the list to a table
// Because it's already a list we don't need to split the individual rows extra, so SplitByNothing is used.
// First null is for the column name, it defaults to "Column1",
// Second null is used as default value if no value is present
edgesTable = Table.FromList(edges, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
// Expand the 'node' record inside each edge from "Column1" into individual columns
expandedEdges = Table.ExpandRecordColumn(edgesTable, "Column1", {"node"}),
// Expand the fields inside 'node'
expandedNode = Table.ExpandRecordColumn(expandedEdges, "node", {"id", "name", "startAt", "finishAt", "tenantTradeVariation", "latestStatusReport"}),
expandedTrade = Table.ExpandRecordColumn(expandedNode, "tenantTradeVariation", {"id", "name", "color"}, {"Gewerke-ID", "Gewerk", "Gewerkefarbe"}),
finalTable = Table.ExpandRecordColumn(expandedTrade, "latestStatusReport", {"status", "progress", "reason", "comment"}, {"Statusmeldung", "Fortschritt", "Grund", "Kommentar"}),
#"Renamed Columns" = Table.RenameColumns(finalTable,{{"name", "Aktivität"}, {"startAt", "Startdatum"}, {"finishAt", "Enddatum"}})
in
#"Renamed Columns"Nachdem du auf Fertig klickst, solltest du bereits eine Vorschau der Tabelle sehen. Nun kannst du noch Änderungen an der Tabelle vornehmen. Zum Schluss musst du nur noch auf "Schließen und übernehmen" klicken, und die Daten sollten dir in Power BI zur Verfügung stehen.
Bitte beachte, dass es nicht sicher ist deine Zugangsdaten in Klartext in die Abfrage zu schreiben. Nutze Power BI Parameter
(https://learn.microsoft.com/en-us/power-query/power-query-query-parameters) oder Secret Storages wie z.B. von Azure.