List of content:

Description:

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 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 (note: response for the request is the OperationOutcome on failure and ClaimResponse on successful).

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 (for Claim and ClaimResponse resource) 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.

This is the Database ID and should be used only internally

ClaimUUID

uniqueidentifier

Response

claim.Identifier

The unique identifier used as PK for FHIR

Will be added when will be available in the python claim module

mapped

InsureeID

FK(tblInsuree)

Request

claim.patient - Reference(Patient)

The subject of the Products and Services

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

Claim number

OK

mapped

DateFrom

smalldatetime

Request

claim.billablePeriod

Period for charge submission

OK

mapped

DateTo

smalldatetime

Request

Period for charge submission

mapped

ICDID

FK(tblICDCodes)

Request

claim.diagnosis

List of 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.outcome

Default value: 2;
- rejected
- entered
- checked
- processed
- valuated

Used the FHIR codeable concept (code = imis_status, text = displayed status)

Can be also a combination of claimResponse.status and claimResponse.outcome but limited in values. Extension required?

mapped

Adjuster

FK(tblUsers)

Request

claim.provider - Reference(Practitioner)

Responsible provider

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.payment.adjustmentReason

Used FHIR adjustmentReason because of the IMIS Adjustment is text.

claimResponse.payment.adjustment

mapped

Claimed

decimal

Request

claim.total

Total claim cost

OK

mapped

Approved

decimal

Response

claimResponse.totalBenefit

OK

mapped

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.payment.date

claimResponse.created is used is the request date

If different endpoint to claimResponse, claimResponse.created will be the request date.

Maybe claimResponse.payment.date

mapped

Feedback

bit

default value: 0

No need. To see if replaced by FeedbackID

FeedbackID

FK(tblFeedback)

Response

claimResponse.communicationRequest

default value: 0

claimResponse.communicationRequest

mapped

Explanation

ntext

Request

claim.information.valueString

Additional Data or supporting information

OK

mapped

FeedbackStatus

tinyint

-

default value: 1
- idle
- not selected
- selected for feedback
- delicered
- 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
- idle
- not selected
- selected for review
- reviewed
- 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

In Web App we have the rejection reason for each Item and Service in a Claim. We should provide these reasons. 

mapped

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)

Servicing Facility

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

Additional Data or supporting information

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)

Author

This information is present in the API token?

ICDID1

int

Request

claim.diagnosis

diagnosis 1 from List of 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

diagnosis 2 from List of 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

diagnosis 3 from List of 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

diagnosis 4 from List of 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:

Claim endpoint

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 (example of the outcome can be found below)
  - OperationOutcome which notice about the failure (list of possible errors);
  - ClaimResponse which notice about the success
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,
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_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_explanation_code":"item_explanation", "fhir_claim_item_code":"item", "fhir_claim_service_code":"service", "fhir_claim_status_rejected_code":"rejected", "fhir_claim_status_entered_code":"entered", "fhir_claim_status_checked_code":"checked", "fhir_claim_status_processed_code":"processed", "fhir_claim_status_valuated_code":"valuated", "fhir_claim_item_status_code":"claim_item_status", "fhir_claim_item_status_passed_code":"passed", "fhir_claim_item_status_rejected_code":"rejected", "fhir_claim_item_general_adjudication_code":"general", "fhir_claim_item_rejected_reason_adjudication_code":"rejected_reason", },

ClaimResponse endpoint:

Example of endpoint URL:

http://127.0.0.1:8000/api_fhir/ClaimResponse/

Supported HTTP operation:

CREATE - the operation not supported
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/ClaimResponse/{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 not supported
DELETE - the operation not supported

Module configuration used by the endpoint:

Configuration key	Description	Default value
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":{ "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_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_explanation_code":"item_explanation", "fhir_claim_item_code":"item", "fhir_claim_service_code":"service", "fhir_claim_status_rejected_code":"rejected", "fhir_claim_status_entered_code":"entered", "fhir_claim_status_checked_code":"checked", "fhir_claim_status_processed_code":"processed", "fhir_claim_status_valuated_code":"valuated", "fhir_claim_item_status_code":"claim_item_status", "fhir_claim_item_status_passed_code":"passed", "fhir_claim_item_status_rejected_code":"rejected", "fhir_claim_item_general_adjudication_code":"general", "fhir_claim_item_rejected_reason_adjudication_code":"rejected_reason", },
stu3_fhir_communication_request_config	configuration of system and codes used to represent the specific codes for IMIS feedback attributes	"stu3_fhir_communication_request_config":{ "fhir_care_rendered_code":"care_rendered", "fhir_payment_asked_code":"payment_asked", "fhir_drug_prescribed_code":"drug_prescribed", "fhir_drug_received_code":"drug_received", "fhir_asessment_code":"asessment" }

Example JSON representation of content:

FHIR Claim (http://127.0.0.1:8000/api_fhir/Claim/clCode1):

{
   "resourceType":"Claim",
   "billablePeriod":{
      "end":"2019-06-12T00:00:00",
      "start":"2019-06-01T00:00:00"
   },
   "created":"2019-06-12T00:00:00",
   "diagnosis":[
      {
         "diagnosisCodeableConcept":{
            "coding":[
               {
                  "code":"ICD_CD"
               }
            ]
         },
         "sequence":1,
         "type":[
            {
               "text":"icd_0"
            }
         ]
      }
   ],
   "enterer":{
      "reference":"Practitioner/1234abcd"
   },
   "facility":{
      "reference":"Location/12345678"
   },
   "id":"code",
   "identifier":[
      {
         "type":{
            "coding":[
               {
                  "code":"ACSN",
                  "system":"https://hl7.org/fhir/valueset-identifier-type.html"
               }
            ]
         },
         "use":"usual",
         "value":"E9B13CFA-62D0-4B2C-B08B-477265B1587D"
      },
      {
         "type":{
            "coding":[
               {
                  "code":"MR",
                  "system":"https://hl7.org/fhir/valueset-identifier-type.html"
               }
            ]
         },
         "use":"usual",
         "value":"code"
      }
   ],
   "information":[
      {
         "category":{
            "text":"guarantee_id"
         },
         "sequence":1,
         "valueString":"guarantee_id"
      },
      {
         "category":{
            "text":"explanation"
         },
         "sequence":2,
         "valueString":"explanation"
      },
      {
         "category":{
            "text":"item_explanation"
         },
         "sequence":3,
         "valueString":"item_explanation"
      },
      {
         "category":{
            "text":"item_explanation"
         },
         "sequence":4,
         "valueString":"service_explanation"
      }
   ],
   "item":[
      {
         "category":{
            "text":"item"
         },
         "informationLinkId":[
            3
         ],
         "quantity":{
            "value":4
         },
         "sequence":1,
         "service":{
            "text":"iCode"
         },
         "unitPrice":{
            "value":21.1
         }
      },
      {
         "category":{
            "text":"service"
         },
         "informationLinkId":[
            4
         ],
         "quantity":{
            "value":3
         },
         "sequence":2,
         "service":{
            "text":"sCode"
         },
         "unitPrice":{
            "value":16.1
         }
      }
   ],
   "patient":{
      "reference":"Patient/TEST_CHF_ID"
   },
   "total":{
      "value":42
   },
   "type":{
      "text":"E"
   }
}

FHIR ClaimResponse (http://127.0.0.1:8000/api_fhir/ClaimResponse/clCode1/):

{
  "resourceType": "ClaimResponse",
  "communicationRequest": [
    {
      "reference": "CommunicationRequest/F719B223-83A7-44A1-8F21-7B80E5B9FDD0"
    }
  ],
  "error": [
    {
      "code": {
        "coding": [
          {
            "code": "1"
          }
        ]
      }
    }
  ],
  "id": "code",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "code": "ACSN",
            "system": "https://hl7.org/fhir/valueset-identifier-type.html"
          }
        ]
      },
      "use": "usual",
      "value": "E9B13CFA-62D0-4B2C-B08B-477265B1587D"
    },
    {
      "type": {
        "coding": [
          {
            "code": "MR",
            "system": "https://hl7.org/fhir/valueset-identifier-type.html"
          }
        ]
      },
      "use": "usual",
      "value": "code"
    }
  ],
  "item": [
    {
      "adjudication": [
        {
          "amount": {
            "value": 2
          },
          "category": {
            "text": "general"
          },
          "reason": {
            "coding": [
              {
                "code": "1",
                "system": "passed"
              }
            ]
          },
          "value": 4
        },
        {
          "category": {
            "text": "rejected_reason"
          },
          "reason": {
            "coding": [
              {
                "code": "1"
              }
            ]
          }
        }
      ],
      "noteNumber": [
        1
      ],
      "sequenceLinkId": 1
    },
    {
      "adjudication": [
        {
          "amount": {
            "value": 4
          },
          "category": {
            "text": "general"
          },
          "reason": {
            "coding": [
              {
                "code": "2",
                "system": "rejected"
              }
            ]
          },
          "value": 3
        },
        {
          "category": {
            "text": "rejected_reason"
          },
          "reason": {
            "coding": [
              {
                "code": "3"
              }
            ]
          }
        }
      ],
      "noteNumber": [
        2
      ],
      "sequenceLinkId": 2
    }
  ],
  "outcome": {
    "coding": [
      {
        "code": "1"
      }
    ],
    "text": "rejected"
  },
  "payment": {
    "adjustmentReason": {
      "text": "adjustment"
    },
    "date": "2010-11-16T00:00:00"
  },
  "processNote": [
    {
      "number": 1,
      "text": "item justification"
    },
    {
      "number": 2,
      "text": "service justification"
    }
  ],
  "totalBenefit": {
    "value": 214.25
  }
  "request": {
    "reference": "Claim/clCode1"
  }
}

FHIR OperationOutcome - failure:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "code": "exception",
            "details": {
                "text": "Duplicate Claim Code"
            },
            "severity": "error"
        }
    ]
}

openIMIS tblClaim resource (FHIR Claim / ClaimResponse)

Description:

Notes / Assumptions:

FHIR resources:

Fields mapping:

Table legend:

Claim mapping:

ClaimItem mapping:

ClaimService mapping:

Endpoint specification:

Claim endpoint

Example of endpoint URL:

Supported HTTP operation:

Module configuration used by the endpoint:

ClaimResponse endpoint:

Example of endpoint URL:

Supported HTTP operation:

Module configuration used by the endpoint:

Example JSON representation of content:

FHIR Claim (http://127.0.0.1:8000/api_fhir/Claim/clCode1):

FHIR ClaimResponse (http://127.0.0.1:8000/api_fhir/ClaimResponse/clCode1/):

FHIR OperationOutcome - failure: