FHIR Profiles and Adaptations

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 Server Management. Click Go.

3. Select the Package Management icon from the left-hand navitation area.

4. Make sure that the dependencies of the new package have already been imported.

   The packages currently available in this namespace are displayed in the left-hand column. For information about a particular package, select its name from the list and view details in the right-hand column.

5. Select Import Package.

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

   The Preview area of the dialog displays the name, version, and description of the package in the selected directory.

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 Server Management.

2. Select the Package Configuration card.

3. Select the package from the list of packages in the left-hand column.

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 Server Management.

2. In the tile for the desired endpoint, open the menu and choose Edit.

3. If this namespace contains packages appropriate for the selected server, the Custom Packages dropdown is displayed. For example, if only packages dependent on FHIR R4 are available, this dropdown does not appear on a server configured for FHIR R3 or R5.

   In the Custom Packages dropdown, select the desired package. If you do not see the package in the list, make sure you have imported the package.

   Note:

   Enabling a custom package triggers the system to re-index search tables when you save your changes.

4. Select Save.

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,! }

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")