OIOXML Vejledning til OIOXML-snitflade En vejledning rettet mod 3. part.
Ændringer i forhold til forrige versioner Første version, 19.11.2010 Snitfladebeskrivelser Side 2 af 10
Indholdsfortegnelse 1. Introduktion... 4 2. Formål og målgrupper... 5 3. Fælles strukturer... 6 3.1. ReturnMessage... 6 4. Supplerende varme... 7 4.1. Strukturer... 7 4.1.1. NotifierStructure... 7 4.1.2. SupplementaryHeatingDataStructure... 7 4.2. Metoder... 8 4.2.1. SupplementaryHeatingNotificationCreate... 8 4.2.1.1. SupplementaryHeatingNotificationCreateRequestStructure... 9 4.2.1.2. SupplementaryHeatingNotificationCreateResponseStructure... 9 5. Adgang til snitfladen... 10 5.1. Sikkerhed... 10 5.2. Autorisation... 10 5.3. Testmiljø... 10 Snitfladebeskrivelser Side 3 af 10
1. Introduktion Denne snitfladebeskrivelse beskriver en af de OIOXML-snitflader, snitfladen, som stiller til rådighed. IndputBoks-servicen opretter indberetninger i s inddataboks. Snitfladen findes på Kommune under: http://bbr-kommune.dk/services/ Dokumentationen findes i biblioteket documents : http://bbr-kommune.dk/services/documents. Servicen/WSDL en findes i biblioteket servicegateway : https://bbr-kommune.dk/services/servicegateway/ Beskrivelsen er inddelt i følgende kapitler: Kapitel 2 beskriver webservicens formål og målgruppe. Kapitel 3 beskriver fælles strukturer. Kapitel 4 Supplerende varme beskriver strukturer og metoder til de metodekald som opretter indberetninger i s inddataboks Kapitel 5 beskriver de betingelser, som skal være opfyldt for at få adgang til snitfladen, deriblandt sikkerheden, autorisation og testmiljø omkring snitfladen. Snitfladebeskrivelser Side 4 af 10
2. Formål og målgrupper Snitfladens funktioner henvender til EBST, som skal udvikle borgerapplikationen, der ved hjælp af webservicebaseret overførsel skal opdatere data i. Snitfladen InputBox stiller en metode til rådighed i, der er nødvendige for at indberette ændringer omkring supplerende varme på en bygning eller enhed. Snitfladebeskrivelser Side 5 af 10
3. Fælles strukturer 3.1. ReturnMessage Resultatet for alle metodekald leveres tilbage i en struktur kaldet ReturnMessage. Der skelnes mellem to forskellige slags svartyper: 1. Metodekaldet blev udført uden fejl. 2. Metodekaldet blev ikke udført på grund af fejl. I første tilfælde, hvis kaldet går godt, er ResponseReturnIdentifier lig med 0 og der returneres kun én ReturnMessage. I det andet tilfælde, hvis der opstår en fejl, er ResponseReturnIdentifier lig med 10 og der returneres kun én ReturnMessage. For hver besked sendes der følgende værdier tilbage: ReturnMessage Feltnavn i NYT OIOXML navn Kommentar Kommentar ResponseReturnIdentifier Beskriver hvilken type besked det drejer sig om. ResponseReasonIdentifier ResponseReasonText Koder: 0: OK 10: Fejl Nærmere detaljer for den returnerede besked. Hvis ReturnIdentifier er 0 forekommer følgende koder: 0: OK, kald udført 10: Fejl ved opret En beskrivelse af fejlen. Snitfladebeskrivelser Side 6 af 10
4. Supplerende varme Denne service tilbyder en metode til at oprette en sag i s inddataboks, som i version 1 kun inkludere opdatering af supplerende varme. 4.1. Strukturer 4.1.1. NotifierStructure Strukturen NotifierStructure benyttes til at repræsentere en indberetter til. Strukturen benyttes i metoden til at oprette en indberetning EntityStructure OIOXML navn NotifierNameText NotifierAddressText NotifierEmailText NotifierTelephoneText NotifierNoteText Kommentar Navn på indberetteren Adresse på indberetteren Email på indberetteren Telefonnummer på indberetteren Note fra indberetter omkring indberetningen 4.1.2. SupplementaryHeatingDataStructure Strukturen SupplementaryHeatingDataStructure beskriver oplysninger om ændringerne omkring supplerende varme. Snitfladebeskrivelser Side 7 af 10
PermissionStructure Feltnavn i OIOXML navn Kommentar Kommunekode MunicipalityCode Kommunekode. SupplementaryHeatingCode SupplerendeVarmeinstallation SupplerendeVarmeinstallation Koder: 0 - Ikke oplyst 1 - Varmepumpeanlæg 2 - Ovne til fast brændsel (brændeovn o. lign.) 3 - Ovne til flydende brændsel 4 - Solpaneler 5 - Pejs 6 - Gasradiator 7 - Elovne, elpaneler 10 - Biogasanlæg 80 - Andet 90 - Bygningen har ingen supplerende varme Bygning id BuildingUniversalIdentifier Den unikke tekniske nøgle til bygningen. Enhed ID BuildingUnitUniversalIdentifier Den unikke tekniske nøgle til enheden. 4.2. Metoder I det følgende beskrives den metode der udstilles i webservicen i forbindelse med indberetninger 4.2.1. SupplementaryHeatingNotificationCreate Metoden SupplementaryHeatingNotificationCreate opretter en indberetning ved angivelse af indberetterens attributter, samt oplysninger vedrørende supplerende varme på enten en bygning eller enhed. De i afsnit 4.2.1.1 og 4.2.1.2 viste tegninger viser metodens input og output struktur. Snitfladebeskrivelser Side 8 af 10
4.2.1.1. SupplementaryHeatingNotificationCreateRequestStructure SupplementaryHeatingNotificationCreateRequestStructure Feltnavn i OIOXML navn Kommentar NotifierStructure Indberetteren SupplementaryHeatingDataStructure Oplysninger vedrørende supplerende varme 4.2.1.2. SupplementaryHeatingNotificationCreateResponseStructure SupplementaryHeatingNotificationCreateResponseStructure Feltnavn i OIOXML navn Kommentar ReturnMessage Se afsnit 3.1. Snitfladebeskrivelser Side 9 af 10
5. Adgang til snitfladen 5.1. Sikkerhed Sikkerheden i webservicen er baseret på OIO-anbefalingen OWSA model T. Kort fortalt benytter denne sikkerhedsmekanisme HTTPS til sikker transport mellem to sikkerhedsdomæner og OCES-certifikater som autentifikation af Service Aftager. For at benytte webservicen skal Service Aftager : være autoriseret i (se afsnit 7.2) og have tilknyttet et gyldigt OCES virksomhedseller medarbejdercertifikat til autorisationen medsende ovennævnte certifikat ved alle webservicekald have installeret OCES-rodcertifikat I øvrigt henvises til IT- og Telestyrelsens beskrivelse af OWSA model T. Derudover henvises til DanIDs hjemmeside (www.danid.dk) for beskrivelse af hvordan man kan få det krævede certifikat og hvordan det installeres korrekt. 5.2. Autorisation For at kunne benytte snitfladen skal man kontakte en given kommune og bede om autorisation. Kommunen skal oprette jer som bruger og tildele jer den eller de passende roller i. De metoder der er beskrevet i denne vejledning kan kaldes bare man er autoriseret i. Der er ikke blevet udviklet selvstændige roller. 5.3. Testmiljø For at kunne teste snitfladen kan man benytte webservicen i s demomiljø. Du kan finde webservicen til test her: http://demo.bbr-kommune.dk/services I modsætning til produktionsmiljøet benyttes ingen sikkerhed eller certifikater i testmiljøet. Vær opmærksom på, at der skal anvendes kommunekode 881 når webservicen kaldes i demomiljøet. Snitfladebeskrivelser Side 10 af 10