How to use WebService for HL7 bi-directional interface with I-CARE
EHR System Requirements
Contact your EHR vendor and/or IT department to verify the following:
1.
Do you need
to purchase a separate interface for your EHR system to export HL7 data and/or
run queries with I-CARE using Web Services?
2.
Does your EHR
system support either the ASMX Web Service (SOAP interface, .asmx based on XMLSerializer), WCF
Service (SOAP interface, .svc based on DataContractSerializer),
or gRPC-Web (Google Remote Procedure Call (RPC)
framework, ProtoBuf for on-wire serialization)
standards?
I-CARE Bi-directional Interfaces
The below information is needed by your EHR vendor/IT department to
implement a bi-directional HL7 interface with I-CARE to upload HL7 messages
(VXU and ADT) or query the I-CARE database (QBP).
I-CARE uses the SOAP protocol (ASMX or WCF), or ProtoBuf
protocol (gRPC-Web) over HTTPS to communicate with
clients. I-CARE recommends using the ProtoBuf (gRPC-Web), the newest standard from Google. CDC recommends
using the ASMX Web Service (older version).
All three clients are compatible with I-CARE.
ASMX
ASMX SOAP interface base address - https://icarehl7.dph.illinois.gov/cdc/
ASMX SOAP interface WSDL (same address) - https://icarehl7.dph.illinois.gov/cdc/
See the IIS
Transport (SOAP) standards page for CDC implementation of the EHR-IIS
Web Service (ASMX).
To generate the initial SOAP request for ASMX, the recommendation is
to use the SoapUI Open-Source
API Testing Tool. These SOAP requests can be used to create your own client.
WCF
WCF SOAP interface base address - https://icarehl7.dph.illinois.gov
WCF SOAP interface WSDL - https://icarehl7.dph.illinois.gov/?wsdl
This is Microsoft’s Windows Communication Web Service. To generate
the initial SOAP request for WCF, the recommendation is to use the SoapUI Open
Source API Testing Tool. These SOAP requests can be used to create your
own client.
gRPC
gRPC-Web
interface base address - https://icarehl7.dph.illinois.gov/gRPC/
gRPC-Web proto file IIS.proto (zip) (Visual
Studio instructions file to generate the ProtoBuf
Client)
To create the gRPC-Web client use the ProtoBuf file - IIS.proto (zip). I-CARE supports gRPC-Web
only. Plans for pure gRPC support will be available in the near future.
To generate the gRPC-Web client
follow these
instructions (using IIS.proto (zip) to
generate a pure gRPC client, then add
gRPC-Web support to the gRPC
client. gRPC-Web can run with HTTP/1.1 or HTTP/2.
Java can also be used to generate the gRPC-Web Java Client.
HL7 I-CARE Service Client Demonstration
To demonstrate how the HL7 Web Service works, a Service Client was
developed, using .NET 4.8. The client requires the installation of .NET version
4.8 and supports ASMX, WCF, or gRPC-Web protocols.
Disclaimer: I-CARE does not have the resources to help support
the development of your own Service Client application. This is the
responsibility of your EHR/IT department. Feel free to use the client source
code to develop your own client.
- Stand Alone (EXE) Client App (zip),
.NET 4.8 required.
- Source Code for Stand Alone (EXE) Client App
(zip),
Visual Studio 2022 required.
VXU Messages
Start the Stand Alone (EXE) Client App. Enter your User
Name (usually starts with 888) and password. Select CDC (ASMX), WCF, or gRPC (gRPC-Web) type of Service.
Go to [HL7 Messages] Tab and paste the VXU message into [Generated] box. For
testing purposes use the word TEST in MSH-4 field. Click on [Send HL7 Message]
button. The system should respond with an ACK message.
QBP messages (HL7 queries)
Start the Stand Alone (EXE) Client App. Enter your User
Name (usually starts with 888), password and the word TEST in [HL7 Site]
field. Select WCF or ASMX type of
Service. Enter your search parameters and click on [QBP^Q11] button to generate
your QBP message.
Click on [Send HL7 Message]
Button. The system responds with the HL7 message accordingly.
To use I-CARE test system, always use the word TEST in
the MSH-4 field.