HAPI FHIR includes a web UI that can be used to test your server implementation. This UI is the same UI used on the http://fhirtest.uhn.ca public server.

The Tester is a Maven WAR Overlay, meaning that you create your own WAR project (which you would likely be doing anyway to create your server) and the overlay drops a number of files into your project.

Adding the Overlay

These instructions assume that you have an exsiting web project which uses Maven to build. The POM.xml should have a "packaging" type of "war".

Adding the overlay to your project is relatively simple. First, add the "hapi-fhir-testpage-overlay" dependency to the dependencies section of your POM.xml file.

<dependencies>
	<!-- ... other dependencies ... -->
	<dependency>
		<groupId>ca.uhn.hapi.fhir</groupId>
		<artifactId>hapi-fhir-testpage-overlay</artifactId>
		<version>2.4</version>
		<type>war</type>
		<scope>provided</scope>		
	</dependency>
	<dependency>
		<groupId>ca.uhn.hapi.fhir</groupId>
		<artifactId>hapi-fhir-testpage-overlay</artifactId>
		<version>2.4</version>
		<classifier>classes</classifier>
		<scope>provided</scope>		
	</dependency>
</dependencies>

Then, add the following WAR plugin to the plugins section of your POM.xml

<build>
	<plugins>
		<!-- ... other plugins ... -->
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-war-plugin</artifactId>
			<configuration>
				<overlays>
					<overlay>
						<groupId>ca.uhn.hapi.fhir</groupId>
						<artifactId>hapi-fhir-testpage-overlay</artifactId>
					</overlay>
				</overlays>
			</configuration>
		</plugin>
	</plugins>
</build>

Then, create a Java source file called FhirTesterConfig.java and copy in the following contents:

package ca.uhn.example.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

import ca.uhn.fhir.context.FhirVersionEnum;
import ca.uhn.fhir.to.FhirTesterMvcConfig;
import ca.uhn.fhir.to.TesterConfig;

//@formatter:off
/**
 * This spring config file configures the web testing module. It serves two
 * purposes:
 * 1. It imports FhirTesterMvcConfig, which is the spring config for the
 *    tester itself
 * 2. It tells the tester which server(s) to talk to, via the testerConfig()
 *    method below
 */
@Configuration
@Import(FhirTesterMvcConfig.class)
public class FhirTesterConfig {

	/**
	 * This bean tells the testing webpage which servers it should configure itself
	 * to communicate with. In this example we configure it to talk to the local
	 * server, as well as one public server. If you are creating a project to 
	 * deploy somewhere else, you might choose to only put your own server's 
	 * address here.
	 * 
	 * Note the use of the ${serverBase} variable below. This will be replaced with
	 * the base URL as reported by the server itself. Often for a simple Tomcat
	 * (or other container) installation, this will end up being something
	 * like "http://localhost:8080/hapi-fhir-jpaserver-example". If you are
	 * deploying your server to a place with a fully qualified domain name, 
	 * you might want to use that instead of using the variable.
	 */
	@Bean
	public TesterConfig testerConfig() {
		TesterConfig retVal = new TesterConfig();
		retVal
			.addServer()
				.withId("home")
				.withFhirVersion(FhirVersionEnum.DSTU2)
				.withBaseUrl("${serverBase}/fhir")
				.withName("Local Tester")
			.addServer()
				.withId("hapi")
				.withFhirVersion(FhirVersionEnum.DSTU2)
				.withBaseUrl("http://fhirtest.uhn.ca/baseDstu2")
				.withName("Public HAPI Test Server");
		
		/*
		 * Use the method below to supply a client "factory" which can be used 
		 * if your server requires authentication
		 */
		// retVal.setClientFactory(clientFactory);
		
		return retVal;
	}
	
}
//@formatter:on

Note that the URL in the file above must be customized to point to the FHIR endpoint your server will be deployed to. For example, if you are naming your project "myfhir-1.0.war" and your endpoint in the WAR is deployed to "/fhirbase/*" then you should put a URL similar to http://localhost:8080/myfhir-1.0/fhirbase

Next, create the following directory in your project if it doesn't already exist:
src/main/webapp/WEB-INF

In this directory you should open your web.xml file, or create it if it doesn't exist. This file is required in order to deploy to a servlet container and you should create it if it does not already exist. Place the following contents in that file, adjusting the package on the FhirTesterConfig to match the actual package in which you placed this file.

<servlet>
		<servlet-name>spring</servlet-name>
		<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
		<init-param>
			<param-name>contextClass</param-name>
			<param-value>org.springframework.web.context.support.AnnotationConfigWebApplicationContext</param-value>
		</init-param>
		<init-param>
			<param-name>contextConfigLocation</param-name>
			<param-value>ca.uhn.example.config.FhirTesterConfig</param-value>
		</init-param>
		<load-on-startup>2</load-on-startup>
	</servlet>
	<servlet-mapping>
		<servlet-name>spring</servlet-name>
		<url-pattern>/tester/*</url-pattern>
	</servlet-mapping>

Customizing the Overlay

The most important customization required is to set the FHIR server base URL in the hapi-fhir-tester-config.xml configuration file created during the previous step.

Beyond this, the entire tester application is built from a number of Thymeleaf template files, any of which can be replaced to create your own look and feel. All of the templates can be found in your built war (after running the Maven build), or in the target directory's staging area, in WEB-INF/templates. By placing a file with the same path/name in your src/main/webapp/WEB-INF/templates directory you can replace the built in template with your own file.

A Complete Example

The "Restful Server Example" project contains a complete working example of the FHIR Tester as a part of its configuration. You may wish to browse its source to see how this works:
https://github.com/jamesagnew/hapi-fhir/tree/master/restful-server-example

Authorization

The testing UI uses its own client to talk to your FHIR server. In other words, there are no special "hooks" which the tested uses to retrieve data from your server, it acts as an HTTP client just like any other client.

This does mean that if your server has any authorization requirements, you will need to configure the tester UI to meet those requirements. For example, if your server has been configured to require a HTTP Basic Auth header (e.g. Authorization: Basic VVNFUjpQQVNT) you need to configure the tester UI to send those credentials across when it is acting as a FHIR client.

This is done by providing your own implementation of the ITestingUiClientFactory interface. This interface takes in some details about the incoming request and produces a client.

Back to top

Reflow Maven skin by Andrius Velykis.