OIOXML Vejledning til OIOXML snitflade for Adresser Address.wsdl Ændringer i AddressV2 En vejledning rettet mod 3. part.
Indholdsfortegnelse 1. Introduktion... 3 2. Ny opdateringsmekanisme i AddressV2... 4 3. Historik i AddressV2... 5 3.1. Sletning af data fra historik... 5 3.2. Adgang til historiske data... 5 4. Nye/ændrede felter i AddressV2... 5 4.1. Ny understruktur NoteStructure for adgangsadresse og enhedsadresse... 5 4.2. Ny indikator IncludeHistoricIndicator... 6 4.3. Nye skemaer til ResponseDates strukturer... 6 4.4. Nyt skema til felt ESDH reference... 6 4.5. Nyt skema til felt Sagsbehandler... 7 4.6. Nye skemaer til felterne RecordChangeDateTime og IgnoreWarningIndicator... 7 4.7. Ændret skema/metadata fil til AddressSpecificUserKeys... 7 5. Nye metoder i AddressV2... 7 5.1. Ny metode DeleteHistoric... 7 6. Fejlrettelser i AddressV2... 7 6.1. Afslutning af adressesag/nedlæggelse af en adresse... 7 Snitfladebeskrivelse Side 2 af 8
1. Introduktion Dette tillæg henvender sig til brugere af OIO XML snitfladen Address. OIO Address eksisteret/eksisterer i 2 versioner. AddressV1 har været i drift siden 15. 12. 2010 og denne version fortsætter med at ekistere intil der kommer en version 3 af snitfladen. AddressV2 er pr. 9.4.2013 den nyeste version af snitfladen. Denne vejledning henvender sig til alle brugere af snitfladen: Brugere af version 1 af snitfladen kan fortsætte med at benytte version 1, dog skal brugerne være opmærksomme på de i denne vejledning beskrevne uhensigtmæssigheder, som er forbundet med dette. Hvis de beskrevne uhensigtsmæssigheder har en betydning for brugerne, anbefales det, at man skifter til version 2 hurtigst muligt. Brugere af version 2 af snitfladen kan benytte denne vejledning for at få et hurtigt overblik over ændringer i version 2. I produktionsmiljø findes snitfladernes endpoint her: https://bbr-kommune.dk/services/servicegateway/addressv1.svc https://bbr-kommune.dk/services/servicegateway/addressv2.svc Snitfladernes dokumentation, snitfladernes wsdl dokumenter for både produktions- og demoversionen vil man kunne finde på s demoserver: http://demo.bbr-kommune.dk/services/ Snitfladebeskrivelse Side 3 af 8
2. Ny opdateringsmekanisme i AddressV2 Der er blevet implementeret en ny opdateringsmekanisme i AddressV2, sådan at alle felter kan nulstilles. I version 1 af snitfladen gælder det, at der kun opdateres de felter i Update metoderne, som sendes med. Et felt som ikke sendes med, berøres således ikke af opdateringen. For at slette et felt er der i version 1 blevet defineret null værdier, som skal indikere, at man vil slette et felt. Denne mekanisme har dog vist sig til at være mangelfuld, idet det har vist sig, at ikke alle felter kan nulstilles/slettes. Det har ikke været muligt at definere null værdier for alle felter, idet nogle af de benyttede xsd-skemaer ikke har tilladt dette. F.eks. er det i version 1 ikke muligt at slette et husnummer (sætte det til 0) efter en adresse er blevet oprettet med husnummer. xsd-skemaet for husnummeret tillader ikke 0 som en gyldig værdi. Den store forskel mellem version 1 og version 2 er, at en undladelse af et felt kan betyde en sletning af feltet i version 2. Dette gælder hovedsagelig for de felter, som ikke kan nulstilles/slettes på andre måder. Ændringen gælder for følgende strukturer/felter på adgangsadressen (AddressAccessRequestStructure): AddressAccessUserKeys med felterne Vejkode og Husnummer Kilde til adresse Kommunespecifikke felter Ændringen gælder for følgende strukturer/felter på enhedsadressen (AddressSpecificRequestStructure): AddressSpecificUserKeys med felterne Etagebetegnelse og Side/dørnummer Kilde til adresse Kommunespecifikke felter Alle andre felter vil stadigvæk kunne nulstilles/slettes ved at opdatere det med en null værdi (som i version 1 af snitfladen) og en undladelse af et felt vil ikke betyde en sletning af feltet. Alle snitflade brugere, som går over fra version1 til version 2 og som benytter snitfladen til at opdatere adresser skal være yderst opmærksomme på den nye opdateringsmekanismus. Hvor man førhen ikke har sendt et felt med fordi den ikke skulle opdatere, kan dette nu betyde at feltet bliver nulstillet. Ændringen behøver ikke at blive håndteret så længe man benytter version 1 af snitfladen. Man skal bare være opmærksom på, at disse muligheder nu er til rådighed i version 2. Snitfladebeskrivelse Side 4 af 8
3. Historik i AddressV2 3.1. Sletning af data fra historik Som noget nyt giver version 2 af snitfladen mulighed for at slette historiske data. I den forbindelse er der blevet tilføjet en ny metode til entiteterne adgangsadresse og enhedsadresse (se afsnit 5.1). Læs mere om denne nye funktionalitet i vejledningen for AddressV2. 3.2. Adgang til historiske data Som noget nyt giver version 2 af snitfladen adgang til historiske data, dvs. entiteter, der er udgået og har fået et ophørstimestamp. Det betyder, at adgangsadresser og enhedsadresser med objekttype 2, dvs. slettede stamadresser, kan fremsøges eller hentes via snitfladen. I den forbindelse er der blevet tilføjet en ny inputparameter IncludeHistoricIndicator til relevante metoder og ResponseDates strukturerne har fået tilføjet ophørstidspunktet (se afsnit 4.2 og 4.3). Læs mere om denne nye funktionalitet i vejledningen for AddressV2. 4. Nye/ændrede felter i AddressV2 4.1. Ny understruktur NoteStructure for adgangsadresse og enhedsadresse Som noget nyt kan version 2 af snitfladen håntere notater. I den forbindelse er der blevet tilføjet en ny struktur NoteStructure til request og response strukturerene for entiteterne adgangsadresse og enhedsadresse: AddressAccessRequestStructure AddressAccessResponseStructure AddressSpecificRequestStructure AddressSpecificResponseStructure Snitfladebeskrivelse Side 5 af 8
Læs mere om denne nye funktionalitet i vejledningen for AddressV2. 4.2. Ny indikator IncludeHistoricIndicator Det er nu muligt at fremsøge og hente historiske entiteter (se afsnit 3.2). I den forbindelse er der blevet tilføjet en ny inputparameter IncludeHistoricIndicator. Ved hjælp af feltet IncludeHistoricIndicator angiver man, om man ønsker, at foretage en historisk søgning hhv. hentning eller ej. Feltet findes på følgende metoder: AddressAccessGetById AddressSpecificGetById AddressSearch Læs mere om denne nye funktionalitet i vejledningen for AddressV2. 4.3. Nye skemaer til ResponseDates strukturer Det er nu muligt at fremsøge og hente historiske entiteter (se afsnit 3.2). I den forbindelse har ResponseDates strukturerne AddressAccessResponseDates og Address- SpecificResponseDates fået tilføjet ophørstidspunktet RecordExpiredDateTime. Læs mere herom i vejledningen for AddressV2. 4.4. Nyt skema til felt ESDH reference Feltet ESDHreferenceIdentifier har haft en fast længde på 200 karakter i version 1. Der er blevet lavet en ny skemafil, hvor feltet har fået en maksimal længde i stedet for. Alle strukturer, som benytter disse felter er som følge af det også opdateret. Ændringen har ikke nogen direkte betydning i forhold til brug af OIO snitfladen. Snitfladebeskrivelse Side 6 af 8
4.5. Nyt skema til felt Sagsbehandler Feltet CaseWorkerReference har haft en fast længde på 5 karakter i version 1. Der er blevet lavet en ny skemafil, hvor feltet har fået en maksimal længde i stedet for. Alle strukturer, som benytter feltet er som følge af det også opdateret. Ændringen har ikke nogen direkte betydning i forhold til brug af OIO snitfladen. 4.6. Nye skemaer til felterne RecordChangeDateTime og IgnoreWarningIndicator Felterne RecordChangeDateTime og IgnoreWarningIndicator findes i en nyere udgave, som benyttes i version 2 af snitfladen. Alle strukturer, som benytter disse felter er som følge af det også opdateret. Ændringen har ikke nogen direkte betydning i forhold til brug af OIO snitfladen. 4.7. Ændret skema/metadata fil til AddressSpecificUserKeys Feltet AddressSpecificUserKeys er opdateret, idet det havde en forkert metadatafil i version 1. Ændringen har ikke nogen direkte betydning i forhold til brug af OIO snitfladen. 5. Nye metoder i AddressV2 5.1. Ny metode DeleteHistoric For at slette en entitet fra historikken benyttes metoderne AddressAccessDeleteHistoric og AddressSpecificDeleteHistoric, som sletter en adgangsadresse hhv. enhedsadresse med status 2 fra historik. <Entity>DeleteHistoric metoden kaldes med id en for den udgåede entitet, som man ønsker at slette fra historik. Læs mere om denne nye funktionalitet i vejledningen for AddressV2. 6. Fejlrettelser i AddressV2 6.1. Afslutning af adressesag/nedlæggelse af en adresse I version 1 af snitfladen håndteres afslutning af en adressesag og nedlæggelse af en adresse som en almindelig opdatering, hvor ReturnIdentifier og ReasonIdentifier er 0 hvis sagen blev afsluttet hhv. adressen succesfuld nedlagt. Denne situation håndteres på en anden måde i version 2 af snitfladen. Her leveres den nu udgåede entitet ikke med tilbage og den succesfulde afslutning/nedlæggelse af entiteten markeres ved ReturnIdentifier 0 og ReasonIdentifier 20. Metode Kald Version 1 Version 2 AddressCaseUpdate Den afsluttede En adressesag afsluttes ved at angive en godkendelsesdato i strukturen AdressCase- adressesag leveres ikke som en del af svaret og der returneres Den afsluttede adressesag leveres ikke som en del af et svar, men der returneres ReturnIdentifier 0 og Snitfladebeskrivelse Side 7 af 8
ReasonIdentifier 20 i strukturen ReturnMessage. AddressAccessUpdate Den nedlagte adresse leveres ikke som en del af et svar, men der returneres ReturnIdentifier 0 og ReasonIdentifier 20 i strukturen ReturnMessage. AddressSpecificUpdate RequestStructure. Dette medfører at adressesagen afsluttes. En adgangsadresse kan nedlægges ved at angive en nedlæggelsesdato i strukturen AdressAccessRequestDates. Dette medfører at adressen nedlægges. En enhedsadresse kan nedlægges ved at angive en nedlæggelsesdato i strukturen AdressSpecificRequestDates. Dette medfører at adressen nedlægges. ReturnIdentifier 0 og ReasonIdentifier 0 i strukturen ReturnMessage. Den nedlagte adresse leveres som en del af svaret. Der returneres ReturnIdentifier 0 og ReasonIdentifier 0 i strukturen ReturnMessage. Den nedlagte adresse leveres som en del af svaret. Der returneres ReturnIdentifier 0 og ReasonIdentifier 0 i strukturen ReturnMessage. Den nedlagte adresse leveres ikke som en del af et svar, men der returneres ReturnIdentifier 0 og ReasonIdentifier 20 i strukturen ReturnMessage. Ændringen betyder, at brugere, som går fra version 1 til version 2 af snitfladen skal tage højde for, at afslutning af en adressesag og nedlæggelse af en adresse håndteres på en andelerledes måde i version 2. Snitfladebeskrivelse Side 8 af 8