Load US VSAC Package to Aidbox

Load all official versions of vocabulary value sets provided by the Value Set Authority Center (VSAC) at the National Library of Medicine (NLM)

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

setup-aidbox-with-fhir-schema-validation-engine.md

The current package is a pre-built version of the VSAC contents 0.7.0 (2022-06-11). Please reach out to us if you need a newer version.

How to set up Aidbox with VSAC value sets

To correctly set up Aidbox, we'll utilize the Aidbox configuration projects.

Check the existing guide that explains how to run Aidbox locally

git clone \
  https://github.com/Aidbox/aidbox-project-template-vsac \
  aidbox-project && \
  cd aidbox-project && \
  rm -rf .git

Start Aidbox with Docker Compose

docker compose up --force-recreate

Navigate to http://localhost:8888/ and Sign In to the Aidbox UI using the login admin and password password.

Configuration Overview: Key Features and Distinctions

If you already have a configuration project, you can replicate these steps to enable US VSAC package in your Aidbox instance.

Added US VSAC dependency to configuration project

zen-package.edn

{:deps {us-nlm-vsac "https://github.com/zen-fhir/us-nlm-vsac.git"}}

Imported VSAC namespace to configuration project entrypoint

{ns main
 import #{aidbox
          config
          us-nlm-vsac}
 …}

Zen requires importing a namespace into the entrypoint to load the ValueSet definition into the definitions store.

FTR Pull Feature — instruct Aidbox to load concepts into the database

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. 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.

To achieve that we set ftr.pull.enable to true in features map.

zrc/config.edn

 features
 {:zen/tags #{aidbox.config/features}
  :ftr {:pull {:enable true}}}

Please be aware the initial loading of terminologies may take a significant amount of time.

How to check if the concepts are still loading or have already loaded? (Usable for async pulls)

Run this query to check the concepts

select resource -> 'code', resource -> 'display' from concept where resource -> 'valueset' @> '["http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1190.58"]'::jsonb