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

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

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 Patient Resource submitted by the PoS entity.

FHIR Server System

The entity that stores a restricted version of the Patient Resource submitted by the PoS entity.

Diagram

​Register New PatientPoint of ServicePoint of ServiceInteroperability LayerInteroperability LayerClient RegistryClient RegistryFHIR ServerFHIR ServerRegister Patient in CRdetailsPatient resource(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 all PII and business identifiersdeactivate ILUpdate Resource.metaactivate 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 a create patient request 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 Patient resource - update (Details: FHIR Restful Interactions code update)

Patient personal information

 Point of Service Interoperability Layer Data Supplying Patient Resource
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 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 all PII and business identifiers

Remove all demographic information and business identifiers from the Patient Resource as required by the Restricted Patient Resource Profile.

 Interoperability Layer Interoperability Layer
2.2 Update Resource.meta

Replace the existing meta.profile value with the structure definition URL for the Restricted Patient Resource Profile.

 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 that was included in the Patient Resource that was submitted by the PoS entity.

 Interoperability Layer Interoperability Layer
2.5 Send data for consumption

Patient Resource is sent to the FHIR server for further processing.

 Interoperability Layer FHIR Server Restricted Patient Resource 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.

Restricted Patient Resource Patient - Patient Identity Cross Reference here

The restricted Patient Resource excl. all PII.

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.