Die KPI’s (Key Performance Indicators bzw. Leistungszahlen) eines Unternehmens sind für die Steuerung von immenser Bedeutung. Meist werden diese Zahlen in Exceltabellen gesammelt oder sind auf mehreren Quellen verstreut abzurufen. Dies bedeutet im weitestgehenden Sinne einen Mehraufwand für die Verantwortlichen, die diese KPI’s screenen und im Nachgang auch präsentabel aufbereiten müssen.

Eine effektive Hilfestellung bietet hierfür die Atlassian Marketplace App PocketQuery für Confluence aus dem Hause Scandio. Mit dieser App lassen sich, sobald einmal definiert, dieselben Datenabfragen aus externen Datenbanken beliebig und tagesaktuell wiederholen. Somit können die relevanten KPI’s auf einer Confluence Seite vollkommen automatisch und optisch aufbereitet dargestellt werden.

Dieses How-To erklärt in 5 einfachen Schritten wie man PocketQuery für Confluence zu diesem Zweck integriert.

1. Übersicht: Wie lege ich eine Datasource an

Die untenstehende Tabelle listet die Bausteine auf, die für das erfolgreiche Anlegen einer Datasource benötigt werden. In den nächsten vier Schritten wird erklärt, wie diese Bausteine erstellt werden.

2. Wie bekomme ich eine Client ID und einen Client Schlüssel (Client Secret)?


  • Anlegen eines neuen Projektes.
  • Klick auf “APIs und Dienste aktivieren”.
  • Im Suchfeld nach “Google Analytics” suchen und dort den dritten Punkt auswählen: “Analytics API”.
  • Die API aktivieren.


  • Mit Klick auf “Anmeldedaten erstellen” die Anmeldedaten für die API erstellen.


  • Danach dem vorgegebenen Link folgen, um auf die unten abgebildete Seite zu gelangen.
  • Erstellung der Client ID: Im Dropdown “OAuth-Client-ID” auswählen.


  • Zustimmungsbildschirm konfigurieren: Anwendungstyp “Intern” auswählen. Der “Name der Anwendung” kann frei gewählt werden.


  • Erstellung eines OAuth-Client: Anwendungstyp “Webanwendung” angeben. Der Name kann wieder frei gewählt werden.

  • Angabe der Anwendungs-URL (die URL, auf der später PocketQuery laufen wird z.B. die eigene Confluence Instanz) unter “Autorisierte JavaScript-Quellen”.

  • Die Weiterleitungs-URL ist der Pfad in der Anwendung, zu dem Nutzer nach der Authentifizierung mit Google weitergeleitet werden. Wichtig für Punkt 3, in dem wir einen Access-, und Refresh-Token erzeugen.

Hinweis Um später die Client-ID und den Client-Schlüssel einzusehen, einfach die entsprechende Webanwendung unter “Anmeldedaten” auswählen.



3. Wie generiere ich einen Access-, und einen Refresh-Token?

  • Einen GET Request in einem neuen Tab absenden:

Beispiel:

 https://accounts.google.com/o/oauth2/v2/auth?client_id=XXXX-9cjimo.apps.googleusercontent.com&redirect_uri=http://ope=https://www.googleapis.com/auth/analytics.readonly&response_type=code&prompt=consent&access_type=offline
  • Im Folgenden wurde der Request für das bessere Verständnis in seine Einzelteile zerlegt:
https://accounts.google.com/o/oauth2/v2/auth?

Die client_id=[CLIENT ID], in Schritt 2 generiert

&redirect_uri=http://localhost:8090&

Die lokale Testinstanz

scope=https://www.googleapis.com/auth/analytics.readonly&response_type=code&prompt=consent&access_type=offline
Hinweis Es muss in diesem Schritt sowohl "prompt", als auch "access_type" gesetzt sein, sonst generiert der nächste Schritt nur einen Access-, aber keinen Refresh-Token.
  • Nutzung des Anmeldedialogs für das Einloggen mit einem Google-Konto, danach folgt der OAuth-Zustimmungsbildschirm.


  • Weiterleitung zu “redirect_uri” (in diesem Fall “https://localhost:8090”)
Hinweis Sollte man mit einer eigenen Testinstanz arbeiten, sollte sichergestellt sein, dass man angemeldet ist, da ansonsten der Authorization Code URL-encoded (kryptisch) ist und zur Benutzung mit Postman wieder entcodet werden muss.
  • Folgende URL erscheint nun im Browser:
http://localhost:8090/?code=4/oQCgmfQng15iszfp1E9lZsG8lH-WLYPzFiLFCMH0Q0ZJ1I_FbhcsGxeES3AswtmmqSEhPQQzyVfd_MfU_Yl0oNQ&scope=https://www.googleapis.com/auth/analytics.readonly#recently-worked


Diese erstellte URL beinhaltet den Authorization Code (alles nach ?code= und vor &scope=), der benötigt wird, um sich einen Access- und einen Refresh-Token zu erzeugen.

  • Durchführung eines POST Request an https://www.googleapis.com/oauth2/v4/token, um den Authorization Code in einen Access-, und einen Refresh-Token umzutauschen, beispielsweise mit dem Postman-Tool (Anmerkung: Postman ist ein nützliches Programm zum Ausführen und Testen von APIs).

  • Das Anlegen einer Datasource in PocketQuery ist nun möglich. Siehe beispielhaft untenstehendes Bild:


4. Wie lege ich eine Query an und wie lautet meine REST URL bzw. welche Parameter frage ich ab?

  • Wir haben für diesen Beispielfall folgende Parameter benutzt:
    • Page Title
    • Users
    • Session Duration
    • Pageviews
    • % Exit
Hinweis Weitere Parameter-Möglichkeiten sind unter https://ga-dev-tools.appspot.com/query-explorer/ vorgegeben und können mit der Endung “API Query URI” ab “ga?ids…” kopiert und in PocketQuery durch eine Query als REST URL eingefügt werden.


  • Nötige Bausteine beim Anlegen einer Query:
    • Name
    • Datasource
    • Template
    • REST URL
    • Converter
    • Allowed Spaces
    • Cache for Duration
    • JSON Path
    • Add results to Confluence search

5. Wie muss mein Converter aussehen bzw. was muss er beinhalten, damit mein Inhalt ordentlich auf einer Confluence-Page angezeigt wird?

  • Einfügen des PocketQuery-Macros auf einer Confluence Seite:


Hinweis Bei diesem Schritt folgt eine Fehlermeldung. Diese wird durch den nachfolgenden Schritt behoben.
  • Da PocketQuery mit Arrays als Antwort arbeitet, muss das Ergebnis der Anfrage durch einen Converter angepasst werden. Dabei müssen unter “// define the headers for your columns here” immer genau die Überschriften der einzelnen Spalten angegeben werden. Später werden diese ins Ergebnis miteingebaut.
// json is the result as json string
function convert(json) {
    // the array-of-objects we will return
    var result = [];
    var parsedJsonObject = JSON.parse(json); // parse json string
    // define the headers for your columns here
    var columnNames = {
        'ga:pageTitle': 'Page Title',
        'ga:users': 'Users',
        'ga:sessionDuration': 'Session Duration',
        'ga:pageviews': 'Page Views',
        'ga:exitRate': 'Exit Rate in %'
    };     
    // insert column names into result and standardise the appearance of numbers
    var rows = parsedJsonObject.rows;
        result = rows.map(function (row) {
        var newRow = {};
        row.forEach(function (item, index) {
            var itemAsInteger = parseFloat(item).toFixed(0);
            var checkForNaN = isNaN(itemAsInteger);
            newRow[columnNames[parsedJsonObject.columnHeaders[index].name]] = checkForNaN ?
                item : itemAsInteger;
        });
        return newRow;
    });
    return result;
}



Fazit

Die erstellte API zu Google Analytics kann nun beliebig abgerufen, verändert und Parameter angepasst werden.

Where to go?