Skip to main content

Supported FHIR Interactions and Operations

When using the Resource Repository storage strategy provided with the FHIR server, the server supports the following interactions and operations. If your custom FHIR server extends the Resource Repository, it also supports these interactions and operations by default.

Interactions

HL7® FHIR® interactionsOpens in a new tab are the set of actions that a FHIR client can take on resources. These interactions can be grouped according to whether they act upon an instance, a type, or the whole system. An instance is a specific instance of a resource, for example, Patient/1 refers to an instance of a Patient resource with an id of 1. A type refers to a particular FHIR resource, for example, a Patient or Observation.

The following table summarizes the support for FHIR interactions in the Resource Repository, or a custom FHIR server that has extended the Resource Repository. Click on an interaction to see how it is defined in the HL7 REST API and how to use it.

Interaction Level of Support
createOpens in a new tab Fully supported, including conditional create.
readOpens in a new tab

Conditional read is not supported.
vreadOpens in a new tab

Conditional read is not supported.
updateOpens in a new tab Fully supported, including conditional update.
patchOpens in a new tab Supported for JSON patch documents only. Conditional patch is supported.
deleteOpens in a new tab Fully supported, including conditional delete.
historyOpens in a new tab

Supported for instance interactions only, not type or system. For example, GET [baseURL]/Patient/1/_history is supported, but not GET [baseURL]/Patient/_history or GET [baseURL]/_history.

The _count and _at parameters are not supported.

Paging is not supported.
batchOpens in a new tab Fully supported
transactionOpens in a new tab Circular references within the bundle are not supported.
search Supported with some limitations. For details, see Search Interaction.

Operations

For FHIR servers using or extending the default Resource Repository, the following operations are supported:

Operation Level of Support
$everything

Fully supported for Patient and Encounter.

Not supported for EpisodeOfCare, Group, MedicinalProduct, or MedicinalProductDefinition.
$find Fully supported
$lastn Fully supported
$update-functional Not part of the FHIR specification. See Working With Functional Lists for details.
$validate

Partially supported. See Profile Validation.

Working with Functional Lists

A functional list, also called a current resource list, is a List resource populated with the subset of relevant information that is currently in use. For example, a patient’s $current-problems functional list includes only those injuries and illnesses that the patient is currently suffering; this list would not include illnesses and injuries from which the patient has fully recovered. Each functional list is specific to a particular subject resource, often a Patient. For full details about functional lists, see the FHIR specificationOpens in a new tab.

Note:

The particular functional lists that your FHIR server recognizes are defined in the Functional List Configuration field in the Interactions Strategy Settings section of the server settings. By default, the following functional lists are defined: $current-problems, $current-medications, $current-allergies, $current-drug-allergies. If you wish to work with a functional list that is not defined for the server, you must first add it to the Functional List Configuration field.

The $update-functional operation facilitates creation and updating of functional lists.

To update a particular functional list, use $update-functional in a POST query, specifying the target functional list name in the URL, and including the desired contents of the List resource in the request body, either directly as a standalone List resource or encased in a Parameters resource. If the specified List resource already exists, it will be replaced with the List resource you sent in the request body. If the specified List resource does not yet exist, it will be created with the contents of the List resource you sent.

For example:

POST [base]/List/$update-functional?for=[subject_resource_id]&name=[functional_list_name]

In the request body:
{
  "resourceType": "List",
     ...
  "entry": [
      {
        "item": {
           "reference": "Condition/7"
        }
      },
      {
        "item": {
           "reference": "Condition/17"
        }
      },
      {
        "item": {
           "reference": "Condition/20"
        }
      }
    ]
...
}
subject_resource_id

The resource ID of the functional list’s subject. For example, if the functional list being updated is the $current-problems list for Patient/123, subject_resource_id would be 123, and the syntax would be for=123.

functional_list_name

Set the name parameter equal to the desired functional list name. The initial $ must be escaped using a \ character. For example name=\$current-problems

Operation Query Parameters

For specific operations, certain operation query parameters are supported:

Operation Query Parameter
$everything
$lastn max is supported.

Recursive Behavior of the _type Operation Query Parameter for $everything

When a list of resource types is provided in the _type query parameter for the $everything operation, the compartment search will return only resources of the type listed. Recursive resource reference retrieval in the compartment will skip over references to resource types that are not specified in the _types parameter. Some examples illustrate how the _type query parameter for $everything operates on the PatientOpens in a new tab compartment:

  1. /Patient/123/$everything?_type=DiagnosticReport,Observation — returns DiagnosticReport and Observation resources but not the Patient resource.

  2. /Patient/123/$everything?_type=Observation — returns the patient's Observation resources, even though the referring DiagnosticReport resources are not included, because Observation is also in the Patient compartment.

  3. /Patient/123/$everything?_type=Practitioner — returns nothing. Practitioner is not in the Patient compartment, and no other resource type that could refer to Practitioner was specified.

  4. /Patient/123/$everything?_type=Patient,DiagnosticReport,Practitioner — returns the Patient resource, all of the DiagnosticReport resources, and only the Practitioner resources directly referred to by the returned DiagnosticReport resources.

Profile Validation

Note:

Profile validation is currently designed to work only with FHIR version R4. Later releases will target R5.

Intersystems IRIS for Health supports profile validation by implementing part of the FHIR standardOpens in a new tab for the $validate operation, which checks a resource against the most recent version of a specified profile.

Note:

Although the standard allows use of a snapshot or a differentialOpens in a new tab, profile validation provided by InterSystems IRIS for health requires the use of a snapshot.

The following query syntax options are supported:

  • You can specify the profile in the query URL:

    Query URL POST <FHIR Endpoint>/<Resource Type>/$validate?profile=<Profile URL>|<Profile Version Number>
    Body Resource details in XML or JSON format

    <Profile Version Number> is required. Note that the character separating <Profile URL> from <Profile Version Number> is a pipe, not a slash.

  • You can provide the profile in the query body, optionally specifying a supported mode:

    Query URL POST <FHIR Endpoint>/<Resource Type>/<Optional Resource ID>/$validate
    Body A Parameters block, which must include the resource details, and which may include the mode and a profile, in XML or JSON format.

    Providing a profile is optional. If no profile is provided, validation is performed based on the core schema for the resource type.

    <Optional Resource ID> may be required or forbidden, based on the value of the mode parameter, as follows:

    Value of mode ID Required? Checks Performed by $validate
    create Forbidden $validate operation confirms that no resource ID is included, and compares the potential new resource to the profile or the core schema for the resource type, if no profile is provided.
    update Required $validate operation checks that a resource ID is included in the request URL and matches the ID in the query body, that the resource URL resource type matches the resource included in the query body, and compares the potential outcome of the update to the profile or the core schema for the resource type, if no profile is provided.
    delete Required $validate operation checks to ensure that a resource ID is included in the request URL. This ID is required for the deletion operation, but no profile validation occurs.
    profile Required $validate operation checks to ensure that a resource ID is included in the request URL, and that a profile is specified either in the request body (in a Parameters resource) or as a query parameter in the request URL.
    unspecified Forbidden $validate operation checks the resource in the query body against the profile or the core schema for the resource type, if no profile is provided.

Migrate from Pre–2020.1 Resource Repository

For FHIR servers developed using InterSystems IRIS for Health 2019.4 or earlier, the data in the old Resource Repository must be migrated before using the new FHIR server architecture. To migrate your FHIR data:

  1. In the Management Portal, switch to the namespace of your pre-2020.1 FHIR server, and then create a STU3 endpoint.

  2. Open the InterSystems Terminal and navigate to the namespace of your pre-2020.1 FHIR server.

  3. Run:

     do ##class(HS.FHIRServer.ConsoleSetup).Migrate()

  4. Select the STU3 endpoint and confirm the migration.

FHIR Profiles and AdaptationsNext section
Previous sectionInstalling and Configuring a FHIR Server
FeedbackOpens in a new tab