Het is mogelijk om data vanuit Anago te ontsluiten met een API koppeling. Hieronder vind je de inhoudsopgave van deze pagina:
Aanvragen
Doorloop de volgende stappen om de API koppeling aan te vragen:
$stappen$
- Geef door via helpdesk.edu@anago.io dat je graag data wilt ontsluiten via de API koppeling.
- Geef ook aan de helpdesk door welke gebruiker de data gaat ontsluiten. Let op: Dit moet een gebruiker zijn die toegang heeft tot alle kostenplaatsen. Dit kan bijv. een controller zijn of een nieuwe gebruiker kan toegevoegd worden aan Anago.
- Vanuit de helpdesk ontvang je de volgende informatie:
- Server: serverXX.cogix.nl
- Applicatienaam: COGIX_KLANTNAAM
- Token: bWlqbm5hYW1Ac2Nob29sYmVzdHV1ci5ubDpkaXRpc21pam5rZXkxMjM=
Let op: bovenstaande gegevens zijn slechts voorbeelden en niet de daadwerkelijke informatie voor het leggen van de koppeling. - Volg onderstaande instructie voor het koppelen met de API.
$/stappen$
Koppelen
Om vervolgens daadwerkelijk te gaan koppelen met de API doorloop je de volgende stappen:
Via de webbrowser:
$stappen$
- Met de aangeleverde gegevens door Anago kun je via een url de koppeling gaan leggen met de API. De URL is als volgt opgebouwd: https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/. Deze is dus opgebouwd met de aangeleverde informatie die via de helpdesk wordt toegestuurd.
- Vervolgens kun je toevoegingen maken aan de url om de volgende gegevens in te kunnen zien:
- Endpoints: hiervoor voeg je …/connectors toe achteraan de url
- Endpoint velden: hiervoor voeg je …/<Endpoint>/fields toe achteraan de url
- Endpoint data: hiervoor voeg je …/<Endpoint>/data toe achteraan de url
Voorbeeld url om de gegevens Endpoint data in te zien: https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/Financieel_Begroting/data -
Voor het eerste request naar een DataConnector endpoint, moet de volgende header worden meegegeven: Authorization: Basic bWlqbm5hYW1Ac2Nob29sYmVzdHV1ci5ubDpkaXRpc21pam5rZXkxMjM=
Voorbeeld van een eerste request:GET https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/Financieel_Begroting/data
Authorization = Basic bWlqbm5hYW1Ac2Nob29sYmVzdHV1ci5ubDpkaXRpc21pam5rZXkxMjM=
-
Het tweede en alle daaropvolgende requests worden gemaakt met de URL verkregen uit de response van het voorgaande request. In de header Authorization wordt het token meegegeven die wordt verkregen uit de response van het eerste request, voorafgegaan door ‘Bearer’.
-
Voorbeeld van een tweede request:
GET https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/ Financieel_Begroting /data?nextPage=ONW6S2VAKCNEXCOBXXQB&pageSize=500
Authorization = Bearer TQCIYE25MEOQ7C7YMBN5
-
De response bestaat uit de volgende velden:
- Data: de lijst met de data records
- Next: de url naar de volgende pagina, indien er nog pagina's met data resteren
- Token: nieuwe Authorization token (alleen bij response op eerste request), deze dient te worden gebruikt bij alle hierop volgende requests
- NumberOfRecords: totaal aantal records
- EndOfData: true als de huidige pagina de laatste records bevat
- Error: heeft een waarde als er een error is opgetreden, anders is dit veld leeg -
De volgende parameters kunnen daarnaast worden meegegeven:
- PageSize: aantal records dat per request wordt opgevraagd, dit veld staat standaard ingesteld op 500.
- IncludeNA: optie om ook records met lege waarden op te vragen, dit veld staat standaard ingesteld als false.
$/stappen$
Via Postman:
$stappen$
- Met de aangeleverde gegevens door Anago kun je via een url de koppeling gaan leggen met de API. De URL is als volgt opgebouwd: https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/. Deze is dus opgebouwd met de aangeleverde informatie die via de helpdesk wordt toegestuurd.
- Vervolgens kun je toevoegingen maken aan de url om de volgende gegevens in te kunnen zien:
- Endpoints: hiervoor voeg je …/connectors toe achteraan de url
- Endpoint velden: hiervoor voeg je …/<Endpoint>/fields toe achteraan de url
- Endpoint data: hiervoor voeg je …/<Endpoint>/data toe achteraan de url
Voorbeeld url om de gegevens Endpoint data in te zien: https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/Financieel_Begroting/data -
Voor het eerste request naar een DataConnector endpoint, moet de volgende header worden meegegeven: Authorization: Basic bWlqbm5hYW1Ac2Nob29sYmVzdHV1ci5ubDpkaXRpc21pam5rZXkxMjM=
Voorbeeld van een eerste request:GET https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/Financieel_Begroting/data
Authorization = Basic bWlqbm5hYW1Ac2Nob29sYmVzdHV1ci5ubDpkaXRpc21pam5rZXkxMjM=
-
Het tweede en alle daaropvolgende requests worden gemaakt met de URL verkregen uit de response van het voorgaande request. In de header Authorization wordt het token meegegeven die wordt verkregen uit de response van het eerste request, voorafgegaan door ‘Bearer’.
-
Voorbeeld van een tweede request:
GET https://serverXX.cogix.nl/dataconnectorapi/COGIX_KLANTNAAM/ Financieel_Begroting /data?nextPage=ONW6S2VAKCNEXCOBXXQB&pageSize=500
Authorization = Bearer TQCIYE25MEOQ7C7YMBN5 -
De response bestaat uit de volgende velden:
- Data: de lijst met de data records
- Next: de url naar de volgende pagina, indien er nog pagina's met data resteren
- Token: nieuwe Authorization token (alleen bij response op eerste request), deze dient te worden gebruikt bij alle hierop volgende requests
- NumberOfRecords: totaal aantal records
- EndOfData: true als de huidige pagina de laatste records bevat
- Error: heeft een waarde als er een error is opgetreden, anders is dit veld leeg -
De volgende parameters kunnen daarnaast worden meegegeven:
- PageSize: aantal records dat per request wordt opgevraagd, dit veld staat standaard ingesteld op 500.
- IncludeNA: optie om ook records met lege waarden op te vragen, dit veld staat standaard ingesteld als false.
$/stappen$
Endpoints
Vanaf januari zijn de volgende endpoints beschikbaar:
API A:
- Kostenplaatsen*: kostenplaatsen met omschrijvingen
- Kostendragers*: kostenplaatsen met omschrijvingen
- Grootboeken*: grootboeken met omschrijvingen en hiërarchie
- Financieel_Begroting*: alleen begroting, scenario basis
- Projecten_Begroting: alleen begroting, scenario basis (indien Project Module afgenomen wordt)
Vanaf maart zijn, tegen een meerprijs, de volgende extra endpoints beschikbaar, naast de standaard endpoints van API A:
API B:
Financieel:
- Financieel_Begrotingsregels: alleen begroting, scenario basis
- Financieel_Volledig: begroting, (roll.)prognose en realisatie, scenario basis
- Financieel_Opmerkingen: opmerkingen, scenario basis
- Financieel_Afslagen (versie met filters): begroting en (roll.)prognose, afslagen zonder basis
- Afslagen: afslagen met omschrijvingen
Activa:
- Activa: activa voor prognose, scenario basis
- Activa_Afschrijvingen: afschrijvingsbedragen voor begroting en prognose, scenario basis
Bekostiging:
- Leerlingaantallen: prognose, scenario basis
Personeel (MDW):
- Personeel_Begroting: alleen begroting, scenario basis
- Personeel_Volledig: begroting, prognose en realisatie, scenario basis
- Personeel_Opmerkingen: opmerkingen, scenario basis
- Personeel_Afslagen (versie met filters): begroting en prognose, afslagen zonder basis
- Afslagen: afslagen met omschrijvingen
Projectmodule (indien deze aparte module afgenomen wordt):
- Projecten_Volledig: begroting, prognose en realisatie, scenario basis
- Projecten_Begrotingsregels: alleen begroting, scenario basis
$note$
Let op: Dit is een eerste oplevering van de API koppeling. In een volgende versie worden de volgende verbeteringen doorgevoerd:
- Er is nu één API URL en dit wordt aangepast naar een aparte login URL en een aparte instance URL. Er moet dan eerst door middel van een POST request op de login URL toegang worden gevraagd met de door Anago aangeleverde token. In de response wordt de instance URL en de access token verkregen, waarmee vervolgens de dataconnector endpoints kunnen worden aangeroepen.
- Er zullen aanvullende parameters per endpoint beschikbaar zijn om de data te kunnen filteren, bijvoorbeeld op afslag of op jaar.
$/note$