Gebruikershandleiding voor klanten van GDS

Transcriptie

1 0.1 Hoofdtitel Gebruikershandleiding voor klanten van GDS Datum 10 december 2012 Versie 2.2 ConceptKadaster

2 Versiehistorie Versie datum locatie omschrijving /12/2012 Gebruikershandleiding voor klanten van GDS /02/ /02/ vervangen door : vervallen en de downloadlocatie van de mock aangepast Versie / 11

3 Inhoudsopgave Inleiding Doel van dit document Algemeen Authenticatie URL en anonieme URL Belangrijkste kenmerken Aansluiten/Procedure Acties en aandachtspunten bij het inrichten van het proces Technische gegevens Testmodule (mock) Systeemgrenzen Begrippenlijst Beschrijving koppelvlak Inleiding Vraagbericht Responsbericht Het responsbericht kleine bestand...11 Versie / 11

4 Inleiding 1.1 Doel van dit document Dit document is bestemd voor klanten en softwareleveranciers. Het bevat informatie die van belang is om aan te sluiten op de (GDS) van het Kadaster. 1.2 Algemeen Jaarlijks levert het Kadaster een groot aantal informatieproducten aan het notariaat, makelaardij, overheid, financiële instellingen, de geo-sector en particulieren. Deze productlevering en gegevensverwerking vinden grotendeels online plaats. Het Kadaster heeft al enige tijd een Download Service in gebruik, waarbij u bestanden kunt ophalen via internet. Daartoe wordt een download-link (URL) via een naar u verstuurd. U kunt deze URL openen en het bestand ophalen. Om u daarbij nog beter van dienst te kunnen zijn, heeft het Kadaster een nieuwe Generieke Download Service (GDS) gebouwd die voor alle digitale leveringen van bestanden ingezet kan worden. In de vernieuwde versie is onder andere een automatische programma interface (webservice) aan de GDS toegevoegd. Dit stelt u in staat om de voor u beschikbare bestanden op te halen in een bestandenlijst, om deze vervolgens (eventueel geautomatiseerd) te kunnen downloaden. Deze mogelijkheid is interessant als u stelselmatig producten afneemt en die geautomatiseerd wilt verwerken in uw systemen. Ter verduidelijking van afkortingen en kadasterbegrippen is onder paragraaf 1.6 een begrippenlijst opgenomen. U kunt op dit moment op verschillende manieren bestanden ophalen. Hiervoor zijn een aantal communicatiekanalen gedefinieerd, die enerzijds aangeven hoe u op de hoogte wordt gebracht van nieuwe bestanden (afgiftes) en anderzijds hoe deze bestanden worden opgehaald. Notificatie ( , ebms 1 ) Voor elke afgifte wordt door het Kadaster een URL gegenereerd. Die URL wordt door middel van een e- mail of een andere vorm van notificatie zoals ebms u gestuurd. Door de URL in het bericht te activeren, wordt het bestand door u opgehaald. Webservice Via een webservice kunt u een bestandenlijst opvragen. Die bestandenlijst bevat informatie die u in staat stelt om de voor u gereedstaande bestanden op te halen. Indien gewenst kan hiermee het ophalen van bestanden volledig worden geautomatiseerd. Daarbij bestaan er twee varianten: o Een loket voor kleine bestanden Wanneer het een klein bestand betreft, kunt u met behulp van een AfgifteID uit de bestandenlijst het bestand downloaden. De gegevens worden in dat geval terugleverd in het responsbericht (als base64 encoded 2 bijlage). Hiervoor geldt wel dat het bestand niet groter mag zijn dan de maximum bestandsgrootte voor 1 Een ebms is een elektronisch bericht dat door de ontvanger automatisch kan worden verwerkt en staat voor EbXML Messaging Servicebericht. De ebms standaard is een protocol voor veilig en betrouwbaar berichtenverkeer tussen twee partijen dat garandeert dat berichten worden bezorgd. Dit bericht bevat de URL voor het te downloaden bestand. 2 Base64 encoded is een manier om binaire code te converteren naar ASCII-tekens. Versie / 11

5 webservice berichten (zie systeemgrenzen). Dit loket wordt nu nog voor een paar applicaties gebruikt, maar we gaan steeds meer over naar het loket voor grote bestanden. o Een loket voor grote bestanden Wanneer het een groot bestand betreft, kunt u met behulp van de URL uit de bestandenlijst het bestand (automatisch) downloaden. Het Kadaster bepaalt via welk loket een bestand beschikbaar wordt gesteld. 1.3 Authenticatie URL en anonieme URL Het Kadaster bepaalt of u een bestand anoniem of geauthenticeerd mag ophalen. Geauthenticeerd houdt in dat u zich bekend moet maken zodat kan worden nagegaan of u daadwerkelijk bent wie u beweert te zijn en het bestand mag ophalen. Dit kan door middel van een PKI 3 overheidscertificaat of via een login met een Gebruikers-id en wachtwoord. Bij gebruik van de Webservice is authenticatie altijd vereist. Dit houdt in dat u én het PKI-overheidscertificaat vooraf bij het Kadaster geregistreerd moeten zijn. Het Klantcontactcenter kan u informeren over de authenticatie plicht. Ook bij gebruik van het communicatiekanaal notificatie kan het Kadaster gebruik maken van een anonieme of een geautoriseerde download. In dat geval moet de persoon die de URL opent zijn Gebruikers-id en wachtwoord van Mijn Kadaster opgeven. Een certificaat authenticatie is ook mogelijk bij het notificatie kanaal, maar dat zal over het algemeen niet worden gebruikt. Een ebms wordt verstuurd over een certificaat-beveiligde verbinding en de afhandeling daarvan (het downloaden) zal doorgaans geautomatiseerd plaatsvinden. 1.4 Belangrijkste kenmerken De webservice voor het opvragen van de bestandenlijst kent de volgende kenmerken: Uitgebreide meta-informatie over het bestand en over de levering (dit kan verschillen per product) Een download-link (URL) die rechtstreeks toegang biedt tot het bestand of een AfgifteID die kan worden gebruikt om het bijbehorende bestand op te halen. Diverse mogelijkheden om de bestandenlijst te filteren. Het verzoek kan bijvoorbeeld zo worden ingesteld, dat alleen de nieuwe bestanden worden teruggemeld. De interface kan worden ingesteld voor een specifiek product van het Kadaster (bijvoorbeeld BAG Extract) door vermelding van het contractnummer en eventueel het artikelnummer (indien meerdere artikelen binnen één contract worden geleverd) uit de overeenkomst tot levering van het product. Hiermee kan een specifieke afhandeling worden gekoppeld aan de download voor de automatische verwerking van het product binnen de systemen van de klant. De webservice en mogelijk ook het notificatiekanaal vereisen een authenticatie via een PKIoverheidscertificaat. 3 PKI overheid is de Public Key Infrastructure (PKI) van de Nederlandse overheid. Net als elke andere PKI is het een systeem waarmee uitgiften en beheer van digitale certificaten kan worden gerealiseerd. PKIoverheid wordt beheerd door Logius. Versie / 11

6 1.5 Aansluiten/Procedure Om aan te sluiten op de GDS, via de webservice voor de bestandenlijst, moeten een aantal stappen worden doorlopen Acties en aandachtspunten bij het inrichten van het proces Bij het Kadaster moet worden geverifieerd of het betreffende product met behulp van de GDS te downloaden is. Aanbevolen wordt om per product een separaat proces in te richten dat de bestandenlijst van dat specifieke product uitvraagt. Op deze manier kunt u via een eigen applicatie de leveringen van bestanden automatisch ophalen en verwerken. Eventuele foutsituaties kunnen altijd optreden en het verdient aanbeveling hiervoor een afhandeling te definiëren. Als er tijdens het downloaden iets mis gaat, zoals bijvoorbeeld het uitvallen van de verbinding, zou een retry mechanisme in werking moeten treden om zo de eventuele onderbrekingen in het transport te kunnen opvangen. Als problemen worden ondervonden bij het opvragen van de bestandenlijst, kan deze altijd opnieuw worden opgevraagd. Bedenk daarbij dat, wanneer gebruik wordt gemaakt van de filterfunctie alleen de nieuwe (indicatie nog niet gerapporteerd), wellicht niet de originele bestandenlijst wordt getoond. In dat geval kan met het filtercriterium datum van/tot een bestandenlijst worden opgevraagd. De map waarin de gedownloade bestanden worden bewaard kan snel vol lopen. Sommige diensten van het Kadaster leveren bestanden van enkele gigabytes of leveren grote aantallen bestanden (zoals bijvoorbeeld in het kader van de Basisregistraties Kadaster en Topografie). Hou daarom rekening met de limiet van het maximaal aantal bestanden per map en richt zo nodig een schonings- en of archiveringsproces in. (Voor GDS is het maximum aantal bestanden per map vastgesteld 5000 bestanden). De bestanden worden in willekeurige volgorde in de bestandenlijst gezet. Iedere dienst van het Kadaster heeft een unieke bestandsnaam. Als een algehele unieke naam gebruikt moet worden bij het opslaan van het downloadbestand, dan kan de bestandsnaam uit de meta-data worden gebruikt. Deze bevat de fysieke bestandsnaam voorzien van een prefix bestaande uit de verkorte dienstnaam en een streepje (bijvoorbeeld: KLIC-MeldingRapport ). Een bestand kan gedurende de beschikbaarheidsperiode altijd opnieuw worden opgehaald, er zit geen limiet op het aantal downloads. We verzoeken u wel om de bestanden slechts éénmalig te downloaden en deze dan binnen uw organisatie te distribueren (dit in verband met fair use en bandbreedtegebruik) Technische gegevens Los van de functionele beschrijving van het koppelvlak (hoofdstuk 2) vindt u de technische definities van de interface (schema s) terug op: Voor informatie over een PKI overheidscertificaat: Testmodule (mock) Alvorens de interfaceconnectie definitief in productie te nemen kunt u deze testen met een speciale testmodule (mock). Met deze testmodule kunnen de eigenschappen en gedragingen van Kadaster programmatuur worden gesimuleerd. U kunt de testmodule gratis downloaden: Versie / 11

7 1.5.4 Systeemgrenzen Om systemen te beschermen tegen te grote bestanden en/of berichten zijn door het Kadaster systeemgrenzen ingesteld. Deze systeemgrenzen kunnen wijzigen. De huidige waarden zijn op vastgesteld. Systeemgrens Maximale bestandsgrootte download Maximale bestandsgrootte webservice Maximale aantal bestandsvermeldingen per bestandenlijst Toelichting Het systeem GDS kent als maximale bestandsgrootte 4 Gb. Uw contactpersoon bij het Kadaster kan u informeren over de te verwachten maximale bestandsgrootte per product. De maximale bestandsgrootte van een bestand bij het loket kleine bestanden dat als payload wordt teruggegeven in het responsbericht als Base64 encoded bijlage (<100Kb). Een bestandenlijst bevat maximaal 2000 bestandsvermeldingen. Wordt dit aantal wordt overschreden, dan worden alleen de eerste 2000 bestanden teruggemeld. Wij adviseren u om regelmatig een bestandenlijst op te vragen om dit probleem te voorkomen. 1.6 Begrippenlijst Afkorting Afgifte BAG BRK ebms GDS GIS KLIC Notificatie PKI URL XML Toelichting De levering van één bestand aan één klant Basisregistraties Adressen en Gebouwen Basisregistratie Kadaster volgens de wet Basisregistraties Kadaster en Topografie EbXML Messaging Servicesbericht Generieke download service Geografisch informatie systeem Kabels en Leidingen Informatie Centrum aanzegging, betekening, kennisgeving Public Key Infrastructure, een systeem waarmee uitgifte en beheer van digitale certificaten kan worden gerealiseerd. Uniform Resource Locator, een gestructureerde naam die verwijst naar een stuk data. extensible Markup Language, een standaard waarmee gestructureerde gegevens weergegeven kunnen worden in de vorm van platte tekst. Versie / 11

8 2 Beschrijving koppelvlak 2.1 Inleiding Bij de uitwerking van de webservice voor de bestandenlijst met download-links is rekening gehouden met de Digikoppeling-standaard voor grote berichten. Dit vindt u terug in de toepassing van het standaardelement datareference. Voor meer informatie verwijzen wij u naar de Koppelvlakstandaard Grote Berichten Document versie 0.99 van Logius. In onderstaande tabellen worden de volgende notaties gehanteerd voor multipliciteit: 1 De rubriek is verplicht 0..1 De rubriek is optioneel (kan 0 of 1 keer voorkomen) 0..N De rubriek kan 0, 1 of meer keer voorkomen 2.2 Vraagbericht Het opvraagverzoek dient te voldoen aan het daarvoor gedefinieerde schema. In onderstaande tabel vindt u de beschrijving van het opvraagbericht en de controles die worden uitgevoerd. De naamgeving van de rubrieken kan enigszins afwijken van de namen in het schema. Rubriek Multipliciteit Formaat / lengte Toelichting Contractnummer 0..1 Tekst (10) Indien vermeld dan worden alleen de bestanden opgenomen in de lijst die gekoppeld zijn aan het genoemde contractnummer. Artikelnummer 0..1 Tekst (20) Indien vermeld dan worden alleen de bestanden opgenomen in de lijst die horen bij het genoemde artikelnummer. Indicatie nog niet gerapporteerd 0..1 Boolean Met deze indicatie wordt aangegeven of uitsluitend de nog niet gerapporteerde bestanden moeten worden opgenomen in de lijst, of dat alle beschikbare bestanden worden genoemd. Niet gerapporteerd betekent in dit geval niet eerder opgevraagd in deze bestandenlijst. Als deze indicator wordt gebruikt, dan worden na terugmelding van de bestandenlijst de bijbehorende bestanden gemarkeerd als zijnde gerapporteerd in het systeem van GDS. Datum/tijd vanaf 0..1 DatumTijd Indien vermeld worden alleen de bestanden (afgiftes) opgenomen in de lijst met een aanmeldingstijdstip NA genoemde datum/tijd. Datum/tijd tot 0..1 DatumTijd Idem, met een aanmeldingstijdstip TOT genoemde datum/tijd. Op basis van deze selectiecriteria worden alle bestanden geselecteerd die op dat moment beschikbaar voor u beschikbaar zijn. De klantselectie vindt plaats via het klantnummer uit de authenticatie. N.B.: Wij adviseren u om altijd gebruik te maken van de indicatie nog niet gerapporteerd, om zo de nieuwe bestanden op te halen. De selectie op datum/tijd is bedoeld voor het geval er in eerdere aanroepen iets is misgegaan. Versie / 11

9 2.3 Responsbericht De bestandenlijst ziet er ongeveer als volgt uit: Figuur 1 Hoofdstructuur bestandenlijst Figuur 2 Rubrieken in de bestandenlijst N.B.: Deze figuren zijn een logische weergave. De technische uitwerking in het schema kan iets afwijken. Vooral bij de presentatie van de URL wordt de DigiKoppeling standaard gevolgd door toepassing van het standaardelement data-reference. Als er meer bestanden (afgiftes) zijn dan het huidige maximum aantal (zie systeemgrenzen) dat is toegestaan voor één opvraag, dan wordt dit teruggemeld via het element MeerAfgiftesBeschikbaar (deze bevat dan de waarde J ). In dat geval kan een nieuwe bestandenlijst worden opgevraagd voor de resterende bestanden (zie hoofdstuk 1.3). In onderstaande tabel vindt u een beschrijving van de rubrieken: Versie / 11

10 Rubriek Multipliciteit Formaat / lengte Toelichting Afgifte 0..N Afgifte is de interne GDS-benaming voor een levering van een bestand aan een klant. Is de bestandenlijst leeg, dan zijn er geen bestanden voor de klant beschikbaar. Per afgifte: Contractnummer 0..1 Tekst (10) Het contractnummer waaronder het product aan de klant wordt geleverd. Bestandsnaam 1 Tekst (128) De unieke bestandsnaam. Deze wordt opgebouwd uit de volgende elementen: <Verkorte dienstnaam> - <Fysieke bestandsnaam> (Bijvoorbeeld: KLIC-MeldingRapport ) De fysieke bestandsnaam is uniek binnen de betreffende dienst van het Kadaster. Artikelnummer 0..1 Tekst (20) Het artikelnummer van het product. Binnen een contract kunnen meerdere artikelen geleverd worden. Artikelomschrijving 0..1 Tekst (80) De officiële benaming van het product. Bestandsreferentie 0..1 Tekst (1 kb) Nadere informatie over dit specifieke bestand. De betreffende dienst kan hierbij kiezen voor een eigen indeling van deze rubriek (eventueel met XML-elementen). Voor nadere informatie hierover verwijzen we u naar uw contactpersoon bij het Kadaster. Afgifte referentie 0..1 Tekst (1 kb) Nadere informatie over deze specifieke levering. De betreffende dienst kan hierbij kiezen voor een eigen indeling van deze rubriek (eventueel met XML-elementen). Voor nadere informatie hierover verwijzen we u naar contactpersoon bij het Kadaster. Beschikbaar tot 1 DatumTijd De uiterste datum/tijd waarop de beschikbaarheid van dit bestand voor u is gegarandeerd. URL 1 Tekst (256) Indien géén authenticatie vereist is bij download dan wordt deze URL ingevuld met een zogenaamde anonieme URL en anders met een certificaat URL. Bij een anonieme URL is bij activering ervan geen authenticatie vereist. Bij een certificaat URL is authenticatie met een PKI overheidscertificaat vereist (overeenkomstig het gebruik van deze webservice zelf). Checksum type 1 Tekst (20) Het type checksum dat bij dit bestand is meegeleverd. Vooralsnog is de defaultwaarde van het type MD5. Versie / 11

11 Rubriek Multipliciteit Formaat / lengte Toelichting Checksum 1 Tekst (32) De berekende checksum van het bestand, zoals de betreffende dienst die heeft berekend. Is de checksum niet berekend dan wordt hier de defaultwaarde 0 (nihil) ingevuld. Bestandsgrootte 1 Positive integer De bestandsgrootte zoals vastgesteld door de betreffende dienst. Deze kan ook de waarde 0 bevatten (nihil = niet bepaald). 2.4 Het responsbericht kleine bestand Betreft het een klein bestand, dan kunt u met behulp van een AfgifteID uit de bestandenlijst een andere webservice aanroepen, welke het bestand dan rechtstreeks teruglevert in het responsbericht (als base64 encoded bijlage) Het responsbericht wordt samengesteld overeenkomstig onderstaande tabel. Rubriek Multipliciteit Formaat / lengte Herkomst AfgifteID 1 Tekst (36) Dit Klantnummer moet een bekend AfgifteID zijn binnen GDS. De klant die de aanvraag indient moet overeenkomen met het klantnummer uit de betreffende Afgifte. Bestandsnaam 0..1* Tekst (128) De unieke bestandsnaam, opgebouwd uit de volgende elementen: <Verkorte dienstnaam> - <Fysieke bestandsnaam> (Bijvoorbeeld: KLIC-MeldingRapport ) Base64 encoded bijlage 0..1* bijlage Het bestand als Base64 encoded bijlage Versie / 11