Stap 1: Een API-client aanmaken
Om de koppeling te maken met Power BI hebben wij een API-client nodig. Als deze al verkregen is in ClockWise door eerder gebruik van Power BI, mag deze stap worden overgeslagen.
Een nieuwe API-client maak je aan door in de ClockWise omgeving onder Configuratie > Instellingen > OAuth/API clients op de knop OAuth client toevoegen te klikken.
Geef de client een herkenbare naam wat aanduidt wat het doeleind is, zoals bijvoorbeeld: Power BI.
Zet de optie Access token expires op Never. De bedoeling is dat deze steeds weer gebruikt wordt om de data op te vragen, nadat we hem een keer opgevraagd hebben.
Vergeet na deze stappen niet om op Opslaan te klikken.
Stap 2: Het aanmaken van een autorisatiecode
---
LET OP: De autorisatiecode verloopt na een uur, dus zorg ervoor dat de komende stap(pen) minder dan een uur duren, anders moet deze stap opnieuw uitgevoerd worden!
---
We hebben een autorisatiecode nodig. Ga hiervoor naar de OAuth client en klik op de knop Request Authorization Code (api/v2/auth).
Er verschijnt een pop-up met een ingevuld Response type, Redirect URI en Client ID. Deze hoeven niet veranderd te worden. Klik vervolgens op Request.
U wordt doorgestuurd naar de inlogpagina van ClockWise. Log in zoals normaal ook wordt gedaan.
Als het inloggen is voltooid, wordt er een nieuwe pagina getoond. Op deze nieuwe pagina wordt aan de onderkant een code wordt getoond (zoals achter code in de voorbeeldafbeelding).
Sla deze code op voor de volgende stap.
Stap 3: Een accesstoken opvragen
We hebben nu een acces token nodig. Dit is werkt ongeveer hetzelfde als in de stappen hierboven, alleen met klikken wij nu op de knop Request Tokens.
Weer staan de standaardgegevens goed.
Er moet nu nog wel een Authorization Code ingevuld worden, dat is de code uit stap 2. Klik op Request.
Er wordt nu een venster zichtbaar met een access_token, een refresh_token en wat andere informatie. Hiervan is de access_token nodig voor de volgende stappen.
Het acces_token is in principe onbeperkt geldig, vanwege de instelling die we in stap 1 hebben aangezet.
Stap 4: Query’s aanmaken in Power BI
We kunnen nu de query voor Power BI voorbereiden.
---
We hebben de autorisatiecode van stap 2 niet meer nodig, dus de rest valt niet meer in de tijdsbeperking van een uur die opgelegd was in stap 2.
---
Als het goed is de data connector al opgevraagd bij de ClockWise ServicDesk. Zoek in de ontvangen bestanden naar ServerDataConnector.m, en open het in een teksteditor.
Tussen de code komt op twee verschillende plekken de tekst uwaccountnaam voor (regels 6 en 35). Deze moeten vervangen worden door de naam van uw ClockWise omgeving, zodat hier uw URL staat.
Daarnaast staat op regel 3 tussen aanhalingstekens de tekst **access token**. Tussen de aanhalingstekens moet dit worden vervangen door de verkregen access_token uit stap 3.
De parameters uit de ClockWise Data connector kunnen hier ook worden ingevuld mocht dit gewenst zijn:
Omdat de omgevingsnaam en access_token al geregeld zijn, heeft de Contents() functieaanroep op regel 237 in deze versie iets minder parameters:
- De eerste is of de tarieven moeten worden opgehaald (true of false, standaard false).
- De parameters daarna zijn de extra argumenten voor de uren, koppelingen, projecten en medewerkers (In dezelfde notatie als voor de dataconnector, tussen dubbele quotes ("), velden 4 tot en met 8).
Sla het bestand op.
Stap 5: Power BI initiëren
Nu zijn we klaar voor Power BI.
Log in de browser in op de Power BI server en ga naar de werkruimte (workspace) toe waar de gegevensstroom (dataflow) moet worden aangemaakt.
LET OP: Dit kan niet in de persoonlijke werkruimte worden gedaan
- Klik op + Nieuw -> Gegevensstroom.
- Klik op Nieuwe tabellen definiëren (Meest linker optie). Er wordt een pagina met gegevensbronnen getoond, ergens onderaan (na scrollen) staat Lege query.
- Klik hierop.
Er wordt een query getoond met een tekst als let Bron=, in Bron (of Source in de Engelse versie).
- Laat deze staan en klik op Volgende.
De Power Query editor wordt nu geopend. Echter wil Power BI heel graag dat de query een tabel is, dus u wordt doorgestuurd naar de Hulpprogramma's tekst tab.
- Klik hier op Naar tabel om Power BI dit te laten omzeilen.
- Ga vervolgens naar de Start tab, kijk bij Query en klik op Geavanceerde editor.
De editor die nu opent lijkt op degene die eerder werd getoond, met een paar extra regels.
- Haal alles weg wat hier staat.
- Kopieer de inhoud van het bestand ServerDataConnector.m (uit stap 4) in het tekstveld.
- Klik op OK.
Nu komt een belangrijke tussenstap:
- Klik met de rechtermuisknop op de query (in de linker kolom), en zorg dat het vinkje bij Laden inschakelen uitgeschakeld is! Omdat de query moeilijke types bevat, kan Power BI hier nog niets mee.
Stap 6: Query’s vullen met informatie uit ClockWise
We gaan nu hier wat mee doen om de vier tabellen van ClockWise weer terug te krijgen in de gegevensstroom.
- Klik nogmaals met de rechtermuisknop op Query onder Query’s [1]
- Selecteer Verwijzing.
Een query met de naam Query (..) wordt gemaakt.
- Klik in de nieuwe aangemaakte Query (als hij geladen is) op de tekst [Tabel] of [Table] rechts van het vakje met Employees (of hetgeen wat opgevraagd wenst te worden).
Na wat rekenen wordt de medewerkerstabel getoond zoals hij ook beschikbaar is in Power BI Desktop.
Doe dit vervolgens nog drie keer, voor respectievelijk Projects, Resources en Hours.
Zorg dat je elke keer in de nieuw aangemaakte query staat wanneer er een selectie wordt gemaakt in de tabel/table, en niet in het tabje van de originele Query. Er wordt namelijk naar de originele Query verwezen, waardoor de gegevens in de andere query’s weergegeven kunnen worden. Naar zichzelf verwijzen kan natuurlijk niet.
Om het in de toekomst makkelijker maken, raden wij aan om de namen zoals Query (2) te hernoemen naar bijvoorbeeld Employees. Dit kan in de rechterkolom.
Als het goed is kan nu de gegevensstroom worden opgeslagen. Het verifiëren van de query's kan een tijdje duren, dus geen zorgen als het een kwartier duurt.
Belangrijk
Soms vraagt PowerBI een aantal dingen tijdens het valideren van de query's:
- Tijdens het uitrekenen van de tabel vraagt Power BI een aantal dingen. Als Power BI zegt dat meerdere databronnen gegevens van elkaar kunnen zien, klik op OK (Alle data komt van ClockWise, dus het is niet erg dat de ene databron de gegevens van de andere kan zien, dat kon ClockWise tóch al.)
- Soms vraagt Power BI hoe er geauthentiseerd moet worden. De Autorisatie: Geen die standaard geselecteerd staat is goed (de autorisatie wordt door het script zelf geregeld, alleen heeft Power BI dit niet altijd door....). Mocht de vraag meerdere keren kort achter elkaar worden gesteld (specifiek voor uwomgevingsnaam.clockwise.info/api/v2), dan helpt het soms om op Vernieuwen te klikken bovenin.
- Het kan zijn dat er problematiek is met wat veiligheidsinstellingen, waardoor er niks uit het account gelezen kan worden. Ga naar de desbetreffende Query en klik op Veiligheidsinstellingen uitschakelen.
Extra informatie
Koppelingen tussen de tabellen
De vier tabellen hebben referenties naar elkaar, waardoor ze aan elkaar kunnen worden gekoppeld in de gegevensstroom. Deze koppelingen zijn:
- hours.resource_id ↔ resources.resource_id
- resources.employee_id ↔ employees.employee_id
- resources.project_id ↔ projects.project_id
Overzicht van de meest gebruikte velden
De volgende tabel geeft een vertaling van de meest gebruikte veldnamen in Power BI naar die in ClockWise.
- Let op, niet alle velden zijn altijd beschikbaar! Sommige worden bijvoorbeeld alleen opgehaald als tarieven ophalen op true is gezet.
De velden customer_name_path, project_name_path en department_name_path hebben ook versies met code (geeft paden van klantcodes, projectcodes of afdelingscodes) en ids (de interne identifiers van de klanten projecten en afdelingen). Daarnaast is er ook nog een customer_number_path, die een pad van klantnummers bevat.
Een stapje verder met de tabellen
De ClockWise_Data_Connector.GetTable (omgevingsnaam, client_id, client_secret, url) heeft ook een counterpart in deze connector: ParsedTable(url).
De omgevingsnaam wordt al meteen ingevuld in de URL’s in stap 4, en de client id en secret id zijn vervangen door de access_token die in dezelfde stap 4 wordt ingevuld.
Er zijn twee manieren om dit aan te passen:
- In een nieuwe query in de dataflow kan de ServerDataConnector.m opnieuw worden geladen, maar Bron = Contents() (regel 237) moet worden vervangen met de regel Bron = ParsedTable(url).
- Voorbeeld: ParsedTable("/report/flat/planning?params=hier").
- De andere optie is om het bijgevoegde bestand ServerDataConnector_gettable.m te openen in een teksteditor, en dezelfde aanpassingen te doen die in stap 4 staan beschreven.
- Daarnaast kan op regel 92 de URL worden ingevuld in de functie GetTable. Bovengenoemd voorbeeld staat daar al als voorbeeld ingevuld.
- Plak dit bestand in een nieuwe query in de gegevensstroom. Het laden van de tabel gaat daarna hetzelfde als in stap 6.
Mogelijk worden er waarschuwing getoond dat een paar kolommen geen type hebben, dit kan worden opgelost in het tabje Transformeren
- Selecteer een kolom met een icoontje ABC 123, en selecteer als Gegevenstype: Tekst (dit is een goede standaard als er geen gevonden is door Power BI zelf).
- Alleen als helemaal zeker is dat alle data in deze kolom uit getallen bestaat, kan ook type decimaal of geheel getal gekozen worden.
Let op! De gegevensstroom kan niet worden opgeslagen zolang er fouten worden gegeven over kolommen zonder typen.
Het opzetten van een incrementele verversing
Om data uit de API te besparen, is het mogelijk om de data incrementeel te vernieuwen
Let op: Deze functionaliteit is alleen in Premium werkruimtes mogelijk
Microsoft heeft hier documentatie over geschreven: Incrementeel vernieuwen gebruiken met gegevensstromen
Case: Sommeren van uren op verschillende niveaus
In deze case laten we een voorbeeld zien hoe de Contents functie moet worden aangeroepen. Hiervoor gebruiken we als voorbeeld dat we statistieken willen gaan maken op subprojectniveau.
We gaan uit van de volgende projectstructuur:
We willen in Power BI de uren van de projecten "Documentatie", "Techniek" en "Website" uitzetten tegen de begrote uren van deze projecten.
Hiervoor moeten we de volgende parameters meegeven in Power BI:
- urenparameters: Bijvoorbeeld start=2020-01-01. Niet perse nodig
- koppelingparameters: Niets
- projectparameters: allprojects=true&project_name_split=1,1&project_id_split=1,1
- medewerkerparameters: Niets.
Regel 228 in het script ziet er dan als volgt uit:
Bron = Contents(false, "start=2020-01-01", "", "allprojects=true&project_name_split=1,1&project_id_split=1,1", "")
Vaak gestelde vragen
Hoe werken de parameters of the Contents functie?
De eerste parameter van deze functie is true of false. Gebruik true als tariefinformatie moet worden opgehaald, en anders false.
De rest van de parameters zijn in url-parameter formaat: Ze worden genoteerd als key=value, met key een van de waardes die in de API-documentatie staat, te vinden op uwomgevingnaam.clockwise.info/api/v2/doc → Reports → Hours in flat format, en value een waarde die daarbij past.
Verschillende key-value-paren worden samengevoegd met een &. Zie ook het voorbeeld in de case hierboven.
Voor de fields parameter specifiek (om specifieke velden op te halen): Deze zijn kommagescheiden. (Bijv. fields=name,code,type). Om velden uit te zetten, kan er een uitroepteken voor worden gezet (Bijv. fields=name,code,!type). Er zijn verschillende veldgroepen, die gebruikt kunnen worden. Deze kunnen op dezelfde manier worden aan- en uitgezet (Bijv. fields=name,projectfields,!otherfields,!type).
Er worden standaard al een paar velden opgehaald! Het kan handig zijn om eerst te kijken welke velden worden opgehaald, en daarna de Contents functie aanpassen om de goede velden aan- en uit te zetten.
Is het ook mogelijk om op Power BI Desktop ClockWise data te gebruiken?
De script die hier wordt gebruikt werkt ook in Power BI Desktop, maar er is een makkelijkere en ietsje veiligere manier, met de ClockWise Dataconnector.
Informatie en instructies hierover kunnen worden gevonden in de Dataconnector handleiding