Deze pagina geeft een overzicht van de stappen die doorlopen moeten worden om een XML-bestand op te laden naar DOV.
In onderstaande voorbeelden wordt steeds gebruik gemaakt van standaard cURL commando's om te connecteren met de services. cURL is namelijk standaard beschikbaar is op vele operating systemen (en voor Windows OS is dit gratis te downloaden op https://curl.haxx.se/windows/).
Er is en demo-applicatie in Java beschikbaar die de verschillende stappen illustreert. Meer info over dit demo-project is te vinden op de github-pagina van DOV (https://github.com/DOV-Vlaanderen/dov-services-quickstart), onder het package "xmlimport".
In de onderstaande voorbeelden zijn steeds de productie URL's gebruikt. Wil je graag eerst je ontwikkeling uit testen? Maak dan gebruik van de oefenomgeving. De URL voor de oefenomgeving is https://services-oefen.dov.vlaanderen.be |
Het opladen van een XML-bestand voor verwerking naar DOV verloopt in 4 stappen. Dit is analoog aan de het opladen en verwerken van een bestand via de webapplicaties van DOV. Je laadt eerst een XML-bestand op. Dit bestand zal je valideren. Indien je bestand geldig is, kan je het importeren. Als laatste stap controleer je of de import van je XML-bestand is gelukt. Heb je de objecten geïmporteerd in het kader van eDOV? Vergeet dan zeker niet de boringen aan te leveren vanuit het overzicht uitgevoerde boringen. Hoe je dit doet, vind je in onze handleiding eDOV - Aanleveren boringen.
Aan te spreken url: https://services.dov.vlaanderen.be/dov-xdov-server/import/upload
Type request: POST
Header: Content-Type: multipart/form-data
Voorbeeld van een form post curl; let erop om de @ voor de bestandsnaam te zetten.
curl -X POST -F file=@voorbeeldbestand.xml -k https://services.dov.vlaanderen.be/dov-xdov-server/import/upload --key my_key.key --cert my_cert.pem -v |
Het antwoord is altijd in json-formaat en bevat een referentie (id) naar het opgeladen bestand. Dit ID moet gebruikt worden bij de volgende stappen om naar dat opgeladen bestand te refereren.
{"id":"804311","naam":"voorbeeldbestand.xml"} |
Sommige curl-implementaties voegen automatisch 'Expect: 100-continue' toe aan het request als dat meer dan 1024 bytes groot is. Dat levert echter een foutmelding op (issue zit in een externe component die we gebruiken - zie https://github.com/spring-cloud/spring-cloud-gateway/issues/1337) Als workaround kan -H 'Expect:' toegevoegd worden aan het curl commando, dat er dan als volgt uitziet: curl -X POST -F file=@voorbeeldbestand.xml -k https://services.dov.vlaanderen.be/dov-xdov-server/import/upload --key my_key.key --cert my_cert.pem -H 'Expect:' |
voor windows versie kan het zijn dat double quotes gebruikt moeten worden i.p.v. single quotes -H 'Content-Type: application/json' wordt dan -H "Content-Type: application/json" |
Aan te spreken url: https://services.dov.vlaanderen.be/dov-xdov-server/import/validate
Type request: POST
Header: Content-Type: application/json
curl -X POST -d "@validate-post-body.json" -k https://services.dov.vlaanderen.be/dov-xdov-server/import/validate -H 'Content-Type: application/json' --key my_key.key --cert my_cert.pem -v |
Een json-body moet hier mee gestuurd worden:
{
"id": null,
"omschrijving": "opladen XML",
"gebruikersnaam": "<username>",
"datumOpladen": "2019-10-10",
"datumProcessed": null,
"aantalVerwerkt": 0,
"aantalFouten": 0,
"partner": "<kbonummer van uw organisatie>",
"invoerwijze": {
"code": "2",
"beschrijving": "edov"
},
"status": {
"code": "1",
"beschrijving": "niet verwerkt"
},
"options": [
{
"id": null,
"propertyValue": "true",
"property": {
"code": "20",
"beschrijving": "Boring"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "21",
"beschrijving": "Opmerkingen bij een boring"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "22",
"beschrijving": "Alternatieve namen"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "101",
"beschrijving": "Informele stratigrafie"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "103",
"beschrijving": "Lithologische beschrijving"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "104",
"beschrijving": "Gecodeerde lithologie"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "105",
"beschrijving": "Hydrogeologische stratigrafie"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "108",
"beschrijving": "Geotechnische codering"
}
},
{
"id": null,
"propertyValue": "true",
"property": {
"code": "120",
"beschrijving": "Opmerkingen bij een interpretatie"
}
}
],
"bestand": {
"id": "<BESTAND-ID>",
"naam": "<BESTANDSNAAM>"
}
} |
In bovenstaand voorbeeld van post-data moet aandacht besteed worden aan de volgende velden:
Het antwoord van de server is een json-bestand met daarin een overzicht van succes of fouten van elke element in de XML tegenover het edov-xml-schema.
Het belangrijkste is lijn 8. Daar moet staan 'validatie zonder fouten'; indien niet is het een ongeldig bestand.
{
"details": [
{
"id": "2",
"context": null,
"status": {
"code": "7",
"beschrijving": "validatie zonder fouten"
},
"messages": [],
"identificatie": "1419-B-P6-Belle-Vue2",
"boring": {
"id": null,
"partner": null,
"uniekDOVId": "1419-B-P6-Belle-Vue2",
"locatie": null,
"displayName": "1419-B-P6-Belle-Vue2",
"boringKey": null,
"statusCode": null,
"permKey": null
}
},
{
"id": null,
"context": null,
"status": {
"code": "7",
"beschrijving": "validatie zonder fouten"
},
"messages": [],
"identificatie": "type 'informele stratigrafie' gekoppeld aan boring '1419-B-P6-Belle-Vue2' (datum '2010-11-13')",
"interpretatie": {
"id": null,
"interpretatieKey": null,
"partner": null,
"type": {
"code": "1",
"beschrijving": "informele stratigrafie",
"naam": "informele stratigrafie"
},
"datum": null,
"auteurs": null,
"moederBoring": {
"id": null,
"partner": null,
"uniekDOVId": "1419-B-P6-Belle-Vue2",
"locatie": null,
"displayName": "1419-B-P6-Belle-Vue2",
"boringKey": null,
"statusCode": null,
"permKey": null
},
"sondering": null,
"statusCode": null,
"permKey": null,
"fase": null,
"securityStatus": null
}
},
{
"id": null,
"context": null,
"status": {
"code": "7",
"beschrijving": "validatie zonder fouten"
},
"messages": [],
"identificatie": "type 'lithologische beschrijving' gekoppeld aan boring '1419-B-P6-Belle-Vue2' (datum '2016-05-12')",
"interpretatie": {
"id": null,
"interpretatieKey": null,
"partner": null,
"type": {
"code": "3",
"beschrijving": "lithologische beschrijving",
"naam": "lithologische beschrijving"
},
"datum": null,
"auteurs": null,
"moederBoring": {
"id": null,
"partner": null,
"uniekDOVId": "1419-B-P6-Belle-Vue2",
"locatie": null,
"displayName": "1419-B-P6-Belle-Vue2",
"boringKey": null,
"statusCode": null,
"permKey": null
},
"sondering": null,
"statusCode": null,
"permKey": null,
"fase": null,
"securityStatus": null
}
}
],
"summary": {
"items": [
{
"option": {
"code": "20",
"beschrijving": "Boring"
},
"numberOfObjects": 1,
"id": "20"
},
{
"option": {
"code": "101",
"beschrijving": "Informele stratigrafie"
},
"numberOfObjects": 1,
"id": "101"
},
{
"option": {
"code": "103",
"beschrijving": "Lithologische beschrijving"
},
"numberOfObjects": 1,
"id": "103"
},
{
"option": {
"code": "105",
"beschrijving": "Hydrogeologische stratigrafie"
},
"numberOfObjects": 0,
"id": "105"
},
{
"option": {
"code": "108",
"beschrijving": "Geotechnische codering"
},
"numberOfObjects": 0,
"id": "108"
},
{
"option": {
"code": "104",
"beschrijving": "Gecodeerde lithologie"
},
"numberOfObjects": 0,
"id": "104"
}
],
"id": null
}
} |
Aan te spreken url: https://services.dov.vlaanderen.be/dov-xdov-server/import
Type request: POST
Header: Content-Type: application/json
Een json-body moet hier mee gestuurd worden; dit is volledig identiek aan de json-body uit stap 2.
curl -X POST -d "@validate-post-body.json" -k https://services.dov.vlaanderen.be/dov-xdov-server/import -H 'Content-Type: application/json' --key my_key.key --cert my_cert.pem -v |
Het antwoord is een json-object met dezelfde structuur als wat er opgestuurd is, maar waar het "id" (zie lijn 2 in onderstaand voorbeeld) ingevuld is.
Dat is het invoerlogID waarvan in stap 4 gebruikt gemaakt kan worden om de verwerking van het xml-bestand op te volgen.
{
"id": "804327",
"omschrijving": "Aanlevering boringen Vlaamse Maatschappij voor Watervoorziening",
"gebruikersnaam": "Timothy De Bock",
"invoerwijze": {
"code": "2",
"beschrijving": "edov"
},
"datumOpladen": 1574850760172,
"bestand": {
"id": "804326",
"naam": "1419-b-P6 (kopie).xml"
},
"datumProcessed": null,
"status": {
"code": "1",
"beschrijving": "niet verwerkt"
},
"options": [
{
"id": "804328",
"property": {
"code": "131",
"beschrijving": "Referentieprofielen en boringen"
},
"propertyValue": "false"
},
{
"id": "804341",
"property": {
"code": "22",
"beschrijving": "Alternatieve namen"
},
"propertyValue": "true"
},
{
"id": "804345",
"property": {
"code": "21",
"beschrijving": "Opmerkingen bij een boring"
},
"propertyValue": "true"
},
{
"id": "804350",
"property": {
"code": "50",
"beschrijving": "Put"
},
"propertyValue": "false"
},
{
"id": "804336",
"property": {
"code": "66",
"beschrijving": "GXG's bij een filter"
},
"propertyValue": "false"
},
{
"id": "804352",
"property": {
"code": "102",
"beschrijving": "Formele stratigrafie"
},
"propertyValue": "false"
},
{
"id": "804332",
"property": {
"code": "11",
"beschrijving": "Opmerkingen bij een opdracht"
},
"propertyValue": "false"
},
{
"id": "804344",
"property": {
"code": "63",
"beschrijving": "Watermonsters bij een filter"
},
"propertyValue": "false"
},
{
"id": "804331",
"property": {
"code": "103",
"beschrijving": "Lithologische beschrijving"
},
"propertyValue": "true"
},
{
"id": "804337",
"property": {
"code": "29",
"beschrijving": "Opmerkingen bij een grondmonster"
},
"propertyValue": "false"
},
{
"id": "804355",
"property": {
"code": "109",
"beschrijving": "Informele hydrostratigrafie"
},
"propertyValue": "false"
},
{
"id": "804348",
"property": {
"code": "41",
"beschrijving": "Opmerkingen bij een sondering"
},
"propertyValue": "false"
},
{
"id": "804330",
"property": {
"code": "23",
"beschrijving": "Grondmonsters"
},
"propertyValue": "false"
},
{
"id": "804343",
"property": {
"code": "61",
"beschrijving": "Opmerkingen bij een filter"
},
"propertyValue": "false"
},
{
"id": "804334",
"property": {
"code": "104",
"beschrijving": "Gecodeerde lithologie"
},
"propertyValue": "true"
},
{
"id": "804349",
"property": {
"code": "65",
"beschrijving": "Onttrekkingen bij een filter"
},
"propertyValue": "false"
},
{
"id": "804342",
"property": {
"code": "30",
"beschrijving": "Laboproeven"
},
"propertyValue": "false"
},
{
"id": "804351",
"property": {
"code": "51",
"beschrijving": "Opmerkingen bij een put"
},
"propertyValue": "false"
},
{
"id": "804335",
"property": {
"code": "106",
"beschrijving": "Quartaire stratigrafie"
},
"propertyValue": "false"
},
{
"id": "804333",
"property": {
"code": "101",
"beschrijving": "Informele stratigrafie"
},
"propertyValue": "true"
},
{
"id": "804346",
"property": {
"code": "105",
"beschrijving": "Hydrogeologische stratigrafie"
},
"propertyValue": "true"
},
{
"id": "804340",
"property": {
"code": "108",
"beschrijving": "Geotechnische codering"
},
"propertyValue": "true"
},
{
"id": "804329",
"property": {
"code": "60",
"beschrijving": "Filter"
},
"propertyValue": "false"
},
{
"id": "804339",
"property": {
"code": "120",
"beschrijving": "Opmerkingen bij een interpretatie"
},
"propertyValue": "true"
},
{
"id": "804353",
"property": {
"code": "10",
"beschrijving": "Opdracht"
},
"propertyValue": "false"
},
{
"id": "804338",
"property": {
"code": "40",
"beschrijving": "Sondering"
},
"propertyValue": "false"
},
{
"id": "804347",
"property": {
"code": "20",
"beschrijving": "Boring"
},
"propertyValue": "true"
},
{
"id": "804354",
"property": {
"code": "62",
"beschrijving": "Peilmetingen bij een filter"
},
"propertyValue": "false"
}
],
"aantalVerwerkt": 0,
"aantalFouten": 0,
"partner": "0224771467"
} |
De import is een asynchroon proces, wat betekent dat u een bestand registreert om te importeren, maar dat het systeem dit zal verwerken van zodra het daar de tijd voor heeft.
Dat zal meestal wel binnen de 2 minuten gebeuren, maar dat is zeker niet gegarandeerd.
Het is dus zaak om deze url periodiek op te roepen om de echte status van de import te kennen.
Aan te spreken url: https://services.dov.vlaanderen.be/dov-xdov-server/logs/[invoerlogID]
Of met extra details (detailoverzicht per opgeladen object) : https://services.dov.vlaanderen.be/dov-xdov-server/logs/[invoerlogID]/details
De url is dus afhankelijk van het invoerlogID dat bekomen is in stap 3
Type request: GET
Header: Content-Type: application/json
curl https://services.dov.vlaanderen.be/dov-xdov-server/logs/804327 -H 'Content-Type: application/json' --key my_key.key --cert my_cert.pem -v of curl https://services.dov.vlaanderen.be/dov-xdov-server/logs/804327/details -H 'Content-Type: application/json' --key my_key.key --cert my_cert.pem -v |
Het antwoord is hetzelfde json-object zoals teruggekomen is in stap 3, mét toevoeging van de huidige status van deze import.
Mogelijke statussen (zie lijn 17)
{
"id": "804370",
"omschrijving": "Aanlevering boringen Vlaamse Maatschappij voor Watervoorziening",
"gebruikersnaam": "SYSTEEM",
"invoerwijze": {
"code": "2",
"beschrijving": "edov"
},
"datumOpladen": 1574851782041,
"bestand": {
"id": "804369",
"naam": "1419-b-P6 (kopie).xml"
},
"datumProcessed": 1574851799145,
"status": {
"code": "4",
"beschrijving": "foutloos verwerkt"
},
"options": [
{
"id": "804377",
"property": {
"code": "105",
"beschrijving": "optie_hydrogeologisch"
},
"propertyValue": "true"
},
{
"id": "804380",
"property": {
"code": "21",
"beschrijving": "optie_opmerkingen_boring"
},
"propertyValue": "true"
},
{
"id": "804391",
"property": {
"code": "131",
"beschrijving": "optie_referentieprofiel"
},
"propertyValue": "false"
},
{
"id": "804398",
"property": {
"code": "50",
"beschrijving": "optie_put"
},
"propertyValue": "false"
},
{
"id": "804381",
"property": {
"code": "20",
"beschrijving": "optie_boring"
},
"propertyValue": "true"
},
{
"id": "804374",
"property": {
"code": "41",
"beschrijving": "optie_opmerkingen_sondering"
},
"propertyValue": "false"
},
{
"id": "804392",
"property": {
"code": "40",
"beschrijving": "optie_sondering"
},
"propertyValue": "false"
},
{
"id": "804395",
"property": {
"code": "22",
"beschrijving": "optie_alternatievenaam"
},
"propertyValue": "true"
},
{
"id": "804382",
"property": {
"code": "23",
"beschrijving": "optie_grondmonster"
},
"propertyValue": "false"
},
{
"id": "804384",
"property": {
"code": "104",
"beschrijving": "optie_gecodeerd"
},
"propertyValue": "true"
},
{
"id": "804389",
"property": {
"code": "66",
"beschrijving": "optie_gxgs"
},
"propertyValue": "false"
},
{
"id": "804393",
"property": {
"code": "11",
"beschrijving": "optie_opmerkingen_opdracht"
},
"propertyValue": "false"
},
{
"id": "804375",
"property": {
"code": "120",
"beschrijving": "optie_opmerkingen_interpretatie"
},
"propertyValue": "true"
},
{
"id": "804394",
"property": {
"code": "63",
"beschrijving": "optie_watermonster"
},
"propertyValue": "false"
},
{
"id": "804378",
"property": {
"code": "61",
"beschrijving": "optie_opmerkingen_filter"
},
"propertyValue": "false"
},
{
"id": "804373",
"property": {
"code": "51",
"beschrijving": "optie_opmerkingen_put"
},
"propertyValue": "false"
},
{
"id": "804396",
"property": {
"code": "65",
"beschrijving": "optie_onttrekkingen"
},
"propertyValue": "false"
},
{
"id": "804379",
"property": {
"code": "109",
"beschrijving": "optie_informelehydro"
},
"propertyValue": "false"
},
{
"id": "804390",
"property": {
"code": "101",
"beschrijving": "optie_informeel"
},
"propertyValue": "true"
},
{
"id": "804383",
"property": {
"code": "103",
"beschrijving": "optie_lithologie"
},
"propertyValue": "true"
},
{
"id": "804388",
"property": {
"code": "30",
"beschrijving": "optie_laboproeven_grondmonster"
},
"propertyValue": "false"
},
{
"id": "804372",
"property": {
"code": "62",
"beschrijving": "optie_peilmetingen"
},
"propertyValue": "false"
},
{
"id": "804387",
"property": {
"code": "10",
"beschrijving": "optie_opdracht"
},
"propertyValue": "false"
},
{
"id": "804386",
"property": {
"code": "60",
"beschrijving": "optie_filter"
},
"propertyValue": "false"
},
{
"id": "804385",
"property": {
"code": "106",
"beschrijving": "optie_quartair"
},
"propertyValue": "false"
},
{
"id": "804397",
"property": {
"code": "102",
"beschrijving": "optie_formeel"
},
"propertyValue": "false"
},
{
"id": "804376",
"property": {
"code": "108",
"beschrijving": "optie_geotechnisch"
},
"propertyValue": "true"
},
{
"id": "804371",
"property": {
"code": "29",
"beschrijving": "optie_opmerkingen_grondmonster"
},
"propertyValue": "false"
}
],
"aantalVerwerkt": 3,
"aantalFouten": 0,
"partner": "0224771467"
} |
Het is ook mogelijk om een lijst op te vragen van de opgeladen bestanden.
De data moet 'paged' opgevraagd' worden, wat wil zeggen dat er een startIndex en een resultSize moet meegegeven worden in de url.
Aan te spreken url:
https://services.dov.vlaanderen.be/dov-xdov-server/logs/?startIndex=0&resultSize=100 voor de laatste 100 opgeladen bestanden
https://services.dov.vlaanderen.be/dov-xdov-server/logs/?startIndex=100&resultSize=100 voor de vorige 100
enz.
Om te weten hoeveel bestanden er op geladen zijn kan de reeds vermelde url
https://services.dov.vlaanderen.be/dov-xdov-server/logs/count
gebruikt worden
Type request: GET
Url parameters: startIndex en resultSize (case sensitive én verplicht)
Header: Content-Type: application/json
#om na te gaan hoeveel bestanden er opgeladen zijn: curl https://services.dov.vlaanderen.be/dov-xdov-server/logs/count -H 'Content-Type: application/json' --key my_key.key --cert my_cert.pem -v #daarna kan een range opgevraagd worden (de meest recente uploads staan eerst): curl https://services.dov.vlaanderen.be/dov-xdov-server/logs/?startIndex=0&resultSize=100 -H 'Content-Type: application/json' --key my_key.key --cert my_cert.pem -v |
Het antwoord is als volgt (voorbeeld met 1 resultSize=1):
[
{
"id": "1296073",
"omschrijving": "opladen XML",
"gebruikersnaam": "geolab",
"invoerwijze": {
"code": "2",
"beschrijving": "edov"
},
"datumOpladen": 1610013593601,
"bestand": {
"id": "1296072",
"naam": "20.12.186_Sondex_Evergem_DOV.xml"
},
"datumProcessed": 1610013615150,
"status": {
"code": "3",
"beschrijving": "verwerkt met fouten"
},
"options": [],
"aantalVerwerkt": 0,
"aantalFouten": 2,
"partner": "0414460412"
}
] |
Met het id op lijn 3 kan dan weer de details van 1 enkele verwerking opgevraagd worden ( = stap 4)