A Definitive Guide to Managing FHIR Projects and Resources

Part 1 of Hidden Gems on Simplifier.net That Make Your FHIR Work Easier

Welcome to our three-part blog highlighting Simplifier.net features you may not know about! We’re taking a dive beneath the surface and exploring how they’re used by different organizations – and by FHIR consultants like me.

This first post starts with general information, plus some useful features around FHIR projects and resources on Simplifier.net.

---

Simplify what exactly?

If you’re new to Simplifier.net, it’s an online collaboration platform that lets you document your FHIR specifications and share them as stable, versioned FHIR packages with your colleagues and/or the FHIR implementation community.

Simplifier.net and Forge – the perfect match.

There are many ways to create the definitions you need for your FHIR project, but Forge is probably the easiest. It’s the de-facto standard for FHIR ‘profiling’ and the only available feature-complete graphical user interface. It allows you to create FHIR profiles, extensions, logical models, search parameters, and operation definitions in an easy-to-understand desktop user interface, providing real-time validation feedback. And when you’re ready, you can share them on Simplifier.net. Create FHIR profiles with Forge: publish and collaborate with Simplifier.net. It’s that simple!

Defining projects and resources

Simplifier.net organizes content into projects: coherent sets of resources that share a use case, goal, or purpose. In this context, the term ‘resource’ can mean any kind of FHIR resource, including StructureDefinitions, implementation guides, profiles, the 150 or so individual units of data included in the FHIR specification, and examples or instances uploaded to the platform. Projects can contain resources from multiple FHIR versions, but sticking to just one will help avoid confusion for your implementers.

Other noteworthy supported FHIR-related resources are logical models, package manifests, and mapping files. We try to keep Simplifier.net as a specialized FHIR repository, but you can upload selected non-FHIR files for creating implementation guides, such as markdown text files, images, and CSS files.

Now let’s look at some Simplifier.net features that help you manage your projects and resources efficiently.

FHIR and ZIP API

There are many ways to upload and interact with resources on Simplifier.net. The user interface supports uploading resources (individually or zipped) from your computer, from a server (fetch from URL), or by copying and pasting. Paid Simplifier.net features include a GitHub integration that allows automatic updates for your project.

It’s easy to overlook the platform’s FHIR and ZIP APIs, but every Simplifier.net project is actually a tiny FHIR server in its own right, and can search for resources or perform CRUD interactions with a client that’s authenticated with your Simplifier.net account. System-wide searches and history searches are also supported. To retrieve the endpoint of a project or resource, click on API in the top-right menu on its page, like this:

The Simplifier.net docs include a description of supported search parameters which follow the standard FHIR rules, like this search on the canonical identifier of a StructureDefinition:

GET https://fhir.simplifier.net/<project-key>/StructureDefinition?url=<canonical of resource>

Here’s a similar system-wide search on Simplifier:
GET https://fhir.simplifier.net/r4/StructureDefinition?url=<canonical of resource>

The project ZIP API is useful for synchronizing a whole project. A GET or PUT can be used on https://api.simplifier.net/<project-key>/zip to retrieve or update your project in a zipped form. The FHIR and ZIP APIs can integrate standards development processes with Simplifier.net – for example to automate synchronization with Simplifier.net as part of a build/publication process or periodically retrieve content as part of a back-up process. We use the ZIP API ourselves: Forge uses the ZIP API to directly save resources into a Simplifier.net project.

Syncing with Forge

You can experience the perfect match between Simplifier.net and Forge for yourself by connecting your local profiling folder to a project on Simplifier.net. The entire folder can be synced in a couple of seconds with just two clicks. If you run into conflicts, Forge provides a conflict resolution interface. The screenshot below shows a summary before a synchronization. The syncing feature uses the Simplifier.net ZIP API endpoint.

To find out more about the sync options, take a look at our technical documentation on the topic.

Automate your FHIR work with Firely Terminal

While we’re talking about automation and integration into building pipelines, we should also mention Firely Terminal (formerly Torinox), the cross-platform ‘Swiss army knife’ and command-line tool for all kinds of FHIR needs. And the best part?  You can download and use it for free. 

Firely Terminal contains a whole set of FHIR utilities. It provides client functionality for FHIR resources and FHIR package servers, and lots of features for managing resources, such as splitting bundles into individual resources or vice versa; transforming between XML and JSON; zipping and unzipping; and generating snapshots. Firely Terminal also incorporates a wide range of FHIR npm package management – more on this in my next blog post – and the .NET validation logic for profiled resource validation.

Besides being incredibly helpful for standards developing or testing, the real power of Firely Terminal lies in its automated build and/or publication processes. It can be incorporated into any architecture and used to periodically validate resources and to create and publish packages: combining its different features makes the potential use cases almost endless. Firely Terminal is the only product of its kind in the market and the number of STU3 version downloads stands at more than ten thousand.

Mapping

StructureDefinitions are commonly backed up by a functional or logical model. But did you know you can add mappings to any information model inside StructureDefinitions? Once you’ve declared the relevant mapping information (e.g. name, id, and URI) in the StructureDefinition.mapping, you can add mappings for every element in the ElementDefinition.mapping, as shown here:

An external mapping can be better for governance reasons, because you get a new version of the profile every time you update it. But keeping the mappings in the profiles also has its benefits: these structured mappings can be used in an automated way to get to exactly the right element: for example, to retrieve a profiled element’s properties in order to dynamically build a user interface.

Conversely, inline mappings guide implementers to the mapped concept for more information. Simplifier.net adds value here by providing a tab on the profile page, as shown in this Patient resource created by the Dutch competence centre, Nictiz. Including a value in the `mapping.comment`helps create an easy to understand overview in one place, and Simplifier.net also links to the StructureDefinition.mapping.uri, so it’s easy to get to the underlying mapped definitions.

History and diff viewer

Simplifier.net keeps track of every uploaded version of the resources. You can find them under the history tab on a resource page and compare them in a stand-alone diff viewer using your favourite FHIR format (XML/JSON).

History and diff viewer feature location.

Download a Simplifier.net project as a FHIR server

One of my favourite hidden gems is the option to download any public STU3 or R4 project as a FHIR server. A fully-featured FHIR server – with all the project’s conformance resources and example instances – can be locked and loaded within minutes. This is the perfect way for authors to test the specifications in a RESTful environment, for example by trying out custom-defined search parameters. For FHIR implementers, it provides a local test server containing instances that conform to the required specifications.

We wanted to make this feature as simple as possible, so Simplifier.net uses a Docker image that runs a FHIR server (Firely Server) with all the settings pre-set for a smooth start. You can find it by clicking “<project name> FHIR server” under downloads on any STU3 project page. If you’ve already installed Docker, simply open the zip file and execute the script in a command-line interface.

Subscribe to FHIR resources and issues

As an author of FHIR resources, you’ll want to access other projects for inspiration, or because you directly depend on them. As an implementer of FHIR specs, besides possible changes to the resources, you may also want to follow updates in projects that have issue tracking enabled (available in the Team and Enterprise plans). The screenshot below shows how to set up email notifications for resource or issue updates. Small fun fact: the number of subscribers drives the ‘popular projects’ list on the Simplifier.net homepage.

Subscribing to a project.

To recap

This post has looked at some really useful features and tools for managing projects and resources on Simplifier.net. Part Two focuses on the validation of FHIR resources, and the third and last article reveals what you need to know about publishing FHIR resources. 

Reach out to us on [email protected] if you have any questions or feedback, or if you’ve found a hidden gem we’ve overlooked!