FTR from CSV

Since the 2405 release, using Aidbox in FHIRSchema mode is recommended, which is incompatible with zen or Entity/Attribute options.

Broken link

Prerequisites

1. Download zen-ftr CLI: Download link

Creating Aidbox Configuration project

Create a directory project with following structure:

project/
  zen-package.edn #Package deps declaration
  resources/
    icd-10.csv #CSV source file
  zrc/
    system.edn #System entrypoint importing a ValueSet definion
    diagnosis.edn # ValueSet definition

zen-package.edn

{:deps {}}

zrc/system.edn

{:ns system
 :import #{aidbox diagnosis}
 
 box
 {:zen/tags #{aidbox/system}}}

This ValueSet definition confirms to zen.fhir ValueSet schema and has a :ftr property, it contains an FTR manifest that defines a csv source via :source-url property to create an expanded version of the ValueSet to be stored in the resulting FTR. For details about FTR manifest, please, refer to this page.

{:ns diagnosis
 :import #{zen.fhir}
 
 diagnosis-vs
 {:zen/tags #{zen.fhir/value-set},
  :zen.fhir/version "0.5.0",
  :uri "diagnosis-vs",
  :ftr
  {:module "ig",
   :source-url "resources/icd-10.csv",
   :ftr-path "ftr",
   :tag "v1",
   :source-type :flat-table,
   :extractor-options
   {:format "csv",
    :csv-format {:delimiter ";", :quote "'"},
    :header false,
    :data-row 0,
    :mapping {:concept {:code {:column 2}, :display {:column 3}}},
    :code-system {:id "icd10", :url "http://hl7.org/fhir/sid/icd-10"},
    :value-set
    {:id "icd10", :name "icd10.accidents", :url "diagnosis-vs"}}}}}

Create resources/icd-10.csv file, containing CSV source for your ValueSet:

10344;20;XX;External causes of morbidity and mortality;;;1;
16003;2001;V01-X59;Accidents;10344;;1;
15062;20012;W00-X59;Other external causes of accidental injury;16003;;1;10/07/2020
11748;2001203;W50-W64;Exposure to animate mechanical forces;15062;;1;
11870;2001203W64;W64;Exposure to other and unspecified animate mechanical forces;11748;;1;
11871;2001203W640;W64.0;Exposure to other and unspecified animate mechanical forces home while engaged in sports activity;11870;;1;
11872;2001203W641;W64.00;Exposure to other and unspecified animate mechanical forces, home, while engaged in sports activity;11871;;1;
11873;2001203W641;W64.01;Exposure to other and unspecified animate mechanical forces, home, while engaged in leisure activity;11871;;1;

Initialize this directory as a git repository, commit your initial set-up

git init && git add --all && git commit -m "init"

Generate FTR

Replace <PATH_TO_JAR> placeholder with absolute path to zen.jar.

Execute command listed below in project directory:

java -jar <PATH_TO_JAR> build-ftr

Commit FTR directory:

git add . && git commit -m "Build ftr"

Now you can run Aidbox with the following configuration project and use FHIR Terminology API methods like $validate-code/$lookup on generated diagnosis-vs ValueSet. Resource validation performed when someone invocates a FHIR REST operations will also validate ValueSet binding via FTR.

// resources/package.json
{
   "name":"ig",
   "version":"0.0.1",
   "type":"ig",
   "title":"ig",
   "description":"ig",
   "author":"hs",
   "url":"url"
}

Initialize this directory as a git repository and commit your initial set-up:

git init && git add . && git commit -m "init"

Instruct Aidbox to load terminologies into the DB

Set the following environment variable:

BOX_FEATURES_FTR_PULL_ENABLE=true

By default, Aidbox does not load terminologies into the database as that can take a lot of disk space. This means that full terminology functionality won’t be available until you enable it manually. BOX_FEATURES_FTR_PULL_ENABLE environment variable is just for that. When you set it to true, Aidbox will load terminologies into the database on the next startup and start functioning as a fully-featured terminology server.

Further steps

For guidance on development and production usage, visit the links below:

• Development tips

• Production tips

For customizing Aidbox startup behavior when using FTR, read about FTR environment variables.