Skip to main content
Previous sectionNext section

Profiling FHIR

According to the FHIR® specification, FHIR is a “platform specification” that requires modification to be suitable for a healthcare implementation and purpose. Adapting FHIR resources, frameworks, and API for a specific healthcare purpose is known as Profiling. The InterSystems FHIR server supports profiling FHIR in the following ways:

Important:

When profiling, never modify the base metadata files installed with your InterSystems product; create a custom metadata set that extends this base metadata. As an exception, modifying the capability statement does not require creating a custom metadata set.

Modifying the Capability Statement

The FHIR server’s capability statement is client-facing metadata that documents how the server behaves; FHIR clients can retrieve the capability statement to determine what the server expects and how it will process FHIR requests. This capability statement can be edited to make small changes like changing the server’s name and description, or to describe functional changes like which resources the server accepts or what FHIR operations are available. In InterSystems products, updating the capability statement consists of retrieving it from the server, editing it, posting it back to the server.

Note:

Do not update the capability statement when adding custom search parameters. The capability statement is updated automatically when you update the custom metadata set that contains the new search parameters.

Retrieving the Capability Statement

InterSystems strongly recommends retrieving the current capability statement from the server and modifying it rather than writing a new one. You can retrieve the capability statement resource with a REST client or programmatically. In the following examples, assume the IP address of the InterSystems server is 172.16.144.98, the superserver port is 52782, and the base url of the endpoint is /fhirapp/namespace/fhir/r4.

  • To retrieve the capability statement with a REST client, send a GET request to base-url/metadata. For example:

    GET http://172.16.144.98:52782/fhirapp/namespace/fhir/r4/metadata

  • To retrieve the capability statement programmatically, enter:

    set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint("/csp/fhirapp/namespace/fhir/r4")
    set interactions = strategy.NewInteractionsInstance()
    set capabilityStatement = interactions.LoadMetadata()
    Copy code to clipboard

Once retrieved, the capability statement can be edited with an external editor or third-party tool. Capability statements retrieved programmatically must be converted from a dynamic object to a JSON file before modifying it.

Updating the Capability Statement

Once you have modified the capability statement, submit the revised version to the server programmatically from the InterSystems Terminal. In the following example, /fhirapp/namespace/fhir/r4 is the endpoint’s base url and MyCapabilityStatment.json is the revised version. The {}.%FromJson method takes a JSON file and puts it into a dynamic object.

set strategy = ##class(HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint("/fhirapp/rnamespace/fhir/r4")
set interactions = strategy.NewInteractionsInstance()
set newCapabilityStatement = {}.%FromJson("c:\localdata\MyCapabilityStatement.json")
do interactions.SetMetadata(newCapabilityStatement)
Copy code to clipboard

Extensions

The FHIR server accepts a resource with extensions as long as it is well-formed according to the FHIR syntax for extensions. For information about adding custom search parameters for an extension, see Custom Search Paramters.

Custom Metadata Sets

By default, the installation process creates an endpoint based on the base metadata for a particular FHIR version. If you are planning to customize the FHIR server’s metadata, for example by creating custom search parameters, create a custom metadata set before beginning the installation process, even if you plan to wait to implement the customizations.

Note:

Though the server’s capability statement is considered metadata, it is customized in a different manner. For more information, see Modifying the Capability Statement.

To create a custom metadata set:

  1. From the InterSystems Terminal, change to the FHIR server’s namespace. For example:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard
  2. Run the installation and configuration utility:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  3. Choose option 8) Create a custom metadata set.

  4. Choose the base FHIR metadata for the FHIR version of your endpoint. The custom metadata set extends this base metadata.

  5. Enter a name of the metadata set. This name appears when you are installing a new endpoint.

  6. Enter a description of the metadata set.

  7. Enter the directory that contains or will contain the custom metadata. For example, this is the directory that contains or will contain JSON files with custom search parameters. If the directory you specified for the custom metadata is empty, you must update the metadata set once you add files to the directory.

Now that you have created a custom metadata set, it appears as an option when installing an endpoint.

Updating a Custom Metadata Set

Whenever files are added to the custom metadata directory or the content of those files changes, you must update the metadata set so the server picks up the changes. The directory was specified when the custom metadata set was created. To update a custom metadata set:

  1. From the InterSystems Terminal, change to the FHIR server’s namespace. For example:

    set $namespace = "FHIRNamespace"
    Copy code to clipboard
  2. Run the installation and configuration utility:

    do ##class(HS.FHIRServer.ConsoleSetup).Setup()
    Copy code to clipboard
  3. Choose option 9) Update a custom metadata set.

  4. Choose the custom metadata set you are updating.

  5. If desired, enter a new description of the custom metadata set.

  6. If desired, enter a new directory that contains the custom metadata.

  7. When you see the prompt Do you want to update the metadata cache?, enter one of the following:

    • If you have added new metadata to the directory, choose Y to rebuild the search tables and add the metadata to the capability statement. Be aware that this can be a lengthy process.

    • If you only changed the description of the metadata, choose N.

Custom Search Parameters

The search parameters that a client can use to retrieve resources from the FHIR server are defined by SearchParameter resources. In many cases, custom search parameters need to be added for custom extensions on resources.

To define custom search parameters, start by using an external editor or third-party tool like Forge to create JSON files that contain the new SearchParameter resources. Each JSON file must include a single bundle that contains one or more SearchParameter resources. You can define multiple files in which each bundle contains a single SearchParameter resource, or define a single file in which the bundle contains multiple SearchParameter resources.

The next step in the process depends on how the endpoint was installed:

  • If the endpoint was installed using the base metadata rather than a custom metadata set, you will have to install a new endpoint. Create a custom metadata set that specifies the directory with the JSON files, and then install the new endpoint.

  • If the endpoint was installed using a custom metadata set, place the JSON files in its custom metadata directory and update the metadata set. You are given the option of specifying a new directory for the JSON files when you update the metadata set.

  • If the endpoint has not been installed yet, create a new metadata set and specify the directory with the JSON files.

Note:

You do not need to manually edit the server’s capability statement when you add custom search parameters; the capability statement is automatically updated when you update the custom metadata set.