Automated deployment of FHIR Iguana on Azure VM

Introduction

The Automated deployment of FHIR Iguana on Azure VM illustrates how to deploy a virtual machine (VM) to Microsoft Azure and install Iguana on this VM automatically with prebuilt channels ready in order to demonstrate how to access and manipulate data using a FHIR based API.

This is achieved via an Azure Resource Manager (ARM) template. The purpose of the ARM template is to provide a cloud based deployment POC (proof of concept) example of Iguana as a web service that allows for health care information to be accessed and manipulated using a FHIR based API. The Iguana channels supplied contain code to map a set of data from an HL7 v2 message to a FHIR v3.0.0 patient resource, and then uploads it to a supplied FHIR server provisioned from Azure API for FHIR automatically. These operations support JSON data formats.

If you have any questions please contact us at support@interfaceware.com.

Note: Real world applications of FHIR are going to be more complex than this example.

The FHIR server is a proof-of-concept or foundation for building your own FHIR projects.

Please feel free to contact us at support@interfaceware.com to discuss you FHIR project needs!

Using the Template [top]

Note: You will need to have a Microsoft Azure account, and know how to fill in parameters for new resources.

See this Microsoft Azure getting started page for more information.

  1. Create a Microsoft FHIR Server using the ARM Template FHIR Server Samples Documentation, or create your own FHIR Azure resource. After deploying the FHIR Server, gather the following parameters:
    • Azure Active Directory domain name: The domain name of your Azure Directory. ex [interfaceware.com] or [interfaceware.onmicrosoft.com]
    • Azure Active Directory service client id: The service id of the FHIR Server resource.
    • Azure Active Directory service client secret: The service secret of the FHIR Server resource.
    • Azure Active Directory Authority: The authenticating link used for applications to connect to your domain. ex [https://login.microsoftonline.com/interfaceware.com] or [https://login.microsoftonline.com/interfaceware.onmicrosoft.com]
    • Azure Active Directory Audience: Unless this differs, this will typically be the FHIR server URL in the format: [https://<AZURE API FOR FHIR NAME>.azurehealthcareapis.com]
    • FHIR service URL: The FHIR Server URL. ex [https://<AZURE API FOR FHIR NAME>.azurehealthcareapis.com]

      Tip: The service client id and service client secret can be found in your azure dashboard by navigating to the “key vault” resource (via the search bar), clicking on your FHIR server’s key vault, and then selecting “secrets” in the side panel.

  2. To sign in to your Azure Active Directory, click the Deploy to Azure button below to navigate to the Azure deployment portal to configure the VM’s parameters to deploy the template:

    In addition, in the screenshot below, please fill in the parameters that were listed in the previous step:
  3. After verifying the parameters, deploy the template.

    Note: Depending on the type of Azure resource group chosen, deploying the ARM template may take 5-10 minutes to fully complete. Accessing the virtual machine before completion may cancel the Iguana provisioning process.

    It is important to make sure that the deployment is complete before accessing the virtual machine.

  4. Register Iguana using your members account, or by using a trial license.
  5. After registering Iguana, you will be greeted with the dashboard. It should contain 6 channels:
    1. CHN 1: Random HL7 ADT Message
    2. CHN1: HL7 From File
    3. CHN2: Random HL7 ADT Receiver
    4. CHN3: ADT To FHIR Mapper
    5. CHN4: FHIR Message to Server
    6. CHN5: Clear FHIR Server
  6. Of the 6 channels, 3 of them should already be running. The channels are CHN2: Random HL7 ADT Receiver, CHN3: ADT To FHIR Mapper, and CHN4: FHIR Message to Server. The dashboard overall can be seen in the screenshot below:
  7. To get the workflow started, first turn on the CHN5: Clear FHIR Server to clear out the server. Upon completion, a message like this should appear in the logs:

    Note: The channel will output a log message after it successfully clears out all existing records in the FHIR server. Depending on the number of records, the time duration until it completes deletion may vary.

  8. After the FHIR Server is cleared of records, start either or both CHN 1: Random HL7 ADT Message and CHN1: HL7 From File channels. CHN 1: Random HL7 ADT Message generates random HL7 v2 messages and pushes them to the CHN2: Random HL7 ADT Receiver channel and goes through the rest of the workflow, and CHN1: HL7 From File reads HL7 v2 messages from a file folder and also pushes them to CHN2: Random HL7 ADT Receiver channel and goes through the rest of the workflow.
  9. At this point, data should start flowing through all the way to the CHN4: FHIR Message to Server channel. Once this channel processes the message, it will appear on the FHIR Server. If the Microsoft dashboard manager was configured in addition to the FHIR Server, the results can be seen inside a web browser, and will look similar to the screenshot below:

How it works [top]

Once the ARM template is deployed, it puts the FHIR server parameters that were provided in the configuration page into the Iguana environment variables, which is IguanaEnv.txt file located in the working directory. After Iguana is licensed and the channels are run according to the steps above, The channels below use the variables in order to access and communicate with the FHIR server. The 6 channels in question can be seen below:

CHN 1: Random HL7 ADT Message

This channel generates a random HL7 ADT message every 10 seconds and then sends it via LLP to localhost:5145. The purpose of this channel is to simulate the generation of HL7 messages that would be coming inbound from an upstream source.

CHN1: HL7 From File

This channel polls a folder for HL7 messages and pushes them to the ADT to FHIR Filter Queue. The purpose of this channel is to simulate the retrieval of HL7 messages that may be placed on the local file system, or over an SFTP directory. The default location for this folder is the root of the operating system drive — typically the C:\ Drive. The full location is C:\FHIR, and contains 3 folders:

  • C:\FHIR\ADT\ : Contains HL7 messages that are awaiting processing
  • C:\FHIR\ERROR\ : Contains HL7 messages that had errors
  • C:\FHIR\PROCESS\ : Contains HL7 messages that were processed by the channel. The files are sorted with a timestamp, which is in the format of YYMMDD.

CHN2: Random HL7 ADT Receiver

This channel receives incoming HL7 messages over the specified LLP port. For this POC workflow, it receives messages directly from the LLP port assigned in the CHN 1: Random HL7 ADT Message channel.

CHN3: ADT To FHIR Mapper

This channel parses an incoming HL7 ADT message from either the CHN1: HL7 From File or CHN2: Random HL7 ADT Receiver and maps it to an outbound HL7 FHIR Resource.

The code for the main module of this channel can be seen below:

The key areas of interest are the FHIRprofiler and ADT_FHIR_PATIENT_MAP.lua modules declared in the top of the script.

FHIRprofiler
  • When mapping data to/from a FHIR resource object, a FHIR resource profile string is required to create the object within the translator.
  • Each type of resource profile the client can handle is defined in the file named resources.json located in other/fhir/profiles/ with a folder name corresponding to the FHIR version.
  • In the resource file, there is an object that stores the resource profile strings in JSON. These strings can be retrieved from www.hl7.org/fhir. (For example the JSON string for a Patient can be found at https://www.hl7.org/fhir/patient.profile.json)
  • FHIR resource objects can be programmatically created by having Lua parse and read these resource profile strings and then create  JSON objects pre-populated with nodes as defined within the profile. These objects are created in functions defined in modules located in shared/fhir/. These are used for step 2 to create the Patient object for mapping purposes.
ADT_FHIR_PATIENT_MAP.lua

This module contains the mappings that are used to convert an incoming HL7 message into a FHIR Resource. For this POC, the incoming message has been mapped to a FHIR patient resource. This can be seen in the screenshot below:

  

Relevant fields have already been mapped to conform to the Azure FHIR server conformance; however, these fields can be modified and changed to be adapted for a much more versatile patient if needed.

CHN4: FHIR Message to Server

This channel posts a FHIR message to the supplied server. These can be changed by modifying the environment variables in the system settings.

The code for the main module of this channel can be seen below:

The channel uses the variables provided from the environment variables that were created from the ARM template.

  1. The first step is to initialize the server, which gets information relating to the conformance statement. This is required in order to build the helper functions that will allow us to do specific post commands to the server for any FHIR resource we supply to it.
  2. The next step is to retrieve the token in order to have access to modify the server. This function is responsible for storing the token and ensuring that a valid token is used for each POST request.
  3. The last step is to upload the resource from the previous channel into the FHIR server. Server Responses (Success and Error):
Server Responses

The code is set up to return the response code from the FHIR server to show whether or not the result was successful. There are 2 types:

Errors

  • 400 error responses are usually returned when a request is performed with improper credentials, or the FHIR resource is missing specific parameters.
  • 500 error responses usually indicate that the server cannot be accessed, possibly because it is offline.
  • Microsoft Azure FHIR Servers employ error handling using basic FHIR “Operation Outcomes”. More comprehensive error responses should be researched and implemented if intending to follow the FHIR standard more closely and implement this in a production environment. For more information see https://www.hl7.org/fhir/operationoutcome.html.

Successes

  • The success response type for the FHIR post request is usually a 200 type response indicating the result was successful.

CHN5: Clear FHIR Server

This channel connects to a database and deletes all the records existing in it. The server address can be changed by modifying the FHIR Server Url located in the Iguana Environment Variables. The channel will also output a log message after it successfully clears out all existing records in the FHIR server. Depending on the number of records, the time duration until it completes deletion may vary.

 

More information [top]