Getting Started - bluehalo/node-fhir-server-core GitHub Wiki

This FHIR server library is intended to simplify the process of standing up your own FHIR server. We try to abstract a lot of the complicated pieces away so all you need to do is provide some configurations and write queries. In this getting started guide, we will walk you through using this library to get started building your own FHIR server.

NOTE: These instructions are for unix based systems. If you are using Windows, you may need to change some commands out for their Windows equivalent.

Let's get started by installing some prerequisites.

1. Install the latest LTS for Node.js. You must have Node >= 7.7 installed.
2. Install yarn.

In terminal, run the following:

1. mkdir fhir-server
2. cd fhir-server
3. yarn init

You will now have a folder structure that looks like this:

fhir-server
- package.json

Simply run yarn add @asymmetrik/node-fhir-server-core.

Let's start by creating an index.js file in the root of the project and add the following code to it.

const FHIRServer = require('@asymmetrik/node-fhir-server-core');

let config = { profiles: {}};
let server = FHIRServer.initialize(config);

server.listen(3000, () => {
	server.logger.info('Starting the FHIR Server at localhost:3000');
});

What we are doing here is loading the core library and then calling initialize on it. Internally this will setup middleware, various security features, public directory routes, error routes, and routes for FHIR resources. Then finally we tell the server to listen on port 3000 which makes the server available at http://www.localhost:3000.

You will now have a folder structure that looks like this:

fhir-server
- node_modules
- index.js
- package.json
- yarn.lock

The next thing we want to do is run this file in node. Let's add a script to our package.json, it should look something like this:

NOTE: You may have different values for some fields which is fine, the "scripts" block is the important part

{
  "name": "fhir-server",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "@asymmetrik/node-fhir-server-core": "^1.3.0"
  }
}

Finally, run yarn start to start the server.

If you have done everything correctly so far, you will receive the following error.

Error: No profiles configured. You must configure atleast 1 profile to run this server. Please review the README.md section on Configuring Profiles.

By default, our library does not provide support for any profiles, and without a profile, what is the point to having a server. Next, let's walk you through setting up a simple patient profile. A profile corresponds to a queryable FHIR resource and we support many.

We will need to do a few things to add support for Patient resources in our server. Let's start by adding a patient service. Create a patient.service.js file in the root.

You will now have a folder structure that looks like this:

fhir-server
- node_modules
- index.js
- package.json
- patient.service.js
- yarn.lock

Add the following code to the patient service.

module.exports.search = (args, logger) => new Promise((resolve, reject) => {
	reject(new Error('Unable to locate patients'));
});

We are going to add support for the search interaction. Each profile can support many interactions. We have some documentation on profiles and how they work in the Profile wiki with more updates coming soon to cover everything. For now, let's start with a simple search.

The next thing we need to do is update our config in index.js to tell it we want to support the patient profile.

In index.js, add the following to the top of the file:

const FHIRServer = require('@asymmetrik/node-fhir-server-core');
const path = require('path');

const { VERSIONS } = FHIRServer.constants;

and then change let config = { profiles: {}}; to the following:

let config = {
	server: {},
	logging: {
		level: 'debug'
	},
	profiles: {
		patient: {
			service: path.posix.resolve('./patient.service.js'),
			versions: [ VERSIONS['3_0_1'] ]
		}
	}
};

Here we are telling the FHIR server where to locate the patient service and that we intend to support it on STU3(3.0.1 specifically). We are also enabling logging and providing a base value for server config (the server config is required at the moment but will not be in the future, for now, just give it an empty object). We are still adding documentation for all the various options you can set here so when it is available, we will add more links to it here.

Now run yarn start one more time. You should something very similar to the following:

2019-01-08T20:56:50.563Z - info: Starting the FHIR Server at localhost:3000

Open http://localhost:3000/3_0_1/metadata in your browser and you should see a capability statement resource indicating you support the Patient resource. You can also open http://localhost:3000/3_0_1/Patient to attempt a patient query. You should see an operation outcome that looks something like this:

{
    "resourceType": "OperationOutcome",
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><table border=\"0\"><tr><td style=\"font-weight: bold;\">error</td><td><pre>Unable to locate patients</pre></td></tr></table></div>"
    },
    "issue": [{
        "severity": "error",
        "code": "exception",
        "diagnostics": "Unable to locate patients"
    }]
}

This is good as this is the error we created in the patient.service.js. patient.service.js is where you want to execute your queries and return your patient JSON. So you may need to connect to a database, query your data, and possibly even map your data back to a FHIR format if it is not already in a FHIR format.

If you made it this far, thanks for sticking it out and completing the Getting Started guide. Please browse the other wiki pages for more information and feel free to file issues/questions on our issues page.