Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

List of content:

Table of Contents
excludeList 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 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 (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

 the final choice, the most suitable choice


Need

to be

to be found the best place for the field (not mapped currently)


Currently not important - not mapped

Claim mappingmapping:

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

This is the Database ID and should be used only internally

ClaimUUID

UK

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;
1 - rejected
2 - entered
4 - checked
8 - processed
16 - 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
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


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.preAuthRefClaimAdminIdFK(tblClaimAdmin)Requestclaim.enterer - Reference(PractitionerRole)This information is present in the API token?ICDID1

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

Ok

ICDID2


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.OKICDID3intRequestclaim.diagnosisIf 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.OkICDID4intRequestclaim.diagnosisIf 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.OKVisitTypecharRequestclaim.typeE - emergency
R - referrals
O - other
"" - select typeOKClaimCategorychar-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:

Module configuration used by the endpoint: 

Configuration keyDescriptionDefault valuedefault_audit_user_iddefault value which will be used for 'audit_user_id' field"default_audit_user_id": 1,stu3_fhir_identifier

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:

  • 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

identifiers

operation outcome

"stu3_fhir_

identifier

issue_type_config":{
  "

system

fhir_code_for_exception":"

https://hl7.org/fhir/valueset-identifier-type.html

exception",
  "fhir_code_for_

imis_db_id_type

not_found":"

ACSN

not-found",
  "fhir_code_for_

imis_chfid_type

informational":"

SB

informational"
},


  "fhir_code_for_imis_passport_type":"PPN",

stu3_fhir_claim_config

configuration of system and codes used to represent the specific types of claim codes

"stu3_fhir_claim_config":{
  "fhir_

code

claim_

for

information_

imis_facility

guarantee_id_

type

code":"

FI

guarantee_id",
  "fhir_

code

claim_

for

information_

imis_claim

explanation_

admin_

code

_type

":"

FILL

explanation",
  "fhir_

code

claim_

for

item_

imis_claim

explanation_code

_type

":"

MR",

},

stu3_fhir_issue_type_configconfiguration of system and codes used to represent the specific types of operation outcome"stu3_fhir_issue_type_config":{

item_explanation",
  "fhir_claim_item_code":"item",
  "fhir_

code

claim_

for

service_

exception

code":"

exception

service",
  "fhir_

code

claim_

for

status_

not

rejected_

found

code":"

not-found

rejected",
  "fhir_claim_

code

status_

for

entered_

informational

code":"

informational

entered"


}

,

stu3_

  "fhir_claim_

configconfiguration of system and codes used to represent the specific types of claim codes"stu3_fhir_claim_config":{

status_checked_code":"checked",
  "fhir_claim

_information

_

guarantee

status_

id

processed_code":"

guarantee_id

processed",
  "fhir_claim_

information

status_

explanation

valuated_code":"

explanation

valuated",
  "fhir_claim_item_

explanation

status_code":"claim_item_

explanation

status",
  "fhir_claim_item_status_passed_code":"

item

passed",
  "fhir_claim_

service

item_status_rejected_code":"

service

rejected",
  "fhir_claim_

status

item_general_

rejected

adjudication_code":"

rejected

general",
  "fhir_claim_item_rejected_

status

reason_

entered

adjudication_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 keyDescriptionDefault valueiso_date_formatiso format used for FHIR date representation "iso_date_format": "%Y-%m-%d", iso_datetime_formatiso format used for FHIR datetime representation"iso_datetime_format": "%Y-%m-%dT%H:%M:%S",stu3_fhir_identifier_type_

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 identifiers"stu3_fhir_identifier_type_config":{
  "system":"https://hl7.org/fhir/valueset-identifier-type.html

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

_for_imis_db_id_type

":"service",
  "fhir_claim_status_rejected_code":"

ACSN

rejected",
  "fhir_

code

claim_

for

status_

imis_chfid

entered_

type

code":"

SB

entered",
  "fhir_

code

claim_

for

status_

imis

checked_

passport_type

code":"

PPN

checked",
  "fhir_

code

claim_

for

status_

imis_facility_id_type

processed_code":"

FI

processed",
  "fhir_

code

claim_

for_imis_claim_admin

status_valuated_code

_type

":"

FILL

valuated",
  "fhir_

code

claim_

for

item_

imis

status_

claim_

code

_type

":"

MR",

},

stu3_fhir_claim_configconfiguration of system and codes used to represent the specific types of claim codes"stu3_fhir_claim_config":{

claim_item_status",
  "fhir_claim_item_status_passed_code":"passed",
  "fhir_claim_

information

item_

guarantee

status_

id

rejected_code":"

guarantee_id

rejected",
  "fhir_claim_

information

item_general_

explanation

adjudication_code":"

explanation

general",
  "fhir_claim_item_rejected_reason_

explanation

adjudication_code":

"item_explanation",

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

claim

care_

item

rendered_code":"

item

care_rendered",
  "fhir_

claim

payment_

service

asked_code":"

service

payment_asked",
  "fhir_

claim

drug_

status_rejected

prescribed_code":"

rejected

drug_prescribed",
  "fhir_

claim

drug_

status

received_

entered_

code":"

entered

drug_received",
  "fhir_

claim_status_checked

asessment_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_configconfiguration 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:

...

asessment"
}

Example JSON representation of content:

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

Code Block
{
   "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":{
            "codecoding":[
"ICD_CD"           }    {
    ]       },       "sequencecode": 1,"ACSN",
                  "system":"https://hl7.org/fhir/valueset-identifier-type.html":
[         {      }
    "text": "icd_0"       ]
 }       ] },
   }   ],   "entereruse": {"usual",
         "referencevalue": "Practitioner/1234abcd"E9B13CFA-62D0-4B2C-B08B-477265B1587D"
  },    "facility": {},
     "reference": "Location/12345678" {
  },   "id": "code",   "identifiertype":{
[     {       "typecoding":[
{         "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
4         },
         "sequence": 1,
         "service":{
{            "text": "iCode"
         },,
         "unitPrice":{
  {          "value": 21.1
         }
      },
      {
         "category":{
{            "text": "service"
         },
         "informationLinkId":[
[            4
         ],
         "quantity":{
   {         "value":3
 3        },
         "sequence": 2,
         "service":{
 {           "text": "sCode"
         },
         "unitPrice":{
{            "value": 16.1
         }
      }
   ],
   "patient":{
{      "reference": "Patient/TEST_CHF_ID"
   },
   "total":{
 {     "value":42
42   },
   "type":{
{      "text": "E"
   }
}

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

Code Block
{
  "resourceType": "ClaimResponse",
  "communicationRequest": [
    {
      "reference": "CommunicationRequest/1F719B223-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": 1"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:

...