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

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	claim.billablePeriod	Period for charge submission		OK	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.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

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

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

openIMIS tblClaim resource (FHIR Claim / ClaimResponse)

List of content:

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:

Did you encounter a problem or do you have a suggestion?

Please contact our Service Desk