List of content:

Description:

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

Notes / Assumptions:

The endpoint uses the UUID as a primary key
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.

FHIR resources:

Patient

RelatedPerson

Fields mapping:

Table legend:

Color	Description
	Mapped - the final choice, the most suitable choice
	Need to be found the best place for the field (not mapped currently)
	Currently not important - not mapped

Mapping:

OpenIMIS field	DB type	FHIR field	Description	Note	STPH	Mapping status
InsureeID	PK, int	identifier				This is the Database ID and should be used only internally
InsureeUUID	uniqueidentifier	identifier	The unique identifier used as PK for FHIR			mapped
FamilyID	FK (tblFamilies)	RelatedPerson		To represent the relationship between patients we can use the RelatedPerson resource.	It could be related to Group entity but not in this direction Another solution is to use the contact field and relate to another Patient (the head of the family)	Will be added after when the final approach will be established
CHFID	ncarchar(12)	Identifier				mapped
LastName	nvarchar(110)	name				mapped
OtherNames	nvarchar(110)	name				mapped
DOB	date	birthDate	Date of birth			mapped
Gender	FK (tblGender)	gender				mapped
Marital	char(1)	maritalStatus				mapped
IsHead	bit	RelatedPerson.relationship		I'm not sure if this information is important for external systems.	It depends on how we relate to the Family	Is related to `FamilyID`
passport	nvarchar(25)	identifier	Identification Number	https://hl7.org/fhir/STU3/datatypes.html#identifier	0..* relation on identifier	mapped
Phone	nvarchar(50)	telecom				mapped
PhotoID	FK (tblPhotos)	photo				That field isn't supported by the current version of openimis-be-insuree (0.0.1).
PhotoDate	date	photo.creation				Is related to `PhotoID`
CardIssued	bit			I'm not sure if this information is important for external systems.	not important	not important
ValidityFrom	datetime		Audit information. More information can be found here (on page 113): Functional%20Design%20Specification.pdf		this could be used to update the insuree information
ValidityTo	datetime
LegacyID	int
AuditUserID	int
RowID	timestamp			I'm not sure but this is probably some unique value used to distinguish database rows. Probably not useful for external systems.
Relationship	FK(tblRelations)		1 Brother/Sister 2 Father/Mother 3 Uncle/Aunt 4 Son/Daughter 5 Grand parents 6 Employee 7 Others 8 Spouse	The FHIR representation doesn't provide this information. We can consider adding the FHIR extensions if needed (if it will be useful for external systems).	not for Claiming	not for Claiming
Profession	FK(tblProfessions)		1 Housewife 2 Employee 3 Self Employee 4 Others		not for Claiming	not for Claiming
Education	FK(tblEducations)		1 Nursery 2 Primary school 3 Secondary school 4 University 5 Postgraduate studies 6 PHD 7 Other		not for Claiming	not for Claiming
Email	nvarchar(100)	telecom				mapped
isOffline	bit			I'm not sure but this is probably used to determine the source of row (offline/online app). Probably information isn't valuable for external systems.
TypeOfId	FK(tblIdentificationTypes)	identifier	Identification Type D - Driver's License N - National ID P - Passport V - Voter Card	As far as I am concerned this is the type of identifier from "passport" field. We can put these values into one FHIR identifier object.	Related to the password field.	That field isn't supported by the current version of openimis-be-insuree (0.0.1). When will be added then the approach of mapping the `passport` field needs to be changed.
HFID	FK (tblHF)	managingOrganization		It depends on mapping the HF to FHIR resource. If the FHIR Organization will be choosen then it shouldn't be an issue but when the FHIR Location will be used there can be an issue. Probably we can add in this field reference to Location instead of Organization (should be verify).	This is important for Claiming as it will be used in the calculation of costs (done manually in Nepal). Represents, for example, the family doctor and the Patient need to go to this First Service Point and to be refered to another HF.	Will be added after when the final approach will be established. Should be changed after creating the mapping for the HF resource.
CurrentAddress	nvarchar(200)	address				mapped
GeoLocation	nvarchar(250)	address	If this information is important for external systems we can put that information as other address. The patient can contain multiple addresses.			mapped
CurrentVillage	int			I'm not sure if this information is important for external systems.	This information is related to CurrentAddress.

Endpoint specification:

Example of endpoint URL:

http://127.0.0.1:8000/api_fhir/Patient/

Supported HTTP operation:

CREATE - used to create new FHIR Patient (Insuree). A 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)
READ - by default return list of all available resources. To fetch information about a specific object you should add the primary key to URL for instance:
http://127.0.0.1:8000/api_fhir/Patient/01DB0819-69F6-44F9-BF3D-0BCC5D4803E2
, where "01DB0819-69F6-44F9-BF3D-0BCC5D4803E2" is the value of the primary key. Should be used the GET HTTP method.
UPDATE - update the value of the specific object. A list of supported fields can be found in the table which shows the mapping between OpenIMIS and FHIR. 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 primary key to URL for instance:
http://127.0.0.1:8000/api_fhir/Patient/01DB0819-69F6-44F9-BF3D-0BCC5D4803E2
, where "01DB0819-69F6-44F9-BF3D-0BCC5D4803E2" is the value of the primary key.
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)
DELETE - 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 primary key to URL for instance:
http://127.0.0.1:8000/api_fhir/Patient/01DB0819-69F6-44F9-BF3D-0BCC5D4803E2/
, where "01DB0819-69F6-44F9-BF3D-0BCC5D4803E2" is the value of the primary key.
Note:
- 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" },
stu3_fhir_identifier_type_config	configuration of system and codes used to represent the specific types of identifiers	"stu3_fhir_identifier_type_config":{ "system":"https://hl7.org/fhir/valueset-identifier-type.html", "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", },
stu3_fhir_marital_status_config	configuration of system and codes used to represent the specific types of marital status	"stu3_fhir_marital_status_config":{ "system":"https://www.hl7.org/fhir/STU3/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": "address",
            "type": "physical",
            "use": "home"
        },
        {
            "text": "geolocation",
            "type": "both",
            "use": "home"
        }
    ],
    "birthDate": "2000-01-02",
    "gender": "female",
    "id": "01DB0819-69F6-44F9-BF3D-0BCC5D4803E2",
    "identifier": [
        {
            "type": {
                "coding": [
                    {
                        "code": "ACSN",
                        "system": "https://hl7.org/fhir/valueset-identifier-type.html"
                    }
                ]
            },
            "use": "usual",
            "value": "01DB0819-69F6-44F9-BF3D-0BCC5D4803E2"
        },
        {
            "type": {
                "coding": [
                    {
                        "code": "SB",
                        "system": "https://hl7.org/fhir/valueset-identifier-type.html"
                    }
                ]
            },
            "use": "usual",
            "value": "chfid"
        },
        {
            "type": {
                "coding": [
                    {
                        "code": "PPN",
                        "system": "https://hl7.org/fhir/valueset-identifier-type.html"
                    }
                ]
            },
            "use": "usual",
            "value": "passport"
        }
    ],
    "maritalStatus": {
        "coding": [
            {
                "code": "U",
                "system": "https://www.hl7.org/fhir/STU3/valueset-marital-status.html"
            }
        ]
    },
    "name": [
        {
            "family": "test patient",
            "given": [
                "test patient"
            ],
            "use": "usual"
        }
    ],
    "telecom": [
        {
            "system": "phone",
            "use": "home",
            "value": "phoneNum"
        },
        {
            "system": "email",
            "use": "home",
            "value": "email@email.com"
        }
    ]
}