Recipe: IBM FHIR Server – Adding a Custom Extended Operation to the IBM FHIR Server

The IBM FHIR Server has support for extended operations beyond the standard C-R-U-D. The Extended Operations are supported at the System, Resource, and Instance levels. Operations are packaged as JAR files, and the IBM FHIR Server loads the specific Operation using the Java ServiceLoader framework at startup. More implementation specific details are at FHIROperationFramework.

The IBM FHIR Server repository builds a number of operations, release to Maven Repository, and bundles a subset automatically with the Docker container. Some of the bundles operations include Healthcheck, Terminology, BulkData Import, BulkData Export, Reindex, Everything, Erase, Convert, Document and Validate. The IBM FHIR Server maintains the Capability Statement which advertises the System, Type and Instance operations on the metadata endpoint.

The IBM FHIR Server can take any configured custom extended operation, such as HelloOperation which is part of the fhir-operation-test.

This document outlines how to add a custom extended operation to the IBM FHIR Server.

Let me show you how to add a custom extended operation to an IBM FHIR Server container Docker: ibmcom/ibm-fhir-server.

Recipe

1. Download the fhir-server-config.json

curl -L -o fhir-server-config.json \
    https://raw.githubusercontent.com/IBM/FHIR/main/fhir-server/liberty-config/config/default/fhir-server-config.json
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  8423  100  8423    0     0  35095      0 --:--:-- --:--:-- --:--:-- 34950

2. Download the fhir-operation-test-*-tests.jar. Note, you should pick the most recent release.

curl -L -o fhir-operation-test-4.8.3.jar \
    https://repo1.maven.org/maven2/com/ibm/fhir/fhir-operation-test/4.8.3/fhir-operation-test-4.8.3-tests.jar
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 12393  100 12393    0     0  58734      0 --:--:-- --:--:-- --:--:-- 58734

3. Create a directory called userlib, don’t put the jar in the userlib yet.

mkdir -p userlib

4. Start the Docker container, and capture the container id. It’s going to take a few moments to start up as it lays down the test database.

docker run -d -p 9443:9443 -e BOOTSTRAP_DB=true \
  -v $(pwd)/fhir-server-config.json:/config/config/default/fhir-server-config.json \
  -v $(pwd)/userlib/:/config/userlib/ ibmcom/ibm-fhir-server
a096978867195ff6e610c36cdba77ff423c31c0ad488a7390f42cef6e89e7fd0

5. Check the logs until you see:

docker logs a096978867195ff6e610c36cdba77ff423c31c0ad488a7390f42cef6e89e7fd0
...
[6/16/21, 15:31:34:533 UTC] 0000002a FeatureManage A   CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 17.665 seconds.

6. Check the Type and Instance operations, you can check using this curl/jq command.

curl -k --location --request GET 'https://localhost:9443/fhir-server/api/v4/metadata' \
    | jq -r '.rest[].resource[].operation[].name' | sort -u
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 1096k    0 1096k    0     0   103k      0 --:--:--  0:00:10 --:--:--  259k
apply
closure
convert
document
erase
everything
expand
export
lookup
reindex
subsumes
translate
validate
validate-code

Note, that the hello operation is not displayed. The CapabilityStatement is best looked at selectively, since it’s such a big document, thus the use of jq.

7. To check the System Level operations, you can check using this curl/jq command.

curl -k --location --request GET 'https://localhost:9443/fhir-server/api/v4/metadata' \
    | jq -r '.rest[].operation[].name'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 1096k    0 1096k    0     0  2592k      0 --:--:-- --:--:-- --:--:-- 2592k
bulkdata-status
closure
convert
export
healthcheck
import
reindex

Note, that the hello operation is not displayed.

8. Copy over the fhir-operation-test-*-tests.jar to userlib/.

9. Restart the docker container

docker restart a096978867195ff6e610c36cdba77ff423c31c0ad488a7390f42cef6e89e7fd0

10. Check the logs until you see:

docker logs a096978867195ff6e610c36cdba77ff423c31c0ad488a7390f42cef6e89e7fd0
...
[6/16/21, 15:31:34:533 UTC] 0000002a FeatureManage A   CWWKF0011I: The defaultServer server is ready to run a smarter planet. The defaultServer server started in 17.665 seconds.

11. To check the System Level operations, you can check using this curl/jq command.

curl -k --location --request GET 'https://localhost:9443/fhir-server/api/v4/metadata' \
    | jq -r '.rest[].operation[].name'
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 1096k    0 1096k    0     0  2562k      0 --:--:-- --:--:-- --:--:-- 2556k
bulkdata-status
closure
convert
export
healthcheck
hello
import
reindex

You should see the hello operation listed.

12. Now you can execute the hello operation.

curl -k --location --request GET 'https://localhost:9443/fhir-server/api/v4/$hello' \
    -v -u fhiruser:change-password
...
* Connection state changed (MAX_CONCURRENT_STREAMS == 200)!
< HTTP/2 200 
< date: Fri, 09 Jul 2021 23:48:33 GMT
< content-length: 0
< content-language: en-US
< 
* Connection #0 to host localhost left intact
* Closing connection 0

You’ve now seen how to add a jar file to the userlib in a running container that adds the custom operation HelloOperation.

References

• IBM FHIR Server: User’s Guide
• IBM FHIR Server: Operations Framework.