Supported 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
FHIR interactions 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 |
---|---|
create | Fully supported, including conditional create. |
read | The _elements parameter is not supported.
Conditional read is not supported. |
vread | The _elements parameter is not supported.
Conditional read is not supported. |
update | Fully supported, including conditional update. |
patch | Only JSON Patch documents are supported. |
delete | Fully supported, including conditional delete. |
history |
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. |
batch | Fully supported |
transaction | 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 specification. This section summarizes the default support for the search interaction when the FHIR server is using or extending the Resource Repository.
General Limitations
Keep in mind that a FHIR server using or extending the Resource Repository has the following limitations:
-
Does not support searching across multiple resource types. For example GET [base]?_id=1 is not supported.
-
You cannot perform a search on all resource types within a compartment. For example, you cannot search for [base]/Patient/10000001/?_id=008. Therefore, searches within the context of a compartment must specify a resource type in that compartment. For example, you can use [base]/Patient/100000001/Observation to return all Observations in the specific patient’s compartment or [base]/Patient/100000001/Observation?status=final to search for a subset of Observations within the compartment. If you want to retrieve a Patient’s entire compartment, use the $everything operation (for example, [base]/Patient/100000001/$everything).
Search Parameter Types
Each search parameter has a search parameter type that determines how the parameter behaves.
Parameter Type | Level of Support |
---|---|
number | Fully supported |
date | Fully supported |
string | Fully supported |
token | Fully supported |
reference | Fully supported |
composite | Not supported |
quantity | Fully supported |
uri | Fully supported |
Parameters
The following summarizes FHIR server support for standard search parameters when retrieving resources from the Resource Repository.
Parameter | Level of Support |
---|---|
_id | Fully supported as described in the official specification |
_lastUpdated | Fully supported as described in the official specification |
_tag | Fully supported as described in the official specification |
_profile | Fully supported as described in the official specification |
_security | Fully supported as described in the official specification |
_text | Not supported |
_content | Not supported |
_list | Not supported |
_source | Fully supported |
_has | Fully supported as described in the official specification |
_type | Not supported. (Note that the operation query parameter _type is supported for Patient and Encounter $everything.) |
_filter | Not supported |
_query | Not supported |
Modifiers
Modifiers can be added to the end of a parameter to affect the results of the search.
Modifier | Level of Support |
---|---|
:missing | Not supported |
:exact | Supported for strings except for accented characters. For example, ?given:exact=Nino returns Patient with given name Niño. |
:contains | Supported for strings |
:above | Supported for uri |
:below | Supported for uri |
:type | Supported for references |
:text | Not supported |
Prefixes
When using search parameters of type number, date, and quantity, you can add a prefix 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 | Not supported |
eb | Not supported |
ap | Not supported |
Search Result Parameters
Search result parameters help manage the resources returned by a search.
Search result parameter | Level of Support |
---|---|
_sort | Fully supported as described in the official specification |
_count | Fully supported as described in the official specification |
_include | Fully supported as described in the official specification |
_revinclude | Fully supported as described in the official specification |
_summary | Supports _summary=count only. For details, see the official specification. |
_total | Not supported |
_elements | Not supported |
_contained | Not supported |
_containedType | 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 Group and MedicinalProduct. |
$validate |
The validation modes (create, update, delete) are supported.
Validation by profile is not supported.
When a FHIR $validate request includes a resource payload, the resource may be enclosed in a Parameters resource. |
$lastn | Fully supported |
Operation Query Parameters
For specific operations, certain operation query parameters are supported:
Operation | Query Parameter |
---|---|
$everything |
_type is supported for Patient and Encounter.
See “Recursive Behavior of the _type Operation Query Parameter for $everything” for details. |
$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 Patient 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.
Migrating from Legacy Resource Repository
For FHIR servers developed using InterSystems IRIS for Health 2019.4 or earlier, the data in the legacy 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 legacy FHIR server, and then create a STU3 endpoint.
-
Open the InterSystems Terminal and navigate to the namespace of your legacy FHIR server.
-
Run:
do ##class(HS.FHIRServer.ConsoleSetup).Migrate()
-
Select the STU3 endpoint and confirm the migration.