Skip to main content
Previous section   Next section

FHIR Operations

The FHIR server supports FHIR operations that perform special functions based on requests from the FHIR client using an RPC-like approach rather than a RESTful one. These can be standard FHIR operations like $everything or custom ones. InterSystems IRIS for Health applications using the Resource Repository already support certain standard FHIR operations (see What is Supported? for a complete list). A FHIR server in Health Connect does not use the Resource Repository, so there are no default operations.

The following is an overview of the process of adding FHIR operations to your FHIR server.

  1. Subclass the FHIR server’s Interactions and InteractionsStrategy classes. If you are using the Resource Repository with InterSystems IRIS for Health, you want to subclass HS.FHIRServer.Storage.JSON.Interactions and HS.FHIRServer.Storage.JSON.InteractionsStrategy.

  2. Create a subclass of HS.FHIRServer.API.OperationHandler. If you are using the Resource Repository that comes with InterSystems IRIS for Health, subclass HSFHIRServer.Storage.BuiltInOperations instead of HS.FHIRServer.API.OperationHandler so you do not lose the default operations like $everything. As a best practice, you might want to create a separate subclass for each operation, and then create a master class that inherits from all of them.

  3. In your Interactions subclass, override the value of the OperationHandlerClass parameter to be the classname of the operation subclass that you just created.

  4. Write a method for each operation in your operation handler subclass.

  5. Add the operations to the CapabilityStatement resource.

The following sections provide more details on the last two steps of the process.

Writing Methods for Custom Operations

Operations supported by the FHIR server correspond directly to methods in the operation handler subclass. The names of these methods must conform to the following syntax:

FHIRScopeOpOperationName

Within this syntax, the variables are:

  • Scope identifies the type of endpoint to which the FHIR client is appending the operation. Possible values are:

    • System — Identifies operations that are appended to a “base” FHIR endpoint (for example, http://fhirserver.org/fhir). These operations apply to the entire server.

    • Type — Identifies operations that are appended to a FHIR endpoint with a resource type (for example, http://fhirserver.org/fhir/Patient). These operations work with all instances of the specified resource type.

    • Instance — Identifies operations that are appended to a FHIR endpoint that points to a specific instance of a resource (for example, http://fhirserver.org/fhir/Patient/1). These operations work solely with a specific instance of a resource.

  • OperationName is the $ operation that the FHIR client appends to its call to the server.

The following table of examples shows the correlation between method names and the operations called by a FHIR client.

Method name REST client call to the operation
FHIRSystemOpMyoperation http://fhirserver.org/fhir/$myoperation
FHIRTypeOpValidate http://fhirserver.org/fhir/Observation/$validate
FHIRInstanceOpEverything http://fhirserver.org/fhir/Patient/1/$everything

If your operation contains a hyphen (-), just remove the hyphen from the method name. For example, if the system-wide operation is $my-operation, name the method FHIRSystemOpMyoperation.

The following is an example of the method signature for $everything:

ClassMethod FHIRInstanceOpEverything(pService As HS.FHIRServer.API.Service, 
  pRequest As HS.FHIRServer.API.Data.Request, 
  pResponse As HS.FHIRServer.API.Data.Response)
Copy code to clipboard

Adding the Operation to Capability Statement

The capability statement of the FHIR server must include all of the operations that the server supports. If the FHIR server is using a custom capability statement, manually update the capability statement to include the new operations.

Most FHIR server use a capability statement that has been customized in some way. However, if the FHIR server is using the default capability statement provided with your InterSystems product, you can use the following two-step procedure to automatically add a new operation to the capability statement.

  1. Add the operation to the AddSupportedOperations method of the operation handler subclass. When the command-line utility generates the server’s capability statement, it takes the supported operations from this method. As an example, the operation handling class for a server that supports the $everything operations would include a method that looked like:

    ClassMethod AddSupportedOperations(pMap As %DynamicObject) 
      {
        Do pMap.%Set("everything","http://hl7.org/fhir/OperationDefinition/patient-everything")
      }
    Copy code to clipboard

    If the superclass of your operation handling class already includes some operations, be sure to call the AddSupportedOperations method of that superclass within the AddSupportedOperations of the subclass. For example, the method of the operation handling subclass might look like:

    ClassMethod AddSupportedOperations(pMap As %DynamicObject)
      {
        Do ##class(HS.FHIRServer.MySuperclass.Validate).AddSupportedOperations(pMap)
        Do pMap.%Set("everything", "http://hl7.org/fhir/OperationDefinition/patient-everything")
      }
    Copy code to clipboard

    If you created a subclass for each operation and a master class that inherits from all of them, make sure the master class calls the AddSupportedOperations method of each operation’s subclass.

  2. Use the command-line utility to re-generate the capability statement:

    Important:

    Do not use the command-line utility to update the capability statement if the FHIR server is using a custom capability statement because the custom one will be overwritten. In these cases, manually update the capability statement with the new operations.

    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 5) Update the CapabilityStatement Resource.

    4. Select the endpoint you are configuring.

    5. Specify whether you want the endpoint to be read-only.

    6. Confirm your selection.

Previous section   Next section