Reference: API – udveksling af data

INNOMATE HR tilbyder adgang til alle data gennem et såkaldt API (Application Programming Interface), som muliggør udveksling af data mellem INNOMATE HR og andre IT-systemer.

Det er muligt både at trække data ud af INNOMATE HR og lægge data ind. På den måde kan der bygges integrationer, hvor andre systemer henter data fra INNOMATE HR til f.eks. rapportering eller opdatering af stamdata, eller hvor I opdaterer data i INNOMATE HR fra andre systemer.

Opret API-nøgle

Adgang til API'et sker ved hjælp af en API-nøgle. En person med administratoradgang kan finde og oprette API-nøgler fra menuen Indstillinger:

Når du opretter en ny nøgle, skal du tage stilling til, hvad den må tilgå. En ny nøgle har ingen adgang, før du har valgt. Du kan enten:

• vælge én eller flere datatyper og de handlinger, nøglen må udføre på dem, eller
• sætte hak i Giv denne nøgle adgang til alle data.

Dialogen gemmer ikke en ny nøgle, der hverken har adgang til alle data eller til mindst én datatype. Se Adgang for API-nøgler nedenfor.

På siden er der også et link til den tekniske dokumentation og hvorfra man ved hjælp af en API-nøgle kan teste mulighederne. Klik her.

Adgang for API-nøgler

Hver API-nøgle har en adgang, der bestemmer, hvilke datatyper nøglen kan bruges til, og hvilke handlinger den må udføre. Adgangen gælder både for OData-API'et og for webhooks. Du ser og ændrer adgangen ved at klikke på redigeringsikonet ud for nøglen på siden API nøgler.

I listen over nøgler kan du se nøglens adgang:

Visning	Betydning
Adgang: alle data	Nøglen kan læse og ændre alle data, API'et udstiller.
Adgang: n datatype(r)	Nøglen er begrænset til de valgte datatyper og handlinger.
Adgang: ingen	Nøglen kan ingenting. Nøglen findes stadig og kan få adgang igen senere.

Handlinger

For hver datatype vælger du én eller flere handlinger:

Handling	Betydning	HTTP-metode
Get	Læse data	GET
Post	Oprette data – og tilføje eller fjerne elementer i en samling på en eksisterende post	POST
Patch	Opdatere eksisterende data	PATCH
Delete	Slette data	DELETE

Opdatering og sletning læser altid posten først. Derfor bliver Get valgt automatisk, når du vælger Patch eller Delete, og fjerner du Get, fjernes Patch og Delete også. Post kræver ikke læseadgang og kan vælges alene.

Ikke alle datatyper tilbyder alle handlinger. Webhooks tilbyder f.eks. kun Post og Delete.

Relaterede data og delte typer

Henter du relaterede data med $expand, skal nøglen have Get på hver af de datatyper, du udvider til – ikke kun på den datatype, du starter fra.

Nogle links kan pege på flere slags data. En overordnet i en relation kan f.eks. være en person, en enhed eller en stilling. Sådanne links peger på en fælles type, som er markeret med delt type i listen over datatyper. For at hente data gennem et sådant link skal nøglen have Get på den delte type. Delte typer tilbyder kun Get.

Når en nøgle ikke har adgang

Forsøger en integration at bruge data eller handlinger uden for nøglens adgang, svarer API'et med HTTP-statuskode 403 Forbidden. Svaret angiver, hvilken datatype og handling der mangler adgang til.

Eksisterende nøgler

Nøgler, der blev oprettet før adgangsstyringen blev indført, har fortsat adgang til alle data. Det betyder, at eksisterende integrationer fortsætter uændret. Vi anbefaler, at du gennemgår jeres nøgler og begrænser hver nøgle til det, integrationen faktisk bruger – f.eks. kun Get til en nøgle, der bruges til udtræk til Business Intelligence.

Midlertidigt spærre en nøgle

Vil du spærre en nøgle uden at slette den, kan du fjerne alle valgte datatyper, så nøglen viser Adgang: ingen. Nøglen kan derefter ingenting, indtil du giver den adgang igen.

Det virker kun, hvis nøglen ikke har adgang, som editoren ikke kan vise (se nedenfor). Den adgang bevares, når du gemmer, så nøglen kan stadig bruges. Skriver dialogen, at nøglen har sådan adgang, skal du i stedet slette nøglen.

Adgang, som editoren ikke kan vise

En nøgle kan have adgang, som ikke kan vises i listen over datatyper – f.eks. adgang til alle datatyper på én gang for en bestemt handling eller adgang til en datatype, som API'et ikke længere udstiller. Dialogen oplyser, når det er tilfældet, og den adgang bevares uændret, når du gemmer.

OData-protokol

INNOMATE HR bruger OData-protokollen til API'et. Det er en protokol, der giver mulighed for bl.a. detaljeret filtrering af data, så man nemmere kan få lige præcis de data, man leder efter.

Webhooks

Det er muligt at oprette webhooks fra både brugergrænsefladen og API'et. Webhooks sættes op, så systemet – på baggrund af opståede hændelser – skubber notifikationer ud til relevante integrationsløsninger. Opståede hændelser kan f.eks. være, at person-stamdata er ændret, eller at en ansættelse er blevet oprettet.

Kom godt i gang

Vi er naturligvis behjælpelige med bistand i brugen af vores API.

Da INNOMATE HR løbende udvikler sig, vil der også tilsvarende komme ændringer af output. Hvis I mangler en OData-feature i vores API eller finder en fejl, vil vi meget gerne høre om det.

Kontakt os på support@innomate.com.

Se også

• CASE: Udtræk fra API til Business Intelligence — brug API'et med Power BI
• Teknisk dokumentation: Send fra scanner — send filer via SFTP
• Public Jobs API — reference til det offentlige API, der returnerer jobopslag fra en jobportal