List of content:
Description:
Currently, the OpenIMIS Claim is mapped only partially because the current version is focused on claim submission. In the current version are mapped fields required by uspUpdateClaimFromPhone database stored procedure (SP) which is used by python claim service to submitting the claim.
Only GET and POST HTTP methods are currently exposed because of the current version is focused on the claim submitting. The GET operation can be used to fetch information about all claim (or a specific one) and the POST operation can be used to submit the claim (response for the request is the OperationOutcome which notice about success or failure).
Notes / Assumptions:
- The current version of mapping will be focused on aspects of claiming.
- To fully mapped the claim probably need to be used two different FHIR resources. Claim - contains base information about the claim (request), ClaimResponse - contains information which is the outcome of processing claim (response).
- The claim code is used as the resource primary key because of the uspUpdateClaimFromPhone didn't return the value of id a new claim
FHIR resources:
Request | Claim |
Response | ClaimResponse |
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 |
Claim mapping:
OpenIMIS field | DB type | Request or response | FHIR field | Description | Note | STPH | Mapping status |
ClaimID | PK | Request | claim.Identifier | this isn't required, most important is the ClaimCode (see below) but FHIR claim can have multiple identifiers | I would include ClaimUUID into the Claim instead of ClaimID. | mapped | |
ClaimUUID | UK | Response | claim.Identifier | ||||
InsureeID | FK(tblInsuree) | Request | claim.patient - Reference(Patient) | We can represent the insuree as the FHIR patient resource but the most important is claim.patient.identifier | claim.patient.identifier | mapped | |
ClaimCode | nvarchar | Request | claim.Identifier | OK | mapped | ||
DateFrom | smalldatetime | Request | claim.billablePeriod | OK | mapped | ||
DateTo | smalldatetime | Request | mapped | ||||
ICDID | FK(tblICDCodes) | Request | claim.diagnosis | If ICD is some fixed set of coded value then we can use the CodeableCondept to describe this. The sequence field can be used to create an order of diagnosis. | OK | mapped | |
ClaimStatus | tinyint | Response | claimResponse.processNote | Default value: 2; 1 - rejected 2 - entered 4 - checked 8 - processed 16 - valuated | We can try to use the process note or create the FHIR extension (if needed) because the FHIR ClaimResponse STU3 haven't the type field. Alternatively we can use the claimResponse.status but then only 4 of 5 statuses can be mapped. | Can be also a combination of claimResponse.status and claimResponse.outcome but limited in values. Extension required? | |
Adjuster | FK(tblUsers) | Request | claim.provider - Reference(Practitioner) | I'm not sure if this field is used, all records created by me have null values in that field. | Only reference to openIMIS user. | ||
Adjustment | ntext | Response | claimResponse.disposition | claimResponse.payment.adjustment | |||
Claimed | decimal | Request | claim.total | OK | mapped | ||
Approved | decimal | Response | claimResponse.totalBenefit | OK | |||
Reinsured | decimal | Response | If needed we can create the FHIR extension. | ||||
Valuated | decimal | Response | If needed we can create the FHIR extension. | ||||
DateClaimed | date | Request | claim.created | default: getDate() | OK | mapped | |
DateProcessed | smalldatetime | Response | claimResponse.created | If different endpoint to claimResponse, claimResponse.created will be the request date. Maybe claimResponse.payment.date | |||
Feedback | bit | default value: 0 | This is probably used only by OpenIMIS and I don't know if this is valuable for external systems. External system might want to know if claim is pending for feedback. | No need. To see if replaced by FeedbackID | |||
FeedbackID | FK(tblFeedback) | default value: 0 | claimResponse.communicationRequest | ||||
Explanation | ntext | Request | claim.information.valueString | I couldn't find a better place for information about the explanation. The FHIR claim can consider multiple information elements. We can use the information category to distinguish the type of information. | OK | mapped | |
FeedbackStatus | tinyint | - | default value: 1 1 - idle 2 - not selected 4 - selected for feedback 8 - delicered 16 - by passed else select status | This field probably is used only by the OpenIMIS and isn't requirement by external systems. | Only used internally | ||
ReviewStatus | tinyint | - | default value: 1 1 - idle 2 - not selected 4 - selected for review 8 - reviewed 16 - by passed else select status | This field probably is used only by the OpenIMIS and isn't requirement by external systems. | Only used internally | ||
ApprovalStatus | tinyint | - | default value: 1; | Probably not used field | |||
RejectionReason | tinyint | Response | claimResponse.error | default value: 0 | I'm not sure if that field is used. | In Web App we have the rejection reason for each Item and Service in a Claim. We should provide these reasons. | |
ValidityFrom | datetime | - | Audit information. More information can be found here (on page 113): Web application - Functional Design Specification.pdf | This information are valuable for OpenIMIS but probably not required by external systems. | |||
ValidityTo | datetime | - | |||||
LegacyID | int | - | |||||
AuditUserID | int | - | |||||
ValidityFromReview | datetime | Response | I'm not sure if this information are valuable for external systems. If needed we can try to use the claimResponse.processNote or add the FHIR extensions. | I don't think this information is valuable for external systems. It's only used internally. | |||
ValidityToReview | datetime | Response | |||||
AuditUserIDReview | int | Response | |||||
RowID | timestamp | - | I'm not sure but this is probably some unique value used to distinguish database rows. Probably not useful for external systems. | Not used by external systems. | |||
HFID | FK(tblHF) | Request | claim.facility - Reference(Location) | Could also be Claim.organization | |||
RunID | FK(tblBatchRun) | - | This is probably useful only for the internal system not for external systems. If needed add the FHIR extension can be considered. | Not used by external systems. | |||
AuditUserIDSubmit | int | Response | I'm not sure if this information are valuable for external systems. If needed we can try to use the claimResponse.processNote or add the FHIR extensions. | ||||
AuditUserIDProcess | int | Response | |||||
SubmitStamp | datetime | Response | |||||
ProcessStamp | datetime | Response | |||||
Remunerated | decimal | Response | If needed we can create the FHIR extension. | ||||
GuaranteeId | nvarchar | Request | claim.information.valueString | I couldn't find a better place for information about the guarantee Id. The FHIR claim can consider multiple information elements. We can use the information category to distinguish the type of information. | Claim.insurance.preAuthRef | ||
ClaimAdminId | FK(tblClaimAdmin) | Request | claim.enterer - Reference(PractitionerRole) | This information is present in the API token? | |||
ICDID1 | int | Request | claim.diagnosis | If ICD is some fixed set of coded value then we can use the CodeableCondept to describe this. The sequence field can be used to create an order of diagnosis. | OK | ||
ICDID2 | int | Request | claim.diagnosis | If ICD is some fixed set of coded value then we can use the CodeableCondept to describe this. The sequence field can be used to create an order of diagnosis. | OK | ||
ICDID3 | int | Request | claim.diagnosis | If ICD is some fixed set of coded value then we can use the CodeableCondept to describe this. The sequence field can be used to create an order of diagnosis. | Ok | ||
ICDID4 | int | Request | claim.diagnosis | If ICD is some fixed set of coded value then we can use the CodeableCondept to describe this. The sequence field can be used to create an order of diagnosis. | OK | ||
VisitType | char | Request | claim.type | E - emergency R - referrals O - other "" - select type | OK | ||
ClaimCategory | char | - | I didn't find the logic related to this field. | I don't think is used externally. |
Note:
- The claim items (tblClaimItems) and services (tblClaimServices) are represented as an FHIR "claim.item".
- Additional in the "insurance" field we can contain information about policies related to insuree (using Reference(Coverage)).
ClaimItem mapping:
see subpage: openIMIS tblClaimItems resource (FHIR Claim / ClaimResponse)
ClaimService mapping:
see subpage: openIMIS tblClaimServices resource (FHIR Claim / ClaimResponse)
Endpoint specification:
Example of endpoint URL:
http://127.0.0.1:8000/api_fhir/Claim/
Supported HTTP operation:
CREATE - used to submitting the claim. The FHIR claim representation is converted to python ClaimSubmit (https://github.com/openimis/openimis-be-claim_py/blob/master/claim/services.py#L38) which is used by the python claim service. 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 claim service is used to process the request (https://github.com/openimis/openimis-be-claim_py/blob/master/claim/services.py#L146).
- The response is OperationOutcome which notice about success or failure (list of possible errors). Example of the outcome can be found below.
- 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/Claim/{claimcode}
, where "{claimcode}" is the value of the primary key (claim code in case of that resource). Should be used the GET HTTP method. - UPDATE - the operation currently not supported
- DELETE - the operation currently not supported
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, |
iso_date_format | iso format used for FHIR date representation | "iso_date_format": "%Y-%m-%d", |
iso_datetime_format | iso format used for FHIR datetime representation | "iso_datetime_format": "%Y-%m-%dT%H:%M:%S", |
stu3_fhir_identifier_type_config | configuration of system and codes used to represent the specific types of identifiers | "stu3_fhir_identifier_type_config":{ }, |
stu3_fhir_issue_type_config | configuration of system and codes used to represent the specific types of operation outcome | "stu3_fhir_issue_type_config":{ "fhir_code_for_exception":"exception", "fhir_code_for_not_found":"not-found", "fhir_code_for_informational":"informational" }, |
stu3_fhir_claim_config | configuration of system and codes used to represent the specific types of claim codes | "stu3_fhir_claim_config":{ "fhir_claim_information_guarantee_id_code":"guarantee_id", "fhir_claim_information_explanation_code": "explanation", "fhir_claim_item_code":"item", "fhir_claim_service_code":"service" } |
Example JSON representation of content:
FHIR Claim:
{ "resourceType": "Claim", "billablePeriod": { "start": "2019-02-19" }, "created": "2019-06-27", "diagnosis": [ { "diagnosisCodeableConcept": { "coding": [ { "code": "icdcod" } ] }, "sequence": 1, "type": [ { "text": "icd_0" } ] } ], "enterer": { "reference": "Practitioner/code" }, "facility": { "reference": "Location/hfcode" }, "identifier": [ { "type": { "coding": [ { "code": "ACSN", "system": "https://hl7.org/fhir/valueset-identifier-type.html" } ] }, "use": "usual", "value": "8" }, { "type": { "coding": [ { "code": "MR", "system": "https://hl7.org/fhir/valueset-identifier-type.html" } ] }, "use": "usual", "value": "clCode" } ], "item": [ { "category": { "text": "item" }, "quantity": { "value": 1 }, "sequence": 1, "service": { "text": "ICode" }, "unitPrice": { "value": 20 } }, { "category": { "text": "service" }, "quantity": { "value": 1 }, "sequence": 2, "service": { "text": "SCode" }, "unitPrice": { "value": 20 } } ], "patient": { "reference": "Patient/chfid" }, "total": { "value": 0 } }
FHIR OperationOutcome - sucess:
{ "resourceType": "OperationOutcome", "issue": [ { "code": "informational", "details": { "text": "Claim submit created" }, "severity": "information" } ] }
FHIR OperationOutcome - failure:
{ "resourceType": "OperationOutcome", "issue": [ { "code": "exception", "details": { "text": "Duplicate Claim Code" }, "severity": "error" } ] }