openIMIS

openIMIS Interoperability

Interoperability between CHT and openIMIS for managing claims and their feedback

openIMIS is an open-source software for the administration of social protection, for example health insurance, occupational accident insurance, voucher systems, cash transfers and social registries.

Use Case

openIMIS is a specialized system used by Nepal’s social security division, which manages health insurance coverage. The goal of this use case is to create an interoperable system that uses CHT’s form feedback feature to gather information on the quality of healthcare patients receive on their insurance.

Data exchange standard

Data exchange between the systems has been done using HL7 FHIR standard.

Overview

This section describes the workflow for the data exchange and integration between CHT and openIMIS.

CHT mediator subscribes to openIMIS for Resource type Claim using the FHIR standard Subscription endpoint. This means that every new Claim Resource that is created at openIMIS is also sent to CHT.
When a Claim is created at openIMIS, a ClaimResponse resource type is sent to CHT. CHT mediator extracts the Claim’s UUID, Claim’s ID, the Patient’s ID, Claim Date and sends the data to CHT’s records API(/api/v2/records) which creates the patient and creates a task for the respective CHW.
Right now for each ClaimResponse, a new patient is created as the use case is still in a proof-of-concept stage.
The task for the CHW requires the CHW to get input from the patient on the experience with the insurance, which is done through the CHT’s feedback form. When the form is submitted, CHT mediator sends the questionnaire data back to openIMIS.

Configuration

Environment variables

The CHT mediator needs to be setup with the following environment variables for a successful communication with openIMIS.

Name	Description
`OPENIMIS_API_URL`	URL of openIMIS instance
`OPENIMIS_USERNAME`	openIMIS username for authentication
`OPENIMIS_PASSWORD`	openIMIS password for authentication
`CHT_OPENIMIS_CALLBACK_ENDPOINT`	The openIMIS server sends `ClaimResponse` data to this CHT mediator endpoint after a `Claim` is created

CHT Config

Add form for processing the ClaimResponse data in CHT. The form below is an example.

{
    "meta": {
        "code": "OP",
        "translation_key": "forms.op.title",
        "icon": "icon-follow-up"
    },
    "fields": {
        "patient_id": {
            "labels": {
                "tiny": {
                    "en": "patient_id"
                },
                "short": {
                    "en": "Patient Id"
                }
            },
            "position": 0,
            "type": "string",
            "length": [
                5,
                13
            ],
            "required": true
        },
        "op_claim_id": {
            "labels": {
                "tiny": {
                    "en": "openIMIS Claim Id"
                },
                "short": {
                    "en": "openIMIS Claim Id"
                }
            },
            "position": 1,
            "type": "string",
            "required": true
        },
        "op_claim_uuid": {
            "labels": {
                "tiny": {
                    "en": "openIMIS Claim UUID"
                },
                "short": {
                    "en": "openIMIS Claim UUID"
                }
            },
            "position": 2,
            "type": "string",
            "required": true
        },
        "op_year": {
            "labels": {
                "tiny": {
                    "en": "OP_Y"
                },
                "short": {
                    "en": "OP Year"
                }
            },
            "position": 3,
            "type": "bsYear",
            "required": true
        },
        "op_month": {
            "labels": {
                "tiny": {
                    "en": "OP_M"
                },
                "short": {
                    "en": "OP Month"
                }
            },
            "position": 4,
            "type": "bsMonth",
            "required": true
        },
        "op_day": {
            "labels": {
                "tiny": {
                    "en": "OP_D"
                },
                "short": {
                    "en": "OP Day"
                }
            },
            "position": 5,
            "type": "bsDay",
            "required": true
        },
        "op_date": {
            "labels": {
                "tiny": {
                    "en": "OP_DATE"
                },
                "short": {
                    "en": "OP Date"
                }
            },
            "position": 6,
            "type": "bsAggreDate",
            "required": false
        }
    },
    "public_form": true
}

Store mediator password in CHT’s secrets, if not already.

curl -X PUT -H "Content-Type: text/plain" https://admin:password@localhost/api/v1/credentials/<interop-key> -d '<interop-password>' -k

Outbound

To have the CHT send data to mediator when the feedback form is submitted, the following outbound config was added. It filters out all the documents with the form type to be claims_feedback and extracts the answers from the form and sends it to openIMIS through the CHT mediator.

{
     "relevant_to": "doc.form === 'claims_feedback'",
     "destination": {
         "base_url": "http://openhim-core:5001",
         "path": "/mediator/claims-feedback",
         "auth": {
             "type": "basic",
             "username": "interop-client",
             "password_key": "<interop-key>"
         }
     },
     "mapping": {
         "doc._id": "doc._id",
         "care_rendered": "doc.fields.claim_feedback_group.care_rendered",
         "payment_asked": "doc.fields.claim_feedback_group.payment_asked",
         "drug_prescribed": "doc.fields.claim_feedback_group.drug_prescribed",
         "drug_received": "doc.fields.claim_feedback_group.drug_received",
         "assessment_rating": "doc.fields.claim_feedback_group.assessment_rating",
         "claimuuid": "doc.fields.inputs.op_claim_uuid",
         "insureeuuid": "doc.fields.inputs.openimis_id"
     }
}

Sample workflow

The following screenshots show a sample workflow of the interoperability between CHT and openIMIS.

Subscribe to openIMIS for Claim Resource type:

The first step is to subscribe to openIMIS for Claim Resource type using the Subscription endpoint. This is done by sending a POST request to the Subscription endpoint.

curl --location 'https://<openimis-server>/api/api_fhir_r4/Subscription/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic QWRtaW46YWRtaW4xMjM=' \
--data '{
"resourceType": "Subscription",
"status": "active",
"end": "2029-12-31T23:59:59Z",
"reason": "Claim",
"criteria": "Claim",
"channel": {
"type": "rest-hook",
"endpoint": "https://localhost:9000/mediator/claim-response",
"header": [
"{\"Content-Type\": \"application/json\", \"Accept\": \"application/json\", \"Authorization\": \"Basic aW50ZXJvcC1jbGllbnQ6aW50ZXJvcC1wYXNzd29yZA==\"}"
]
}
}'

Claim Request

When a Claim is created at openIMIS, a POST request is sent to CHT mediator’s callback endpoint with the ClaimResponse data.

Sample Request Body:

{
  "resourceType": "ClaimResponse",
  "id": "d3256498-ad16-4482-a2d2-4a6d9c78ba81",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
            "code": "UUID"
          }
        ]
      },
      "value": "d3256498-ad16-4482-a2d2-4a6d9c78ba81"
    },
    {
      "type": {
        "coding": [
          {
            "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
            "code": "Code"
          }
        ]
      },
      "value": "CHT979"
    }
  ],
  "status": "active",
  "type": {
    "coding": [
      {
        "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-visit-type",
        "code": "O",
        "display": "Other"
      }
    ]
  },
  "use": "claim",
  "patient": {
    "reference": "Patient/7b00e6ec-e0f5-4d07-a8e0-ec00a4160e73",
    "type": "Patient",
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
            "code": "UUID"
          }
        ]
      },
      "value": "7b00e6ec-e0f5-4d07-a8e0-ec00a4160e73"
    }
  },
  "created": "2025-08-25",
  "insurer": {
    "reference": "openIMIS"
  },
  "requestor": {
    "reference": "Practitioner/c60bacae-2aac-4bbf-bdad-7258ebb75f1f",
    "type": "Practitioner",
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
            "code": "UUID"
          }
        ]
      },
      "value": "c60bacae-2aac-4bbf-bdad-7258ebb75f1f"
    }
  },
  "request": {
    "reference": "ClaimV2/d3256498-ad16-4482-a2d2-4a6d9c78ba80",
    "type": "ClaimV2",
    "identifier": {
      "type": {
        "coding": [
          {
            "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
            "code": "UUID"
          }
        ]
      },
      "value": "d3256498-ad16-4482-a2d2-4a6d9c78ba80"
    }
  },
  "outcome": "queued",
  "item": [
    {
      "extension": [
        {
          "url": "https://openimis.github.io/openimis_fhir_r4_ig/StructureDefinition/claim-item-reference",
          "valueReference": {
            "reference": "ActivityDefinition/488d8bcb-5b88-438c-9077-f177f6f32626",
            "type": "ActivityDefinition",
            "identifier": {
              "type": {
                "coding": [
                  {
                    "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/openimis-identifiers",
                    "code": "UUID"
                  }
                ]
              },
              "value": "488d8bcb-5b88-438c-9077-f177f6f32626"
            },
            "display": "A1"
          }
        }
      ],
      "itemSequence": 1,
      "adjudication": [
        {
          "category": {
            "coding": [
              {
                "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-status",
                "code": "1",
                "display": "rejected"
              }
            ]
          },
          "reason": {
            "coding": [
              {
                "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-rejection-reasons",
                "code": "0",
                "display": "ACCEPTED"
              }
            ]
          },
          "amount": {
            "value": 999,
            "currency": "$"
          },
          "value": 1
        }
      ]
    }
  ],
  "total": [
    {
      "category": {
        "coding": [
          {
            "system": "https://openimis.github.io/openimis_fhir_r4_ig/CodeSystem/claim-status",
            "code": "2",
            "display": "entered"
          }
        ]
      },
      "amount": {
        "value": 0,
        "currency": "$"
      }
    }
  ]
}

A person is created using the form created in the CHT Config section above.
A task is also created for the CHW to get feedback from the patient.
Once the feedback form is submitted, the data is sent to openIMIS through the CHT mediator.

This completes the interoperability process between CHT and openIMIS for managing claims.

Did this documentation help you ?

Loss To Follow-Up OpenMRS

openIMIS Interoperability

Use Case

Data exchange standard

Overview

Configuration

Environment variables

CHT Config

Sample workflow

Build > Interoperability > Configuring

Build > Interoperability > OpenHIM Mediators

Build > Interoperability > OpenMRS

Did this documentation help you ?

openIMIS Interoperability

Use Case

Data exchange standard

Overview

Configuration

Environment variables

CHT Config

Sample workflow

Related Content

Build > Interoperability > Configuring

Build > Interoperability > OpenHIM Mediators

Build > Interoperability > OpenMRS

Did this documentation help you ?