Les og analyser data fra Simployer Classic HRM via OData, Excel, Power BI eller egne systemer.

Analytics API er et REST API som gjør det mulig å lese og analysere data fra Simployer Classic HRM. Analytics API implementerer den åpne standarden OData. Du kan bruke Analytics API med tredjepartsverktøy som Excel og Power BI eller konsumere API-et direkte fra egne systemer.

For dokumentasjon om autentisering med SimplAuth API, se artikkelen om SimplAuth.

Slik bruker du Analytics API

URL-er for Analytics API

OData-endepunkt: https://analytics-api.simployer.com/

Dokumentasjons- og testside: https://analytics-api.simployer.com/swagger

Se delen om Swagger UI nedenfor for mer informasjon om dokumentasjons- og testsiden.

Bruk Analytics API med Self-Service BI-verktøy

For et spesifikt Self-Service BI-verktøy bør du kontrollere om verktøyet støtter OData Feed. Alternativt kan du bruke Analytics API som et vanlig REST-endepunkt.

Analytics API bruker paginering og har en grense for antall resultater per forespørsel. Se FAQ-delen for detaljer.

Autentiser mot Analytics API

Analytics API støtter autentiseringsprotokollen SimplAuth. Se artikkelen om SimplAuth for detaljer.

Koble Excel eller Power BI til Analytics API

Følgende fremgangsmåte viser hvordan du autentiserer og kobler til Analytics API med Excel. Fremgangsmåten er tilsvarende i Power BI fordi begge løsningene bruker Power Query.

Se artikkelen "Koble til HRConnect API via Power Query (Excel/Power BI)" for en mer detaljert guide til å konfigurere Power Query for autentisering og datahenting.

1. Gå til Data → Get Data → From Other Sources → From Web
2. Velg Advanced i popup-vinduet og fyll inn nødvendig informasjon

Et nytt vindu åpnes med dataene som er hentet. Deretter kan du gjøre responsen om til en tabell.

Bruk OData V4-standarden med Analytics API

Analytics API er et REST API basert på den åpne protokollen OData V4. Protokollen støtter følgende funksjoner:

• $filter begrenser hvilke elementer som returneres. Maksimalt antall uttrykk er 100.
• $orderby angir sorteringsrekkefølgen for returnerte elementer
• $top begrenser antall elementer som returneres fra en samling
• $skip utelater et angitt antall elementer fra starten av resultatsettet
• $count angir om totalt antall elementer i en samling skal returneres i resultatet
• $expand angir relaterte entiteter som skal inkluderes direkte i resultatet. Maksimal dybde er 2.
• $select begrenser hvilke egenskaper som returneres i resultatet

Disse funksjonene er beskrevet i OData-dokumentasjonen.

Test Analytics API med Swagger UI

Analytics API har en integrert Swagger UI som lar deg teste endepunktene før du kobler til med et Self-Service BI-verktøy.

Swagger UI viser alle tilgjengelige endepunkter og tilhørende skjemaer (schemas). Utvid et skjema for å se en detaljert beskrivelse av hver egenskap.

Referanser til andre entiteter, som absences, immediateSupervisor, affiliationUnit, employees og directReports, vises som ekspanderbare egenskaper. Bruk disse egenskapene med OData-funksjonen $expand for å inkludere relaterte entiteter i resultatsettet.

Gjør Analytics API-kall i Swagger UI

Du må være autorisert før du kan bruke Swagger UI til å gjøre kall mot Analytics API-endepunktene.

1. Velg Authorize over listen over endepunkter
2. Følg instruksjonene for å autorisere
3. Utvid et endepunkt og velg Try it out for å teste det

Du kan for eksempel hente én person (sk = 1) og inkludere detaljer om personens affiliationUnit. For begge entitetene kan du begrense egenskapene som returneres, til et fåtall kolonner. Dette kan nestes i $expand-funksjonen.

Vanlige spørsmål om Analytics API

Hvorfor får jeg feilen Unauthorized (401) når jeg kobler til OData-endepunktet for Analytics API?

Følg instruksjonene for verktøyet du bruker:

• Nettleser: Du kan ikke bruke en nettleser til å hente data fra OData-endepunktet. Bruk en spesialisert applikasjon som Excel eller Power BI. Hvis du vil utforske datamodellen eller dokumentasjonen i en nettleser, kan du bruke Swagger UI, som er tilgjengelig via et separat endepunkt.
• Spesialisert BI-verktøy: Se delen om Excel og Power BI, og kontroller at du har angitt riktige parametere for tilkoblingen.
• Swagger UI: Kontroller at du har angitt riktig token når du velger Authorize, før du kaller et endepunkt.

Når du genererer et SimplAuth-token, må du kontrollere at du målretter mot riktig audience: https://analytics-api.simployer.com. Tokens som er generert for en annen audience, for eksempel HRConnect, blir ikke autorisert i Analytics API.

Hvor finner jeg dokumentasjon for datamodellen i Analytics API?

Dokumentasjonen for datamodellen i Analytics API er tilgjengelig i Swagger UI. Du finner den i delen Schemas, under listen over endepunkter.

Hvordan bruker jeg $filter i en Analytics API-forespørsel?

Bruk nøkkelordet $filter i forespørselen. Se OData-tutorialen for detaljer.

Du kan for eksempel bruke følgende filter for å returnere bare personer med fornavnet Anna:

v1/Person?$filter=firstName eq 'Anna'

Andre logiske filteroperatorer er også tilgjengelige. Se dokumentet OData URL Conventions for en fullstendig liste.

Hvordan inkluderer jeg relaterte entiteter i et Analytics API-resultat?

Bruk nøkkelordet $expand i forespørselen. Når du henter data for en entitet med en konfigurert relasjon, for eksempel Person, kan Excel vise flere kolonner, for eksempel affiliationUnit.

Eksempel på forespørsel:

https://analytics-api.simployer.com/v1/person?$filter=sk eq 1

Uten $expand blir ikke det relaterte feltet fylt ut. Legg til $expand og angi entiteten for å inkludere den relaterte entiteten:

https://analytics-api.simployer.com/v1/person?$filter=sk eq 1&$expand=affiliationUnit

Hvorfor returnerer ikke Analytics API all data fra det store datasettet mitt?

Analytics API bruker OData sin pagineringsmekanisme. Du kan hente et begrenset antall poster per forespørsel. Grensen er for øyeblikket 100 000 rader.

OData-tilkoblinger, som tilkoblingen i Power BI, skal vanligvis håndtere pagineringen automatisk. Hvis du bruker Analytics API manuelt, har du to alternativer:

• @odata.nextLink: Bruk dette feltet fra responsen for å hente URL-en til neste side med poster.
• $skip: Bruk dette nøkkelordet i forespørselen for å hente neste side med poster.

Hvorfor får jeg responskode 429 (Too Many Requests) fra Analytics API?

Analytics API bruker hastighetsbegrensning (rate limiting) for å forhindre misbruk og opprettholde ytelsen for alle kunder. Grensen er for øyeblikket 30 forespørsler per minutt.