Skip to content

Migration Guide

Jump to bottom
JP edited this page Apr 22, 2022 · 8 revisions

Overview

Version 0.5.0 of the cqf-ruler contains numerous updates and changes to increase compatibility with the base hapi-fhir-jpaserver-starter project, improve the maintainability of code, and enhance test coverage throughout the project. Additionally, it adds a runtime extensibility API such that downstream consumers don't need to fork the entire codebase, they can simply write plugins for their use case.

Unfortunately, achieving all of the above required several breaking changes. This guide describes those and discusses how to migrate to the new version of the cqf-ruler.

Breaking Changes Summary

  • Plugin API
  • New base server URL
  • New configuration system
  • Deprecation of multi-version Docker containers
  • New Docker Registry - alphora/cqf-ruler

Plugin API

Previously, new FHIR operations were added to the cqf-ruler by creating "Operation Providers" within the main codebase. While this is still possible, the cqf-ruler now groups operations into IG-specific modules that can be seen here. Changes or additions to modules supported by the cqf-ruler should be made with the module's respective directory. New IGs are supported by adding an IG-specific module and adding the operations there.

Additionally, the cqf-ruler supports picking up new dynamically modules at startup. A full example of a runtime plugin is available here. Further discussion/documentation of plugins is available on the Architecture page.

If you have a fork of the cqf-ruler to add additional FHIR operations, request/response interceptors, etc., please consider refactoring the code so that you need only maintain the operation-specific logic. This will make future updates easier to perform and allow you to contribute non-proprietary code back to the main codebase.

Base server URL

In prior versions of the cqf-ruler there were two distinct servers available, one for FHIR version dstu3 and one for FHIR r4. The base URLs for the servers were: <base>/cqf-ruler-dstu3/fhir and <base>/cqf-ruler-r4/fhir respectively. The current version of the ruler has adopted the pattern in the upstream hapi-fhir-jpaserver-starter project. There's only one server codebase that handles both versions. The version selected is runtime configuration option, done in exactly the same way as the upstream hapi-fhir-jpaserver-project. the base URL drops the cqf-ruler-* prefix and is always <base>/fhir irrespective of the FHIR version selected.

Any URLs referencing a cqf-ruler API should be pointed at <base>/fhir (or <base>/cds-services as appropriate).

If needed for backwards compatibility the base context path of the cqf-ruler container can be set using the SERVER_SERVLET_CONTEXT_PATH environment variable. See the example docker-compose file below:

version: '3.2'
services:
  ########################
  # CQF-Ruler
  ########################
  cqf-ruler:
    image: "alphora/cqf-ruler:latest"
    container_name: "cqf-ruler"
    restart: always
    ports:
      - 80:8080
    environment:
      - HAPI_FHIR_SERVER_ADDRESS=http://localhost/cqf-ruler-r4/fhir
      - HAPI_FHIR_TESTER_HOME_SERVER_ADDRESS=http://localhost/cqf-ruler-r4/fhir
      - SERVER_SERVLET_CONTEXT_PATH=/cqf-ruler-r4

Configuration

Configuration used to be managed primarily through mounting hapi.properties files to the cqf-ruler container which contained the appropriate configuration options. This made it incompatible with some container runtimes such as podman. The current version of the cqf-ruler now follows the pattern established by the upstream hapi-fhir-jpaserver-starter project and uses a standard approach provided by the Spring framework to read configuration from environment variables. This means that nearly all configuration can simply be done with flags provided to the cqf-ruler container launch, and that all the configuration documentation available on the hapi-fhir wiki applies equally to the ruler.

As an example, to run the cqf-ruler from a docker container in dstu3 mode, use the following command:

docker run -e hapi.fhir.fhir_version=DSTU3 -p 8080:8080 alphora/cqf-ruler

While it's still possible to mount a configuration file, it's generally preferable for users to check whatever configuration was needed for their specific deployment of the cqf-ruler, and convert those to the corresponding environment variables.

Docker Container

The cqf-ruler docker container no longer starts up both a dstu3 and an r4 version of the cqf-ruler. This reduces memory consumption if only one version is needed. It does mean that any deployments that were using both versions of the cqf-ruler need to deploy TWO instances, each one configured for the appropriate FHIR version. Since the base URLs are by default the same, a proxy server or some other means of disambiguation between the two instances will be needed in the deployment infrastructure.

New Docker Registry

Dynamic Content Group has been migrating to new branding under the name "Alphora". The Docker registry has been changed to reflect. All references to contentgroup/cqf-ruler should be redirected to alphora/cqf-ruler.

Clone this wiki locally