Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
There are a few concepts that are core to Snow Owl. Understanding these concepts from the outset will tremendously help ease the learning process.
A terminology (also known as code system, classification and/or ontology) defines and encapsulates a set of terminology components (eg. set of codes with their meanings) and versions. A terminology is identified by a unique name and stored in a repository. Multiple code systems can exist in a single repository besides each other as long as their name is unique.
A terminology component is a basic element in a code system with actual clinical meaning or use. For example in SNOMED CT, the Concept, Description, Relationship and Reference Set Member are terminology components.
A version that refers to an important snapshot in time, consistent across many terminology components, also known as tag or label. It is often created when the state of the terminology is deemed to be ready to be published and distributed to downstream customers or for internal use. A version is identified by its version ID (or version tag) within a given code system.
A repository manages changes to a set of data over time in the form of revisions. Conceptually very similar to a source code repository (like a Git repository), but information stored in the repository must conform to a predefined schema (eg. SNOMED CT Concepts RF2 schema) as opposed to storing it in pure binary or textual format. This way a repository can support various full-text search functionalities, semantical queries and evaluations on the stored, revision-controlled terminology data.
A repository is identified by a name and this name is used to refer to the repository when performing create, read, update, delete and other operations against the revisions in it. Repositories organize revisions into branches and commits.
A revision is the basic unit of information stored in a repository about a terminology component or artifact. It contains two types of information:
one is the actual data that you care about, for example a single code from a code system with its meaining and properties.
the other is revision control information (aka revision metadata). Each revision is identified by a random Universally Unique IDentifier (UUID) that is assigned when performing a commit in the repository. Also, during a commit each revision is associated with a branch and timestamp. Revisions can be compared, restored, and merged.
A set of components under version control may be branched or forked at a point in time so that, from that time forward, two copies of those components may develop at different speeds or in different ways independently of each other. At later point in time the changes made on one of these branches can be merged into the other.
Branches are organized into hierarchies like directories in file systems. A child branch has access to all of the information that is stored on its parent branch up until its baseTimestamp, which is the time the branch was created. Each repository has a predefined root branch, called MAIN
.
A commit represents a set of changes made against a branch in a repository. After a successful commit, the changes made by the commit are immediately available and searchable on the given branch.
A merge/rebase is an operation in which two sets of changes are applied to set of components. A merge/rebase always happens between two branches, denoting one as the source and the other as the target of the operation.
Snow Owl requires Java 11 or newer version. Specifically as of this writing, it is recommended that you use JDK (Oracle of OpenJDK is preferred) version 11.0.2. Java installation varies from platform to platform so we won’t go into those details here. Oracle’s recommended installation documentation can be found on Oracle’s website. Suffice to say, before you install Snow Owl, please check your Java version first by running (and then install/upgrade accordingly if needed):
Once we have Java set up, we can then download and run Snow Owl. The binaries are available at the Releases pages. For each release, you have a choice among a zip or tar archive, a DEB or RPM package.
For simplicity, let's use a zip file.
Let's download the most recent Snow Owl release as follows:
Then extract it as follows:
It will then create a bunch of files and folders in your current directory. We then go into the bin directory as follows:
And now we are ready to start the instance:
If everything goes well with the installation, you should see a bunch of log messages that look like below:
Now that we have our instance up and running, the next step is to understand how to communicate with it. Fortunately, Snow Owl provides very comprehensive and powerful APIs to interact with your instance.
Among the few things that can be done with the API are as follows:
Check your instance health, status, and statistics
Administer your instance data
Perform CRUD (Create, Read, Update, and Delete) and search operations against your terminologies
Execute advanced search operations such as paging, sorting, filtering, scripting, aggregations, and many others
Snow Owl® is a highly scalable, open source terminology server with revision-control capabilities and collaborative authoring platform features. It allows you to store, search and author high volumes of terminology artifacts quickly and efficiently.
Features include:
Revision-controlled authoring
Maintains multiple versions (including unpublished and published) for each terminology artifact and provides APIs to access them all
Independent work branches offer work-in-process isolation, external business workflow integration and team collaboration
SNOMED CT and others
Full SNOMED CT terminology support (full RF2 support, ECL v1.3, SCG 2.3.1, ETL 1.0, Reference Sets, OWL Axioms, OWL 2 EL/DL support, SNOMED Query Language draft specification)
With its modular design, the server can maintain multiple terminologies (including local codes, mapping sets, value sets)
Various set of APIs
SNOMED CT API (RESTful and native Java API)
FHIR API
CIS API
Highly extensible and configurable
Simple to use plug-in system makes it easy to develop and add new terminology tooling/API or any other functionality
Built on top of Elasticsearch (highly scalable, distributed, open source search engine)
Connect to your existing cluster or use the embedded instance
All the power of Elasticsearch is available (full-text search support, monitoring, analytics and many more)
This distribution only includes features licensed under the Apache 2.0 license. To get access to the full set of features, please contact B2i Healthcare.
View the detailed release notes here.
Not the version you're looking for? View past releases.
NOTE: You need to have a recent version of Java installed (Java 11+, https://jdk.java.net/archive/).
Once you have downloaded the appropriate package:
Run bin/snowowl.sh
on unix, or bin/snowowl.bat
on windows
Run curl http://localhost:8080/snowowl/admin/info
Navigate to http://localhost:8080/snowowl
Snow Owl uses Maven for its build system. In order to create a distribution, simply run the following command in the cloned directory.
The distribution packages can be found in the releng/com.b2international.snowowl.server.update/target
folder, when the build is complete.
To run the test cases, use the following command:
These instructions will get Snow Owl up and running on your local machine for development and testing purposes.
Snow Owl is an Equinox-OSGi based server. To develop plug-ins for Snow Owl you need to use Eclipse as IDE:
Use latest Eclipse IDE for Eclipse Committers package: http://www.eclipse.org/downloads/eclipse-packages/
Required Eclipse plug-ins (install the listed features via Help
-> Install New Software...
):
Note: you may have to untick the Show only the latest versions of the available software
checkbox to get older versions of a feature. Please use the exact version specified below, not the latest point release.
Xtext/Xtend (http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/)
MWE 2 language SDK 2.11.2 (MWE)
Xtend IDE 2.21.0 (Xtext)
Xtext Complete SDK 2.21.0 (Xtext)
Maven integration (http://download.eclipse.org/technology/m2e/releases)
Make sure you have the following preferences enabled/disabled.
Plug-in development API baseline errors is set to Ignored (Preferences > Plug-in Development > API Baselines)
The Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-clean-plugin:2.5:clean type of errors can be ignored or changed to Warnings in Preferences->Maven->Errors/Warnings.
Set the workspace encoding to UTF-8 (Preferences->General->Workspace)
Set the line endings to Unix style (Preferences->General->Workspace)
Make sure the Git line endings are set to input (Preferences->Team->Git->Configuration - add key if missing core.autocrlf = input)
Import all projects into your Eclipse workspace and wait for the build to complete
Select all projects and hit Alt
+ F5
and trigger an update to all Maven projects manually (to download dependencies from Maven)
Open the target-platform/target-platform-local.target
file
Wait until Eclipse resolves the target platform (click on the Resolve
button if it refuses to do so) and then click on Set as Active Target platform
Wait until the build is complete and you have no compile errors
Launch snow-owl-oss
launch configuration in the Run Configurations menu
Navigate to http://localhost:8080/snowowl
Please see CONTRIBUTING.md for details.
Our releases use semantic versioning. You can find a chronologically ordered list of notable changes in CHANGELOG.md.
This project is licensed under the Apache 2.0 License. See LICENSE for details and refer to NOTICE for additional licensing notes and uses of third-party components.
In March 2015, SNOMED International generously licensed the Snow Owl Terminology Server components supporting SNOMED CT. They subsequently made the licensed code available to their members and the global community under an open-source license.
In March 2017, NHS Digital licensed the Snow Owl Terminology Server to support the mandatory adoption of SNOMED CT throughout all care settings in the United Kingdom by April 2020. In addition to driving the UK’s clinical terminology efforts by providing a platform to author national clinical codes, Snow Owl will support the maintenance and improvement of the dm+d drug extension which alone is used in over 156 million electronic prescriptions per month. Improvements to the terminology server made under this agreement will be made available to the global community.
Many other organizations have directly and indirectly contributed to Snow Owl, including: Singapore Ministry of Health; American Dental Association; University of Nebraska Medical Center (USA); Federal Public Service of Public Health (Belgium); Danish Health Data Authority; Health and Welfare Information Systems Centre (Estonia); Department of Health (Ireland); New Zealand Ministry of Health; Norwegian Directorate of eHealth; Integrated Health Information Systems (Singapore); National Board of Health and Welfare (Sweden); eHealth Suisse (Switzerland); and the National Library of Medicine (USA).
Let’s start with a basic health check, which we can use to see how our instance is doing. We’ll be using curl
to do this but you can use any tool that allows you to make HTTP/REST calls. Let’s assume that we are still on the same node where we started Snow Owl on and open another command shell window.
And the response:
In the response, we can see the version of our instance along with the available repositories and their health status (eg. SNOMED CT
with status GREEN
).
Whenever we ask for the status, we either get GREEN
, YELLOW
, or RED
and an optional diagnosis
message.
Green - everything is good (repository is fully functional)
Yellow - some data or functionality is not available, or diagnostic operation is in progress (repository is partially functional)
Red - diagnostic operation required in order to continue (repository is not functional)
And the response is:
Which simply means we have no SNOMED CT concepts yet in our instance.
Now let's take a peek at our code systems:
And the response:
Which means, we have a single Code System in Snow Owl, called SNOMED CT
. It has been created by the SNOMED CT module by default on the first startup of your instance. A Code System lives in a repository and its working branchPath
is currently associated with the default MAIN
branch in the snomedStore
repository.
The RPM for Snow Owl can be downloaded from the Downloads section. It can be used to install Snow Owl on any RPM-based system such as OpenSuSE, SLES, Centos, Red Hat, and Oracle Enterprise.
On systemd-based distributions, the installation scripts will attempt to set kernel parameters (e.g., vm.max_map_count
); you can skip this by masking the systemd-sysctl.service unit.
Use the chkconfig command to configure Snow Owl to start automatically when the system boots up:
Snow Owl can be started and stopped using the service command:
If Snow Owl fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/snowowl/
.
To configure Snow Owl to start automatically when the system boots up, run the following commands:
Snow Owl can be started and stopped as follows:
These commands provide no feedback as to whether Snow Owl was started successfully or not. Instead, this information will be written in the log files located in /var/log/snowowl/
.
You can test that your Snow Owl instance is running by sending an HTTP request to:
which should give you a response something like this:
Snow Owl defaults to using /etc/snowowl
for runtime configuration. The ownership of this directory and all files in this directory are set to root:snowowl
on package installation and the directory has the setgid
flag set so that any files and subdirectories created under /etc/snowowl
are created with this ownership as well (e.g., if a keystore is created using the keystore tool). It is expected that this be maintained so that the Snow Owl process can read the files under this directory via the group permissions.
The RPM places config files, logs, and the data directory in the appropriate locations for an RPM-based system:
You now have a test Snow Owl environment set up. Before you start serious development or go into production with Snow Owl, you must do some additional setup:
To check the instance status/health, we will be using the . You can run the command by clicking the "Copy" link on the right side and pasting it into a terminal.
Now that we have a SNOMED CT Code System, let's take a look at its content. We can query its content using either the or the .
For sake of simplicity, let's search for the available concepts using the . For that we will need the branch we would like to query, but fortunately we already know the value from our previous call to the Code Systems API, it was MAIN
. To list all available concepts in a SNOMED CT Code System, use the following command:
RPM install is not supported on distributions with old versions of RPM, such as SLES 11 and CentOS 5. Please see instead.
Snow Owl loads its configuration from the /etc/snowowl/snowowl.yml
file by default. The format of this config file is explained in .
Learn how to .
Configure .
Configure .