Policies module scope

This document summarizes the openIMIS features provided by the Policies module.

The module features are, among others, used within the scope of https://openimis.atlassian.net/wiki/spaces/OP/pages/1365934087 business processes.


Business definition of the policy dates

Enrolment date: Date when the insuree takes the insurance (not to be mixed up with registration date, where a person gets its insuree number)

Start date: contract start date

Effective date: coverage start date

Expiry date: date of the coverage and contract.

in the default enrollment:

Expiry date = Start date + Product Duration

Effective date is calculated based on the last installment (policy fully paid)

Start date, is either the enrollment date or based on the product cycle if any defined


Access Rights

There is no straight link between a Policy and a Location. However, a Policy is linked to a Family, which in turn is attached to a location. Besides role-based feature access control (cf. Actors and Roles here below), all policy management actions (querying, entering, ...) are limited by user’s location(s) scope: users can only access/manage policies of families listed for his registered health facilities.

Actors & Rights

Health Facilities staff


  • Search (and verifies) for policy data (in the scope of claim entering)

//note: does not have write permission!

Scheme administrator & district Staff

Clerck & Enrolment Officer:

  • Search, create, modify and delete policies


  • Search for policies (in the scope of contribution management)

//note: does not have write permission!



The other profiles are NOT allowed to search (see the details of) policies: Claim Administrator, Claim Contributor,…

Other IT System (API calls)

  • Enter policy

  • List (active) policies

Policy Management Features

Find Policy

Classical search/result panel page, with classical search criteria (enrollment date, family name,…).


  • there are filters on the location… but a policy is not linked to a specific location. So we assume the location criteria are on policies' families (… which can be down to ‘village’).

  • when double clicking on a policy from the list, the legacy app opens the family overview (!), we’ll replace this by the default behavior (open the entity itself - in this case the policy, but add a ‘open family’ button in the rows to access the family overview from the policies (i.e. as we did for the insurees)

Note about the ‘historical’ checkbox:

The search in ‘historical’ values makes the assumption that archiving is performed “in live table”. This mechanism is under review (for performance reasons). This criteria may not be available anymore (depending on the new archiving mechanism chosen).

Adding a Policy

Simple link to a ‘blank’ Policy Page (here under).

Editing a Policy

Simple link from Find Policy result table to the Policy Page (here under).

Policy Page

Policy form, screen mock:


  • The policy ‘values’ (deductibility ‘in-patient,…) influenced by the product (i.e. distinct values to fill in depending on the product 'parameters’), please check Policy Value Calculation.

  • Policy amendments are not implemented. To change anything in a policy, one has to close/reopen (or renew) a policy. More specifically:

    • when adding a member to the family, the member is (by default) not covered by the policy (need to be added in the tblInsureePolicy)

    • when removing a member from a family, he remains covered by the policy until policy expiry (or anticipated renewal).

  • Policy status are Idle, Ready, Active, Suspended and Expired. When creating a new policy, it remains in status “Idle” until contribution is recorded for it… in which case it either (based on [ActivationOption] value in [tblIMISDefaults] table, configuration) switches to:

    • “Ready” status (waiting for payment before switching to “Active”)

    • … or straight to “Active” status (without waiting for payment)

once expiry date over, the policy switches to ‘Expired’ (via the policy renewal batch).

An Idle or Active policy can be switched to ‘Suspended’ via the ‘pause’ action button, for “Expired” or “Suspended” policies, the ‘pause’ button is replaced by a ‘renew’ button:


Deleting a Policy

Simple delete (logical, by adding the validity_to date), with confirmation dialog.

Eligibility Check

The (medical) Service and Item eligibilty check, contributed in Insuree Enquiry screen are part of (calculated from) the policy module and, in legacy openIMIS, implemented via the uspServiceItemEnquiry stored procedure. This stored procedure was migrated to a python service in openimis-be-policy_py module.

See details in https://openimis.atlassian.net/wiki/spaces/OP/pages/1920630795

Note: the service is already existing (bridging to the stored procedure) and used from the current enquiry screen, but also the FHIR API.

Policy renewal batch (scheduled process)

Policy renewals … in “tools” menu + separate https://github.com/openimis/policy_renewal_service_vb

Batch launch screen mock:


Actions on the top right (in the order): Update, Send SMS, Preview… and “update” is in fact “launch”… so should we use the ‘launch’ icon (as for claim batches?)

Current process

1. policy renewal inserts

Go through policies, families, insurees, products, villages, wards, districts, officer
where valid, policy status is active or expired, expiring within reminding interval, expiring within date range

For each of those policies:

  • Check for product or officer substitutions

  • Check if the expiring policy already has another policy in place

  • Insert into tblPolicyRenewals

  • If the photo in the insuree profile is outdated, insert into tblPolicyRenewalDetails

2. update

One simple query to set policy status = expired on all expired policies

3. send sms

The Windows service provides the stored procedure with the XML template to use for sending SMS and returns the filled-in messages.

Go through tblPolicyRenewals with the substitution officer/product/etc

Composing the SMS message has a lot of:
SET @SMSHeader = '--Renewal--' + char(10) + CONVERT(nvarchar(20),@RenewalDate,103) + char(10) + @CHFIDPhoto + char(10) + @InsLastNamePhoto + ' ' + @InsOtherNamesPhoto + char(10) + @DistrictName + char(10) + @WardName + char(10) + @VillageName + char(10) + @ProductCode + '-' + @ProductName + char(10)

SET @NewFamilyMessage = REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(@FamilyMessage, '@@InsuranceID', @CHFID), '@@LastName', @InsLastName), '@@OtherNames', @InsOtherNames), '@@ProductCode', @ProductCode), '@@ProductName', @ProductName), '@@ExpiryDate', FORMAT(@ExpiryDate,'dd MMM yyyy'))

=> Generate SMS XML message based on all that.

Then, the Windows Service takes these XML files and HTTP posts them to the SMS gateway, one by one. This is in fact the only time consuming task as the others are pretty quick to execute.

⚠️ There is no feedback from the SMS submission in the database ! The Windows Service only writes the response of the gateway into the Windows Event Log.

Many SMS gateways use asynchronous callbacks to notify delivery failures. We did not find any evidence of this being handled in the existing code.

⚠️ There is no feedback from the SMS submission in the database ! The Windows Service only writes the response of the gateway into the Windows Event Log.

Many SMS gateways use asynchronous callbacks to notify delivery failures. We did not find any evidence of this being handled in the existing code.