27.2.1FHIR Gateway Configuration Document
The FHIR Gateway uses a JSON document to describe the specific functionality required. Configuration for the gateway consists of the following basic units:
-
Targets are internal/external FHIR servers that will ultimately process the requests received by the gateway
-
Routes are rules that govern which target or targets a request should be forwarded to
This configuration uses the GatewayConfiguration model. An example is shown below.
{
"targets": [
{
"id": "target1",
"baseUrl": "http://localhost:8000",
"fixedEndpointUrl": "http://fhir1.example.com/api",
"resourceIdPrefix": "TGT1-",
"forcedEncoding": "XML",
"headersToForward": ["Authorization"]
},
{
"id": "target2",
"baseUrl": "http://fhir2.example.com/api",
"resourceIdPrefix": "TGT2-",
"headersToForward": ["Authorization"],
"retryStrategy": {
"maxRetries": 3,
"backoffStrategy": "linear",
"backoffInterval": 100,
"errorRetryClasses": [
"ca.uhn.fhir.rest.server.exceptions.MethodNotAllowedException"
]
}
}
],
"searchRoutes": [
{
"id": "route1",
"resourceTypes": [
"Observation",
"Patient",
"Encounter"
],
"targets": [
{
"targetId": "target1"
},
{
"targetId": "target2"
}
],
"parallel": true
}
],
"readRoutes": [
{
"id": "readingRoute",
"resourceTypes": [
"Patient"
],
"targets": [
{
"targetId": "target1"
},
{
"targetId": "target2"
}
]
}
],
"operationRoutes": [
{
"id": "operatingRoute",
"resourceTypes": [
"Patient"
],
"targets": [
{
"targetId": "target1"
}
],
"parallel": true,
"operations": [
{
"name": "$everything",
"system": true,
"type": true,
"instance": false
},
{
"name": "$graphql",
"system": true,
"type": true,
"instance": true
},
{
"name": "$meta",
"system": true,
"type": true,
"instance": true
},
{
"name": "$meta-add",
"system": false,
"type": false,
"instance": true
},
{
"name": "$meta-delete",
"system": false,
"type": false,
"instance": true
},
{
"name": "$process-message",
"system": true,
"type": false,
"instance": false
}
]
}
],
"updateRoutes": [
{
"id": "updateRoute",
"resourceTypes": [
"Patient"
],
"targets": [
{
"targetId": "target1"
}
]
}
],
"createRoutes": [
{
"id": "createRoute",
"resourceTypes": [
"Patient"
],
"targets": [
{
"targetId": "target1"
}
]
}
],
"deleteRoutes": [
{
"id": "deleteRoute",
"resourceTypes": [
"Patient"
],
"targets": [
{
"targetId": "target1"
}
]
}
],
"historyRoutes": [
{
"id": "historyRoute",
"resourceTypes": [
"Patient"
],
"targets": [
{
"targetId": "target1"
}
]
}
]
}
27.2.2Defining Targets
The targets array in the gateway configuration uses the GatewayTarget model. It supports the following elements:
| Element | Required | Description |
|---|---|---|
| id | Yes |
An ID for this target. The ID must consist of only
letters, numbers, and the characters ._-.
The ID will appear in logs but is not visible to FHIR
clients.
|
| baseUrl | Yes | The base URL for the target FHIR server. |
| fixedEndpointUrl | No | The advertised fixed-value URL for the target FHIR server, if it differs from the baseUrl provided. For example, you may want gateway to connect to `localhost:8000`, but the publicly advertised endpoint is `https://myfhirserver.com/fhir`. This field should be populated with the [fixed value for endpoint](/docs/configuration_categories/fhir_rest_endpoint.html#property-fixed-value-for-endpoint-base-url) of the target server. |
| httpBasicCredentials | No | Supplies a username and password to be passed to the target server, in the form `username:password`. If credentials should be supplied dynamically (e.g. for OAuth2 support), credentials can instead be supplied using an interceptor. |
| connectTimeoutMillis socketTimeoutMillis |
No | Sets the connect and socket timeout values to use when communicating between Smile CDR and the target server. |
| resourceIdPrefix | No |
If this is supplied, resources from this target will
have the given prefix applied to their IDs. This is
useful for cases where two target servers are present,
and there is a possibility of conflicting IDs (e.g. if
both servers can potentially supply a resource with ID
Patient/123).If prefixes are used, all targets should have a prefix defined, and the prefixes should be short and conformant to the FHIR resource ID rules. Note that the maximum length for resource ids is 64 characters including the prefix and if exceeded will result in a violation of the FHIR specification. |
| useHttpPostForAllSearches | No |
If this is supplied a boolean value of true,
FHIR searches and paging against this target will always use the HTTP
POST format specified in the FHIR Specification, instead
of using HTTP GET. Default is false.
|
| serverCapabilityStatementValidationEnabled | No |
If this is supplied a boolean value of false,
the gateway will not validate the target server's
CapabilityStatement with a request to /metadata.
Default is true.
|
| alternateValidationPath | No |
Specify an alternate relative path to validate the target endpoint is reachable.
The validation is done as part of module diagnostics though HTTP GET with anonymous auth.
For cases where serverCapabilityStatementValidationEnabled is set to false
the relative path used will be this value, otherwise it will be the capability statement path.
|
| headersToForward | No |
Any headers specified by name will be copied from the incoming
client request and added to requests to the target server. i.e. "headersToForward": ["Authorization"]
|
| allowedToFail | No |
If this is supplied a boolean value of true,
the gateway will allow the target to fail in search routes,
without returning an error to the client unless
all targets for a given search request have failed.This permits sending partial target results in response to client requests when a target cannot be reached or fails to handle the request. Read routes are not modified by this target configuration and are still not allowed to fail without error sent to the client. Default is false.
|
| forcedEncoding | No | If this is supplied, any requests made to the target server will have their payloads re-encoded to the target encoding. This is useful in scenarios where a target server supports only XML or only JSON. Valid values are constants defined in EncodingEnum. |
| retryStrategy | No | If this is supplied, it defines how failed calls to this target should be handled. To learn more about this configuration, see Defining a Retry Strategy |
27.2.3Defining Search Routes
The searchRoutes array in the gateway configuration uses the GatewaySearchRoute model. It supports the following elements:
| Element | Required | Description |
|---|---|---|
| id | Yes |
An ID for this route. The ID must consist of only
letters, numbers, and the characters ._-.
The ID will appear in logs but is not visible to FHIR
clients.
|
| resourceTypes | Yes |
Contains a list of resource types (e.g. Patient) that this route applies to.
|
| targets | Yes | Supplies the list of targets that searches should be directed to. |
| parallel | No |
If parallel is set to true, the searches to each target server will be performed by the gateway in parallel. If parallel is set to false, the searches to each target server will be performed by the gateway in serial, in the order specified by the targets array.In both cases, the call by the calling client will not return until all target calls have completed. If not specified, the gateway will perform backing calls sequentially. |
27.2.4Defining Read, Create, Update, Delete, and History Routes
The readRoutes array in the gateway configuration uses the GatewayReadRoute model.
The updateRoutes array uses the GatewayUpdateRoute model.
The createRoutes array uses the GatewayCreateRoute model.
The deleteRoutes array uses the GatewayDeleteRoute model.
The historyRoutes array uses the GatewayHistoryRoute model.
It supports the following elements:
The following defines the elements used for each:
| Element | What routes (read, create, update, delete, and history) require this | Description |
|---|---|---|
| id | Required for Read, Create, Update, Delete, and History routes |
An ID for this route. The ID must consist of only
letters, numbers, and the characters ._-.
The ID will appear in logs but is not visible to FHIR
clients.
|
| resourceTypes | Required for Read, Create, Update, Delete, and History routes |
Contains a list of resource types (e.g. Patient) that this route applies so.
|
| targets | Required for Read, Create, Update, Delete, and History routes |
Supplies the list of targets that reads should be directed to.
A FHIR read will only be attempted against a single target, and the response (whether successful or unsuccessful) will be returned to the calling client. The target used will be the first target in the list which is able to handle the given request (a target will be skipped if it declares a resource ID prefix that is not present in the request). FHIR updates will be attempted against the first target that can also return a resource with the provided id. In the case of creates, the first route that matches the prefix of the id will be used for the create path. If no prefixes for targets are defined, and no interceptors provided, the first route will be used for any and all creates. Nota Bene Create with client supplied id will also use the prefix of the client supplied id to determine its path. But unlike other creates, create with client id will use configured updateRoutes, not createRoutes If a prefix is defined, delete will only be called on the first target that matches the prefix of the id. If no prefixes for targets are defined, and no interceptors provided, delete will be attempted on all routes. |
27.2.5Defining Operation Routes
The operationRoutes array in the gateway configuration uses the GatewayOperationRoute model.
The currently supported built-in operations are $graphql, $everything, $meta, $meta-add, $meta-delete and $process-message.
In addition to that, users can also define Custom Operations.
For $graphql operations, they will take into account resource types and resource ID prefix if provided and attempt the operation on the first eligible target. $graphql currently does not support aggregating results from multiple targets; It only returns results for the first successful target call.
It supports the following elements:
| Element | Required | Description |
|---|---|---|
| id | Yes |
An ID for this route. The ID must consist of only
letters, numbers, and the characters ._-.
The ID will appear in logs but is not visible to FHIR
clients.
|
| resourceTypes | Yes |
Contains a list of resource types (e.g. Patient) that this route applies so.
|
| targets | Yes | Supplies the list of targets that reads should be directed to. A FHIR read will only be attempted against a single target, and the response (whether successful or unsuccessful) will be returned to the calling client. The target used will be the first target in the list which is able to handle the given request (a target will be skipped if it declares a resource ID prefix that is not present in the request). |
| parallel | No |
If parallel is set to true, the operations to each target server will be performed by the gateway in parallel. If parallel is set to false, the operations to each target server will be performed by the gateway in serial, in the order specified by the targets array.Note that this only applies to operations which return bundles, such as the $everything operation. Operations which return a single resource, such as $meta, will always be performed in serial.In both cases, the call by the calling client will not return until all target calls have completed. If not specified, the gateway will perform backing calls sequentially. |
| operations | Yes |
Supplies the list of FHIR operations this route applies to. Each operation contains four elements:
|
27.2.6Defining a Retry Strategy
The retryStrategy in the gateway configuration uses the RetryStrategy model.
It supports the following elements:
| Element | Required | Description |
|---|---|---|
| maxRetries | Yes | Specifies the maximum number of times to try a request. This number will include the initial request, and must be > 0. |
| backoffStrategy | Yes | Defines the kind of backoff strategy to use when retrying a request. Valid values are: LINEAR and EXPONENTIAL |
| backoffInterval | No |
A time, in milliseconds, to wait between calls. If not defined, a default value of 1000ms is used.
This value is used differently depending on the `backoffStrategy` employed. LINEAR: backoffInterval defines the time between any 2 successive calls. EXPONENTIAL: backoffInterval defines the initial time interval to use. |
| retryErrorClasses | Yes |
An array of fully qualified class names on which calls should be retried.
See the HAPI FHIR Server Response Exceptions for a list of standard exception classes. Example: `[ ca.uhn.fhir.rest.server.exception.MethodNotAllowedException ]` not `[ MethodNotAllowedException ]` |
Example:
{
"maxRetries": 3,
"backoffStrategy": "LINEAR",
"backoffInterval": 100,
"retryErrorClasses": [
"ca.uhn.fhir.rest.server.exception.MethodNotAllowedException"
]
}