Specifikation af Web Services til Danmarks Miljø Portal

Transkript

1 Specifikation af Web Services til Danmarks Miljø Portal

2 Indholdsfortegnelse Indholdsfortegnelse 1 Generelt Introduktion Forkortelser og Standarder Arkitektur Generelt Principskitse ESB Overvejelser Krav Krav til løsningen som helhed Governance Dokumentation Drift Infrastruktur SLA Fælles datastrukturer Fælles sikkerhedssystem Log & Revisionsspor Statistik og Rapporter Batchkørsler Kommunikation Fejlhåndtering DMP WebService Spec v1.3 revideret oktober 2015

3 3.2 Krav til de enkelte systemer Struktur Forretningsprocesser Primær data lokation Transaktionsstyring Projekt procedure Dokumentation Test Specifikationer General Notation Timestamps Web Service Interface Web Service Design Methodologies Communication Patterns SOAP Formatting Rules SOAP Protocol Naming Conventions Namespaces Namespace Prefixes Endpoint naming convention Target namespace naming convention Web Service Payload Design Principles XML Message Payload Structure Methods for both XML and Object Structures DMP WebService Spec v1.3 revideret oktober 2015

4 4.4.4 XML Result Message Structure Web Service Security Federation Security Implications on Web Service Development Roles for authorization Web Service Application REST support Introduction to REST The body of the request URI HTTP headers HTTP status codes Security Limits Support for REST in standard platforms Logging Log Service Logging into Windows Event Log Transactions across web services ErrorHandling Response Categories Action on Error Test Test Client Alive Method Compliance Test DMP WebService Spec v1.3 revideret oktober 2015

5 5.4 Performance Test BizTalk Server specifikations Naming Conventions Namespaces XML Message format XML Schemas BizTalk Conventions BizTalk Folder structure BizTalk Application Deployment BizTalk Orchestration BizTalk Orchestration Exeption Handling Web Services Publishing web services Consuming web services Bindings BizTalk Global Variables BizTalk Server ADFS Scenarios Scenarios Scenario A Simple Service Scenario B Service using Claims Scenario C Service using standard BizTalk Scenario D Service using BizTalk and Claims Certificates involved Appendix: Reference Documents DMP navnestandard DMP Infrastruktur DMP WebService Spec v1.3 revideret oktober 2015

6 7.3 DMP IT Arkitektur rammeværk DMP Arkitektur principper DMP Procedurer for tilkobling, deployment, versionering, governance mm DMP Fællesdatastrukturer fra sektorstandardiseringsudvalget DMP Logningsservice DMP Standard SLA skabelon Dokumentations templates Guidelines for DMP Web Service security (Globeteam) W3C, OASIS standarder Claim enabling of biztalkserver Appendix: Rules collection DMP WebService Spec v1.3 revideret oktober 2015

7 Document information Title: Documenttype Project: Web Service Specification for Danmarks Miljø Portal Specification DMP Documentfolder: Version 1.3 Revision Date 01 Oktober 2015 Coming into force: 01 Oktober 2015 Author: Contributors: Approved by: jbartold CSC Jens Jakob Nørtved Bork DMP Jens Jakob Nørtved Bork DMP Activity ID: Distribute to: DMP, CSC DMP WebService Spec v1.3 revideret oktober 2015

8 Change log Version Date Changed pages or chapters Comments Document initialized Document draft review with DMP Changed from recommendations to specifications Added several sections Document draft review with DMP Document draft review with DMP Added rule boxes Many changes Document draft review with DMP Added section on ESB and REST Added rules for Transactions, REST Query string parameters, Web Service message payload Adjustments ESB put in appendix Document draft review with DMP Document draft review with DMP Document draft review with DMP Adjustments on Test and links Document draft review with DMP Adjustments according to hearing answers and added section plus note on future compliance with namespace naming conventionfrom NDR Appendix 8 rules collection added. Link to UDDI corrected??? remove Document draft review with DMP Document draft review with DMP 0, NDR 3.2 rules applied Document released Version changed to 1.0 DMP WebService Spec v1.3 revideret oktober 2015

9 BizTalk sections added (BizTalk/ADFS TBD) NDR 4.0 rule compliance checked Text Adjustments Appendix 8 Rules collection NOT updated Appendix Rules collection updated Links updated. DMP WebService Spec v1.3 revideret oktober 2015

10 1 Generelt 1.1 Introduktion Dette dokument indeholder en specifikation af områder der relaterer sig til implementering af web services på Danmarks Miljø Portal (DMP). Der vil foruden egentlige regler som skal overholdes (markeret i rammer med teksten Regel ) tillige være vejledende tekst til hjælp med at træffe de designmæssige beslutninger om strukturen og implementeringen af de involverede forretningsservices. Et citat fra OIO: For at gøre det muligt at frembringe anvendelige systemer opbygget af webservices fra forskellige offentlige instanser og leverandører til en offentlig administration er det vigtigt, at interfacet til disse webservices implementeres på en ensartet måde. Det er såvel rettet mod de tekniske specifikationer, valg af standarder og profiler og generelt måden at implementere de enkelte systemer (via web services) på for at opnå de mulige fordele for DMP som helhed. Kapitlerne 2 og 3 beskriver de overordnede krav til løsningen mens kapitel 4 giver de mere specifikke implementeringskrav. Kapitel 5 omhandler Test. Kapitel 6 giver specifikke implementeringskrav til biztalk server installationer. Læseren forudsættes at have et rimeligt kendskab til almindelige tekniske termer og de involverede standarder. 1.2 Forkortelser og Standarder DMP WSDL XML SOAP WS * WS I http HTTPS WS Sec WS Trust WS Policy WS ReliableMessaging WS Communication WS Transaction OASIS W3C OIO OIOXML OCES Danmarks Miljø Portal Web Services Description Language Extensible Markup Language Simple Object Access Protocol Web Services Standarder Web Services Interoperability Hypertext Transfer Protocol Hypertext Transfer Protocol Secure (over SSL) Web Services Security Web Services Trust Web Services Policy Web Services ReliableMessaging Web Services Communication Web Services Transaction Organization for the Advancement of Structured Information Standards World Wide Web Consortium Offentlig Information Online XML for Offentlig Information Online Offentlige Certifikater til Elektronisk Service DMP WebService Spec v1.3 10

11 SAML OWSA model T EA RASP REST ESB BAM Security Assertion Markup Language OIO Web Service Arkitektur model (sikker direkte transport) Enterprise Architecture Reliable Asynchronous Secure Profile Representational State Transfer Enterprise Service Bus Business Activity Monitoring 2 Arkitektur 2.1 Generelt Der er i Miljøsektoren foretaget sektorstandardisering og hvilket har resulteret i en række dokumenter med standarder herunder navnedokumentet med betegnelser og navngivning for forretningsområder under Danmarks Miljøportal. Link til DMP navnestandard [7.2] Link til DMP Arkitekturdokumenter [7.4] Regel 2.1a DMP navnestandarder SKAL til enhver tid følges. Såfremt der ikke er defineret navne for det pågældende område skal DMP kontaktes for at aftale den navngivning der skal anvendes. DMP WebService Spec v1.3 11

12 2.2 Principskitse Fagsystem Web Service DMP( evt ESB) Databaser 2.3 ESB Overvejelser Centralt vil miljøet i DMP, hvor forretningsservices skal afvikles enten være med eller uden anvendelse af en ESB. I den forbindelse er der en række overvejelser om måden at konstruere forretningsservices på. Disse overvejelser er placeret i kapitel 6. 3 Krav Overordnet stilles en del krav til DMPs centrale løsning. Disse er karakteriseret ved dels at omfatte specifikke krav til de enkelte systemer dels krav som følge af mangfoldigheden af systemer der samles. 3.1 Krav til løsningen som helhed Målene er bl.a. 1. At tilvejebringe mulighed for at opdatere data, på en måde således den passer ind i brugeren hverdag(forretning). Dette kan være fra et enkelt decentralt fagsystem eller fra flere kilder. 2. At give adgang til interne data for de myndigheder, systemer og personer, der har retmæssig adgang. 3. At give adgang til data for offentligheden, myndigheder og systemer. 4. At standardisere grænseflader, data og procedurer i en grad der både gør det gennemskueligt hvorledes de enkelte systemer skal udvikles og samtidig forenkler de centrale processer. 5. At genbruge fælles services og datastrukturer 6. At muliggøre en fyldestgørende grad af governance for systemet som helhed DMP WebService Spec v1.3 12

13 Ad 1. Det er valgt at data udstilles via web services og at al tilgang til data foregår gennem web services. Ad 2. Interne data(data som ikke er kvalitetsmærket) udstilles kun gennem web services og det er omfattet af en rettighedsmodel til styring af hvem, der har ret til at skrive og læse data. Ad 3. Kvalitetsmærkede data udstilles gennemwebservices. Ad 4. Det er nødvendigt at følge de til enhver tid gældende procedurer for tilkobling, deployment, versionering, governance etc. Dette kan være håndteret i et central system fx en ESB og/eller centrale custom udviklede komponenter. Et eksempel herpå er logning hvor updates foretages i specifikke formater hvorved applikationer, der efterfølgende skal vise log data forenkles betydeligt. Ad 5. Der er et meget stort behov for at gøre arkitekturen så enkel, som muligt via genbrug af services og komponenter. Ad 6. Der vil være er række områder hvor governance bliver et vigtigt område at håndtere. Dette er drevet bl.a. af et behov for at kunne monitorere run time performance men i høj grad også af antallet af services, idet det ikke er svært at bevare overblikket over enkelte systemer, men i høj grad komplekst ved mange services. Governance håndteres centralt og vil run time være transparent for services. Det bemærkes at der kan være enkelte systemer, som i web service kaldet vil overføre referencer til data i stedet for selve data. Dette kan være nødvendigt ved meget store datamængder som således kun bliver hentet af selve applikationen, der skal bruge data uden at skulle overføre disse gennem alle interfaces. Regel 3.1a Data SKAL udstilles via web services Regel 3.1b De til enhver tid gældende procedurer for tilkobling, deployment, versionering, governance mm SKAL følges Der refereres til [7.5] Regel 3.1c Services og andet programmel SKAL være compliant med DMPs ESB hvis en sådan er implementeret Governance Governance omfatter life cycle management af services på SOA platformen. Dette gælder for for alle dele af en service livscyklus, dvs fra første release over ændringer (versioner) til terminering. Data der registreres spænder fra servicebeskrivelser og kontrakter, SLA mm til lister over systemer, der bruger de enkelte services. Der refereres til [7.5] Dokumentation For de enkelte services skal dokumentationen følge DMPs dokumentations template hvilket omfatter bl.a. DMP WebService Spec v1.3 13

14 Forretningsmæssig beskrivelser af services Forretningsobjekter Usecases Tekniske beskrivelser af services med wsdl, xml schema mm Versionering af services Primær data lokation f.eks. database Data ejer dvs hvilken myndighed, der er ansvarlig Custom Log record format med xml schema Interessenter f.eks. i form af liste over personer og institutioner Aftalegrundlag som referencer til tekniske og juridiske dokumenter Jf. iøvrigt afsnit Drift Services skal naturligvis kunne afvikles på eller i forbindelse med DMPs driftsmiljø. Driften vil være monitoreret og der vil blive opsamlet statistik til brug for rapporter og fejlfinding. Der vil blive foretaget centrale målinger for at måle belastning, finde evt. peak perioder og kunne foretage kapacitets planlægning samt følge op på SLA. Der vil tillige centralt blive anvendt sikkerhedspolicies som services skal følge samt overvåget fejl login / Intruder detection. (se afsnit 3.1.7) Følgende emner indgår bl.a. i monitoreringen af driften: Run time monitorering: response tid, antal hits, antal failures, tilgængelighed (Up time ) Log: Revisionsspor (se afsnit 4.8) Statistik: Hvem gør hvad hvornår Alle forretningsservices skal implementere en funktion, der kan anvendes til test og driftsovervågning. Funktionen skal kunne kaldes til enhver tid, som minimum for at overvåge om servicen er i live. Dette kan ske fra testprogrammer, funktionalitet i en central ESB eller automatiseret som en del af driftsovervågning. For flere detaljer se afsnit 5 Regel 3.1.3a Services og andet programmel SKAL kunne afvikles i DMPs driftsmiljø Regel 3.1.3b Alle services SKAL implementere en Test funktion Infrastruktur Services skal anvende DMP s fælles infrastruktur med mindre andet er specifikt aftalt. Dette omfatter tillige at følge de gældende standardiserede processer for implementering af softwaren, web services, policies mm. For yderligere detaljer vedrørende infrastrukturen se [7.3] DMP WebService Spec v1.3 14

15 Regel 3.1.4a Leverandøren SKAL sætte sig ind i relevante områder af DMPs Infrastruktur. Det aftales for hvert enkelt projekt med DMP, hvad der er relevant SLA Det må påregnes at der skal udarbejdes Service Level Agreements (SLA) for de enkelte systemer / myndigheder. Indholdet kan omfatte alt fra backup af databaser til tilgængelighed / fremkommelighed af services. En central tilgang er nødvendig for at opnå en del af effektiviseringsfordelene men det giver også risiko for single point of failure. Der skal være taget stilling til og implementeret den passende og relevante håndtering af redundans og failover for at kunne honorere de krav (service mål) der er stillet i SLA. Tilsvarende vil dette kunne udnyttes til load balancing. Regel 3.1.5a Der SKAL udarbejdes et SLA bilag til kontrakten. Der refereres til [7.9] Fælles datastrukturer Der er for centrale dataelementer defineret standardiserede strukturer, specielt de, der skal anvendes og udveksles på tværs af systemer. Fx koordinatbeskrivelse, adresser, generaliseret prøvestedsbeskrivelse o.l. Disse datastrukturer skal anvendes og standarder skal overholdes. Derudover kan der for sektorspecifikke elementer være defineret tilsvarende standarder. For ikke definerede områder kan det være nødvendigt for den givne service at definere yderligere datastrukturer. Det skal i så fald i hvert enkelt tilfælde først undersøges om der eksisterer centrale definitioner eller sektor (domænespecifikke) definitioner og i så fald skal de anvendes. Hvis dette ikke er tilfældet skal det undersøges om det er relevant at få datastrukturerne defineret på centralt eller sektor niveau med de procedurer, der hører til dette. Såfremt dette ikke skønnes nødvendigt fx fordi der er tale om interne definitioner for den enkelte service skal der alligevel defineres som om der var tale om strukturer på sektorniveau dvs at fx navnekonventioner og xml schema overholder fx OIOXML NDR og laves i den ånd, der er beskrevet heri og i øvrigt fremgår af andre DMP definerede xml schemaer. OIOXML NDR Fællesdatastrukturer kan findes hos sektorstandardiseringsudvalget [7.7] DMPs arkitekturprincipper kan rekvireres hos DMP. DMP WebService Spec v1.3 15

16 Regel 3.1.6a Fælles datastrukturer specificeret af sektorstandardiseringsudvalg SKAL anvendes. (Jf. Regel 2.1a) Regel 3.1.6b Relevante generiske services i DMP SKAL anvendes Regel 3.1.6c OIOXML NDR i senest gældende version BØR følges. (Link: NDR DIGST) De til enhver tid gældende services vil være udstillet via DMPs UDDI (Link: Fælles sikkerhedssystem Et fælles sikkerhedssystem er gældende for DMP og vil styre den administrative håndtering af brugere, grupper, roller og rettigheder (authorization) for de enkelte systemer, der skal bruge de udstillede services. Der er udstukket diverse Policies som skal følges se Brugerstyringsspace på Se iøvrigt afsnit 4.5. Bemærk at login proceduren (authentication) håndteres lokalt (omend nogle løsninger baserer sig på et centralt placeret system, hvorimod rettigheder (authorization) håndteres centralt. Regel 3.1.7a DMPs fælles sikkerhedssystem SKAL anvendes Regel 3.1.7b DMPs IT sikkerhedspolitik og sikkerhedspolicies SKAL følges Regel 3.1.7c DMPs fortolkning af DS484/ISO27001 SKAL overholdes Log & Revisionsspor Der er generelle krav fra DMP til niveauet af log og revisionsspor. Eksempelvis er det et krav at man til enhver tid kan følge hvem der har lavet hvilke ændringer i data (det skal aftales med DMP hvilket detaljeringsniveau for selve dataindholdet der skal gælde for en given forretningsservice). Desuden ønskes generelt at kunne se hvem der kalder hvad hvornår af hensyn til fx kapacitetsplanlægning. Dele af disse data fås fra ESB interne statistikker, udvalgte BAM målepunkter, fra Windows system Logs og fra den fælles logningsservice (revisionssporet) Hensynet til at logning generelt ikke må tage væsentlig del af performance i selve service-kaldene gør at der skal være særskilt fokus på tiltag, der understøtter dette. Dette er løst bl.a. ved at standardisere måden, der logges på (anvendelse af en fælles central logningsservice kaldet revisionspor ) og her prioritere en hurtig funktion, der ikke foretager beregninger af betydning. Standardiseringen specificerer en generisk DMP WebService Spec v1.3 16

17 sektion, der dannes centralt og en systemspecifik sektion, der dannes af den applikation, der kalder for at få den logget eller evt. af det centrale system, hvis der udvikles speciel kode for den pågældende service. Der er centralt mulighed for at specificere flere niveauer af logning for fx at styre detaljeringsgraden således at log størrelsen ikke vokser uhensigtsmæssigt meget, men også således at der i trace eller debugging øjemed kan laves mere detaljeret logning. Regel 3.1.8a DMPs fælles logningsservice SKAL anvendes. [7.8] Regel 3.1.8b Der skal som minimum logges for alle metoder: OnEntry med Input parametre mm fra web service kaldet således at det entydigt kan identificeres hvem der gør hvad OnExit med returværdier således at det kan ses om kaldet var succesfuldt eller hvilken fejl, der opstod. Regel 3.1.8c Logningskaldet i en given service (metode) OnEntry SKAL placeres som det første der bliver gjort og OnExit SKAL placeres som det sidste således at timestamps på logrecords kan anvendes præcist og retvisende Statistik og Rapporter Der vil blive udtrukket data til anvendelse for statistik og rapporteringer med faste intervaller og efter behov. Data udtrækkes fra flere kilder herunder Log (Revisionssporet) Windows logs ESB built in logs Særligt opsatte BAM målepunkter Udvalgte rapportudtræk implementeret i forretningsservices Andet Data vil blive anvendt til bl.a. drift og forretnings rapportering herunder Forretning o o Anvendelsesstatistik Afregninger DMP WebService Spec v1.3 17

18 Drift o o o o Tilgængelighedsmåling Identifikation af peak perioder Kapacitet vs Belastning Beregninger Fejl Sikkerhed o Intrusion log Batchkørsler Der kan i enkelte tilfælde være behov for batch kørsler til større udtræk eller opdateringer af data mellem systemer og databaser indbyrdes. Batch kørsler kan inddeles i to hovedgrupper med henblik på tilgangen til data: Databasen tilgås via forretningsservices (web services) Databasen tilgås direkte Valget af tilgang afhænger af det specifikkke behov herunder datamængder og hyppighed, hvormed operationen skal udføres. Ved store datamængder er der typisk performancemæssige hensyn at tage og her falder valget oftest på direkte tilgang til databasen evt. ved anvendelse af scripting og built in features i databasen. Herved undgås at skulle serialisere og evt streame store datamængder. Regel a Forretningsservices BØR være designet således at det ikke er nødvendigt at anvende batchkørsler Regel b Anvendelse og design af samtlige batchkørsler SKAL være altid forhåndsgodkendt af DMP Kommunikation Kommunikationen mellem decentrale fagapplikationer og centrale services foregår via HTTPS og eventuelt via VPN opkoblinger. DMP WebService Spec v1.3 18

19 Regel a Servicen SKAL anvende standard kommunikationsprotokoller Regel b DMP SKAL forhåndsgodkende de kommunikationsprotokoller, der planlægges at blive anvendt Fejlhåndtering For enhver services er gældende at der er en Client (Requestor) og en Web Service (Server). Client kalder en funktion (metode) hos Web Servicen og for et svar (Response) tilbage. Hvis en Client kalder Web Service via en almindelig unreliable request/response protokol som fx SOAP/HTTPS kan man underopdele de mulige udfald i 4 forskellige kategorier, som er gennemgået nedenfor Result response received Client modtager et svar fra Web Service. Client ved dermed, at operationen er udført af Web Service med success. Client ved således, at tilstandsændringer som følge af operationens kørsel hos Web Service er blevet commited Fault response received Client modtager en fejl fra Web Service. Client ved dermed, at kaldet er fejlet hos Web Service, hvilket indebærer, at tilstandsændinger som følge af operationens kørsel hos Web Service er blevet rolled back No response received Client modtager intet svar fra Web Service, men får sikkert en fejl genereret af kommunikationsframeworket i stedet. Client ved nu ikke, om kaldet nåede at blive kørt hos Web Service, og om det i så fald commitede eller resulterede i roll back. Fejlen kan fx skyldes, at kaldet aldrig nåede frem til Web Servicen, at Web Servicen crashede eller at svaret fra Web Servicen ikke nåede tilbage til Client Client has crashed Client når at lave kaldet og Client crasher så enten inden Client har modtaget svaret eller efter Client har modtaget svaret, men inden Client kunne nå at afslutte sin egen transaktion og / eller at gemme svaret. Web Servicen ved ikke noget om, at Client er crashet / vil crashe, og forsøger derfor på at udføre (commite) operationen (hvis det ikke allerede er sket). Da Client ikke ved om kaldet lykkedes, vil Client efter en genstart evt. prøve at køre kaldet endnu engang, hvilket kan medføre uønskede konsekvenser og evt. stille krav til duplikate håndtering hos Web Servicen Fejlhåndteringsaktion En given fejl vil typisk fåes i form af en SOAP fault (exception). Client kan forsøge at gentage kaldet, men efter et antal forsøg (0 n retries) må en eller flere fejlhåndteringsaktioner specifik for den pågældende forretningsservice iværksættes. Dette omfatter som minimum logning og dernæst fx at sætte kaldet i en error kø, overlade til drift at tage sig af fejlen etc. Se I øvrigt afsnit 4.10 DMP WebService Spec v1.3 19

20 3.2 Krav til de enkelte systemer Regel 3.2a DMPs arkitekturprincipper SKAL følges. Kan rekvireres hos DMP Struktur Den overordnede struktur med lokale (fag)systemer og central udstillelse af services herunder adgang til primær data er givet. Et overblik kan fås fra figuren i afsnit 2.2 Principskitse. Der vil således typisk være en decentral applikation (fagsystem) der kommunikerer med den primære database via web services. Fagsystemet håndterer data dvs. er kilde for opdateringer til databasen samt trækker på data herfra. I nogle tilfælde vil der være andre (fag)systemer, der skal læse og måske endda berige data. Også dette foregår via web services Forretningsservices. En forretningsservice er primært vendt mod eksterne modtagere borgere, private virksomheder og andre offentlige organisationer. Man kan dog godt have interne forretningsservices et direktorat der leverer services til fx departementet, eller services rettet mod den enkelte ansatte. En forretningstjeneste bør i sin yderste konsekvens forstås som en logisk størrelse, der fastlægger den totale mængde forretningsobjekter, relationer og de processer der påvirker disse. Det den udveksler med omverdenen er forretningsservices. En forretningstjeneste forvalter et eller flere forretningsobjekter. Det er helt afgørende, at tjenesten stiller sin funktionalitet til rådighed for andre. Det kan den gøre via logiske interfaces for dialog eller systemer. Det er vigtigt at forretningsservices beskrives teknologiuafhængigt. En forretningstjeneste kan implementeres på mange måder og i mange forskellige instanser. Der vil også være behov for at holde data i de forskellige implementeringer nogenlunde synkrone. Det er derfor meget nemmere at foretage udvekslinger af ensartede data, hvis de forskellige implementeringer har taget udgangspunkt i den samme forretningstjeneste. For at dokumentere hvilke foretningsservices der understøttes skal der henvises til eksisterende forretningsservices eller udarbejdes nye Forretningsprocesser Et basalt princip er anvendelsen af forretningsobjekter. Når et givet fagområde/system skal implementeres analyseres forretningsområdet for at identificere de data strukturer, interessenter, forretningsprocesser og use cases der indgår. Ud fra dette fastlægges forretningsobjekter (datastrukturer) og de funktioner, der er nødvendige for at kunne understøtte forretnings processerne. For at dokumentere og give et overblik over et givet forretningsområde skal, processer, states, aktører, swimlanes, objekter, input og output mm for beskrives i en standard notation BPMN. Funktioner vil typisk omfatte: 1. Create 2. Read 3. Update DMP WebService Spec v1.3 20

21 4. Delete 5. GetItemList 6. GetItemDetails 7. [MoreFunctions] Ved updates (hvis det er tilladt) vil der typisk blive logget en del a.h.t. revisionssporet (jf. afsnit 3.1.8). Delete er ligeledes en funktion, der ikke altid er tilladt. Det fremgår at funktionerne ikke kun er standard CRUD men netop tilføjet yderligere funktioner for at muliggøre og optimere anvendelsen af forretningsservicen. Eksemelvis vil en klient applikation med et GUI kunne have behov for at vise en liste af elementer og ved valg af et enkelt element at kunne vise yderligere DMP WebService Spec v1.3 20

22 detaljer om dette element (drill down). Dette er oftest kun svært muligt, hvis der kun er simple kald til rådighed. Derfor er der implementeret (5 og 6) sammensatte funktioner, der understøtter dette. Item kan således være et forretningsobjekt der igen kan lagres på mange måder i datalaget. Et evt. behov for transaktionshåndtering (f.eks. med roll back) stiller særlige behov. (jf. afsnit 3.2.4) Der kan være behov for speciel håndtering af applikationer med mange hits og transaktioner. Dette gælder tillige applikationer med store datamængder pga overheadet ved serialisering til xml (SOAP message payload) gennem service kaldene. I disse tilfælde anvendes i stedet referencer til data, som embedded i web service request/response xml, mens data ikke røres førend det er nødvendigt. Regel 3.2.2a Der skal henvises til eksisterende forretningservices eller udarbejdes nye. Skabelon kan rekvireres hos DMP. Regel 3.2.2b Et forretningsområde SKAL overholde krav beskrevet i den for DMP gældende version af IT Arkitektur rammeværk jf. [7.4] Regel 3.2.2c Et forretningsområde SKAL beskrives i den for DMP gældende version af BPMN(p.t. v1.2) Regel 3.2.2d En service SKAL bygges over en model med udgangspunkt i Forretningsservices og Forretningsobjekter. Regel 3.2.2e En service KAN understøtte flere forretningsobjekter. Regel 3.2.2f Det BØR altid overvejes om der er behov for at anvende reference til store data items. Regel 3.2.2g Primær data lokation Den primære data lokation er bestemt i hvert enkelt tilfælde af DMP. Det vil typisk være i form af en (eller flere) database(r), men kan også være i form af fx et fil repository. Den fysiske placering afgøres af de aktuelle hosting aftaler, men tilgangen er udelukkende via centrale web services, der udstiller data og muliggør de nødvendige forretningsprocesser. Der tænkes her ikke på tilgang for drift idet dette tillige vil omfatte andre metoder. Det er ikke væsentlig hvilken database, der anvendes så længe den på enkel vis kan bringes til at kommunikere effektivt med de web services, der udstiller data. Dog skal der naturligvis tænkes på databasens egnethed i forhold til performance på de relevante mænger af data og transaktioner. Det må imidlertid frarådes at placere for store mængder logik i stored procedures eller lignende DMP WebService Spec v1.3 22

23 embedded i databasen, med mindre det af performancemæssige grunde er nødvendigt. I stedet bør det placeres i koden, der understøtter web servicen. Det er intentionen at forretningslogikken er placeret i et forretningslag og at applikationer, der anvender web service (forretningsservicen) IKKE behøver at kende lagringsstrukturen i det underliggende data lag. Således skal der anvendes forretningsobjekter og ikke blot direkte adgang til tabeller, hvorved det fx efterlader applikationen med ansvaret for data integritet. Anvendelse af stored procedures skal således ses som en mulig del af data access laget, men ikke som et sted at placere forretningslogik. En vis sammenhæng mellem lagene vil der altid være og vurderingen er tillige påvirket af hvilket kodningssprog, man er nødt til at vælge samt hvor meget database lock in, der påføres løsningen. Såfremt det i enkelte tilfælde er nødvendigt kan databaser kopieres fx gennem et raw export kald til anvendelse for ressourcekrævende analyser. Dette må ikke ændre den entydige definition af hvor primære data er placeret for det enkelte system. Regel 3.2.3a For enhver involveret database (defineret som alle typer af data lagre) SKAL der eentydigt beskrives hvor primær data er placeret og hvem der er ansvarlige for disse data Transaktionsstyring Ved tilgang (skrivning) til flere databaser på een gang er der oftest brug for styring af data integritet. Situationen håndteres normalt ved at indkapsle opdateringerne i et Transaction Scope hvorved det muliggøres at foretage en roll back såfremt en eller flere dele af transaktionen fejler. Dette kan gøres på tværs af tabeller og databaser og har længe været fuldt integreret i udviklingsmiljøerne. Udfordringerne opstår først når man f.eks. i en løs koblet arkitektur anvender stateless services for tilgang til databaserne og således skal have transaktionen til at omfatte flere på hinanden følgende uafhængige web service kald for at opdatere i flere databaser på een gang. Der er naturligvis mange kombinationsmuligheder, men Principskitsen nedenfor illustrerer et udvalg af scenarier. Scenarie A viser en simpel transaktion uden anvendelse af særlige mekanismer I Scenarie B er anvendt WS AtomicTransaction og viser hvorledes protokol frameworket kan håndtere en transaktion hvor Client starter en transaktion (dvs specifikt angiver dette i Web Service kaldet) mod Web Service 1. Web Service 1 opdaterer sin egen Database 1 kalder under udførelsen af opgaven Web Service 2 som opdaterer en anden Database 2. Scenarie C viser hvorledes Client selv kalder to web services for at foretage opdateringerne i Database 1 og Database 2. Client hjælpes af protokol frameworkets Transaction Coordinator til at holde styr på de enkelte del transaktioner og foretage roll back hvis det er nødvendigt. Scenarie D viser den samme situation, men her har man erkendt at der er et behov for at kunne DMP WebService Spec v1.3 23

24 foretage indbyrdes afhængige opdateringer på tværs af databaser og har derfor defineret en forretningsservice, der på traditionel vis håndterer transaktionen med opdatering i Database 1 og Database 2. Dette er implementeret i een almindelig web service og baserer sig ikke på anvendelse af protokol framework for at styre sit transaction scope. Den kalder heller ikke andre web services for at løse opgaven. Det skal i hver enkel situation overvejes, hvilken tilgang til transaktionstyring på tværs af databaser, der som udgangspunkt er udstillet via web services, der skal vælges. Det kan i nogle tilfælde være et følsomt emne at afgøre hvem, der skal eje den fælles webservice, der skal implementere tilgangen til flere databaser på tværs af f.eks. myndighedsgrænser. Ovenstående gælder specielt for opdateringer af databaser, men overvejelserne om definition af en forretningsservice på tværs af databaser (fagområder) kan tillige være relevant for læsninger omend der her ikke er behov for transaktionsstyring, hvilket forsimpler situationen betydeligt. Se iøvrigt afsnit 4.9 DMP WebService Spec v1.3 24

25 Scenario A Simple Transaction Client Web Service Database Scenario B WS AtomicTransaction Web Service 1 Database 1 Client Web Service 2 Database 2 Scenario C WS AtomicTransaction + WS Coordination Transaction Coordinator Web Service 1 Database 1 Client Web Service 2 Database 2 Scenario D Coding using traditional Transaction Scope (not based on protocol framework) Web Service 1 Web Service Database 1 Client Database 2 Web Service 2 [DMP WebService Spec v1.2] 24

26 Principskitse Regel 3.2.4a Ved simple transaktioner MÅ Scenarie A benyttes Regel 3.2.4b Ved simple transaktioner med viderekald BØR Scenarie B benyttes Regel 3.2.4c Ved transaktioner med mere end én commit BØR Scenarie C eller D benyttes Projekt procedure Overordnet bør et projekt minimum have tre faser defineret: 1. Pre projekt 2. Projekt 3. Release Ad 1. Denne fase er defineret som alt før godkendelsen og igangsættelsen af et projekt. I denne fase skal krav og løsningsbeskrivelse være dokumenteret. Løsningsbeskrivelsen bør indeholde (i det mindste overordnede) definitioner af forretningsprocesser og forretningsobjekter, funktioner, primær database, web services og eventuelle specielle sikkerhedskrav. Det er ligeledes her (eller tidligere) at kontraktuelle forhold afklares) Ad 2. Denne fase indeholder udvikling, test og implementering. Der vil være en del milepæle undervejs, men dokumentationen udfærdiges typisk sidst i fasen. Ad 3. Endelig release af (del)projektet. Accepten af leverancen kan forudsætte bl.a. gennemførte testprocedurer, compliance test, dokumentation etc. Regel 3.2.5a DMPs projektmodel SKAL følges Regel 3.2.5b DMP s release proces skal følges Dokumentation Alle komponenter skal være dokumenteret til et niveau, der opfylder visse minimumskrav. 1. web services 2. sikkerhed 3. Forretningsprocesser DMP WebService Spec v1.3 26

27 4. Konceptuelle datamodeller Der er udarbejdet en dokumentationstemplate jf. [7.10] samt indeholdt i DMPs arkitektur rammeværk bygget på OIO EA metoden jf. [7.4]. Ad 1. Web Services beskrives med WSDL og message payload med XML Schema. Ad 2. sikkerhedsprofiler fx RASP Ad 3. Forretningsprocesser beskrives i tekst og med use cases. Funktioner beskrives jf. wsdl og i tekst. Forretningsobjekter beskrives i tekst med angivelse af attributter og relationer. Ad 4. Datastrukturer beskrives i konceptuelle datamodeller. I alle tilfælde skal der minimum være en kort beskrivelse af de enkelte områder for at supplere de tekniske dokumenter i et almindeligt sprog for at give et hurtigt overblik. Derudover skal fx semantikken i de enkelte funktioner mm dokumenteres, hvilket typisk ikke fremgår i tilstrækkelig grad af de øvrige dokumenter. Der kan være forskellige niveauer af dokumentation nødvendig på forskellige stadier af udviklingen. Fx design og initiel godkendelse af et projekt versus dokumentation ved release og deployment af services. Se i øvrigt dokumentations template [7.10] DMP WebService Spec v1.3 27

28 Regel 3.2.6a Den af DMP specificerede dokumentations template SKAL (som minimum) benyttes til dokumentation jf. [7.10] Regel 3.2.6b Deliverables: Enhver web services SKAL som minimum levere følgende dokumenter, filer mm: Install filer for Web Service herunder WSDL XML Schemaer for Message Payload for Requests og Responses Dokumentation af configuration filer (fx.config) Install filer for Test Client Install filer for andre komponenter Database relaterede filer herunde Scripts til create og/eller updates af databaser Stored Procedures mm ER diagrammer Dokumentation af security elementer (fx users and access rights) i database Regel 3.2.6c Alt documentation og kilde kode skal lægges i DMPS s TFS (miljoeportal.visualstudio.com) Install filer refererer til alle file, der er nødvendige for at installere den pågældende service samt delkomponenter. Dette kunne eksempelvis være MSI, JAR, install scripts til database mm. DMP WebService Spec v1.3 28

29 3.3 Test I forbindelse med udviklingen af en web service skal der udvikles en Test Client, der kan verificere funktionaliteten i servicen samt fungere til test af SLA, Security (Access Rights) mm. Regel 3.3a Der SKAL udvikles en Test Client til enhver Web Service. Regel 3.3b Test Client BØR også kunne fungere i Produktionsmiljøet 4 Specifikationer 4.1 General Der tages udgangspunkt i den af MVTU definerede OIO standard for interoperabilitet af web services (OWSA T). Uddrag af OWSA T fra OIO: Byggestene i OWSA model T er etablerede komponenter, der har vist sig reelt interoperable i praksis og som sikrer ens implementeringer. Overordnet set er OWSA model T en tilpasning til danske forhold af WS I s Basic Profile 1.1 og simple SOAP Binding Profile 1.0 udvidet med krav om brug af OCES, OIOXML og HTTPS. Et basalt begreb i design og udviklingsprocessen er kontrakt først princippet. Det betyder at der efter analyse, kravspecifikationer, definering af forretningsprocesser, forretningsobjekter mm udarbejdes wsdl filer til beskrivelse af web services samt xml schema til beskrivelse af message payload. Generelt baseres løsningerne på eksisterende standarder fra bl.a. OASIS og W3C, idet disse i vidt omfang er implementeret i de relevante framework (Microsoft.Net og diverse Java Libraries) For ikke at forvirre begreberne er selve specifikationerne i vid udstrækning holdt på engelsk da dette er det officielle standardiserings sprog anvendt i langt de fleste standardorganisationer Notation In this document (especially in the sections on Architecture and Specifications the terms "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" should be interpreted as described in RFC Generally the notation conventions from the XML Infoset are used e.g. abstract properties are placed in square brackets [some property]. Xpath notation is used like [namespace]:level/sublevel/element and {any} describes any element. Endpoints are described using URI notation. DMP WebService Spec v1.3 29

30 CamelCase and the object approach are used for the names, variables attributes etc. Regel 4.1.1a Notation specification in this section MUST be used Timestamps All timestamps must use the UTC (Z) timezone. They must be stored using the standard database type or using the ISO 8601 format e.g. in all xml representations. DateTime, Date and Time may be converted into local time when displayed in or input from user interfaces but must always be stored in UTC. a sample datetime: <dmp:timestamp> t23:56:00</dmp:timestamp> refer to datetime for details. Regel 4.1.2a Timestamps MUST always be stored in UTC Regel 4.1.2b Timestamps MUST use the ISO 8601 representation Regel 4.1.2b applies e.g. to ALL cases where a Timestamp, Date or datetime is included in an XML instance document. 4.2 Web Service Interface Web Service Design Methodologies This following section will explain in detail the different Web Service Design Methodologies as defined by the Web Services Standardization Groups, clarify the terms, and highlight their differences. Here the focus will be on the following Web Services Design Approaches, evaluate their strength and weaknesses and explore how far each style supports in designing an Interoperable Web Service. 1. RPC/Encoded Style 2. RPC/Literal Style 3. Document/Encoded 4. Document/Literal Style 5. Document/Literal wrapped The styles RPC/Literal and Document/Encoded are not commonly used and will not be discussed further in this document DMP WebService Spec v1.3 30

31 4.2.2 Communication Patterns With reference to Web Services, three are three different ways of communication. Remote procedure call: Client sends a SOAP request to the service and waits for a SOAP response (synchronous communication). Messaging: Client sends a SOAP request and expects no SOAP response back (one way communication). Asynchronous callback: A client calls the service with one of the above methods. Later, the two parties switch roles for a callback call. This pattern can be build from either of the first two SOAP Formatting Rules The SOAP Message (essentially the message <soap:body> Element) of a Web Services can be formatted based on the following formatting rules. The first formatting rule is about the different binding styles. The WSDL 1.1 specification distinguishes two different binding styles (referred to as soap:binding styles): RPC and Document. RPC Style The RPC style specifies that the <soap:body> contains an element with the name of the web method being invoked (wrapper element). This element in turn contains an entry for each parameter and the return value of this method. Document Style If the style is of type document, there is no wrapper element as with the RPC style. Instead, the message parts appear directly under the <soap:body> element. There are no SOAP formatting rules for what the <soap:body> contains; it contains what the sender and receiver agreed upon as an XML document. The second formatting rule is the Use attribute. This concerns how types are represented in SOAP messages. It indicates whether the message parts are encoded using some encoding rules, or whether the parts define the concrete schema of the message. There are two permitted choices for Use attribute. Encoding If use is encoded, then each message part references an abstract type using the type attribute. The message is produced using an encoding specified by the encodingstyle attribute. The mostly used SOAP Encoding is a set of serialization rules defined in SOAP 1.1. The rules specify how objects, structures, arrays and object graphs should be serialized. In general, the applications using SOAP encoding is focused on remote procedure calls and will likely use RPC message style. Literal If use is Literal, then each part references a concrete schema definition using either the element or type attribute, i.e., data is serialized according to a given schema. In practice, this schema is usually expressed using W3C XML Schema specification. An important realization is that, three are three independent decisions to be made by a web services developer. DMP WebService Spec v1.3 31

32 1. What is the Communication Pattern to be used? 2. What is the SOAP formatting Style to be used? 3. What is the SOAP message encoding Type to be used? The following table summarizes the options for different web services parameters. WSDL Parameters Communication Patterns Style Use Available Options Remote Procedure Call or One way messaging Document or RPC Encoded or Literal Theoretically any combination of these options is possible, but in practice there is a clear preference of one combination over the other, and also the standards and the Web Services Interoperability organization (WS I) has a clear preference. In practice, only Document/Literal and RPC/Encoded combinations have got vide acceptance RPC/Encoded Style: RPC/Encoded is essentially a format following the classical remote procedures call style in which a client sends a synchronous request to a server to execute an operation. The SOAP request contains the name of method to be executed and the parameter it takes. The server running the Web Service converts this request to appropriate objects, executes the operation and sends the response back to the client as SOAP message. At the client side, this response is used to form appropriate objects and return the required information to the client. In RPC style Web Services, the complete method is specified in the WSDL file and in the SOAP body, including the sent parameters and the return values. So this style has a rather tight coupling with the service interface. <wsdl:binding name="dmpmessageuploadservicesoap" type="tns:dmpmessageuploadservicesoap"> <soap:binding style="rpc" transport=" <wsdl:operation name="uploaddmpmessage"> <soap:operation soapaction=" ploaddmpmessage" style="document" /> <wsdl:input> <soap:body use="encoded" encodingstyle=" </wsdl:input> <wsdl:output> <soap:body use="encoded" encodingstyle=" </wsdl:output> </wsdl:operation> </wsdl:binding> DMP WebService Spec v1.3 30

33 In the above example the binding style is set to rpc, and use is set to encoded. In RPC/Encoded style the <message> section can contain any number of <part> elements each containing a type attribute which is unique to rpc style. The RPC/Encoded style has the following advantages and disadvantages. Advantages: The definition of the WSDL file follows the intuitive and well known remote procedure call style. The operation name appears in the message, so that the receiver has an easy time dispatching the message to its implementation. The RPC/Encoded style allows polymorphic features in the service implementation. Disadvantages: The SOAP message includes the type encoding information such as xsi:type="xsd:int", xsi:type="xsd:string", xsi:type="xsd:double" which is an overhead. In general it is very hard to validate the SOAP message in this style. RPC/Encoded style causes a rather tight coupling between service provider and client, any changes to the interface would break the contract between the service and the client. Depending on the information that may need to handle simultaneously, memory constraints may make RPC messaging unfeasible as marshalling takes place in memory. It is not supported by the Web Services Interoperability Organization as a conformance standard Document/Literal The major difference of the Document style to the above RPC style is that, the client sends the service parameters in a normal XML document to the server instead of a discrete set of parameter values of methods. This makes the Document style to a more loosely coupled style of interaction than the RPC format. The Web Service provider processes the normal XML document, executes the operation and sends the response to the client again as a normal XML document. There is no direct mapping between the server objects (parameters, method calls etc) and the values in XML documents. The application is responsible for mapping the XML data values. The SOAP message of a Document style carries one or more XML documents within its SOAP body. The protocol places no constraint on how the document needs to be structured; this is completely handled at the application level. Additionally, Document style Web Services follows the asynchronous processing paradigm. WSDL for Document/Literal style <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions xmlns:soap=" xmlns:tm=" xmlns:soapenc=" xmlns:mime=" xmlns:tns=" xmlns:s=" DMP WebService Spec v1.3 31

34 xmlns:soap12=" xmlns:http=" targetnamespace=" /01/" xmlns:wsdl=" <wsdl:types> <s:schema elementformdefault="qualified" targetnamespace=" /01/"> <s:element name="messagexml" type="s:string" /> <s:element name="uploaddmpmessageresult" type="s:string" /> </s:schema> </wsdl:types> <wsdl:message name="uploaddmpmessagesoapin"> <wsdl:part name="messagexml" element="tns:messagexml" /> </wsdl:message> <wsdl:message name="uploaddmpmessagesoapout"> <wsdl:part name="uploaddmpmessageresult" element="tns:uploaddmpmessageresult" /> </wsdl:message> <wsdl:porttype name="dmpmessageuploadservicesoap"> <wsdl:operation name="uploaddmpmessage"> <wsdl:input message="tns:uploaddmpmessagesoapin" /> <wsdl:output message="tns:uploaddmpmessagesoapout" /> </wsdl:operation> </wsdl:porttype> <wsdl:binding name="dmpmessageuploadservicesoap" type="tns:dmpmessageuploadservicesoap"> <soap:binding transport=" /> <wsdl:operation name="uploaddmpmessage"> <soap:operation soapaction=" ploaddmpmessage" style="document" /> <wsdl:input> <soap:body use="literal" /> </wsdl:input> <wsdl:output> <soap:body use="literal" /> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:binding name="dmpmessageuploadservicesoap12" type="tns:dmpmessageuploadservicesoap"> <soap12:binding transport=" /> <wsdl:operation name="uploaddmpmessage"> <soap12:operation soapaction=" ploaddmpmessage" style="document" /> <wsdl:input> <soap12:body use="literal" /> </wsdl:input> DMP WebService Spec v1.3 32