Skip to main content

FHIR Profiles and Adaptations

The HL7® FHIR® standard is intended to be adapted for specific healthcare environments and implementations. At the core of these adaptations are FHIR profiles, which define the allowable fields of a specific resource. These profiles extend or constrain the resource definitions that are found in the base FHIR specification. Profiles and other FHIR artifacts are achieved through conformance resources; for example, profiles are defined by StructureDefinition resources, search parameters are defined by SearchParameter resources, codes are defined by ValueSet and CodeSystems resources, and so on.

In most cases, a complete, robust FHIR adaptation is defined by an Implementation Guide, which is a coherent collection of conformance resources that includes documentation explaining the adaptation-specific profiles and other artifacts. Most commonly, these Implementation Guides are distributed as NPM-like packages that are downloadable from distribution sites. In InterSystems products, you control what a FHIR server supports by adding a FHIR package of conformance resources to an endpoint, even when the package does not contain an entire Implementation Guide.

An InterSystems FHIR endpoint can support multiple FHIR packages. For example, a FHIR endpoint can support the package of the US Core Implementation Guide while simultaneously supporting a unique Patient profile or search parameter from a custom package. This allows FHIR clients to search and use resources that conform to all of the supported packages.

In adherence to the FHIR specification, an InterSystems FHIR server does not automatically verify whether a resource that it receives from a FHIR client conforms to a supported profile. The FHIR client asserts that a resource conforms to one or more profiles using the meta element of the resource, but the FHIR server does not check whether that assertion is true. A FHIR client can use the _profile search parameter to retrieve resources that claim to conform to a profile.

Because FHIR servers support variations of the core FHIR specification, it is important that FHIR clients be able to determine exactly what is acceptable and possible with the FHIR server. To meet this need, every FHIR server must provide a Capability Statement that identifies the APIs, FHIR operations, search parameters, and resources that it supports. FHIR clients can retrieve this Capability Statement with a call to GET [EndpointBaseURL]/metadata.

Working with FHIR Packages

Within InterSystems products, a FHIR package is a collection of conformance resources, like StructureDefinitions and SearchParameters. In this way, packages contain the profiles for a healthcare environment. A package can contain the standard conformance resources for a version of FHIR or it can extend or constrain a version of FHIR for a specific purpose. These packages are distributed and imported as NPM packages of JSON files. The contents of a package can vary widely; it can be used to distribute a national Implementation Guide (for example, US Core) or be limited to a Patient profile that is unique to a health network. In some cases, you might need to configure an endpoint using a standard, published package that can be downloaded from a distribution site. In other cases, you might develop your own package that contains custom profiles and search parameters.

If you need to work with packages programmatically, see Package APIs.

Importing Packages

Before you can configure an endpoint to support an Implementation Guide or custom package, you need to import the published or custom package using the Management Portal. Some standard packages are available by default (for example, US Core), and do not need to be imported before applying them to an endpoint.

To import a package:

  1. Make sure the JSON files of the package are on your local machine. If you are importing a published package, download it from the distribution site to your local machine. For additional requirements for a custom package, see Creating Custom Packages.

  2. In the Management Portal, navigate to Home > Health > MyFHIRNamespace > FHIR Configuration.

  3. Select the Package Configuration card.

  4. Make sure that the dependencies of the new package have already been imported. You can review which packages have been imported by looking at the left hand navigation bar of the Package Configuration page.

  5. Select Import Package.

  6. Select the directory that contains the package’s JSON files. Do not select the individual files.

  7. Select Import.

The package of profiles and other artifacts that were contained in the FHIR package are now available for an endpoint.

Uninstalling Packages

You can remove a package from the FHIR server’s namespace if it is not a dependency of another package and has not been applied to an existing endpoint. Uninstalling a package does not delete the local JSON files that were used to import the package. To uninstall a package:

  1. In the Management Portal, navigate to Home > Health > MyFHIRNamespace > FHIR Configuration.

  2. Select the Package Configuration card.

  3. Select the package from the left hand navigation bar.

  4. Select Uninstall Package. You cannot uninstall a package that has been applied to an endpoint. In addition, you cannot uninstall a package that is a dependency of another package.

Creating Custom Packages

You can use a custom package to configure your FHIR endpoint to support a custom profile or search parameter. For example, to add a custom search parameter, define a SearchParameter resource in a JSON file on your local machine. Then, create a file called package.json in the same directory. At a minimum, this file must include the name, version, and dependencies of the package. For example, the package.json file might look like:

{
  "name":"myorg.implementation.r5",
  "version":"0.0.1",
  "dependencies": {
    "hl7.fhir.r5.core":"5.0.0"
  }
}

Once you have JSON files with conformance resource definitions and a package.json file in a directory, you are ready to import the new package.

Applying Packages to an Endpoint

When you create a new FHIR endpoint, you can select a package that the endpoint will support. Only those packages that have been imported are available when creating the endpoint; InterSystems products come with a few published packages already imported.

You can also apply a new package to an existing endpoint. To add a package to an existing endpoint:

  1. In the Management Portal, navigate to Home > Health > [MyFHIRNamespace] > FHIR Configuration.

  2. Select the Server Configuration card.

  3. Select the endpoint from the list.

  4. Select Edit.

  5. Use the Additional Packages drop-down list to select the package. If you do not see the package in the list, make sure you have imported the package.

  6. Select Update.

Important:

If you are applying a package to an existing endpoint, and the package has new search parameters, the new parameters cannot be used to retrieve pre-existing resources until you re-index the endpoint. For details, see Re-indexing an Endpoint

Re-indexing an Endpoint

When you add new search parameters to an existing endpoint using a published or custom package, FHIR clients can use the new parameter to retrieve resources added to the repository after you applied the package. However, resources that existed before you added the new search parameter will not be returned until you re-index the endpoint. Until the endpoint is re-indexed, a FHIR client that uses the new search parameter receives an OperationOutcome stating that the search results might be incomplete.

Once you have applied a package that contains new search parameters, an option to re-index the endpoint appears next to the endpoint’s URL on the Server Configuration page (Health > FHIR Configuration > Server Configuration). If the repository has a lot of pre-existing resources, it can take a significant amount of time to re-index the endpoint.

Package APIs

If your implementation needs to work with packages directly without using the user interface, you can leverage the following API methods.

Importing Packages

The InterSystems FHIR server uses packages to determine which FHIR profiles and other assets it supports. While InterSystems products come with pre-loaded packages that correspond to base FHIR versions and popular Implementation Guides, you can also import new packages by specifying a directory that contains the JSON files that define conformance resources like StructureDefinition and ValueSet. For more information about FHIR packages, see Working with Packages.

The API for importing a new package so it can be added to an endpoint is HS.FHIRMeta.Load.NpmLoader.importPackages()Opens in a new tab. For example, the following code would import a custom package:

 do ##class(HS.FHIRMeta.Load.NpmLoader).importPackages($lb("C:\fhir-packages\node_modules\myorg.fhir.myPackage\"))
Listing Available Packages

To obtain a list of the packages that have been imported into the namespace, use the HS.FHIRMeta.Storage.Package.GetAllPackages()Opens in a new tab method. For example, the following code displays the identifiers of the available packages:

 set packages = ##class(HS.FHIRMeta.Storage.Package).GetAllPackages()
 for i=1:1:packages.Count()
   { write packages.GetAt(i).id,! }
Specifying a Package when Creating an Endpoint

The pPackageList parameter of the InstallInstance() method allows you to specify the packages you want applied to a new endpoint. For more details, see installing a FHIR server programmatically.

Adding Packages to an Existing Endpoint

If you need to add a package to an existing endpoint, you can leverage the HS.FHIRServer.Installer.AddPackagesToInstance()Opens in a new tab method.

Uninstalling a Package

You can use HS.FHIRMeta.Load.NpmLoader.UninstallPackage()Opens in a new tab to remove a package from the FHIR server’s namespace if it is not a dependency of another package and has not been applied to an existing endpoint. Uninstalling a package does not delete the local JSON files that were used to import the package. You can determine the id of the package you want to uninstall by Listing Available Packages. As an example, the call to uninstall a package might look like:

 do ##class(HS.FHIRMeta.Load.NpmLoader).UninstallPackage("myorg.r5@1.0.0")

Custom Search Parameters

Adding a custom search parameter to an endpoint consists of creating a custom package with the SearchParameter resource and applying it to the endpoint. To complete the process:

Extensions

The FHIR server accepts a resource with extensions as long as it is well-formed according to the syntax for extensions defined by the base FHIR specification. In adherence to the FHIR specification, the FHIR server does not automatically verify whether those extensions are valid or conform to the profile specified in the resource’s meta field.

For information about adding custom search parameters for an extension, see Custom Search Parameters.

FeedbackOpens in a new tab