Botswana FHIR Implementation Guide
1.0.0 - ci-build Botswana flag

Botswana FHIR Implementation Guide, published by Jembi Health Systems. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/jembi/botswana-hie-fhir-ig/ and changes regularly. See the Directory of published versions

ExampleScenario: Retrieve Patient Record

Official URL: http://moh.bw.org/ExampleScenario/RetrievePatientRecord Version: 1.0.0
Active as of 2025-08-20 Computable Name: RetrievePatientRecord

This serves to demonstrate the retrieval of a patient's record, from the Client Registry (CR) and a FHIR datastore.

Actors

NameTypeDescription
Point of Service System

The entity that submits a request for a patient record.

Interoperability Layer System

The entity that retrieves the patient data from the CR and FHIR entities.

Client Registry System

The entity that will provide PII and demographic information for the patient.

FHIR Server System

The entity that will provide the clinical information for the patient.

Diagram

​Retrieve Patient RecordPoint of ServicePoint of ServiceInteroperability LayerInteroperability LayerClient RegistryClient RegistryFHIR ServerFHIR ServerRetrieve Patient in CRdetailsRequest for patient record(payload)Find patient(payload)response(payload)Success: Invoke FHIR mediatorendRetrieve Patient Record in FHIRdetailsGet patient record(payload)response(payload)Success: Invoke IL mediator 1endUpdate Patient RecorddetailsRemove Restricted Patient Resourceactivate ILInsert Data Supplying Patient Resourcedeactivate ILSuccess: Invoke IL mediator 2endRespond to Search RequestdetailsResponse(payload)Log the outcomeactivate PoSConsume dataend

Processes

Process: Retrieve Patient in CR

Pre-conditions:

PoS entity has submitted a request for the patient's record

Post-conditions:

CR entity has responded with the patient's personal information which includes a MPI identifier.

Process: Retrieve Patient in CR

This scenario demonstrates the process of retrieving the patient's personal information in the CR, which includes the Master Patient Index (MPI) identifier for the patient.

StepNameDescriptionInitiatorReceiverRequestResponse
1 See subprocessRetrieve Patient in CR below
StepNameDescriptionInitiatorReceiverRequestResponse
1.1 Request for patient record - search (Details: FHIR Restful Interactions code search)

Request contains one or more business identifiers.

 Point of Service Interoperability Layer FHIR Search request
1.2 Find patient - search (Details: FHIR Restful Interactions code search)

Request fo find the patient's personal information in the CR.

 Interoperability Layer Client Registry CR Search request CR Search response
1.3 Success: Invoke FHIR mediator

IL asserts that the response from CR contains the patient's personally identifiable information for the patient and a MPI and passes the data to the mediator responsible for calling the endpoint for searching patient data in FHIR.

 Interoperability Layer Interoperability Layer
Process: Retrieve Patient Record in FHIR

Pre-conditions:

CR has matched the patient using provided business identifiers and responded to the IL with the patient's personal information which includes a MPI identifier.

Post-conditions:

FHIR entity has found the patient record using using the MPI.

Process: Retrieve Patient Record in FHIR

This scenario demonstrates the process of retrieving the patient's record in FHIR, using the MPI.

StepNameDescriptionInitiatorReceiverRequestResponse
2 See subprocessRetrieve Patient Record in FHIR below
StepNameDescriptionInitiatorReceiverRequestResponse
2.1 Get patient record - search (Details: FHIR Restful Interactions code search)

Mediator uses the patient's MPI and executes a search request for the patient's record.

 Interoperability Layer FHIR Server FHIR Search request Lab Order Bundle excl. PII
2.2 Success: Invoke IL mediator 1

Pass the data to a mediator for further processing. The IL asserts that the response Bundle from FHIR contains the patient's clinical data as well as incl. the Restricted Patient Resource which contains non-personally identifiable information for the patient.

 Interoperability Layer Interoperability Layer
Process: Update Patient Record

Pre-conditions:

FHIR has responded with the patient's record.

Post-conditions:

IL has removed the Restricted Patient Resource from the bundle and replaced it with the Data Supplying Patient Resource.

Process: Update Patient Record

This scenario demonstrates the process of updating the patient's record retrieved from FHIR by replacing the Restricted Patient Resource with the Data Supplying Patient Resource so that the patient's personal information can be included in the response back to the rp.

StepNameDescriptionInitiatorReceiverRequestResponse
3 See subprocessUpdate Patient Record below
StepNameDescriptionInitiatorReceiverRequestResponse
3.1 Remove Restricted Patient Resource

Mediator removes the Restricted Patient Resource from the bundle as well as the MPI identifier.

 Interoperability Layer Interoperability Layer
3.2 Insert Data Supplying Patient Resource

Mediator inserts the Data Supplying Patient Resource into the bundle and appends to it the patient's personal information and business identifiers as supplied by the CR.

 Interoperability Layer Interoperability Layer
3.3 Success: Invoke IL mediator 2

Pass the data to the mediator responsible for calling the endpoint that must send a response back the PoS system who initiated the search request request.

 Interoperability Layer Interoperability Layer
Process: Respond to Search Request

Pre-conditions:

FHIR entity has found the patient's record and replaced the Restricted Patient Resource with the Data Supplying Patient Resource which includes the patient's personal information and business identifiers.

Post-conditions:

IL entity has responded to the PoS search request which includes the patient's record.

Process: Respond to Search Request

This scenario demonstrates the process for responding to the PoS search request for the patient's record.

StepNameDescriptionInitiatorReceiverRequestResponse
4 See subprocessRespond to Search Request below
StepNameDescriptionInitiatorReceiverRequestResponse
4.1 Response

Mediator responds to the search request with the patient's record.

 Interoperability Layer Point of Service Lab Order Bundle
4.2 Log the outcome

PoS entity logs the outcome issued by the FHIR entity.

 Point of Service Point of Service
4.3 Consume data

PoS entity consumes the data according to the user's needs.

 Point of Service Point of Service

Instances

NameTypeContentDescription
FHIR Search request Endpoint here

The search query to find a patient in FHIR using business identifiers.

Lab Order Bundle Bundle - Lab Orders here

The FHIR bundle containing the patient's record. This includes the Data Supplying Patient Resource.

Lab Order Bundle excl. PII Bundle - Process Patient in FHIR here

The FHIR bundle after being updated by the IL by replacing the Data Supplying Patient Resource with the Restricted Patient Resource.

CR Search request Endpoint here

The search query to find a patient in CR using XXX.

CR Search response Endpoint here

The response to the search request issued by the CR.