FHIR Bulk Export System API - Implementation Template
home
This API implementation template is a shared component of MuleSoft Accelerators, which accelerate the implementation of essential integration use cases.
The solution includes pre-built APIs, connectors, and integration templates that help unlock business-critical data from external systems and guide you in adopting best practices synthesized from thousands of customer implementations. Use these assets as is or extend them to meet your company’s unique needs.
Overview
This asset provides a framework for implementation of the HLS FHIR Bulk Export System API specification.
The FHIR Bulk Export System API provides an interface for performing a FHIR bulk export from a FHIR bulk server. It allows you to:
- Initiate the bulk export.
- Query for status.
- Download bulk export results in NDJSON when ready.
Getting started
|
The Getting Started with MuleSoft Accelerators guide provides general information on getting started with the accelerator components. This includes instructions on setting up your local workstation for configuring and deploying the applications. |
Once your workstation has been set up and the application template imported into Anypoint Studio, proceed with the Prerequisites section.
Prerequisites
This implementation template has the following dependencies:
Using Authenticated SMART Bulk Data Server
In order to authenticate with the SMART Bulk Data Server a number of steps need to be completed. The following steps will outline how this is accomplished.
Navigate to the server webpage https://bulk-data.smarthealthit.org/. In the Authentication section click the "JWKS" button and click the "Generate" drop down and select "Generate RS384". This will generate new credentials in the text box below. In the "Access Token Lifetime" drop down select "1 hour". At the bottom of the page in the "Launch Configuration" section click the "Download as JSON" button to save the configuration to file. (Note that this configuration is only good for 1 hour.)
Open up the saved configuration file in a text editor. In the "jwks.keys" section select the key with "key_ops" of "sign" which should be the second one. Copy that key structure and convert from JWK to PEM. Once converted copy the private key text including the begin and end declarations and save it into the project file src/main/resources/smart-bulk-data.private.pem.rsa. For testing purposes, use an online JWK to PEM converter such as the one by 8gwifi.org.
In the project src/main/resources directory, run the following command to convert the RSA key to PKCS for use by the application.
> openssl pkcs8 -topk8 -inform PEM -in smart-bulk-data.private.pem.rsa -out smart-bulk-data.private.pem -nocryptIn the src/main/resources directory in the config-local.yaml file update the bulk-export-server.basePath to the path provided in the downloaded config file in the "fhir_url" field.
In the src/main/resources directory in the config-secured-local.yaml file update bulk-export-server.clientId with the value from the downloaded config file in the "client_id" field and update the bulk-export-server.kid value with the value from the downloaded config file in the signing key with the "kid" field name.
Deployment
Each Accelerator implementation template in Exchange includes Bash and Windows scripts for building and deploying the APIs to CloudHub. These scripts depend on repositories, global settings, deployment profiles, and associated properties configured in the Maven settings.xml file. In particular, make sure the common properties for your environment have been provided in the CloudHub-DEV profile (e.g., Anypoint Platform client ID and secret).
For additional details, please refer to the Application Deployment section of the Getting Started Guide.
Required property overrides
Many templates can also be run from Anypoint Studio without having to customize the Run/Debug profiles. However, some templates make use of hidden deployment properties to protect sensitive information (e.g., passwords and secret keys). These properties must be supplied to the runtime by updating the configuration profile and adding them as VM arguments. At a minimum, the following properties must be customized to reflect the target deployment environment.
At a minimum, the following properties must be customized to reflect the target deployment environment.
| Property Name | Description |
|---|---|
| api.autodiscoveryID | Required if using API Manager to secure this API |
| https.host | sets the service host interface. It should be configured in config-<mule.env>.yaml file. (Defaults to 0.0.0.0 for all interfaces) |
| https.port | sets the service port number. It should be configured in config-<mule.env>.yaml file. (Default 8082) |
| keystore.alias | sets the alias to the keystore. It should be configured in config-<mule.env>.yaml file |
| keystore.path | sets the path to the key file. Key should be available in /src/main/resources/keystore. It should be configured in config-<mule.env>.yaml file |
| keystore.keypass | sets keystore keypass to support HTTPS operation. It should be encrypted and configured in config-secured-<mule.env>.yaml file |
| keystore.password | sets keystore password to support HTTPS operation. It should be encrypted and configured in config-secured-<mule.env>.yaml file |
| bulk-export-server.protocol | sets the protocol to be used when connecting to the bulk export server. (http/https) It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.host | sets the host name to be used when connecting to the bulk export server. It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.basePath | sets the base path string to be used when connecting to the bulk export server. It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.connectionIdleTimeout | sets the idle timeout in milliseconds for the bulk export connection. It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.responseTimeout | sets the response timeout in milliseconds for HTTP requests for status and data download. This response timeout should be set to something high like 60000 milliseconds or more to give ample time to download the requested file from the bulk server. It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.useAuth | sets a flag which signals if the app should use authentication or not. (true/false) It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.tokenurl | if useAuth is set to 'true' this sets the token URL used with authentication. It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.reconnection.frequency | sets the reconnection frequency in milliseconds for the bulk export connection. (2000) It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.reconnection.attempts | sets the number of reconnection attempts for the bulk export connection. (2) It should be configured in config-<mule.env>.yaml file |
| bulk-export-server.clientId | sets the authentication clientId of the bulk export server. It should be configured in config-secure-<mule.env>.yaml file |
| bulk-export-server.kid | sets the authentication kid value of the bulk export server. It should be configured in config-secure-<mule.env>.yaml file |
Tested and verified
This solution was developed and tested on Anypoint Studio 7.15 and Mule Runtime 4.4.0.
Testing
Use Advanced Rest Client or Postman to send a request over HTTPS. The template includes a Postman collection in the src/test/resources folder. Update the collection variable(s) after successful import.
Additional resources
- Please refer to the attached link on how to generate the Keystore.
- Please refer to the attached link on how to secure the configuration properties.
- The Developer guide tab provides information generated from the DataWeave scripts included in the project.
- Refer to the Accelerators documentation home for more information about the MuleSoft Accelerators.