The document discusses implementing HL7v3 web services. It covers SOAP and WSDL standards, including envelopes, headers and bodies. It describes using generic versus specific WSDL, and issues with dynamic responses. The document also discusses HL7v3 patterns for query messages and reliability considerations like wire signatures.

1. www.marcdegraauw.com Implementeren van HL7v3 Web Services - Marc de Graauw -

2. www.marcdegraauw.com SOAP & WSDL

3. www.marcdegraauw.com SOAP & WSDL Intro WSDL & code generation Dynamic response, “wrapped” style Generic WSDL Reliability issues Wire signature

4. Web Services WSDL historie opsplitsen WSDL IHE, OMG/HL7

5. Historie XML SGML Standard Generalized Markup Language IBM: back to the sixties... Markup: structuur, niet processing HTML: SGML spinoff 1998: XML SGML voor het Web, zonder ballast 2000: SOAP 1.1, WSDL 1.0 2001: XML Schema

6. SOAP SOAP envelope SOAP Envelope, Header, Body transport: HTTP POST <ws:SecToken> Certificate <ds:Signature> Sig value Authenticatietoken body HL7v3 bericht Prescription 1

7. www.marcdegraauw.com Zorg Informatie Systeem Zorg Informatie Makelaar Zorg Informatie Systeem Berichten diensten Zorg Informatie Systeem Zorg Informatie Systeem Patiënten Verwijs Index Zorg Informatie Systeem

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

9. www.marcdegraauw.com AORTA Message Patronen Queries (van GBZ aan ZIM) asynchroon synchroon Andere berichten met respons zonder respons

10. www.marcdegraauw.com Query met synchroon antwoord

11. www.marcdegraauw.com Bericht zonder respons

12. www.marcdegraauw.com Bericht met asynchrone respons

13. www.marcdegraauw.com 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 Binding POST / HTTP/1.1 bla bla... SOAPAction: "urn:hl7-org:v3/QURX_AR990120NL“ <?xml version="1.0" encoding="utf-8"?> <soap:Envelope ... namespaces ... > SOAP Encoding: legacy, forget it

14. www.marcdegraauw.com ‘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)))

15. www.marcdegraauw.com 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

16. www.marcdegraauw.com Medication Query Service Medication Query PortType Query Schema Binding QueryResponse Operation Query Message Response Message Response Schema Other Operation Other PortType Other PortType

17. www.marcdegraauw.com ‘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

18. www.marcdegraauw.com ‘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 “Out of the box” cCode generation: fine for float FahrenheitToCelsius(float) currency StockQuote(string)

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

20. www.marcdegraauw.com HLv3 responseModalityCode = “R” Some HL7v3 Query Schema Some HL7v3 PortType Binding Some HL7v3 Query Some HL7v3 Query HL7v3 Query Response HL7v3 Query Response Schema Dynamic response

21. www.marcdegraauw.com HLv3 responseModalityCode = “B” Some HL7v3 Query Schema Some HL7v3 PortType Binding Some HL7v3 Query Some HL7v3 Query HL7v3 Response Batch HL7v3 Batch Response Schema Dynamic response (cont.)

22. www.marcdegraauw.com 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

23. www.marcdegraauw.com Specific WSDL: HL7v3 Medication Query Schema HL7v3 Medication PortType Binding HL7v3 Medication QueryResponse Operation HL7v3 Medication Query HL7v3 Medication Response HL7v3 Medication Response Schema Generic vs. specific WSDL

24. www.marcdegraauw.com Generic WSDL: HL7v3 Message Schema HL7v3 Message PortType Binding HL7v3 Message Operation HL7v3 MessageOut HL7v3 MessageIn HL7v3 Message Schema Generic vs. specific WSDL

25. www.marcdegraauw.com 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>

26. www.marcdegraauw.com 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

27. www.marcdegraauw.com 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

28. www.marcdegraauw.com 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

29. www.marcdegraauw.com HL7v3 Medication PortType Wire signatures Continuation: continuationQuantity > 0 Cancel: continuationQuantity = 0 Binding HL7v3 Medication QueryContinuation Operation HL7v3 QueryContinuation HL7v3 Med. Response Binding HL7v3 Medication QueryCancel Operation HL7v3 QueryCancel HL7v3 Accept Ack

30. Waar raakt WSDL wire format document / literal element onder Body Schema / XML payload in Body SOAPAction header Service location URI

31. Basic Profile 2004: aanvullingen en correcties op SOAP/WSDL veel tooling ondersteunt dit belangrijk

32. HL7 Web Services Profile HL7 Web Services Profile DSTU 1 SOAP, WSDL, WS-I Basic Profile 1.0 naamgeving WSDL-componenten gladstrijken oneffenheden HL7 – SOA HL7 Web Services Profile DSTU 2 WS-Addressing, WS-Security, WS-ReliableMessaging tamelijk dunne toevoegingen, veel nader in te vullen Daarna: stilstand, DSTU 2 is verlopen

33. Web Services en HL7 Abstract Transport Specification ebXML Messaging HL7/OMG IHE

34. Transport vs. SOA HL7 RIM based model serialisatie in XML Transport agnostic MIME ebXML alles kan erin Send XML / Receive XML Send something / Receive something Web server XML in Verstrekkingsbericht Medicatiequery XML uit Accept ack Medicatielijst

35. Transport vs. SOA SOA Services FindPatientsByTrait DispenseMedication Expliciete service Namen van operations vastgelegd Content model (schema) expliciet gemaakt Blootstellen van services Implementatie service is niet zichtbaar Web server Verstrekkingsbericht Verstrekkings- service Accept ack Medicatie- service Medicatiequery Medicatielijst

36. HL7 Transmission wrapper Control Act Wrapper

37. OMG/HL7 Retrieve, Locate, and Update (RLUS) Service Entity Identification Service (EIS) HL7 Wrappers dropped

38. IHE XCPD (Cross-Community Patient Discovery) Patient Identifier Cross-Reference HL7 V3 (PIXV3) and Patient Demographic Query HL7 V3 (PDQV3) Cross-Community Access (XCA) ebXML Registry / Repository MTOM

39. ‘Design time’ versionering Design time versionering gaat over versies van dingen die gebruikt worden bij het implementeren Versies van: documentatie (Aorta v6.0.0.0) architectuur implementatiehandleidingen XML Schema WSDL Schematron (gegenereerde) programmacode database schema Op basis van wat bouw je?

40. ‘Run time’ versionering Run time versionering gaat over versies van dingen die je tegenkomt in productie Versies van: XML instances en HL7 artefacten daarin (datgene wat een client stuurt) Web Services endpoints (datgene waarnaar het verzonden wordt De versie van een ingestuurde XML instance kun je potentieel herkennen door middel van: HTTP Header: SOAPAction SOAP Headers in de SOAP Envelope Top element in SOAP Body == HL7 interactionId (b.v. QURX_IN990011NL) HL7 namespace (urn:hl7-org:v3) andere namespaces (b.v.: http://www.aortarelease.nl/805/) profileId (<profileId root="2.16...11.1" extension="810"/>) De versie van een Web Service is te herkennen aan de URI Wat gebeurt er “on the wire”?