Power BI Gegevensstroom handleiding

Het is mogelijk om gegevens uit ClockWise te visualiseren op de online versie van Power BI. Dit kan gedaan worden via een gegevensstroom. In deze handleiding wordt uitgelegd hoe deze ingesteld kan worden om de goede gegevens uit ClockWise te halen.

1. 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'. Geef een herkenbare naam aan de client, wat aangeeft waar het voor gebruikt wordt (bijv. Power BI), en vul hier ook de emailadres van de connectorbeheerder in.
Druk op Opslaan.

Zet de optie "Access token expires" op "Never". De access token die in een volgende stap wordt opgehaald wordt steeds gebruikt om de data op te vragen.

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 hievoor 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 op "Request".

U wordt doorgestuurd naar de inlogpagina van ClockWise. Log in zoals normaal ook wordt gedaan.

Als het inloggen is voltooid, wordt een nieuwe pagina getoond. Op deze nieuwe pagina wordt aan de onderkant een code wordt getoond:

Deze code is nodig voor de volgende stap

3. Het opvragen van een accesstoken

We hebben nu een access token nodig. Dit werkt ongeveer hetzelfde als de stappen hierboven, alleen is nu de knop "Request Tokens" nodig.

De standaardgegevens staan weer goed, alleen moet de autorisatiecode nog wel worden ingevoerd in het veld authorization code. Dat is de code uit de vorige stap.

Klik op "Request"

Er wordt nu een venster zichtbaar met een access_token, refresh_token en wat andere informatie. Hiervan is de access_token nodig voor de volgende stappen.

Deze token is onbeperkt geldig, wegens de "Access token expires"-instelling uit de eerste stap

4. De query voorbereiden

De autorisatiecode is niet meer nodig, dus de tijdsbeperking van een uur geldt niet meer

Download het bestand ServerDataConnector.m van onze website. Open het in een tekstbewerker (bijv. notepad).

In dit bestand komt "uwomgevingnaam" voor, rond regel 26. Dit moet vervangen worden door de naam van de ClockWise omgeving.

Daarnaast staat op regel 3 tussen aanhalingstekens de tekst **access token**. Dit (inclusief de sterretjes, exclusief de aanhalingstekens) moet vervangen worden door de verkregen access token uit de vorige stap.

Indien gewenst kunnen er parameters worden meegegeven aan de verschillende tabellen, vergelijkbaar met de parameters uit de ClockWise Dataconnector.
Deze kunnen worden ingesteld in de Contents() functieaanroep op regel 228. Deze heeft een aantal parameters:

• De eerste is of de tarieven moeten worden opgehaald (true of false, standaard false)
• De parameters daarna zijn om de extra argumenten voor respectievelijk de uren, koppelingen, projecten en medewerkers. Deze moeten tussen aanhalingstekens (") worden opgegeven, als URL-parameter (bijv. "all_projects=true&project_name_split=1,1"). Uitleg over de verschillende velden kan worden gevonden bij de API-documentatie. Ga hiervoor naar "uwomgevingnaam.clockwise.info/api/v2/doc" → Reports → "Hours in flat format", waarbij uwomgevingnaam weer de naam is van de ClockWise omgeving.

Sla de aanpassingen op.

5. Power BI initiëren

Nu kunnen we de gegevensstroom aanmaken.

Log in de browser in op de online omgeving van Power BI en ga naar de werkruimte/workspace waar de gegevensstroom/dataflow moet worden aangemaakt.

LET OP: Dit kan niet in een persoonlijke werkruimte

• Klik op "+ Nieuw" → "Gegevensstroom"
• Klik op "Nieuwe tabellen definiëren (Meest linker optie).
• Er wordt een pagina met gegevensbronnen getoond, ergens onderaan staat "Lege query". Klik hierop

Er wordt een query getoon met een tekst als

let
  Bron=""
in
  Bron

(of met Source) in de Engelse versie.
Laat dit 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 dit te omzeilen
• Ga vervolgens naar de "Start" tab, kijk bij "Query" en klik op "Geavanceerde editor".

De editor die u nu opent lijk op degene die eerder werd getoond, met een paar extra regels.

• Haal alles weg wat hier staat.
• Kopieer de inhoud van het bestand van de vorige stap (na de aanpassingen) in het tekstveld.
• Klik op OK

Belangrijk

Klik met de rechtermuisknop op de query (in de linker kolom), en zorg dat het vinkje bij "Laden inschakelen" uit staat! Er zitten moeilijke types in de query, en PowerBI kan er (nog) niets mee.

6. Query's vullen met informatie uit ClockWise

We gaan nu wat met deze query doen om de losse tabellen 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 (met een getal op de puntjes)

• Klik in de nieuwe aangemaakte Query (als hij geladen is) op de tekst 'Tabel' (of 'Table') rechts van het vakje met "Employees" (of datgene wat opgevraagd wenst te worden). Na wat rekenen wordt de medewerkerstabel getoond.

Doe deze 3 stappen nog 3 keer, voor respectievelijk "Projects", "Resources" en "Hours".
Let op: Zorg dat de selectie steeds gemaakt worden van de nieuwe "Query (...)", en niet van de orginele "Query"! Anders kunnen de andere query's de data niet ophalen, omdat ze allemaal verwijzen naar de oorspronkelijke.
Tip! *Het is overzichtelijker als de verschillende query's hernoemd worden naar de tabel die daar geselecteerd is, bijv. "Query (2)" kan worden hernoemd naar "Employee". Dit kan in de rechterkolom.

Als het goed is kan nu de gegevensstroom worden opgeslagen. Het valideren 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:

• 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 toch al)
• Soms vraag 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 "uwbedrijfsnaam.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 de omgeving gelezen kan worden. Ga naar de desbetreffende Query en klik op 'Veiligheidsinstellingen uitschakelen'.

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.

Geavanceerd: Een stapje verder met de tabellen

Het is ook mogelijk om andere tabellen of endpoints aan te roepen in een gegevensstroom, net zoals met de GetTable functie in het 'Geavanceerd' hoofdstukje in de ClockWise Dataconnector handleiding. Dit gaat met de ParsedTable(url) functie.
Er zijn twee manieren om dit te doen:

• In een nieuwe query in de gegevensstroom kan de "ServerDataConnector.m" uit stap 4. opnieuw worden geladen, maar in plaats van Bron = Contents() op regel 228 moet er staan Bron = ParsedTable(*url*) (bijv. Bron = ParsedTable("/report/flat/planning?params=hier")).
• De andere optie is om het bestand ServerDataConnector_gettable.m te gebruiken. Hierin moeten dan soortgelijke aanpassingen worden gedaan als in stap 4.
  • Daarnaast kan op regel 83 de URL worden ingevuld in de functie GetTable. Daar staat bovengenoemd voorbeeld al 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 waarschuwingen 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 standaardtype als PowerBI zelf niets kon vinden)
• Als helemaal zeker is dat deze kolom alleen getallen bevat, kan ook het type decimaal getal of geheel getal worden gekozen.

Let op: De gegevensstroom kan niet worden opgeslagen zolang er fouten worden gegeven over kolommen zonder types!

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

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", "")

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

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