old.miljoeportal.dkold.miljoeportal.dk/Dokumenter alle/Specifikation af Web Services til... · DMP...

Specifikation af Web Services til

Danmarks Miljø Portal

DMP WebService Spec v1.3 – revideret oktober 2015

Indholdsfortegnelse

Indholdsfortegnelse

1 Generelt ..................................................................................................................................................... 10

1.1 Introduktion ....................................................................................................................................... 10

1.2 Forkortelser og Standarder ................................................................................................................ 10

2 Arkitektur ................................................................................................................................................... 11

2.1 Generelt ............................................................................................................................................. 11

2.2 Principskitse ....................................................................................................................................... 12

2.3 ESB Overvejelser ................................................................................................................................ 12

3 Krav ............................................................................................................................................................ 12

3.1 Krav til løsningen som helhed ............................................................................................................ 12

3.1.1 Governance ................................................................................................................................ 13

3.1.2 Dokumentation .......................................................................................................................... 13

3.1.3 Drift ............................................................................................................................................ 14

3.1.4 Infrastruktur ............................................................................................................................... 14

3.1.5 SLA ............................................................................................................................................. 15

3.1.6 Fælles datastrukturer ................................................................................................................. 15

3.1.7 Fælles sikkerhedssystem ............................................................................................................ 16

3.1.8 Log & Revisionsspor ................................................................................................................... 16

3.1.9 Statistik og Rapporter................................................................................................................. 17

3.1.10 Batchkørsler ............................................................................................................................... 18

3.1.11 Kommunikation ......................................................................................................................... 18

3.1.12 Fejlhåndtering ............................................................................................................................ 19


3.2 Krav til de enkelte systemer............................................................................................................... 20

3.2.1 Struktur ...................................................................................................................................... 20

3.2.3 Forretningsprocesser ................................................................................................................. 20

3.2.4 Primær data lokation .................................................................................................................. 22

3.2.5 Transaktionsstyring ................................................................................................................... 23

3.2.6 Projekt procedure ...................................................................................................................... 26

3.2.7 Dokumentation .......................................................................................................................... 26

3.3 Test .................................................................................................................................................... 29

4 Specifikationer ........................................................................................................................................... 29

4.1 General .............................................................................................................................................. 29

4.1.1 Notation ..................................................................................................................................... 29

4.1.2 Timestamps ............................................................................................................................... 30

4.2 Web Service Interface ........................................................................................................................ 30

4.2.1 Web Service Design Methodologies ........................................................................................... 30

4.2.2 Communication Patterns ........................................................................................................... 31

4.2.3 SOAP Formatting Rules .............................................................................................................. 31

4.2.4 SOAP Protocol ............................................................................................................................ 38

4.3 Naming Conventions .......................................................................................................................... 42

4.3.1 Namespaces ............................................................................................................................... 42

4.3.2 Namespace Prefixes ................................................................................................................... 43

4.3.3 Endpoint naming convention ..................................................................................................... 43

4.3.4 Target namespace naming convention ...................................................................................... 44

4.4 Web Service Payload ......................................................................................................................... 44

4.4.1 Design Principles ........................................................................................................................ 44

4.4.2 XML Message Payload Structure ................................................................................................ 45

4.4.3 Methods for both XML and Object Structures ........................................................................... 48


4.4.4 XML Result Message Structure .................................................................................................. 49

4.5 Web Service Security ......................................................................................................................... 53

4.5.1 Federation ................................................................................................................................. 53

4.5.2 Security Implications on Web Service Development .................................................................. 55

4.5.3 Roles for authorization ............................................................................................................... 56

4.6 Web Service Application .................................................................................................................... 57

4.7 REST support ...................................................................................................................................... 57

4.7.1 Introduction to REST .................................................................................................................. 57

4.7.2 The body of the request ............................................................................................................. 58

4.7.3 URI ............................................................................................................................................. 59

4.7.4 HTTP headers ............................................................................................................................. 60

4.7.5 HTTP status codes ...................................................................................................................... 60

4.7.6 Security ...................................................................................................................................... 60

4.7.7 Limits.......................................................................................................................................... 61

4.7.8 Support for REST in standard platforms ..................................................................................... 61

4.8 Logging ............................................................................................................................................... 62

4.8.1 Log Service ................................................................................................................................. 62

4.8.2 Logging into Windows Event Log ............................................................................................... 63

4.9 Transactions across web services....................................................................................................... 65

4.10 ErrorHandling ..................................................................................................................................... 66

4.10.1 Response Categories .................................................................................................................. 66

4.10.2 Action on Error ............................................................................................................................... 67

5 Test ............................................................................................................................................................ 68

5.1 Test Client .......................................................................................................................................... 68

5.2 Alive Method ..................................................................................................................................... 68

5.3 Compliance Test ................................................................................................................................. 69


5.4 Performance Test ............................................................................................................................... 70

6 BizTalk Server specifikations. ..................................................................................................................... 70

6.1 Naming Conventions .......................................................................................................................... 70

6.1.1 Namespaces ............................................................................................................................... 70

6.1.2 XML Message format ................................................................................................................. 71

6.1.3 XML Schemas ............................................................................................................................. 71

6.2 BizTalk Conventions ........................................................................................................................... 72

6.2.1 BizTalk Folder structure ............................................................................................................. 72

6.2.2 BizTalk Application Deployment ................................................................................................ 72

6.2.3 BizTalk Orchestration ................................................................................................................. 73

6.2.4 BizTalk Orchestration Exeption Handling ................................................................................... 73

6.3 Web Services...................................................................................................................................... 74

6.3.1 Publishing web services.............................................................................................................. 74

6.3.2 Consuming web services ............................................................................................................ 74

6.4 Bindings ............................................................................................................................................. 75

6.5 BizTalk Global Variables ..................................................................................................................... 75

6.6 BizTalk Server ADFS Scenarios ........................................................................................................... 77

6.7 Scenarios ............................................................................................................................................ 78

6.7.1 Scenario A Simple Service .......................................................................................................... 78

6.7.2 Scenario B Service using Claims ................................................................................................. 78

6.7.3 Scenario C Service using standard BizTalk .................................................................................. 78

6.7.4 Scenario D Service using BizTalk and Claims .............................................................................. 79

6.8 Certificates involved .......................................................................................................................... 79

7 Appendix: Reference Documents ............................................................................................................... 79

7.1 DMP navnestandard .......................................................................................................................... 79

7.2 DMP Infrastruktur .............................................................................................................................. 79


7.3 DMP ITArkitektur rammeværk.......................................................................................................... 79

7.4 DMP Arkitektur principper. ............................................................................................................... 79

7.5 DMP Procedurer for tilkobling, deployment, versionering, governance mm .................................... 79

7.7 DMP Fællesdatastrukturer fra sektorstandardiseringsudvalget ........................................................ 80

7.8 DMP Logningsservice ......................................................................................................................... 80

7.9 DMP Standard SLA skabelon ............................................................................................................. 80

7.10 Dokumentations templates ............................................................................................................... 80

7.11 ”Guidelines for DMP Web Service security” (Globeteam) ................................................................ 80

7.12 W3C, OASIS standarder ..................................................................................................................... 80

7.13 Claim enabling of biztalkserver. ........................................................................................................ 83

8 Appendix: Rules collection ........................................................................................................................ 83


Document information

Title: Web Service Specification for Danmarks Miljø Portal

Documenttype Specification

Project: DMP

Documentfolder:

Version 1.3

Revision Date 01 Oktober 2015

Coming into force: 01 Oktober 2015

Author: jbartold – CSC

Contributors: Jens Jakob Nørtved Bork DMP

Approved by: Jens Jakob Nørtved Bork DMP

Activity ID:

Distribute to: DMP, CSC


Change log

Version Date Changed pages or chapters Comments

0.1 29.10.2008 Document initialized

0.2 19.2.2009 Document draft review with DMP

0.3 13.3.2009 Changed from recommendations to specifications

Document draft review with DMP

0.9 20.3.2009 Added several sections

Added rule boxes


0.91 23.4.2009 Many changes Document draft review with DMP

0.92 27.4.2009 Added section on ESB and REST


0.93 4.5.2009 Added rules for Transactions, REST Query string parameters, Web Service message payload


0.94 1.6.2009 Adjustments ESB put in appendix


0.95 3.6.2009 Adjustments on Test and links Document draft review with DMP

0.96 3.8.2009 Adjustments according to hearing answers and added section 4.4.3 plus note on future compliance with namespace naming conventionfrom NDR 3.2


0.97 7.8.2009 Appendix 8 rules collection added. Link to “UDDI” corrected ??? remove


0,98 4.10.2009 NDR 3.2 rules applied Document released

1.0 18.08.2010 Version changed to 1.0


1.1 23.2.2011 BizTalk sections added (BizTalk/ADFS TBD) NDR 4.0 rule compliance checked Text Adjustments Appendix 8 Rules collection NOT updated

1.2 9.5.2011 Appendix Rules collection updated

1.3 01.10.2015 Links updated.

DMP WebService Spec v1.3 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 Danmarks Miljø Portal WSDL Web Services Description Language XML Extensible Markup Language SOAP Simple Object Access Protocol WS* Web Services Standarder WSI Web Services Interoperability http Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol Secure (over SSL) WSSec Web Services Security WSTrust Web Services Trust WSPolicy Web Services Policy WSReliableMessaging Web Services ReliableMessaging WSCommunication Web Services Communication WSTransaction Web Services Transaction OASIS Organization for the Advancement of Structured Information Standards W3C World Wide Web Consortium OIO Offentlig Information Online OIOXML XML for Offentlig Information Online OCES Offentlige Certifikater til Elektronisk Service


SAML Security Assertion Markup Language OWSA model T OIO Web Service Arkitektur model (sikker direkte transport) EA Enterprise Architecture RASP Reliable Asynchronous Secure Profile REST Representational State Transfer ESB Enterprise Service Bus BAM Business Activity Monitoring

2 Arkitektur

2.1 Generelt Der er i Miljøsektoren foretaget sektorstandardisering og hvilket har resulteret i en række dokumenter med standarder herunder navnedokumentet med betegnelser og navngivning for forretningsområder under Danmarks Miljøportal.

Link til DMP navnestandard [7.2]

Link til DMP Arkitekturdokumenter [7.4]

Regel 2.1a

DMP navnestandarder SKAL til enhver tid følges.

Såfremt der ikke er defineret navne for det pågældende område skal DMP kontaktes for at aftale den

navngivning der skal anvendes.


2.2 Principskitse

2.3 ESB Overvejelser Centralt vil miljøet i DMP, hvor forretningsservices skal afvikles enten være med eller uden anvendelse af en ESB. I den forbindelse er der en række overvejelser om måden at konstruere forretningsservices på. Disse overvejelser er placeret i kapitel 6.

3 Krav Overordnet stilles en del krav til DMPs centrale løsning. Disse er karakteriseret ved dels at omfatte specifikke krav til de enkelte systemer dels krav som følge af mangfoldigheden af systemer der samles.

3.1 Krav til løsningen som helhed Målene er bl.a.

1. At tilvejebringe mulighed for at opdatere data, på en måde således den passer ind i brugeren hverdag(forretning). Dette kan være fra et enkelt decentralt fagsystem eller fra flere kilder.

2. At give adgang til interne data for de myndigheder, systemer og personer, der har retmæssig adgang.

3. At give adgang til data for offentligheden, myndigheder og systemer.

4. At standardisere grænseflader, data og procedurer i en grad der både gør det gennemskueligt hvorledes de enkelte systemer skal udvikles og samtidig forenkler de centrale processer.

5. At genbruge fælles services og datastrukturer

6. At muliggøre en fyldestgørende grad af governance for systemet som helhed

Fagsystem Web Service DMP( evt ESB) Databaser


Ad 1. Det er valgt at data udstilles via web services og at al tilgang til data foregår gennem web services.

Ad 2. Interne data(data som ikke er kvalitetsmærket) udstilles kun gennem web services og det er omfattet af en rettighedsmodel til styring af hvem, der har ret til at skrive og læse data. Ad 3. Kvalitetsmærkede data udstilles gennemwebservices.

Ad 4. Det er nødvendigt at følge de til enhver tid gældende procedurer for tilkobling, deployment, versionering, governance etc. Dette kan være håndteret i et central system fx en ESB og/eller centrale custom udviklede komponenter. Et eksempel herpå er logning hvor updates foretages i specifikke formater hvorved applikationer, der efterfølgende skal vise log data forenkles betydeligt.

Ad 5. Der er et meget stort behov for at gøre arkitekturen så enkel, som muligt via genbrug af services og komponenter.

Ad 6. Der vil være er række områder hvor governance bliver et vigtigt område at håndtere. Dette er drevet bl.a. af et behov for at kunne monitorere runtime 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 runtime 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.

3.1.1 Governance Governance omfatter ”lifecycle 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]

3.1.2 Dokumentation For de enkelte services skal dokumentationen følge DMPs dokumentations template hvilket omfatter bl.a.

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


Regel 3.1c

Services og andet programmel SKAL være compliant med DMPs ESB hvis en sådan er implementeret.


• Forretningsmæssig beskrivelser af services • Forretningsobjekter • Usecases • Tekniske beskrivelser af services med wsdl, xml schema mm • Versionering af services • Primær data lokation f.eks. database • Data ejer dvs hvilken myndighed, der er ansvarlig • Custom Log record format med xml schema • Interessenter f.eks. i form af liste over personer og institutioner • Aftalegrundlag som referencer til tekniske og juridiske dokumenter

Jf. iøvrigt afsnit 3.2.6.

3.1.3 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 fejllogin / Intruder detection. (se afsnit 3.1.7)

Følgende emner indgår bl.a. i monitoreringen af driften:

Runtime monitorering: response tid, antal hits, antal failures, tilgængelighed (Uptime ) 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

3.1.4 Infrastruktur Services skal anvende DMP’s fælles infrastruktur med mindre andet er specifikt aftalt. Dette omfatter tillige at følge de gældende standardiserede processer for implementering af softwaren, web services, policies mm.

For yderligere detaljer vedrørende infrastrukturen se [7.3]

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


3.1.5 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 singlepointoffailure.

Der skal være taget stilling til og implementeret den passende og relevante håndtering af redundans og fail over for at kunne honorere de krav (service mål) der er stillet i SLA. Tilsvarende vil dette kunne udnyttes til loadbalancing.

3.1.6 Fælles datastrukturer Der er for centrale dataelementer defineret standardiserede strukturer, specielt de, der skal anvendes og udveksles på tværs af systemer. Fx koordinatbeskrivelse, adresser, generaliseret prøvestedsbeskrivelse o.l. Disse datastrukturer skal anvendes og standarder skal overholdes. Derudover kan der for sektorspecifikke elementer være defineret tilsvarende standarder.

For ikke definerede områder kan det være nødvendigt for den givne service at definere yderligere datastrukturer. Det skal i så fald i hvert enkelt tilfælde først undersøges om der eksisterer centrale definitioner eller sektor (domænespecifikke) definitioner og i så fald skal de anvendes. Hvis dette ikke er tilfældet skal det undersøges om det er relevant at få datastrukturerne defineret på centralt eller sektor niveau med de procedurer, der hører til dette. Såfremt dette ikke skønnes nødvendigt fx fordi der er tale om interne definitioner for den enkelte service skal der alligevel defineres som om der var tale om strukturer på sektorniveau dvs at fx navnekonventioner og xml schema overholder fx OIOXML NDR og laves i den ånd, der er beskrevet heri og i øvrigt fremgår af andre DMP definerede xml schemaer.

OIOXML NDR

Fællesdatastrukturer kan findes hos sektorstandardiseringsudvalget [7.7]

DMPs arkitekturprincipper kan rekvireres hos DMP.

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.

Regel 3.1.5a

Der SKAL udarbejdes et SLA bilag til kontrakten.


http://www.digst.dk/Arkitektur-og-standarder/Standardisering/Datastandardisering/Saadan-laver-du-OIOXML/Overhold-reglerne-NDR


De til enhver tid gældende services vil være udstillet via DMPs UDDI (Link: http://ww w.mil joeportal .dk/dig i tal /Digi tal_w ebs ervices/Sider/Webserv iceProdukt ion.as px)

3.1.7 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å http://wiki.miljoeportal.dk/display/brugerstyring/Brugerstyring+hjemmeside 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.

3.1.8 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 servicekaldene 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

Regel 3.1.6a

Fælles datastrukturer specificeret af sektorstandardiseringsudvalg SKAL anvendes. (Jf. Regel 2.1a)

Regel 3.1.6b

Relevante generiske services i DMP SKAL anvendes

Regel 3.1.6c

OIOXML NDR i senest gældende version BØR følges. (Link: NDR DIGST)

Regel 3.1.7a

DMPs fælles sikkerhedssystem SKAL anvendes

Regel 3.1.7b

DMPs IT‐sikkerhedspolitik og sikkerhedspolicies SKAL følges

Regel 3.1.7c

DMPs fortolkning af DS484/ISO27001 SKAL overholdes

http://www.miljoeportal.dk/digital/Digital_webservices/Sider/Webservice---Produktion.aspx

http://wiki.miljoeportal.dk/display/brugerstyring/Brugerstyring%2Bhjemmeside

http://wiki.miljoeportal.dk/display/brugerstyring/Brugerstyring%2Bhjemmeside

http://www.digst.dk/%7E/media/Files/Arkitektur-og-standarder/Datastandardisering/OIOXML/NDR32.pdf


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.

3.1.9 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 builtin 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 Anvendelsesstatistik

o Afregninger

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


• Drift

o Tilgængelighedsmåling

o Identifikation af peak perioder

o Kapacitet vs Belastning Beregninger

o Fejl

• Sikkerhed

o Intrusion log

3.1.10 Batchkørsler Der kan i enkelte tilfælde være behov for batchkørsler til større udtræk eller opdateringer af data mellem systemer og databaser indbyrdes.

Batchkø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 builtin features i databasen. Herved undgås at skulle serialisere og evt streame store datamængder.

3.1.11 Kommunikation Kommunikationen mellem decentrale fagapplikationer og centrale services foregår via HTTPS og eventuelt via VPN opkoblinger.

Regel 3.1.10a

Forretningsservices BØR være designet således at det ikke er nødvendigt at anvende batchkørsler

Regel 3.1.10b

Anvendelse og design af samtlige batchkørsler SKAL være altid forhåndsgodkendt af DMP.


3.1.12 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/responseprotokol som fx SOAP/HTTPS kan man underopdele de mulige udfald i 4 forskellige kategorier, som er gennemgået nedenfor.

3.1.12.1 Resultresponsereceived 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.

3.1.12.2 Faultresponsereceived 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 rolledback.

3.1.12.3 Noresponsereceived Client modtager intet svar fra Web Service, men får sikkert en fejl genereret af kommunikationsframewor ket 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 rollback. 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.

3.1.12.4 Clienthascrashed 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.

3.1.12.5 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 (0n 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 errorkø, overlade til drift at tage sig af fejlen etc.

Se I øvrigt afsnit 4.10

Regel 3.1.11a

Servicen SKAL anvende standard kommunikationsprotokoller

Regel 3.1.11b

DMP SKAL forhåndsgodkende de kommunikationsprotokoller, der planlægges at blive anvendt


3.2 Krav til de enkelte systemer

3.2.1 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. 3.2.2 Forretningsservices.

En forretningsservice er primært vendt mod eksterne modtagere – borgere, private virksomheder og andre offentlige organisationer. Man kan dog godt have interne forretningsservices – et direktorat der leverer services til fx departementet, eller services rettet mod den enkelte ansatte. En forretningstjeneste bør i sin yderste konsekvens forstås som en logisk størrelse, der fastlægger den totale mængde forretningsobjekter, relationer og de processer der påvirker disse. Det den udveksler med omverdenen er forretningsservices. En forretningstjeneste forvalter et eller flere forretningsobjekter. Det er helt afgørende, at tjenesten stiller sin funktionalitet til rådighed for andre. Det kan den gøre via logiske interfaces for dialog eller systemer. Det er vigtigt at forretningsservices beskrives teknologiuafhængigt. En forretningstjeneste kan implementeres på mange måder og i mange forskellige instanser. Der vil også være behov for at holde data i de forskellige implementeringer nogenlunde synkrone. Det er derfor meget nemmere at foretage udvekslinger af ensartede data, hvis de forskellige implementeringer har taget udgangspunkt i den samme forretningstjeneste.

For at dokumentere hvilke foretningsservices der understøttes skal der henvises til eksisterende forretningsservices eller udarbejdes nye.

3.2.3 Forretningsprocesser Et basalt princip er anvendelsen af forretningsobjekter. Når et givet fagområde/system skal implementeres analyseres forretningsområdet for at identificere de data strukturer, interessenter, forretningsprocesser og use cases der indgår. Ud fra dette fastlægges forretningsobjekter (datastrukturer) og de funktioner, der er nødvendige for at kunne understøtte forretnings processerne.

For at dokumentere og give et overblik over et givet forretningsområde skal , processer, states, aktører, swimlanes, objekter, input og output mm for beskrives i en standard notation BPMN.

Funktioner vil typisk omfatte:

1. Create

2. Read

3. Update

Regel 3.2a

DMPs arkitekturprincipper SKAL følges.

Kan rekvireres hos DMP.


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


detaljer om dette element (drilldown). 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 rollback) 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.

3.2.4 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

Regel 3.2.2a Der skal henvises til eksisterende forretningservices eller udarbejdes nye. Skabelon kan rekvireres hos DMP. Regel 3.2.2b

Et forretningsområde SKAL overholde krav beskrevet i den for DMP gældende version af IT‐Arkitektur

rammeværk jf. [7.4]

Regel 3.2.2c

Et forretningsområde SKAL beskrives i den for DMP gældende version af BPMN(p.t. v1.2)

Regel 3.2.2d

En service SKAL bygges over en model med udgangspunkt i Forretningsservices og Forretningsobjekter.

Regel 3.2.2e

En service KAN understøtte flere forretningsobjekter.

Regel 3.2.2f

Det BØR altid overvejes om der er behov for at anvende reference til store data‐items.

Regel 3.2.2g


embedded i databasen, med mindre det af performancemæssige grunde er nødvendigt. I stedet bør det placeres i koden, der understøtter web servicen. Det er intentionen at forretningslogikken er placeret i et forretningslag og at applikationer, der anvender web service (forretningsservicen) IKKE behøver at kende

lagringsstrukturen i det underliggende data lag. Således skal der anvendes forretningsobjekter og ikke blot direkte adgang til tabeller, hvorved det fx efterlader applikationen med ansvaret for data integritet.

Anvendelse af stored procedures skal således ses som en mulig del af data access laget, men ikke som et sted at placere forretningslogik. En vis sammenhæng mellem lagene vil der altid være og vurderingen er tillige påvirket af hvilket kodningssprog, man er nødt til at vælge samt hvor meget database lockin, 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.

3.2.5 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 ”rollback” 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 WSAtomicTransaction 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 deltransaktioner og foretage rollback hvis det er nødvendigt.

Scenarie D viser den samme situation, men her har man ”erkendt” at der er et behov for at kunne

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.


foretage indbyrdes afhængige opdateringer på tværs af databaser og har derfor defineret en forretningsservice, der på traditionel vis håndterer transaktionen med opdatering i Database 1 og Database 2. Dette er implementeret i een ”almindelig” web service og baserer sig ikke på anvendelse af protokol framework for at styre sit transaction scope. Den kalder heller ikke andre web services for at løse opgaven.

Det skal i hver enkel situation overvejes, hvilken tilgang til transaktionstyring på tværs af databaser, der som udgangspunkt er udstillet via web services, der skal vælges. Det kan i nogle tilfælde være et ”følsomt” emne at afgøre hvem, der skal ”eje” den fælles webservice, der skal implementere tilgangen til flere databaser på tværs af f.eks. myndighedsgrænser.

Ovenstående gælder specielt for opdateringer af databaser, men overvejelserne om definition af en forretningsservice på tværs af databaser (fagområder) kan tillige være relevant for læsninger omend der her ikke er behov for transaktionsstyring, hvilket forsimpler situationen betydeligt.

Se iøvrigt afsnit 4.9

Scenario A Simple Transaction

Client Web Service Database

Scenario B WS‐AtomicTransaction

Client

Scenario C WS‐AtomicTransaction + WS‐Coordination Transaction Coordinator

Client

Scenario D Coding using “traditional” Transaction Scope (not based on protocol framework)

Web Service

Web Service 1

Database 1

Client

Database 2

Web Service 2

[DMP WebService Spec v1.2] 24

Web Service 1

Web Service 2 Database 2

Database 1




Principskitse

3.2.6 Projekt procedure Overordnet bør et projekt minimum have tre faser defineret:

1. Preprojekt

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, compliancetest, dokumentation etc.

3.2.7 Dokumentation Alle komponenter skal være dokumenteret til et niveau, der opfylder visse minimumskrav.

1. web services

2. sikkerhed

3. Forretningsprocesser

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

Regel 3.2.5a

DMPs projektmodel SKAL følges Regel 3.2.5b DMP’s release proces skal følges.


4. Konceptuelle datamodeller

Der er udarbejdet en dokumentationstemplate jf. [7.10] samt indeholdt i DMPs arkitektur rammeværk bygget på OIO EA metoden jf. [7.4].

Ad 1. Web Services beskrives med WSDL og message payload med XML Schema.

Ad 2. sikkerhedsprofiler fx RASP

Ad 3. Forretningsprocesser beskrives i tekst og med use cases. Funktioner beskrives jf. wsdl og i tekst. Forretningsobjekter beskrives i tekst med angivelse af attributter og relationer. Ad 4. Datastrukturer beskrives i konceptuelle datamodeller.

I alle tilfælde skal der minimum være en kort beskrivelse af de enkelte områder for at supplere de tekniske dokumenter i et ”almindeligt sprog” for at give et hurtigt overblik. Derudover skal fx semantikken i de enkelte funktioner mm dokumenteres, hvilket typisk ikke fremgår i tilstrækkelig grad af de øvrige dokumenter.

Der kan være forskellige niveauer af dokumentation nødvendig på forskellige stadier af udviklingen. Fx design og initiel godkendelse af et projekt versus dokumentation ved release og deployment af services.

Se i øvrigt dokumentations template [7.10]


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.

Regel 3.2.6a

Den af DMP specificerede dokumentations template SKAL (som minimum) benyttes til dokumentation jf.

[7.10]

Regel 3.2.6b

Deliverables:

Enhver web services SKAL som minimum levere følgende dokumenter, filer mm:

‐ Install filer for Web Service herunder

‐ WSDL

‐ XML Schemaer for Message Payload for Requests og Responses

‐ Dokumentation af configuration filer (fx .config)

‐ Install filer for Test Client

‐ Install filer for andre komponenter

‐ Database relaterede filer herunde

‐ Scripts til create og/eller updates af databaser

‐ Stored Procedures mm

‐ ER diagrammer

‐ Dokumentation af security elementer (fx users and access rights) i database

Regel 3.2.6c

Alt documentation og kilde kode skal lægges i DMPS’s TFS (miljoeportal.visualstudio.com)


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.

4 Specifikationer

4.1 General Der tages udgangspunkt i den af MVTU definerede OIO standard for interoperabilitet af web services (OWSAT).

Uddrag af OWSAT 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 kontraktfø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.

4.1.1 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 2119.

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.

Regel 3.3a

Der SKAL udvikles en Test Client til enhver Web Service.

Regel 3.3b

Test Client BØR også kunne fungere i Produktionsmiljøet


CamelCase and the ”object approach” are used for the names, variables attributes etc.

4.1.2 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:

refer to http://www.w3.org/TR/NOTEdatetime for details.

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

4.2.1 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

Regel 4.1.1a

Notation specification in this section MUST be used

<dmp:Timestamp>2009-03-11T23:56:00</dmp:Timestamp>

Regel 4.1.2a

Timestamps MUST always be stored in UTC

Regel 4.1.2b

Timestamps MUST use the ISO 8601 representation

http://www.w3.org/TR/NOTE-datetime


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 (oneway 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.

4.2.3 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.

http://www.w3.org/TR/xmlschema-1/


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 Available Options

Communication Patterns Remote Procedure Call or Oneway messaging Style Document or RPC Use 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 (WSI) has a clear preference. In practice, only Document/Literal and RPC/Encoded combinations have got vide acceptance.

4.2.3.1 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 RPCstyle 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="http://schemas.xmlsoap.org/soap/http"/> <wsdl:operation name="UploadDMPMessage">

<soap:operation soapAction="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/U ploadDMPMessage"

style="document" /> <wsdl:input>

<soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>

</wsdl:input> <wsdl:output>

<soap:body use="encoded" encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>

</wsdl:output> </wsdl:operation>

</wsdl:binding>

http://schemas.xmlsoap.org/soap/http

http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/U

http://schemas.xmlsoap.org/soap/encoding/



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 wellknown remoteprocedurecall 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 inmemory. • It is not supported by the Web Services Interoperability Organization as a conformance standard.

4.2.3.2 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="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"

xmlns:tns="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/"

xmlns:s="http://www.w3.org/2001/XMLSchema"

http://schemas.xmlsoap.org/wsdl/soap/

http://microsoft.com/wsdl/mime/textMatching/


http://schemas.xmlsoap.org/wsdl/mime/

http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/

http://www.w3.org/2001/XMLSchema


xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"

targetNamespace="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03 /01/"

<wsdl:types>

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

<s:schema elementFormDefault="qualified"

targetNamespace="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03 /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="http://schemas.xmlsoap.org/soap/http" /> <wsdl:operation name="UploadDMPMessage">


<wsdl:input>

style="document" />

<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="http://schemas.xmlsoap.org/soap/http" /> <wsdl:operation name="UploadDMPMessage">

<soap12:operation soapAction="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/U ploadDMPMessage"

<wsdl:input>

style="document" />

<soap12:body use="literal" /> </wsdl:input>

http://schemas.xmlsoap.org/wsdl/soap12/

http://schemas.xmlsoap.org/wsdl/http/

http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03

http://schemas.xmlsoap.org/wsdl/







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

<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="http://localhost/DMPMessage/WcfSampleService/DMPMessageUploadService.A SMX" />

</wsdl:port> <wsdl:port name="DMPMessageUploadServiceSoap12"

binding="tns:DMPMessageUploadServiceSoap12"> <soap12:address

location="http://localhost/DMPMessage/WcfSampleService/DMPMessageUploadService.A SMX" />

</wsdl:port> </wsdl:service>

</wsdl:definitions>

POST /DMPMessage/WcfSampleService/DMPMessageUploadService.ASMX HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/UploadDMPMes sage" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body> <messageXml

xmlns="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/">stri ng</messageXml>

</soap:Body> </soap:Envelope>

http://localhost/DMPMessage/WcfSampleService/DMPMessageUploadService.A


http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/UploadDMPMes


http://www.w3.org/2001/XMLSchema-instance


http://schemas.xmlsoap.org/soap/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.

4.2.3.3 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.

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="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body> <messageXml

xmlns="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/">stri ng</messageXml>

</soap12:Body> </soap12:Envelope>



http://www.w3.org/2003/05/soap-envelope



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="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:tm="http://microsoft.com/wsdl/mime/textMatching/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"

xmlns:tns="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/" xmlns:s="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/"

targetNamespace="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03 /01/"

<wsdl:types>

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

<s:schema elementFormDefault="qualified"

targetNamespace="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03 /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" />


http://microsoft.com/wsdl/mime/textMatching/


http://schemas.xmlsoap.org/wsdl/mime/




http://schemas.xmlsoap.org/wsdl/http/


http://schemas.xmlsoap.org/wsdl/



<wsdl:output message="tns:UploadDMPMessageSoapOut" /> </wsdl:operation>

</wsdl:portType> <wsdl:binding name="DMPMessageUploadServiceSoap"

type="tns:DMPMessageUploadServiceSoap"> <soap:binding transport="http://schemas.xmlsoap.org/soap/http" /> <wsdl:operation name="UploadDMPMessage">


<wsdl:input>

style="document" />


<soap:body use="literal" /> </wsdl:output>

</wsdl:operation> </wsdl:binding> <wsdl:binding name="DMPMessageUploadServiceSoap12"

type="tns:DMPMessageUploadServiceSoap"> <soap12:binding transport="http://schemas.xmlsoap.org/soap/http" /> <wsdl:operation name="UploadDMPMessage">

<soap12:operation soapAction="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/U ploadDMPMessage"

<wsdl:input>

style="document" />

<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="http://localhost/DMPMessage/WcfSampleService/DMPMessageUploadService.A SMX" />

</wsdl:port> <wsdl:port name="DMPMessageUploadServiceSoap12"

binding="tns:DMPMessageUploadServiceSoap12"> <soap12:address

location="http://localhost/DMPMessage/WcfSampleService/DMPMessageUploadService.A SMX" />

</wsdl:port> </wsdl:service>

</wsdl:definitions>


POST /DMPMessage/WcfSampleService/DMPMessageUploadService.ASMX HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length









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.

4.2.3.4 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

SOAPAction: "http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/UploadDMPMes sage" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"


<soap:Body> <UploadDMPMessage

xmlns="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/"> <messageXml>string</messageXml>

</UploadDMPMessage> </soap:Body>

</soap:Envelope>

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="http://www.w3.org/2001/XMLSchema-instance"


<soap12:Body> <UploadDMPMessage


</UploadDMPMessage> </soap12:Body>

</soap12:Envelope>












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.

4.2.4 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 widescale 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.

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


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 Details SOAP 1.1 Namespace Details:

• Namespace URI: http://schemas.xmlsoap.org/wsdl/soap/ • Envelope Namespace URI: http://schemas.xmlsoap.org/soap/envelope/ • Encoding Namespace URI: http://schemas.xmlsoap.org/soap/encoding/ References • Specification: http://www.w3.org/TR/2000/NOTESOAP20000508/

SOAP 1.2 Namespace Details: • Namespace URI: http://schemas.xmlsoap.org/wsdl/soap12/ • Envelope Namespace URI: http://www.w3.org/2002/12/soapenvelope/ • Encoding Namespace URI: http://www.w3.org/2003/05/soapencoding References • SOAP Version 1.2 Part 0: Primer: http://www.w3.org/TR/soap12part0/ • SOAP Version 1.2 Part 1: Messaging Framework: http://www.w3.org/TR/soap12part1/ • SOAP Version 1.2 Part 2: Adjuncts: http://www.w3.org/TR/soap12part2/

The following are the sample formats for Request and Response for SOAP version 1.1 and 1.2.


SOAP 1.1 Response Format

POST /DPMMessage/WcfSampleService/DMPMessageUploadService.asmx HTTP/1.1 Host: localhost Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/UploadDMPMes sage" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"


<soap:Body> <UploadDMPMessage


</UploadDMPMessage> </soap:Body>

</soap:Envelope>

HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"




http://www.w3.org/TR/2000/NOTE-SOAP-20000508/


http://www.w3.org/2002/12/soap-envelope/

http://www.w3.org/2003/05/soap-encoding

http://www.w3.org/TR/soap12-part0/













SOAP 1.2 Response Format

4.2.4.1 Comparison between SOAP 1.1 and SOAP 1.2

1. 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.

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <UploadDMPMessageResponse

xmlns="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/"> <UploadDMPMessageResult>string</UploadDMPMessageResult>

</UploadDMPMessageResponse> </soap:Body>

</soap:Envelope>

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="http://www.w3.org/2001/XMLSchema-instance"


<soap12:Body> <UploadDMPMessage


</UploadDMPMessage> </soap12:Body>

</soap12:Envelope>

HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"


<soap12:Body> <UploadDMPMessageResponse xmlns="

http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/"> <UploadDMPMessageResult>string</UploadDMPMessageResult>

</UploadDMPMessageResponse> </soap12:Body>

</soap12:Envelope>












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.

4.2.4.2 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.

4.2.4.3 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="http://schemas.xmlsoap.org/soap/http" />

<wsdl:operation name="UploadDMPMessage"> <soap:operation

soapAction="http://rep.oio.dk/miljoeportal.dk/xml/service/namespace/2009/03/01/U ploadDMPMessage"

style="document" /> <wsdl:input>


<soap:body use="literal" />




4.3 Naming Conventions

4.3.1 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:

http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss wssecurity-secext-1.0.xsd

http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss 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: NMS2] "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)

http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss

http://www.docs.oasis-open.org/wss/2004/01/oasis-200401-wss


http://rep.oio.dk/


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:1.0.0

4.3.2 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) http://rep.oio.dk/miljoeportal.dk/xml/schemas/2009/02/01/ and http://rep.oio.dk/miljoeportal.dk/xml/schemas/2009/03/01/, then the suitable namespace prefixes could be similar to miljoeportal1/miljoeportal2 or miljoeportal0201/miljoportal0301.

4.3.3 Endpoint naming convention The Endpoint has a naming convention defined in the string below:

where

Regel 4.3.2a

Namespace prefixes MUST follow OIOXML NDR 3.2 rule NMS-2

Regel 4.3.3a

Endpoint naming MUST follow the format

http://xxxhost/miljoeportal.[main area].[sub area].[version]/[Name of Service]

http://rep.oio.dk/miljoeportal.dk/xml/schemas/2009/02/01/

http://rep.oio.dk/miljoeportal.dk/xml/schemas/2009/03/01/

http://xxxhost/miljoeportal


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 “1.0.0”

and the services on that interface are described using

[Name Of Service] mandatory some preferably selfexplanatory name

The [version] in the Interface name is used to enable several versions of the same service (interface) coexit on the same machine in order to be backward compatible until the old services are phasedout and removed.

Ex: http://xxxhost/miljoeportal.surface.sea.1.0.0/nameofservice

4.3.4 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.

For example the following namespace definition is perfectly valid for using as target namespace.

urn:oio:miljoeportal:nature.samples:1.0.0

4.4 Web Service Payload

4.4.1 Design Principles

Regel 4.3.4a

Namespace naming MUST follow the format

"urn:oio:" <organisation> ":" <business area>”.”[lower businessarea]> ":" <version>.

only small letters(az),’:’ and numbers can be used in the value for <organisation> and <business area>

Regel 4.4.1a

The “contract‐first” approach MUST be used

Regel 4.4.1b

The “stable‐interface” approach SHOULD be used

http://xxxhost/miljoeportal.surface.sea.v1/nameofservice


4.4.1.1 Contractfirst Note that the web services are defined in a “contractfirst” 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.

4.4.1.2 Stableinterface 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 reinsert) various xml elements from the file before it can be inserted as (inner) xml in the overall Message Payload xml.

4.4.2 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

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" ?>  <schema

xmlns:dmp="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/" version="1.0" xmlns="http://www.w3.org/2001/XMLSchema"> <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"

http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/


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"/>


<complexType name="MessageBodyType"> <annotation>

<documentation>The xml message body specific for each service under DMP</documentation>


<any minOccurs="1" processContents="skip" maxOccurs="unbounded"/>


<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>

The following listing shows a sample payload xml conforming to the schema specified in the above listing.

Sample Message Payload Xml

4.4.3 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

</schema>

<?xml version="1.0" encoding="utf-8"?>  <Message xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/ DMPMessagePayload.xsd"

xmlns="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/"> <MessageHeader>

<SectorName>DMP sector 1</SectorName> <UnitName>Ground water</UnitName> <ServiceName>Sample test webservice</ServiceName> <MessageType>DMPUploadMessage</MessageType>

</MessageHeader> <MessageBody>

 <temp>data</temp> <temp>data</temp> <temp>data</temp>

</MessageBody> </Message>


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.

4.4.4 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

Regel 4.4.3a

Methods for both xml string and object structure SHOULD be supported

http://www.w3.org/TR/soap12-part1/%23soapfault

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 selfexplanatory 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" ?>  <schema

xmlns:dmp="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/" attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/" version="1.0" xmlns="http://www.w3.org/2001/XMLSchema">

<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>


<element minOccurs="1"

maxOccurs="1" name="ResultCode" type="integer" >

<annotation>

<documentation> The ResultCode indicates the result of the web service call.


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).


</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).


</element>


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="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/"> <dmp:ResultCode>-1</dmp:ResultCode> <dmp:ResultReason>Failed to connect to the database!</dmp:ResultReason> <dmp:ResultDetail>

SqlException (0x80131904): 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

</sequence>

</complexType> </schema>



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)

Refer also to section 4.10 for more on Error Handling

4.5 Web Service Security

4.5.1 Federation A Federation is a collection of ”realms” (security domains) having established connections to share resources in a secure way. En resourceprovider (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 resourceprovider aka the Relying Party. See diagram below.

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>

<?xml version="1.0" encoding="utf-8"?> <dmp:ResultMessage xmlns:dmp="http://rep.oio.dk/dmp.dk/xml/schemas/2009/03/01/"> <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.



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 WSTrust 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 namevalue 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=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

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 (claimsaware) web service to authorize access to various resources.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name


4.5.2 Security Implications on Web Service Development The security system is divided in several parts:

• Authentication

• Authorization

• Confidentiality

• Integrity

• NonRepudiation

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 NonRepudiation 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)


4.5.3 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 (Basisrolle) 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]

Standardization related to security

STS

Web Service Specification

Client (Requestor)

Web Service (Resource Provider)

Spec Spec

SpecSpec

Web Service Specification (This document)

Standards from Organizations (W3C, OASIS, …)


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]

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 crossfunctional 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

4.7 REST support

4.7.1 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 http://www.json.org/ 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.

Regel 4.5a

Web services MUST comply with the DMP security system.

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

http://www.json.org/


• 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:

http://myservice/busroutes/{RouteNumber}/{date}/

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.

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.

4.7.2 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>2009-05-01</Date>

<DepotDepartures>

<DepotDeparture>

Regel 4.7.1a

OIOREST recommendation SHOULD be followed

http://myservice/busroutes/


<Driver>http://busservice/drivers/martinjakobsen/</Driver>

<DepatureTime>05:35:00</DepatureTime>

</DepotDeparture>

<DepotDeparture>

<Driver>http://busservice/drivers/liselarson/</Driver>

<DepatureTime>08:35:00</DepatureTime>

</DepotDeparture>

</DepotDepartures>

</BusRoute>

4.7.3 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:

http://myservice/busroutes/A370/20090501/DepotDeparture/?Driver= liselarson

Or get update Lise’s driver details by sending a HTTP PUT to:

http://busservice/drivers/liselarson/

DMP has a naming convention for URIs which include all REST services:

http://miljoe.dk/{area}/[{subarea}]/[ServiceSpecific]

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

http://busservice/drivers/martinjakobsen/


http://myservice/busroutes/A370/20090501/DepotDeparture/?Driver


http://miljoe.dk/


4.7.4 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.

• “ContentType” defines the character encoding to be used in the response. • “AcceptEncoding” can define what format the body is in.

4.7.5 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.

4.7.6 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.

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

Regel 4.7.5a

REST services MUST use standard HTTP status codes


REST is currently NOT supported by the DMP security framework! This means that only ReadOnly services for specific areas with nonsensitive data are possible since DMP has allowed these services to be presented for anonymous users.

4.7.7 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.

4.7.8 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 builtin tools.

WCF includes several different object serializers outofthebox 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:

http://myservice/busroutes/{route}/{date}/DepotDeparture/?Driver= {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

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

http://myservice/busroutes/


{

[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.

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 builtin ESB logs.

Any service must be implemented in such a way that flooding of the Log is prevented in case of a persistent failure.

4.8.1 Log Service Basically the Log service is logging Who does What and When and may be used as an Audit Trail (“revisonsspor”), for TrackAndTrace, 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

Regel 4.7a

REST services MUST be based on a web service according to the standards in this specification


• 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 3.1.8 for more details on this.

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]

4.8.2 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,

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.1d

The service SHOULD log all other relevant activities to the DMP Log Service.


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.


• Event Type: Based on the nature of the event, one of the predefined windows event types (listed above) should used.

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 thirdparty 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 (WSCoordination) defines specific coordination types for:

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”


• Short duration, ACID transactions (WSAtomicTransaction)

• Longer running business transactions (WSBusinessActivity)

WS‐AtomicTransaction

This specification provides the definition of the atomic transaction coordination type that is to be used with the extensible coordination framework described in the WSCoordination specification. The specification defines three specific agreement coordination protocols for the atomic transaction coordination type: completion, volatile twophase commit, and durable twophase commit. Developers can use any or all of these protocols when building applications that require consistent agreement on the outcome of short lived distributed activities that have the allornothing 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 WSCoordination 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 longrunning distributed activities.

Microsoft Windows Communication Foundation supports WSAtomic Transactions and also IBM has support.

Refer also to section 3.2.4.

4.10 ErrorHandling Refer to section 3.1.12.

4.10.1 Response Categories As described in section 3.1.12 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/responseprotokol like SOAP/HTTPS:

4.10.1.1 Resultresponsereceived 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)


“negative integer” indicating unsuccessful completion

4.10.1.2 Faultresponsereceived 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 rolledback. This may be considered a “special case” of the Resultresponsereceived as described above. The fault is indicated be the ResponseCode being negative.

4.10.1.3 Noresponsereceived 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 rolledback. 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.

4.10.1.4 Clienthascrashed 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.

4.10.2 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 4.4.4 for more on Result structure and error codes

Refder to section 4.8 for more on Logging errors in the Windows Event Log

Regel 4.10.2a

All Errors MUST be logged in the DMP Logging Service

Regel 4.10.2b

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.

Regel 4.10.2c

All Errors MUST be logged in the DMP eventlog


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 4.4.2 and 4.4.4.


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 4.4.4 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 indepth 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.

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.

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

4.3.3

Regel 5.2c

The ResultCode and ResultMessage MUST reflect the failures found


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 predefined 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

6.1.1 Namespaces


6.1.2 XML Message format

6.1.3 XML Schemas

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”

Regel 6.1

All the namespaces used in the Biztalk server applications MUST conform to DMP Namespace Naming

Conventions 4.3.1.

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

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.


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

6.2.1 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

6.2.2 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.

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.

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.

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.


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.

6.2.3 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 ebusiness 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.

6.2.4 BizTalk Orchestration Exeption Handling

An effective exception strategy will simplify troubleshooting, and allow delegation of troubleshooting to nonadministrators. Exceptions in BizTalk orchestration are handled using a 'scope' shape.

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.

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.

Regel 6.2.4a

Suitable exception handling MUST be used in Biz Talk Server Orchestrations.

Regel 6.2.4b

All the calls to the external web services SHOULD be defined in scope shape with proper exception handling.

Regel 6.2.4c

The scope's transaction type property SHOULD be assigned to 'NONE'.


6.3 Web Services BizTalk Server provides builtin 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.

6.3.1 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 inprocess 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.

6.3.2 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 highavailability 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.

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.

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.


6.4 Bindings You can use the WCFWSHttp adapter to do crosscomputer 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.

The proxy setting for the WCFWSHttp (and also WCFBasicHttp) 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 WCFWSHttp (and also WCFBasicHttp) send ports always ignore the proxy if the service address begins with http://localhost whether the proxy is configured on the Proxy tab of the send port or the Proxy tab of the send handler.

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

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.

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.

http://localhost/


This will enable easy maintenance and also removes the overhead of scripting the registry settings for global variables.

Regel 6.5

For simple Biz Talk server applications, the global variable SHOULD be stored in configuration files

(BTSNTSvc.exe.config).


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

1

3

4

Scenario C Service using standard BizTalk Client

1

Publish BizTalk Web Service

1C0onsume 2

3

4

Scenario D Service using BizTalk and Claims (To Be verified)

Secure Token Server

2

Client 1

4a ?

3 Publish

4b

BizTalk Consume

Web Service

4 5

6 7


6.7 Scenarios

6.7.1 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

6.7.2 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

6.7.3 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.


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)

6.7.4 Scenario D Service using BizTalk and Claims Se pkt. 8.13

6.8 Certificates involved 1. STS server certificate

2. Client certificate

3. Web service certificate

7 Appendix: Reference Documents

7.1 DMP navnestandard Under udarbejdelse

7.2 DMP Infrastruktur Under udarbejdelse

7.3 DMP ITArkitektur rammeværk. Udleveres af DMP 7.4 DMP Arkitektur principper. Udleveres af DMP

7.5 DMP Procedurer for tilkobling, deployment, versionering, governance mm Under udarbejdelse

7.6 DMP Rollebeskrivelser http://www.miljoeportal.dk/inddatering_data/brugeradministration/Sider/brugeradministratorer.aspx


7.7 DMP Fællesdatastrukturer fra sektorstandardiseringsudvalget Der henvises til de fælles grundbegreber.

7.8 DMP Logningsservice Udleveres af DMP

7.9 DMP Standard SLA skabelon Under udarbejdelse

7.10 Dokumentations templates http://dmp.miljoeportal.dk/extranet/fagomraader/tvaergaaende/itarkitektur/SitePages/Startside.aspx

7.11 ”Guidelines for DMP Web Service security” (Globeteam) https://faq.miljoeportal.dk/viewtopic.php?f=29&t=19

7.12 W3C, OASIS standarder Extract from OIOXML NDR

NDR

Rule Id Rule Remarks

OIO: OIOXML Modelling Rules OIO1 Existing elements or types belonging to the OIOXML

Core Components and OIOXML Domain Components classes MUST be reused.

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).

GXS: General XML Schema Rules GXS1 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 .

GXS2 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

XML version

http://dmp.miljoeportal.dk/extranet/fagomraader/tvaergaaende/itarkitektur/SitePages/Startside.aspx

https://faq.miljoeportal.dk/viewtopic.php?f=29&t=19


Edition) . GXS3 All XML schemas MUST use UTF8 as XML encoding

scheme. Choice of XML encoding scheme

GXS4 All XML schemas MUST be assigned a namespace. Namespace assignment GXS5 The include construct MUST be used when referring to a

schema module under the same namespace. Otherwise the import construct MUST be used.

The use of include and import

GXS8 All schemaLocation attributtes MUST be specified with an absolute and valid URL that identifies the location of the referred schema module in the Infostructurebase.

The use of schemaLocation

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.

Naming in English

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.

Unique naming

GNR3 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).

Singular form of nouns

GNR4 Element and attributtes MUST be named using UpperCamelCase.

The use of UpperCamelCase naming convention.

GNR5 Abbreviations and acronyms SHOULD NOT be used in names.

Use of Abbreviations and acronyms.

GNR7 Underscore (_), period (.), and hyphen () MUST NOT be used in names.

The use of characters in names.

GNR8d 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.

Naming rules for complex types.

TPN: Type Naming Rules TPN1 The name of a simple or complex type MUST end with

the suffix "Type". Suffixing for Types

ELN: Element Naming Rules ELN1 An element SHOULD have the same name as its type

with the suffix "Type" omitted. The relation between element and type names

ATN: Attribute Naming Rules


ATN1 Attributes MUST be named using lowerCamelCase. Use of lowerCamelCase for attributes.

FNR: File Naming Rules FNR1 The file name of a schema module MUST comply with

the naming scheme: <namespace prefix with capital letters>_<element name>.xsd.

Naming of schema module files

GTD: General Type Definition Rules (applies to simple and complex types) GTD1 All types MUST be defined as strongly as possible. Strong data types GTD2a All simple and complex types belonging to the OIOXML

Core Components and OIOXML Domain Components classes MUST be globally defined.

Global type definitions

GTD5 The builtin simple types anyURI or base64Binary SHOULD be used for handling binary content.

Handling binary content

CTD: Complex Type Definition Rules (applies only to complex types) CTD1a A complex type SHOULD be defined using either the

sequence or choice construct. Definition of complex types by Aggregation

CTD1b A complex type MUST NOT be defined using the all construct.

Definition of complex types by Aggregation

CTD6 The anyAttribute construct MUST NOT be used in a content model.

The use of anyAttribute

ELD: Element Declaration Rules (applies ony to elements) ELD1a All elements belonging to the OIOXML Core Components

and OIOXML Domain Components classes MUST be globally declared.

Global element declarations

ELD1b All elements belonging to the OIOXML NDR Components class SHOULD be globally declared.

Global element declarations

ELD2 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.

Namespace for elements

ELD4 The attribute nillable MUST NOT be used in element declarations.

The use of nillable

ATD: Attribute Declaration Rules (applies only to attributes) ATD1 Attributes MUST only be used for metadata. The use of attributes ATD2 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.

Namespace for attributes

NMS: Namespace Rules NMS1 A namespace MUST represent a valid URL in the Namespace representation


Infostructurebase and comply with the following naming scheme: http://rep.oio.dk/<internetdomæne> /xml/schemas/<YYYY >/<MM>/<DD>/

NMS2 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

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

http://rep.oio.dk/


implementeret.

3.1.3a Services og andet programmel SKAL kunne afvikles i DMPs driftsmiljø

3.1.3b Alle services SKAL implementere en Test funktion

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.

3.1.5a Der SKAL udarbejdes et SLA bilag til kontrakten.

3.1.6a Fælles datastrukturer specificeret af sektorstandardiseringsudval g SKAL anvendes. (Jf. Regel 2.1a)

3.1.6b Relevante generiske services i DMP SKAL anvendes

3.1.6c OIOXML NDR i senest gældende version BØR følges. (Link: http://itst.dk/NDR)

3.1.7a DMPs fælles sikkerhedssystem SKAL anvendes

3.1.7b DMPs IT-sikkerhedspolitik og sikkerhedspolicies SKAL følges

3.1.7c DMPs fortolkning af DS484/ISO27001 SKAL overholdes

http://itst.dk/NDR)

http://itst.dk/NDR)


3.1.8a DMPs fælles logningsservice SKAL anvendes.

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.

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

3.1.10a Forretningsservices BØR være designet således at det ikke er nødvendigt at anvende batchkørsler

3.1.10b Anvendelse og design af samtlige batchkørsler SKAL være forhåndsgodkendt af DMP.

3.1.11a Servicen SKAL anvende standard kommunikationsprotokoller

3.1.11b DMP SKAL forhåndsgodkende de kommunikationsprotokoller, der planlægges at blive anvendt


3.2a DMPs arkitekturprincipper SKAL følges.

3.2.2.a Der skal henvises til eksisterende forretningservices eller udarbejdes nye.

3.2.2b Et forretningsområde SKAL overholde krav beskrevet i den for DMP gældende version af IT-Arkitektur rammeværk

3.2.2c Et forretningsområde SKAL beskrives i den for DMP gældende version af BPMN

3.2.2d En service SKAL bygges over en model med udgangspunkt i Forretningsservices og Forretningsobjekter

3.2.2e En service KAN understøtte flere forretningsobjekter.

3.2.2f Det BØR altid overvejes om der er behov for at anvende reference til store data- items.

3.2.2g Udstillelse af data via en ”raw” tilgang SKAL i hvert enkelt tilfælde godkendes af DMP.

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.


3.2.4a Ved simple transaktioner MÅ Scenarie A benyttes

3.2.4b Ved simple transaktioner med viderekald BØR Scenarie B benyttes

3.2.4c Ved transaktioner med mere end én commit BØR Scenarie C eller D benyttes

3.2.5a DMP’s projektmodel skal følges

3.2.5b DMP’s releaseproces skal følges.

3.2.6a Den af DMP specificerede dokumentations template SKAL (som minimum) benyttes til dokumentation jf. [7.10]


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

3.2.6b Alt dokumentation og kildekode skal lægges u DMP’s TFS(miljoeportal.visualstudio.com)


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 Notation specification in this section MUST be used

4.1.2a Timestamps MUST always be stored in UTC

4.1.2b Timestamps MUST use the ISO 8601 representation

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.

4.2.3b DMP MUST approve of the selected method

4.2.4a SOAP 1.2 MUST be used.

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)

4.3.2a Namespace prefixes MUST follow OIOXML NDR 3.2 rule NMS-2

4.3.3a Endpoint naming MUST follow the format

http://xxxhost/miljoeportal.[m ain area].[sub area].[version]/[Name of

http://xxxhost/miljoeportal


Service]

4.3.4a Namespace naming MUST follow the format

"urn:oio:" <organisation> ":" <business area>”.”[lower businessarea]> ":" <version>.

4.4.1a The “contract-first” approach MUST be used

4.4.1b The “stable-interface” approach SHOULD be used

4.4.3a Methods for both xml string and object structure SHOULD be supported

4.4.4a 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 OIOREST recommendation SHOULD be followed

4.7.2a The REST request and response body MUST be using XML

4.7.2.b The REST request and response body SHOULD have same format as message payload for


corresponding web services

4.7.3a The REST URIs MUST comply with DMP naming conventions

4.7.3b REST Query string parameters MUST be in english

4.7.3c REST Query string parameters MUST use ASCII character set and MUST NOT use space

4.7.5a REST services MUST use standard HTTP status codes

4.7.6a The REST service MUST comply with DMP security Framework

4.7.6b Using a REST service MUST be agreed with DMP in each case

4.7.6c 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 The DMP Log Service MUST be used

4.8.1b The LogMessage format specified by the LogMessage XML Schema MUST be used.

4.8.1c The service MUST log all updates to data and access to sensitive data to the DMP Log Service.


4.8.1d The service SHOULD log all other relevant activities to the DMP Log Service

4.8.2a A custom Windows Event Log SHOULD be created and named “DMP Event Log”

4.8.2b Naming conventions from Log Service MUST also be followed using the “DMP Event Log”

4.8.2c Application/Service start, shutdown and major errors MUST be logged in the “DMP Event Log”

4.8.2d Other relevant Application/Service events SHOULD be logged in the “DMP Event Log”

4.10.2a All Errors must be logged in the DMP Logging Service

4.10.2b 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.

4.10.2c All Errors MUST ve logged in the DMP eventlog

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 4.3.3

5.2c The ResultCode and


ResultMessage MUST reflect the failures found

6.1 All the namespaces used in the Biztalk server applications MUST conform to DMP Namespace Naming Conventions 4.3.1.

6.1.2a All XML message formats that are exchanged between applications SHOULD be defined with proper namespaces conforming to the OIO standards.

6.1.2.b If the XML message are designed to carry payload, then the format SHOULD conform to the payload message standards specified in 4.4

6.1.2c All XML messages MAY be designed with suitable XML schemas conforming to OIO NDR 3.2 or later versions

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.

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.

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.

6.2.2a An assembly MUST NOT be deployed to a Biz Talk Server production environment from Visual Studio

6.2.2b A shared web application (for example as a receive location) SHOULD be deployed as a separate application.

6.2.2c MSI files MUST be used in order to deploy a Biz Talk Server application to production environment.

6.2.4a Suitable exception handling MUST be used in Biz Talk Server Orchestrations.

6.2.4b All the calls to the external web services SHOULD be defined in scope shape with proper exception handling.

6.2.4c The scope's transaction type property SHOULD be assigned to 'NONE'.

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.

6.3.2b For the WCF services published with WCF adapters, the IsOneWay property of the service


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.

6.5 For simple Biz Talk Server applications, the global variable SHOULD be stored in configuration files (BTSNTSvc.exe.config)

old.miljoeportal.dkold.miljoeportal.dk/Dokumenter alle/Specifikation af Web Services til... · DMP...

Documents

Transcript of old.miljoeportal.dkold.miljoeportal.dk/Dokumenter alle/Specifikation af Web Services til... · DMP...