Description

The openIMIS Insuree object (from the openimis-be-insuree_py module) was mapped to the FHIR R4 Patient resource.

Notes / Assumptions

The current version of mapping will be focused on aspects of claiming.
In the current version of the openimis-be-insuree_py missing services layer which can be used to perform operations (CRUD - Create, Read, Update, Delete) on entities. That's why the current version of API use directly database layer manager for managing the Insuree objects. This leads to differences between operation between legacy and new openIMIS, for instance, the update operation doesn't create the database row with a history of the object and the delete operation permanently remove the object from the database.
familyId - missing in the current version of the Insuree model (from the openimis-be-insuree_py module). That's why the current version of API doesn't cover that field. Attribute needs to be nullable type in the Database Schema.
photoId - missing in the current version of the Insuree model (from the openimis-be-insuree_py module). That's why the current version of API doesn't cover that field. Attribute need to be nullable type in the Database Schema.
typeofid - missing in the current version of the Insuree model (from the openimis-be-insuree_py module). That's why the current version of API doesn't cover that field. Attribute need to be nullable type in the Database Schema.

Mapping

FHIR R4 Resource - Patient

openIMIS table - tblInsurees, tblFamilies

FHIR R4 field	openIMIS field	Notes	Mapping status
identifier	InsureeID / CHFID / passport / TypeOfId / InsureeUUID	there is a 0..* relation on identifier	InsureeID / CHFID / passport / InsureeUUID is mapped
name	LastName / OtherNames	name field contains values that are being mapped for both LastName and OtherNames fields	mapped
birthDate	DOB		mapped
gender	Gender	Link to `gender_codes` configuration key	mapped
maritalStatus	Marital	maritalStatus.text in [Married, Single, Divorced, Widowed, Not specified]	mapped
telecom	Phone / Email	telecom field contains values that are being mapped for both Phone and Email fields	mapped
photo.url	tblInsuree.PhotoID → tblPhotos.PhotoFolder + PhotoFileName	Should include the base URL	mapped
photo. creation	tblInsuree.PhotoID → tblPhotos.PhotoDate		mapped
generalPractitioner	HFID	reference/HeathcareService	mapped
address	CurrentAddress / GeoLocation	The patient can contain multiple addresses	mapped
link.other	link to tblInsuree.FamilyId → tblFamilies.InsureeId → tblInsurees.InsureeUUID	reference Patient/UUID UUID is head of the family	mapped
link.type	tblInsuree.relationship → tblRelations.Relation OR tblRelations.RelationId	Based on module configuration. tblRelations.Relation by default.	mapped
extension.isHead	tblInsuree.IsHead	url: isHead type: valueBoolean	mapped
extension.registrationDate	tblInsuree.ValidityFrom	url: registrationDate type: valueDateTime	mapped
extension.locationCode	link to tblInsuree.FamilyId → tblFamilies.LocationId→ tblLocations.LocationUUID	url: locationCode type: valueReference	mapped
extension.educationCode.valueCoding.code extension.educationCode.valueCoding.display	tblInsuree.Education → tblEducations.EducationId tblInsuree.Education → tblEducations.Education	utl: educationCode type: valueCoding	mapped
extension.professionCode.valueCoding.code extension.professionCode.valueCoding.display	tblInsuree.Profession → tblProfessions.ProfessionId tblInsuree.Profession → tblProfessions.Profession	utl: professionCode type: valueCoding	mapped
extension.povertyStatus	tblInsuree → tblFamilies → Poverty	url: povertyStatus type: valueBoolean	mapped
extension.group	link to tblInsuree.FamilyId → tblFamilies.FamilyUUID	reference/Group/UUID	not mapped

Endpoint specification

Example of endpoint URL

http://localhost:8000/api_fhir_r4/Patient/

Supported HTTP operation

CREATE - POST HTTP method

Used to create new FHIR Patient (Insuree). List of supported fields can be found in the table which shows the mapping between openIMIS and FHIR. Should be used the POST HTTP method and the body as JSON representation (example can be found below).

note

The `head` model attribute isn't currently covered by the current API (related to the not supported familyId). By the default value is False (can be modified by the module configuration).
The `card_issued` model attribute isn't currently covered by the current API. By the default value is False (can be modified by the module configuration).
The `validity_from` attribute is set as the current value of date when the object is created
The `audit_user_id` - the user which interact with the FHIR API is the `TechnicalUser` (Backend security - Models and Concepts) which hasn't representation in tblUsers. That's why the value of the `audit_user_id` attribute is set based on the following algorithm:
1. Try to get that value from the 'auditUserId' query parameter
2. If missing get that value then use the value from the module configuration (by default 1)

The `head` model attribute isn't currently covered by the current API (related to the not supported familyId). By the default value is False (can be modified by the module configuration).
The `card_issued` model attribute isn't currently covered by the current API. By the default value is False (can be modified by the module configuration).
The `validity_from` attribute is set as the current value of date when the object is created
The `audit_user_id` - the user which interact with the FHIR API is the `TechnicalUser` (Backend security - Models and Concepts) which hasn't representation in tblUsers. That's why the value of the `audit_user_id` attribute is set based on the following algorithm:
1. Try to get that value from the 'auditUserId' query parameter
2. If missing get that value then use the value from the module configuration (by default 1)

READ - GET HTTP method

By default, returns the list of all available Patient resources. To fetch information about a specific object, you should add the UUID (e.g. 01DB0819-69F6-44F9-BF3D-0BCC5D4803E2) key to URL :

http://localhost:8000/api_fhir_r4/Patient/01DB0819-69F6-44F9-BF3D-0BCC5D4803E2

Should be used the GET HTTP method.

UPDATE - PUT HTTP method

Updates the value of the specific object. List of supported fields can be found in the mapping table. Should be used the PUT HTTP method and the body as JSON representation (example can be found below). The requested URL needs to point to a specific object to do that you should add the UUID (e.g. 01DB0819-69F6-44F9-BF3D-0BCC5D4803E2) key to URL for instance:

http://localhost:8000/api_fhir_r4/Patient/01DB0819-69F6-44F9-BF3D-0BCC5D4803E2

note

The `head` model attribute isn't updated
The `head` model attribute isn't updated
The UPDATE operation will update the specific row of the database and doesn't create the history of changes (like in the legacy openIMIS)

The `head` model attribute isn't updated
The `head` model attribute isn't updated
The UPDATE operation will update the specific row of the database and doesn't create the history of changes (like in the legacy openIMIS)

DELETE - DELETE HTTP method

The operation can be used to remove the specific object from the database. Should be used the DELETE HTTP method. The requested URL needs to point to a specific object to do that you should add the UUID (e.g. 01DB0819-69F6-44F9-BF3D-0BCC5D4803E2) key to URL for instance:

http://localhost:8000/api_fhir_r4/Patient/01DB0819-69F6-44F9-BF3D-0BCC5D4803E2

The DELETE operation will permanently remove the row from the database.

Module configuration used by the endpoint:

Configuration key	Description	Default value
default_audit_user_id	default value which will be used for 'audit_user_id' field	"default_audit_user_id": 1
gender_codes	configuration of codes used by the openIMIS to represent gender (male, female, other)	"gender_codes": { "male": "M", "female": "F", "other": "O" }
R4_fhir_identifier_type_config	configuration of system and codes used to represent the specific types of identifiers	"R4_fhir_identifier_type_config":{ "system":"https://hl7.org/fhir/valueset-identifier-type.html", "fhir_code_for_imis_db_uuid_type":"UUID", "fhir_code_for_imis_db_id_type":"ACSN", "fhir_code_for_imis_chfid_type":"SB", "fhir_code_for_imis_passport_type":"PPN", "fhir_code_for_imis_facility_id_type":"FI", "fhir_code_for_imis_claim_admin_code_type":"FILL", "fhir_code_for_imis_claim_code_type":"MR" "fhir_code_for_imis_location_code_type":"LC", "fhir_code_for_imis_diagnosis_code_type":"DC", "fhir_code_for_imis_item_code_type":"IC", "fhir_code_for_imis_service_code_type":"SC" }
R4_fhir_marital_status_config	configuration of system and codes used to represent the specific types of marital status	"R4_fhir_marital_status_config":{ "system":"http://hl7.org/fhir/valueset-marital-status.html", "fhir_code_for_married":"M", "fhir_code_for_never_married":"S", "fhir_code_for_divorced":"D", "fhir_code_for_widowed":"W", "fhir_code_for_unknown":"U" },
default_value_of_patient_head_attribute	default value for 'head' attribute used for creating new Insuree object	"default_value_of_patient_head_attribute": False,
default_value_of_patient_card_issued_attribute	default value for 'card_issued' attribute used for creating new Insuree object	"default_value_of_patient_card_issued_attribute": False,

Example JSON representation of content:

{
    "resourceType": "Patient",
    "address": [
        {
            "text": "5 Tsoka",
            "type": "physical",
            "use": "home"
        }
    ],
    "birthDate": "1987-01-07",
    "extension": [
        {
            "url": "https://openimis.atlassian.net/wiki/spaces/OP/pages/960069653/isHead",
            "valueBoolean": true
        },
        {
            "url": "https://openimis.atlassian.net/wiki/spaces/OP/pages/960331779/registrationDate",
            "valueDateTime": "2020-05-13T06:21:37.810000"
        },
        {
            "url": "https://openimis.atlassian.net/wiki/spaces/OP/pages/960495619/locationCode",
            "valueReference": {
                "reference": "Location/BEE392F1-07D8-482F-B601-6C8BBA0BF2A9"
            }
        },
        {
            "url": "https://openimis.atlassian.net/wiki/spaces/OP/pages/960331788/educationCode",
            "valueCoding": {
                "code": "3",
                "display": "Secondary school"
            }
        },
        {
            "url": "https://openimis.atlassian.net/wiki/spaces/OP/pages/960135203/professionCode",
            "valueCoding": {
                "code": "3",
                "display": "Self Employee"
            }
        },
        {
            "url": "https://openimis.atlassian.net/wiki/spaces/OP/pages/1556643849/povertyStatus",
            "valueBoolean": true
        }
    ],
    "gender": "M",
    "id": "01EEDC6C-436C-465F-86C2-6FF68644D751",
    "identifier": [
        {
            "type": {
                "coding": [
                    {
                        "code": "UUID",
                        "system": "https://hl7.org/fhir/valueset-identifier-type.html"
                    }
                ]
            },
            "use": "usual",
            "value": "01EEDC6C-436C-465F-86C2-6FF68644D751"
        },
        {
            "type": {
                "coding": [
                    {
                        "code": "SB",
                        "system": "https://hl7.org/fhir/valueset-identifier-type.html"
                    }
                ]
            },
            "use": "usual",
            "value": "6561"
        },
        {
            "type": {
                "coding": [
                    {
                        "code": "PPN",
                        "system": "https://hl7.org/fhir/valueset-identifier-type.html"
                    }
                ]
            },
            "use": "usual",
            "value": "6561"
        }
    ],
    "maritalStatus": {
        "coding": [
            {
                "code": "M",
                "system": "http://hl7.org/fhir/valueset-marital-status.html"
            }
        ],
        "text": "Married"
    },
    "name": [
        {
            "family": "Banda",
            "given": [
                "James"
            ],
            "use": "usual"
        }
    ],
    "photo": [
        {
            "creation": "1900-01-01",
            "url": "Images\\Updated\\"
        }
    ],
    "telecom": [
        {
            "system": "phone",
            "use": "home",
            "value": ""
        },
        {
            "system": "email",
            "use": "home",
            "value": "                                                                                                    "
        }
    ]
}