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!

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

InsuranceClaim

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

InsuranceClaimStatus

The enum which contains possible claim statuses. 

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.

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.

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. 

Bill

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

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. 

PaymentType

The enum which contains possible payment types. 

InsuranceClaimItem

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

InsuranceClaimItemStatus

The enum which contains possible statuses for claimed items. 

InsurancePolicy

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

InsurancePolicyStatus

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

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

Claim Example:

{
  "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

InsuranceClaimDiagnosis → claim.diagnosis

FHIR resources:

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

The diagnosis is a part of the 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

InsurancePolicy → Coverage

FHIR resources:

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

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