Via een Polaris API koppeling kunnen diverse gegevens worden ontsloten uit Polaris. Door middel van API-calls kunnen via een aantal standaard views of maatwerkconnectoren gegevens worden ontsloten uit Polaris bijvoorbeeld ten behoeve van een Datawarehouse omgeving. In dit artikel worden de mogelijkheden beschreven hoe de gegevens ontsloten kunnen worden.

Oauth

Om van deze functionaliteit gebruik te maken is het noodzakelijk dat er door BCS een (systeem) gebruiker wordt aangemaakt op basis van OAUTH2 authenticatie. In Polaris is de gekoppelde gebruiker vervolgens als type API-gebruiker terug te vinden onder Beheer|Gebruiker

Aan de Polaris API gebruiker kan vervolgens een rol en een populatie worden gekoppeld om toegang te geven tot de standaard views/maatwerk connectoren. Deze views/ en maatwerk connectoren hebben allen een “connectornaam” die vervolgens gebruikt kan worden in de API-call.

Om een data call te kunnen doen moet er eerst een autorisatie token worden opgehaald. Als er een OAUTH 2 gebruiker is aangemaakt, dan zal een medewerker van BCS de credentials hiervoor verstrekken in de vorm van een Client_ID en Client_Secret. Met die credentials kun je via de volgende url een autorisatie token ophalen: https://login.bcs.nl/inloggen/api/authenticate/token
Een voorbeeld aanroep in Powershell vind je aan het einde van dit artikel.

Als je een geldig token hebt teruggekregen, kun je samen met het Client_ID en dit token een data API-call uitvoeren. Hiervoor kun je de volgend basis url gebruiken: https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis

In dit artikel wordt als connectornaam de standaardview qvBasis gebruikt. Deze connector retourneert een aantal persoon gerelateerde gegevens. Aan het einde van dit artikel vind je een voorbeeld script waarmee je in Powershell de gegevens van de standaard view qvBasis uit Polaris kan ontsluiten.

Connectoren

De volgende standaard views/connectoren zijn beschikbaar: 

Naast de standaard views is het ook mogelijk maatwerk views door Polaris te laten ontwikkelen. Ook zijn alle export overzichten als connector in te stellen. Deze zijn separaat in te schakelen bij de rol via het API-tabblad onder Beheer|Rol. Op het tabblad zijn ook een aantal standaard signalen als connector in te schakelen. Let op! Bij signaal connectoren zijn een aantal parameters verplicht (Zie voorbeeld verderop in dit artikel).

Door in de API-call “info” als ConnectorNaam te gebruiken, kun je een overzicht van alle voor de API-gebruiker beschikbare connectoren op te vragen. Dit overzicht geeft daarnaast een opsomming van alle beschikbare velden en datatypes.

Ten behoeve van filtering en of het beperken van de op te halen dataset ondersteunt de API-koppeling de volgende parameters/opties:

Let op! Alle parameters/opties worden gescheiden door een Ampersand(&).

Naast het beperken van de op te halen dataset d.m.v. pagination is het ook mogelijk om elke rubriek uit de dataset te gebruiken in een filter door middel van operatoren.

Let op! Een combinatie van operatoren is mogelijk. Na de rubrieknaam begin je altijd met een = teken. Datums worden omsloten door “.

Let op! Geneste datastructuren zijn niet te filteren op rubrieknamen. Indien je de “Info” van een connector opvraagt krijg je een melding dat column informatie niet beschikbaar is.

Voorbeelden

In deze paragraaf worden een aantal voorbeelden aanroepen gegeven.

• Geef alle connector informatie binnen waar de API-gebruiker recht op heeft: 

https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=info

• Retourneer alle gegevens van connector qvBasis https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis
• Retourneer de structuur van connector qvBasis https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&info=1
• Retourneer de structuur en data van connector qvBasis https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&info=2

Operatoren

• Retourneer data van connector qvBasis waarbij het Persoon_ID groter of gelijk aan 10 is en kleiner dan 100.
• https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&Persoon_ID=>=10&Persoon_ID=<100
• Retourneer data van connector qvBasis waarbij het Persoon_ID gelijk is aan 10.
  https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&Persoon_ID=10
• Retourneer data van connector qvBasis waarbij het woord heer in de VolledigeNaam voorkomt.
  https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&VolledigeNaam=%heer%
• Retourneer data van connector qvBasis waarbij je naar medewerkers zoekt die vanaf een bepaalde datum in dienst zijn. https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&Vanaf=“2020-01-01”

Sortering

• Retourneer data van connector qvBasis waarbij het Persoon_ID groter of gelijk aan 10 en sorteer aflopen op Persoon_ID.
  https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&Persoon_ID=>=10&order=Persoon_ID desc

Pagination

• Retourneer data van connector qvBasis, begin bij regel 20 van de dataset beperk de dataset tot 10 regels.
  https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&limit=20&offset=10
• Retourneer data van connector qvBasis, begin bij regel 100.
  https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&offset=100
• Retourneer data van connector qvBasis, beperk de dataset tot 5 regels.
  https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qvBasis&limit=5

Signalen

• Retourneer data van signaal connector qqJubilea. Parameters Datum, DagenVoor en DagenNa zijn verplicht.
  https://dynamicapi.bcs.nl/dynamicapi/api/dataconnect/koppeling/connector/aansluitingv2/?Connector=qqJubilea&Datum=2026-01-01&DagenVoor=30&DagenNa=30

Voorbeeld aanroep Powershell:

Het advies is om dit voorbeeldscript niet in productie te gebruiken en slechts voor test- en ontwikkeldoeleinden in te zetten, aangezien dit script Client_ID en Client_Secret in platte tekst bevat!

# Haal eerst het token op

$token         = Invoke-RestMethod -Uri "https://login.bcs.nl/inloggen/api/authenticate/token" -Method Post -Body
@{client_id         = ""
  client_secret     = ""
         grant_type        = "client_credentials"
         audience          = "APPLICATION.DYNAMICAPI"
        } | Select-Object -ExpandProperty access_token

# Haal met het token de data op            

$api_response = Invoke-WebRequest  -UseBasicParsing -Uri $api_url -Method Get -
Headers @{"x-BCS-Client_Id" = ""
          "x-Api_Request_Available_Time_Ms"   = 60000
           Authorization = "Bearer $token"
           Accept = "application/xml"
        }

Let op! De werking met uitvoer json is niet altijd betrouwbaar (sortering en volgorde rubrieken)

Als respons op bovenstaande calls worden de gebruikelijke HTTP respons codes gehanteerd. 200 is Succesvol. En in veel gevallen 401 en 403 indien er respectievelijk geen authenticatie is of indien er een connector wordt opgevraagd waar je geen rechten op hebt.

Standaard views

qvAdressen

qvBasis

qvBedrijfsauto

qvCompetenties

qvDienstverband

qvKind

qvRegistraties

qvVerstrekkingen

qvNaam

qvSalaris