tarr2fhir API

Convert tarr2fhir Sync4Genes - Versiti and GenDx

Introduction

This repository contains an API that can translate GenDx xml format to fhir. Input is either a single xml or a collection of all HLA loci xmls for a single Sample/Subject. These input files are generated by Versiti using the Gendx format for Sync4Genes.

Details

Two API EPs are available

1. /tarr/convert2Fhir - this EP accepts a single input Xml generated based on the Tarr.xsd (available in the src/main/resources folder). The xml file will be translated into an Hl7 Fhir bundle in R4 format.
2. /tarr/convertZip - this EP accepts a zip file containing all the individual HLA locus files for a single sample (or subject)
3. The Resources generated include the following:
   • DiagnosticReport
   • Bundle
   • Observation (both allele and genotype)
   • Provenance
   • MolecularSequence
   • Device

NEW UI ADDED

• A simple Angular based UI has been enabled for the users to upload files and translate to FHIR
• Build and running instructions are described in the DevOps section

Pre-requisites

• Java 8 or above
• Apache Maven
• Postman or Curl
• If you are a programmer, then an IDE such as one of the following will be useful to modify/update code as needed:
  • IntelliJ
  • Eclipse
  • Spring Tools Suite (STS)
• Only item that may need modifying, is the "server.port" in the "application.properties" file. If the default port specified in the application is in use in your local-environment, then the application will need a different "free" port to start up
  • If you change this port, then you need to modify the following also -
    • In the UI code folder 'tarr2fhirUI', find file "upload.service.ts" under 'src/app/uploader/'
    • Update the SERVER_URL_SINGLE and SERVER_URL_ZIP with the same port number from 'application.properties' file

DevOps

• The code can be checked out from the "master" branch of the "nmdp-bioinformatics/tarr2fhir" page.
  • If the intent is to add your own code, then kindly fork this repo and create your changes in your forked repo
  • Generate Pull Request when ready and merge to main repository
• Code repository details:
  • main repo nmdp-bioinformatics/tarr2fhir has the latest published code
    • master branch will have release ready code
  • forked repo jiyer-nmdp/tarr2fhir is being used for active development
    • master branch will be updated before merging upstream
    • develop branch will contain latest development updates
• After checking out the code, please do the following
  • The "TARR.xsd" file is not part of the code repository.
  • This file needs to be downloaded from - https://www.gendx.com/NGSengine/XSD/20190613/TARR.xsd
  • After downloading the file, please put it in the "src/main/resources/schemas/" folder next to "bindings.xjb".
  • Run the command 'mvn clean install'
• Starting the backend application
  • Navigate to the 'target' folder that is generated
  • Run 'java -jar tarr2fhir-0.0.1-SNAPSHOT.jar' in the command line
• Starting the UI component
  • Navigate to 'tarr2fhirUI' folder in the command line
  • Run 'npm install --save-dev @angular-devkit/build-angular' to install angular build capability
  • Run 'ng serve'

Testing

• With the application launched locally, the APIs will be available at
  • http://localhost:8090
    • for /tarr/convert2Fhir
      • POST a single gendx format "xml" to this using POSTman or curl
      • Use the following headers:
        • Content-type: application/xml
    • for /tarr/convertZip
      • POST a zip file containing all HLA locus xml files for a single Sample/Subject using POSTman or curl
      • Use the following input types:
        • POSTMAN
          • Body: form-data: input file name - "upfile" Choose "File" and upload the zip file
        • CURL
          • curl --location --request POST 'http://localhost:8090/tarr/convertZip'
            --header 'Access-Control-Request-Headers: *'
            --form 'upfile=@/Users/jiyer2/Downloads/FHIR NMDP names_03.tarr.zip'
  • API Responses (for both):
    • 200 OK
      • Json fhir transaction Bundle containing the following resources:
        • Bundle
        • DiagnosticReport
        • Observation (both Allele and Genotype)
        • Provenance
        • Device
        • MolecularSequence
    • if there are errors, standard error messages will be received
• The API health can be tested by calling one of the two actuator end-points that are enabled as part of spring-boot application setup
  • http://localhost:8090/actuator/health
  • http://localhost:8090/actuator/info
• The Swagger-Api documentation page can be found at
  • http://localhost:8090/v2/api-docs
• Using UI to test
  • After starting the application
  • Go to "http://localhost:4200"
  • On the page
    • Select 'Zip file' if uploading a zip of tarr xml files.
    • Select 'Xml file' if uplading a single tarr xml
    • Hit 'Upload' and wait for 'Download' button to appear
    • Click 'Download' button to download the json bundle
  • Downloading the resource will also Refresh the UI page (for a fresh file upload)

TODO

1. Resource(s) to be generated in future

   • Organization

2. Make the API and UI customizable by providing input "parameters" to specify meta-data options

3. Add test classes

4. Add more Java Docs

5. Make the Json bundle response generated in the UI better formatted

6. Dockerize both the Service and the UI

###Notes

• Please refer to existing Pull Requests that have been merged and the changelist descriptions for details of code updates