Overview

By defining claims blocks for your product, you configure the product specific information that needs to be captured and saved to a claim so that it can be assessed. Claims blocks simultaneously represent 1) the claim information input parameters, and 2) the user interface components for capturing those parameters on the Root management dashboard.

Claims blocks store information in block states. Block states are stored on the claim object and can be retrieved and updated via corresponding API endpoints.

Block states persist on the claim object from when the claim is opened to when it is finalised. By default, this information remains viewable and updatable throughout the assessment process. However, specific blocks can disabled or hidden depending on the claim status and approval status.

Claims blocks are also used to generate payout and fulfillment requests, which facilitate the disbursement of compensation of beneficiaries. Read more in the disbursement blocks guide.

📘

Claims blocks allow for API-only integration

Claims blocks serve two purposes at the same time: defining the information that needs to be captured to a claim, and defining the user interface components for capturing that information via the Root management dashboard.

This doesn't mean you have to use the Root management dashboard as your frontend for capturing claim information. You could build your own frontend and integrate with claims blocks via the Root API.

Blocks schema

Claims blocks are defined in a JSON schema as an array of objects, each containing a block and its associated display conditions ("show_if", "hide_if", "disabled_if" and "required_if").

Display conditions are used to hide or disable certain blocks based on other block states, or based on existing claim, policy or other available data. Setting a block's "required_if" parameter to true makes the corresponding input parameter mandatory.

Each block must have its own unique key. The key is used to identify a specific block, both when referencing one block from another block within the schema, and when retrieving and updating block states via the API.

You also need to specify each block's "type", which determines the type of data that can be stored in the block's state. Different configuration options are supported for each block type. For example, the "input.value" block type supports validation options like minimum and maximum values.

On the Root management dashboard, each block will render as a form component in the claim description form. The type of form element that is rendered, like a text input field or a dropdown, will correspond to the block type. Within the schema, blocks can reference each other's state, allowing for some blocks to be disabled, hidden or required based on the values saved in other block states.

[
  {
    "show_if": "",
    "hide_if": "",
    "disabled_if": "",
    "required_if": "",
    "block": {
      "type": "<block type>",
      "key": "<block key>",
      ...
    }
  },
  ...
]

Block states

Claims blocks store information in block states, in the "block_states" object on the claim object. Within the "block_states" object, each block is identified by its unique key. The parameters stored in each block's state include the block's type and current value.

The following is an example snippet from a blocks schema.

[
  {
    "show_if": true,
    "hide_if": false,
    "disabled_if": false,
    "required_if": false,
    "block": {
        "type": "input.text",
        "key": "first_name_block",
        "title": "First name"
    }
  },
  {
    "show_if": true,
    "hide_if": false,
    "disabled_if": false,
    "required_if": false,
    "block": {
        "type": "input.text",
        "key": "last_name_block",
        "title": "Last Name"
    }
  }
]

Provided that the input values have been captured via the API or the Root management dashboard, the block states would be saved on the claim like this:

{
  "claim": {
    "block_states": {
      "first_name_block": {
        "type":"input.text",
        "value":"Erlich"
      },
     "last_name_block": {
       "type":"input.text",
       "value":"Bachman"
     }
    },
    ...
  }
}

📘

Block states are updated in real time

When a dashboard user changes the value of an input component on the claim description form, this value saves to the block states whenever the input component loses focus. There is no "submit" button.

Working with claims blocks via the API

Block states can be retrieved and updated via the API. Block states can be retrieved either by retrieving the entire claim together with all its blocks from the retrieve a claim endpoint, or by retrieving the the state of an individual block from the retrieve a block state endpoint.

When updating block states you can update a single block state or update multiple blocks states in a single request. Any updates made via the API will be reflected in the claim description form when viewing the claim on the Root management dashboard.

Accessing contextual data

In addition to the block states, the claims blocks schema can also access the entire claim object, the policy object linked to the claim, and the policyholder object linked to the policy.

This means the workflow can be adapted dynamically according to information that is stored on the claim, policy or policyholder. For example, it could be a product requirement that an input field for the claimant's family doctor should only be displayed if no family doctor was specified at the time of policy issue. The claims blocks schema is able to reference the policy object to determine if this information is already saved on the policy, and hide the input component if this is the case.

Action blocks such as payout request blocks also typically reference policy information, for example to allow the benefit amount saved to the policy to be prefilled as the default payout amount or to utilise existing beneficiaries' bank details.

The claims blocks schema accesses the claim and policy information by means of handlebars.

Handlebars

Claim, policy and policyholder data (the "merge variables") can be injected into the JSON schema using handlebars, as in the example below. See the handlebars guide for a detailed explanation of handlebars functionality.

{
  "show_if": true,
  "hide_if": false,
  "disabled_if": false,
  "required_if": false,
  "block": {
    "type": "input.text",
    "key": "example_block",
    "title": "Enter REF for policy number {{claim.policy.policy_number}}"
  }
}

The merge variables available to the claims block schema have the following nested object structure:

{
  "claim": {
  	"block_states": {
      ...
    },
    "policy": {
      "policyholder": {
      	...
      },
      ...
    },
    ...
  }
}

Example handlebars expressions for referencing these objects are provided below.

{{claim.claim_id}}
{{claim.block_states.example_block.value}}
{{claim.policy.policy_id}}
{{claim.policy.policyholder.first_name}}

Note that, since handlebars expressions are injected into string fields in the JSON claims blocks file, no line breaks are allowed in or between handlebars expressions. You should also avoid including unnecessary space characters. For example, a leading or trailing space could mean that a string value is not parseable as an integer by the platform.

Below is a more complete example showing how to use handlebars to make the display of one block conditional on other blocks.

{
  "show_if": "{{if (if claim.block_states.claim_type.option_key '===' 'accidental') '&&' (if claim.block_states.claim_type.option_key '===' 'natural')}}",
  "hide_if": false,
  "disabled_if": false,
  "required_if": false,
  "block": {
    "type": "input.text",
    "key": "example_block",
    "title": "Enter REF for policy number {{claim.policy.policy_number}}"
  }
}

Claim event lifecycle hooks

Certain claim events cause predefined functions to be executed in the product module code. These functions (or hooks) accept the claim object (together will all the block states saved to the claim) and policy object as parameters, and return actions that update policy information or create other side effects.

These hooks can be used to customise automatic product logic triggered by claim events. For example, the afterClaimApproved hook can be used to decrease policy benefit levels following a successful claim.

Read more about the supported claim event hooks and how to use them to configure custom product logic in in the lifecycle hooks guide.