On this page:

15.2FHIR 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 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://fhir1.example.com/api",
         "resourceIdPrefix": "TGT1-",
         "forcedEncoding": "XML"
      },
      {
         "id": "target2",
         "baseUrl": "http://fhir2.example.com/api",
         "resourceIdPrefix": "TGT2-"
      }
   ],
   "searchRoutes": [
      {
         "id": "route1",
         "resourceTypes": [
            "Observation",
            "Patient",
            "Encounter"
         ],
         "targets": [
            {
               "targetId": "target1"
            },
            {
               "targetId": "target2"
            }
         ],
         "parallel": true
      }
   ],
   "readRoutes": [
      {
         "id": "readingRoute",
         "resourceTypes": [
            "Patient"
         ],
         "targets": [
            {
               "targetId": "target1"
            },
            {
               "targetId": "target2"
            }
         ],
         "parallel": true
      }
   ],
   "operationRoutes": [
      {
         "id": "operatingRoute",
         "resourceTypes": [
            "Patient"
         ],
         "targets": [
            {
               "targetId": "target1"
            }
         ],
         "parallel": true,
         "operations": [
            {
               "name": "$process-message",
               "system": true,
               "type": false,
               "instance": false
            },
            {
               "name": "$meta",
               "system": true,
               "type": true,
               "instance": true
            }
         ]
      }
   ]
}

15.2.1Defining 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.
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.
useHttpPostForAllSearches No If this is supplied a boolean value of true, FHIR searches 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.
headersToForward No Any headers specified by name will be copied from the incoming client request and added to requests to the target server.
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.

15.2.2Defining 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 so.
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.

15.2.3Defining Read Routes

 

The readRoutes array in the gateway configuration uses the GatewayReadRoute 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 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 read to each target server will be performed by the gateway in parallel. If parallel is set to false, the read 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.

15.2.4Defining Operation Routes

 

The operationRoutes array in the gateway configuration uses the GatewayOperationRoute model.

Currently only the $meta and $process-message operations are supported.

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 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.
operations Yes Supplies the list of FHIR operations this route applies to. Each operation contains four elements:
  • name (string): the name of this operation, e.g. $meta
  • system (boolean): whether this operation can be perfomed at the system level
  • type (boolean): whether this operation can be perfomed at the type level for all resource types in this route
  • instance (boolean): whether this operation can be perfomed at the instance level for all resource types in this route