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

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


System


System


System


System


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



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

32


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

Operation


HL7v3 Medication Response

HL7v3Medication

QuerySchema

HL7v3 Medication ResponseSchema

Reliability Issues

• Delegated to HTTP 200 OK

38


Reliability Issues

• Using Accept Acknowledgements

BindingHL7v3 Medication ResponseOperation

HL7v3 Accept Ack

HL7v3 Med. Response

BindingHL7v3 Medication Query

Operation


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


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



• Pitfall: Dynamic response types


• 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


45

Marc de Graauw

• Independent Consultant• ... and I like it!• not available till sometime in summer• www.marcdegraauw.com• [email protected]• Feedback welcome!

• QUESTIONS .... ???

http://www.marcdegraauw.com/

http://www.marcdegraauw.com/

Documents

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