Implementing Web Services for Healthcare

1
Implementing Web Services for Healthcare

• Lessons Pitfalls
• - Marc de Graauw -

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
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
Healthcare Information System
Healthcare Information Broker
Healthcare Information System
Messa- ging Services
Healthcare Information System
Healthcare Information System
Patient Registry
Healthcare Information System
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.xml

6
HL7v3 Layered Model
HTTP, SSL
SOAP / XML
HL7 Transmission Wrapper
HL7 Query Control Wrapper
HL7 Medical Data
TCP
lower protocol layers
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
(No Transcript)
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
XML in one slide

• XML 1.0 Namespaces
• ltname xmlns"urnhl7-orgv3"gt
• ltgivengtFranslt/givengt
• ltfamilygtRijtjelt/familygt
• lt/namegt
• XML Schema
• ltxsdsequencegt
• ltxsdelement name"given" type"string"/gt
• ltxsdelement name"family" type"string"/gt
• lt/xsdsequencegt

11
SOAP in one slide

• Envelope, Headers, Body
• ltsoapEnvelope ... namespaces ... gt
• ltsoapHeader mustUnderstand 1gt
• ... headers ...
• lt/soapHeadergt
• ltsoapBodygt
• ... payload ...
• lt/soapBodygt
• lt/soapEnvelopegt
• HTTP Binding
• POST / HTTP/1.1
• bla bla...
• SOAPAction "urnhl7-orgv3/QURX_AR990120NL
• lt?xml version"1.0" encoding"utf-8"?gt
• ltsoapEnvelope ... namespaces ... gt
• SOAP Encoding legacy, forget it

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
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 (IBMlt Microsoft et. al.)
• not finished, (was?) proprietary
• HL7v3 Accept Acks
• Confused?

14
Sender
Receiver
Message
15
Sender
Receiver
Message
Copy of Message
Receipt Ack
16
Sender
Receiver
Message
Receipt Ack
Copy of Message
Receipt Ack
Does duplicate detection
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
Lessons Pitfalls

• Lesson 1 Do not adopt standards too soon!

19
Real world complexity

• HL7v3 XML Schema ltincludegt stacks of 10 15
  schemas
• HL7v3 typing system (mapped onto XSD datatypes)
• HL7v3 vocabulary
• Layered wrapper approach
• SOAP (Transmission (Query (Medical Data)))

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
Medication Query Service
Medication Query PortType
Query Schema
Binding
QueryResponse Operation
Query Message
Response Message
Response Schema
Other Operation
Other PortType
Other PortType
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
• ltbirthdategt19610306lt/birthdategt
• maps to date
• ltnamegtltfirstgtMarclt/firstgtltlastgtde
  Graauwlt/lastgtlt/namegt
• maps to struct of string, string
• ltgendergtMlt/gendergt
• maps to char(1) or enum(M, F) or
  GenderType
• map operations, HTTP Binding et cetera

23
Real world complexity (cont.)

• WSDL code generation
• reserved word clashes
• creates object for each XML construct
• 15 schemas -gt Gargantuan objects!
• all of vocabulary.xsd
• all objects in one module
• Code generation fine for
• float FahrenheitToCelsius(float)
• currency StockQuote(string)

24
Lessons Pitfalls

• Lesson 1 Do not adopt standards too soon
• Lesson 2 Do not count on code generation

25
Dynamic response types

• WSDL operation with defined message types with
  defined Schemas
• HL7v3 has attributes where content co-determines
  response Schema

26
Dynamic response

• HLv3 responseModalityCode R

Some HL7v3 Query Schema
Some HL7v3 PortType
Binding
Some HL7v3 Query
Some HL7v3 Query
HL7v3 Query Response
HL7v3 Query Response Schema
27
Dynamic response (cont.)

• HLv3 responseModalityCode B

Some HL7v3 Query Schema
Some HL7v3 PortType
Binding
Some HL7v3 Query
Some HL7v3 Query
HL7v3 Response Batch
HL7v3 Batch Response Schema
28
Dynamic response (cont.)

• More HL7v3 attributes (XML elements)
• acceptAckCode
• responsePriority
• continuationQuantity
• content co-determines response Schema
• Solutions
• multiple PortTypes clutter, bad design
• ltchoicegt in Schema undescriptive, hard to read

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
Generic vs. specific WSDL

• Specific WSDL

HL7v3 Medication Query Schema
HL7v3 Medication PortType
Binding
HL7v3 Medication QueryResponse Operation
HL7v3 Medication Query
HL7v3 Medication Response
HL7v3 Medication Response Schema
31
Generic vs. specific WSDL

• Generic WSDL

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

• Generic WSDL uses generic Schemas
• Possibly with Transmission Wrapper

ltxsschema targetNamespace"urnhl7-orgv3"gt
ltxselement name"hl7Message"gt
ltxscomplexTypegt ltxssequencegt
ltxsany/gt lt/xssequencegt
lt/xscomplexTypegt lt/xselementgt
lt/xsschemagt
33
HL7 Medical Application
HL7v3 medical content
HL7 Control Query Processing Application
HL7v3 CQ Wrapper payload
HL7 Transmission Wrapper Adapter
HL7v3 messages
HL7 web services Messaging Adapter
SOAP messages
HTTP Client / Server
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
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
Reliability Issues

• We chose HL7v3 Accept Acks
• unclarity in standards situation
• 2003/4 standards not finished
• SOAP allows extension
• but commit / accept blur!

37
Reliability Issues

• Delegated to HTTP 200 OK

HL7v3 Medication Query Schema
HL7v3 Medication PortType
Binding
HL7v3 Medication QueryResponse Operation
HL7v3 Medication Query
HL7v3 Medication Response
HL7v3 Medication Response Schema
38
Reliability Issues

• Using Accept Acknowledgements

HL7v3 Medication PortType
Binding
HL7v3 Medication Query Operation
HL7v3 Medication Query
HL7v3 Accept Ack
Binding
HL7v3 Medication Response Operation
HL7v3 Med. Response
HL7v3 Accept Ack
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
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
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 soapBody

42
Wire signatures

• Continuation continuationQuantity gt 0
• Cancel continuationQuantity 0

HL7v3 Medication PortType
Binding
HL7v3 Medication QueryContinuation Operation
HL7v3 QueryContinuation
HL7v3 Med. Response
Binding
HL7v3 Medication QueryCancel Operation
HL7v3 QueryCancel
HL7v3 Accept Ack
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
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
Marc de Graauw

• Independent Consultant
• ... and I like it!
• not available till sometime in summer
• www.marcdegraauw.com
• marc_at_marcdegraauw.com
• Feedback welcome!
• QUESTIONS .... ???