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. |
Search Interaction
FHIR clients use the search interaction to retrieve resources from the Resource Repository. For full details about the search interaction, refer to FHIR specificationOpens in a new tab. This section summarizes the default support for the search interaction when the FHIR server is using or extending the Resource Repository.
Prior to version 2024.1, the Resource Repository’s search interaction was implemented using a different search strategy. This legacy strategy is still supported in this version; however, they provide a limited set of features compared to the current strategy, described in this documentation.
If you have upgraded an instance with a preexisting Resource Repository to this version from a version prior to 2024.1, see JSON Legacy SQL Strategy for a comparison of supported features and instructions for upgrading your Resource Repository from the legacy strategy to the current strategy.
General Support Notes
Keep in mind that a FHIR server using or extending the Resource Repository:
-
Does not support searching across multiple resource types across compartments. For example GET [base]?_id=1 is not supported.
-
Does support the use of the wildcard character (*) to search across multiple resource types within a compartment. For example: GET [base]/Patient/100000001/* is supported. Within a compartment, the search can use the wildcard in conjunction with any search parameters common to all the resource types which the search is targeting. This is especially useful if you use the _type parameter. For example: GET [base]/Patient/100000001/*?status=final&_type=Observation,DiagnosticReport is supported because both the Observation and DiagnosticReport resource type include the status element.
Note:The wildcard syntax provides a different result than the $everything operation. GET [base]/Patient/100000001/* returns any and all resources associated with the specified Patient—including, for example, a Patient’s DiagnosticReport resources. By contrast, GET [base]/Patient/100000001/$everything returns all resources associated with the Patient resource as well as resources associated with those resources. Compared with the previous search, this search would also include Practitioner resources associated with the Patient’s DiagnosticReport resources.
Search Parameter Types
Each search parameter has a search parameter typeOpens in a new tab that determines how the parameter behaves.
Parameter Type | Level of Support |
---|---|
compositeOpens in a new tab | Not supported |
dateOpens in a new tab | Fully supported |
numberOpens in a new tab | Fully supported |
quantityOpens in a new tab | Fully supported |
referenceOpens in a new tab | Fully supported* |
stringOpens in a new tab | Fully supported |
tokenOpens in a new tab | Fully supported |
uriOpens in a new tab | Fully supported |
* For canonical references, chained search is not supported. The use of the search result parameters _include and _revinclude for canonical references is also not supported.
Parameters
The following summarizes FHIR server support for standard search parametersOpens in a new tab when retrieving resources from the Resource Repository.
Parameter | Level of Support |
---|---|
_content | Not supported |
_filter | Not supported |
_has | Fully supported as described in the official specificationOpens in a new tab |
_id | Fully supported as described in the official specificationOpens in a new tab |
_lastUpdated | Fully supported as described in the official specificationOpens in a new tab |
_list | Not supported |
_profile | Fully supported as described in the official specificationOpens in a new tab |
_query | Not supported |
_security | Fully supported as described in the official specificationOpens in a new tab |
_source | Fully supported |
_tag | Fully supported as described in the official specificationOpens in a new tab |
_text | Not supported |
_type | Fully supported. |
Modifiers
ModifiersOpens in a new tab can be added to the end of a parameter to affect the results of the search.
Modifier | Level of Support |
---|---|
:above | Supported for URI |
:below | Supported for URI |
:code-text | Not supported |
:contains | Fully supported (strings and URIs) |
:exact | Fully supported |
:identifier | Fully supported |
:in | Not supported |
:iterate | Fully supported |
:missing | Fully supported |
:not | Fully supported |
:not-in | Not supported |
:of-type | Fully supported |
:text | Supported for references and tokens, not supported for strings |
:text-advanced | Not supported |
:[type] | Fully supported |
Prefixes
When using search parameters of type number, date, and quantity, you can add a prefixOpens in a new tab to the parameter’s value to affect what resources match the search. For example, [parameter]=le100 returns values that are less than or equal to 100.
Prefix | Level of Support |
---|---|
eq | Fully supported |
ne | Fully supported |
gt | Fully supported |
lt | Fully supported |
ge | Fully supported |
le | Fully supported |
sa | Fully supported |
eb | Fully supported |
ap | Fully supported |
Search Result Parameters
Search result parametersOpens in a new tab help manage the resources returned by a search.
Search result parameter | Level of Support |
---|---|
_contained | Not supported |
_containedType | Not supported |
_count | Fully supported as described in the official specificationOpens in a new tab |
_elements | Fully supported as described in the official specificationOpens in a new tab |
_graph | Not supported |
_include | Fully supported as described in the official specificationOpens in a new tab |
_maxresults | Fully supported as described in the official specificationOpens in a new tab.
Note:
Queries using this parameter can be made more efficient by setting the Use TOP for _maxresults FHIR configuration setting. See the table in Configuring an Existing FHIR Server for details and important considerations. |
_revinclude | Fully supported as described in the official specificationOpens in a new tab |
_score | Not supported |
_sort | Fully supported as described in the official specificationOpens in a new tab |
_summary | Supports _summary=count, _summary=data, and _summary=text. For details, see the official specificationOpens in a new tab. |
_total | Not supported |
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. |
$lastn | Fully supported |
$validate |
Partially supported. See “Profile Validation”. |
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:
-
/Patient/123/$everything?_type=DiagnosticReport,Observation — returns DiagnosticReport and Observation resources but not the Patient resource.
-
/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.
-
/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.
-
/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
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.
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:
-
In the Management Portal, switch to the namespace of your pre-2020.1 FHIR server, and then create a STU3 endpoint.
-
Open the InterSystems Terminal and navigate to the namespace of your pre-2020.1 FHIR server.
-
Run:
do ##class(HS.FHIRServer.ConsoleSetup).Migrate()
-
Select the STU3 endpoint and confirm the migration.