7 FHIR Command-Line Utility

The HDR FHIR command-line interface (CLI) tool is a standalone command-line tool distributed with HDR 8.1 that contains a number of commands to ingest terminology data provided by the LOINC and SNOMED organizations.

The current version of the HDR FHIR command-line interface tool supports LOINC and SNOMED terminology data to be loaded into the HDR FHIR repository.

The tool is distributed in the form of zip file (hdr-fhir-cli-app-8.1.0-SNAPSHOT.zip) and is located in the <HDR_HOME>/weblogic/hdrfhircli/ directory when the HDR 8.1 installation is complete.

Extract it into a directory where you will keep it, and add this directory to your path.

The zip file hdr-fhir-cli-app-8.1.0-SNAPSHOT.zip contains the following files:

File	Description
lib	All runtime executable jar file.
hdr-fhir-cli.sh	Linux script to manage the command line tool.

7.1 Prerequisites

The following prerequisites are required to use the command-line utility:

Install the JDK 1.8
Set the environment variable JAVA_HOME
Extract the hdr-fhir-cli-app-8.1.0-SNAPSHOT.zip file into the <HDR_HOME>/weblogic/hdrfhircli directory
Set the environment variable CLI_HOME to the location where hdr-fhir-cli-app-8.1.0-SNAPSHOT.zip file is extracted

7.2 Commands

The HDR FHIR command line tool has a number of supported functions, called commands. Each command has a name and a set of supported arguments.

You can see a list of supported commands by simply executing the below command. For example:

$>{$CLI_HOME}/hdr-fhir-cli.sh

Usage:
  hdr-fhir-cli {command} [options]
 
Commands:
  export-conceptmap-to-csv  - Exports a specific ConceptMap resource to a CSV file.
                            
  import-csv-to-conceptmap - Imports a CSV file to a ConceptMap resource.
 
  upload-definitions       - Uploads the conformance resources (StructureDefinition and ValueSet) from the official FHIR definitions.                            
  upload-examples          - Downloads the resource example pack from the HL7.org FHIR specification website, and uploads all of the example resources to a given server.
                            
  upload-terminology       - Uploads a terminology package (e.g. a SNOMED CT ZIP file) to a server, using the $upload-external-code-system operation.

You can also see the list of supported arguments for a given command by issuing command help [commandname]. For example:

$>{$CLI_HOME}/hdr-fhir-cli.sh help upload-terminology
 
Usage:
  hdr-fhir-cli upload-terminology [options]
 
Uploads a terminology package (e.g. a SNOMED CT ZIP file) to a server, using the
$upload-external-code-system operation.
 
Options:
    
  -d,--data <arg>              Local file to use to upload (can be a raw file or   a ZIP containing the raw file)
  -l,--logging                 If specified, verbose logging will be used.
  -t,--target <target>         Base URL for the target server (e.g.
                               " http://localhost:7001/oracle-fhir-server/fhir").
  -u,--url <arg>               The code system URL associated with this upload (e.g. http://snomed.info/sct)
  -v,--fhir-version <version>  The FHIR version being used. Valid values: r4

7.2.1 export-conceptmap-to-csv

The export-conceptmap-to-csv command can be used to export a ConceptMap resource as a CSV file of terminology mappings.

The first row of the CSV file will include the following headers:

    SOURCE_CODE_SYSTEM – ConceptMap.group.source
    SOURCE_CODE_SYSTEM_VERSION – ConceptMap.group.sourceVersion
    TARGET_CODE_SYSTEM – ConceptMap.group.target
    TARGET_CODE_SYSTEM_VERSION – ConceptMap.group.targetVersion
    SOURCE_CODE – ConceptMap.group.element.code
    SOURCE_DISPLAY – ConceptMap.group.element.display
    TARGET_CODE – ConceptMap.group.element.target.code
    TARGET_DISPLAY – ConceptMap.group.element.target.display
    EQUIVALENCE – ConceptMap.group.element.target.equivalence ConceptMapEquivalence)
    COMMENT – ConceptMap.group.element.target.comment

Usage:

hdr-fhir-cli export-conceptmap-to-csv [options]

Exports a specific ConceptMap resource to a CSV file.

Options:

-f,--filename <filename>	The path and filename of the CSV file to be exported (./output.csv).
-l,--logging	If specified, verbose logging will be used.
-t,--target <target>	Base URL for the target server (e.g. ”http://localhost:7001/oracle-fhir-server/fhir").
u,--url <url>	The URL of the ConceptMap resource to be exported (i.e. ConceptMap.url).
-v,--fhir-version <version>	The FHIR version being used. Valid values: r4.

These terminology mappings could then be exported with the following command:

./hdr-fhir-cli.sh export-conceptmap-to-csv --fhir-version R4 -t http://localhost:8080//oracle-fhir-server/fhir -u http://hl7.org/fhir/ConceptMap/cm-administrative-gender-v2 -f /u01/output.csv

7.2.2 import-csv-to-conceptmap

The import-csv-to-conceptmap command can be used to import a CSV file of terminology mappings and store it as a ConceptMap resource.

The first row of the CSV file is expected to include the following headers:

    SOURCE_CODE_SYSTEM – ConceptMap.group.source
    SOURCE_CODE_SYSTEM_VERSION – ConceptMap.group.sourceVersion
    TARGET_CODE_SYSTEM – ConceptMap.group.target
    TARGET_CODE_SYSTEM_VERSION – ConceptMap.group.targetVersion
    SOURCE_CODE – ConceptMap.group.element.code
    SOURCE_DISPLAY – ConceptMap.group.element.display
    TARGET_CODE – ConceptMap.group.element.target.code
    TARGET_DISPLAY – ConceptMap.group.element.target.display
    EQUIVALENCE – ConceptMap.group.element.target.equivalence (ConceptMapEquivalence)
    COMMENT – ConceptMap.group.element.target.comment

An example CSV file that describes the mapping of FHIR to HL7v2 for Administrative Gender would appear as follows:

"SOURCE_CODE_SYSTEM","SOURCE_CODE_SYSTEM_VERSION","TARGET_CODE_SYSTEM","TARGET_CODE_SYSTEM_VERSION","SOURCE_CODE","SOURCE_DISPLAY","TARGET_CODE","TARGET_DISPLAY","EQUIVALENCE","COMMENT"
"http://hl7.org/fhir/administrative-gender","","http://hl7.org/fhir/v2/0001","","male","Male","M","Male","equal",""

Usage:

hdr-fhir-cli import-csv-to-conceptmap [options]

Imports a CSV file to a ConceptMap resource.

Options:

-f,--filename <filename>	The path and filename of the CSV file to be imported (for example, ./input.csv).
-i,--input <input>	The source value set of the ConceptMap to be imported (i.e. ConceptMap.sourceUri).
-l,--logging	If specified, verbose logging will be used.
-o,--output <output>	The target value set of the ConceptMap to be imported (i.e. ConceptMap.targetUri).
-t,--target <target>	Base URL for the target server (e.g. "http://localhost:7001/oracle-fhir-server/fhir").
-u,--url <url>	The URL of the ConceptMap resource to be imported/exported (i.e. ConceptMap.url).
-v,--fhir-version <version>	The FHIR version being used. Valid values: r4.

These terminology mappings could then be imported with the following command:

./hdr-fhir-cli.sh import-csv-to-conceptmap --fhir-version R4 -t http://localhost:8080//oracle-fhir-server/fhir -u http://hl7.org/fhir/ConceptMap/cm-administrative-gender-v2 -i http://hl7.org/fhir/ValueSet/administrative-gender -o http://hl7.org/fhir/ValueSet/v2-0001 -f  /u01/sampleInputFile.csv

7.2.3 upload-definitions and upload-examples

The upload-definitions command uploads the conformance resources (StructureDefinition and ValueSet) from the official FHIR definitions.

The upload-examples command uploads the example resources from the official FHIR definitions.

Usage:

hdr-fhir-cli upload-definitions/upload-examples [options]

The conformance rules are available at https://www.hl7.org/fhir/conformance-rules.html.

Options:

-e,--exclude <arg>	Exclude uploading the given resources, such as "-e dicom-dcim,foo".
-t,--target <arg>	Base URL for the target server (such as "http://localhost:7001/oracle-fhir-server/fhir ").
-v,--fhir-version <version>	The FHIR version being used. Valid values: r4.

Command usage:

./hdr-fhir-cli.sh upload-definitions --fhir-version R4 -t http://localhost:8181/baseR4 "-e dicom-dcim,foo"
 
./hdr-fhir-cli.sh upload-examples --fhir-version R4 -t http://localhost:8181/baseR4 "-e dicom-dcim,foo"

7.2.4 upload-terminology

The HDR FHIR server provides a terminology server, which supports ingestion of terminology data provided by LOINC and SNOMED. For more information on obtaining the above terminology data refer to the respective websites.

The HDR FHIR server provides a repository for terminology content used across the HDR platform, and an API suite to access the content.

The server provides a mechanism for ingestion of the terminology data via the upload- terminology command of the CLI tool. This command supports only LOINC and SNOMED terminologies in the current release.

Note:

The path and exact filename of the terminology files will likely need to be adjusted for your local disk structure.

Usage:

hdr-fhir-cli upload-terminology [options]

Uploads a terminology package (such as a SNOMED CT ZIP file) to a server, using the $upload-external-code-system operation.

Options:

-d,--data <arg>	Local file to use to upload (can be a raw file or a ZIP containing the raw file).
-l,--logging	If specified, verbose logging will be used.
-t,--target <target>	Base URL for the target server (such as "http://localhost:7001/oracle-fhir-server/fhir").
-u,--url <arg>	The code system URL associated with this upload (such as http://snomed.info/sct).
-v,--fhir-version <version>	The FHIR version being used. Valid values: r4.

Command usage:

$>{$CLI_HOME}$./hdr-fhir-cli.sh upload-terminology -d /scratch/fhir/Loinc_2.65.zip -d /scratch/fhir/loincupload.properties --fhir-version R4 –t http://localhost:8080//oracle-fhir-server/fhir -u http://loinc.org