Blog

A Definitive Guide to Managing FHIR Projects and Resources

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

manage FHIR projects and resources
Photo by Jason D on Unsplash

Welcome to this three-part blog series about Simplifier.net  features you may not yet know about! We will dive into features that are just beneath the surface and explore how they are used by different organizations and myself as a FHIR consultant.

This first post starts with general information followed by useful features around projects and resources on Simplifier.net.


Simplifier? Simplify what?

Perhaps you are new to Simplifier.net. What does it simplify or what does it do? In one sentence: it is an online collaboration platform for FHIR projects, allowing you to document your FHIR specifications and share them as stable, versioned FHIR packages with your colleagues or the FHIR implementation community.

And Forge?

Simplifier.net and Forge are the perfect match. Create FHIR profiles with Forge, collaborate on and publish projects with Simplifier.net. There are numerous ways to create the definitions required by your FHIR project, but Forge is probably the easiest way to do it. It is the only feature-complete graphical user interface and the de-facto standard for FHIR “profiling”. 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.

Defining projects and resources

To avoid confusion, let’s agree on the definition of projects and resources.

Simplifier.net organizes content like implementation guides and resources (more on this shortly) into projects. A project is a coherent set of resources that share a common use case, goal, or purpose. Although a project can contain resources of multiple FHIR versions, it is best to stick to one. This is more widely supported and prevents confusion with your consumers.

We call everything that goes inside projects resources. This can be any kind of FHIR resource, like StructureDefinitions, which are also known as profiles, or instances/examples of FHIR resources, like an Observation resource. Other noteworthy supported FHIR related resources are implementation guides, logical models, package manifests and mapping files for the FHIR mapping language. Although we try to keep Simplifier.net a specialized FHIR repository, it is possible to upload some non-FHIR files to a project for creating implementation guides, such as markdown text files, images, and CSS files.

Now that we’re on the same page, we can dive into Simplifier.net features that help you efficiently manage your projects and resources.

FHIR and ZIP API

There are numerous ways to upload and interact with resources on Simplifier.net. The user interface supports uploading resources (individually or combined in a zip) from your computer, from a server (fetch from URL) or by copy-and-pasting. Among the paid features is a GitHub integration, that allows your project to be automatically updated.

Sometimes people overlook the FHIR and ZIP APIs of Simplifier.net. Every project is, in fact, a tiny FHIR server on its own that can be used to search for resources or to perform CRUD interactions with a client, 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 when visiting either a project or resource page.

Location of FHIR and ZIP API endpoint information in Simplifier.
Location of FHIR and ZIP API endpoint information in Simplifier.

Supported search parameters are described in the docs and follow the standard FHIR rules. For example, a search on a canonical identifier of a StructureDefinition is performed as follows:

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

It works similarly for a 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. Example requests are shown in the docs. These API’s can be used to integrate standards development processes with Simplifier.net, to automate, for example, the synchronization with Simplifier.net as part of a build/publication process. Another use case from our customers is to periodically retrieve the project’s content as part of a back-up process. We use the API ourselves, too. Forge uses the API to directly save resources into a Simplifier.net project.

Automate your FHIR work with Torinox

Automation by robot at the piano
https://unsplash.com/@franckinjapan

Since we mentioned automation and integration into building pipelines, we should talk about Torinox too. We view it as 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.

Torinox contains a whole set of FHIR utilities. It provides client functionality for FHIR resources and FHIR package servers. It contains a lot of features for managing resources, such as splitting Bundles into individual resources or the other way around, transforming between XML and JSON, zipping and unzipping resources, and generating snapshots. It also contains a wide range of FHIR npm package management. More on this in the third blog post. Lastly, Torinox includes the .NET validation logic for profiled resource validation.

Besides being incredibly helpful for standards developing or testing, the power of Torinox lies within automated build and/or publication processes as it can be incorporated into any architecture. You can use it to periodically validate resources and to create and publish packages. By combining the different features, the possible use cases of Torinox are practically endless. The number of downloads supports this: the STU3 version has been downloaded more than ten thousand times! It is the only product of its kind in the market.

Mapping

Commonly, StructureDefinitions are backed up by a functional or logical model. Did you know you can add mappings to any information model inside StructureDefinitions? After the declaration of the relevant mapping information (e.g. name, id and uri) in the StructureDefinition.mapping, mappings can be given for every element in the ElementDefinition.mapping as shown below.

ElementDefinition.mapping

Sometimes an external mapping may be preferred because of governance reasons as any update to the mapping will result in a new version of the profile. However, keeping the mappings in the profiles has its benefits. Because the mappings are structured, consumers of the StructureDefinition can use the mappings in an automated way, to get to exactly the right element. A use case could be to retrieve a profiled element’s datatype, name or description based on the functional or logical model concept ID to build a user interface.

Mapping overview of a resource
Mapping overview of a resource.

If you want to do it the other way around, inline mappings will guide consumers to the mapped concept for more information. This is where Simplifier.net adds value: mappings are nicely shown in a table at the mapping tab of a resource page. If you use the mapping.comment to capture the concept name or description of the external mapping, you will have a nice mapping table here. As shown in the screenshot and profiles of Nictiz. The StructureDefinition.mapping.uri is given as a link by Simplifier.net. This makes it easy to get to the underlying mapped definitions!

History and diff viewer

Simplifier.net keeps track of every uploaded version of the resources. On a resource page, these are shown in the history tab. Every version can be compared in a stand-alone diff viewer. A bonus is the possibility to select your favorite FHIR format (XML/JSON) for the diff viewer.

History and diff viewer feature location
History and diff viewer feature location.

Download a Simplifier.net project as a FHIR server

One of my favorite gems is the option to download any public STU3 project as a FHIR server. Within minutes a fully-featured FHIR server can be locked and loaded with all conformance resources (profiles, search parameters, value sets etc.) and example instances that exist in the project.

This is helpful for both authors and consumers.  As an author, it is a perfect way to test the specifications in a RESTful environment. For instance, you can try out customer search parameters. As a consumer, it is helpful because this provides a local test server that contains instances that conform to the required specifications.

How to download a complete project as a FHIR server.

We tried to make this feature as simple as possible. For this purpose, Simplifier.net uses a Docker image that runs a Vonk FHIR server with all the settings preset for a smooth start. You can find this gem by clicking “<project name> FHIR server” under downloads on any STU3 project page. If you have already installed Docker, simply open the zip file and execute the script in a command-line interface.

Currently, this feature is only present for STU3 projects.  Let us know if you think this is helpful for your R4 projects as well! Reach out through the feedback button on Simplifier.net or send an email directly to simplifier@fire.ly.

Subscribe to FHIR resources and issues

As an author of FHIR resources, it is highly likely that you would want to access other projects to use as inspiration or because you directly depend on them. As a consumer, besides possible changes to the resources, you could be interested in updates to issues made in projects that have issue tracking enabled (available in the Team and Enterprise plans).  Subscribing to a project of interest comes in handy as this will trigger an email notification whenever something is updated. Simplifier.net currently supports notifications for resource and issue changes from a project and resource/issue level. The screenshot shows the bell icon you can click on to be notified. Small fun fact: the number of subscribers is used to dynamically create the list of popular projects on the Simplifier.net homepage.

Subscribe location
Subscribing to a project.

Recap

We have covered several features and tools that are available in the free plan around projects and resources on Simplifier.net. The second part of this series will focus on the validation of FHIR resources. The third and last article will reveal tips on our most beloved topic: versioning. Luckily, Simplifier.net has got you covered there. Follow me along these posts to get the most out of Simplifier.net and boost your FHIR project.

Reach out to us on simplifier@fire.ly if you’ve found a hidden gem that we have not covered here! If you have any questions or feedback, we’d also love to hear from you.

Post a comment

Your email address will not be published. Required fields are marked *