### Install HL7 over HTTP Relay as a Windows Service Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Execute this command from the relay's bin directory to install the HL7 over HTTP Relay as a Windows Service. This allows the relay to start automatically after system reboots. ```bash C:\hl7overhttp-relay\bin> hl7overhttp-relay install ``` -------------------------------- ### Start HL7 over HTTP Relay on Windows Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Start the HL7 over HTTP Relay in console mode on Windows systems to test its functionality. This command should be executed from the relay's bin directory. ```bash C:\hl7overhttp-relay\bin> hl7overhttp-relay console ``` -------------------------------- ### HTTP Date Header Example Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/specification.html This example shows the format for the HTTP Date header, which indicates the time the message transmission was started. It is distinct from the HL7 message's internal MSH-7 timestamp. ```http Date: Tue, 15 Nov 1994 08:12:31 GMT ``` -------------------------------- ### Start HL7 over HTTP Relay on Linux/OSX Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Start the HL7 over HTTP Relay in console mode on Linux or macOS systems to test its functionality. This command should be executed from the relay's bin directory. ```bash hl7overhttp-relay/bin james$ ./hl7overhttp-relay console ``` -------------------------------- ### Check Java Version Source: https://hapifhir.github.io/hapi-hl7v2/installation.html Verify that a Java Virtual Machine (JVM) is installed and accessible. This command should be run in your terminal or command prompt. ```bash java -version ``` -------------------------------- ### Embedding Jetty Server for HL7 Messages Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/doc_non_hapi.html Embed a Jetty servlet container within a standalone application to receive HL7 messages. This example demonstrates starting the server, configuring the servlet, and handling incoming requests. ```java // The port to listen on int port = 8080; // Create a Jetty server instance Server server = new Server(port); Context context = new Context(server, "/Hl7Listener", Context.SESSIONS); Servlet servlet = new ExampleRawHl7OverHttpServlet(); /* * Adds the servlet to listen at * http://localhost:8080/Hl7Listener/Incoming */ context.addServlet(new ServletHolder(servlet), "/Incoming"); // Start the server server.start(); // .. let the application run .. /* * Later it will probably be appropriate to shut the server * down. */ server.stop(); ``` -------------------------------- ### Navigate to HAPI Directory Source: https://hapifhir.github.io/hapi-hl7v2/installation.html Change the current directory to your HAPI installation directory using the HAPI_HOME environment variable. This is typically done in a Windows Command Prompt. ```batch cd %HAPI_HOME% ``` -------------------------------- ### Enable HAPI HL7 over HTTP Relay (RedHat/CentOS) Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Use `update-rc.d --add` to enable the relay service on RedHat-based systems. This ensures the service starts on system boot. ```bash /etc/init.d$ update-rc.d --add hl7overhttp_relay ``` -------------------------------- ### Check Java Runtime Environment Version Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Verify that a Java Runtime Environment (JRE) version 1.5.xx or newer is installed on your system. This is a prerequisite for running the HL7 over HTTP Relay. ```bash ~ $ java -version ``` -------------------------------- ### Extract HAPI HL7 over HTTP Relay (Linux) Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Extract the relay archive to the desired installation directory on a Linux system. Adjust the path if you are not using `/opt/hl7overhttp-relay`. ```bash /opt$ sudo tar jxf ~/hapi-hl7overhttp-relay-XXX.tar.bz2 ``` -------------------------------- ### Sending Raw HL7 Messages with HohRawClientSimple Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/doc_non_hapi.html Example of sending a raw HL7 message using HohRawClientSimple. This client is suitable for embedded environments. It demonstrates setting up the client, providing optional authentication, and sending/receiving messages. ```java /* * http://localhost:8080/AppContext */ String host = "localhost"; int port = 8080; String uri = "/AppContext"; // Create a client HohRawClientSimple client = new HohRawClientSimple(host, port, uri); // Optionally, if credentials should be sent, they // can be provided using a credential callback IAuthorizationClientCallback authCalback = new SingleCredentialClientCallback("ausername", "somepassword"); client.setAuthorizationCallback(authCalback); // The ISendable defines the object that provides the actual // message to send String message = "MSH|^~\\&|||||200803051508||ADT^A31|2|P|2.5\r" + "EVN||200803051509\r" + "PID|||ZZZZZZ83M64Z148R^^^SSN^SSN^^20070103\r"; ISendable sendable = new RawSendable(message); try { // sendAndReceive actually sends the message IReceivable receivable = client.sendAndReceive(sendable); // receivavle.getRawMessage() provides the response System.out.println("Response was:\n" + receivable.getRawMessage()); // IReceivable also stores metadata about the message String remoteHostIp = (String) receivable.getMetadata().get(MessageMetadataKeys.REMOTE_HOST_ADDRESS); System.out.println("From:\n" + remoteHostIp); } catch (DecodeException e) { // Thrown if the response can't be read e.printStackTrace(); } catch (IOException e) { // Thrown if communication fails e.printStackTrace(); } catch (EncodeException e) { // Thrown if the message can't be encoded (generally a programming bug) e.printStackTrace(); } ``` -------------------------------- ### Send HL7 Messages with HohClientSimple Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/doc_hapi.html Example of sending HL7 messages using `HohClientSimple`. This client is suitable for embedded environments and supports optional authentication callbacks. It demonstrates message parsing, sending, and handling responses, including metadata. ```java /* * http://localhost:8080/AppContext */ String host = "localhost"; int port = 8080; String uri = "/AppContext"; // Create a parser Parser parser = PipeParser.getInstanceWithNoValidation(); // Create a client HohClientSimple client = new HohClientSimple(host, port, uri, parser); // Optionally, if credentials should be sent, they // can be provided using a credential callback IAuthorizationClientCallback authCalback = new SingleCredentialClientCallback("ausername", "somepassword"); client.setAuthorizationCallback(authCalback); // The ISendable defines the object that provides the actual // message to send ADT_A01 adt = new ADT_A01(); adt.initQuickstart("ADT", "A01", "T"); // .. set other values on the message .. // The MessageSendable provides the message to send ISendable sendable = new MessageSendable(adt); try { // sendAndReceive actually sends the message IReceivable receivable = client.sendAndReceiveMessage(sendable); // receivavle.getRawMessage() provides the response Message message = receivable.getMessage(); System.out.println("Response was:\n" + message.encode()); // IReceivable also stores metadata about the message String remoteHostIp = (String) receivable.getMetadata().get(MessageMetadataKeys.REMOTE_HOST_ADDRESS); System.out.println("From:\n" + remoteHostIp); /* * Note that the client may be reused as many times as you like, * by calling sendAndReceiveMessage repeatedly */ } catch (DecodeException e) { // Thrown if the response can't be read e.printStackTrace(); } catch (IOException e) { // Thrown if communication fails e.printStackTrace(); } catch (EncodeException e) { // Thrown if the message can't be encoded (generally a programming bug) e.printStackTrace(); } ``` -------------------------------- ### Example HL7 over HTTP Raw Message Servlet Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/doc_non_hapi.html Extend HohRawServlet to create a custom servlet for receiving and responding to HL7 messages. Configure a message handler and optionally an authorization callback. ```java /** * This class illustrates an example HL7 over HTTP * raw message servlet for receiving and responding to messages */ public class ExampleRawHl7OverHttpServlet extends HohRawServlet { /** * Constructor */ public ExampleRawHl7OverHttpServlet() { /* * The servlet must be provided an implementation * of IMessageHandler, such as the one which * is nested below */ setMessageHandler(new ExampleMessageHandler()); /* * Optionally, if we want to verify HTTP authentication, * we can specify an authorization callback */ IAuthorizationServerCallback callback = new SingleCredentialServerCallback("someusername", "apassword"); setAuthorizationCallback(callback); } /** * IMessageHandler defines the interface for the class which receives * and processes messages which come in */ private static class ExampleMessageHandler implements IMessageHandler { /** * This method is fired every time a message is received. The return value * contains the HL7 response value */ public IResponseSendable messageReceived(IReceivable theReceived) throws MessageProcessingException { String incomingRawMsg = theReceived.getRawMessage(); System.out.println("Received message:\n" + incomingRawMsg); // ... do some processing ... /* * Your application should generate an appropriate * HL7 ACK message here */ String ack = "MSH|....."; /* * If something goes horribly wrong, you can throw an * exception and an HTTP 500 error will be generated. * However, it is preferable to return a normal HL7 ACK * message with an "AE" response code to note an error. */ boolean somethingFailed = false; if (somethingFailed) { throw new MessageProcessingException(""); } // Return the raw response message return new RawSendable(ack); } } } ``` -------------------------------- ### Compile Demo Application Source: https://hapifhir.github.io/hapi-hl7v2/conf/compiler_demo.html Compile the Java source files for the demo application. Ensure the demo directory is the current working directory. ```bash cd app javac DemoView.java ``` -------------------------------- ### Import Public Key into Keystore Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/creating_keystores_by_importing.html Use this command to import a public certificate file (PEM or DER format) into a keystore. If the keystore does not exist, it will be created. Ensure the password entered matches the existing keystore's password if it already exists. ```bash $ keytool -import -alias trust_app_alias -file public.cert -keystore truststore.jks -storetype JKS Enter keystore password: trustpassword Re-enter new password: trustpassword Owner: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown Issuer: CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown Serial number: 50257625 Valid from: Fri Aug 10 16:59:17 EDT 2012 until: Thu Aug 10 16:59:17 EDT 2017 Certificate fingerprints: MD5: B9:5B:43:34:CA:00:82:EE:1F:7B:24:14:B6:3E:56:09 SHA1: 98:56:ED:0B:E0:F2:A6:20:2D:DD:66:72:5F:DF:7D:CB:BC:98:C7:AE Signature algorithm name: SHA1withRSA Version: 3 Trust this certificate? [no]: yes Certificate was added to keystore ``` -------------------------------- ### Build Demo JAR with ANT Source: https://hapifhir.github.io/hapi-hl7v2/conf/compiler_demo.html Invoke ANT to create a JAR file containing the generated conformance classes. This JAR is essential for the demo application's classpath. ```bash ant ``` -------------------------------- ### Embed Jetty Server for HL7 Message Reception Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/doc_hapi.html Embed a Jetty servlet container within a standalone application to receive HL7 messages. This example demonstrates starting a Jetty server and configuring a servlet to listen on a specific port and path. ```java // The port to listen on int port = 8080; // Create a Jetty server instance Server server = new Server(port); ServletContextHandler context = new ServletContextHandler("/Hl7Listener"); Servlet servlet = new ExampleRawHl7OverHttpServlet(); /* * Adds the servlet to listen at * http://localhost:8080/Hl7Listener/Incoming */ context.addServlet(new ServletHolder(servlet), "/Incoming"); // Start the server server.start(); // .. let the application run .. /* * Later it will probably be appropriate to shut the server * down. */ server.stop(); ``` -------------------------------- ### Execute Demo Application Source: https://hapifhir.github.io/hapi-hl7v2/conf/compiler_demo.html Run the compiled Java demo application. This will launch the user interface for generating HL7 messages. ```bash java DemoView ``` -------------------------------- ### Import PKCS#12 File into Keystore with Keytool Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/creating_keystores_by_importing.html Import a PKCS#12 file into a Java keystore using the `keytool` command. Specify source and destination keystore details, passwords, and aliases. You will be prompted for the source keystore password. ```bash $ keytool -v -importkeystore -destkeystore otherside.jks -deststorepass changeit -srckeystore private_key.pfx -srcstoretype PKCS12 -srcalias le-d7ffb209-fb59-4e0c-bd42-75157dccc563 -destalias lab_staging_system -destkeypass changeit Enter source keystore password: helloworld123 [Storing otherside.jks] ``` -------------------------------- ### Create Private Key with Keytool Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/generating_selfsigned_keys.html Use this command to generate a private key and store it in a JKS keystore. Remember to choose a strong password and a descriptive alias. The validity period can be adjusted as needed. ```bash $ keytool -genkey -alias my_app_alias -keyalg RSA -keysize 2048 -validity 1826 -keystore privatekeystore.jks -storetype JKS Enter keystore password: thepassword Re-enter keystore password: thepassword What is your first and last name? [Unknown]: _(provide a sensible value)_ What is the name of your organizational unit? [Unknown]: _(provide a sensible value)_ What is the name of your organization? [Unknown]: _(provide a sensible value)_ What is the name of your City or Locality? [Unknown]: _(provide a sensible value)_ What is the name of your State or Province? [Unknown]: _(provide a sensible value)_ What is the two-letter country code for this unit? [Unknown]: _(provide a sensible value)_ Is CN=Unknown, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct? [no]: yes Enter key password for (RETURN if same as keystore password): (hit enter) ``` -------------------------------- ### Retrieve a Conformance Component Source: https://hapifhir.github.io/hapi-hl7v2/conf/compiler_manual/Procedure3.htm Get an object reference for a component within a field. ```java ConformanceComponent_XX comp = field.getComponent_XX( ); ``` -------------------------------- ### Retrieve a Conformance Sub-Component Source: https://hapifhir.github.io/hapi-hl7v2/conf/compiler_manual/Procedure3.htm Get an object reference for a sub-component within a component, if one exists. ```java ConformanceSubComponent_XX subc = comp.getSubComponent(); ``` -------------------------------- ### Export Public Key with Keytool Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/generating_selfsigned_keys.html After creating the private key, use this command to export the public key into a PEM-formatted certificate file. This file can be shared with other parties. ```bash $ keytool -export -alias my_app_alias -keystore privatekeystore.jks -rfc -file public.cert Enter keystore password: thepassword Certificate stored in file ``` -------------------------------- ### Copy init.d script (Linux) Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Copy the provided init.d script to the system's init directory. This script is used to manage the relay as a daemon. ```bash /opt/hl7overhttp-relay/daemon$ sudo cp hl7overhttp_relay /etc/init.d/ ``` -------------------------------- ### Retrieve a Conformance Field Source: https://hapifhir.github.io/hapi-hl7v2/conf/compiler_manual/Procedure3.htm Get an object reference for a field within a segment. The 'n' parameter specifies the repetition number if needed. ```java ConformanceField_XX field = seg.getField_XX( n ); ``` -------------------------------- ### Build HAPI Base JAR with Maven Source: https://hapifhir.github.io/hapi-hl7v2/building.html Use this command to build the core HAPI library JAR. The output will be located in the hapi-base/target directory. ```bash mvn install ``` -------------------------------- ### Retrieve a Conformance Segment Source: https://hapifhir.github.io/hapi-hl7v2/conf/compiler_manual/Procedure3.htm Get an object reference for a segment within the message. The 'n' parameter specifies the repetition number if needed. ```java ConformanceSegment_XX seg = msg.getSegment_XX( n ); ``` -------------------------------- ### Configuring TLS for Encryption Profile Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/doc_non_hapi.html Example of configuring HohRawClientSimple to use TLS for the Encryption Profile by setting a TlsSocketFactory. This is necessary for secure communication. ```java // Create a client HohRawClientSimple client = new HohRawClientSimple(host, port, uri); // Set the socket factory to use TLS client.setSocketFactory(new TlsSocketFactory()); ``` -------------------------------- ### Level 1 Authorization Header Example Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/specification.html This header is used for Security Profile Level 1 to authenticate the sending system. Ensure the username:password is base64 encoded. ```http Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ``` -------------------------------- ### Disable HAPI HL7 over HTTP Relay (RedHat/CentOS) Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/relay_install.html Use `update-rc.d --del` to disable the relay service on RedHat-based systems. This prevents the service from starting on system boot. ```bash /etc/init.d$ update-rc.d --del hl7overhttp_relay ``` -------------------------------- ### Run HAPI TestPanel Source: https://hapifhir.github.io/hapi-hl7v2/installation.html Execute the HAPI TestPanel application. This command is specific to Windows and assumes you are in the HAPI_HOME directory. ```batch testpanel ``` -------------------------------- ### POST Request for HL7 Message Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/specification.html Example of an HTTP POST request to send an ADT message to a specific interface on a receiving system. The URI indicates the target queue or interface. ```http POST /Lab_Info_System/ADT HTTP/1.1 ``` -------------------------------- ### Configure Servlet Container with web.xml Source: https://hapifhir.github.io/hapi-hl7v2/hapi-hl7overhttp/doc_hapi.html Configure a servlet container to use your custom HAPI HL7 over HTTP servlet by defining it in the web.xml file. Map the servlet to a specific URL pattern. ```xml hl7_listener ca.uhn.hl7v2.examples.hoh.ExampleHl7OverHttpServletWithOneApplication hl7_listener /hl7list ``` -------------------------------- ### Initialize HAPI Context with Custom ModelClassFactory Source: https://hapifhir.github.io/hapi-hl7v2/configuring_hapi.html Configure HAPI by instantiating DefaultHapiContext and setting a custom ModelClassFactory. This custom factory is then used by the obtained PipeParser. ```java HapiContext context = new DefaultHapiContext(); context.setDefaultModelClassFactory(new MyOwnModelClassFactory()); PipeParser parser = context.getPipeParser(); ```