How to Build a Dynamic FHIR Implementation Guide

The Simplifier Implementation Guide Editor is the intuitive user interface where you can quickly start creating FHIR Implementation Guides. In recent releases of Simplifier.net we introduced the Firely Query Language (FQL), for dynamic tables of information from your resources, and the feature to create copies of your FHIR Implementation Guides (IG).

The feature to create copies of your IGs allows you to re-use a template you have created and start building a new guide from there. It also allows you to maintain multiple branches of a guide.

With the introduction of Firely Query Language (FQL), available on any of our paid plans, it is now possible to dynamically embed useful information, directly queried from the resources in your project or package. In the rest of this article, we will provide some examples of how to use FQL in your IG or you can dive straight into the FQL syntax explanation and start exploring.

FQL allows you to render traditional resource tables or customize it in any way you see fit for your use case. Combining the new FQL feature with the option to create copies of your Implementation Guides is especially powerful as we will show in the examples below.

But first, what is the Firely Query Language (FQL)?

FQL tries to be as easy to use and understand as possible, while at the same time allowing the room for complex queries as well. FQL borrows from and merges two well-known and widely adopted languages: SQL and JSON. The functional gaps are filled with the addition of FHIRPath. This will allow you to render information relevant for your Implementation Guide and make it possible to dynamically generate tables with content linked to your resources. All FQL output will be rendered in table format.

Note that our command-line tool Firely Terminal also allows you to query with FQL with the fhir query command, outputting the table as XML, JSON or formatted HTML.

In the next sections I will give you a couple of examples on how you can use FQL to create a dynamic table in your Implementation Guide.

Creating a resource table of content

With the following query you can quickly select all the resources from your project or package that meet your criteria.

@```
from
    StructureDefinition
where 
    kind = 'resource'
select
    Name: name,
    Type: type,
    Canonical_URL: url
order by
    name 
```

With the above query, a table is created which contains columns indicating the name, type and url of all the StructureDefinitions in your scope* where the kind equals ‘resource’. Note that in the select statement you can specify different column header titles than the default ones. Note: The scope of your Implementation Guide can be selected in the settings and can be set to the live development project or a released package.

The benefit of doing this with FQL is that if you continue to work on your project and add a new resource, it will automatically be included in the generated list in your IG. If you rename, alter, or delete any resource, this will automatically be updated in your IG as well. These tables can also be created for your Extensions, Valuesets and Codesystems and other content of your project.

An example query of how to render a table containing all the Extensions in the scope:

@```
from
    StructureDefinition
where
    type = 'Extension'
select
    name,
    type,
    kind,
    url
order by
    name
```

Now let’s give you a base template

This is an example of the FQL you can include in your own base template for rendering resources in your IG. The benefit of doing this with FQL is that it allows you to customize what is rendered and you can simply re-use most of the FQL tables for all your resources. You can work on modeling your resources and at the same time FQL is directly adding the latest information to your guide!

Resource information

Let’s start with an example of the introduction page for every one of your resources. The information, which is traditionally used are URL, Version, Name, Title, Status, Description and Publisher. In the Implementation Guide editor you can now save your FQL statements in a .snippet.md file. This allows you to call your ‘base’ FQL statements in any Implementation Guide page. The .snippet.md files are project specific but can be downloaded an uploaded to your other projects.

@```
from 
    StructureDefinition
where 
    url = 'https://fake-acme.org/fhir/StructureDefinition/ACME-base-patient'
select 
    Defining_URL: url,
    Version: version,
    Name: name,
    Status: status,
    Description: description,
    Publisher: publisher
```

As you see fit you can add any additional information to this table.

Terminology binding for your FHIR Implementation Guide

You can retrieve a lot more information from your resources building on the basics we covered above. For example, you can create a table that lists all the valueSets used in your resource by using a join statement.

@```
from
    StructureDefinition
where
    url = 'https://fake-acme.org/fhir/StructureDefinition/ACME-base-patient'
for 
    differential.element
select
    Path: path,
    join binding 
    {
        Strength: strength, 
        Description: description, 
        ValueSet: valueSet 
    }
```

As you can see, you can make the queries as complicated and complex as you would like. Luckily, if you create a complicated query like this to retrieve detailed information you can easily re-use them for all your other resources.

Similar queries are possible for rendering Extensions and SearchParameters. Even constraints can be rendered using FQL. Below you will find some more examples of queries for different tables you might want to include in your FHIR Implementation Guide (IG).

SearchParameters for a particular base resource

@```
from
    SearchParameter
where
    base = 'Patient'
select
    Name: name,
    Type: type,
    Description: description, 
    Expression: expression
```

Constraints for all resources in your project

@```
from
    StructureDefinition
for
    differential.element
select
    path,
    join constraint
    {
        key,
        human,
        expression
    }
order by
    path
```

Recap

With the combination of FQL and the new functionality to copy your Implementation Guides you can create your own IG templates which can be used for all your projects and packages.

Now go out and try the FQL playground where we provide more examples of all the queries you can run on your projects and packages. Full documentation can be found in the Firely Query Language documentation.