BBR OIOXML. Vejledning til OIOXML snitflade for Bygninger og boliger BuildingDwelling.wsdl

Transkript

1 OIOXML Vejledning til OIOXML snitflade for Bygninger og boliger BuildingDwelling.wsdl En vejledning rettet mod 3. part.

2 Ændringer i forhold til forrige versioner Version Version Version Version Version 2.0 Første version, 01. maj juni 2010 Mange to be written steder er blevet skrevet. Implementering og beskrivelse af teknisk anlæg afventer (på grund af DIADEM felter) Nogle steder er markeret med to be written. Disse afsnit skrives snarest. Andre steder er markeret med gul farve. Disse skrives når implementringen af snitfladerne er afsluttet idet disse steder kræver afklaring. metoderne er blevet beskrevet nærmere oprettelse og sletning af geometripunkter er beskrevet teknisk anlæg er blevet opdateret 29. juni produktionsversion (svarende til BuildingDwellingServiceV1.svc) Tegning vedr. repræsentative adresser tilknyttet Ændring af navn til BuildingDwelling.wsdl Alle strukturer og metoder er beskrevet færdigt Webservice version 2, BuildingDwellingServiceV2.svc 15. december 2010 ( Kommune version 1.2. lægges i produktion) Søgningen er begrænst til 100 resultater (tilføjet til vejledningen) Beskrivelse af hvordan man sletter et ejerskab tilføjet Opdatering af links i kapitel 1 Ny kapitel 4.13 Datatyper Ny kapitel 4.14 Udviklingsværktøjer Afsnit 16.2 (Kodeeksempel for kald af certifikat) tilføjet Opdatering af strukturer på grund af nye felter i Nyt version 1.2 eller andre ændringer/fejlrettelser o o o o o o o Pålæg fra stormområdet ny kodeliste Gyldighedsdato på 7 entiteter (flyttet fra update/create metoder til selve entitetsstrukturerne) Afløbsforhold nye kodeværdier og nye kodeoversættelser Nyt felt Omfattet af byggeskadeforsikring Forsikringsselskab ny kodeliste (kode 3 slettet, kode 8 tilføjet) En byggesag Et teknisk anlæg kan oprettes på en grund uden vandforsyning og afløbsforhold. Snitfladebeskrivelse Side 2 af 294

3 o Beskrivelsen vedr. midlertidig afslutning er udvidet med beskrivelse for afslutning af byggesager med teknisk anlæg o Felt FloorDeviationStatusIndicator hedder nu FloorDeviationStatusCode på grund af fejl i version 1. o o o o Felt DrainagePermissionCode er blevet opdateret på grund af fejl i version 1. Felt PublicSubsidyCode er blevet opdateret på grund af fejl i version 1. Felt WaterSupplyCode er blevet opdateret på grund af fejl i version 1 (kode 7 manglede). Kode 1 har fået ny kodeoversættelse. Felt LegalUseCode er blevet opdateret på grund af fejl i version 1 (kode I manglede og kode blank er blevet fjernet) o Felt TechnicalInstallationContentCode: Tekst oliebekendtgørelsens 6, stk. 1 nr. 11 rettet til oliebekendtgørelsens 6, stk. 1 nr. 13 Version 3.0 Version 1.0 af snitfladen udfases (BuildingDwellingServiceV1.svc) Webservice version 3, BuildingDwellingServiceV3.svc lægges i produktion den 21. juni 2011 ( Kommune version 1.3.) Bygning/Grunde Bygning 7 nye felter i strukturen WaterDrainage, som angiver yderligere spildevandsoplysninger. Ny kodeliste (ændrede kodeoversættelser og nye koder) til feltet DrainageCode (afløbsforhold) Ny kodeliste (ændrede kodeoversættelser og nye koder) til feltet DrainagePermissionCode (afløbsforholdtilladelse) Ny struktur på bygning, som angiver om bygningen er under flytning til en anden kommune (MunicipalityRelocation) Ny kodeliste for feltet Forsikringsselskab, BuildingDamageInsuranceCompanyCode i strukturen BuildingInsurance. Kode 09 er tilføjet. Ny version af feltet Pålæg fra Stormrådet (StormCouncilInstructionCode), idet feltet ændrer navn til Selvrisiko ved oversvømmelse jf. Stormrådet. Det engelske navn for xsd skemaet bibeholdes, men der tilføjes en ny metadatafil og der laves en ny version af strukturen. Teknisk anlæg Snitfladebeskrivelse Side 3 af 294

4 Ny xsd fil til TechnicalInstallationContentCode, idet xsd filen ved en fejl manglede kode 40. Nyt felt Sløjfningsår (TechnicalInstallationAbolishYearIdentifier) i strukturen TechnicalInstallationInformation Version 4.0 Webservice version 4, BuildingDwellingServiceV4.svc lægges i produktion den 9. februar 2012 ( Kommune version 1.4.) Version 2.0 af snitfladen udfases (BuildingDwellingServiceV2.svc) Identændringer Flere muligheder for identændringer for bygning, teknisk anlæg og opgang. Disse er beskrevet i afsnit , og og Ny funktion på grundniveau, som flytter alle entiteter fra en matrikel til en anden (afsnit 5.1.1) Historiske data Nyt afsnit Historiske data, som beskriver at snitfalden ikke giver adgang til historiske data. (afsnit 3.7). Ny mulighed for at slette data fra historikken (afsnit 3.7). Dette indebærer en ny metode <Entitity>DeleteHistoric for hvert niveau. Grund Ny metode SiteMoveEntities som flytter alle entiteter fra en matrikel til en anden (afsnit 5.1.1) Enhed Ny kodeliste for feltet Boligtype (DwellingTypeCode) i strukturen BuildingUnitInformation. Det tidligere brugte xsd skema DwellingTypeCode fra namespacet for feltet Boligtype indeholder desværre ikke værdien E. Det betyder at snitfladen i version 3.0 fejler, når man henter en enhed med boligtype E. Fejlen er rettet ved at definere et nyt skema i version 4.0. Ny kodeliste for feltet Offentlig Støtte (PublicSubsidy- Code) i strukturen BuildingUnitInformation. Det tidligere brugte skema mangler fejlagtigt kodeværdi 0. Bygning Nye muligheder for identændringer Ny kodeliste for feltet Forsikringsselskab, BuildingDamageInsuranceCompanyCode i strukturen BuildingInsu- Snitfladebeskrivelse Side 4 af 294

5 rance. Koderne 10, 11, 12 og 13 er tilføjet. Ny kodeliste for feltet Tagdækningsmateriale (Roofing- MaterialCode) og Supplerende Tagdækningsmateriale(RoofingSupplementaryMaterialCode) i strukturen BuildingMaterial. Kode 20 Grønne tage er tilføjet. Ny version af feltet Dato for pålæg fra Stormrådet (StormCouncilInstructionDate) i strukturen BuildingInsurance, idet feltet ændrer navn til Dato for skade hos Stormrådet. Det engelske navn for xsd skemaet bibeholdes, men der tilføjes en ny metadatafil og der laves en ny version af strukturen. Tilføjelse, at feltet byggeskadeforsikring kan indberettes på nybyggerier og stambygninger. Teknisk anlæg Nye muligheder for identændringer Opgang Nye muligheder for identændringer Byggesag Afsnit 3.5 er tilrettet i forbindelse med en revidering af byggesagskoderne. Diverse Feltet Sagstype i strukturen EntityBuildingCaseInformation hed fejlagtigt BuildingCaseFileTypeCode i vejledningen og er nu blevet rettet til BuildingCaseTypeCode, som er det rigtige navn. Sætningen For København og Frederiksberg gennemføres disse kald til KMS ikke. (afsnit 3.6.1) er fjernet. Sætningen for Københavns og Frederiksberg dog fra den kommunale matrikel. (3.6.1.) er fjernet. Snitfladebeskrivelse Side 5 af 294

6 Indholdsfortegnelse Indholdsfortegnelse Introduktion Formål og målgrupper Forretningsviden De forskellige entiteter i og deres sammenhæng Adressers tilknytning til niveauer i Bygninger og boliger Stamentiteter Sagsentiteter Byggesager Mulige byggesagskoder Afslutning af en byggesag Overførsel af data fra sag til stam Midlertidig afslutning af en byggesag Delvis afslutning af en byggesag Indflytning Henlæggelse Sletning af sagsentitet i en byggesag Sletning af byggesag Kopiering af byggesager Koordinater til bygning og teknisk anlæg Foreløbige koordinater Kontrol af koordinater Historiske data Overblik over webservices og metoderne Sandsynlighedskontroller (IgnoreWarningIndicator) Udskrivning af Meddelelser (printenableindicator) Gyldighedsdato (AssessmentChangedDate) Den implementerede opdateringsmekanisme Rettigheder Styring af opdateringer (RecordChangeDateTime) Sagstype (BuildingCaseTypeCode og updatereasoncode) Resultat for metodekald (ReturnMessage) Skemavalidering UniversalIdentifier og Reference Placeholder-problematik <Entity>GetById og <Entity>GetByIds metoder <Entity>GetByParentId metoder <Entity1>GetBy<Entity2>Id metoder BuildingCaseGetByEntityId metode Delete og update metoder Namespaces Datatyper Udviklingsværktøjer Rettigheder Strukturer til entiteter - <Entity>Structure SiteStructure Mulighed for identændringer SiteKeys Snitfladebeskrivelse Side 6 af 294

7 SiteInformation AddressComplete WaterDrainage EntityBuildingCaseInformation ExternalReferences MunicipalityFields NoteStructure BuildingStructure Mulighed for identændringer BuildingKeys BuildingInformation AddressComplete CondominiumStructure ConstructionPoint BuildingHeating BuildingArea BuildingArrangement BuildingMaterial WaterDrainage EntityBuildingCaseInformation BuildingInsurance ExternalReferences MunicipalityFields NoteStructure MunicipalityRelocation EntranceStructure Mulighed for identændringer EntranceKeys EntranceInformation AddressComplete EntityBuildingCaseInformation ExternalReferences MunicipalityFields NoteStructure FloorStructure Mulighed for identændringer FloorKeys FloorInformation FloorArea EntityBuildingCaseInformation ExternalReferences MunicipalityFields NoteStructure BuildingUnitStructure Mulighed for identændringer BuildingUnitKeys BuildingUnitInformation AddressComplete EntityBuildingCaseInformation CondominiumStructure BuildingUnitHeating BuildingUnitArea BuildingUnitInterior ExternalReferences MunicipalityFields Snitfladebeskrivelse Side 7 af 294

8 NoteStructure TechnicalInstallationStructure Mulighed for identændringer TechnicalInstallationKeys TechnicalInstallationInformation AddressComplete ConstructionPoint EntityBuildingCaseInformation CondominiumStructure ExternalReferences MunicipalityFields NoteStructure RoomStructure Mulighed for identændringer RoomKeys RoomInformation AddressComplete EntityBuildingCaseInformation ExternalReferences MunicipalityFields NoteStructure UseUnitStructure Mulighed for identændringer UseUnitKeys UseUnitInformation UseUnitArea AddressComplete EntityBuildingCaseInformation ExternalReferences MunicipalityFields NoteStructure BuildingCaseStructure BuildingCaseKeys BuildingCaseInformation BuildingCaseDates BuildingCaseInformationDates BuildingCaseCompletionDates Fælles strukturer landparcelidentitystructure AddressComplete ConstructionPoint WaterDrainage EntityBuildingCaseInformation ExternalReferences MunicipalityFields CondominiumStructure NoteStructure Metoder til entitet grund SiteGetById SiteGetByIdRequestStructure SiteGetByIdResponseStructure SiteGetByIds SiteGetByIdsRequestStructure SiteGetByIdsResponseStructure Snitfladebeskrivelse Side 8 af 294

9 6.3. SiteGet SiteGetRequestStructure SiteGetResponseStructure SiteGetByMunicipalRealPropertyId SiteGetByMunicipalRealPropertyIdRequestStructure SiteGetByMunicipalRealPropertyIdResponseStructure SiteGetByParentId SiteGetByParentIdRequestStructure SiteGetByParentIdResponseStructure SiteGetSubStructuresById SiteGetSubStructuresByIdRequestStructure SiteGetSubStructuresByIdResponseStructure SiteCreate SiteCreateRequestStructure SiteCreateResponseStructure SiteUpdate SiteUpdateRequestStructure SiteUpdateResponseStructure SiteDelete SiteDeleteRequestStructure SiteDeleteResponseStructure SiteMoveEntities SiteMoveEntitiesRequestStructure SiteMoveEntitiesResponseStructure Metoder til entitet bygning BuildingGetById BuildingGetByIdRequestStructure BuildingGetByIdResponseStructure BuildingGetByIds BuildingGetByIdsRequestStructure BuildingGetByIdsResponseStructure BuildingGet BuildingGetRequestStructure BuildingGetResponseStructure BuildingGetBySiteId BuildingGetBySiteIdRequestStructure BuildingGetBySiteIdResponseStructure BuildingGetByParentId BuildingGetByParentIdRequestStructure BuildingGetByParentIdResponseStructure BuildingCreate BuildingCreateRequestStructure BuildingCreateResponseStructure BuildingUpdate BuidlingUpdateRequestStructure BuildingUpdateResponseStructure BuildingDelete BuildingDeleteRequestStructure BuildingDeleteResponseStructure BuildingDeleteHistoric BuildingDeleteHistoricRequestStructure BuildingDeleteHistoricResponseStructure Metoder til entitet opgang/indgang Snitfladebeskrivelse Side 9 af 294

10 8.1. EntranceGetById EntranceGetByIdRequestStructure EntranceGetByIdResponseStructure EntranceGetByIds EntranceGetByIdsRequestStructure EntranceGetByIdsResponseStructure EntranceGet EntranceGetRequestStructure EntranceGetResponseStructure EntranceGetByBuildingId EntranceGetByBuildingIdRequestStructure EntranceGetByBuildingIdResponseStructure EntranceGetByParentId EntranceGetByParentIdRequestStructure EntranceGetByParentIdResponseStructure EntranceCreate EntranceCreateRequestStructure EntranceCreateResponseStructure EntranceUpdate EntranceUpdateRequestStructure EntranceUpdateResponseStructure EntranceDelete EntranceDeleteRequestStructure EntranceDeleteResponseStructure EntranceDeleteHistoric EntranceDeleteHistoricRequestStructure EntranceDeleteHistoricResponseStructure Metoder til entitet etage FloorGetById FloorGetByIdRequestStructure FloorGetByIdResponseStructure FloorGetByIds FloorGetByIdsRequestStructure FloorGetByIdsResponseStructure FloorGet FloorGetRequestStructure FloorGetResponseStructure FloorGetByBuildingId FloorGetByBuildingIdRequestStructure FloorGetByBuildingIdResponseStructure FloorGetByParentId FloorGetByParentIdRequestStructure FloorGetByParentIdResponseStructure FloorCreate FloorCreateRequestStructure FloorCreateResponseStructure FloorUpdate FloorUpdateRequestStructure FloorUpdateResponseStructure FloorDelete FloorDeleteRequestStructure FloorDeleteResponseStructure FloorDeleteHistoric FloorDeleteHistoricRequestStructure Snitfladebeskrivelse Side 10 af 294

11 FloorDeleteHistoricResponseStructure Metoder til entitet enhed BuildingUnitGetById BuildingUnitGetByIdRequestStructure BuildingUnitGetByIdResponseStructure BuildingUnitGetByIds BuildingUnitGetByIdsRequestStructure BuildingUnitGetByIdsResponseStructure BuildingUnitGet BuildingUnitGetRequestStructure BuildingUnitGetResponseStructure BuildingUnitGetByEntranceId BuildingUnitGetByEntranceIdRequestStructure BuildingUnitGetByEntranceIdResponseStructure BuildingUnitGetByFloorId BuildingUnitGetByFloorIdRequestStructure BuildingUnitGetByFloorIdResponseStructure BuildingUnitGetByParentId BuildingUnitGetByParentIdRequestStructure BuildingUnitGetByParentIdResponseStructure BuildingUnitCreate BuildingUnitCreateRequestStructure BuildingUnitCreateResponseStructure BuildingUnitUpdate BuildingUnitUpdateRequestStructure BuildingUnitUpdateResponseStructure BuildingUnitDelete BuildingUnitDeleteRequestStructure BuildingUnitDeleteResponseStructure BuildingUnitDeleteHistoric BuildingUnitDeleteHistoricRequestStructure BuildingUnitDeleteHistoricResponseStructure Metoder til entitet teknisk anlæg TechnicalInstallationGetById TechnicalInstallationGetByIdRequestStructure TechnicalInstallationGetByIdResponseStructure TechnicalInstallationGetByIds TechnicalInstallationGetByIdsRequestStructure TechnicalInstallationGetByIdsResponseStructure TechnicalInstallationGet TechnicalInstallationGetRequestStructure TechnicalInstallationGetResponseStructure TechnicalInstallationGetBySiteId TechnicalInstallationGetBySiteIdRequestStructure TechnicalInstallationGetBySiteIdResponseStructure TechnicalInstallationGetByBuildingId TechnicalInstallationGetByBuildingIdRequestStructure TechnicalInstallationGetByBuildingIdResponseStructure TechnicalInstallationGetByParentId TechnicalInstallationGetByParentIdRequestStructure TechnicalInstallationGetByParentIdResponseStructure TechnicalInstallationCreate TechnicalInstallationCreateRequestStructure Snitfladebeskrivelse Side 11 af 294

12 TechnicalInstallationCreateResponseStructure TechnicalInstallationUpdate TechnicalInstallationUpdateRequestStructure TechnicalInstallationUpdateResponseStructure TechnicalInstallationDelete TechnicalInstallationDeleteRequestStructure TechnicalInstallationDeleteResponseStructure TechnicalInstallationDeleteHistoric TechnicalInstallationDeleteHistoricRequestStructure TechnicalInstallationDeleteHistoricResponseStructure Metoder til entitet rum RoomGetById RoomGetByIdRequestStructure RoomGetByIdResponseStructure RoomGetByIds RoomGetByIdsRequestStructure RoomGetByIdsResponseStructure RoomGet RoomGetRequestStructure RoomGetResponseStructure RoomGetByFloorId RoomGetByFloorIdRequestStructure RoomGetByFloorIdResponseStructure RoomGetByBuildingUnitId RoomGetByBuildingUnitIdRequestStructure RoomGetByBuildingUnitIdResponseStructure RoomGetByParentId RoomGetByParentIdRequestStructure RoomGetByParentIdResponseStructure RoomCreate RoomCreateRequestStructure RoomCreateResponseStructure RoomUpdate RoomUpdateRequestStructure RoomUpdateResponseStructure RoomDelete RoomDeleteRequestStructure RoomDeleteResponseStructure RoomDeleteHistoric RoomDeleteHistoricRequestStructure RoomDeleteHistoricResponseStructure Metoder til entitet brugsenhed UseUnitGetById UseUnitGetByIdRequestStructure UseUnitGetByIdResponseStructure UseUnitGetByIds UseUnitGetByIdsRequestStructure UseUnitGetByIdsResponseStructure UseUnitGet UseUnitGetRequestStructure UseUnitGetResponseStructure UseUnitGetByBuildingId UseUnitGetByBuildingIdRequestStructure Snitfladebeskrivelse Side 12 af 294

13 UseUnitGetByBuildingIdResponseStructure UseUnitGetByParentId UseUnitGetByParentIdRequestStructure UseUnitGetByParentIdResponseStructure UseUnitCreate UseUnitCreateRequestStructure UseUnitCreateResponseStructure UseUnitUpdate UseUnitUpdateRequestStructure UseUnitUpdateResponseStructure UseUnitDelete UseUnitDeleteRequestStructure UseUnitDeleteResponseStructure UseUnitDeleteHistoric UseUnitDeleteHistoricRequestStructure UseUnitDeleteHistoricResponseStructure Metoder til entitet byggesag BuildingCaseGetById BuildingCaseGetByIdRequestStructure BuildingCaseGetByIdResponseStructure BuildingCaseGetByIds BuildingCaseGetByIdsRequestStructure BuildingCaseGetByIdsResponseStructure BuildingCaseGet BuildingCaseGetRequestStructure BuildingCaseGetResponseStructure BuildingCaseGetBySiteId BuildingCaseGetBySiteIdRequestStructure BuildingCaseGetBySiteIdResponseStructure BuildingCaseGetByEntityId BuildingCaseGetByEntityIdRequestStructure BuildingCaseGetByEntityIdResponseStructure BuildingCaseGetAllEntities BuildingCaseGetAllEntitiesRequestStructure BuildingCaseGetAllEntitiesResponseStructure BuildingCaseCreate BuildingCaseCreateRequestStructure BuildingCaseCreateResponseStructure BuildingCaseUpdate BuidlingCaseUpdateRequestStructure BuildingCaseUpdateResponseStructure BuildingCaseDelete BuildingCaseDeleteRequestStructure BuildingCaseDeleteResponseStructure Metoder til søgninger Søgekriterier AddressSearchRequestSubStructure SiteSearchRequestSubStructure BuildingSearchRequestSubStructure FloorSearchRequestSubStructure BuildingUnitSearchRequestSubStructure CondominiumSearchRequestSubStructure TechnicalInstallationSearchRequestSubStructure Snitfladebeskrivelse Side 13 af 294

14 RoomSearchRequestSubStructure UseUnitSearchRequestSubStructure BuildingCaseSearchRequestSubStructure Søgemetoder og søgeresultat Søgning på grunde SiteSearchRequestStructure SiteSearchResponseStructure Søgning på bygninger BuildingSearchRequestStructure BuildingSearchResponseStructure Søgning på opgange/indgange EntranceSearchRequestStructure EntranceSearchResponseStructure Søgning på etager FloorSearchRequestStructure FloorSearchResponseStructure Søgning på enheder BuildingUnitSearchRequestStructure BuildingUnitSearchResponseStructure Søgning på tekniske anlæg TechnicalInstallationSearchRequestStructure TechnicalInstallationSearchResponseStructure Søgning på rum RoomSearchRequestStructure RoomSearchResponseStructure Søgning på brugsenheder UseUnitSearchRequestStructure UseUnitSearchResponseStructure Søgning på byggesager BuildingCaseSearchRequestStructure BuildingCaseSearchResponseStructure Adgang til snitfladen Sikkerhed Kodeeksempel for kald af certifikat Autorisation Testmiljø Snitfladebeskrivelse Side 14 af 294

15 1. Introduktion Denne snitfladebeskrivelse beskriver en af de OIOXML snitflader BuildingDwelling, som systemet stiller til rådighed. Baggrunden for snitfladen er, at man ønsker at registrere og opdatere Bygninger og boliger -data i ved webservicebaseret overførsel fra et eksternt system i OIOXML format. Denne snitfladebeskrivelse svarer til følgende version af webservicen: BuildingDwellingServiceV4.svc. I produktionsmiljø findes snitfladens endpoint her: Snitfladens dokumentation, snitfladens wsdl dokumenter for både produktions- og demoversionen vil man kunne finde på s demoserver, hvor den kan tilgåes uden certifikater. Wsdl'en er ikke eksponeret i produktion. Man skal bruge den fra demomiljøet og erstatte endpointet når man vil køre op mod produktion. Snitfladebeskrivelsen giver kort sagt mulighed for fremsøgning samt opdatering af Bygninger og boliger -data i, herunder grunde, bygninger, opgange/indgange, etager, enheder, tekniske anlæg, rum, brugsenheder og ikke mindst byggesager. Kapitel 2 giver en mere detaljeret beskrivelse af snitfladens formål samt dens målgruppe. Kapitel 3 beskriver de grundlæggende begreber og definitioner for s bygnings- og boligoplysninger, herunder datasammenhængen. Kapitel 4 giver et overblik over webservicen BuildingDwelling og dens metoder, som udgør snitfladen. Kapitlet beskriver også nogle generelle forhold som gælder for alle metoder og strukturer hørende til webservicen. Kapitel 5 beskriver strukturerne, som benyttes til at beskrive de enkelte entiteter. Det er en og den samme struktur som benyttes for hver entitet, uafhængig af hvor den benyttes, dvs. i alle metoder som henter og opdaterer entiteterne samt i søgningerne. Kapitel 5 beskriver også nogle fælles strukturer, som benyttes på tværs af entiteterne. Kapitel 6 til 14 beskriver metoderne for hver entitet i detaljer. kapitel 6 beskriver metoderne hørende til entiteten grund kapitel 7 beskriver metoderne hørende til entiteten bygning kapitel 8 beskriver metoderne hørende til entiteten opgang/indgang kapitel 9 beskriver metoderne hørende til entiteten etage kapitel 10 beskriver metoderne hørende til entiteten enhed kapitel 11 beskriver metoderne hørende til entiteten teknisk anlæg kapitel 12 beskriver metoderne hørende til entiteten rum kapitel 13 beskriver metoderne hørende til entiteten brugsenhed kapitel 14 beskriver metoderne hørende til entiteten byggesag Kapitel 15 beskriver søgningerne. Snitfladebeskrivelse Side 15 af 294

16 Kapitel 16 beskriver de betingelser, som skal være opfyldt for at få adgang til snitfladen, deriblandt sikkerheden omkring snitfladen. Der gøres opmærksom på, at denne snitflade alene dækker data i 's Bygninger og boliger del. Ud over denne snitflade findes 4 andre snitflader, som er relevante, hvis man ønsker at udvikle applikationer til systemet. Snitfladen Address dækker over systemets adressedel og stiller metoder til hentning og opdatering af adgangs- og enhedsadresser til rådighed. Snitfladen Permission stiller funktionalitet til rådighed, som er relevant både når man benytter Address eller BuildingDwelling. Denne service tilbyder metoder til at få oplysninger om feltrettigheder i Nyt. Afhængig af hvilke roller man er tildelt i Nyt vil man have adgang til at læse, skrive eller læse/skrive til de enkelte felter. Snitfladen CodeList stiller funktionalitet til rådighed, som er relevant både når man benytter Address eller BuildingDwelling. Denne service tilbyder tre metoder til at få oplysninger om kodelister i Nyt. Snitfladen StreetName stiller funktionalitet til rådighed, som er relevant både når man benytter Address eller BuildingDwelling. Denne service tilbyder 2 metoder til at hente veje og adgangsadresser i. Vejledninger til snitfladerne kan finde her: Snitfladebeskrivelse Side 16 af 294

17 2. Formål og målgrupper Snitfladen har til formål at gøre det muligt for kommunerne at fremsøge og ajourføre Bygninger og boliger -data i. Snitfladen er en tovejskommunikation mellem en leverandør/kommune og systemet. Den gør det muligt at hente data fra systemet og den gør det muligt at sende data til opdatering af. Når der skrives "Bygninger og boliger"-data dækker det over de allerede nævnte 9 entiteter: Grund Bygning Opgang/indgang Etage Enhed Teknisk anlæg Rum Brugsenhed Byggesag Snitfladens funktioner henvender sig hovedsaglig til private eller offentlige itvirksomheder som ønsker at udvikle it-løsninger eller andre komponenter, der ved hjælp af webservicebaseret overførsel kan anvendes til at registrere eller opdatere 's bygnings- og boligoplysninger. Snitfladebeskrivelse Side 17 af 294

18 3. Forretningsviden For at kunne forstå den efterfølgende vejledning og snitfladens metoder er det vigtigt at kende de enkelte entiteter samt deres datasammenhæng. Snitfladen indeholder metoder hørende til de i kapitel 2 nævnte 9 entiteter. De første 8 entiteter og deres sammenhæng er beskrevet i afsnit 3.1. Entiteten byggesag adskiller sig fra de andre 8 entiteter og bliver beskrevet i afsnit 3.5. Afsnit 3.2. beskriver sammenhængen mellem adresser og entiter i Bygninger- og Boliger. Afsnit 3.3 og 3.4 beskriver forskellen mellem stamentiteter og sagsentiteter, som er vigtig at kende for at kunne forstå forretningslogikken omkring de 8 entiteter og entiteten byggesag. Afsnit 3.6 beskriver geometripunkter til tekniske anlæg og bygninger De forskellige entiteter i og deres sammenhæng Billedet på næste side viser sammenhængen mellem de 8 nævnte entiteter. Selv om matriklen vises som entitet på figuren, betragtes den ikke som en -entitet, idet matrikeloplysninger stammer fra KMS og ESR-systemerne og de kan således ikke oprettes, rettes eller slettes i. I snitfladen vil matrikeloplysninger altid blive leveret som en undertsruktur til de respektive entiteter. Entiteten byggesag er ikke med på tegningen idet den som nævnt adskiller sig fra de andre 8 entiteter. Som man kan se, er entiteterne knyttet til hinanden. En grund består altid af 1 til flere matrikler. Omvendt er en matrikel altid knyttet til præcis en grund. På en matrikel kan der være registeret 0 til flere bygninger og 0 til flere tekniske anlæg. Omvendt er en bygning altid knyttet til en matrikel og et teknisk anlæg er enten knyttet til en bygning eller direkte til en matrikel. Som noget nyt kan man oprette tekniske anlæg på ubebyggede grunde uden at der er indberettet kloak- og vandforhold på grunden. En bygning kan have tilknyttet 0 til flere opgange/indgange, 0 til flere etager, 0 til flere tekniske anlæg og 0 til flere brugsenheder. Omvendt er en opgang/indgang, en etage og en brugsenhed altid knyttet til en bygning. Et teknisk anlæg kan være knyttet til en bygning eller direkte til en matrikel. En opgang/indgang og en etage kan have 0 til flere tilknyttede enheder. Omvendt er en enhed altid knyttet til en opgang/indgang og til en etage i samme bygning. En etage eller en enhed kan have underliggende rum. Omvendt er et rum altid knyttet til en etage og et rum kan yderligere være knyttet til en enhed. Snitfladebeskrivelse Side 18 af 294

19 Brugsenheder, rum og tekniske anlæg har ikke nogen underliggende entiteter. I forbindelse med de enkelte metoder vil relationerne mellem entiteterne blive beskrevet endnu engang. Grund hedder på engelsk site og i servicen Site. Bygning hedder på engelsk building og i servicen Building. Opgang/indgang hedder på engelsk entrance og i servicen Entrance. Etage hedder på engelsk floor og i servicen Floor. Enhed hedder på engelsk unit og i servicen BuildingUnit for at markere at en enhed altid hører til en bygning. Teknisk anlæg hedder på engelsk technical installation og i servicen TechnicalInstallation. Snitfladebeskrivelse Side 19 af 294

20 Rum hedder på engelsk room og i servicen Room. Brugsenhed hedder på engelsk use unit og i servicen UseUnit. En byggesag er altid knyttet til en grund og de sagsentiteter som hører til byggesagen skal ligge under selv samme grund. Byggesag hedder på engelsk building case og i servicen BuildingCase. Ud over at entiteterne har deres indbyrdes sammenhæng, kan de have tilknyttet adresser. I denne webservice er denne tilknytning udtrykt via en reference til en adresse ident, hørende til en adgangs- eller enhedsadresse. Denne webservice giver mulighed for at oprette, ændre og slette referencer til adresser, men vil man oprette nye adresser, ændre eller slette adresser i s adressedel, skal man benytte sig af webservicen Address.wsdl Adressers tilknytning til niveauer i Bygninger og boliger En adresse kan bruges på flere niveauer i Bygninger og Boliger. I Bygninger og Boliger fungerer adressen som en simpel attribut, der beskriver beliggenheden af den pågældende entitet. Man kan også sige at Bygninger og Boliger anvender de adresser der er oprettet i Adresser. En adgangsadresse kan tilknyttes til følgende niveauer: Grund Bygning Teknisk anlæg Opgang En enhedsadresse kan tilknyttes til følgende niveauer: Enhed Brugsenhed Følgende niveauer har ingen adresse tilknyttet: Rum Etage Adressen er krævet for alle niveauer, som har en adresse, undtagen ubebyggede grunde, som ikke behøver at have en adresse. Der kan forekomme grunde uden adresse når grunde oprettes automatisk efter besked fra ESR/KMS. Når adresser tilknyttes til niveauer i Bygninger og Boliger kan følgende adresser benyttes: Gældende adgangsadresser og gældende enhedsadresser Nye foreløbige adgangsadresser med husnummer og tilhørende enhedsadresser Den samme adresse må gerne benyttes på flere niveauer i Bygninger og boliger. I tidligere versioner af Nyt har det ikke været muligt for to ejendomme at have den samme adresse. Denne begrænsning er fjernet. En adgangsadresse, som er knyttet til en bygning direkte kaldes også repræsentativ adgangsadresse. For de repræsentative bygningsadresser gælder det, at samme adgangsadresse kan benyttes for flere bygninger. På en Snitfladebeskrivelse Side 20 af 294

21 landbrugsejendom vil alle bygninger typisk have samme repræsentative adgangsadresse. For et enfamiliehus vil garagen typisk have samme repræsentative adgangsadresse som villaen. Adgangsadresser kan også knyttes til en bygning indirekte via bygningens opgang/indgange. Bygninger hvori der findes en eller flere opgange/indgange har tilknyttet en adgangsadresse for hver opgang eller indgang. En adgangsadresse kan i en bygning kun være tilknyttet til højst én opgang/indgang i bygningen. Hvis en bygning har mere end en opgang/indgang vil den have lige så mange adgangsadresser tilknyttet via opgangene/indgangene. Opgangsadresser skal være entydige i én bygning. To opgange i to forskellige bygninger på samme ejendom kan dog have den samme adresse. Dette imødekommer anneksproblematikken. Systemet vil dog give en advarsel i dette tilfælde. To opgange i forskellige ejendomme må ikke have den samme adresse. Disse regler skal også opretholdes, når man flytter en bygning til en anden matrikel. Der er sammenhæng mellem en opgangs adgangsadresse og de tilhørende enheders enhedsadresser. Enheder i en opgang har enhedsadresser, som ligger under den adgangsadresse, som opgangen har. Der gælder, at enhedsadresser og brugsenhedsadresser i to forskellige ejendomme ikke må være ens. Snitfladebeskrivelse Side 21 af 294

22 3.3. Stamentiteter Der skelnes mellem stamentiteter med status 1 og sagsentiteter med status 3. Sagsentiteter er nybyggerier (N) eller rettelser til stamentiteter (S). Hvis du vil rette, oprette eller slette en stamentitet, kan dette gøres direkte i stamdelen eller via en byggesag, hvor ændringer først bliver gældende ved afslutning af byggesagen. Sidstnævnte mulighed er nærmere forklaret i afsnit 3.5. Når entiteter slettes i stamdelen får de et ophørstimestamp og deres status ændres til 2. Stamentiteter vil altid ligge under andre stamentiteter i det i afsnit 3.1 beskrevne hierarki. Dvs. man kan fx ikke have en stam-brugsenhed som ligger under en bygning, som er et nybyggeri. Eller en stam-enhed som ligger under en etage eller opgang, der er nybyggerier Sagsentiteter Der findes 3 slags sagsentiteter: Nybyggerier (N) Til/ombygninger (S) Nedrivninger (S) Nedrivninger og til-/ombygninger refererer til den stamentitet de hører til, dvs. den de er en ændring til. I nedenstående eksempel peger sagsentiteten 14 på stamentiteten 13. Nybyggerier peger også på en stamentitet, men her drejer det sig om en slags placeholder for den senere stamentitet. Placeholderen har den id, som entiteten får, når sagen afsluttes og nybyggeriet overføres til stam. I nedenstående eksempel peger nybyggeriet 12 på en placeholder 11 i stamdelen. Id: 11 Placeholder for nybyggeri (status 1) Id: 13 Stamentitet (status 1) <Entity>ParentReference <Entity>ParentReference Id: 12 Nybyggeri (status 3) Id: 14 Ændring til stamentitet (nedrivning eller til/ombygning) (status 3) I nogle sjældne tilfælde kan man godt have en sag på et nybyggeri. I givet fald vil (S) entiteten pege på samme placeholder som (N) entiteten. Placeholdere er nærmere beskrevet i afsnit Når man opretter en sagsentitet (S), dvs. en ændring til en stamentitet, gøres det ved at angive stamentitetens id. Snitfladebeskrivelse Side 22 af 294

23 Der vil automatisk blive kopieret nogle får oplysninger fra stamentiteten over til sagsentiteten Byggesager En sagsentitet er altid knyttet til en byggesag. En byggesag kan samle en eller flere sagentiteter. Når en byggesag afsluttes ved angivelse af en eller flere nødvendige datoer afsluttes de tilhørende sagsentiteter og overføres til stamdata. Der må ikke være to sagsentiteter hørende til samme stamentitet i den samme byggesag. I enhver byggesag skal der normalt være en bygning (en (S)BYG eller (N)BYG)). Undtaget er byggesager som alene indeholder entiteter som ikke ligger under en bygning, dvs. ændringer til grunde ((S)GRU entiteter) eller ændringer eller nyopførelser af tekniske anlæg som ikke knytter sig til en bygning ((N)TEK hhv. (S)TEK entiteter). Opretter man fx en ny enhed, (N)ENH, og byggesagen ikke indeholder en bygning, vil der blive oprettet en (S)BYG entitet i byggesagen. Denne sagsentitet er en ændring til den bygning, som den nye enhed ligger under. Baggrunden for denne implementering er, at synkronisering af Nyt til KMD, i mange tilfælde kræver, at der forefindes en bygning i byggesagen. Der må kun være én bygning i en byggesag. En byggesag er altid knyttet til en grund og de sagsentiteter som hører til byggesagen skal ligge under selv samme grund Mulige byggesagskoder En byggesag skal have en af de nedenstående byggesagskoder: 1 BR Tilladelsessag uden ibrugtagningstilladelse 2 BR Anmeldelsessag (garager, carporte, udhuse og nedrivning) 3 BR Tilladelsessag med ibrugtagningstilladelse 4 BR Tilladelsessag uden landbrugsbygning 5 BR Anmeldelsessag (øvrige) Afslutning af en byggesag Når en byggesag afsluttes overføres data fra de tilhørende sagsentiteter ((N) hhv. (S) entiteter) til data i stam. En byggesag afsluttes ved at der angives en eller flere relevante datoer: For byggesagskode 1,2,4,5: Fuldførelsesdato udfyldes og sagen gemmes. For byggesagskode 3: Ibrugtagningsdato udfyldes og sagen gemmes (udfyldes der fuldførelsesdato uden indtastning af ibrugtagningsdato afsluttes sagen midlertidig, se afsnit 3.5.4). Ibrugtagningsdato indberettes kun ved byggesagskode 3. Mere nøjagtig sker der følgende ved afslutning af en byggesag: Data overføres fra sag til stam. Sagsentiteterne får status 4 og et ophørstimestamp. Byggesagen får et ophørstimestamp. Hvis byggesagen indeholder en nybyggeri bygning sættes opførelsesår. Hvis byggesagen indeholder et nybyggeri teknisk anlæg sættes etableringsår. Snitfladebeskrivelse Side 23 af 294

24 For nedrivninger gælder det, at stamentiteten slettes i stamdelen, dvs. får et ophørstimestamp og status 2. Dette gælder naturligvis kun ved nedrivning af hele entiteten. For tilladelsessager med byggesagskode 3 kan man afslutte byggesagen midlertidig eller delvis. Disse to typer er beskrevet i det følgende Overførsel af data fra sag til stam Når en byggesag afsluttes overføres data fra de tilhørende sagsentiteter ((N) hhv. (S) entiteter) til data i stam. For nybyggerier overføres alle data, men for sagsentiteter (S) overføres ikke alle felter. Følgende felter opfattes som hørende til sagsniveauet og overføres ikke til stamentiteter ved afslutning af en (S) entitet: ESDH reference Journalnummer Oprettelsesdato (RecordCreatedDateTime) Seneste ændringsdato (RecordChangeDateTime) Ved til- og ombygninger samt nedrivininger kan der forekomme negative værdier i f.eks. arelafelter, som trækkes fra det i stamdelen registrerede areal Midlertidig afslutning af en byggesag En byggesag med byggesagskode 3 kan afsluttes midlertidigt. Dette sker når en byggesag fuldføres, men ikke ibrugtages (fuldførelsesdato forskellig fra null, ibrugtagningstilladelse = null). Tidligere har der været et krav om en bygning i byggesagen for at kunne afslutte denne midlertidig, men dette krav er nu fjernet hvis byggesagen indeholder alene et teknisk anlæg. En midlertidig afslutning betyder, at data overføres fra sag til stam for alle sagsentiteter, men at byggesagen ikke afsluttes endeligt. Byggesagen venter på, at der angives en ibrugtagningsdato. Alle entiteter undtagen bygninger og tekniske anlæg fjernes fra byggesagen, men bygninger og tekniske anlæg vil som sagsentiteter forblive i byggesagen indtil den afsluttes helt. De kan dog ikke længere rettes. Et forsøg på at opdatere de forblivne sagsentiteter i byggesagen eller et forsøg på at rette selve byggesagen vil blive afvist. Det eneste der kan inddateres i byggesagen er ibrugtagningstilladelse. Alle andre data skal rettes i stam. Mere teknisk udtrykt sker der følgende ved en midlertidig afslutning af en byggesag: Data overføres fra sag til stam for alle sagsentiteter. Sagsentiteterne - undtagen bygninger og tekniske anlæg - får status 4 og et ophørstimestamp. Hvis det er nybyggerier, sættes deres opførelsestimstamp. Data for bygninger/tekniske anlæg overføres fra sag til stam men sagsentiteterne forbliver i byggesagen med status 3 og får ingen ophørstimestamp. Byggesagen får ikke et ophørstimestamp. Sagentiterne i byggesagen må ikke rettes, men der kan foretages rettelser i stamentiteterne. Snitfladebeskrivelse Side 24 af 294

25 Midlertidigstatus på stambygning sættes til 2 hvis nybyggeri og 4 hvis om/tilbygning. Først når der efterfølgende indtastes en ibrugtagningsdato på byggesagen vil sagsentiterne få status 4 og et ophørstimestamp, men der sker ingen overførsel af data fra sagsdata til stam. Stambygningens felt Midlertidig status resettes. (Dvs. det undersøges, om der er andre midlertidig afsluttede byggesager på samme bygning. I dette tilfælde sættes midlertidig status til 2 eller 4 alt efter nybyggeri eller ej. Hvis der ikke er andre midlertidigt afsluttede byggesager på bygningen sættes feltet til 0.) Delvis afslutning af en byggesag Byggesager med byggesagskode 3 og som indeholder enheder kan delvis afsluttes. Dette sker normalt når nogle enheder ibrugtages, mens andre endnu ikke er færdiggjort. Som det første skridt opdateres den (eller de) enhed(er) der skal afsluttes, med en dato i feltet Delvis ibrugtagning. Som det andet skridt indtastes dato for Delvis ibrugtagningstilladelse på byggesagen. I feltet Foreløbig færdiggjort bygningsareal indtastes et areal. Grunden til at det ikke bare kan beregnes ud fra enheden(erne) er, at der godt kan være noget fællesareal der også er færdiggjort. Når byggesagen gemmes sker følgende: Foreløbig færdiggjort bygningsareal vil blive adderet til feltet Færdiggjort bygningsareal i alt. Felterne Foreløbig færdiggjort antal lejligheder og Foreløbig færdiggjort antal lejligheder uden køkken beregnes. De enheder der har en dato i feltet Delvis ibrugtagning afsluttes. Hvis der er tale om nybyggeri afsluttes enhedens opgang og etage ligeledes. Hvis bygningen i byggesagen er et nybyggeri opdateres placeholderen med et opførelsesår. Stambygningen må stadig ikke opdateres. Midlertidstatus på bygningen i stam sættes til 1 hvis nybyggeri og til 3 hvis om-/tilbygning. Bygningens sagsdata overføres ikke til stamdata. Det er sagsbygningen som opdateres og ikke stambygningen. Der er muligt efter en delvis afslutning af byggesagen at foretage en fuldførelse af byggeriet før ibrugtagningstilladelse. Sker dette følges beskrivelsen i ovenstående afsnit Midlertidig afslutning af byggesag. En delvis afsluttet byggesag ibrugtages/afsluttes ved at indtaste dato for ibrugtagningstilladelse. Alle entiteter i byggesagen (inkl. bygningen) afsluttes og sagsdata overføres til stam på almindeligvis. Bygningens felt Midlertidig status resettes. (Dvs. det undersøges, om der er andre midlertidig afsluttede byggesager på samme bygning. I dette til sættes midlertidig status til 2 eller 4 alt efter nybyggeri eller ej. Hvis der ikke er andre midlertidigt afsluttede byggesager på bygningen sættes feltet til 0.) Snitfladebeskrivelse Side 25 af 294

26 Indflytning På en byggesag med byggesagskode 1 eller 3 kan man på en sagsenhed indtaste en indflytningsdato. Det vil afslutte denne enhed og overføre den til stam. Hvis det er en byggesagskode 1 foretages der en midlertidig afslutning af byggesagen. (KMD kan ikke håndtere en delvis afslutning af byggesagskode 1), dvs. alle sagsdata (ikke kun den ene enhed) flyttes til stam og byggesagen venter kun på fuldførelse. Følg beskrivelsen under afsnittet Midlertidig afslutning af byggesag. Det er ikke specielt hensigtsmæssigt at lave en midlertidig afslutning af byggesagen ved byggesagskode 1. Det giver kun mening for parcelhuse med én enhed, men hvis der er flere enheder i bygningen vil de alle blive afsluttet, selvom kun den ene har fået en indflytningsdato. Denne implementering skyldes, at synkroniseringen til KMD ellers ville fejle. Hvis det er en byggesagskode 3 simuleres en delvis ibrugtagningstilladelse. Enheden opdateres med Delvis ibrugtagning sat lig indflytningsdato. Byggesagen opdateres med Delvis ibrugtagningstilladelse sat til dags dato og byggesagens FærdigtBygningsareal sat lig med enhedens areal. Følg herefter beskrivelsen i Delvis afslutning af byggesag Henlæggelse Man henlægger en byggesag ved at udfylde henlæggelsesdatoen og gemme byggesagen. Byggesagen får et ophørstimestamp. Når en byggesag henlægges, henlægges også de underliggende sagentiteter, dvs. ophørstimestampet sættes og status ændres til Sletning af sagsentitet i en byggesag Man sletter en sagsentitet ved at benytte Slet entitet (Delete) metoden. Når en sagsentitet slettes, bliver ophørstimestampet sat, og status forbliver 3. En sletning af en sagsentitet tolkes som om entiteten aldrig burde have været oprettet Sletning af byggesag Man sletter en byggesag ved at benytte Slet byggesag (Delete) delete metoden på byggesagen. Byggesagen får et ophørstimestamp. Når en byggesag slettes, slettes også de underliggende sagsentiteter Kopiering af byggesager En byggesag er altid relateret til én grund, og sagsentiteter i en byggesag må kun høre til højst én bygning, dvs. må ikke høre til to forskellige bygninger. Disse regler bliver der taget højde for, når man identændrer entiteter og flytter dem til nye bygninger, ejendomme og grunde. I forbindelse med flytning af entiteter, kan byggesager blive involveret på forskellige måder: - Der flyttes et nybyggeri. - Der flyttes en stam-entitet, som har en tilhørende sagsentitet. - Der flyttes en entitet, som har en eller flere byggesager på et underliggende niveau. Snitfladebeskrivelse Side 26 af 294

27 Når byggesager er involveret i forbindelse med en identændring, bliver følgende regel anvendt: Hvis det er muligt, flyttes en byggesag sammen med alle dens sagsentiteter til den nye grund. Dette er dog kun muligt, hvis alle sagsentiteter i byggesagen kan flyttes med. Hvis byggesagen indeholder entiteter, som ikke kan flyttes med, vil byggesagen blive kopieret. Den kopierede byggesag vil have de samme attributter (dvs. byggesagsnummer, sagsbehandler mm.), som den byggesag, man kopierer. Hvis flere sagsentiteter i en byggesag flyttes umiddelbart efter hinanden, vil de efter flytningen igen komme til at ligge i samme byggesag, idet der ved flytningen af en sagsentitet bliver taget hensyn til, om der på den nye grund ligger en byggesag, som er en tidligere kopi af den byggesag, som sagsentiteten hører til. Den beskrevne regel gælder dog ikke for en nybyggeri-opgang, som flytter til en ny nybyggeri-bygning. Her flytter opgangen altid i samme byggesag, som nybyggeri-bygningen ligger i. Dette gælder også, hvis opgangen ikke samtidig flyttes til en anden grund. Hvis en nybyggeri-opgang flyttes under en nybyggeri-bygning, vil også alle andre sagsentiteter, som ligger i samme byggesag som opgangen, og som kan flyttes med, blive flyttet i samme sag. Eksempel 1 En (N)BYG entitet og en (N)TEK entitet ligger i den samme byggesag, og man ønsker at flytte dem til en ny grund en ad gangen. GRU 1 SAG MAT 1 (N)BYG (N)TEK Den første flytning af (N)TEK resulterer i, at byggesagen kopieres: GRU 1 SAG MAT 1 (N)BYG Snitfladebeskrivelse Side 27 af 294