Skip to main content
Previous sectionNext section

FHIR Profiles and Adaptations

The 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 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, that extend or constrain 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.

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.r4",
  "version":"0.0.1",
  "dependencies": {
    "hl7.fhir.r4.core":"4.0.1"
  }
}
Copy code to clipboard

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, you must run a utility before the parameters can be used to query existing resources. For details, see Enabling New Search Parameters

Enabling New Search Parameters

When you add new search parameters to an existing endpoint using a published or custom package, you need to run a utility before those parameters can be used to query existing resources. The parameters can be used to query resources added after the package was applied to the endpoint, but pre-existing resources will not be returned until you run the utility. In addition, the utility adds the search parameters to the Capability Statement. If the repository has a lot of pre-existing resources, it can take a significant amount of time for the utility to run.

To run the utility:

  1. Open the InterSystems Terminal.

  2. Change to the namespace of your FHIR server. For example, if the namespace is MyFHIRnamespace, enter:

    set $namespace = "MyFHIRnamespace"
    Copy code to clipboard
  3. Run:

    do ##class(HS.FHIRServer.Storage.Json.Tools.Index).upgradeServiceMetadata("/MyURL")
    Copy code to clipboard

    Where /MyURL is the FHIR endpoint. Make sure to include the leading slash (/). To find the endpoint, use the Management Portal to navigate to Health > MyFHIRnamespace > FHIR Configuration > Server Configuration.

Package APIs

If your implementation needs to work with packages directly without using the user interface, you can leverage the following API methods to import packages, add packages to an endpoint, and list all available packages in the namespace.

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(). 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\"))
Copy code to clipboard
Listing Available Packages

To obtain a list of the packages that have been imported into the namespace, use the HS.FHIRMeta.Storage.Package.GetAllPackages() 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,! }
Copy code to clipboard
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() method.

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 Creating Custom Packages.

Feedback