Development details

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.

Note!

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

Field name	Type	DB Type	Description	Database constraints
BaseOpenmrsData
creator	User	FK(users)	Information about user who created the row
dateCreated	Date	DATETIME	Date of creating the row	nullable = false
changedBy	User	FK(users)	Information about user who changed the row
dateChanged	Date	DATETIME	Date of changing the row
voided	Boolean	BOOLEAN	If true that mean that the row was voided	nullable = false, defaultValueBoolean="false"
dateVoided	Date	DATETIME	Date of voiding the row
voidedBy	User	FK(users)	Information about user who voided the row
voidedReason	String	varchar(255)	The voided reason message	length = 255
BaseOpenmrsObject
uuid	String	char(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.

Field name	Type	DB Type	Description	Database constraints
InsuranceClaim (table name: iclm_claim)
id	Iinteger	PK
provider	Provider	FK(provider)	Information about the provider which is the author of the claim request
patient	Patient	FK(patient)	The subject of the Products and Services	nullable = false
location	Location	FK(location)	Servicing Facility
claimCode	String	varchar(255)	Claim number	nullable = false, length = 255
dateFrom	Date	DATETIME	Start date for requesting period	nullable = false
dateTo	Date	DATETIME	End date for requesting period	nullable = false
adjustment	String	TEXT	The contents of the disposition message (getting from response)
claimedTotal	BigDecimal	decimal(10,2)	Total claim cost
approvedTotal	BigDecimal	decimal(10,2)	Total benefit payable for the Claim
dateCreated	Date	DATETIME	Date of creating claim	nullable = false
dateProcessed	Date	DATETIME	Date of processing claim
explanation	String	TEXT	The additional explanation for claim request
rejectionReason	String	varchar(255)	Optional rejection reason message	length = 255
guaranteeId	String	varchar(255)	Optional information about guarantee	length = 255
visitType	VisitType	FK(visit_type)	Information about the visit type
status	InsuranceClaimStatus	varchar(50)	Information about current claim status	nullable = false
bill	Bill	FH(item_biill)	The related bill

InsuranceClaimStatus

The enum which contains possible claim statuses.

Value
InsuranceClaimStatus
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.

Field name	Type	DB Type	Description	Database constraints
InsuranceClaimDiagnosis (table name: iclm_claim_diagnosis)
id	Integer	PK
concept	Concept	FK(concept)	The value of concept which describe the diagnosis	nullable = false
claim	InsuranceClaim	FK(iclm_claim)	The claim which is connect with the diagnosis	nullable = 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.

Field name	Type	DB Type	Description	Database constraints
ProvidedItem (table name: iclm_provided_item)
id	Integer	PK
price	BigDecimal	decimal(10,2)	The value of the price at the moment on serving the item or service.	nullable = false, length = 255
dateOfServed	Date	DATETIME	Date of serving the item or service.
item	Concept	FK(concept)	The concept which represent specific item or service.	nullable = false
patient	Patient	FK(patient)	The patient who receives the item/service.	nullable = false
status	ProcessStatus	VARCHAR(50)	Information about process status	nullable = false
bill	Bill	FK(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.

Value
ProcessStatus
entered
processed

Bill

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

Field name	Type	DB Type	Description	Database constraints
Bill (table name: iclm_bill)
id	Integer	PK
startDate	Date	DATETIME	The start date of the requested range	nullable = false
endDate	Date	DATETIME	The end date of the requested range	nullable = false
totalAmount	BigDecimal	decimal(10,2)	The total requested amount
paymentStatus	PaymentStatus	VARCHAR(50)	The status of payment	nullable = false
paymentType	PaymentType	VARCHAR(50)	The type of payment
diagnosis	Concept	FK(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.

Value
PaymentStatus
entered
requested
completed

PaymentType

The enum which contains possible payment types.

Value
PaymentType
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.

Field name	Type	DB Type	Description	Database constraints
InsuranceClaimItem (table name: iclm_claim_item)
id	Integer	PK
quantityProvided	Integer	int	Information about the amount of requested items
quantityApproved	Integer	int	Information about the amount of approved items
priceApproved	BigDecimal	decimal(10,2)	The approved price
priceAsked	BigDecimal	-	The requested price determined based on related
explanation	String	TEXT	Optional additional information for claimed item
justification	String	TEXT	Optional additional information for claimed item (getting from response)
rejectionReason	String	varchar(255)	Optional rejection reason message	length = 255
item	ProvidedItem	FK(iclm_provided_item)	The related item	nullable = false
claim	InsuranceClaim	FK(iclm_claim)	The related claim	nullable = false
status	InsuranceClaimItemStatus	varchar(50)	The related status for claimed item

InsuranceClaimItemStatus

The enum which contains possible statuses for claimed items.

Value
InsuranceClaimItemStatus
passed
rejected

InsurancePolicy

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

Field name	Type	DB Type	Description	Database constraints
InsurancePolicy
id	Integer	PK
startDate	Date	DATETIME	The start date of policy
expiryDate	Date	DATETIME	The end date of policy
patient	Patient	FK(patient)	The related patient	nullable = false
status	InsurancePolicyStatus	varchar(50)	The status of policy	nullable = false

InsurancePolicyStatus

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

Value
InsurancePolicyStatus
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:

Claim - http://hl7.org/fhir/STU3/claim.html
ClaimResponse - http://hl7.org/fhir/STU3/claimresponse.html

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 field	FHIR field	Note
claimCode	claim.identifier	Claim number
uuid	claim.identifier	Unique uuid code
provider	claim.enterer - Reference(Practitioner)	Information about the provider which is the author of the claim request
patient	claim.patient - Reference(Patient)	The subject of the Products and Services
location	claim.facility - Reference(Location)	Servicing Facility
dateFrom	claim.billablePeriod	Start date for requesting period
dateTo	claim.billablePeriod	End date for requesting period
claimedTotal	claim.total	Total claim cost
dateCreated	claim.created	Date of creating claim
explanation	claim.information	The additional explanation for claim request
guaranteeId	claim.information	Optional information about guarantee
visitType	claim.type	Information about the visit type
diagnosis	claim.diagnosis	Diagnosis included in claim

Claim Example:

Claim Sample

{
  "resourceType": "Claim",
  "id": "claimUuid",
  "extension": [
    {
      "url": "http://fhir-es.transcendinsights.com/stu3/StructureDefinition/resource-date-created",
      "valueDateTime": "2020-01-31T10:04:49+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": "claimExternalId"
    },
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "https://hl7.org/fhir/valueset-identifier-type.html",
            "code": "MR"
          }
        ]
      },
      "value": "claimUuid"
    }
  ],
  "type": {
    "text": "Claim Visit Type"
  },
  "patient": {
    "id": "patientUuid",
    "reference": "Patient/patient_external_id",
    "identifier": {
      "id": "patientUuid"
    },
    "display": "some given name some family name(Identifier:patientUuid)"
  },
  "billablePeriod": {
    "start": "2020-01-31T10:04:49+01:00",
    "end": "2020-01-31T10:04:49+01:00"
  },
  "created": "2020-01-31T10:04:49+01:00",
  "enterer": {
    "reference": "Practitioner/externalId",
    "display": "null(Identifier:null)"
  },
  "provider": {
    "reference": "Practitioner/externalId",
    "display": "null(Identifier:null)"
  },
  "facility": {
    "id": "locationUuid",
    "reference": "Location/locationExternalId",
    "display": "Rio Bravo, []"
  },
  "information": [
    {
      "category": {
        "text": "guarantee_id"
      },
      "valueString": "guaranteeID"
    },
    {
      "category": {
        "text": "explanation"
      },
      "valueString": "explaination"
    },
    {
      "sequence": 3,
      "category": {
        "text": "item_explanation"
      },
      "valueString": "item explanation"
    }
  ],
  "diagnosis": [
    {
      "id": "diagnosisUuid",
      "diagnosisCodeableConcept": {
        "coding": [
          {
            "system": "http://www.pih.org/",
            "code": "7127"
          },
          {
            "system": "http://snomed.info/snp",
            "code": "61462000"
          },
          {
            "system": "http://ciel.org",
            "code": "160148"
          },
          {
            "system": "http://hl7.org/fhir/sid/icd-10",
            "code": "B53.8"
          },
          {
            "system": "http://snomed.info/snp",
            "code": "2931005"
          },
          {
            "system": "https://www.e-imo.com/releases/problem-it",
            "code": "1527785"
          },
          {
            "system": "http://openmrs.org",
            "code": "160148AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
            "display": "Malaria, confirmed"
          }
        ],
        "text": "Malaria, confirmed"
      },
      "type": [
        {
          "text": "http://www.pih.org/"
        },
        {
          "text": "http://snomed.info/snp"
        },
        {
          "text": "http://ciel.org"
        },
        {
          "text": "http://hl7.org/fhir/sid/icd-10"
        },
        {
          "text": "http://snomed.info/snp"
        },
        {
          "text": "https://www.e-imo.com/releases/problem-it"
        },
        {
          "text": "http://openmrs.org"
        }
      ]
    }
  ],
  "item": [
    {
      "informationLinkId": [
        3
      ],
      "category": {
        "text": "service"
      },
      "service": {
        "coding": [
          {
            "code": "serviceExternalId"
          }
        ],
        "text": "serviceExternalId"
      },
      "quantity": {
        "value": 5
      },
      "unitPrice": {
        "value": 21000
      }
    }
  ],
  "total": {
    "value": 105000
  }
}

ClaimResponse Resource

OpenMRS field	FHIR field	Note
claimCode	claimResponse.identifier	Claim number
uuid	claimResponse.identifier	Unique uuid code
adjustment	claimResponse.payment.adjustment	The contents of the adjustment message (getting from response)
approvedTotal	claimResponse.totalBenefit	Total benefit payable for the Claim
dateProcessed	claimResponse.created	Date of processing claim
rejectionReason	claimResponse.error	Optional rejection reason message
status	claimResponse.processNote	Information about current claim status
uuid	claimResponse.communicationRequest - Reference(Claim)	Request for additional information

Sample ClaimResponse

{
  "resourceType": "ClaimResponse",
  "id": "claimUuid",
  "identifier": [
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "https://hl7.org/fhir/valueset-identifier-type.html",
            "code": "ACSN"
          }
        ]
      },
      "value": "externalIdentifier"
    },
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "https://hl7.org/fhir/valueset-identifier-type.html",
            "code": "MR"
          }
        ]
      },
      "value": "claimUuid"
    }
  ],
  "created": "2020-01-31T11:16:20+01:00",
  "request": {
    "reference": "Claim/claimUuid"
  },
  "outcome": {
    "coding": [
      {
        "code": "2"
      }
    ],
    "text": "ENTERED"
  },
  "disposition": "20e5e68e-c4ce-4812-95b7-3179fd3eac57",
  "error": [
    {
      "code": {
        "coding": [
          {
            "code": "errorCode"
          }
        ],
        "text": "errorCode"
      }
    }
  ],
  "totalBenefit": {
    "value": 1234567890.21
  },
  "payment": {
    "adjustmentReason": {
      "text": "adjustmentReason"
    },
    "date": "2020-01-31"
  },
  "communicationRequest": [
    {
      "reference": "CommunicationRequest/communicationRequestId"
    }
  ]
}

InsuranceClaimDiagnosis → claim.diagnosis

FHIR resources:

Claim - http://hl7.org/fhir/STU3/claim.html

The diagnosis is a part of the FHIR Claim resource.

OpenMRS field	FHIR field	Request or response	Note
concept	claim.diagnosis	Request	The 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:

Claim.item - http://hl7.org/fhir/STU3/claim.html
ClaimResponse.item - http://hl7.org/fhir/STU3/claimresponse.html

OpenMRS field	FHIR field	Request or response	Note
quantityProvided	claim.item.quantity	Request	Information about the amount of requested items
quantityApproved	claimResponse.item.adjudication.value	Response	Information about the amount of approved items
priceApproved	claimResponse.item.adjudication.amount	Response	The approved price
priceAsked	claim.item.unitPrice	Request	The requested price. The value is determined based on value of price attribute from related ProvidedItem.
explanation	claim.information	Request	Optional additional information for claimed item
justification	claimResponse.processNote	Response	Optional additional information for claimed item (getting from response)
rejectionReason	claimResponse.item.adjudication.reason	Response	Optional rejection reason message
item	claim.item.service	Request	The related item. The related ProvidedItem provides the value of the product code which is entered into claim.item.service.
claim	see above		The related claim
status	claimResponse.item.adjudication.reason / extension	Response	The related status for claimed item

InsurancePolicy → Coverage

FHIR resources:

Coverage - https://hl7.org/fhir/STU3/coverage.html

OpenMRS field	FHIR field	Note
startDate	coverage.period	The start date of policy
expiryDate	coverage.period	The end date of policy
patient	coverage.policyHolder	The related patient
status	coverage.status	The 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:

EligibilityRequest - http://hl7.org/fhir/STU3/eligibilityrequest.html
EligibilityResponse - http://hl7.org/fhir/STU3/eligibilityresponse.html

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.

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

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).