GIF Tutorial (Part 2): The Policy Module

Learn about the components making up the Policy module and how each of them relates to the steps involved in the life cycle of an insurance product.

Previous parts:

Part 1 — How to build a simple insurance product:https://blog.etherisc.com/gif-tutorial-part-1-dc595057c1b9

See also:

GIF user manual: https://gif-manual.readthedocs.io/en/latest/

Github repo: https://github.com/etherisc/GIF

Breaking down the Policy module

In this article, we continue getting acquainted with the Generic Insurance Framework (GIF). In the previous article, we have built a simple insurance product. Our next stop is the Policy module, which belongs to the very core of the platform. But, first, let’s think about a generic process, which can describe the life cycle of any insurance product. The main idea is the possibility of building an insurance product based on such a generic business process. In our view, this process can be divided into five major stages as in the diagram below.

Five stages of a generic business process

The first stage starts with the customer’s application. An insurance product collects application data required to make a decision: should this application be underwritten or declined. Application underwriting triggers issuance of a new policy, which means that a customer pays a calculated premium for this policy. An insurer takes the liability to maintain this policy, accept and resolve customer claims, as well as make payouts for valid claims. The last stage is finalization, which means the policy has expired, and the insurer has fulfilled its obligation to the customer.

To maintain this process, our basic objects can be defined:

1. An application. A form where a prospective insured submits data requested by an insurer. Based on this information — together with the data from other sources — an insurer decides whether to accept the risk, modify the coverage offered, or decline the risk.
2. A policy. An agreement between an insurer and an insured (known as a policyholder) that determines the claims an insurer is legally required to pay.
3. A claim. A request by a policyholder to an insurance company to cover or compensate a loss or a policy event.
4. A payout. A sum of money paid to a policyholder when a claim is accepted.

The Policy module works as a storage for the data types mentioned above. It also stores a Metadata object, which manages shared data across basic objects and optimizes the usage of smart contracts.

The Policy module features methods to create and modify these objects, but it does not contain any business rules related to valid transitions between states of basic objects. For this purpose, the GIF supports multiple PolicyFlowcontracts. A PolicyFlow contract defines policy life cycle business rules and transitions between states of basic objects. During registration, each product defines what kind of a PolicyFlow contract it will use. The employment of pluggable policy life cycles brings flexibility to the GIF if some new business login is required.

Below, we share how the Policy module operates each of the four objects mentioned above.

An application

An application contains basic information required by insurers to decide whether to accept the risk. Each product can contain an individual set of fields (e.g., if we build a flight delay insurance app, we will need such fields as a carrier, a flight number, a departure date, etc.) Application data is divided into two parts: general and custom fields.

General fields include:

• a premium amount
• a currency code
• payout options
• an application state

General fields are stored in the Policy module storage and should be provided as parameters to the _newApplicationfunction.

The _newApplicationfunction also requires the bpExternalKeyparameter, which is a business process external key. Each individual policy should start with creating a business process key. Each product builder has access to the gifcli tool, which can create such a key.

Custom fields should be defined, stored in product contracts, and mapped with the corresponding application through the applicationId tooling provided by the GIF.

An application has four possible states:

• Applied. An initial state that indicates a customer applied for a policy.
• Revoked. Before an application is considered by an underwriter, a customer can revoke the application.
• Underwritten. An application is signed by an underwriter.
• Declined. An application is declined by an underwriter.

A policy

A policy represents an agreement between a customer and an insurer. Once an application is underwritten by an insurer, a new policy object is created. The policy has two states:

• Active. An initial state meaning an agreement is active.
• Expired. An expiry can happen after a certain period of time or once the claim is resolved. This completely depends on the product’s business logic. Each product has its own expiration policy.

A claim

A claim represents a request from a policyholder for compensation. The claim has three states:

• Applied. An initial state that means a policyholder created a new claim.
• Confirmed. This means that an insurer should pay a compensation to a policyholder.
• Declined. This means an insured is not eligible for compensation due to some reason.

A payout

Once a claim is created the reasonable question is who can resolve it (confirm or decline). There are several options:

• Each product could define a separate role (e.g., claimResolver) and assign it to a particular account or accounts. This role becomes responsible for resolving claims.
• The GIF sandbox has a special microservice for signing transactions on behalf of specified accounts. To do this, the _onlySandboxmodifier should be added to the method. Then, a transaction can be created using the gifcli.
• A special oracle can be queried to send transactions.

If a claim is resolved, the GIF will create a new payout entity. A payout has three important fields: expectedAmount,actualAmount, and state. There are two possible states:

• Expected. A certain amount should be paid out to a customer.
• PaidOut. The amount is fully paid out to a customer.

Once a payout is created, theexpectedAmount is the amount required to be paid out. The GIF supports partial payouts, so each payout transaction will increase actualAmountand decrease expectedPayout. When expectedPayoutreaches a zero value, a payout changes its status to PaidOut.

Relationships between basic objects and transitions of statuses

To learn more about under-the-hood mechanisms of the GIF, check out the GIF user manual.