Setting up for development

• Prereqs
  • Java 8
  • Maven
  • Git Tools
  • Docker Optional
  • Eclipse Optional
• Build the code
• Importing to Eclipse
• Running from Eclipse
• Installing the server
• Running the end-to-end tests from Eclipse

Prereqs

Java 8 (or above)

The IBM FHIR Server has been tested with OpenJDK 8, OpenJDK 11, and the IBM SDK, Java Technology Edition, Version 8. To install Java on your system, we recommend downloading and installing Java 11 OpenJ9 from https://adoptopenjdk.net.

Maven

The IBM FHIR Server is a multi-module Maven project. Any recent version of Maven should work, the team uses 3.6.3. Download from the Maven download site.

Git Tools

To download this repository or a fork, you should have Git Tools installed. Download and install from git-scm.

Docker

Optional: If you intend to use IBM FHIR Server in a docker container or build the docker image. It's recommended you install Docker Desktop.

Eclipse

Optional: If you want or do use Eclipse.

Note: do not attempt to mix the Liberty Developer Tools with Spring Boot tools - they appear to conflict.

Download Eclipse IDE for Enterprise Java Developers and install the following plugins:

• TestNG - Use 'Help > Install New Software', Enter into the Work with field, the following https://dl.bintray.com/testng-team/testng-eclipse/, and install all items.
• IBM Liberty Developer Tools. This can be installed via the Marketplace.
• Checkstyle configuration plugin for M2Eclipse, using use 'Help > Install New Software'. Link to Update Site

Once installed, navigate to Preferences and make the following changes:

1. Validation -> uncheck the Build checkbox next to JSON Syntax Validator, JSON Validator, Open API 3.0 Validator, and XML Validator.

   This step speeds up workspace builds by avoiding needless validation of sample files. Manual validation can still be performed by right-clicking a file and choosing Validate.

2. Import the Style Guide Style Guide, remember to import the formatting. Click Eclipse > Preference. Click on Java > Code Style > Formatter. Import the Style Guide - TeamRules.xml You will need to import the Style Guide for each unique Eclipse workspace.

3. Configure 'General > Editors > Text Editors' with 'Insert spaces for tabs' (4 spaces).

4. Import the Code Template Click Eclipse > Preference. Click on Java > Code Style > Code Template. Import the Template - Template.xml

You are now ready to build the code, setup Open Liberty and import the projects.

Build the code

Git fork and clone the IBM FHIR Server repository following the GitHub Standard Fork & Pull Request Workflow. For instance, git clone [email protected]:<myuser>/FHIR.git where <myuser> is your GitHub user or GitHub organization.

Once cloned locally, execute the following from the root of the repository:

1. mvn clean install -f fhir-examples

The fhir-examples project contains every FHIR R4 spec examples, some FHIR Profile examples along with additional examples that we generate for our tests. Since it rarely changes, we kept it out of the main build for now.

2. mvn clean install -f fhir-parent

This command invoke the IBM FHIR Server build with all of the tests. If you want to skip the tests, add -DskipTests.

After the build completes, you can navigate fhir-install/target to find the zip installable.

3. Optionally, once the build completes, you can build a docker image from the installable by running: docker build fhir-install.

Import to your IDE / editor of choice

The IBM FHIR Server team is using Eclipse; feel free to use anything you want while honoring the Style Guide and Code Template.

Importing to Eclipse

1. Import the Projects - File > Import > Maven > Existing Maven Projects and M2Eclipse configures the projects. (import all projects from the repository).

2. Delete the extraneous EAR projects for each project used in the FHIR server webapps. There is a Liberty Tools issue which leads to the automatic creation of extraneous. These projects are only generated a single time and should be deleted from your system (delete all EAR projects). Note, these may not appear until you add the war files to the Open Liberty server in Eclipse.

3. If you import fhir-tools, you may be prompted to fix the m2e connector for maven-plugin-plugin. The error details are: Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-plugin-plugin:3.6.0:descriptor (execution: mojo-descriptor, phase: process-classes)

• In this case, it is recommended you 'Setup Maven plugin connectors', and click Finish.

4. If you are prompted to install the m2e connector for Checkstyle Plugin, please do install and setup. Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-checkstyle-plugin:3.1.0:check (execution: default, phase: validate)

Running from Eclipse

To run the IBM FHIR Server from Eclipse you must first install a Liberty Server. Due to special packaging requirements of the FHIR persistence layer, its simplest to "install" the Server to a local directory first, then Define a Server in eclipse and point it at the install location.

Installing the server

After building the project, navigate to fhir-install/target, unzip fhir-server-distribution.zip, and enter the directory; then

1. From a terminal, execute ./install.sh <targetDir> or install.bat <targetDir> depending on your platform. This will install OpenLiberty to that location with a single server named "fhir-server".
2. Once done installing, navigate to <targetDir>/wlp/usr/servers/fhir-server/apps and delete the apps (rm -f *.war) contained in that directory. We're going to replace them with the apps from Eclipse.
3. From eclipse, create a New Server, select IBM/Liberty Server, Choose an existing installation, and point it at the server you just installed - <targetDir>/wlp.
4. From eclipse, copy the folders tenant1 and tenant2 from fhir-server/liberty-config-tenants to Liberty Runtime/servers/fhir-server/config. After the copy you should have three folders there: default, tenant1 and tenant2. (if the server is running, you will need to stop and re-start it)
5. From eclipse, copy fhir-operation-test/target/fhir-operation-test-<VERSION>-tests.jar to Liberty Runtime/servers/fhir-server/userlib/, replacing VERSION with the current version. If the server is running, you will need to stop and re-start it.
6. Right-click on the Liberty Server > Add and Remove > Add all the War files to the server. Note, I added without removing the ghosted applications.
7. If needed, update your Liberty server's server.xml with the master copy that is under fhir-server/liberty-config. This is needed if eclipse decides to rewrite the webApplication element which can lose our common library reference around line 58.

Running the server

Once configured, you can start and stop the server from the Servers view.

Running the end-to-end tests from Eclipse

With a running server on localhost:9443, navigate to fhir-server-test/src/test/java, right-click testng.xml, and Run As a TestNG Suite.

Alternative endpoints and client settings can be configured at fhir-server-test/src/test/resources/test.properties.