Clinical Data Exchange using HL7 and Mirth Connect Lecture 8 - HTTP Connectors - Web Service Connectors - JMS Connectors Siv Raman, MD, MS
HTTP Listener/HTTP Sender HTTP Listener: HTTP Connectors HTTP Listener/HTTP Sender HTTP Listener: Listener acts as web server Listens on a specific interface or all interfaces Message can be body content only (any data type) or XML structure containing request info, headers, query parameters and body content If XML, the body content is enclosed within a CDATA block Ability to respond from any destination Specify MIME content type and character encoding
HTTP Connectors HTTP Listener, cont. XML message structure: <?xml version="1.0" encoding="UTF-8"?> <HttpRequest> <RemoteAddress>127.0.0.1</RemoteAddress> <RequestUrl>http://localhost:8090/</RequestUrl> <Method>POST</Method> <RequestPath>param1=%22ABC%22¶m2=%22DEF%22</RequestPath> <Parameters> <param1>"ABC"</param1> <param2>"DEF"</param2> </Parameters> <Header> <Host>localhost:8090</Host> <Content-Length>4462</Content-Length> <User-Agent>Jakarta Commons-HttpClient/3.0.1</User-Agent> <Content-Type>text/plain;charset=UTF-8</Content-Type> </Header> <Content><![CDATA[MSH|^~\&|EPIC|Hospital B|KEANE|KEANE|20090601093321|I000007|ADT^A08|LFILLMORE-0041|P|2.3 EVN|A08|200906010933|||I000007^INTERFACE^ADT^^^^^^M^^^^^LBM PID||B1230041|B1230041||Fillmore^Larry^J.||19740514|M||G|555 FIVE LN^^LONG BEACH^CA^90745||(562)555-0041^^M||ENG|S|NO|LBACT0041|770-22-7887|||||||||||N NK1|1|WOCAHWOYW^VO^VORI|FR|8387 SEKL LCA^^LOJA LEYFI^DI^48213|(007)307-6703|^^^^^^^|1 NK1|2|""|""|""|""|"" PV1||O|ZMR||||4^PLUTO^DOG^|12^ROD^FLANDERS^|19^SARAH^WIGGUM^|O/P|||||||005463^PITA^ABELARDO^R|O|333866716||||||||||||||||||||DISNEY CLINIC||N|||200906010928||||||882506717281 PV2|||^HA/DIZZINESS|||||20090529||||||||||||||N AL1|1|20|526^NO KNOWN ALLERGIES]]></Content> </HttpRequest>
HTTP Sender: HTTP Connectors Supports GET, POST, PUT, and DELETE methods Supports Multipart content type for binary data Can only be used with POST method Supports optional basic or digest authentication Supports persistent queues Supports header variables and query parameters Specify content and content type for request body Response can be forwarded to another channel Response stored in Response Map (or optionally forwarded to another channel) can include headers (in XML format) or be content (response body) only When response is in XML format, body will be enclosed in CDATA block
HTTP Sender, cont. HTTP Connectors XML response structure: <?xml version="1.0" encoding="UTF-8"?> <HttpResponse> <Status>HTTP/1.1 200 OK</Status> <Header> <Field> <Name>Date</Name> <Value>Fri, 15 Oct 2011 01:13:04 GMT</Value> </Field> <Name>Server</Name> <Value>Jetty/5.1.15 (Windows Vista/6.0 x86 java/1.6.0_20</Value> … </Header> <Body><![CDATA[This is the HTTP response body/content]]></Body> </HttpResponse>
Web Service Connectors Web Services Overview API for executing services hosted on a remote system Uses HTTP for transmission of data Mirth Connect uses SOAP protocol XML "envelopes" define method to execute, parameters, etc. Available interface defined by a "WSDL" (Web Services Description Language) Web Service Listener/ Web Service Sender Web Service Listener: Listens on a specific interface or all interfaces Use default service or your own custom service Default service receives messages though method acceptMessage() Service name configurable Response can be generated by destination Message put in return element of response envelope Supports basic authentication
Web Service Connectors Web Service Sender: Can auto-populate fields and available operations based on given WSDL Generate default envelope based on selected operation Edit envelope to provide required parameters Can use Destination Mappings Supports web service authentication Supports persistent queues Invocation can be two-way (default) or one-way Supports binary attachments using MTOM (Message Transmission Optimization Mechanism) Surround HL7 messages with CDATA block Response can be forwarded to another channel Creates Response Map variable containing the response envelope from destination web service
Web Service Connectors Creating and using a Custom Web Service (using Java): Create a java class that extends the Mirth Connect class com.mirth.connect.connectors.ws.AcceptMessage See com.mirth.connect.connectors.ws.DefaultAcceptMessage for an example (source code available at http://www.mirthcorp.com/community/source-code and specifically at http://www.mirthproject.org/svn/trunk/server/src/com/mirth/connect/connectors/ws/) Build a JAR file containing the class Put the JAR file in custom-lib subfolder of the Mirth Connect installation folder Restart the Mirth Connect Server/Service In the Web Service Listener, select "Custom service" and specify the name of class that extends AcceptMessage
Read/write from/to a JMS queue or topic JMS Connectors JMS Reader/JMS Writer Java Message Service (JMS) is a Java-based API for sending messages between a provider and one or more clients Read/write from/to a JMS queue or topic Queue messages are consumed by one client, topic messages are consumed by multiple clients Use JNDI or specify connection factory Easy to add any additional properties Each JMS implementation will have its own set of required properties Equivalent to the -D option when executing java.exe JMS Reader: Supports durable connections for topics Messages will be queued when not connected Use optional selector expression to get a subset of available messages
JMS Connectors JMS Writer: Template field defines data to be placed in the JMS queue as the message Creates a Response Map variable with the message "JMS message sent"