Hinweis: Die Integration von koppla Daten in Power BI ist technisch anspruchsvoll, da koppla eine spezielle Schnittstelle nutzt, die in Power BI manuell angelegt werden muss.

Dieser Artikel gibt einen Überblick über die notwendigen Schritte, erklärt aber nicht die Grundlagen die für die Anbindung notwendig sind.

Zugangsdaten beantragen

Die Zugangsdaten müssen manuell mit einer formlosen E-Mail an [email protected] beantragt werden. Diese Zugangsdaten ermöglichen es, jegliche Projektdaten abzurufen und sollten daher unter allen Umständen geheim gehalten werden.

Zusätzlich sollten die Zugangsdaten niemals in Klartext gespeichert oder abgelegt werden. Power BI erlaubt die Nutzung von Parametern, die zumindest einen gewissen Schutz der Zugangsdaten darstellen.

Mehr Informationen zum allgemeinen Prozess und zur Verwendung sind hier zu finden: https://koppla.notion.site/GraphQL-API-documentation-183251a5997b80fba0a9dab5accd6752#193251a5997b8055b177cc5784de5cd1

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:

https://studio.apollographql.com/public/koppla/variant/prod/schema/reference

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.
1. 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/schedule
2. ProjektID: 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/schedule
3. XApiKey: Dies ist der erste Teil deiner Zugangsdaten, das du vom koppla Tech Team erhalten haben solltest.
4. Authorization: Dies ist der zweite Teil deiner Zugangsdaten.
  Achte unbedingt darauf, dass du die Zeichenkette INKLUSIVE des Worts "Bearer" in das Feld einfügst.
5. An allen anderen Parametern müssen KEINE Veränderungen vorgenommen werden
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.staging.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"

5. 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.