icon

Power BI Data Connector handleiding

Het is mogelijk om gegevens uit ClockWise te visualiseren in Power BI. Dit kan gedaan worden via de data connector. In deze handleiding wordt uitgelegd hoe deze ingesteld kan worden om de goede gegevens uit ClockWise te halen.

API client aanmaken

Om met Power BI te kunnen werken, moet er een API client aangemaakt worden in ClockWise. Dit kan in Configuratie → Instellingen → OAuth/API clients. Klik op 'OAuth client toevoegen', en geef een naam aan de client (bijv. Power BI), en druk op Opslaan. Let op: We hebben de Client ID en Client secret die hier al staan ingevuld later nodig om de verbinding te kunnen maken. Open de pagina van de API client om deze te kunnen kopiëren/plakken, of noteer deze ergens.

API-Client

Data Connector 'installeren' in Power BI

Download de ClockWise Data Connector versie 1.0 van onze website.

Het bestand met de Data Connector heeft een .mez extensie. Deze moet geplaatst worden in de map 'Documents\Power BI Desktop\Custom Connectors' onder de huidige gebruiker (maak de map of mappen aan als ze nog niet bestaan). Daarnaast moet in Power BI, onder 'Bestand → Opties en instellingen → Opties → Beveiliging → Gegevens extensie → (Niet aanbevolen) Toestaan dat een extensie wordt geladen zonder validatie of waarschuwing' ('File → Options and settings → Options → Security → Data extension → (Not recommended) Allow any extension to load without validation or warning'). Dit zorgt ervoor dat (onder andere) extensies die in de bovengenoemde map staan worden geladen. Herstart Power BI

InstallatieOptiesBeveiliging

In sommige gevallen kan er alleen een signed of trusted connector gebruikt worden. Hiervoor hebben we een self-signed versie met een pqx extensie van de connector beschikbaar met A28548EDB0467E017E48B322C3733FBD4756930E als thumbprint.

Gegevens ophalen met de data connector

Vooraf

Er zijn een paar instellingen, die per bestand worden gemaakt in Power BI. Daaronder vallen een paar opties die de server verlichten. Voornamelijk voor grotere omgevingen is het aan te raden om deze instellingen aan te passen voordat de gegevens opgehaald worden via de dataconnector.

Ga in Power BI naar 'Bestand → Opties en instellingen → Opties → Gegevens laden (onder Huidig Bestand)'
Zet dan de volgende opties uit:

  • Achtergrondgegevens → Voorbeeld van gegevens downloaden op de achtergrond toestaan.
  • Tabellen parallel laden → Tabellen parallel laden inschakelen.

De laatste van deze twee is de belangrijkste van de twee. Deze zorgt er namelijk voor dat er niet vier (mogelijk grote) tabellen tegelijk worden opgehaald waardoor de server overbelast raakt.

Gegevens laden

Connectie maken

Om gegevens op the halen vanaf ClockWise via de Data Connector, moet in Power BI op 'Gegevens ophalen' geklikt worden. Hier is een menu te zien met alle connectoren die bestaan in Power BI. Druk op 'Overig'. Hier staat de data connector van ClockWise, namelijk 'ClockWise v1.0'. Deze connector bevat alle medewerker en projectgegevens, in meerdere tabellen die in relatie staan met de uren en de koppelingen. Selecteer deze connector en klik daarna op 'Verbinden'.

Gegevens ophalen

Daarna komt een popup met 8 velden:

  1. Clockwise account (bedrijfsnaam). Vul hier de naam van uw ClockWise omgevingsnaam in (bijvoorbeeld als u inlogt bij uwomgevingnaam.clockwise.info, dan is uwomgevingnaam de naam die u in zou vullen in dit veld).
  2. Client ID. Vul hier de client id in die is aangemaakt in de API client.
  3. Client Secret. Vul hier de client secret in die is aangemaakt in de API client.
  4. Tarieven ophalen. Dit veld is optioneel, en mag óf leeg blijven, óf de waardes 'true' (waar) of 'false' (onwaar) bevatten. Indien 'true' wordt ingevuld, wordt tariefinformatie opgehaald bij de verschillende gegevens.
  5. Extra parameters voor de uren. Dit veld is optioneel, en mag dus leeggelaten worden. Hier kunnen parameters worden meegegeven zoals de aan de API kunnen worden meegegeven. Kijk hiervoor bij de API-documentatie (ga hiervoor naar uwbedrijfsnaam.clockwise.info/api/v2/doc → Reports → Hours in flat format). Bijvoorbeeld start en einddata kunnen worden meegegeven met start=YYYY-MM-DD&end=YYYY-MM-DD, etc.
  6. Extra parameters voor de koppelingen. Dit werkt op dezelfde manier als hierboven, maar is speciaal voor de koppelingen tabel die opgehaald kan worden door Power BI.
  7. Extra parameters voor de projecten. Idem.
  8. Extra parameters voor de medewerkers.
Contents venster

Inloggen

Het volgende scherm dat wordt getoont de eerste keer dat de verbinding wordt gemaakt, is een inlogscherm. Daar staat de melding dat er nog niet is ingelogd, met een knopje inloggen. Druk hierop. Nu opent een andere scherm met de ClockWise inlogpagina. Log hier in. Dan zegt het inlogscherm dat er ingelogd is. Klik op "Verbinden".

Inloggen

Als er eerder al een keer ingelogd was, en de naam van het ClockWise omgeving, de Client ID en de Client Secret hetzelfde zijn, wordt dit scherm niet getoont en worden de oude inloggegevens gebruikt. In "Bestand → Opties en instellingen → Gegevensbroninstellingen" kunnen bij verschillende data connectors opnieuw worden ingelogd als een andere gebruiker.

Uitkiezen van tabellen

Als de 'ClockWise' data connector wordt aangemaakt, opent nu het volgende scherm, met een keuze uit vier tabellen: Employees, Projects, Resources en Hours. Dit zijn respectievelijk de medewerkergegevens, projectgegevens, gegevens over de koppelingen tussen de medewerkers en projecten, en de gegevens over de uren. Power BI kan een voorvertoning maken van de tabellen, met een paar rijen data en alle kolommen die opgehaald worden, dit is echter afgeraden voor grote omgevingen (Anders moet Power BI de data twee keer ophalen, wat veel druk geeft aan zowel Power BI als de server). Dit kan aan of uit worden gezet in de instellingen vlak boven de vier tabellen.

Navigatievenster

Vink de tabellen die opgehaalt moeten worden aan, en de andere uit, en klik verder. Nu gaat Power BI rekenen, de data ophalen, en de tabellen initialiseren. Als Power BI klaar is kan de data gebruikt worden om grafische voorstellingen te maken.

Alles geladen

Power BI kan de gegevens verversen, dus de connector hoeft niet opnieuw aangemaakt te worden als er bijv. nieuwe projecten worden aangemaakt. Mochten er andere parameters moeten worden ingesteld, bijvoorbeeld als de uren van het huidige jaar werden opgehaald en er is een jaarwisseling, dan moet de connector wel opnieuw aangemaakt worden om de nieuwe parameters in te kunnen stellen.

Instellen van relaties

Bij de 'ClockWise' data connector worden meerdere tabellen geladen. PowerBI probeert zelf de relaties tussen de tabellen te vinden, door de kolommen met dezelfde namen met elkaar te verbinden (de kolom 'hours.resource_id' van de uurtabel wordt bijvoorbeeld gekoppeld met 'resources.resource_id' van de koppelingentabel). Soms lukt dit niet altijd goed, en moet dit handmatig gedaan worden. Ook als er van andere plaatsen data wordt opgehaald die gekoppeld moet worden met de data van ClockWise moet dit handmatig ingesteld worden. Ga hiervoor naar het relatieoverzicht (derde knopje aan de rechterzijde). Daar staan de tabellen afgebeeld, met mogelijk lijntjes tussen de tabellen met óf een 1, óf een * bij de tabellen. Als je met de muis over de lijn gaat worden in de tabellen de namen van de kolommen opgelicht die met elkaar gekoppeld zijn. Om twee tabellen te koppelen (als het lijntje ontbreekt) zijn er twee mogelijkheden: Door een kolomnaam van de ene tabel op de corresponderende kolomnaam van de andere tabel te slepen wordt de koppeling gemaakt. Daarnaast kan ook in het menu bovenin op 'Relaties beheren' worden geklikt. Daar staan alle relaties onder elkaar en kunnen ze aan en uit worden gezet, ze kunnen daar worden aangepast, verwijderd, en nieuwe kunnen worden toegevoegd. Er verschijnt dan een menu met een selectie van de tabellen, een kleine voorvertoning van die tabel, een selectie van de tweede tabel, een kleine voorvertoning van die tabel, en instellingen van de relatie. Selecteer de ene tabel in het bovenste menu, de tweede in het onderste menu en selecteer in de voorvertoningen de kolommen die gekoppeld moeten worden. Druk daarna op 'OK' en de koppeling is aangemaakt.

De koppelingen die aangemaakt (zouden) moeten worden zijn de volgende:
- hours.resource_id ↔ resources.resource_id
- resources.employee_id ↔ employees.employee_id
- resources.project_id ↔ projects.project_id

RelatieRelatie editor

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.

Power BI <=> ClockWise
employees.contract_hours_min Minimale contracturen van medewerker
employees.department_name_path Pad van afdelingsnamen (standaard onderscheiden met ' / ')
employees.employee_email Emailadres van medewerker
employees.employee_name Medewerkernaam
employees.salary_number Salarisnummer van medewerker
hourly_sales_rate Uurtarief verkoop
hourly_purchase_rate Uurtarief inkoop
hours.date Datum
hours.hours Aantal uren
hours.hourstatus Uurstatus (written = beschreven, submitted = ingeleverd, approved = goedgekeurd, rejected = afgekeurd)
hours.units Eenheden
projects.customer_name_path Pad van klantnamen (standaard onderscheiden met ' / ')
projects.end_date Deadline
projects.hours_budgetted Begrote uren
projects.project_name_path Pad van projectnamen (standaard onderscheiden met ' / ')
projects.start_date Startdatum
resources.resource_status Koppelingstatus (running = Lopend, closed = gesloten, in_preparation = in voorbereiding)
employee_id Identifier van de medewerker. Wordt gebruikt om de koppeling- en medewerkertabellen te verbinden
project_id Identifier van de project. Wordt gebruikt om de koppeling- en projecttabellen te verbinden
resource_id Identifier van de koppeling. Wordt gebruikt om de uren- en koppelingtabellen te verbinden

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.

Geadvanceerd: De power query editor

De data connector biedt een aantal functies voor de power query editor: De onderliggende functies van de twee connectoren zijn daar te gebruiken, en nog een derde functie waarmee informatie van een van de API endpoints op te halen is.
Om de editor te gebruiken, klikt u in het 'Gegevens ophalen → Overige' menu op 'Lege query'. De 'Power Query Editor' wordt geopend. Klik daarin op 'Advanced editor'.

Lege query

Er opent een scherm met de tekst (over verschillende regels): 'let Bron = "" in Bron'. Haal de dubbele quotes weg en typ daar "ClockWise_Data_Connector.", met daarachter de functie die u wilt gebruiken.
Er zijn verschillende opties:

  • ClockWise_Data_Connector.Contents. Deze functie is equivalent aan de 'ClockWise' data connector. Ze heeft dezelfde acht argumenten als de data connector. NB: als een parameter leeg moet worden gelaten, dan kan er 'null' worden ingevuld. Deze functie geeft een tabel terug met de vier tabelnamen in de 'Name' kolom, en de 'Data' kolom bevat de geassocieerde tabellen.
  • ClockWise_Data_Connector.GetTable. Deze functie heeft geen geassocieerde data connector. Ze heeft de volgende parameters: instance, client_id, client_secret en url. De eeste drie zijn dezelfde argumenten als de andere functies/data connectors. De vierde argument is de naam van de api v2 endpoint. Dus om bijvoorbeeld alle projecten op te halen via de rapportage endpoint zou de url "/report/flat/projects" kunnen worden gebruikt als laatste argument. Let op: In tegenstelling tot de andere functies is deze vierde argument verplicht, omdat er een valide endpoint moet worden meegegeven. Dat heeft het bij-effect dat Power BI de inloggegevens associeert met de ingevulde URL. Mocht deze in de toekomst aangepast worden, dat moet er opnieuw ingelogd worden.
Geavanceerde editorVoorbeeld GetTable

Voor de volledige documentatie van M, de taal waarmee Power Query werkt, kijk op: https://docs.microsoft.com/nl-nl/powerquery-m/

Case: Sommeren van uren op subproject niveau versus begrote uren op dit niveau

In deze case laten we zien hoe uren gesommeerd kan worden op subproject niveau, terwijl andere informatie van dat subproject behouden kan blijven.
We gaan uit van de volgende projectstructuur:

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.

In Power Bi worden nu de velden project_name_1 (bevat "Nieuwe feature"), project_name_2 (degene waar we in geïnteresseerd zijn) en project_name_3 (Met "Ontwerp", "Implementatie", etc.) opgehaald.
Vink in het menu rechts de velden project_name_1, project_name_2 en hours_budgetted aan. Maak een nieuwe snelle meting:

  • Berekening: Totaal voor de categorie (filters toegepast)
  • Basiswaarde: Som van hours.hours (Sleep hours.hours uit de "Hours" tabel vanuit het scherm rechts naar basiswaarde)
  • Categorie: projects.project_name_3
Snelle meting

Sleep de snelle meting vanuit het menu rechts naar de tabel.
Nu zijn er per subproject twee rijen zichtbaar: één met de som van de uren, en één met de begrote uren. Om dit op te lossen, moet bij "hours.hours_budgetted" in de "Waardes" sectie in de middelste kolom aan de rechterkant de optie "Eerste" worden gekozen (Vlak onder "Niet samenvatten"). Daarmee worden de rijen samengevoegd.

Instellingen begrote uren

N.B. Dit werkt met alle velden van dat projectniveau, niet alleen de begrote uren!

Vaak gestelde vragen

Nadat ik heb ingelogd, geeft PowerBi een foutmelding dat de gedownloade gegevens onverwacht HTML zijn.

Het is mogelijk dat in het bedrijf een whitelist is ingesteld die bepaalde urls blokkeerd. In dit geval wordt de url https://oauth.powerbi.com/views/oauthredirect.html geblokkeerd, waardoor PowerBi het inloggen nooit af kan maken

Hoe moet ik instellen dat Power Bi Server (automatisch) gegevens op kan halen?

Dit kan op twee manieren:

  • Via een 'On-premise gateway'. Microsoft heeft documentatie geschreven hoe dit in te stellen is met een "custom connector", zoals de data connector van ClockWise: Let erop dat dezelfde gegevens ingevuld worden in de gateway als in Power BI Desktop! Power BI matcht de twee op de ClockWise omgevingsnaam, de Client ID en Client Secret.
  • Via een gegevensstroom/dataflow. Hiervoor is een handleiding beschikbaar.