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: Register New Patient (Using a Bundle)

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

This serves to demonstrate the creation of a patient record, when using a Client Registry (CR) and a FHIR datastore.

Actors

NameTypeDescription
Point of Service System

The entity that registers the patient.

Interoperability Layer System

The entity that receives the registration request submitted by PoS entity.

Client Registry System

The entity that stores PII and demographic information for the patient included in the lab order bundle submitted by PoS entity.

FHIR Server System

The entity that stores clinical information for the patient included in the request submitted by PoS entity.

Diagram

​Register New Patient (Using a Bundle)Point of ServicePoint of ServiceInteroperability LayerInteroperability LayerClient RegistryClient RegistryFHIR ServerFHIR ServerRegister Patient in CRdetailsLab order bundle(payload)Get patient datadeactivate ILValidate patient data for compliance(payload)response(payload)Validation success: Send patient data(payload)response(payload)Success: Invoke FHIR mediatorendRegister Patient in FHIRdetailsRemove Data Supplying Patient Resourcedeactivate ILAdd Restricted Patient Resourceactivate ILAdd the MPI identifierdeactivate ILSet the Restricted Patient Resource literal IDactivate FHIRSend data for consumption(payload)response(payload)Success: Invoke IL mediatorendRespond to Create Patient RequestdetailsResponse(payload)Log the outcomeend

Processes

Process: Register Patient in CR

Pre-conditions:

PoS entity has submitted the Lab Order Bundle which contains the Data Supplying Patient Resource.

Post-conditions:

CR entity has stored the patient's personal information and sent a response back to the IL which inlcudes a MPI identifier.

Process: Register Patient in CR

This scenario demonstrates the process of storing the patient's personal information in the CR, acquired from the Patient Resource and returning a Master Patient Index (MPI) identifier for the patient.

StepNameDescriptionInitiatorReceiverRequestResponse
1 See subprocessRegister Patient in CR below
StepNameDescriptionInitiatorReceiverRequestResponse
1.1 Lab order bundle - update (Details: FHIR Restful Interactions code update)

Patient data contains PII and clinical information

 Point of Service Interoperability Layer Lab Order Bundle
1.2 Get patient data

Mediator extracts the patient data from the Patient Resource which includes all personal identifiers.

 Interoperability Layer Interoperability Layer
1.3 Validate patient data for compliance - operation (Details: FHIR Restful Interactions code operation)

Request for FHIR's $validate operation to check that the supplied data is compliant with the Data Supplying Patient Resource Profile. FHIR's $validate operation validates the message structure and its data to ensure that the supplied data is compliant with the Data Supplying Patient Resource Profile.

 Interoperability Layer FHIR Server Data Supplying Patient Resource FHIR Validation outcome
1.4 Validation success: Send patient data - CREATE (Details: Scenario Operation Type Codes code CREATE)

Patient Resource is sent to the CR for processing. The CR associates a MPI with the patient record and stores it.

 Interoperability Layer Client Registry Data Supplying Patient Resource Assigned Master Patient Index identifier
1.5 Success: Invoke FHIR mediator

Pass the data to the mediator responsible for calling the endpoint for creating the new patient data in FHIR.

 Interoperability Layer Interoperability Layer
Process: Register Patient in FHIR

Pre-conditions:

CR has provided a MPI identifier in its response sent back to the IL.

Post-conditions:

FHIR entity has processed the lab order bundle which incl. the Restricted Patient Resource that documents the MPI for re-identification purposes.

Process: Register Patient in FHIR

This scenario demonstrates the process of storing a restricted version of the Patient Resource which excludes all PII to ensure patient privacy. This Patient Resource includes the MPI identifier issued by the CR so that the IL can reassociate the clinical information (FHIR) with the PII (CR) during GET requests.

StepNameDescriptionInitiatorReceiverRequestResponse
2 See subprocessRegister Patient in FHIR below
StepNameDescriptionInitiatorReceiverRequestResponse
2.1 Remove Data Supplying Patient Resource

Remove the Data Supplying Patient Resource from the lab order bundle and replace it with the Restricted Patient Resource

 Interoperability Layer Interoperability Layer
2.2 Add Restricted Patient Resource

Add the Restricted Patient Resource to the lab order bundle

 Interoperability Layer Interoperability Layer
2.3 Add the MPI identifier

Add the MPI assigned by the CR as a business identifier in the Restricted Patient Resource

 Interoperability Layer Interoperability Layer
2.4 Set the Restricted Patient Resource literal ID

Set the literal ID in the Restricted Patient Resource to the same value as the ID used as a patient reference in the other resources in the bundle. Note: There can only be one!.

 Interoperability Layer Interoperability Layer
2.5 Send data for consumption

Lab order bundle is sent to the FHIR server for further processing.

 Interoperability Layer FHIR Server Lab Order Bundle excl. PII Outcome response
2.6 Success: Invoke IL mediator

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

 Interoperability Layer Interoperability Layer
Process: Respond to Create Patient Request

Pre-conditions:

FHIR entity has processed the request to create the patient record and has issued an outcome response.

Post-conditions:

IL entity has received the outcome response from FHIR and forwarded the response to the PoS system.

Process: Respond to Create Patient Request

This scenario demonstrates the process for responding to the PoS sytem who issued the create patient request.

StepNameDescriptionInitiatorReceiverRequestResponse
3 See subprocessRespond to Create Patient Request below
StepNameDescriptionInitiatorReceiverRequestResponse
3.1 Response

Mediator responds to the create patient request.

 Interoperability Layer Point of Service Outcome response
3.2 Log the outcome

PoS entity logs the outcome issued by the FHIR entity.

 Point of Service Point of Service

Instances

NameTypeContentDescription
Data Supplying Patient Resource Patient - Botswana Patient here

The Patient involved in the scenario.

Lab Order Bundle Bundle - Lab Orders here

The FHIR bundle provided by the PoS entity to create the patient record.

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.

FHIR Validation outcome Endpoint here

The validation outcome as issued by the FHIR server.

Assigned Master Patient Index identifier Endpoint here

A Master Patient Index identifier assigned by the CR when new patients are created.

Outcome response Endpoint here

FHIR issues an outcome response to each CRUD request.