Working with the FHIR Server

The topics in the right-hand column describe how to work with FHIR data using Opala's API.

Storing Source Information

The Resource.meta.source field exists in every resource, and is used to store basic information about the provenance of a resource (i.e., what system was used to create it). When the dao_config.store_source_information setting on the FHIR Storage module is enabled, this property will be stored for every resource that is saved.

According to the FHIR specification, the field should store a URI indicating the identity of the source system used to create the data.

In HAPI FHIR and Smile CDR, this concept is extended so that this field may optionally store two pieces of information:

• The Source URI: This is a URI indicating the source system, as described in the FHIR specification.
• The Request ID: This is the identity of the request transaction used to create the resource version.

The Source URI is drawn from the request resource body, in the field Resource.meta.source. The Request ID is drawn from the X-Request-ID header and is generated by the system if not supplied by the client.

Capturing

If needed, request headers can be used to capture the source information when performing write operations.

When processing incoming resources (i.e., for create, update, etc.) some basic details about the resource provenance are captured in Resource.meta.source. Opala stores both the Source System URI (typically the identity of the system that was used to create the data) as well as the Transaction ID (typically a unique identifier for the specific HTTP request involved).

When Opala stores FHIR data (using a FHIR Storage module) these two fields are automatically combined using a hash symbol. For example, given a Source System URI of http://example.com/some-app and a Transaction ID of 000001 the system might capture the following value:

{
    "resourceType": "Patient",
    "meta": {
      "source": "http://example.com/some-app#000001"
    }
}

It is possible to supply both of these properties using HTTP Request Headers in environments where it is easier to capture/inject this data using network infrastructure. The following two headers may be used:

• X-Request-ID. Supplies the Transaction ID.
• X-Request-System. Supplies the Source System ID. The process_request_header.request_source_enabled property must be enabled on the module in order to use this header.

Searching

The _source search parameter can be used to search for resources that have a given source value. It can be used as follows:

Style	Usage	Example
Source URI	Search by source URI: In this search, the parameter value is simply the Source URI itself.	Patient?_source=http://somesystem.example.org/foo
Request ID	Search by Request ID: In this search, the parameter value is a percent-encoded hash sign (# / %23) followed by the Request ID.	Patient?_source=%23AD83y3ydgSSF
Source URI and Request ID	Search by Source URI and Request ID: In this search, the parameter value is the Source URI followed by a percent-encoded hash sign (# / %23) followed by the Request ID.	Patient?_source=http://somesystem.example.org/foo%238dUEj34hwkDNd

Example: Storing Source Information

The following HTTP request shows a request that includes both a source URI and a Request ID.

POST /Patient
X-Request-ID: 8dUEj34hwkDNd
Content-Type: application/fhir+json
                                
{
   "resourceType": "Patient",
   "meta": {
      "source": "http://somesystem.example.org/foo"
   },
   "name": {
      "family": "Simpson"
    }
}

• If the X-Request-ID header is not present, a randomly generated request ID will be created and stored automatically.
• If the Meta.source value is not present, no Source URI will be stored.