Simployer Analytics API

Endret Mon, 23 Jun ved 2:00 PM

Analytics API er et REST API som gjør det mulig for våre kunder å lese og analysere sine Simployer HRM-data. Analytics API implementerer OData åpen standard. Det kan nås via ulike tredjepartsverktøy som Excel, Power BI, samt integreres i kundens interne systemer.

Hvordan bruke Analytics API

URL

OData-endepunkt:

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

Dokumentasjon/testside (se Swagger UI-seksjonen senere i dokumentet):

https://analytics-api.simployer.com/swagger

Bruk i Self-Service BI-verktøy

For spesifikke SSBI-verktøy bør brukeren sjekke om det støtter OData Feed. Alternativt kan API-et behandles som typiske REST-endepunkter, men merk at API-et har pagineringsmekanisme og en grense for antall resultater per spørring (se FAQ lengre ned for mer info).

Autentiseringsmetode

Analytics API støtter SimplAuth autentiseringsprotokoll.

Se denne siden for mer informasjon: SimplAuth.

Excel, Power BI

Nedenfor finner du eksempel på hvordan autentisere og koble til Analytics API med Excel. For Power BI er prosessen lik, siden begge bruker Power Query.

Dette er en god måte å starte interaksjonen med Analytics API på. Det finnes en mer detaljert guide for hvordan sette opp Power Query til autentisering og datainnhenting her: Connect API through Power Query.

Gå til Data > Hent data > Fra andre kilder > Fra web

I popup-vinduet velger du "Avansert" og legger inn nødvendig informasjon som vist nedenfor:

Nytt vindu åpnes med hentede data:

Deretter kan du bore ned og konvertere responsen til tabell.

OData-standard

Analytics API er et REST API basert på åpen data-protokoll OData V4. Denne protokollen tillater bruk av flere funksjoner:

$filter - begrenser settet av returnerte elementer. Maksimalt 100 uttrykk.
$orderby - spesifiserer rekkefølgen elementene returneres i.
$top - begrenser antall elementer som returneres.
$skip - ekskluderer et spesifisert antall elementer fra resultatet.
$count - angir om totalantallet elementer i en samling skal returneres.
$expand - inkluderer relaterte enheter inline. Maks dybde er 2.
$select - begrenser hvilke egenskaper som returneres.

Alle disse funksjonene er beskrevet i OData-dokumentasjonen her: https://www.odata.org/getting-started/basic-tutorial/. Under følger vanlige brukstilfeller.

Swagger UI

Løsningen har integrert Swagger UI som lar brukeren teste endepunkter før tilkobling med Self-Service BI-løsninger.

Oversikt over Swagger UI

Alle tilgjengelige endepunkter listes i Swagger UI, inkludert tilhørende skjemaer. Under er eksempel med et begrenset antall enheter:

Ved å utvide skjemaer ser brukeren detaljerte beskrivelser av hver egenskap. Referanser til andre enheter vises også som utvidbare egenskaper – se for eksempel absences, immediateSupervisor, affiliationUnit, employees og directReports nedenfor. Disse kan brukes med $expand-funksjonen i OData for å inkludere refererte enheter i resultatet.

Bruk av Swagger UI

For å bruke Swagger UI må brukeren være autorisert. Dette gjøres via knappen Authorize rett over endepunktlisten. Brukeren blir bedt om å autorisere.

Når autorisert, kan man teste Analytics API-endepunkter med knappen Try it out (tilgjengelig når man utvider hvert endepunkt). Eksempel under:

Ifølge eksempelet vil vi hente én person (sk=1) inkludert detaljer for tilknyttet enhet. For begge enhetene begrenser vi returnerte egenskaper til et fåtall kolonner (dette kan være nestet med $expand). Eksempel på respons fra Analytics API:

FAQ

Jeg får Unauthorized (401) feil ved tilkobling til OData-endepunktet.

Følg instruksjoner for ditt verktøy:

Nettleser: Kan ikke brukes til å benytte OData-endepunkt, kun spesialiserte applikasjoner (Excel, Power BI osv.). For å utforske datamodell eller dokumentasjon i nettleser, bruk Swagger UI tilgjengelig som eget endepunkt (URL seksjonen finnes i dokumentet).
BI-verktøy: Se Excel, Power BI-seksjonen for å sikre at riktige parametere er brukt ved tilkobling.
Swagger UI: Sørg for korrekt token ved Authorize-knappen før kall til endepunkt.

Sjekk at du genererer SimplAuth-token for riktig audience (https://analytics-api.simployer.com). Token generert for andre audience (f.eks. HrConnect) godkjennes ikke.

Hvor finner jeg datamodellens dokumentasjon?

Dokumentasjonen finnes i Swagger UI under "Schemas", like under listen over endepunkter.

Hvordan bruke filter i spørring?

Bruk "$filter" i spørringen. For eksempel, for å velge Person med fornavn "Anna":
v1/Person?$filter=firstName eq 'Anna'.

Andre logiske filteroperatorer finnes i OData URL Conventions-dokumentet.

Hvordan inkludere relaterte enheter i resultatet?

Bruk "$expand" i spørringen. Se OData-tutorial og Swagger UI-seksjon. For eksempel, for Person med tilknyttet enhet:

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

Men om du klikker for å utvide, vil de ikke være fylt ut:

For å fikse dette, bruk $expand og angi enheten som skal utvides:

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

Datasettet mitt er stort, og jeg får ikke all data fra endepunktet. Hvorfor?

API-et bruker pagineringsmekanisme med maks 100 000 rader per spørring. OData-kontakter som Power BI håndterer dette automatisk. Ved manuell bruk kan du:

Bruke @odata.nextLink i responsen for å hente neste side
Bruke $skip for å hente neste side

Jeg får svarkode 429 (Too Many Requests)

Analytics API har rate limiting for å unngå overbelastning og sikre ytelse. Maks 30 forespørsler per minutt.