1 implementing web services for healthcare lessons & pitfalls - marc de graauw -
TRANSCRIPT
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
Broker
Healthcare Information
System
Healthcare Information
System
Healthcare Information
System
Healthcare Information
System
Healthcare Information
System
PatientRegistry
Messa-ging
Services
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
TCP
HTTP, SSL
SOAP / XML
HL7 Transmission Wrapper
HL7 Query Control Wrapper
lower protocol layers
HL7v3 Layered Model
HL7 Medical Data
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
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)
11
SOAP in one slide
• Envelope, Headers, Body<soap:Envelope ... namespaces ... >
<soap:Header mustUnderstand = ‘1’>... headers ...
</soap:Header><soap:Body>
... payload ...</soap:Body>
</soap:Envelope>
• HTTP BindingPOST / HTTP/1.1bla bla...SOAPAction: "urn:hl7-org:v3/QURX_AR990120NL“
<?xml version="1.0" encoding="utf-8"?><soap:Envelope ... namespaces ... >
• 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 (IBM< 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
Copy of Message
Receipt Ack
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 <include> 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
Binding
Medication Query Service
Other PortType
Other PortType
Medication Query PortType
Other Operation
QueryResponse Operation Query Message
Response Message
QuerySchema
ResponseSchema
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
• <birthdate>19610306</birthdate> • maps to: date• <name><first>Marc</first><last>de Graauw</last></name>• maps to: struct of string, string• <gender>M</gender> • 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 -> 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
Binding
Some HL7v3 PortType
Some HL7v3 Query Some HL7v3 Query
HL7v3 Query Response
Some HL7v3 Query
Schema
HL7v3 Query
ResponseSchema
Dynamic response
• HLv3 responseModalityCode = “R”
27
Binding
Some HL7v3 PortType
Some HL7v3 Query Some HL7v3 Query
HL7v3 Response Batch
Some HL7v3 Query
Schema
HL7v3 Batch
ResponseSchema
Dynamic response (cont.)
• HLv3 responseModalityCode = “B”
28
Dynamic response (cont.)
• More HL7v3 attributes (=XML elements)– acceptAckCode– responsePriority– continuationQuantity
• content co-determines response Schema• Solutions:
– multiple PortTypes = clutter, bad design– <choice> 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
Binding
HL7v3 Medication PortType
HL7v3 Medication QueryResponse
Operation
HL7v3 Medication Query
HL7v3 Medication Response
HL7v3Medication
QuerySchema
HL7v3 Medication ResponseSchema
Generic vs. specific WSDL
• Specific WSDL:
31
Binding
HL7v3 Message PortType
HL7v3 MessageOperation
HL7v3 MessageOut
HL7v3 MessageIn
HL7v3MessageSchema
HL7v3MessageSchema
Generic vs. specific WSDL
• Generic WSDL:
32
Generic vs. specific WSDL
• Generic WSDL uses generic Schemas
• Possibly with Transmission Wrapper
<xs:schema targetNamespace="urn:hl7-org:v3">
<xs:element name="hl7Message">
<xs:complexType>
<xs:sequence>
<xs:any/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
33
HL7 Medical Application
HL7 Control Query Processing Application
HL7 Transmission Wrapper Adapter
HL7 web services Messaging Adapter
HTTP Client / Server
SOAPmessages
HL7v3 messages
HL7v3 CQ Wrapper
& payload
HL7v3 medicalcontent
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
Binding
HL7v3 Medication PortType
HL7v3 Medication QueryResponse
Operation
HL7v3 Medication Query
HL7v3 Medication Response
HL7v3Medication
QuerySchema
HL7v3 Medication ResponseSchema
Reliability Issues
• Delegated to HTTP 200 OK
38
HL7v3 Medication PortType
Reliability Issues
• Using Accept Acknowledgements
BindingHL7v3 Medication ResponseOperation
HL7v3 Accept Ack
HL7v3 Med. Response
BindingHL7v3 Medication Query
Operation
HL7v3 Medication Query
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 soap:Body
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
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• [email protected]• Feedback welcome!
• QUESTIONS .... ???