Handling Registration Patient Flow in OpenMRS using FHIR

What is a Patient in OpenMRS?

In OpenMRS, anyone who receives care must be registered as a Patient. A Patient serves as the foundation for healthcare records and interactions. To register someone as a Patient, they must have:

At least one Patient Identifier (e.g., a Medical Record Number).
At least one name (first and last names are required), along with optional information such as addresses and demographics.

For example, if a person has an Encounter or is enrolled in a healthcare Program, they must first be registered as a Patient in the system.

🔎 What Are Patient Identifiers?

A Patient Identifier is a unique label assigned to a patient by a healthcare facility. These identifiers are critical for ensuring accurate identification of the patient during every interaction with the system. Examples include:

Medical Record Numbers (MRNs)
National ID Numbers
Driver’s License Numbers

Administrators can customize the types of identifiers to collect using the PatientIdentifierType feature. These identifiers play a vital role in maintaining the accuracy and reliability of patient records, ensuring that no two patients are confused or duplicated.

🔧 Registering a Patient Using FHIR in OpenMRS

OpenMRS supports the registration of patients through the FHIR (Fast Healthcare Interoperability Resources) endpoint. Below is a step-by-step guide:

1️⃣ Prerequisites:

Ensure all required Patient Identifiers are added to the Patient resource.
Include the Location Session ID in the request if applicable (especially for identifiers tied to a specific location).

2️⃣ Creating a Patient with POST or PATCH Requests:

To register a Patient, you can use either a POST or PUT request to the FHIR endpoint with the Patient resource data. The system will validate the submitted data and create the record. Here's how:

Example FHIR Endpoint:

/ws/fhir2/{release}/Patient

Sample Payload for Patient Registration:

{
  "resourceType": "Patient",
  "identifier": {
    "extension": [{
      "url": "http://fhir.openmrs.org/ext/patient/identifier#location",
      "valueReference": {
        "reference": "Location/92ab9667-4686-49af-8be8-65a4b58fc49c",
        "type": "Location"
      }
    }],
    "use": "official",
    "type": {
      "text": "Test Identifier Type"
    },
    "value": "4444-6"
  },
  "name": [
    {
      "given": [
        "Adam"
      ],
      "family": "John"
    }
  ]
}

Note:

If the identifier requires a Location, add the Location extension as shown in the example above.

Additional info on Managing Patient Identifiers:

Fetch all available PatientIdentifierTypes using the REST API:
GET /patientidentifiertype?v=default
IMPORTANT: Include all mandatory identifiers (those marked as required=true in the configuration) to the patient, else patient will not be created.
If the uniqueness behavior for an identifier is set to “Location,” you can either:
1. Include the location session ID in the request as a cookie (details below on establishing a session location) .
2. If the identifier is autogenerated, fetch a new one using the IDGEN module and embed it into the patient record. If it is not autogenerated, directly add any valid value to the identifier.

For more detailed instructions, refer to the OpenMRS REST API documentation.

Info regarding establishing a session location:

The simplest thing to do would be to establish a session location. I think you can do that in two requests:

POST to /ws/rest/v1/session with an Authentication: Basic xxxx header (where xxxx is what would normally be there) and a body like { "sessionLocation": "<location uuid>" } .
The response to that will have a Set-Cookie header with JSESSIONID=xxxx store that value.
Make the request to create the patient via the FHIR API as usual but with a Cookie: JSESSIONID=xxxx header.

Documentation