1. 1 Implementing Web Services for Healthcare Lessons & Pitfalls - Marc de Graauw -

2. 2 NICTIZ & Dutch Healthcare Standardization authority for data exchange in Dutch healthcare Short term goal: national exchange of medication data operational in 2006 90.000 people are hospitalized yearly due to wrong medication "The question is not whether the electronic medical file will become obligatory, but how" – Min. Hoogervorst

3. 3 NICTIZ & Dutch Healthcare Communication between: –Healthcare Provider (GP, hospital etc.) –Healthcare Information Broker (HIB) HIB provides: –index of which parties have patient data –no patient data itself –messaging services –aggregation services Health Level Seven version 3 (HL7v3)

4. 4 Healthcare Information Broker Healthcare Information System Healthcare Information System Healthcare Information System Healthcare Information System Healthcare Information System Patient Registry Messa- ging Services

5. 5 Just enough HL7 HL7 version 2 : currently used HL7v3: –XML based –Reference Information Model HL7v3 Message contains: –medical payload –Trigger Event Wrappers (Query Control etc.) –Transmission Wrapper Example: QURX_EX990001NL-1.xmlQURX_EX990001NL-1.xml

6. 6 TCP HTTP, SSL SOAP / XML HL7 Transmission Wrapper HL7 Query Control Wrapper lower protocol layers HL7v3 Layered Model HL7 Medical Data

7. 7 Transmission Wrapper Addressing information (Sender, Receiver) MessageId (unique id / message) –duplicate detection is requirement Accept Acknowledgement Code –request accept acknowledgement (Never / Always, Error, Succes) –is syntactical – not semantic – acceptance more... Contains other wrappers Transmission Wrapper intersects web services stack

8. 8

9. 9 Which standards? The basics were pretty clear: –HL7v3 –XML 1.0 & Namespaces –XML Schema –SOAP 1.1 (not a real standard!) In 2003 when work started: –SOAP 1.2 not finished –WSDL 1.1 finished, 2.0 not –WS-stack not finished (Reliability, Security etc.) –ebXML Messaging (ebMS)

10. 10 XML in one slide XML 1.0 & Namespaces Frans Rijtje XML Schema

11. 11 SOAP in one slide Envelope, Headers, Body... headers...... payload... HTTP Binding POST / HTTP/1.1 bla bla... SOAPAction: "urn:hl7-org:v3/QURX_AR990120NL SOAP Encoding: legacy, forget it

12. 12 Which standards?(cont.) Security? No. –we use HTTPS –intermediaries (HIB) are trusted –this is secure –later: WS-Security, XML Signature, XML Encryption Addressing? No. –HL7v3 provides own addressing scheme Description? Maybe. –HL7v3 has own interaction modelling methodology

13. 13 Which standards? Reliability? Yes. –transport over HTTP is not reliable The options? –ebMS 2.0 no IBM, Microsoft adoption –WS-Reliability (Sun, Oracle et. al.) not finished –WS-ReliableMessaging (IBM< Microsoft et. al.) not finished, (was?) proprietary –HL7v3 Accept Acks Confused?

14. 14 SenderReceiver Message

15. 15 SenderReceiver Message Copy of Message Receipt Ack

16. 16 SenderReceiver Copy of Message Receipt Ack Message Receipt Ack Does duplicate detection

17. 17 Which standards? (cont.) Basics were clear (XML, XSD, SOAP) WSDL added (well standardized & used) No need for discovery / repository specs Future of some WS standards uncertain Adopt as few standards as possible –No lock-in to wrong (= losing) standard –Facilitate later adoption –SOAP Headers make transition easier

18. 18 Lessons & Pitfalls Lesson 1: Do not adopt standards too soon!

19. 19 Real world complexity HL7v3 XML Schema stacks of 10 – 15 schemas HL7v3 typing system (mapped onto XSD datatypes) HL7v3 vocabulary Layered wrapper approach SOAP (Transmission (Query (Medical Data)))

20. 20 WSDL in one slide WSDL defines a web service Which schemas are used? Which messages are used & which schemas are involved? Which operations are used & which messages go in and which go out? How do operations assemble to make a web service (PortType, Service)? Binding to SOAP and HTTP

21. 21 Binding Medication Query Service Other PortType Medication Query PortType Other Operation QueryResponse Operation Query Message Response Message Query Schema Response Schema

22. 22 Real world complexity (cont.) WSDL is a: –description of a web service –generate WSDL from code? –generate code from WSDL? WSDL code generation –map XML to programming object 19610306 maps to: date Marc de Graauw maps to: struct of string, string M maps to: char(1) or: enum(M, F) or: GenderType –map operations, HTTP Binding et cetera

23. 23 Real world complexity (cont.) WSDL code generation: –reserved word clashes –creates object for each XML construct –15 schemas -> Gargantuan objects! –all of vocabulary.xsd –all objects in one module Code generation: fine for –float FahrenheitToCelsius(float) –currency StockQuote(string)

24. 24 Lessons & Pitfalls Lesson 1: Do not adopt standards too soon Lesson 2: Do not count on code generation

25. 25 Dynamic response types WSDL: operation with defined message types with defined Schemas HL7v3 has attributes where content co- determines response Schema

26. 26 Binding Some HL7v3 PortType Some HL7v3 Query HL7v3 Query Response Some HL7v3 Query Schema HL7v3 Query Response Schema Dynamic response HLv3 responseModalityCode = R

27. 27 Binding Some HL7v3 PortType Some HL7v3 Query HL7v3 Response Batch Some HL7v3 Query Schema HL7v3 Batch Response Schema Dynamic response (cont.) HLv3 responseModalityCode = B

28. 28 Dynamic response (cont.) More HL7v3 attributes (=XML elements) –acceptAckCode –responsePriority –continuationQuantity content co-determines response Schema Solutions: –multiple PortTypes = clutter, bad design – in Schema = undescriptive, hard to read

29. 29 Lessons & Pitfalls Lesson 1: Do not adopt standards too soon Lesson 2: Do not count on code generation Pitfall 1: Dynamic response types

30. 30 Binding HL7v3 Medication PortType HL7v3 Medication QueryResponse Operation HL7v3 Medication Query HL7v3 Medication Response HL7v3 Medication Query Schema HL7v3 Medication Response Schema Generic vs. specific WSDL Specific WSDL:

31. 31 Binding HL7v3 Message PortType HL7v3 Message Operation HL7v3 MessageOut HL7v3 MessageIn HL7v3 Message Schema HL7v3 Message Schema Generic vs. specific WSDL Generic WSDL:

32. 32 Generic vs. specific WSDL Generic WSDL uses generic Schemas Possibly with Transmission Wrapper

33. 33 HL7 Medical Application HL7 Control Query Processing Application HL7 Transmission Wrapper Adapter HL7 web services Messaging Adapter HTTP Client / Server SOAP messages HL7v3 messages HL7v3 CQ Wrapper & payload HL7v3 medical content

34. 34 Generic WSDL Pro: –eases separation of layers –no problems with dynamic response –code generation is useful again Con: –does not describe actual web service neatly

35. 35 Lessons & Pitfalls Lesson 1: Do not adopt standards too soon Lesson 2: Do not count on code generation Pitfall 1: Dynamic response types Lesson 3: Consider generic WSDL

36. 36 Reliability Issues We chose HL7v3 Accept Acks unclarity in standards situation 2003/4: standards not finished SOAP allows extension but: commit / accept blur!

37. 37 Binding HL7v3 Medication PortType HL7v3 Medication QueryResponse Operation HL7v3 Medication Query HL7v3 Medication Response HL7v3 Medication Query Schema HL7v3 Medication Response Schema Reliability Issues Delegated to HTTP 200 OK

38. 38 HL7v3 Medication PortType Reliability Issues Using Accept Acknowledgements BindingHL7v3 Medication Response Operation HL7v3 Accept Ack HL7v3 Med. Response BindingHL7v3 Medication Query Operation HL7v3 Medication Query HL7v3 Accept Ack

39. 39 Reliability Issues Delegate to HTTP 200 OK –only for idempotent messages –synchronous –one side only needs SOAP client –single HTTP request – response pair Accept Acks –works for all messages –asynchronous –both sides need SOAP server –two HTTP request – response pairs

40. 40 Lessons & Pitfalls Lesson 1: Do not adopt standards too soon Lesson 2: Do not count on code generation Pitfall 1: Dynamic response types Lesson 3: Consider generic WSDL Lesson 4: Carefully design Bindings

41. 41 Wire signatures We chose to follow WS-I Basic Profile –sensible set of guidelines –not an additional standard –refinement of SOAP 1.1 / WSDL 1.0 R2710: operations MUST result in wire signatures that are different R2710: wire signature = name of the child element of the soap:Body

42. 42 HL7v3 Medication PortType Wire signatures Continuation: continuationQuantity > 0 Cancel: continuationQuantity = 0 BindingHL7v3 Medication QueryCancel Operation BindingHL7v3 Medication QueryContinuation Operation HL7v3 QueryContinuation HL7v3 Med. Response HL7v3 QueryCancel HL7v3 Accept Ack

43. 43 Lessons & Pitfalls Lesson 1: Do not adopt standards too soon Lesson 2: Do not count on code generation Pitfall: Dynamic response types Lesson 3: Consider generic WSDL Lesson 4: Carefully design Bindings Pitfall: R2710 & wire signatures

44. 44 The ebMS story ebMS –used in NHS (British Healthcare) –Dutch Criminal Justice Chain –Dutch Social Security Chain (BKWI) –NICTIZ reconsidered –did not adopt ebMS now: stability of specs Lesson 1: Do not adopt standards too soon

45. 45 Marc de Graauw Independent Consultant... and I like it! not available till sometime in summer www.marcdegraauw.com marc@marcdegraauw.commarcdegraauw.com Feedback welcome! QUESTIONS.... ???