Wiki Spaces

Documentation
Projects
Resources

Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack

Projects

Page tree
Skip to end of metadata
Go to start of metadata

How to use project Jira?

Link to project Jira space:

https://issues.openmrs.org/projects/ICLM/issues/?filter=allopenissues

How does the development workflow in the Jira Project Board looks like?

Supported version of OpenMRS Platform

In the beginning the insurance claims module will be compatible with the 2.1.3 version of OpenMRS Platform.

Module entities

The entities which can be found in the insurance claim module are shown below (note: diagram show class fields and relations between class but class methods were skipped).

Note!

Note: work in progress. This isn't the final version of the diagram.


InsuranceClaimsModuleEntities

Note!

All presented classes below extend the BaseOpenmrsData which contain the following fields.

BaseOpenmrsData 

Field nameTypeDB TypeDescriptionDatabase constraints
creatorUserFK(users)Information about user who created the row
dateCreatedDateDATETIMEDate of creating the rownullable = false
changedByUserFK(users)Information about user who changed the row
dateChangedDateDATETIMEDate of changing the row
voidedBooleanBOOLEANIf true that mean that the row was voidednullable = false, defaultValueBoolean="false"
dateVoidedDateDATETIMEDate of voiding the row
voidedByUserFK(users)Information about user who voided the row
voidedReasonStringvarchar(255)The voided reason messagelength = 255
BaseOpenmrsObject
uuidStringchar(38)The row universally unique identifier (UUID)nullable="false", unique="true"

InsuranceClaim

This object should be used to contain information about the requested insurance claim and additionally contains information about the adjudication of the request.

InsuranceClaim (table name:  iclm_claim)

Field nameTypeDB TypeDescriptionDatabase constraints
idIintegerPK

providerProviderFK(provider)Information about the provider which is the author of the claim request
patientPatientFK(patient)The subject of the Products and Servicesnullable = false
locationLocationFK(location)Servicing Facility
claimCodeStringvarchar(255)Claim numbernullable = false, length = 255
dateFromDateDATETIMEStart date for requesting periodnullable = false
dateToDateDATETIMEEnd date for requesting periodnullable = false
adjustmentStringTEXTThe contents of the disposition message (getting from response)
claimedTotalBigDecimaldecimal(10,2)Total claim cost
approvedTotalBigDecimaldecimal(10,2)Total benefit payable for the Claim
dateCreatedDateDATETIMEDate of creating claimnullable = false
dateProcessedDateDATETIMEDate of processing claim
explanationStringTEXTThe additional explanation for claim request
rejectionReasonStringvarchar(255)Optional rejection reason messagelength = 255
guaranteeIdStringvarchar(255)Optional information about guaranteelength = 255
visitTypeVisitTypeFK(visit_type)Information about the visit type
statusInsuranceClaimStatusvarchar(50)Information about current claim statusnullable = false
billBillFH(item_biill)The related bill

InsuranceClaimStatus

The enum which contains possible claim statuses. 

InsuranceClaimStatus

Value
rejected
entered
checked
processed
valuated

InsuranceClaimDiagnosis

This object should be used to contain information about the claimed diagnosis (relation between claim and claim diagnosis). One claim can have relationships with many diagnoses.

InsuranceClaimDiagnosis (table name: iclm_claim_diagnosis)

Field nameTypeDB TypeDescriptionDatabase constraints
idIntegerPK

conceptConceptFK(concept)The value of concept which describe the diagnosisnullable = false
claimInsuranceClaimFK(iclm_claim)The claim which is connect with the diagnosisnullable = false

ProvidedItem

This object contains information about the goods and services provided by the health facility to the specific patients. Each row represents a single operation. Because we want to combine multiple operation into a single bill that's why each item has a status which indicates if item was performed.

ProvidedItem (table name: iclm_provided_item)

Field nameTypeDB TypeDescriptionDatabase constraints
idIntegerPK

priceBigDecimaldecimal(10,2)The value of the price at the moment on serving the item or service.nullable = false, length = 255
dateOfServedDateDATETIMEDate of serving the item or service. 
itemConceptFK(concept)The concept which represent specific item or service.nullable = false
patientPatientFK(patient)The patient who receives the item/service.nullable = false
statusProcessStatusVARCHAR(50)Information about process statusnullable = false
billBillFK(bill)Information about the related bill. The column should be filled after creating related bill.

Note:

The relatedItem is represented by the OpenMRS resource named Concept. Each Concept which is to be used as an item/service need to contain the following information:

  • name - stored in the concept table
  • description - stored in the concept table
  • careService - The value used to determine if the item is the good or service. Stored as a concept attribute.
  • price - The value of price. Stored as a concept attribute.
  • insuranceSystemCode - stored as the concept relationship

ProcessStatus

The enum which contains possible process statuses. 

ProcessStatus

Value
entered
processed

Bill

The object provides combine information about the set of provided items. 

Bill (table name: iclm_bill)

Field nameTypeDB TypeDescriptionDatabase constraints
idIntegerPK

startDateDateDATETIMEThe start date of the requested rangenullable = false
endDateDateDATETIMEThe end date of the requested rangenullable = false
totalAmountBigDecimaldecimal(10,2)The total requested amount
paymentStatusPaymentStatusVARCHAR(50)The status of paymentnullable = false
paymentTypePaymentTypeVARCHAR(50)The type of payment
diagnosisConceptFK(concept)The concept which represent related diagnosis.

Note:

The relatedDiagnosis is just represented by the OpenMRS and doesn't need to provide any additional information.

PaymentStatus

The enum which contains possible payment statuses. 

PaymentStatus

Value
entered
requested
completed

PaymentType

The enum which contains possible payment types. 

PaymentType

Value
cash
insuranceClaim

InsuranceClaimItem

This object should be used to represent the relation between the claim and the item. Contains additional attributes related to this relationship.

InsuranceClaimItem (table name: iclm_claim_item)

Field nameTypeDB TypeDescriptionDatabase constraints
idIntegerPK

quantityProvidedIntegerintInformation about the amount of requested items
quantityApprovedIntegerintInformation about the amount of approved items
priceApprovedBigDecimaldecimal(10,2)The approved price
priceAskedBigDecimal-The requested price determined based on related 
explanationStringTEXTOptional additional information for claimed item
justificationStringTEXTOptional additional information for claimed item  (getting from response)
rejectionReasonStringvarchar(255)Optional rejection reason messagelength = 255
itemProvidedItemFK(iclm_provided_item)The related itemnullable = false
claimInsuranceClaimFK(iclm_claim)The related claimnullable = false
statusInsuranceClaimItemStatusvarchar(50)The related status for claimed item

InsuranceClaimItemStatus

The enum which contains possible statuses for claimed items. 

InsuranceClaimItemStatus
Value
passed
rejected

InsurancePolicy

This object should be used to contain information about patient insurance policy.

InsurancePolicy
Field nameTypeDB TypeDescriptionDatabase constraints
idIntegerPK

startDateDateDATETIMEThe start date of policy
expiryDateDateDATETIMEThe end date of policy
patientPatientFK(patient)The related patientnullable = false
statusInsurancePolicyStatusvarchar(50)The status of policynullable = false

InsurancePolicyStatus

The enum which contains possible values of the insurance policy status.

InsurancePolicyStatus
Value
idle
active
suspended
expired

FHIR mapping

Below is placed FHIR mapping proposals for the OpenMRS objects which will be used to communicate with external insurance systems.

InsuranceClaim → Claim/ClaimResponse

FHIR resources:

The claim is the resources which have to be presented using two different FHIR resources. Claim - contains base information about the claim (request), ClaimResponse - contains information which is the outcome of processing claim (response). In the table below you can find information where fields should be included (note! the response can contain the reference of request).

Claim Resource

OpenMRS fieldFHIR fieldNote
claimCodeclaim.identifierClaim number

uuid


Unique uuid code
providerclaim.enterer - Reference(Practitioner)Information about the provider which is the author of the claim request
patientclaim.patient - Reference(Patient)The subject of the Products and Services
locationclaim.facility - Reference(Location)Servicing Facility
dateFromclaim.billablePeriodStart date for requesting period
dateToEnd date for requesting period
claimedTotalclaim.totalTotal claim cost
dateCreatedclaim.createdDate of creating claim
explanationclaim.informationThe additional explanation for claim request
guaranteeIdOptional information about guarantee
visitTypeclaim.typeInformation about the visit type
diagnosisclaim.diagnosisDiagnosis included in claim

Claim Example:

Claim Sample
{
  "resourceType": "Claim",
  "id": "claim_uuid",
  "extension": [
    {
      "url": "http://fhir-es.transcendinsights.com/stu3/StructureDefinition/resource-date-created",
      "valueDateTime": "2019-11-05T16:43:11+01:00"
    },
    {
      "url": "https://purl.org/elab/fhir/StructureDefinition/Creator-crew-version1",
      "valueString": "admin"
    }
  ],
  "identifier": [
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "https://hl7.org/fhir/valueset-identifier-type.html",
            "code": "ACSN"
          }
        ]
      },
      "value": "claim_uuid"
    },
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "https://hl7.org/fhir/valueset-identifier-type.html",
            "code": "MR"
          }
        ]
      },
      "value": "claimCode"
    }
  ],
  "type": {
    "text": "Visit_type"
  },
  "patient": {
    "id": "patient_uuid",
    "reference": "Patient/patient_uuid",
    "identifier": {
      "id": "patient_uuid"
    },
    "display": "some given name some family name(Identifier:patient_uuid)"
  },
  "billablePeriod": {
    "start": "2019-11-05T16:43:11+01:00",
    "end": "2019-11-05T16:43:11+01:00"
  },
  "created": "2019-11-05T16:43:11+01:00",
  "enterer": {
    "reference": "Practitioner/provider_uuid",
    "display": "Super User(Identifier:Test)"
  },
  "facility": {
    "id": "location_uuid",
    "reference": "Location/location_uuid",
    "display": "location_name, [location_tag]"
  },
  "information": [
    {
      "category": {
        "text": "guarantee_id"
      },
      "valueString": "guaranteeID"
    },
    {
      "category": {
        "text": "explanation"
      },
      "valueString": "explaination"
    }
  ],
  "diagnosis": [
    {
      "id": "diagnosis_uuid",
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://www.pih.org/",
            "code": "pih_code"
          },
          {
            "system": "http://snomed.info/snp",
            "code": "snowmed_code"
          },
          {
            "system": "http://ciel.org",
            "code": "ciel_code"
          },
          {
            "system": "http://hl7.org/fhir/sid/icd-10",
            "code": "icd-19_code"
          },
          {
            "system": "http://openmrs.org",
            "code": "diagnosis_uuid",
            "display": "Malaria, confirmed"
          }
        ],
        "text": "Diagnosis name"
      }
    }
  ],
  "total": {
    "value": 1234567890.21
  }
}


ClaimResponse Resource

OpenMRS fieldFHIR fieldNote
claimCodeclaimResponse.identifierClaim number

uuid


Unique uuid code
adjustmentclaimResponse.payment.adjustmentThe contents of the adjustment message (getting from response)
approvedTotalclaimResponse.totalBenefitTotal benefit payable for the Claim
dateProcessedclaimResponse.createdDate of processing claim
rejectionReasonclaimResponse.errorOptional rejection reason message
statusclaimResponse.processNoteInformation about current claim status
uuidclaimResponse.communicationRequest - Reference(Claim)Request for additional information
Sample ClaimResponse
{
  "resourceType": "ClaimResponse",
  "id": "claim_uuid",
  "identifier": [
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "https://hl7.org/fhir/valueset-identifier-type.html",
            "code": "ACSN"
          }
        ]
      },
      "value": "claim_uuid"
    },
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "https://hl7.org/fhir/valueset-identifier-type.html",
            "code": "MR"
          }
        ]
      },
      "value": "claim_code"
    }
  ],
  "created": "2019-11-05T17:00:29+01:00",
  "request": {
    "reference": "Claim/8a589dc9-435f-4453-957a-31106cf0d932"
  },
  "outcome": {
    "coding": [
      {
        "code": "2"
      }
    ],
    "text": "ENTERED"
  },
  "error": [
    {
      "code": {
        "coding": [
          {
            "code": "error_code"
          }
        ],
        "text": "error_code"
      }
    }
  ],
  "totalBenefit": {
    "value": 1234567890.21
  },
  "payment": {
    "adjustmentReason": {
      "text": "adjustment reason"
    },
    "date": "2019-11-05"
  },
  "communicationRequest": [
    {
      "reference": "CommunicationRequest/claim_uuid"
    }
  ]
}


InsuranceClaimDiagnosis → claim.diagnosis

FHIR resources:

The diagnosis is a part of the FHIR Claim resource.

OpenMRS fieldFHIR fieldRequest or responseNote
conceptclaim.diagnosisRequestThe value of concept which describe the diagnosis
claim

The claim which is connect with the diagnosis; not mapped because this is part of FHIR claim resource

InsuranceClaimItem → Claim.item / ClaimResponse.item

FHIR resources:

OpenMRS fieldFHIR fieldRequest or responseNote
quantityProvidedclaim.item.quantityRequestInformation about the amount of requested items
quantityApprovedclaimResponse.item.adjudication.valueResponseInformation about the amount of approved items
priceApprovedclaimResponse.item.adjudication.amountResponseThe approved price
priceAskedclaim.item.unitPriceRequestThe requested price. The value is determined based on value of price attribute from related ProvidedItem.
explanationclaim.informationRequestOptional additional information for claimed item
justificationclaimResponse.processNoteResponseOptional additional information for claimed item  (getting from response)
rejectionReasonclaimResponse.item.adjudication.reasonResponseOptional rejection reason message
itemclaim.item.serviceRequestThe related item. The related ProvidedItem provides the value of the product code which is entered into claim.item.service.
claimsee above
The related claim
statusclaimResponse.item.adjudication.reason / extensionResponseThe related status for claimed item

InsurancePolicy → Coverage

FHIR resources:

OpenMRS fieldFHIR fieldNote
startDatecoverage.periodThe start date of policy
expiryDateThe end date of policy
patientcoverage.policyHolderThe related patient
statuscoverage.statusThe status of policy

Architecture Overview

The diagram below illustrates a general overview of the insurance claim module architecture. Note that components might be simplified and in the real implementation split into multiple pieces.

Architecture for checking patient insurance enrollment on registration status

Note that to verify status of insurance enrollment should be considered following FHIR resources:

InsuranceClaimsMod Arch - checking patient insurance enrollment

Architecture for persisting information about performer/provided items

Note: the diagram below illustrates the way how the module should store information about the performed item/services.

InsuranceClaim - generate the bill items

Architecture for generating the bill

Note: the diagram below illustrates the way how the module should generate the bill. Generated bill can be used to submit the claim

InsuranceClaim - generate the bill


Architecture for submitting claims

Note that the diagram below shows only the basic flow (submitting claim). Additionally flows should be considered for handling the situation when the external system processed the request with errors or need some additional information. Note that the external system probably wouldn't reply immediately (automatically).

InsuranceClaims Arch - submitting claims





  • No labels