How to Design a Front-End Application

[.icon-alert][.icon-alert] This guide is written with the Dynamic Application in mind. The process for the static application is nearly identical, but you'll need to gather the associated data for each risk and coverage parameter from the Appendix.

‍

To design a front-end application, you'll need to have a good grasp on risk and coverage parameters. To refresh your memory, an application is essentially a series of questions for a set of products, categorized as risk values (each question is a [.h-code]risk_parameter[.h-code]) and coverage values (each question is a [.h-code]coverage_parameter[.h-code]).
‍
Since the Dynamic Application is….well, dynamic, Herald provides metadata for each parameter to help you render them on-screen with proper validation.

In this guide, we’ll teach you:

1. Format Each Question

For every risk and coverage parameter, we’ll include some useful information to help you render it on screen. The 3 pieces of metadata you should use when formatting individual parameters [.h-code]text[.h-code], [.h-code]schema[.h-code], and [.h-code]input_type[.h-code].

Any number of conditional questions can appear when using the Dynamic Application, so it’s important to build logic to handle every situation. For the most part, parameters are either text inputs, number inputs, multiple choice questions, or objects. We strongly recommend having unique styling in place for each of the input types.

Let’s take a look at a few different parameters based on their [.h-code]input_type[.h-code]

  {
    "risk_parameter_id": "rsk_yor8_location",
    "instance": "location_1",
    "value": null,
    "text": "Location",
    "input_type": "address",
    "relevant_products": [
      "prd_mc4r_herald_general_liability"
    ],
    "creates_array": true,
    "affects_conditions": true,
    "required_for": [
      "quote"
    ],
    "schema": {
      "type": "object",
      "properties": {
        "line1": {
          "type": "string"
        },
        "line2": {
          "type": "string"
        },
        "organization": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string",
          "enum": [
            "AL",
            "AK",
            "AZ",
            ...
            "WY"
          ]
        },
        "postal_code": {
          "type": "string",
          "pattern": "^\\d{5}$"
        },
        "country_code": {
          "type": "string",
          "enum": [
            "USA"
          ]
        }
      },
      "required": [
        "line1",
        "city",
        "state",
        "postal_code",
        "country_code"
      ]
    },
  }
   
  

  {
      "risk_parameter_id": "rsk_fjpk_has_claims_history_three_years",
      "value": null,
      "text": "Has the applicant had any claims in the last three years?",
      "input_type": "select_one",
      "relevant_products": [
          "prd_m3qr_herald_general_liability"
      ],
      "affects_conditions": true,
      "required_for": [
          "quote"
      ],
      "schema": {
          "type": "string",
          "enum": [
              "yes",
              "no"
          ]
      }
  },
   
  

  {
    "coverage_parameter_id": "cvg_c02a_gl_each_occurrence_limit",
    "value": null,
    "text": "Each Occurrence Limit",
    "input_type": "integer",
    "relevant_products": [
      "prd_mc4r_herald_general_liability"
    ],
    "affects_conditions": false,
    "required_for": [],
    "schema": {
      "type": "integer",
      "minimum": 100000,
      "maximum": 5000000
    }
  },
   
  

‍

2. Render Nested Questions

Since some questions have a parent/child relationship, it’s important to visually communicate this hierarchy. You’ll also need to associate the child parameter with the parent when submitting values, with the child parameter nested beneath the parent. Child parameters are nested under the parent in an array:

Let’s use the example of an applicant with multiple locations. The applicant may have different class codes under each location, like a manufacturing plant in a San Francisco location and a sales department in Los Angeles. In the application response, each location will have a class code nested below it within the [.h-code]child_risk_values[.h-code] array.

It’s important to render each class code visually below the correct location. This way the applicant knows which class code to submit for each instance of class code. Otherwise, they could see 2 class code inputs without the context of what each of them are for.

Copied

{
  "risk_parameter_id": "rsk_yor8_location",
  "instance": "location_1",
  "value": null,
  "text": "Location",
  "input_type": "address",
  "affects_conditions": true,
  "creates_array": true,
  "required_for": ["quote"],
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "value": null,
      ...
    },
  ]
},
{
  "risk_parameter_id": "rsk_yor8_location",
  "instance": "location_2",
  "value": null,
  "text": "Location",
  "input_type": "address",
  "affects_conditions": true,
  "creates_array": true,
  "required_for": ["quote"],
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "value": null,
      ...
    },
  ]
}
 

This segues nicely into our next step.

3. Allow Multiple Values

Parameters that can have multiple values have the property [.h-code]creates_array: true[.h-code]. Inherently, parents parameters can have multiple values, because the child parameters are related to a unique instance of the parent. Many parameters support multiple values, some examples of this are:

• Class code for a specific location. Some applicants have multiple locations, performing different types of work at each one.
• Payroll for a specific class code. Some appliances have multiple professions, and are required to submit an exposure basis for each one.
• Property Limits for a specific building. Some applicants have multiple buildings, and have the option to choose unique limits for each one depending on its size and value.
• A field for domain names, that allows for applicants with multiple domains.

[.icon-alert][.icon-alert] By default, The Dynamic Application only provides 1 instance of each parameter. You can generate additional instances by following the steps in our guide to using instances.

To build a front-end that supports multiple values, you should pay attention to the following metadata: [.h-code]creates_array[.h-code], [.h-code]instance[.h-code], and [.h-code]required_for[.h-code].

To support these cases, your application should support the ability to add and remove instances. All parameters with the property [.h-code]creates_array: true[.h-code] support multiple values. Let's continue with our same example from above. Class code, which is a child of location, can have multiple values to support applicants that perform work across multiple industries.

To power this feature on your front-end, we recommend building logic to:

1. Render an [.btn-small-ui]Add +[.btn-small-ui] button for each parameter that has [.h-code]creates_array: true[.h-code]. When clicked, a new instance should be created. Steps for creating instances are documented here.
2. Render an [.btn-small-ui]Remove -[.btn-small-ui] button for each [.h-code]creates_array: true[.h-code] parameter when multiple instances are present. This feature must be restricted when only 1 instance is present. Steps for deleting instances are documented here.

Here’s an example of how a front-end could power this functionality:

Copied

{
  "risk_parameter_id": "rsk_yor8_location",
  "instance": "location_1",
  "value": null,
  "creates_array": true,
  "required_for": ["quote"],
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "instance": "location_1.gl_class_code_by_location_1",
      "value": null,
      "text": "Class code",
      "input_type": "short_text",
      "affects_conditions": true,
      "creates_array": true,
      "required_for": ["quote"],
      "schema": {
          "type": "string"
      }
    },
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "instance": "location_1.gl_class_code_by_location_2",
      "value": null,
      "text": "Class code",
      "input_type": "short_text",
      "affects_conditions": true,
      "creates_array": true,
      "required_for": [],
      "schema": {
          "type": "string"
      }
    }
  ]
}
 

It’s important to build this logic to globally support parameters with creates_array: true, not on a parameter by parameter basis. Here’s a matrix of how this logic would render different questions on screen based on the parameters value of [.h-code]creates_array[.h-code]:

When adding and removing inputs on your front-end, you should also be adding and removing the parameter in your application body. Each individual instance of a parameter will have a unique [.h-code]instance[.h-code]. Our guide to using instance outlines how to use this property to map the correct value to the correct instance when filling out an application.

‍

4. Update the Application

As we discussed at length in our Dynamic App doc, the dynamic application handles conditionality for you. As you collect and submit values, additional conditional questions can come back. Any risk or coverage parameter that can potentially yield additional parameters is given the property [.h-code]affects_conditions: true[.h-code].

As you update your application and receive new questions, you’ll need somewhere to put them! Some ways we’ve seen this handled:

• You could render them on the same screen as you continually update the application, making a PUT request after each value is entered.
• You could collect the values for the initial set of questions, make a PUT request, and put the next level of conditional questions on the following screen.
• You could ask each question 1 step at a time for a more conversational approach, inserting each new question with a null value in a following step.

Continuing with our example, we’ve now added a class code input below Location, with the ability to add multiple class codes. Since class code has [.h-code]affects_conditions: true[.h-code], let’s update the application and see what comes back.

[.icon-alert][.icon-alert] Conditional questions can come back anywhere after each update, they are not always placed at the bottom. For example, if State is question [ 1 ] and Name is [ 2 ], a conditional question based on State could be returned below [ 1 ]. In this case, Name would now be placed as question [ 3 ].

Copied

{
  "risk_parameter_id": "rsk_yor8_location",
  "instance": "location_1",
  ...
  "child_risk_values": [
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "instance": "location_1.gl_class_code_by_location_1",
      "value": "53731",
      ...
      "child_risk_values": [
      {
        "risk_parameter_id": "rsk_xcv3_payroll_by_gl_class_code",
        "value": null,
        ...
      },
    },
    {
      "risk_parameter_id": "rsk_km7k_gl_class_code_by_location",
      "instance": "location_1.gl_class_code_by_location_2",
      "value": "16900",
      ...
      "child_risk_values": [
      {
        "risk_parameter_id": "rsk_w72m_gross_sales_by_gl_class_code",
        "value": null,
        ...
      },
    },
  ]
}
 

‍

5. Build Front-End Validation

Alluded to Herald includes a [.h-code]schema[.h-code] object to describe the expected value. This property can help render items like enum values on screen, but it can also power front-end validation. Depending on the [.h-code]input_type[.h-code], schema can define things such as:

• Min and max values for number inputs.
• Patterns, for inputs such as phone number.
• Max characters, for things like FEIN number.

You can use the information denoted in the [.h-code]schema[.h-code] to power your own front-end validation. Here’s a few examples:

    {
      "coverage_parameter_id": "cvg_c02a_gl_each_occurrence_limit",
      "value": null,
      "text": "Each Occurrence Limit",
      "input_type": "integer",
      "relevant_products": [
        "prd_mc4r_herald_general_liability"
      ],
      "affects_conditions": false,
      "required_for": [],
      "schema": {
        "type": "integer",
        "minimum": 100000,
        "maximum": 5000000
      }
    },
     
    

    {
      "risk_parameter_id": "rsk_14kt_insured_contact_phone",
      "value": null,
      "text": "Applicant phone number",
      "input_type": "phone",
      "relevant_products": [
        "prd_mc4r_herald_general_liability"
      ],
      "affects_conditions": false,
      "required_for": ["quote"],
      "schema": {
        "type": "string",
        "pattern": "$\\d{10}^"
      }
    },
     
    

‍

6. Decide Which Questions to Require

A risk and parameter can either be optional or required depending on the product and event you are tracking toward. This is conveyed using the [.h-code]required_for[.h-code] array. If it is required for quote, it will be [.h-code]required_for: [”quote”][.h-code]. If it is optional, the array will be empty like this [.h-code][ ][.h-code].

There is a chance that optional questions will still be required to bind a policy when you bridge to the carriers portal. If your goal is simply to get quotes in your platform as quickly as possible, you could choose to only show [.h-code]required_for: [”quote”][.h-code] parameters. If you want to make a seamless experience after going to the carriers portal, it may be better to ask all questions up front. Here’s an example of how this appears in the application response.

Copied

{
  "coverage_parameter_id": "cvg_c02a_gl_each_occurrence_limit",
  "value": null,
  "text": "Each Occurrence Limit",
  "input_type": "integer",
  "relevant_products": [
    "prd_mc4r_herald_general_liability"
  ],
  "affects_conditions": false,
  "required_for": [],
  "schema": {
    "type": "integer",
    "minimum": 100000,
    "maximum": 5000000
  }
},
{
  "risk_parameter_id": "rsk_14kt_insured_contact_phone",
  "value": null,
  "text": "Applicant phone number",
  "input_type": "phone",
  "relevant_products": [
    "prd_mc4r_herald_general_liability"
  ],
  "affects_conditions": false,
  "required_for": ["quote"],
  "schema": {
    "type": "string",
    "pattern": "$\\d{10}^"
  }
},
 

‍

7. Structure Your Application

At last, it’s time to decide how to structure your application. Herald provides you with metadata to build an application that works for you. The most basic form of rendering our Dynamic Application response on screen is by making a 1-page application, where conditional questions appear on the same screen as updates are submitted. If a 1-page application works for you, you can simply make a [.h-code]PUT[.h-code] request every time a value is entered into an input.

If you’re looking to build a fully integrated application with an existing front-end, where you’d like to pick and choose where to place each individual question, our static application might be best for you. But we’re continually looking to improve our Dynamic Application API to support more use cases. If you’re still deciding what to build and want to chat, reach out!

‍