Eens je de nodige rechten hebt kan je fiches aanmaken in het DOV-portaal. Dit kan a) manueel via het DOV-portaal, b) in bulk door bestanden op te laden in het DOV-portaal, of c) door automatische uitwisseling via DOV-services. Deze pagina beschrijft stap-voor-stap hoe de automatische uitwisseling via DOV-services gebeurt (optie c).

Algemene info over gebruik van DOV-services is ook te vinden op de pagina "synchronisatie - gebruik DOV-webservices". Er is een voorbeeldscript te vinden waarin putten, filters en instrumenten worden aangemaakt en uitgelezen via Python. Dit script kan gedownload worden via de link https://www.milieuinfo.be/confluence/download/attachments/160110598/instrumenten_api_demoscript-master.zip?api=v2. 

1. Een XML-bestand opladen via XML-webservice

Dit werkt voor een hele reeks objecten: boring, put, filter, grondwaterlocatie, manuele metingen, ...

Stap 1: maak een XML-bestand aan

In het XML-bestand maak je een XML-object aan. Dit XML-object start met een specifieke tag (<grondwaterlocatie> voor put-objecten, en <filter> voor filter-objecten). Tussen de start- en eindtag van het object (bv. <filter> en </filter>) worden de andere  eigenschappen van het object toegevoegd met hun eigen tags. Deze tags zijn specifiek voor DOV en worden gecontrolleerd via een XSD-bestand, waarin gedocumenteerd wordt welke tags toegelaten zijn, en wat ze precies betekenen. Er is een apart XSD-bestand voor objecten van het grondwatermeetnet. Meer informatie over validatie van XML-bestanden en het XML-formaat van DOV is te vinden op de pagina over het xml-import-uitwisselingsformaat.

• Het formaat van het XML-bestand luistert redelijk nauw: zo moet elke begintag ook afgesloten worden met een eindtag. Indien er geen geneste tags voorkomen kan ook gebruikt gemaakt worden van de verkorte notatie (bv. <filter />). 
• Je kan een apart XML-bestand aanmaken voor elke apart object, of alle XML-objecten samenvoegen in één bestand. Putten, Filters en peilmetingen worden als aparte objecten toegevoegd (dus een filter is geen genest object van een put, een peilmeting is geen genest object van een filter).  

Voorbeeld van XML-bestanden en een oplijsting van de belangrijkste velden die je moet meegeven, kan je vinden op de pagina "Data toevoegen via XML-bestanden"

Stap 2: XML inladen via DOV-services

Het algemene stappenplan staat uitgelegd op de pagina "Case 1: Opladen van XML-bestanden voor boorbedrijven"

Er is een voorbeeldscript beschikbaar op XXXX  Nog aan te vullen

2. Een JSON-bestand opladen via RESTfull API 

Dit werkt momenteel enkel voor instrumenten, sensoren en links tussen sensor/gwlocatie. 

Relevante info is te vinden in de API-guide. Specifiek moet je kijken naar volgende demo's:

• Voor het aanmaken van een instrument (en sensoren), bekijk Demo 8 .
• Voor het linken van een instrument/sensor aan een filter, bekijk Demo 9
• Voor het opladen van sensordata in json-formaat, bekijk Demo 4

Op deze pagina's staan telkens een uitgewerkt voorbeeld van het json-bestand dat in een POST-request moet worden meegegeven, en een tabel waarin alle velden worden opgelijst en beschreven. 

Enkele nuttige tips: 

• Een aantal velden verwachten een waarde uit een codelijst. Andere waardes zijn niet toegelaten. De codelijsten met toegelaten waardes zijn voorlopig nog niet gestructureerd gedocumenteerd. Maar onderstaande tabel geeft voor enkele van de velden een API-call waarmee de codelijst kan opgevraagd worden (opgelet: deze api-calls zijn intern bedoeld, en kunnen dus onverwacht wijzigen). Voor een aantal velden kan dit ook teruggevonden worden in de XSD-bestanden die voor XML-bestanden gebruikt worden.
  Opgelet: de api-calls hieronder zijn voor de productie-omgeving. Voor de oefen-omgeving moet de base-url worden aangepast naar  XXXX  Nog aan te vullen
• een veld 'code' of 'id' bevat altijd een string, dus met quotes. Ook als dit een getal bevat, bv. "code": "4". 
• datumformaat is anders dan in XML: nl. dd-mm-yyyy HH:MM:SS (en niet yyyy-mm-dd zoals in de XML-bestanden). De tijdscomponent is verplicht.

3.1 Tips en Troubleshooting

Hieronder enkele fouten die kunnen voorkomen: 

• Wanneer je een nieuw instrument probeert aan te maken: "Access is denied"
  • Test of de certificaten goed werken via de healthcheck "/chucknorris". 
  • Kijk het object 'Databeheerder' na: dit ziet er als volgt uit:   "databeheerder": { "id": "8", "kbonummer": "OVO000092", "naam": "VMM" }. Gebruik de call uit de tabel hierboven om een lijst te krijgen met alle databeheerders, Zoek naar je eigen databeheerder, daarin staat het juiste formaat. 
• Wanneer je een nieuw instrument probeert aan te maken: "Referentie moet uniek zijn binnen organisatie" of "Er bestaat reeds een instrument met serienummer xxxxx":
  
  • Het veld 'referentie' en 'serienummer' moet uniek zijn. Je kan dus geen twee instrumenten hebben met exact dezelfde referentie en/of serienummer.
  • Ofwel heb je geprobeerd hetzelfde instrument opnieuw aan te maken van scratch, dat lukt dus niet omdat het al bestaat. Verwijder het bestaande instrument eerst, alvorens je het opnieuw aanmaakt. Je kan ook de permkey van het instrument meegeven in de json. Dan wordt dit beschouwd als een update-operatie, en worden alle velden overschreven met de nieuwe waarde. 
  • Ofwel heb je geprobeerd een instrument aan te maken met een referentie die al bij een ander instrument gebruikt wordt. In dat geval kan je bv. de serienummer toevoegen aan de referentie om de string uniek te maken. 
• Wanneer je een nieuw instrument probeert aan te maken: "Sensoridentificatie niet mogelijk aan het instrument.":
  • Gebruik de call uit tabel hierboven voor de codetabel sensoridentificatie. Kijk na of de combinatie sensortype (jsonlocatie=sensordata>sensoren>sensorIdentificatie>code) en instrument type (jsonlocatie=metadata>type>code) voorkomt in de lijst. Indien niet, best DOV contacteren om dit te laten rechtzetten. 
• Wanneer je een instrument probeert te koppelen aan een grondwater- of bodemlocatie: "Unparseable date: "2020-06-01"
  • het datum-formaat in de json-bestanden is dd-mm-yyyy HH:MM:SS (en niet yyyy-mm-dd zoals in de XML-bestanden). Het tijdscomponent is verplicht.

3. Een CSV-bestand opladen via RESTfull API

Dit werkt voor HF-metingen (loggermetingen). 

Consulteer de API-guide → Demo 4 . In de demo zoeken naar de subtitel 'CSV bestand'. 

Stap 1: aanmaken van een CSV-bestand

Het formaat staat beschreven in Bulkingave via het DOV-portaal#Stap1:maakeencsv-bestandaan

Stap 2: CSV-bestand opladen via REST-services

Via een POST-request wordt het CSV-bestand opgeladen naar de server. Daar komt het in een verwerkingsqueue. Het kan dus even duren voor de nieuwe data verwerkt wordt, en zichtbaar wordt in schermen (typisch 1 tot enkele minuten). De POST-request geeft een ImportLogID terug, waarmee de status van de verwerkingsjob kan opgevraagd worden.

• API-call om CSV-bestand op te laden: POST /hfmetingen/instrumenten/{idOrPermkey}/sensoren/{sensorIdOrPermkey}/meetpunten
• API-call om de status van de verwerkingsjob op te vragen: GET /hfmetingen/importlog/{id}