CIMPL Setup and Installation

Table of Contents


Introduction

CIMPL (Clinical Information Modeling Profiling Language) is a specially-designed language for defining clinical information models. It is simple and compact, with tools to produce Fast Healthcare Interoperability Resources (FHIR) profiles, extensions and implementation guides (IG). Because it is a language, written in text statements, CIMPL encourages distributed, team-based development using conventional source-code control tools such as Github. CIMPL provides tooling that enables you to define a model once, and publish that model to multiple versions of FHIR.

Purpose of this Document

This guide will take you through the steps needed to set up the environment needed to run CIMPL and associated tools.

Intended Audience

Anyone intending to use CIMPL for modeling clinical information and authoring FHIR Implementation Guides.

Prerequisite

This guide assumes you have:

Windows Installation Instructions

Unlike most applications that include a standalone installation file that you can click on to install, CIMPL is dependent on the installation of other applications, like Node.js and Yarn, and optionally, Git and Visual Studio Code

For a successful installation, it is critical that you:

Windows Proxy Setup

Warning: Many professional organizations use proxy servers to filter incoming internet content (e.g., antivirus checks, adult material, etc.). Many of the applications that support CIMPL require that these proxy servers be explicitly declared before they will function properly. If your organization does not use a proxy server, you can skip to the next step.

If your organization uses a proxy server, you will need to set up environment variables before proceeding.

setx HTTP_PROXY http://your.proxy.org:80
setx HTTPS_PROXY https://your.proxy.org:80
setx http_proxy http://your.proxy.org:80
setx https_proxy https://your.proxy.org:80
setx proxy http://your.proxy.org:80
setx JAVA_OPTS "-Dhttp.proxyHost=your.proxy.org -Dhttp.proxyPort=80 -Dhttps.proxyHost=your.proxy.org -Dhttps.proxyPort=80 -DsocksProxyHost=your.proxy.org -DsocksProxyPort=80"

Some of the following installation steps will also include specific setups for running the CIMPL tooling and HL7 FHIR IG Publisher from behind a proxy server.

Install Node.js for Windows

The CIMPL command-line utilities are built using the Node.js runtime environment. It is recommended that CIMPL developers download and install the LTS (long-term support) version of Node.js. Use the default options in the installer file (i.e., just keep clicking 'Next' until the installation is complete)

Install Yarn for Windows

Yarn is a dependency manager that ensures that all the prerequisite code libraries on which CIMPL depends are properly installed. It is recommended that CIMPL developers download and install the stable version of Yarn. Use the default options in the installer file (i.e., just keep clicking 'Next' until the installation is complete)

Yarn Proxy Setup

If your organization uses a proxy server, replace http://your.proxy.org with your organization's proxy server in the following code block:

yarn config set proxy http://your.proxy.org
yarn config set strict-ssl false

...then run the modified code block (with your organization's proxy server) in the command prompt. Close and re-open your command prompt to make sure those settings take effect.

Install Visual Studio Code for Windows

Visual Studio Code (also referred to as 'VSCode' or 'Code') is a smart text editor. VSCode is not a strict dependency (i.e., you can author CIMPL files using any text editor), but it is recommended for CIMPL development. An extension for VSCode has been developed that offers syntax highlighting, autocomplete, and other things that make life easier.

To get started, download and install the latest stable build from the VSCode homepage. You can use the default options in the installer file, but some developers find it helpful to check these checkboxes during the installation wizard:

VSCode Proxy Setup

If your organization uses a proxy server, you'll need to configure VSCode settings. If your organization does not use a proxy server, you can skip ahead to the next step.

To ensure that Visual Studio Code can download extensions from the internet, follow this steps:

Install the CIMPL Extension for VSCode

CIMPL authors have created tools for VSCode that offer syntax highlighting, autocomplete, and other things that make life easier. These tools are known as 'extensions' in VSCode (for more information, watch this video about working with extensions). To enable CIMPL syntax highlighting in VSCode:

Install SHR-CLI for Windows

With the supporting software installed, you can move on to installing the Standard Health Record Command Line Interface (SHR-CLI) tool.

Note: Each time you download a new version of SHR-CLI, you must re-run yarn command.

For git users, there is an alternate approach. After installing git, open 'Git Bash' (not the windows command prompt) and enter the following commands, which grab the latest version of the SHR-CLI tool and places it in the ~/cimpl/shr-cli directory, and installs it using Yarn:

cd ~
mkdir cimpl
cd cimpl
git clone https://github.com/standardhealth/shr-cli.git
cd shr-cli
yarn

Install Java Runtime for Windows

The FHIR implementation guide (IG) publisher is owned and operated by the HL7 FHIR team. The IG publisher is primarily written in Java and requires JRE version 8. To install JRE:

Note: You may need to create an Oracle account to download JRE 8

Install Jekyll for Windows

The FHIR IG Publisher also requires Jekyll be installed in order to run properly. Jekyll is a Ruby library (a "gem" in Ruby parlance) that takes code and turns it into webpages. That is especially helpful for generating static websites like the FHIR Implementation Guides.

Use the Windows Installation Instructions for Jekyll:

gem install jekyll bundler
jekyll -v

You should see the following:

jekyll X.X.X

...where X.X.X is the latest Jekyll version number.

That's it!

To test whether your CIMPL environment has been properly set up, try the Hello World example. For detailed information on using SHR-CLI and the IG Publisher, see the CIMPL Tooling Reference.

macOS Installation Instructions

Unlike most applications that include a standalone installation file that you can click on to install, CIMPL is dependent on the installation of other applications, like Node.js and Yarn, and optionally, Git and Visual Studio Code.

For a successful installation, it is critical that you:

Terminal Proxy Setup for macOS

Warning: Many professional organizations use proxy servers to filter incoming internet content (e.g., antivirus checks, adult material, etc.). Many of the applications that support CIMPL require that these proxy servers be explicitly declared before they will function properly. If your organization does not use a proxy server, you can skip ahead to the next step.

If your organization uses a proxy server and you use the standard Terminal app for macOS, you will need to set up environment variables before proceeding.

echo "export http_proxy=http://your.proxy.org:80
export https_proxy=http://your.proxy.org:80
export HTTP_PROXY=http://your.proxy.org:80
export HTTPS_PROXY=http://your.proxy.org:80
export JAVA_OPTS='-Dhttp.proxyHost=your.proxy.org -Dhttp.proxyPort=80 \
-Dhttps.proxyHost=your.proxy.org -Dhttps.proxyPort=80 \
-DsocksProxyHost=your.proxy.org -DsocksProxyPort=80'" >> ~/.bash_profile;\
source ~/.bash_profile

Some of the following installation steps will also include specific setups for running the CIMPL tooling from behind a proxy server.

Install Node.js for macOS

The CIMPL command-line utilities are built using the Node.js runtime environment. It is recommended that CIMPL developers download and install the LTS (long-term support) version of Node.js. Use the default options in the installer file (i.e., just keep clicking 'Next' until the installation is complete)

Install Homebrew for macOS

Homebrew is a package manager for macOS which will allow us to install several other applications.

To install homebrew, enter the following in a terminal window:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Note: During the installation, you may be asked if you want to install 'OSX Developer Tools'. If this occurs, answer 'yes'.

Install Yarn for macOS

Yarn is a dependency manager that ensures that all the prerequisite code libraries on which CIMPL depends are properly installed.

With homebrew installed, yarn can be installed by entering the following in a terminal window:

brew install yarn

Install Visual Studio Code for macOS

Visual Studio Code (occasionally referred to as 'VSCode', or simply 'Code') is not a strict dependency (i.e., you can author CIMPL files using any text editor), but it is recommended that you use it for CIMPL development. An extension for VSCode has been developed that offers syntax highlighting, autocomplete, and other things that make life easier.

To get started, download and install the latest stable build from the VSCode homepage.

VSCode Proxy Configuration

If your organization uses a proxy server, you'll need to configure VSCode settings. If your organization does not use a proxy server, you can skip ahead to the CIMPL Extension Setup.

To ensure that Visual Studio Code can download extensions from the internet, follow this steps:

Install CIMPL Extension for VSCode

CIMPL authors have created tools for VSCode that offer syntax highlighting, autocomplete, and other things that make life easier. These tools are known as 'extensions' in VSCode (for more information, watch this video about working with extensions). To enable CIMPL syntax highlighting in VSCode:

Install SHR-CLI for macOS

With the supporting software installed, you can move on to installing the Standard Health Record Command Line Interface (SHR-CLI) tool. Open a terminal window and enter the following commands:

cd ~
mkdir cimpl
cd cimpl
git clone https://github.com/standardhealth/shr-cli.git

This grabs the latest version of the SHR-CLI tool and places it in the ~/cimpl/shr-cli directory.

To set up the SHR-CLI tool, run:

cd ~/cimpl/shr-cli
yarn

Note: If you encounter error unable to get local issuer certificate, run the following command in terminal:

yarn config set strict-ssl false

...and then re-run yarn using:

yarn

Note: Each time you download a new version of SHR-CLI, you must re-run yarn command.

Install Java Runtime Environment for macOS

The FHIR implementation guide (IG) publisher is owned and operated by the HL7 FHIR team. The IG publisher is primarily written in java and requires JRE version 8. To install JRE:

Install Jekyll for macOS

The FHIR IG Publisher also requires Jekyll be installed in order to run properly. Jekyll is a Ruby library ("gem") that takes code and turns it into webpages. That is especially helpful for generating static websites like the FHIR Implementation Guides.

If you don't know if the xcode developer tools are installed, run the following command:

xcode-select --install

Install the latest version of Ruby:

brew install ruby

When ruby is finished installing, run the following:

gem install bundler jekyll

NOTE: If your system requires sudo to gem install bundler and jekyll, use the following command to preserve environment variables when using sudo:

sudo -E gem install bundler jekyll

That's it!

To test whether your CIMPL environment has been properly set up, try the Hello World example. For detailed information on using SHR-CLI and the IG Publisher, see the CIMPL Tooling Reference.

Appendix: Installing Git for Team Projects

Git is a free and open source distributed version control system that allows developers working simultaneously on a single project to manage various updates to their code. If you're new to Git, github has a great introduction where you can learn by reading or playing with some helpful visualizations.

Git is not a strict dependency (i.e., you can run the SHR-CLI tool without git), but for team projects, it is recommended for CIMPL model developers to use git, along with a hosted git solution like GitHub or GitLab.

Github Desktop is a client interface that simplifies working with Github. It is available for both Windows and macOS.

Install Git for Windows

Download the installation package for Git for Windows and run it, using the default options in the installer file (i.e., just keep clicking 'Next' until the installation is complete).

This will install a few applications, but the most useful (if you do not opt for Github Desktop) will be the 'Git Bash' application. This opens a command-line prompt which emulates the use of git on a Unix-based system (e.g., Linux or macOS). Most CIMPL developers use Unix-based systems, so you may want to use 'Git Bash' for working with CIMPL instead of the standard Windows command line. There are many tutorials online about the use of git. Users that are new to Unix or bash may find this video introduction to Git Bash helpful.

You should also set up git so that any changes you make to the codebase are properly identified (replacing the name and email placeholders with your name and email):

git config --global user.name "Your Name Here"
git config --global user.email "your_email@work.org"

Git Proxy Setup for Windows

If your organization uses a proxy server, you will need to add some proxy settings to git:

git config --global http.proxy http://your.proxy.org:80
git config --global url."https://".insteadOf git://

Install Git for macOS

With homebrew installed, git can be installed by entering the following in a terminal window:

brew install git

You should also set up git so that any changes you make to the codebase are properly identified. Replace the name and email placeholders with your name and email:

git config --global user.name "Your Name Here"
git config --global user.email "your_email@work.org"

Git Proxy Setup for macOS

If your organization uses a proxy server, you will need to add some proxy settings to git:

git config --global http.proxy http://your.proxy.org:port
git config --global url."https://".insteadOf git://