Specifikation af Web Services til Danmarks Miljø Portal

Transkript

1 Specifikation af Web Services til Danmarks Miljø Portal

2 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 Krav til de enkelte systemer Struktur Forretningsprocesser [DMP WebService Spec v1.2] 2

3 3.2.3 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 XML Result Message Structure Web Service Security Federation [DMP WebService Spec v1.2] 3

4 4.5.2 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 Performance Test BizTalk Server specifikations Naming Conventions [DMP WebService Spec v1.2] 4

5 6.1.1 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 wiki DMP navnestandard DMP Infrastruktur DMP IT Arkitektur rammeværk DMP Procedurer for tilkobling, deployment, versionering, governance mm [DMP WebService Spec v1.2] 5

6 7.6 DMP Rollebeskrivelser DMP Fællesdatastrukturer fra sektorstandardiseringsudvalget DMP Logningsservice DMP Standard SLA skabelon Dokumentations template Guidelines for DMP Web Service security (Globeteam) W3C, OASIS standarder Claim enabling of biztalkserver. Fås ved henvendelse til DMP Appendix: Rules collection [DMP WebService Spec v1.2] 6

7 Document information Title: Documenttype Project: Web Service Specification for Danmarks Miljø Portal Specification DMP Documentfolder: Version 1.2 Revision Date 9. maj 2011 Coming into force: Author: Contributors: Approved by: TBD jbartold CSC Jens Jakob Nørtved Bork DMP Jens Jakob Nørtved Bork DMP Activity ID: Distribute to: DMP, CSC [DMP WebService Spec v1.2] 7

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.2] 8

9 BizTalk sections added (BizTalk/ADFS TBD) NDR 4.0 rule compliance checked Text Adjustments Appendix 8 Rules collection NOT updated Apendix Rules collection updated [DMP WebService Spec v1.2] 9

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.2] 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 herinder 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.2] 11

12 2.2 Principskitse Fagsystem Web Service DMP( evt ESB) Databaser Log 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 data for de myndigheder, systemer og personer, der har retmæssig adgang. 3. 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. 4. At genbruge fælles services og datastrukturer [DMP WebService Spec v1.2] 12

13 5. At muliggøre en fyldestgørende grad af governance for systemet som helhed Ad 1. Det er valgt at data udstilles via web services og at al tilgang til data foregår gennem web services. Ad 2. Data 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. 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 4. Der er et meget stort behov for at gøre arkitekturen så enkel, som muligt via genbrug af services og komponenter. Ad 5. 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.2] 13

14 Forretningsmæssig beskrivelser af services Forretningsobjekter 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 den 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.2] 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 jf. Fællesdatastrukturer kan findes hos sektorstandardiseringsudvalget [7.7] DMPs arkitekturprincipper kan findes i arkitektur+forside [DMP WebService Spec v1.2] 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: 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 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.2] 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.2] 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 forhåndsgodkendt af DMP Kommunikation Kommunikationen mellem de centrale fagapplikationer og centrale services foregår via HTTPS og eventuelt via VPN opkoblinger. [DMP WebService Spec v1.2] 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.2] 19

20 3.2 Krav til de enkelte systemer Regel 3.2a DMPs arkitekturprincipper SKAL følges. Der refereres til 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 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 og forretningsprocesser (evt med 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 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.2] 20

21 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 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.2b Et forretningsområde SKAL beskrives i den for DMP gældende version af BPMN(p.t. v1.2) Regel 3.2.2c En service SKAL bygges over en model med udgangspunkt i Forretningsservices og Forretningsobjekter. Regel 3.2.2d Det BØR altid overvejes om der er behov for at anvende reference til store data items. Regel 3.2.2e Udstillelse af data via en raw tilgang SKAL i hvert enkelt tilfælde godkendes af DMP 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 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 [DMP WebService Spec v1.2] 21

22 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 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. [DMP WebService Spec v1.2] 22

23 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.2] 23

24 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

25 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 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.2] 25

26 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 evt med use cases. Funktioner beskrives jf. wsdl og i tekst. Forretningsobjekter beskrives i tekst med angivelse af attributter og relationer. 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] 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 databasen 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.2] 26

27 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 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.2] 27

28 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.2] 28

29 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.2] 29

30 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.2] 30

31 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.2] 31

32 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.2] 32

33 <wsdl:output> <soap12:body use="literal" /> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="dmpmessageuploadservice"> <wsdl:port name="dmpmessageuploadservicesoap" binding="tns:dmpmessageuploadservicesoap"> <soap:address location=" SMX" /> </wsdl:port> <wsdl:port name="dmpmessageuploadservicesoap12" binding="tns:dmpmessageuploadservicesoap12"> <soap12:address location=" SMX" /> </wsdl:port> </wsdl:service> </wsdl:definitions> Note that, the binding style is set to document and use to literal. Under the message section only a single <wsdl:part> element is possible as against multiple elements in RPC style. The <wsdl:part> element points to a schema element declaration, which describes the entire contents of the soap body. The primary feature of Document/Literal style, and its key benefit compared to RPC/Literal is that it uses of schema element declaration to completely describe the contents of the<soap:body>. So it is possible to understand the message body infoset, just by looking at the schema definition of the <wsdl:part> element under the message element. The schema describing a Document/Literal message can also be used to validate the message, which is not possible with RPC/Literal. The HTTP requests in SOAP 1.1 and SOAP 1.2 versions for the Document/Literal style are shown in the following listings. SOAP 1.1 Request Format POST /DMPMessage/WcfSampleService/DMPMessageUploadService.ASMX HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: " sage" <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <messagexml xmlns=" ng</messagexml> </soap:body> </soap:envelope> [DMP WebService Spec v1.2] 33

34 SOAP 1.2 Request Format POST /DMPMessage/WcfSampleService/DMPMessageUploadService.ASMX HTTP/1.1 Host: localhost Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <messagexml xmlns=" ng</messagexml> </soap12:body> </soap12:envelope> The following are the advantages and disadvantages of the Document/Literal style approach. Advantages: No type encoding information in the SOAP Message. The messages can always be validated with any XML validation applications. Everything within the soap body is defined in the schema. With document style, the rules are less rigid and many enhancements and changes can be made to the XML schema without breaking the interface. Document style services can maintain application state if multiple procedures are called in a particular sequence. Document style is better suited for asynchronous process communication. Disadvantages: The WSDL is getting a bit more complicated. The operation name in the SOAP message is lost. In the sample WSDL, please note that the method name UploadDMPMessage is missing in the definition of <wsdl:types> and in place of it, we have only the parameter name messagexml. We can also observe the same difference in the sample HTTP requests for SOAP version 1.1 and 1.2, where we have the <messagexml> element directly placed below the </soap:body> element. The Document/Literal style eliminates most of the drawbacks from the RPC/Literal style. Hence the Document/Literal style is more widely accepted as an industry standard, but it has the disadvantages as explained above which are rectified in the Document/Literal wrapped style explained in the next section Document/Literal wrapped This style has been suggested by Microsoft to fix the drawback from the standard Document/Literal style. Although there is no specification in WSDL 1.1 standard for this style, many current SOAP toolkits support this style. [DMP WebService Spec v1.2] 34

35 This method has all the strengths from the Document/Literal style and in addition to that it has solution for the missing web method name. The web method name can be seen in both WSDL Xml and SOAP requests as shown below in the listings. WSDL for Document/Literal wrapped style <?xml version="1.0" encoding="utf-8"?> <wsdl:definitions xmlns:soap=" xmlns:tm=" xmlns:soapenc=" xmlns:mime=" xmlns:tns=" xmlns:s=" xmlns:soap12=" xmlns:http=" targetnamespace=" /01/" xmlns:wsdl=" <wsdl:types> <s:schema elementformdefault="qualified" targetnamespace=" /01/"> <s:element name="uploaddmpmessage"> <s:complextype> <s:sequence> <s:element minoccurs="0" maxoccurs="1" name="messagexml" type="s:string" /> </s:sequence> </s:complextype> </s:element> <s:element name="uploaddmpmessageresponse"> <s:complextype> <s:sequence> <s:element minoccurs="0" maxoccurs="1" name="uploaddmpmessageresult" type="s:string" /> </s:sequence> </s:complextype> </s:element> </s:schema> </wsdl:types> <wsdl:message name="uploaddmpmessagesoapin"> <wsdl:part name="parameters" element="tns:uploaddmpmessage" /> </wsdl:message> <wsdl:message name="uploaddmpmessagesoapout"> <wsdl:part name="parameters" element="tns:uploaddmpmessageresponse" /> </wsdl:message> <wsdl:porttype name="dmpmessageuploadservicesoap"> <wsdl:operation name="uploaddmpmessage"> <wsdl:input message="tns:uploaddmpmessagesoapin" /> [DMP WebService Spec v1.2] 35

36 <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> <wsdl:output> <soap12:body use="literal" /> </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:service name="dmpmessageuploadservice"> <wsdl:port name="dmpmessageuploadservicesoap" binding="tns:dmpmessageuploadservicesoap"> <soap:address location=" SMX" /> </wsdl:port> <wsdl:port name="dmpmessageuploadservicesoap12" binding="tns:dmpmessageuploadservicesoap12"> <soap12:address location=" SMX" /> </wsdl:port> </wsdl:service> </wsdl:definitions> SOAP 1.1 Request Format POST /DMPMessage/WcfSampleService/DMPMessageUploadService.ASMX HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length [DMP WebService Spec v1.2] 36

37 SOAPAction: " sage" <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <UploadDMPMessage xmlns=" <messagexml>string</messagexml> </UploadDMPMessage> </soap:body> </soap:envelope> SOAP 1.2 Request Format POST /DMPMessage/WcfSampleService/DMPMessageUploadService.ASMX HTTP/1.1 Host: localhost Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <UploadDMPMessage xmlns=" <messagexml>string</messagexml> </UploadDMPMessage> </soap12:body> </soap12:envelope> Advantages: Contains all the strengths from Document/Literal style. The web method name appears in the SOAP message. Disadvantages: The WSDL is even more complicated, but this is still a very minor weakness. If there are overloaded operations in the web service, then this style cannot be used Recommendations It can be clearly concluded from the above discussions that the Document/Literal [Wrapped] style outweighs over the RPC/Encoded style. Using RPC/Encoded style is highly discouraged in view of the web services interoperability standards. Even though not specified in WSDL 1.1 specification, the Document/Literal wrapped style is widely accepted as industry standard and supported by all major players such as Microsoft, IBM etc. The only [DMP WebService Spec v1.2] 37

38 problem with Document/Literal wrapped style is that, it does not support overloading of web methods in web services even though WSDL specification supports method overloading. Hence Document/Literal wrapped style SHOULD be used unless there is need for overloading of web methods. In the cases where overloading of web methods is required, the Document/Literal SHOULD be used. Regel 4.2.3a Document/Literal wrapped style SHOULD be used unless there is need for overloading of web methods. When overloading of web methods is required, the Document/Literal MUST be used. Regel 4.2.3b DMP MUST approve of the selected method SOAP Protocol Simple Object Access Protocol (SOAP) is a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment. It uses XML technologies to define an extensible messaging framework providing a message construct that can be exchanged over a variety of underlying protocols. The framework has been designed to be independent of any particular programming model and other implementation specific semantics. Two major design goals for SOAP are simplicity and extensibility. SOAP attempts to meet these goals by omitting, from the messaging framework, features that are often found in distributed systems. Such features include but are not limited to "reliability", "security", "correlation", "routing", and Message Exchange Patterns" (MEPs). The technological foundation that makes up Web services includes SOAP, the Web Service Description Language (WSDL), Universal Description, Discovery, and Integration (UDDI), and XML. Specifically, SOAP provides a heterogeneous mechanism to allow the invocation and communication between Web services. There are two versions of SOAP protocol: SOAP Version 1.1, SOAP Version 1.2. Some of the shortcomings of the SOAP 1.1 has been clarified, updated and corrected in SOAP 1.2. SOAP 1.2 contains answers to number of issues such as those on interoperability and ambiguities that resulted in differences of interpretation. SOAP 1.1 is based on XML 1.0 and can only use HTTP POST headers to transmit SOAP messages and as a result, it isn't really suitable for wide scale applications. SOAP 1.2 adds support for the use of HTTP GET in the SOAP HTTP binding. The semantics of HTTP GET are respected such that the action performed by SOAP endpoint responding to a request transmitted via HTTP GET should be both safe and idempotent. SOAP 1.2 provides a tighter, more robust set of specifications based on an abstract model for binding protocols and XML serialization schemes. SOAP 1.2 also has been tested by a wide variety of participants, including IBM, Microsoft, Sun Microsystems, BEA systems, and the Apache Software Foundation. It has undergone many reviews and drafts and has seen a tremendous amount of public feedback. The W3C tested the interoperability of the specifications by successfully implementing several projects. [DMP WebService Spec v1.2] 38

39 Important information such as namespace URI and reference to the specifications of SOAP 1.1 and 1.2 are listed in the following table. Version SOAP 1.1 SOAP 1.2 Namespace Details: Details Namespace URI: Envelope Namespace URI: Encoding Namespace URI: References Specification: SOAP / Namespace Details: Namespace URI: Envelope Namespace URI: envelope/ Encoding Namespace URI: encoding References SOAP Version 1.2 Part 0: Primer: part0/ SOAP Version 1.2 Part 1: Messaging Framework: part1/ SOAP Version 1.2 Part 2: Adjuncts: part2/ The following are the sample formats for Request and Response for SOAP version 1.1 and 1.2. SOAP 1.1 Request Format POST /DPMMessage/WcfSampleService/DMPMessageUploadService.asmx HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: " sage" <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <UploadDMPMessage xmlns=" <messagexml>string</messagexml> </UploadDMPMessage> </soap:body> </soap:envelope> SOAP 1.1 Response Format HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" [DMP WebService Spec v1.2] 39

40 xmlns:soap=" <soap:body> <UploadDMPMessageResponse xmlns=" <UploadDMPMessageResult>string</UploadDMPMessageResult> </UploadDMPMessageResponse> </soap:body> </soap:envelope> SOAP 1.2 Request Format POST /DPMMessage/WcfSampleService/DMPMessageUploadService.asmx HTTP/1.1 Host: localhost Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <UploadDMPMessage xmlns=" <messagexml>string</messagexml> </UploadDMPMessage> </soap12:body> </soap12:envelope> SOAP 1.2 Response Format HTTP/ OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <UploadDMPMessageResponse xmlns=" <UploadDMPMessageResult>string</UploadDMPMessageResult> </UploadDMPMessageResponse> </soap12:body> </soap12:envelope> Comparison between SOAP 1.1 and SOAP SOAP 1.1 is based on XML 1.0; SOAP 1.2 is based on XML Infoset. 2. In SOAP 1.2 the specification of a binding is left to an underlying protocol to specify the XML serialization used in the underlying protocol data units. 3. The HTTP binding specified in SOAP 1.2 uses XML 1.0 as the serialization format of the SOAP message Information set. 4. SOAP 1.1 allows additional elements to follow the SOAP Body element, but SOAP 1.2 disallows these. [DMP WebService Spec v1.2] 40

41 5. SOAP 1.1 has the actor attribute. In SOAP 1.2 this attribute is renamed to role. The semantics of the attribute are unchanged. 6. SOAP 1.2 adds two new predefined roles to the existing "Next" role in SOAP 1.1: o "None" for header blocks that should never be directly processed. o "Ultimate Receiver" for header blocks that should only be processed by nodes acting as the ultimate receiver of a message. 7. Support for HTTP GET Carrying of a SOAP 1.1 message was discussed using only HTTP POST. SOAP 1.2 adds support for the use of HTTP GET in the SOAP HTTP binding. The semantics of HTTP GET are respected such that the action performed by SOAP endpoint responding to a request transmitted via HTTP GET should be both safe and idempotent Rules for SOAP 1.1 and SOAP 1.2 version interactions The rules for dealing with the possible SOAP/1.1 and SOAP Version 1.2 interactions are as follows, 1. When a SOAP 1.2 message reaches a SOAP 1.1 node it will generate a SOAP fault containing a version mismatch. 2. When a SOAP 1.2 node receives a SOAP 1.1 message it can do one of the two things as stated below: a. The node may process the SOAP 1.1 message. b. It generates a Fault containing a Version Mismatch SOAP support in.net and Java Environments SOAP version 1.2 has supported in Microsoft.Net framework version 2.0 onwards. Similarly on the Java environment, Apache Axis2/Java supports SOAP version 1.2. In general it is good practice to support both versions of SOAP protocol while developing the web services. Latest versions of all major development environments on Microsoft and Java worlds, such as Visual Studio and Eclipse support both version of SOAP protocol. When web services are developed using these environments, by default they add supporting bindings for both versions of SOAP protocol, as shown in the following example. Bindings for both versions of SOAP <wsdl:binding name="dmpmessageuploadservicesoap" type="tns:dmpmessageuploadservicesoap"> <soap:binding style="document" 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" /> [DMP WebService Spec v1.2] 41

42 </wsdl:output> </wsdl:operation> </wsdl:binding> <wsdl:binding name="dmpmessageuploadservicesoap12" type="tns:dmpmessageuploadservicesoap"> <soap12:binding style="document" transport=" /> <wsdl:operation name="uploaddmpmessage"> <soap12:operation soapaction=" miljoeportal.dk/xml/service/namespace/2009/03/01/uploaddmpmessage" style="document" /> <wsdl:input> <soap12:body use="literal" /> </wsdl:input> <wsdl:output> <soap12:body use="literal" /> </wsdl:output> </wsdl:operation> </wsdl:binding> Regel 4.2.4a SOAP 1.2 MUST be used. 4.3 Naming Conventions Namespaces Namespace URIs represents an string dependent on an application or context as defined in RFC 2396 [URI]. XML namespace URIs which must be used in implementations complying with this specification are the following: wssecurity-secext-1.0.xsd wssecurity-utility-1.0.xsd This specification is intended to work with the general SOAP [SOAP11, SOAP12] message. As per the OIOXML standards [NDR 3.0] the schemas for elements, attributes and types MUST use a namespace that represents a valid URL in the Info Structure Database and MUST have the following structure: [NDR 3 rule: NMS 2] "urn:oio: <organisation> :" <forretningsområde> ":" <version>. The basic idea behind the namespace naming strategy is that the namespaces should comply with the following requirements. Regel 4.3.1a The namespace MUST be uniquely identifiable It SHOULD contain version information as part of namespace, by using numbers x.x.x (1.0.0) [DMP WebService Spec v1.2] 42

43 The following are some of the valid examples for namespace definitions as per OIOXML rules. urn:oio:miljoeportal:nature:1.0.0 urn:oio:miljoeportal:soilcontamination.samples:1.0.0 urn:oio:miljoeportal:surfacewater.test: Namespace Prefixes As the OIOXML NDR 3.2 rule: NMS-2 describes, a namespace prefix MUST be based on the internet domain name in the corresponding namespace without the ending period (.) and root domain (e.g. without ".dk"). Even though the scope of the namespace prefixes is limited to the document where they are defined, the relation between prefix and namespace provides readability in the Xml documents. Using a single namespace prefix for a particular namespace across multiple documents will improve readability associating all the elements of that namespace to a particular namespace prefix. It is better to choose relatively short domain names, so that it is easy to remember and if there is a very long domain name, then an abbreviation must be used. It should be noted that namespace prefixes should not begin with character sequence xml, as xml character sequence is reserved by the Xml standards. If more than one namespace belonging to same internet domain are used, then namespace prefixes MUST be chosen in such a way that they distinguishes from each other representing a particular namespace at any time. For example if you need to use two versions of a namespace such as (using namespace convention from previous NDR) and then the suitable namespace prefixes could be similar to miljoeportal1/miljoeportal2 or miljoeportal0201/miljoportal0301. Regel 4.3.2a Namespace prefixes MUST follow OIOXML NDR 3.2 rule NMS Endpoint naming convention The Endpoint has a naming convention defined in the string below: Regel 4.3.3a Endpoint naming MUST follow the format area].[sub area].[version]/[name of Service] where [DMP WebService Spec v1.2] 43

44 The interface name is described using miljoeportal mandatory is fixed [main area] mandatory is the defined from the list maintained by DMP [sub area] optional is defined from the list maintained by DMP [version] mandatory describes the version in the format and the services on that interface are described using [Name Of Service] mandatory some preferably self explanatory name The [version] in the Interface name is used to enable several versions of the same service (interface) co exit on the same machine in order to be backward compatible until the old services are phased out and removed. Ex: Target namespace naming convention All the web services should be defined with a predefined target namespace and the same guidelines explained in the section Namespaces should be followed. The following convention should be used in finalizing the target namespace for the web services. Regel 4.3.4a Namespace naming MUST follow the format "urn:oio:" <organisation> ":" <business area>. [lower businessarea]> ":" <version>. only small letters(a z), : and numbers can be used in the value for <organisation> and <business area> For example the following namespace definition is perfectly valid for using as target namespace. urn:oio:miljoeportal:nature.samples: Web Service Payload Design Principles Regel 4.4.1a The contract first approach MUST be used Regel 4.4.1b The stable interface approach SHOULD be used [DMP WebService Spec v1.2] 44

45 Contract first Note that the web services are defined in a contract first approach as described and recommended by OIO. The first step in the design process breaking down the business area into services and business objects to deliver for the clients to perform their tasks. It is not sufficient to e.g. just expose the database tables (views) and then let the clients themselves figure out how to use them (although some methods on the service may as a supplement support this rather raw approach for performance reasons). The structure of the Message Payload is formalized and constitutes the contract between Client (requestor) and Service (server). XML Schema(s) are used to specify the XML Message Payload Stable interface There are several considerations to make when designing the structure of the Message Payloads. The Request Message Payload contains the data, metadata and control parameters being transferred from the Client to the Server in the Request and The Response Message Payload contains data, metadata and result of the operation and is transferred from the Server to the Client in the Response. Both of these may contain various type of data embedded in the xml as well as containing single or multiple entities. Some data may have to be encoded e.g. using base64. This could be attached files or even whole stand alone xml structures (files) that otherwise would conflict with xml declarations, namespaces etc. The XML Message Payload having and overall xml structure with embedded (sometimes encoded) section compared to having everything unpacked Advantages: Is not affected by changes in the xml structures that are encoded Less versioning giving a stable interface for the service and all the clients using the service Less parser problems at the interface level No stripping and transformation to carry xml files within the message payload xml Disadvantages: Embedded data will have to decoded before validations of these section can be made The stable interface approach is less suitable for services with small simple requests and responses and more suitable for services with more data and of varying types. The approach is a must if whole xml files should be sent across since you otherwise would have to strip (and re insert) various xml elements from the file before it can be inserted as (inner) xml in the overall Message Payload xml XML Message Payload Structure After defining the business objects the Message Payload XML must be defined. The general structure of the Message Payload should use a header containing the Meta information and a content section where the actual content can be placed. The data definition of the Message Payload should [DMP WebService Spec v1.2] 45

46 be defined using XML schema specification conforming to OIOXML design and naming rules listed in the above table. Entities with more elements are named Structure Entities with several identical elements are named Collections. Use Collections to handle both single and multiple (bulk) data elements for both request/response (i.e. use a ComplexType with minoccurs= 0 or 1 and maxoccurs= unbounded ) In order to define Message Payload XML, the OIOXML Naming and Design Rules 3.0 MUST be followed. See section 0 for the most important rules. The sample schema for Message Payload Xml conforming to OIOXML NDR Rules listed in the above table is shown in the following listing. DMP_Message.xsd <?xml version="1.0" encoding="utf-8"?> <!-- XML Schema for the DMP message payload written by jbartold T16:00:00--> <schema xmlns:dmp=" attributeformdefault="unqualified" elementformdefault="qualified" targetnamespace=" version="1.0" xmlns=" <element name="message" type="dmp:messagetype" /> <complextype name="messagetype"> <annotation> <documentation>the xml message structure common for all services under DMP</documentation> </annotation> <sequence> <element minoccurs="1" maxoccurs="1" name="messageheader" type="dmp:messageheadertype" /> <element minoccurs="0" maxoccurs="1" name="messagebody" type="dmp:messagebodytype" /> </sequence> </complextype> <complextype name="messageheadertype"> <annotation> <documentation>the xml message header common for all services under DMP</documentation> </annotation> <sequence> <element minoccurs="1" maxoccurs="1" [DMP WebService Spec v1.2] 46

47 name="sectorname" type="dmp:sectornametype"/> <element minoccurs="1" maxoccurs="1" name="unitname" type="dmp:unitnametype"/> <element minoccurs="1" maxoccurs="1" name="servicename" type="dmp:servicenametype"/> <element minoccurs="0" maxoccurs="1" name="messagetype" type="dmp:messagetypetype"/> </sequence> </complextype> <complextype name="messagebodytype"> <annotation> <documentation>the xml message body specific for each service under DMP</documentation> </annotation> <sequence> <any minoccurs="1" processcontents="skip" maxoccurs="unbounded"/> </sequence> </complextype> <simpletype name="sectornametype"> <annotation> <documentation>the name of the DMP sector responsible for the service</documentation> </annotation> <restriction base="string"></restriction> </simpletype> <simpletype name="unitnametype"> <annotation> <documentation>the name of the DMP unit responsible for the service</documentation> </annotation> <restriction base="string"></restriction> </simpletype> <simpletype name="servicenametype"> <annotation> <documentation>the name of the service</documentation> </annotation> <restriction base="string"></restriction> </simpletype> <simpletype name="messagetypetype"> <annotation> <documentation>the name of the DMP Message</documentation> </annotation> <restriction base="string"></restriction> </simpletype> [DMP WebService Spec v1.2] 47

48 </schema> The following listing shows a sample payload xml conforming to the schema specified in the above listing. Sample Message Payload Xml <?xml version="1.0" encoding="utf-8"?> <!-- Sample Message Payload XML instance --> <Message xmlns:xsi=" xsi:schemalocation=" DMPMessagePayload.xsd" xmlns=" <MessageHeader> <SectorName>DMP sector 1</SectorName> <UnitName>Ground water</unitname> <ServiceName>Sample test webservice</servicename> <MessageType>DMPUploadMessage</MessageType> </MessageHeader> <MessageBody> <!--The message content can be any number of valid Xml elements.--> <temp>data</temp> <temp>data</temp> <temp>data</temp> </MessageBody> </Message> Methods for both XML and Object Structures The web service should support both passing the message payload as a string with the Xml Structure and an Object. Example: 1. string SampleMethodXml(string SampleMethodXml) 2. ResultMessage SampleMethodObject(Message Message) SampleMethod is the name of the message according to naming conventions. Both the methods do the same job of passing information (data and metadata) supplied by the calling web services. The method SampleMethodObject takes an instance of Message (class) as parameter and returns an instance of ResultMessage (class) containing the results of the execution of SampleMethodObject method. This method is targeted for calling the Web Service from clients developed in the.net framework. On the other hand, the method takes SampleMethodXml string as parameter and returns a string containing Result Xml. Both the input and return parameters of this method are valid Xml conforming to the schemas Message.xsd and ResultMessage.xsd. If the Xml is not valid according to schema, then schema validation error will be thrown, containing information of schema [DMP WebService Spec v1.2] 48

49 validation errors. This web method is primarily targeted for the clients on the platforms other than.net platform (for example Java clients). In order to develop clients for Web Service, please refer to an associated WSDL file. Further proxy classes for Web Service can also be generated using.net svcutil.exe functionality. Regel 4.4.3a Methods for both xml string and object structure SHOULD be supported XML Result Message Structure The Result Message will be sent by the service in response to a client s web service request, no matter whether the web service request is executed successfully or failed. The information provided in the Result Message is similar to the SOAP Fault, but not the same. Here the Result Message will be used to send both success and failure messages from the server. The communication between the Client and Web Service is carried in the message payload of respectively the request and the response. These are to some extent standardized across different business areas using (among other) a specified data structure defined by xml schema(s) and specified structure of the result. The Result Message structure contains the following fields to hold the relevant information. ResultCode (Mandatory) Integer ResultReason (Mandatory) string ResultDetail (Optional) string ResultActor (Optional) string The ResultCode is used to determine if the request have completed successfully or an error has occurred The ResultReason contains a text that explains the result status and can be logged, shown to the user etc. ResultDetail contains any data related to the response and possibly to an error e.g. details about the error from the Web Service to aid in troubleshooting ResultActor specifies the part of the code or process that is the originator for e.g. the error. May be used in trobleshooting. The resultcodes fall in 3 categories: 1. 0 Completed successfully no further action needed [DMP WebService Spec v1.2] 49

50 2. [pos integer] Completed successfully but with a warning or using the result code to take a specified action on return 3. [neg integer] Failed and the result code signifies the type of error encountered. The structure of the response is controlled by the xml schema but the content is defined individually for each Web Service. This means that result codes and associated result texts always are related to the context i.e. the web service and the business processes it covers. All result codes should be listed as part of the documentation and meaningful preferably self explanatory result text should be associated with each result code. Result codes must be unique within the Web Service/Context. The primary language for Result Text should be english but always prepared for multilanguage e.g. by using resource files or similar lookups in a database using the ResultCode as key. The schema for Result Message is shown in the following listing. The result returned by execution of web service must conform to the DMP Result Message structure. The schema definition for Result Messages is shown in the following listing. DMP_ResultMessage.xsd <?xml version="1.0" encoding="utf-8"?> <!-- XML Schema for the DMP service result message T16:00:00--> <schema xmlns:dmp=" attributeformdefault="unqualified" elementformdefault="qualified" targetnamespace=" version="1.0" xmlns=" <element name="resultmessage" type="dmp:resultmessagetype" /> <complextype name="resultmessagetype"> <annotation> <documentation> The xml response message is common for all services under DMP. The web services will return the response message after processing the request by the clients. </documentation> </annotation> <sequence> <element minoccurs="1" maxoccurs="1" name="resultcode" type="integer" > <annotation> <documentation> The ResultCode indicates the result of the web service call. [DMP WebService Spec v1.2] 50

51 It is mandatory to have this element irrespective of whether a web service call is successful or not. The ResultCode is 0 when the web service call is executed without any errors. The ResultCode will be a negative integer, if the web service call is a failure. The ResultCode with a positive integer indicates the perial success that is the service call is executed with warnings. </documentation> </annotation> </element> <element minoccurs="1" maxoccurs="1" name="resultreason" type="string" > <annotation> <documentation> This element is mandatory irrespective of whether a web service call is successful or not. The ResultReason element should contain information intended to provide a human-readable explanation of the fault or error. In case if the ResultCode is 0, then ResultReason can be empty string. On the other hand, it should contain the human-readable explanation of error or warning, that the server wish to send to the cleint. </documentation> </annotation> </element> <element minoccurs="0" maxoccurs="1" name="resultdetail" type="string" > <annotation> <documentation> This element is optional. The ResultDetail element should contain deatiled error message or stack trace in case if the web service call not executed successfully (that is when the return code is not equal to 0). </documentation> </annotation> </element> <element minoccurs="0" maxoccurs="1" name="resultactor" type="string" > <annotation> <documentation> This element is optional. The ResultDetail element should contain deatiled error message or stack trace in case if the web service call not executed successfully (that is when the return code is not equal to 0). </documentation> </annotation> </element> [DMP WebService Spec v1.2] 51

52 </sequence> </complextype> </schema> The following listing shows a sample Result message, returned by the web service when it fails to perform a database operation. Sample Result Message Xml (in case of exception) <?xml version="1.0" encoding="utf-8"?> <dmp:resultmessage xmlns:dmp=" <dmp:resultcode>-1</dmp:resultcode> <dmp:resultreason>failed to connect to the database!</dmp:resultreason> <dmp:resultdetail> SqlException (0x ): Login failed for user 'XYZ'.] System.Data.ProviderBase.DbConnectionPool.GetConnection(DbConnection owningobject) +437 System.Data.ProviderBase.DbConnectionFactory.GetConnection(DbConnection owningconnection) +82 System.Data.ProviderBase.DbConnectionClosed.OpenConnection(DbConnection outerconnection, DbConnectionFactory connectionfactory) +105 System.Data.SqlClient.SqlConnection.Open() +111 CommunityServer.Data.SqlCommonDataProvider.LoadSiteSettings(String application, Int32 settingsid, Boolean findfirst) +275 [CSException: Unable to open connection to data provider.] CommunityServer.Components.SiteUrls.Instance() +567 CommunityServer.Components.CSUrlReWriter..cctor() +26 [TypeInitializationException: The type initializer for 'CommunityServer.Components.CSUrlReWriter' threw an exception.] [TargetInvocationException: Exception has been thrown by the target of an invocation.] System.RuntimeTypeHandle.CreateInstance(RuntimeType type, Boolean publiconly, Boolean nocheck, Boolean& canbecached, RuntimeMethodHandle& ctor, Boolean& bneedsecuritycheck) +0 System.RuntimeType.CreateInstanceSlow(Boolean publiconly, Boolean fillcache) +103 System.RuntimeType.CreateInstanceImpl(Boolean publiconly, Boolean skipvisibilitychecks, Boolean fillcache) +261 System.Activator.CreateInstance(Type type, Boolean nonpublic) +66 CommunityServer.Components.SingletonProviderHelper.LoadInstance(String ProviderKey, Type defaulttype) +141 CommunityServer.Components.UrlReWriteProvider..cctor() +26 [TypeInitializationException: The type initializer for 'CommunityServer.Components.UrlReWriteProvider' threw an exception.] CommunityServer.Components.UrlReWriteProvider.Instance() +0 CommunityServer.CSHttpModule.ReWriteUrl(HttpContext context) +23 CommunityServer.Components.CSContext.Create(HttpContext context, UrlReWriterDelegate rewriter) +50 CommunityServer.CSHttpModule.Application_BeginRequest(Object source, EventArgs e) +173 [DMP WebService Spec v1.2] 52

53 System.Web.SyncEventExecutionStep.System.Web.HttpApplication.IExecutionStep.Exec ute() +92 System.Web.HttpApplication.ExecuteStep(IExecutionStep step, Boolean& completedsynchronously) +64 </dmp:resultdetail> <dmp:resultactor>data Util Component</dmp:ResultActor> </dmp:resultmessage> The following listing shows a valid sample Result message in case if the web service performs the necessary operation successfully. Please note that only <dmp:resultcode> and <dmp:resultreason> are mandatory elements in the Result message structure, the rest of the elements are optional. Sample Result Message Xml (in case of success) <?xml version="1.0" encoding="utf-8"?> <dmp:resultmessage xmlns:dmp=" <dmp:resultcode>0</dmp:resultcode> <dmp:resultreason></dmp:resultreason> </dmp:resultmessage> Regel 4.4.4a The ResultMessage format specified by the ResultMessage XML Schema MUST be used. Refer also to section 4.10 for more on Error Handling 4.5 Web Service Security Federation A Federation is a collection of realms (security domains) having established connections to share resources in a secure way. En resource provider (e.g a web service) in a realm can based on claims about the requestor allow authorized access to one or more resources within its control. These claims may consist of identity attributes or specialized attributes known in the context. Claims must be issued by an approved identity provider (STS) from one of the associated realms. DMP has a central STS, issuing the SAML tokens for web service clientsklienter (requestors). With this token the client may access resources on the resource provider aka the Relying Party. See diagram below. [DMP WebService Spec v1.2] 53

54 1. Client read web service policy 2. Client authenticates with STS 3. STS issues a token to the Client 4. Client presents token to web service 5. Web service validates token 6. Web service returns method based on claims-based authorization The entire communication uses WS Trust and is both encrypted and signed using certificates (refer to the PKI principles and standards): Certificate for the web service Certificate for the STS Certificate for the Clients Claims are name value pairs with a centrally defined xml schema (contract) ensuring that both parties have access to metadata on the contract. A typical claim could have the following syntax: claimtype= The STS exposes two endpoints each using a different security model for authentication: username uses windows credentials (username/password) to authenticate the user against a central Access Rights directory service. certificate uses client certificates for authentication. The client certificates must be associated with a user in the central Access Rights directory service. After the authentication the STS issues the claims associated with the user and these claims are read by the (claims aware) web service to authorize access to various resources. [DMP WebService Spec v1.2] 54

55 4.5.2 Security Implications on Web Service Development The security system is divided in several parts: Authentication Authorization Confidentiality Integrity Non Repudiation Authentication is handled decentrally even if some business areas are based on a centrally located system. These systems handle login credentials and stores the information about login status ( authentication Id ) in the context for later use with subsequent requests and SSO. Authorization data is stored in the security system mainly using roles. Roles are normally defined specifically for each business area and are maintained in a store (e.g. the role list). The authorization data is retrieved from the store by extracting the relevant tokens for the business process using the authentication Id as key and is transferred to the application (Web Service) using SAML tokens in the SOAP header. Currently tokens are SAML 1.1 but it is expected to be upgraded to SAML 2.0. Each application has the responsibility to interpret and act accordingly to the tokens it receives with each request. Confidentiality is handled by using encryption on various levels in the transmission stack e.g. SSL (HTTPS) on level 4 or VPN on level 2 or 3. Integrity and Non Repudiation is handled using digital signature on (parts of) the message payload. The extent of implementation of the above features depend on each busniess area, the sensitivity of the data, the need to be able to track usage etc. Generally there are two documents governing the deveopment: This specification (structure, naming conventions etc of the web service) The Role list (authorization definitions) [DMP WebService Spec v1.2] 55

56 Standardization related to security STS roles Web Service Specification Client (Requestor) Web Service (Resource Provider) Spec Spec Spec Standards from Organizations (W3C, OASIS, ) Spec Web Service Specification (This document) Roles for authorization The authorization aspect in the applications or services are governed using roles. Three types of roles are defined: System Role Basic Role Super Role The System Role (Systemrolle) is the atom of granting access to a particular resource within an application or service. System roles are translated to SAML tokens presented to the services on each request. The naming convention according to the role specification is: [Fagapplikation][Rollenavn] The Basic role (Grundrolle) is a collection (group) of Systemroles within one business system. The naming convention according to the role specification is: [Sektor][Emne][Dataset][Facet][Myndighed][Myndighedsnavn] [DMP WebService Spec v1.2] 56

57 The Super role (Superrolle) is a collection (group) of Basic roles that may span several business systems. The naming convention according to the role specification is: [Sektor][Emne][Dataset][Facet][Myndighed][Myndighedsnavn] Basic roles and Super roles are typically shaped to cover the use cases for the business system(s). For more details about setting up the web service to work in the security environment refer to [7.11] For more details on roles used for authorization refer to [7.6] Regel 4.5a Web services MUST comply with the DMP security system. 4.6 Web Service Application The developer could use the sample code as a template for the development of the webservices and must be prepared to use the libraies for some of the generic functions on the portal to ensure compliance with the cross functional services e.g. log, monitoring, security etc. Stub code may be available from DMP to be used in the development and to ensure correct usages of the common features. (Check for compatibilitet with (future) ESB Regel 4.6a The DMP sample client and server stubs MAY be used Regel 4.6b If DMP has implemented an ESB the service MUST be checked for compatibility with the ESB 4.7 REST support Introduction to REST REST (Representational State Transfer) services rely on a number of existing standards to operate: most typically the HTTP protocol, URIs and the representation of the transferred data usually XML or JSON (JavaScript Object Notation refer to for more details) but it can be anything from CSV to HTML to a JPEG. REST web services operate using HTML requests and verbs. The verbs include: GET gets the object or resource the URI is pointing to. POST inserts the object or resource the URI is pointing to. PUT updates the object or resource the URI is pointing to. [DMP WebService Spec v1.2] 57

58 DELETE deletes the object or resource. REST differs from procedural call services (like SOAP web services) in that the object or resource is referenced first, then the verb. You could say that SOAP is verb orientated and REST is noun orientated. For example if a web service is exposing a bus route schedule, the web service URL may look like: To get the object for that route you would use the GET HTTP verb in the request. To add a new route you would use the POST HTTP verb and post to the route number that doesn t yet exist. Advantages Lightweight Easy to build (no toolkits required and people used to write URIs) Disadvantages No type/data checking Not suited for secure solutions Not suited for some data models It is definitely not all types of data that are suitable for being presented using REST and the usage of this type of presentation for (parts of) the data should be carefully considered before implementation for any business area. Regel 4.7.1a OIOREST recommendation SHOULD be followed Web services are the primary way to access data and the ONLY way to perform create, update and delete functions. REST is the secondary way to access (read) data made available for this purpose. This approach is chosen in order to best support the security etc. DMP wants for the data and business processes The body of the request Since REST web service communication is HTTP communication, REST can transfer any number of data formats. XML (and JSON) are the most common however. A bus route object sent to the client on a GET request may look like: <BusRoute> <RouteNumber>A370</RouteNumber> <Date> </Date> <DepotDepartures> <DepotDeparture> [DMP WebService Spec v1.2] 58

59 <Driver> <DepatureTime>05:35:00</DepatureTime> </DepotDeparture> <DepotDeparture> <Driver> <DepatureTime>08:35:00</DepatureTime> </DepotDeparture> </DepotDepartures> </BusRoute> Regel 4.7.2a The REST request and response body MUST be using XML Regel 4.7.2b The REST request and response body SHOULD have same format as message payload for corresponding web services URI URIs (Universal Resource Identifiers) are central to REST web services. They are used to refer to the object resource of interest. This is handy when one object needs to reference another object as seen in the reference to the bus driver of the route in the above XML example. Query parameters can also be used. For example, to get a list of bus departures for the 1 May 2009 for driver Lise Larson you may summit a HTTP GET request to: liselarson Or get update Lise s driver details by sending a HTTP PUT to: DMP has a naming convention for URIs which include all REST services: [DMP WebService Spec v1.2] 59

60 Regel 4.7.3a The REST URIs MUST comply with DMP naming conventions Regel 4.7.3b REST Query string parameters MUST be in english Regel 4.7.3c REST Query string parameters MUST use ASCII character set and MUST NOT use space HTTP headers REST web services use HTTP header information on their requests. The Authentication header is a frequently used example. It can be possible for the client to make head request that works just like a GET request but it returns only the response headers and no entity body. Other common REST web service headers include: Allow can return to the client to determine what the service is capable of returning. For example GET if the user have limited access or GET, POST, PUT and DELETE if the user has more access. Content Type defines the character encoding to be used in the response. Accept Encoding can define what format the body is in HTTP status codes REST web services use HTTP s suite of standard status codes to specify the result of the request. Status codes are organized into ranges that mean different things. For example: status codes in the 200 range mean a successful request status codes in the 400 range mean the client issued an invalid request, whether it be a object not found or unauthorized access etc. Regel 4.7.5a REST services MUST use standard HTTP status codes Security REST services can authenticate requests in a couple of ways: 1. Using HTTP s basic access authentication. This authentication is easy to set up and widely used. The main problem with this method is that usernames and passwords are sent to the server as plain text. One way around this shortcoming is to require SSL (HTTPS). 2. Another option is to use a custom authentication technique where by a hash of the request is placed in the authorization header what was calculated from the body of the request with a timestamp using the private password. The server (knowing the private password can too generate the hash. If the two hashes are identical and the timestamp isn t too far of the current time the client is authenticated. [DMP WebService Spec v1.2] 60

61 REST is currently NOT supported by the DMP security framework! This means that only Read Only services for specific areas with non sensitive data are possible since DMP has allowed these services to be presented for anonymous users. Regel 4.7.6a The REST service MUST comply with DMP security Framework Regel 4.7.6b Using a REST service MUST be agreed with DMP in each case Regel 4.7.6c REST services MUST NOT be used for anything else but READ operations Limits As URLs are used much in REST the maximum URL length becomes prevalent. The maximum URL length is browser dependant, the smallest being Internet Explorer at 2048 characters for GET requests. The maximum size of a POST request is determined by the server. Microsoft s IIS 7 sets the maximum at 200kb. This can be changed however by changing the AspMaxRequestEntityAllowed setting Support for REST in standard platforms REST has various levels of support in standard systems, some example are provided below for information. Windows Communication Foundation (WCF) 3.5 has support for REST web services at a number of levels and in a number of built in tools. WCF includes several different object serializers out of the box for generating and consuming XML (and JSON etc.). Using WCF UriTemplate class and URI template strings it is possible to more easily parse the URLs which is so central to REST web services. A URI template string may look like: {driver} Please note that much of the URI parsing functionality requires at least.net 3.5 SP1 and IIS7 or later versions of.net framework. When defining the service contract it is possible to add the [WebGet] and [WebInvoke] attributes (providing the WCF endpoint binding as been set to webhttpbinding and behaviorconfiguration has been set to webhttp). These attributes define the mapping between the URIs and HTTP verbs with.net methods. For example: [ServiceContract] public partial class BusRouteService [DMP WebService Spec v1.2] 61

62 { [WebGet(UriTemplate = "/{routenumber}/{date}/")] [OperationContract] BusRoute GetBusRoute(string routenumber, string date) {...} } [WebInvoke(Method = "POST", UriTemplate = " drivers/{driverid}")] [OperationContract] void PutDriver(string driverid, Driver driver) {...} Although WCF has adequate tools to implement almost any REST web service, the open source WCF REST Starter Kit, a Microsoft CodePlex project, can make developing REST web services even easier. Regel 4.7a REST services MUST be based on a web service according to the standards in this specification 4.8 Logging Logging is done using a limited number of systems. These are all centrally controlled and one service is made available for (mandatory) use by services: the Log Service aka an Audit Trail (Revisionsspor). Other logging will be performed by using the Windows log system (Event Log) and built in ESB logs. Any service must be implemented in such a way that flooding of the Log is prevented in case of a persistent failure Log Service Basically the Log service is logging Who does What and When and may be used as an Audit Trail ( revisonsspor ), for Track And Trace, Debugging and Statistics purposes. A sample log record is for example, among others defined with the following fields. Generic fields o MessageId o Timestamp o LogType o LogSubType o LogLevel o UserId o SystemId o WebserviceURI o WebMethodName o ParameterCollection o LogData [DMP WebService Spec v1.2] 62

63 Specific fields (e.g. Fagsystem specific logging) o Custom (field which is place holder for application specific custom data.) Most of the fields are input from the client and some are added by the Logging service itself (e.g. ID and timestamp). The use of this LogService is mandatory for services on specified events/actions and optionally available for more detailed looging specific for the web service. Log entries are used for various purposes refer to section for more details on this. Regel 4.8.1a The DMP Log Service MUST be used Regel 4.8.1b The LogMessage format specified by the LogMessage XML Schema MUST be used. Regel 4.8.1c The service MUST log all updates to data and access to sensitive data to the DMP Log Service. Regel 4.8.1c The service SHOULD log all other relevant activities to the DMP Log Service. The central security system will log selected events and possible violations of the security system. Description of XML Schemaes, client code etc. Are provide in section [7.8] Logging into Windows Event Log The event logs contain the most important information for diagnosing application and operating system failures. They are useful in determining the health and status of an application, and also to ensure that the system and applications are operating properly. Windows systems store all logs in binary.evt files. There are three basic event logs: System, Application and Security. System log: The system log contains events logged by Windows system components. It tracks miscellaneous system events like startup, shutdown and events like hardware and controller failures. For example, if a driver fails to load during startup, an event is recorded in the system log. Application log: The application log contains events logged by programs. For example, a database program may record a file error in the application log. Events that are written to the application log are determined by the developers of the software program. It is an important source for application status information. Applications can use the application log to report events that have occurred, such as errors, warnings, and informational messages. Security log: The security log records events such as valid and invalid logon attempts, as well as events related to resource use, such as the creating, opening, or deleting of files. For example, [DMP WebService Spec v1.2] 63

64 when logon auditing is enabled, an event is recorded in the security log each time a user attempts to log on to the computer. The Windows Event log contains following event types. Information: This type of event describes the successful operation of a task performed by an application or service. Warning: This type of event is not necessarily significant, but indicates that there could be a potential problem in the future. The entries help in taking preventive measures. For example, a Warning message is logged when disk space starts to run low. Error: This type of event describes a significant problem, such as the failure of a critical task. Error events may involve data loss or loss of functionality. For example, an Error event is logged if a service fails to load during startup. Success Audit: This type of event describes the successful completion of an audited security event. For example, a Success Audit event is logged when a user logs on to the computer. Failure Audit: This type of event describes an audited security event that did not complete successfully. For example, a Failure Audit may be logged when a user cannot access a network drive. Normally, it is a good practice to log all important events such as application/service start, shutdown and other crucial events into windows event log for monitoring purposes. Web services hosted on Internet Information Service need not necessarily log their start/shutdown events into windows event log, as their application life cycle (such as loading/unloading of an ASP.Net web application/web service) is automatically managed by the IIS host environment, to allocate and manage the resources efficiently. The events in case failure to load the web applications/web services on IIS will be automatically logged to the windows log by the IIS. On the other hand, if a web service is using some legacy application such as windows service or some other applications behind the scenes to perform some complicated tasks, then it is necessary to log some crucial events for monitoring purposes. The application/service start and shutdown events should be logged into the system log. A custom event log should be created and used for logging all application specific crucial events. For example a custom log by name DMP Event Log should be created and used for logging all events from DMP applications/services on a server. The following information MUST be logged while logging the crucial events by the Applications/Services. Source Name: Name of the application/service that is logging. Event Message: Detailed description of the event. In case if the event type is error, then stack trace along with error message should be part of the event message. [DMP WebService Spec v1.2] 64

65 Event Type: Based on the nature of the event, one of the predefined windows event types (listed above) should used. Regel 4.8.2a A custom Windows Event Log SHOULD be created and named DMP Event Log Regel 4.8.2b Naming conventions from Log Service MUST also be followed using the DMP Event Log Regel 4.8.2c Application/Service start, shutdown and major errors MUST be logged in the DMP Event Log Regel 4.8.2d Other relevant Application/Service events SHOULD be logged in the DMP Event Log 4.9 Transactions across web services Transactions are an important building block in all crucial business applications. A transaction is a unit of work that involves one or more resources and is either completed in its entirety or is not done at all. Participating resources are locked for the duration of the transaction. Depending on the readiness of all the participating resources, the changes made to the resources are either committed or rolled back, and the lock is released. Increasingly, Web services are key additions to business applications and third party integration. A complex business process that accesses multiple Web services needs a reliable mechanism for combining together the various Web services. This ensures that no part of the business process gets out of sync with the other parts. The Web Services Transactions specifications define mechanisms for transactional interoperability between Web services domains and provide a means to compose transactional qualities of service into Web services applications. WS Coordination This specification describes an extensible framework for providing protocols that coordinate the actions of distributed applications. Such coordination protocols are used to support a number of applications, including those that need to reach consistent agreement on the outcome of distributed activities. The framework defined in this specification enables an application service to create a context needed to propagate an activity to other services and to register for coordination protocols. The framework enables existing transaction processing, workflow, and other systems for coordination to hide their proprietary protocols and to operate in a heterogeneous environment. Additionally this specification describes a definition of the structure of context and the requirements for propagating context between cooperating services. The extensible coordination framework (WS Coordination) defines specific coordination types for: [DMP WebService Spec v1.2] 65

66 Short duration, ACID transactions (WS AtomicTransaction) WS AtomicTransaction Longer running business transactions (WS BusinessActivity) This specification provides the definition of the atomic transaction coordination type that is to be used with the extensible coordination framework described in the WS Coordination specification. The specification defines three specific agreement coordination protocols for the atomic transaction coordination type: completion, volatile two phase commit, and durable two phase commit. Developers can use any or all of these protocols when building applications that require consistent agreement on the outcome of shortlived distributed activities that have the all or nothing property. WS BusinessActivity This specification provides the definition of the business activity coordination type that is to be used with the extensible coordination framework described in the WS Coordination specification. The specification defines two specific agreement coordination protocols for the business activity coordination type: BusinessAgreementWithParticipantCompletion and BusinessAgreementWithCoordinatorCompletion. Developers can use any or all of these protocols when building applications that require consistent agreement on the outcome of long running distributed activities. Microsoft Windows Communication Foundation supports WS Atomic Transactions and also IBM has support. Refer also to section ErrorHandling Refer to section Response Categories As described in section all web service communication have a Client (Requestor) and a Web Service (Server). The Client calls a function (method) at the Web Service and gets a response back from the Web Service Server or (in case of broken communication) from its own framework in the Client. There are a number of possible categories of result from such a scenario where a Client calls a Web Service via a standard unreliable request/response protokol like SOAP/HTTPS: Result response received The Client receives a response from the Web Service. The Client then knows that the operation has been completed successfully and that any necessary transactions have been committed in the Web Service. The ResultCode may be 0 indicating a succesful completion positive integer indicating successful completion but with the ReturnCode signalling either a warning or some output from the service to be used for further processing (e.g. branching) [DMP WebService Spec v1.2] 66

67 negative integer indicating unsuccessful completion Fault response received The Client receives an error from the Web Service. The Client then knows that the call has failed and that any transactions in the Web Service have been rolled back. This may be considered a special case of the Result response received as described above. The fault is indicated be the ResponseCode being negative No response received The Client does not receive any response from the Web Service, but will get an error (exception) generated by the communications framework. The Client now does not know if the request was processed by the Web Service, what the result was and if any transactions was committed or rolled back. The error may be caused by the request not reaching the Web Service, That the Web Service crashed or that the response never made it back to the Client Client has crashed The Client sends the request and then crashes either before the Client receives the response or after the response is received but before the Client has processed the response and completed its own transactions. The Web Servicen is not aware that the Client has crashet and has/will commit any transactions as normal. The Client is also not aware of the status and may after a restart retry the operation which may cause undesired results and may require duplicate handling in the Web Service Action on Error The communication between the Client and Web Service is carried in the message payload of respectively the request and the response. Error responses uses the same overall structure as successful responses but obviously with a different content. Any error is typically received in the form of an exception. Depending on the nature of the error the Client may attempt to retry the operation, change the process flow or take other action. If the operation even after retrying still fails an error handling procedure specific for the business process must be invoked. This involves as a minimum logging and e.g. putting the failed operations in and error queue and leave it to operations procedures to handle the error. If the application has a GUI a message may be sent to the user and also the decision to abort, retry etc. Refer to section for more on Result structure and error codes Refder to section 4.8 for more on Logging errors in the Windows Event Log Regel a All Errors MUST be logged in the DMP Logging Service Regel b Applications SHOULD have a Log Level to control the detail level of logging in the DMP Logging Service. The Log Level MUST be configurable with a parameter. [DMP WebService Spec v1.2] 67

68 5 Test 5.1 Test Client All services must be tested according to appropriate testing schemes before release. It obviously includes internal development testing such as unit testing but also includes developing a Test client that can test all methods on the Web Service. The purpose is to ensure a structured comprehensive test of the business service. It may be used for: 1. Vendor internal testing during development and system test phases 2. Acceptance test 3. Performance test 4. Regression test related to upgrades or new versions. The Test client is typically an application which must provide 1. method calls with dummy data 2. log of timing i.e. timestamp when request is sent and when response is received 3. a user interface a. with easy and intuitive access to execute the various methods b. display of (type of) request and response with response code c. display of timestamps d. preferably possibility to enter relevant parameters for the methods e. preferably functionality to save result in a (text/xml) file It will typically be appropriate to use configuration files (XML format) containing the parameters for the Test client so entering a large number of parameters can be reduced to providing the filename of the configuration file. This combined with some amount of automation will enhance the usability of the Test client and ensure stable and reproducible test scenarios. Dummy data for the Test client methods should also be provided in files on the harddisk. 5.2 Alive Method All Web Services must implement a specific method for monitoring purposes. The method uses a standardized xml message payload for request and response compliant with the normal message payloads specified in section and [DMP WebService Spec v1.2] 68

69 The last part of name of the method must be Alive to simplify the work for setting up operations monitoring. The Alive method will respond to requests if the Web Service is alive and well with a ResultMessage where ResultCode is 0 ResultReason is Completed successfully ResultDetail is [timestamp] (in UTC and standard ISO 8601 format) Other ResultCodes may be used to specify various conditions accompagnied by a text in ResultReason but the rules from section about positive ResultCodes signifying a running state whereas negative ResultCodes signify some kind of error. Although the minimum implementation just returns from the web service (and as such only checks if the web service resources are running) the functionality of the IsAlive method may be far more in depth checking all kinds of resources e.g. access to database, availability of other services etc. The designer of the business service decides which level(s) are to cheked in the IsAlive method. The ResultCode and ResultMessage will reflect the failures found and give a better picture for the calling aplication or monitoring program. The absence of a response from calling the Alive method is of course an indicator that the service is not up and running and slow responses may indicate (over)load, insufficient resources etc. Regel 5.2a All Web Services MUST implement a standard IsAlive method with at least the 0 response Regel 5.2b The name of the method (service) MUST be IsAlive and also comply with naming convention from section Regel 5.2c The ResultCode and ResultMessage MUST reflect the failures found 5.3 Compliance Test A formal compliance test must be performed before any Web Services are released and deployed to operations. This requirement is valid also for updates to existing Web Services although a reduced regression test may be applied in this case. The purpose is to verify that the service fulfils the functional requirements and will function in the operational environment e.g. with the central ESB and any monitoring and statistics tools. Also compliance with security regulations and systems needs to be verified. [DMP WebService Spec v1.2] 69

70 5.4 Performance Test The Test client may be used for performance testing using the timestamps logged and displayed when calling the methods. It will typically be applied in a larger setup e.g. with stress tools to create a background load and may require automated and repetitive execution of methods calls along with pre defined data. The central logging service also logs timing and may be used as a supplement for generating reports. Performance testing is part of the development, testing and acceptance procedure for each individual business service being implemented and requirements will vary depending on the nature of the service and the contract with DMP. 6 BizTalk Server specifikations. DMP has evaluated Microsoft BizTalk as an ESB. This section gives an introduction and overview of how to develop web services passing through BizTalk in stead of requestor communicating directly with the server. General guidelines and best practices are presented as well as rules for the compliance with DMP specification. Sample BizTalk architecture. 6.1 Naming Conventions Namespaces [DMP WebService Spec v1.2] 70

71 Regel 6.1 All the namespaces used in the Biztalk server applications MUST conform to DMP Namespace Naming Conventions XML Message format Regel 6.1.2a All XML message formats that are exchanged between applications SHOULD be defined with proper namespaces conforming to the OIO standards. Regel 6.1.2b If the XML message are designed to carry payload, then the format SHOULD conform to the payload message standards specified in 4.4 Regel 6.1.2c All XML messages MAY be designed with suitable XML schemas conforming to OIO NDR 3.2 or later versions XML Schemas Regel 6.1.3a All the Xml Schemas required for Biz Talk Server projects MUST be defined confirming to OIO NDR 3.2 or later versions. Regel 6.1.3b If the Xml schema definitions are used by multiple BizTalk server projects, then the schemas MUST be placed in a separate project under the Biz Talk Server solution. Keeping all schemas in a separate project will enable easy deployment across multiple Biz Talk server projects. Hence it is recommended to put all the schemas that will be consumed by different BizTalk server applications into one assembly and then reference the schemas assembly from all the applications in the BizTalk server. If a XML schema is deployed to more than one project, then an error will be thrown by the Biz Talk Server application saying that Cannot locate document specification because multiple schemas matched the message type [DMP WebService Spec v1.2] 71

72 Regel 6.1.3c The XML Schema constructs redefine, include, and import elements SHOULD be used when the schemas for the message formats become too large and complex or when the schemas that represent your different types of instance messages have some portions in common. It can be useful to combine smaller schemas into the schemas that ultimately define the structure of messages that will be used for communication between applications. The XML schemas can be published as WCF services that receive input by using the BizTalk WCF Service Publishing Wizard. 6.2 BizTalk Conventions BizTalk Folder structure Use a consistent folder structure for BizTalk server projects and solutions. It will facilitate the maintenance of the projects easier. If the project is not too complicated, then the following suggested structure may be followed. \projects\<client>\<application>\ Projects Documentation Deployment\Scripts Deployment\Bindings BizTalk Application Deployment During deployment, Visual Studio may undeploy, unbind, stop, and unenlist artefacts contained in project assemblies, causing unexpected and undesired consequences in a production environment. Regel 6.2.2a An assembly MUST NOT be deployed to a Biz Talk Server production environment from Visual Studio. Regel 6.2.2b A shared web application (for example as a receive location) SHOULD be deployed as a separate application. Regel 6.2.2c MSI files MUST be used in order to deploy a Biz Talk Server application to production environment. If you are deploying a web application which is shared by more than one solution, deploy it as a separate application. If a web application is shared as a part of another Biz Talk server application, then its virtual directory will be removed when that Biz Talk server application is removed. The web application will stop working and any other Biz Talk server applications relying on it would stop working. [DMP WebService Spec v1.2] 72

73 MSI files can package all the resources such as depended custom assemblies/dlls, schemas, bindings etc. that are needed by a Biz Talk Server application. Using MSI files to deploy a Biz Talk server application will also simplify deployment and maintenance of different versions of applications BizTalk Orchestration An orchestration is a flexible, powerful tool for representing an executable business process based on XLANG/s language. XLANG/s can be viewed as a messaging language with some limited expression capabilities of C# language. You can design flow, interpret and generate data, call custom code, and organize the entire process in an intuitive visual drawing, and at run time, the BizTalk Orchestration Engine executes XLANG/s files which are the executable business processes that are produced by BizTalk Orchestration Designer. Messages, the send and receive actions that operate on them, and the ports through which they are transported are all fundamental elements of an orchestration. The message is the medium by which orchestrations communicate with the outside world and by which e business is conducted. Receive and Send shapes encapsulate the functionality you need to receive messages into your orchestration and send messages from it. You should become familiar with the various shapes that Orchestration Designer provides to represent the logical flow of your orchestration BizTalk Orchestration Exeption Handling Regel 6.2.4a Suitable exception handling MUST be used in Biz Talk Server Orchestrations. An effective exception strategy will simplify troubleshooting, and allow delegation of troubleshooting to non administrators. Exceptions in BizTalk orchestration are handled using a 'scope' shape. Regel 6.2.4b All the calls to the external web services SHOULD be defined in scope shape with proper exception handling. The scope shape defines an exception section where an exception can be gracefully handled. Place all the logic for which an exception needs to be handled within a scope shape. Regel 6.2.4c The scope's transaction type property SHOULD be assigned to 'NONE'. This will avoid the overhead of a transaction, but still have the ability to handle exceptions. In order to communicate with WCF services from a Biz Talk server application, use appropriate Wizard supplied by the Microsoft as part of Biz Talk server tools. [DMP WebService Spec v1.2] 73

74 6.3 Web Services BizTalk Server provides built in support for Windows Communication Foundation (WCF) services. BizTalk Server enables us to reuse and aggregate all your existing WCF services within the orchestrations. BizTalk Server also has support for native adapters in WCF services. Native adapter support provides scalability, fault tolerance, and tracking capabilities for WCF services. WCF service can be used from BizTalk server in two ways: Publishing and Consuming Publishing web services You can publish/expose your orchestrations and schemas as WCF services with the WCF adapters to separate the WCF service logic from the business process logic. For isolated WCF adapters, you can use the BizTalk WCF Service Publishing Wizard to create isolated WCF receive locations hosted by Web applications running in Internet Information Services (IIS). For the in process WCF adapters, you can publish service metadata for any WCF locations with the BizTalk WCF Service Publishing Wizard. The publishing of metadata allows the creation of client code using the svcutil.exe utility Consuming web services In order to consume a WCF web service, you can use the BizTalk WCF Service Consuming Wizard to generate the BizTalk artifacts, such as BizTalk orchestrations and message types, based on the metadata document of the WCF service. Metadata allows a send port to access an external service as a web service client. Metadata is used for describing the endpoint address, binding, and contract. The receive locations can be either hosted in Biz Talk server or in IIS. Hosting a receive location within the BizTalk Server process space, has the advantages simple deployment and development. The Biz Talk Server can creates more host instances than hosting in IIS to take advantage of the high availability and load balancing capabilities of BizTalk Server. But on the other hand, to enable web services on Biz Talk server, at least one isolated host process must be created. An isolated host instance can run only one adapter. Regel 6.3.2a If there are receive handlers for HTTP and SOAP adapters with the one single isolated host, then you MUST create two application pools, one application pool for each adapter. Regel 6.3.2b For the WCF services published with WCF adapters, the IsOneWay property of the service should be set to false. If the IsOneWay property is set to false, then even methods those return a void result in the rely message. In this way, the web service host environment creates and sends an empty message to indicate to the caller that the method has returned. Using this approach enables to send exceptions thrown by the service operation back to the client. [DMP WebService Spec v1.2] 74

75 6.4 Bindings You can use the WCF WSHttp adapter to do cross computer communication with services and clients that can understand the latest web service standards, using either the HTTP or HTTPS transport. The WCF WSHttp adapter provides full access to the SOAP security, reliability, and transaction features. Regel 6.4a The WCF WSHttp binding type SHOULD be used as a transport type for both Send and Receive ports for communicating (either for consuming or receiving input) with a WCF service, until unless you have special requirements for using Custom bindings. The proxy setting for the WCF WSHttp (and also WCF BasicHttp) can be specified on the Proxy tab of the send port or the Proxy tab of the send handler. If this proxy setting is not correctly configured, the WCF adapters suspend the messages, and there will be an error saying that "There was no endpoint listening that could accept the message". The WCF WSHttp (and also WCF BasicHttp) send ports always ignore the proxy if the service address begins with whether the proxy is configured on the Proxy tab of the send port or the Proxy tab of the send handler. Regel 6.4b The host name instead of localhost SHOULD be used, if clients have to go through the proxy when talking to web services on the same computer. Regel 6.4c Separate host instances for send ports SHOULD be created for the send ports that use different proxy addresses and/or proxy credentials. The rule 9.4c will results in best performance for WCF send adapters. Also creating separate host instances will avoid contention on proxy settings. 6.5 BizTalk Global Variables There are various options to store and access global variables that are used by the orchestrations in a Biz Talk server project. The global variables can be stored in 1. Biz Talk Server Configuration files 2. Windows Registry 3. SQL Server [DMP WebService Spec v1.2] 75

76 Regel 6.5 For simple Biz Talk server applications, the global variable SHOULD be stored in configuration files (BTSNTSvc.exe.config). This will enable easy maintenance and also removes the overhead of scripting the registry settings for global variables. [DMP WebService Spec v1.2] 76

77 6.6 BizTalk Server ADFS Scenarios Scenario A Simple Service Client Web Service 1 2 Scenario B Service using Claims Client Secure Token Server 2 Web Service Servers with Scenario C Service using standard BizTalk Client Publish 1 BizTalk 10 Consume 2 Web Service 4 3 Scenario D Service using BizTalk and Claims (To Be verified) Secure Token Server Client Publish 4a? 4b BizTalk Consume Web Service [DMP WebService Spec v1.2] 77

78 6.7 Scenarios Scenario A Simple Service 1. A standard (.Net) web service client sends a request to a (.Net) web service. The Payload is a simple xml structure. 2. The web service processes the request and send the response to the web service client Scenario B Service using Claims In this scenario, the client presents certain claims issued by the authentication or ADFS server. Claims describe the capabilities associated with some entity in the system, often a user of that system. The set of claims associated with a given entity can be thought of as a key or a right to some resource (called value in the model). A claim is the expression of a right with respect to a particular value /resource. A right could be something like "Read", "Write", or "Execute." A value could be a database, a file, or a property. 1. Client authenticates using credentials (Certificate or username/password) The client uses STS Certificate public key to encrypt the message to STS server. The STS server identifies the client by the supplied credential in the request message either by username/password or by the client certificate. In case, if the client uses its certificate to prove it s identify, a digest will be signed by the client s private key and then the message will be encrypted by the STS server s public key. 2. STS issue security token with claims (SAML format) The STS uses the STS Certificate private key to decrypt the message supplied by the client. After verification of client credentials, the STS server prepares a message containing claims for the client and then it uses its private key to encrypt the claims (to prove to the service that the claims are prepared by the STS server only). After that it uses the Web Service certificate public key to encrypt the message to create the security token. 3. Client send request to web service with security token embedded in SOAP header. The client has no access to the content of the security token as it is encrypted by the public key of web service, so only web service can decrypt it with its private key. At the web service, it decrypts the security token with its own private key and then further decrypt the claims sent by the STS server using public key of STS server to make sure that claims are prepared only by STS server. Finally it reads claims to know about the client s authorizations to the resources and then acts accordingly. The web service makes no calls to the STS server. 4. After processing the request the web service send a response back to client Scenario C Service using standard BizTalk The web service client wants to communicate with the web service as described in the above scenarios, but a BizTalk has been positioned in between the web service and client. 1. A standard (.Net) web service client sends a request to a published location on BizTalk server. Payload is a simple xml structure. [DMP WebService Spec v1.2] 78

79 2. The BizTalk receives the request on a published web service, start an orchestration and start processing the request. 3. The BizTalk server forwards the request through the send port to the consumed target web service. In this step BizTalk Act as the original web service client and the request in general to look as if they came from the original requestor (the web service client). 4. The web service processes the request and sends the response back to BizTalk (synchronously). 5. The BizTalk passes the response back to the original requestor (the web service client)(synchronously) Scenario D Service using BizTalk and Claims Se pkt Certificates involved 1. STS server certificate 2. Client certificate 3. Web service certificate 7 Appendix: Reference Documents 7.1 DMP wiki De fleste af dokumenterne beskrevet nedenfor samt andre dokumenter fra DMP kan findes på DMPs wiki Link til DMP wiki: DMP navnestandard Under udarbejdelse 7.3 DMP Infrastruktur Under udarbejdelse 7.4 DMP IT Arkitektur rammeværk arkitektur+forside 7.5 DMP Procedurer for tilkobling, deployment, versionering, governance mm Under udarbejdelse 7.6 DMP Rollebeskrivelser FB6F 491E AC26 6B955E260954/0/Rollebeskrivelse_ver_16.pdf [DMP WebService Spec v1.2] 79

80 7.7 DMP Fællesdatastrukturer fra sektorstandardiseringsudvalget Under udarbejdelse 7.8 DMP Logningsservice DMP Standard SLA skabelon Under udarbejdelse 7.10 Dokumentations template Dokumenterne ligger underfølgende link: Her skal som minimum udfyldes følgende: B1.1 3 Forretningsobjekter beskrivelse( B3.1 Forretningsservices ( B3.1a Serviceoperationer ( Guidelines for DMP Web Service security (Globeteam) Denne side kræver specielle rettigheder for adgang. Rettighederne kan fås ved kontakt til DMP 7.12 W3C, OASIS standarder Extract from OIOXML NDR NDR Rule Id OIO: OIOXML Modelling Rules OIO 1 Rule Existing elements or types belonging to the OIOXML Core Components and OIOXML Domain Components classes MUST be reused. GXS: General XML Schema Rules GXS 1 GXS 2 OIOXML schemas MUST be defined in accordance with the W3C XML Schema Recommendation of May 2nd, 2001: XML Schema Part 1: Structures and XML Schema Part 2: Datatypes. All XML schemas MUST comply with version 1.0 of the W3C XML Recommendation of February 4th, 2004: Extensible Markup Language (XML) 1.0 (Third Remarks For example if you are using CPR Number data element in your message format, you MUST reuse the either element or type from CPR namespace ( CivilRegistrationNumber/ CivilRegistrationNumberType). XML version [DMP WebService Spec v1.2] 80

81 GXS 3 Edition). All XML schemas MUST use UTF 8 as XML encoding scheme. Choice of XML encoding scheme GXS 4 All XML schemas MUST be assigned a namespace. Namespace assignment GXS 5 GXS 8 The include construct MUST be used when referring to a schema module under the same namespace. Otherwise the import construct MUST be used. All schemalocation attributtes MUST be specified with an absolute and valid URL that identifies the location of the referred schema module in the Infostructurebase. GNR: General Naming Rules GNR-1 Elements, attributtes, and types MUST be named in English according to the Oxford English Dictionary or other relevant technical dictionaries. GNR-2 Elements, attributtes, and types MUST be uniquely named within the namespace of a schema and SHOULD be uniquely named across all namespaces of all approved schemas. GNR 3 A noun used as part of an element, attribute, or type name MUST be in singular form unless the noun only exists in plural form (e.g. Goods). GNR 4 Element and attributtes MUST be named using UpperCamelCase. GNR 5 Abbreviations and acronyms SHOULD NOT be used in names. GNR 7 Underscore (_), period (.), and hyphen ( ) MUST NOT be used in names. The use of include and import The use of schemalocation Naming in English Unique naming Singular form of nouns The use of UpperCamelCase naming convention. Use of Abbreviations and acronyms. The use of characters in names. GNR 8d A complex type MUST NOT use the Representation term in its name. The Property term MUST be "Collection" if the type contains exactly one element with 2 or more occurrences. The Property term MUST either be "Structure" or omitted completely if the type contains 2 or more different elements. TPN: Type Naming Rules TPN 1 The name of a simple or complex type MUST end with the suffix "Type". ELN: Element Naming Rules ELN 1 An element SHOULD have the same name as its type with the suffix "Type" omitted. ATN: Attribute Naming Rules Naming rules for complex types. Suffixing for Types The relation between element and type names [DMP WebService Spec v1.2] 81

82 ATN 1 Attributes MUST be named using lowercamelcase. Use of lowercamelcase for attributes. FNR: File Naming Rules FNR 1 The file name of a schema module MUST comply with the naming scheme: <namespace prefix with capital letters>_<element name>.xsd. GTD: General Type Definition Rules (applies to simple and complex types) Naming of schema module files GTD 1 All types MUST be defined as strongly as possible. Strong data types GTD 2a GTD 5 All simple and complex types belonging to the OIOXML Core Components and OIOXML Domain Components classes MUST be globally defined. The built in simple types anyuri or base64binary SHOULD be used for handling binary content. CTD: Complex Type Definition Rules (applies only to complex types) CTD 1a CTD 1b CTD 6 A complex type SHOULD be defined using either the sequence or choice construct. A complex type MUST NOT be defined using the all construct. The anyattribute construct MUST NOT be used in a content model. ELD: Element Declaration Rules (applies ony to elements) ELD 1a ELD 1b ELD 2 ELD 4 All elements belonging to the OIOXML Core Components and OIOXML Domain Components classes MUST be globally declared. All elements belonging to the OIOXML NDR Components class SHOULD be globally declared. All elements MUST be assigned a namespace, i.e. the attribute elementformdefault in the root element schema MUST be assigned the value "qualified" and the attribute form MUST NOT be used in element declarations. The attribute nillable MUST NOT be used in element declarations. ATD: Attribute Declaration Rules (applies only to attributes) Global type definitions Handling binary content Definition of complex types by Aggregation Definition of complex types by Aggregation The use of anyattribute Global element declarations Global element declarations Namespace for elements The use of nillable ATD 1 Attributes MUST only be used for metadata. The use of attributes ATD 2 All attributes MUST NOT be assigned a namespace, i.e. the attribute attributeformdefault in the root element schema MUST be assigned the value "unqualified" and the attribute form MUST NOT be used in attribute declarations. NMS: Namespace Rules Namespace for attributes NMS 1 A namespace MUST represent a valid URL in the Namespace representation [DMP WebService Spec v1.2] 82

83 NMS 2 Infostructurebase and comply with the following naming scheme: /xml/schemas/<yyyy >/<MM>/<DD>/ A namespace prefix MUST be based on the internet domain name in the corresponding namespace without the ending period (.) and root domain (e.g. without ".dk"). Prefix naming in the namespace declaration 7.13 Claim enabling of biztalkserver. Fås ved henvendelse til DMP 7.14 DMP Test Service ADFS and BizTalk Developers Guide +Milj%C3%B8+Portal.pdf 8 Appendix: Rules collection Skal udfyldes med kryds i felterne Ja/Nej/Delvis Såfremt der sættes kryds i Nej eller Delvis skal bemærkningsfeltet udfyldes. Regel Ja Nej Delvis Bemærkninger 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. 3.1a Data SKAL udstilles via web services 3.1b De til enhver tid gældende procedurer for tilkobling, deployment, versionering, governance mm SKAL følges 3.1c Services og andet programmel SKAL være compliant med DMPs ESB hvis en sådan er [DMP WebService Spec v1.2] 83

84 implementeret a 3.1.3b 3.1.4a Services og andet programmel SKAL kunne afvikles i DMPs driftsmiljø Alle services SKAL implementere en Test funktion 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 a Der SKAL udarbejdes et SLA bilag til kontrakten a 3.1.6b 3.1.6c 3.1.7a 3.1.7b 3.1.7c Fælles datastrukturer specificeret af sektorstandardiseringsudval g SKAL anvendes. (Jf. Regel 2.1a) Relevante generiske services i DMP SKAL anvendes OIOXML NDR i senest gældende version BØR følges. (Link: DMPs fælles sikkerhedssystem SKAL anvendes DMPs IT-sikkerhedspolitik og sikkerhedspolicies SKAL følges DMPs fortolkning af DS484 SKAL overholdes [DMP WebService Spec v1.2] 84

85 3.1.8a 3.1.8b DMPs fælles logningsservice SKAL anvendes. 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 c 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 a Forretningsservices BØR være designet således at det ikke er nødvendigt at anvende batchkørsler b Anvendelse og design af samtlige batchkørsler SKAL være forhåndsgodkendt af DMP a Servicen SKAL anvende standard kommunikationsprotokoller b DMP SKAL forhåndsgodkende de kommunikationsprotokoller, der planlægges at blive anvendt [DMP WebService Spec v1.2] 85

86 3.2a DMPs arkitekturprincipper SKAL følges a 3.2.2b 3.2.2c 3.2.2d 3.2.2e 3.2.3a 3.2.4a 3.2.4b 3.2.4c Et forretningsområde SKAL overholde krav beskrevet i den for DMP gældende version af IT-Arkitektur rammeværk Et forretningsområde SKAL beskrives i den for DMP gældende version af BPMN En service SKAL bygges over en model med udgangspunkt i Forretningsservices og Forretningsobjekter Det BØR altid overvejes om der er behov for at anvende reference til store dataitems. Udstillelse af data via en raw tilgang SKAL i hvert enkelt tilfælde godkendes af DMP. 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. Ved simple transaktioner MÅ Scenarie A benyttes Ved simple transaktioner med viderekald BØR Scenarie B benyttes Ved transaktioner med mere end én commit BØR Scenarie C eller D benyttes [DMP WebService Spec v1.2] 86

87 3.2.5a 3.2.6a DMP s projektmodel skal følges 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 databasen [DMP WebService Spec v1.2] 87

88 3.3a Der SKAL udvikles en Test Client til enhver Web Service. 3.3b Test Client BØR kunne fungere i Produktionsmiljøet 4.1.1a 4.1.2a 4.1.2b 4.2.3a Notation specification in this section MUST be used Timestamps MUST always be stored in UTC Timestamps MUST use the ISO 8601 representation Document/Literal wrapped style SHOULD be used unless there is need for overloading of web methods. When overloading of web methods is required, the Document/Literal MUST be used b 4.2.4a 4.3.1a DMP MUST approve of the selected method SOAP 1.2 MUST be used. The namespace MUST be uniquely identifiable It SHOULD contain version information as part of namespace, by using numbers x.x.x (1.0.0) 4.3.2a 4.3.3a Namespace prefixes MUST follow OIOXML NDR 3.2 rule NMS-2 Endpoint naming MUST follow the format ain area].[sub area].[version]/[name of [DMP WebService Spec v1.2] 88

89 Service] 4.3.4a Namespace naming MUST follow the format "urn:oio:" <organisation> ":" <business area>. [lower businessarea]> ":" <version> a 4.4.1b 4.4.3a 4.4.4a The contract-first approach MUST be used The stable-interface approach SHOULD be used Methods for both xml string and object structure SHOULD be supported The ResultMessage format specified by the ResultMessage XML Schema MUST be used. 4.5a Web services MUST comply with the DMP security system. 4.6a The DMP sample client and server stubs MAY be used 4.6b If DMP has implemented an ESB the service MUST be checked for compatibility with the ESB 4.7.1a 4.7.2a b OIOREST recommendation SHOULD be followed The REST request and response body MUST be using XML The REST request and response body SHOULD have same format as message payload for [DMP WebService Spec v1.2] 89

90 corresponding web services 4.7.3a 4.7.3b 4.7.3c 4.7.5a 4.7.6a 4.7.6b 4.7.6c The REST URIs MUST comply with DMP naming conventions REST Query string parameters MUST be in english REST Query string parameters MUST use ASCII character set and MUST NOT use space REST services MUST use standard HTTP status codes The REST service MUST comply with DMP security Framework Using a REST service MUST be agreed with DMP in each case REST services MUST NOT be used for anything else but READ operations 4.7a REST services MUST be based on a web service according to the standards in this specification 4.8.1a 4.8.1b 4.8.1c The DMP Log Service MUST be used The LogMessage format specified by the LogMessage XML Schema MUST be used. The service MUST log all updates to data and access to sensitive data to the DMP Log Service. [DMP WebService Spec v1.2] 90

91 4.8.1d 4.8.2a 4.8.2b 4.8.2c 4.8.2d The service SHOULD log all other relevant activities to the DMP Log Service A custom Windows Event Log SHOULD be created and named DMP Event Log Naming conventions from Log Service MUST also be followed using the DMP Event Log Application/Service start, shutdown and major errors MUST be logged in the DMP Event Log Other relevant Application/Service events SHOULD be logged in the DMP Event Log a All Errors must be logged in the DMP Logging Service b Applications SHOULD have a Log Level to control the detail level of logging in the DMP Logging Service. The Log Level MUST be configurable with a parameter. 5.2a All Web Services MUST implement a standard IsAlive method with at least the 0 response 5.2b The name of the method (service) MUST be IsAlive and also comply with naming convention from section c The ResultCode and [DMP WebService Spec v1.2] 91

92 ResultMessage MUST reflect the failures found 6.1 All the namespaces used in the Biztalk server applications MUST conform to DMP Namespace Naming Conventions a b 6.1.2c 6.1.3a 6.1.3b 6.1.3c All XML message formats that are exchanged between applications SHOULD be defined with proper namespaces conforming to the OIO standards. If the XML message are designed to carry payload, then the format SHOULD conform to the payload message standards specified in 4.4 All XML messages MAY be designed with suitable XML schemas conforming to OIO NDR 3.2 or later versions All the Xml Schemas required for Biz Talk Server projects MUST be defined confirming to OIO NDR 3.2 or later versions. If the Xml schema definitions are used by multiple BizTalk server projects, then the schemas MUST be placed in a separate project under the Biz Talk Server solution. The XML Schema constructs redefine, include, and import elements SHOULD be used when the schemas for the message formats become too [DMP WebService Spec v1.2] 92

93 large and complex or when the schemas that represent your different types of instance messages have some portions in common a 6.2.2b 6.2.2c 6.2.4a 6.2.4b 6.2.4c 6.3.2a 6.3.2b An assembly MUST NOT be deployed to a Biz Talk Server production environment from Visual Studio A shared web application (for example as a receive location) SHOULD be deployed as a separate application. MSI files MUST be used in order to deploy a Biz Talk Server application to production environment. Suitable exception handling MUST be used in Biz Talk Server Orchestrations. All the calls to the external web services SHOULD be defined in scope shape with proper exception handling. The scope's transaction type property SHOULD be assigned to 'NONE'. If there are receive handlers for HTTP and SOAP adapters with the one single isolated host, then you MUST create two application pools, one application pool for each adapter. For the WCF services published with WCF adapters, the IsOneWay property of the service [DMP WebService Spec v1.2] 93

94 should be set to false. 6.4a The WCF-WSHttp binding type SHOULD be used as a transport type for both Send and Receive ports for communicating (either for consuming or receiving input) with a WCF service, until unless you have special requirements for using Custom bindings. 6.4b The host name instead of localhost SHOULD be used, if clients have to go through the proxy when talking to web services on the same computer. 6.4c Separate host instances for send ports SHOULD be created for the send ports that use different proxy addresses and/or proxy credentials. [DMP WebService Spec v1.2] 94