HAPI HL7v2

https://hapifhir.github.io/hapi-hl7v2/
Admin
HAPI HL7v2 is an open-source Java API for parsing, generating, and manipulating HL7 version 2.x...
Tokens:37,192
Snippets:580
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### 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<String> 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<Message> 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<String>, 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<String> {

		/**
		 * This method is fired every time a message is received. The return value
		 * contains the HL7 response value 
		 */
		public IResponseSendable<String> messageReceived(IReceivable<String> 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 <my_app_alias>  
(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 <public.cert>
```

--------------------------------

### 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
<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
    <servlet>
        <servlet-name>hl7_listener</servlet-name>
        <servlet-class>ca.uhn.hl7v2.examples.hoh.ExampleHl7OverHttpServletWithOneApplication</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>hl7_listener</servlet-name>
        <url-pattern>/hl7list</url-pattern>
    </servlet-mapping>
</web-app>

```

--------------------------------

### 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();
```
Tokens:
Raw