Standaarden voor geografische data _______________________________________ 3 Introductie.................................................................................................................................3 Web Mapping Service (WMS) .................................................................................................3 Web Feature Service (WFS) .....................................................................................................3
4 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8
De afzonderlijke services _________________________________________________ 3 Opvragen van Luchtfoto’s .......................................................................................................3 Opvragen van PIPO Percelen ..................................................................................................3 Opvragen van Perceelsregistratie...........................................................................................3 Optimalisatie van een Geometrie...........................................................................................3 Validatie van een opgave/wijziging in Perceelsregistratie..................................................3 Opvragen van het Validatieresultaat ....................................................................................3 Opvragen van een TAN volgnummer ....................................................................................3 Opgave van een opgave/wijziging in Perceelsregistratie....................................................3
Specificatie van de SOAP services, het WSDL document_______________________ 3 Inleiding.....................................................................................................................................3 XML Types .................................................................................................................................3 6.2.1 Optimalisatie van een Perceel 3 6.2.2 Validatie van een Perceelswijziging 3 6.2.3 Opvragen van een ValidatieResultaat 3 6.2.4 Opvragen van een TAN Volgnummer 3 6.2.5 Opgave van een PerceelsWijziging 3 Messages ...................................................................................................................................3 Porttype .....................................................................................................................................3 Binding ......................................................................................................................................3 Service........................................................................................................................................3
6.3 6.4 6.5 6.6
Versie 1.2
20-09-2013
pagina ii
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
7 7.1 7.2
7.3
7.4
7.5
7.6
8 8.1 8.2 8.3 8.4 8.5 8.6
Definitief
XML Schemas ___________________________________________________________ 3 Inleiding.....................................................................................................................................3 Fouten........................................................................................................................................3 7.2.1 Voorbeeld 3 7.2.2 Schema 3 Properties ..................................................................................................................................3 7.3.1 Voorbeeld 3 7.3.2 Schema 3 PerceelsWijzigingen .................................................................................................................3 7.4.1 Voorbeeld 3 7.4.2 Schema 3 Perceel .......................................................................................................................................3 7.5.1 Voorbeeld 3 7.5.2 Schema 3 OptimalisatiePercelen..............................................................................................................3 7.6.1 Voorbeeld 3 7.6.2 Schema 3 Voorbeelden ____________________________________________________________ 3 Opvragen van een luchtfoto ...................................................................................................3 Opvragen percelen met HTTP/POST .......................................................................................3 Opvragen Pipo percelen met HTTP/POST ..............................................................................3 Optimalisatie van een Geometrie...........................................................................................3 Validatie van een wijziging in perceelsregistratie................................................................3 Opgave van een wijziging in perceelsregistratie..................................................................3
Versie 1.2
20-09-2013
pagina iii
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
Aanpassingsgeschiedenis Versie 0.1 0.2
Datum 26-10-2006 21-11-2006
0.3
07-11-2006
0.4
18-05-2007
0.6
01-06-2011
Versie 1.2
Aanpassingen Eerste versie voor de BMS leveranciers Enkele kleine aanpassingen in de XML schema’s. Eenheden en formaten expliciet gespecificeerd (2.3.3) Fout in definitie PerceelWijzigingType gecorrigeerd XML Schema’s voor berichtenuitwisseling aangepast. Mogelijkheid om de WFS GetFeature aan te roepen via een HTTP POST. Services voor Optimalisatie, Validatie en Opgave nu via SOAP (de berichtstructuur blijft vrijwel ongewijzigd). Specificatie van WMS en WFS services aangepast en voorbeelden van WMS en WFS berichten toegevoegd Datumformaat aangepast aan werkelijk formaat (Dit is het standaard formaat voor SOAP en WFS Toevoeging van beschrijving functionaliteit om om te kunnen gaan met machtigingen.
20-09-2013
pagina 1
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
1
Definitief
Inleiding
Dit document beschrijft de Interface van de applicatie ‘geoboer’, als ontwikkeld tijdens het project GeoBoer van het Ministerie van LNV. De Interface Specification zal optreden als leidraad voor de leveranciers van de Bedrijfs Management Systemen (BMS).
1.1
Referenties
Nummer Document 1 Web Map Service Implementation Specification, OpenGIS Consortium 2 Web Feature Service Implementation Specification, OpenGIS Consortium 3 ARCIMS 9, Customizing ArcIMS – WFS Connector
Versie 1.2
20-09-2013
Versie v. 1.1.1 ref. OGC01-068r3 v. 1.1.0 ref. OGC-04-095
pagina 2
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
2
Geoboer
2.1
Inleiding
Definitief
Geoboer is voortgekomen uit de wens een communicatiemogelijkheid te hebben tussen Bedrijfsmanagement Systemen (BMS) en de overheid. De applicatie Geoboer biedt als zodanig een aantal internetservices. Middels deze services worden referentiegegevens door de Dienst Regelingen (DR) beschikbaar gesteld. Bovendien wordt de mogelijkheid geboden tot het doorgeven van wijzigingen in Perceelsregistratie aan Dienst Regelingen.
2.2
http / soap requests
De applicatie Geoboer zal een aantal services aanbieden. De meeste services zullen door een BMS over internet benaderd kunnen worden met behulp van het SOAP protocol over HTTP. De enige uitzondering betreft de services welke gebruik maken van standaarden voor de uitwisseling van geografische data, te weten de standaarden WMS (Web Mapping Service) en WFS (Web Feature Service). In deze situaties dienen HTTP (GET of POST) requests uitgevoerd te worden. Hierbij worden de standaarden als gebruikt door ArcIMS 9.1 aangehouden (zie [3]). Zie voor de details van deze services hoofdstuk 3. Service WMS Services (opvragen luchtfoto’s) WFS Services (opvragen PIPO percelen of perceelsregistratie) Optimalisatie Geometrieën Validatie opgave/wijziging perceelsregistratie Opvragen Validatieresultaat Opvragen TAN volgnummer Opgave/wijziging perceelsregistratie
2.3
Techniek HTTP GET HTTP GET / POST SOAP SOAP SOAP SOAP SOAP
Technische details
2.3.1 Adressen HTTP GET en HTTP POST requests (voor WMS en WFS services) dienen gericht te worden aan het volgende adres: https://geoboer.agro.nl/geoboer/http Bij GET requests dienen de meegestuurde parameters in de URL toegevoegd te worden. Bij POST requests dient het bericht meegestuurd te worden in de body van het HTTP request.
Versie 1.2
20-09-2013
pagina 3
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
Alle SOAP requests dienen gericht te worden aan het volgende adres: https://geoboer.agro.nl/geoboer/soap
2.3.2 Authenticatie en Identificatie Voor toegang tot en gebruik van de geboden services zal de relatie zich via de services dienen te identificeren. Bovendien zal het BMS zich moeten identificeren. Hiertoe dienen voor elke service aanroep de volgende gegevens meegezonden te worden: • ABA code van de gebruiker • Wachtwoord (behorende bij de ABA code) van de gebruiker • BMS identificatiecode, als verstrekt door dienst regelingen aan de BMS leverancier • BMS versie De BMS versie dient hierbij te bestaan uit maximaal 20 (alfanumerieke) karakters. Deze gegevens dienen te worden opgeslagen in de ‘user-agent’ header van het door de BMS verzonden http-request. Let wel, dit geldt ook voor de services die via SOAP (over http) benaderd dienen te worden. ABA-nummer en wachtwoord van de gebruiker dienen te worden opgeslagen in het http Authorization header veld, volgens de standaard van basic authentication. De combinatie van BMS identificatiecode en BMS versie dient opgeslagen te worden In het user-agent header veld, gescheiden door een slash-karakter (‘/’): /.
2.3.3
Machtigingen
Om gebruik te kunnen maken van machtingingen moet onderstaande aanpassing worden doorgevoerd. Voor elke service aanroep moeten de volgende gegevens van de machtigingsgever meegezonden worden: • Type dienstsleutel (BRS, KVK of BSN) • Dienstsleutel van de gebruiker • Postcode (formaat 1234AB) • Huisnummer (numeriek) Deze gegevens dienen te worden opgeslagen in een nieuw te maken ‘user-gbv’ header van het door de BMS verzonden http-request. Let wel, dit geldt ook voor de services die via SOAP (over http) benaderd dienen te worden. De combinatie van Type dienstsleutel, dienstsleutel, postcode en huisnummer dient opgeslagen te worden in het user-gbv header veld, gescheiden door een slash-karakter (‘/’): Voorbeeld: BSN/123456789/1234AB/789.
Versie 1.2
20-09-2013
pagina 4
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
2.3.4 • • •
•
Definitief
Eenheden en formaten Oppervlaktes zullen worden uitgedrukt in hectare. Eventuele decimalen zullen gescheiden zijn door middel van een punt-karakater (‘.’). Datums zullen worden uitgedrukt volgens het yyyy-mm-dd patroon. Percelen zullen gecommuniceerd worden volgens de GML (Geographical Markup Language) versie 2.1.1. Hierbij dient uitsluitend gebruik gemaakt te worden van de GML Types Polygon of MultiPolygon. Indien een MultiPolygon wordt meegegeven, dient deze precies één buitenring te bevatten. De percelen die gecommuniceerd worden zullen gebruik maken van het EPSG:28992 (of te wel het Rijks Driehoek Stelsel) SRS.
Versie 1.2
20-09-2013
pagina 5
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
3
Standaarden voor geografische data
3.1
Introductie
Definitief
Voor de communicatie van geografische gegevens zijn verschillende standaarden ontwikkeld. Meest bekende standaarden zijn de standaarden voor de Web Mapping Service (WMS) en de Web Feature Service (WFS). De Geoboer service voor het opvragen van luchtfoto’s zal voldoen aan de WMS standaard. De services voor het opvragen van PIPO percelen en Perceelsregistratie zullen aan de WFS standaard voldoen. Voor het aanroepen van deze services zullen we de standaarden als gebruikt door ArcIMS 9.1 aanhouden (zie [3]). Technisch betekent dit dat deze services opgevraagd zullen worden met behulp van geparametriseerde HTTP GET requests of door middel van een HTTP POST Request. Uiteraard moet ook aan de authenticatie/identificatie voorwaarden zoals beschreven in paragraaf 2.3.2 worden voldaan.
3.2
Web Mapping Service (WMS)
De Web Mapping Service is ontwikkeld voor het opvragen van geografische kaarten of luchtfoto’s via het internet. Met behulp van deze service kunnen de volgende request typen uitgevoerd worden: • GetCapabilities, voor een beschrijving van de capaciteiten van de WMS service. • GetMap, voor her retourneren van geografische kaarten of luchtfoto’s. • GetFeatureInfo, voor het leveren van informatie over features verwerkt in geografische kaarten of luchtfoto’s. Elke WMS service dient de operaties GetCapabilities en GetMap te bieden. Voor de exacte specificatie van de aanroep, zie de implementatie specificatie [1]. Voorlopig wordt hier slechts WMS versie 1.1.1 ondersteund.
3.3
Web Feature Service (WFS)
De Web Feature Service is ontwikkeld voor het uitwisselen van vector informatie via het internet. Met behulp van deze service kunnen verschillende operaties uitgevoerd worden: • GetCapabilities, voor een beschrijving van de capaciteiten van de WFS service. • GetFeature, voor het ophalen van features (alleen via HTTP POST Request). • DescribeFeatureType, voor een beschrijving van de feature types die m.b.v de service geleverd kunnen worden. • Transaction, voor het uitvoeren van transacties (insert, update, delete) • LockFeature, voor het locken van feature types gedurende een transactie Elke WFS service dient de operaties GetCapabilities, GetFeature en DescribeFeatureType te bieden. Een ‘transactional WFS service’ dient ook de Transaction operatie te bieden. De Geoboer applicatie biedt deze Transaction operation niet.
Versie 1.2
20-09-2013
pagina 6
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
Alle operaties kunnen worden aangeroepen gebruik makende van de HTTP GET Key-Value pair encoding. De GetFeature operatie kan alleen worden aangeroepen door middel van de HTTP POST XML encoding. Voor de exacte specificatie van de aanroep, zie de implementatie specificatie [2]. Voorlopig wordt hier slechts WFS versie 1.0 ondersteund. Binnen WFS is het ondersteunen van filters optioneel. Geoboer ondersteunt de BBOX filter, en een beperkte implementatie van de Logical en Comparison filters Als Logical filter wordt alleen ondersteund. Hierbij is het nesten van filters niet toegestaan. Comparison filters zijn alleen geimplementeerd voor datum en string. Voor een datum worden de operatoren "PropertyIsLessThan", PropertyIsLessThanOrEqualTo", "PropertyIsGreaterThanOrEqualTo", "PropertyIsEqualTo" en "PropertyIsNotEqualTo" ondersteund. Voor string waardes wordt alleen “PropertyIsEqualTo” ondersteund. Alle waardes die niet in het datumformaat staan worden door het filter gezien als een string. Hierdoor is het mogelijk om een filter op relatienummer of gewascode te maken. Wanneer gebruik gemaakt wordt van filters, dan zal het attribuut ‘maxFeatures’ van de node ‘GetFeature’ niet altijd correct werken. Meer informatie hierover staat bij de betreffende services.
Versie 1.2
20-09-2013
pagina 7
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
4
De afzonderlijke services
4.1
Opvragen van Luchtfoto’s
Definitief
Voor deze service wordt de specificatie van de Web Mapping Service (WMS) van het Open GIS Consortium gevolgd. Als response op een valide GetMap-request wordt een luchtfoto door middel van een bytesteam geretourneerd. Indien bij de processing van het GetMap-request fouten optreden, wordt door de WMS service een dergelijke foutmelding geretourneerd: <ServiceExceptionReport version="1.1.1"> <ServiceException> Invalid HEIGHT value Contenttype is dan application/vnd.ogc.se_xml.
4.2
Opvragen van PIPO Percelen
Voor deze service wordt de specificatie van de Web Feature Service (WFS) van het Open GIS Consortium gevolgd. Indien een GetFeature-request wordt ingeschoten, dient een request parameter TYPENAME toegevoegd te worden. Deze request parameter dient de volgende waarde ‘Pipo-0’te krijgen Als response wordt dan een XML document verstuurd. Dit XML document zal per PIPO perceel volgende gegevens retourneren: • • • • • • • • •
Indien een foutmelding optreedt wordt door de WFS service het volgende bericht geretourneerd: <ServiceExceptionReport version="1.2.0" xmlns="http://www.opengis.net/ogc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <ServiceException code="001" locator="GetFeature"> Wrong typename: PIP 2005-1
Versie 1.2
20-09-2013
pagina 8
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
Het is mogelijk om gebruik te maken van filters. Zoals al beschreven in hoofdstuk 3 worden filters maar beperkt ondersteund. Wanneer een filters gebruikt worden dan zal het ‘maxFeatures’ attribuut van ‘GetFeature’ niet correct werken. Het advies is om ieder geval ook een BBOX op te geven, en in dat geval ‘maxFeatures’ op een waarde te zetten die groter is of gelijk is het aantal percelen binnen de BBOX valt.
4.3
Opvragen van Perceelsregistratie
Voor deze service wordt de specificatie van de Web Feature Service (WFS) van het Open GIS Consortium gevolgd. Indien een GetFeature-request wordt ingeschoten, dient een request parameter TYPENAME toegevoegd te worden. Deze request parameter dient de volgende waarde te krijgen: • Percelen-1 Als response wordt dan een XML document verstuurd. Dit XML document zal per geretourneerde perceel volgende gegevens retourneren: • perceelID • relatienummer • formuliernummer • communicatienummer • volgnummer • begindatum • einddatum • gewascode • gewasnaam • gebruikstitelcode • gebruikstitel • opgegeven_oppervlak • status_perceelsgebruik • perceelsbron • wijzigingsdatum • geometrie.area • geometrie.len Het is verplicht om een filter op te nemen met daarin het relatienummer. Een voorbeeld van het filter (gebaseerd op HTTP POST) is:
Versie 1.2
20-09-2013
pagina 9
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
lnv:relatienummer9999999999
Het is mogelijk om meerdere filters te combineren met nodes. Zoals al beschreven in hoofdstuk 3 worden filters maar beperkt ondersteund. Wanneer een combinatie van filters wordt gebruikt zal het ‘maxFeatures’ attribuut van ‘GetFeature’ niet correct werken. Het advies is om in dat geval maxFeatures op een waarde te zetten die groter is dan het aantal percelen dat bij het relatienummer hoort.
4.4
Optimalisatie van een Geometrie
Deze service dient te worden aangeroepen met behulp van een SOAP request. Hierbij dienen de volgende gegevens verstrekt te worden: • Relatienummer • Verzameling van geometriëen. • Referentie datum • Optimalisatie marge Elk element in de verzameling geometriëen dient hierbij een in dit bericht uniek regelnummer mee te krijgen. Dit regelnummer zal in de response terugkomen. Bovendien dient een geometriëen een ID meekrijgen, wanneer het een wijziging betreft op een reeds bestaand perceel (als geretourneerd door de service beschreven in 4.3). Er zal dan niet geoptimaliseerd worden naar het perceel met dat meegegeven ID. De inhoud van het veld optimalisatie marge zal voorlopig echter niet gebruikt worden. Als optimalisatiemarge wordt standaard met 5 meter gewerkt. Deze gegevens dienen verstrekt te worden via een SOAP request. Het XML document in de body dient te voldoen aan het XML schema van 6.2.1. Als response zal een verzameling geoptimaliseerde geometriëen geretourneerd worden, of één of meer foutmeldingen. Deze response zal voldoen aan het XML schema van 6.2.1.
4.5
Validatie van een opgave/wijziging in Perceelsregistratie
Deze service dient te worden aangeroepen met behulp van een SOAP request. Hierbij dienen de volgende gegevens verstrekt te worden: • Relatienummer • Een verzameling van perceelsgegevens, waarin voor elk perceel de volgende gegevens verstrekt kunnen worden:
Versie 1.2
20-09-2013
pagina 10
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Deze gegevens dienen verstrekt te worden via SOAP. Het XML document in de body van het SOAP request dient te voldoen aan het XML schema van 6.2.2. Elke set perceelsgegevens dient hierbij een in dit bericht uniek regelnummer mee te krijgen. Bovendien dienen de regelnummers in dit bericht opeenvolgend te zijn, beginnend bij 1. In geval er gekozen is voor een asynchrone verwerking, wordt een wachtrijnummer geretourneerd. Indien dit validatie-verzoek synchroon verwerkt wordt, zal het resultaat van de validatie geretourneerd worden. De response is dan afhankelijk van het feit of er (harde) fouten tijdens de validatie zijn opgetreden. Indien er harde fouten zijn opgetreden, zullen deze fouten geretourneerd worden. Indien tijdens de validatie geen of slechts zachte fouten geretourneerd zijn, zal een ValidatieTicket geretourneerd worden. Mogelijke waardes van ‘RedenPipooverschrijving’ zijn: • Situatie veranderd door stadsuitbreiding • Situatie veranderd door wegaanleg • Situatie veranderd door ruilverkaveling • Situatie veranderd door demping sloot Mogelijke waardes voor RedenNietOpnemenVorigeGebruiker zijn: • Uitgegeven door BBL • Ruilverkaveling • Particulier • Verstoorde relatie De exacte inhoud van de response voldoet aan het XML schema van 6.2.2.
4.6
Opvragen van het Validatieresultaat
Deze service dient te worden aangeroepen m.b.v. het SOAP protocol. Als input dient slechts het relatienummer en het wachtrijnummer verstuurd te worden. De response zal de status van de validatie (‘Nog niet klaar’, ‘Positief’ of ‘Negatief’), eventueel het validatieticket (indien de validatie gereed en positief is), en één of meer foutmeldingen bevatten.
Versie 1.2
20-09-2013
pagina 11
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
De exacte layout van de XML berichten staan in het WSDL document, dat beschreven wordt in paragraaf 6.2.3.
4.7
Opvragen van een TAN volgnummer
Deze service dient te worden aangeroepen met behulp van het SOAP protocol. Als input dient slechts het relatienummer en het bevestigingstype verstuurd te worden. Als response zal het TAN volgnummer geretourneerd worden, of één of meer foutmeldingen. De exacte layout van de XML berichten staan in het WSDL document, dat beschreven wordt in paragraaf 6.2.4.
4.8
Opgave van een opgave/wijziging in Perceelsregistratie
Deze service dient te worden aangeroepen met behulp van een SOAP request. Hierbij dienen de volgende gegevens verstrekt te worden: • Relatienummer • Authorisatiewijze • Authorisatie-parameters. • Validatieticket, als geretourneerd door de validatie service. • Een verzameling perceelsgegevens, waarin voor elk perceel de volgende gegevens verstuurd kunnen worden: 1. Geometrie 2. Begindatum 3. RedenPipoOverschrijding 4. Gewascode 5. Gebruikscode 6. OpgegevenOppervlak (hectare) 7. BrsNummerVorigeGebruiker 8. RedenNietOpnemenVorigeGebruiker 9. Regelnummer
Deze lijst gegevens dienen verstrekt te worden via een SOAP request. Het XML document in de body van het SOAP bericht dient te voldoen aan het XML schema van 6.2.5. Elke set perceelsgegevens dient hierbij opnieuw een regelnummer mee te krijgen. Dit regelnummer moet voor elk perceel overeenkomen met het regelnummer dat tijdens de validatie voor dit perceel meegestuurd is. Als Authorisatiewijze wordt vooralsnog slechts TAN ondersteund. Dit betekent dat de authorisatie-parameters TAN volgnummer en TAN code (behorende bij het TAN volgnummer) verstuurd dienen te worden. Deze gegevens dienen te worden verstrekt als properties. De service zal een communicatienummer en een inwindatum, of één of meer foutmeldingen retourneren.
Versie 1.2
20-09-2013
pagina 12
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
De exacte inhoud van de response voldoet aan het XML schema van 6.2.5.
Versie 1.2
20-09-2013
pagina 13
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
5
Foutmeldingen
5.1
Opbouw
Definitief
Voor de op WMS en WFS gebaseerde services kan een WMS of WFS foutmelding worden teruggestuurd. Meer informatie over deze foutmeldingen staat in de specificaties [1] en [2] Foutmeldingen van op SOAP gebaseerde services zijn gedefinieerd door Geoboer. De foutmeldingen die terug gestuurd worden naar de BMS bestaan uit: • een code • een oorsprong • een omschrijving • een foutboodschap • een indicatie of de fout blokkerend is • (optioneel) een regelnummer Indien de foutmelding een regelnummer meekrijgt, is de fout die optreedt dan direct gerelateerd aan de bij dat regelnummer meegestuurde perceelsgegevens (zie hoofdstuk 7). Bovendien krijgt een foutmelding een indicatie of de fout al dat niet blokkerend (dat wil zeggen hard of zacht) geweest is. Wanneer harde fouten zijn opgetreden, zal de opgevraagde service niet het verwachte of gewenste resultaat terug geven. Voorbeelden zijn situaties waarin een incorrect ABA nummer/wachtwoord combinatie of een incorrecte datum wordt meegegeven. Deze fouten kunnen ook optreden bij de validatie service, in het geval de opgegeven perceelswijziging niet goedgekeurd wordt. In geval van zachte fouten is de opgevraagde service er wel in geslaagd het verzoek uit te voeren, maar zijn er toch inconsistenties waargenomen. Een voorbeeld is de situatie waarin een perceelswijziging verzonden wordt waarin het verzonden opgegeven oppervlak niet overeenkomt met het opgegeven perceel. Zachte fouten kunnen vooralsnog alleen optreden bij de services voor: • De (synchrone) validatie van een wijziging in perceelsregistratie. • Het opvragen van een validatie resultaat. In beide gevallen wordt er in deze situatie een validatieticket geretourneerd, in combinatie met de foutmeldingen. Echter, in volgende versies zullen zachte foutsituaties mogelijk ook optreden bij andere services. Vandaar dat de definities van alle geretourneerde XML berichten bestaan uit: • Maximaal één deel dat een resultaat teruggeeft, in geval het verzoek succesvol verwerkt is • Een willekeurig aantal foutsituaties.
De exacte specificaties van de foutmelding volgen in 7.2.
Versie 1.2
20-09-2013
pagina 14
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
6
Specificatie van de SOAP services, het WSDL document
6.1
Inleiding
Behalve de WMS en WFS services, dienen alle Geoboer Services te worden aangeroepen als webservices door middel van SOAP. Het gebruik van deze services wordt dan gespecificeerd m.b.v. de Web Service Description Language (WSDL). Dit document bevat onder andere de structuur van de XML berichten die tijdens het gebruik van de services over en weer gestuurd worden. Een WSDL document is opgedeeld in specificaties voor: • De gebruikte types, voor elke service • De gebruikte messages, voor elke service • Het porttype • Binding • Service
6.2
XML Types
De gedefinieerde XML types zijn de types voor de input en output berichten van de twee verschillende services welke via SOAP worden aangeboden. De hier gedefinieerde types maken gebruik van de referenties naar de volgende, elders gedefinieerde elementen: • fouten • Properties • OptimalisatiePercelen • PerceelsWijzigingen Deze elementen zijn allemaal gedefinieerd in hoofdstuk 7.
Het porttype definieert de twee operaties (met input, output en eventuele foutberichten) welke door de SOAP service geboden worden. <portType name="geoboerPortType">
Versie 1.2
20-09-2013
pagina 18
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
6.5
Binding
Het binding element definieert het berichtformaat en protocol details voor elke geboden SOAP service. <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <soap:operation soapAction="http://www.minlnv.nl/ws/geoboer/wsdl/1.0/getTanOrder"/> <soap:body parts="parameters" use="literal"/> <soap:operation soapAction="http://www.minlnv.nl/ws/geoboer/wsdl/1.0/getValidationResult"/> <soap:body parts="parameters" use="literal"/> <soap:operation soapAction="http://www.minlnv.nl/ws/geoboer/wsdl/1.0/validatie"/> <soap:body parts="parameters" use="literal"/> <soap:operation soapAction="http://www.minlnv.nl/ws/geoboer/wsdl/1.0/optimalisatie"/> <soap:body parts="parameters" use="literal"/>
Versie 1.2
20-09-2013
pagina 19
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
7
XML Schemas
7.1
Inleiding
Definitief
Voorbeelden en XML schema’s voor deze berichten worden gespecificeerd in de volgende paragrafen.
7.2
Fouten
7.2.1
Voorbeeld
OPN-test1PCV <melding>Ongeldige gewascode Pas de gewascode aan.OPN-test2PCV <melding>Nog iets kleins OPN-test1PCV <melding>Ongeldige gewascode Pas de gewascode aan. Het regelnummer attribuut is niet verplicht.
7.2.2 Schema De foutenspecificatie zal altijd voldoen aan het volgende XML schema. <xsd:element name="fouten" type="foutenType"/> <xsd:complexType name="foutenType"> <xsd:sequence> <xsd:element ref="fout" minOccurs="1" maxOccurs="unbounded"/> <xsd:element name="fout" type="foutType"/> <xsd:complexType name="foutType"> <xsd:sequence> <xsd:element name="code" type="xsd:string"/> <xsd:element name="oorsprong" type="xsd:string"/> <xsd:element name="melding" type="xsd:string"/> <xsd:element name="toelichting" type="xsd:string"/> <xsd:attribute name="blokkerend" type="xsd:boolean" use="required" form="unqualified"/>
Versie 1.2
20-09-2013
pagina 21
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Dit type zal uitsluitend gebruikt worden voor het versturen van authorisatie-parameters. Vooralsnog betreffen dit uitsluitend het TAN volgnummer en de TAN Code.
7.3.1
Voorbeeld
TANVolgnummer34567TANCode7890
7.3.2
Schema
Het XML met deze properties zal altijd voldoen aan het volgende XML schema. <xsd:element name="Properties" type="propertiesType"/> <xsd:complexType name="propertiesType"> <xsd:sequence> <xsd:element ref="Property" maxOccurs="unbounded"/> <xsd:element name="Property" type="propertyType"/> <xsd:complexType name="propertyType"> <xsd:sequence> <xsd:element name="Name" type="xsd:string"/> <xsd:element name="Value" type="xsd:string"/>
7.4
PerceelsWijzigingen
Versie 1.2
20-09-2013
pagina 22
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
Voor de services ter validatie en opgave wordt een verzameling perceelswijzigingen opgestuurd. Deze perceelswijzigingen dienen te worden uitgedrukt als hieronder gespecificeerd.
Dit schema bevat een referentie naar een element Perceel. Dit element is van het type PerceelType (zie paragraaf 7.5). <xsd:element name="PerceelsWijzigingen" type="perceelsWijzigingenType"/> <xsd:complexType name="perceelsWijzigingenType"> <xsd:sequence> <xsd:element ref="PerceelsWijziging" maxOccurs="unbounded"/> <xsd:element name="PerceelsWijziging" type="perceelWijzigingsType"/> <xsd:complexType name="perceelWijzigingsType"> <xsd:sequence> <xsd:element ref="Perceel"/>
Versie 1.2
20-09-2013
pagina 23
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
8
Voorbeelden
8.1
Opvragen van een luchtfoto
Definitief
Let op: ‘user-agent’ moet wel met de juiste waarde worden gevuld!! https://geoboer.agro.nl/geoboer/http?request=getmap&service=wms&FORMAT=JPEG&TRAN SPARENT=true&HEIGHT=600&version=1.1.1&Layers=0&WIDTH=800&BBOX=208000,553000,20 9000,554000&SRS=EPSG:28992
8.2
Opvragen percelen met HTTP/POST
De waarde content-type moet op ‘text/xml’ worden gezet, en ook de ‘user-agent’ header moet goed worden gezet. Daarna kan het volgende request worden gepost: lnv:einddatum2005-05-15lnv:relatienummer999999999
8.3
Opvragen Pipo percelen met HTTP/POST
De waarde content-type moet op ‘text/xml’ worden gezet, en ook de ‘user-agent’ header moet goed worden gezet. Daarna kan het volgende request worden gepost:
Versie 1.2
20-09-2013
pagina 26
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
the_geom188020,600094 188805,600632
8.4
Optimalisatie van een Geometrie
Als input wordt een optimalisatie request verzonden. 12345678….15-10-2006 <Marge>5 Als reactie wordt een optimalisatie response verstuurd, welke de geoptimaliseerde geometriëen bevat. …. …
8.5
Validatie van een wijziging in perceelsregistratie
Als input wordt een ValidatieRequest verstuurd: 45678912
Versie 1.2
20-09-2013
pagina 27
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
….12-11-2006……12.45623456789…….18-10-2006……45.67834567890... Indien de validatie synchroon uitgevoerd wordt, wordt de volgende response verstuurd: A789TUP9IU … Bij een asynchrone verwerking wordt de volgende response verstuurd: <Wachtrijnummer>527 …
8.6
Opgave van een wijziging in perceelsregistratie
<SubmitRequest>
Versie 1.2
20-09-2013
pagina 28
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
Definitief
45678912TAN TANVolgNummer …TANCode…. A789TUP9IU ….12-11-2006……12.45623456789…….18-10-2006….….45.67834567890…. De response bevat een communicatienummer en een inwindatum. <SubmitResponse> dd-mm-yyyy .…
Versie 1.2
20-09-2013
pagina 29
Ministerie van Economische Zaken, Landbouw en Innovatie – Geoboer - Interface Specificatie
