How To Use Instances
Learn how to submit values for parameters that have multiple instances.
As discussed in our risk and coverage parameter doc, some risk and coverage parameters can have multiple values. In the Dynamic Application, we communicate that a parameter can have multiple values using the property [.h-code]creates_array: true[.h-code], and each instance of that parameter is given a unique [.h-code]instance[.h-code] to distinguish between them.
The Purpose of Instances
Most of the questions on an application are unique, in that they can only have 1 value. As an obvious example, an applicant can only have 1 insured name on an application. However, some risks and coverages can have multiple values, to support cases such as an applicant with multiple locations, multiple class codes, or multiple domain names.
Let’s look at an example where an applicant has multiple locations and multiple class codes.
- The applicant has a manufacturing location in Los Angeles
- The applicant has a sales and marketing center in San Francisco.
This application would need multiple instances of risk parameter [.h-code]rsk_yor8_location[.h-code] for location, and multiple instances of risk parameter [.h-code]rsk_km7k_gl_class_code_by_location[.h-code] for class code which is a child of location. In this example, the application would include 2 instances of location, and 3 instances of class code (1 for manufacturing in Los Angeles, and 2 for sales and marketing in San Francisco).
[.icon-circle-blue][.icon-circle-blue] By default, the Dynamic Application only provides 1 [.h-code]instance[.h-code] of each parameter. You can generate additional instances by following the steps below.
Since there will be multiple instances of the same risk parameter, Herald assigns a unique [.h-code]instance[.h-code] to each case of the risk parameter to distinguish between them. This makes it easy to keep track of individual instances and map values to the correct instance, like this:
Instances in Dynamic Applications
Every risk or coverage parameter that supports multiple values will have 2 distinct properties associated with it: [.h-code]creates_array: true[.h-code] to communicate that the parameter can have multiple values, and the unique [.h-code]instance[.h-code] instance of that parameter.
In the example above, we have:
- 2 instances of location, for Los Angeles and San Francisco
- 1 instance of class code below the Los Angeles location, for manufacturing
- 2 instances of class code below the San Francisco location, for sales and marketing.
These parameters would be returned like this:
Creating New Instances
By default, the Dynamic Application only provides 1 instance of each parameter. When building a front-end application, Herald recommends that you give applicants the ability to add additional instances, to support applicants with multiple locations or multiple domains. Our guide to building a front-end provides some guidance on rendering this experience, but for now we’ll cover how to create additional instances using Dynamic Application.
You can create an additional instance by including an additional parameter via [.h-code]PUT[.h-code] [.h-endpoint-link]/applications[.h-endpoint-link]. Let’s walk through the example from above. When you first create the application, the response only includes 1 instance of each parameter.
To add a second instance, you should call a function to submit an additional instance of the parameter. That function should have 3 inputs:
- Parameter Type: Either a Risk Parameter (which would use [.h-code]risk_parameter_id[.h-code]) or a Coverage Parameter (which would use [.h-code]coverage_parameter_id[.h-code]).
- The Parameter ID: The actual ID for the parameter, such as [.h-code]rsk_yor8_location[.h-code].
- The Parent Array: The parameter could be nested within the [.h-code]risk_values[.h-code] array or [.h-code]coverage_values[.h-code] array, or it could be nested below a parent parameter.
Example function:
Let’s walk through the example from earlier where an applicant has 2 locations. When you first create the application, the response will only include 1 instance of location:
Note that the parameter is [.h-code]required_for: [”quote”][.h-code]. This is because at least 1 value is required by the carrier.
The parameter for location is a Risk Parameter with the ID [.h-code]rsk_yor8_location[.h-code], nested within the [.h-code]risk_values[.h-code] array. To create the additional instance of location, you would make a [.h-code]PUT[.h-code] request with the following:
The Application response will now include 2 instances of location, and automatically generate the new [.h-code]instance[.h-code]. Note that the additional instance is [.h-code]required_for: [ ][.h-code] because the additional location is optional.
On a front-end, you would power this by rendering an [.btn-small-ui]Add +[.btn-small-ui] button below every parameter that has [.h-code]creates_array: true[.h-code]. When the button is clicked, you would call the function to generate a new instance of the parameter, make a [.h-code]PUT[.h-code], and receive the additional instance. This can be done any incremental amount of time. Read our guide to building a front-end to learn more.
[.icon-circle-blue][.icon-circle-blue] If you already know an applicant has multiple locations, or multiple values for any parameter, you don’t have to add them one at a time. You can include any amount of instances and values when updating your application.
Deleting Instances
You can delete instances using a similar method to adding instances. On a front-end, you can generate a [.btn-small-ui]Remove -[.btn-small-ui] button below each instance when multiple are present. Since at least 1 value is required, this feature must be restricted when only 1 instance is present.
When adding an additional instance, you add an additional instance of a parameter to the [.h-endpoint-link]/applications[.h-endpoint-link] request and make a [.h-code]PUT[.h-code]. To remove an instance, you remove the specific instance from the [.h-endpoint]/applications[.h-endpoint] request and make a [.h-code]PUT[.h-code].
Following the example from above, let’s say the applicant now wants to remove the second location which has the instance [.h-code]location_2[.h-code]. To remove this location, you would remove that entire parameter from the application body, and make a [.h-code]PUT[.h-code].
The following application response will now only include the first location, which has the instance [.h-code]location_1[.h-code]. It’s important to use [.h-code]instance[.h-code] to make sure you are removing the correct values from an application.
Using Instance to Map Values
Using [.h-code]instance[.h-code] is very important when removing a specific value, and submitting a value below a parent parameter. In the example we’ve been using, an applicant has multiple locations with unique class codes for each building.
- The applicant has a manufacturing location in Los Angeles
- The applicant has a sales and marketing center in San Francisco.
In this example, we need to make sure we submit the class code value for manufacturing below the location for Los Angeles, and the class codes for sales and marketing below the location for San Francisco.
Since class codes and locations have a parent/child relationship, the value for each class code must be nested below the [.h-code]child_risk_values[.h-code] of the correct parent [.h-code]instance[.h-code]. In this case, we start with 2 locations:
As you can see above:
- The parameters for location have instances of [.h-code]location_1[.h-code] and [.h-code]location_2[.h-code] respectively.
- The class code below [.h-code]location_1[.h-code] has an instance of [.h-code]location_1.gl_class_code_by_location_1[.h-code].
- The class code below [.h-code]location_2[.h-code] has an instance of [.h-code]location_2.gl_class_code_by_location_1[.h-code].
[.icon-circle-blue][.icon-circle-blue] When rendering this on screen, you’ll want to want to visually place the child parameters below the parent, and you may want to hide the 2nd [.h-code]instance[.h-code] of all [.h-code]creates_array: true[.h-code] parameters. All of these instructions are documented in our guide to building a front end.
Let’s assume that the class code for manufacturing, which takes place at the location in Los Angeles, is 53731. We want to make sure that we submit 53731 as the class code with the instance [.h-code]location_1.gl_class_code_by_location_1[.h-code], nested below the location with the instance [.h-code]location_1[.h-code].
Your [.h-code]PUT[.h-code] request to [.h-endpoint-link]/application/{application_id} [.h-endpoint-link] should look like this:
How Instances are Generated
Each instance is automatically generated by Herald. The [.h-code]instance[.h-code] value has a relevant description based on the question, and a number based on its instance in the series. Submitting 4 individual values for location would automatically assign the instances [.h-code]location_1[.h-code], [.h-code]location_2[.h-code], [.h-code]location_3[.h-code], and [.h-code]location_4[.h-code].
If a parameter that can support multiple values is nested below a parent parameter that can have multiple values, the [.h-code]instance[.h-code] will have the parents instance as a prefix. For example, an applicant can have multiple locations with multiple class codes at each location. If the applicant has performs work across 2 industries at their second location, the class codes would have an instance of [.h-code]location_2.gl_class_code_by_location_1[.h-code] and [.h-code]location_2.gl_class_code_by_location_2[.h-code] respectively.
You can read the full list of parameters that have instances, and their instance names, in this document.
[.icon-circle-blue][.icon-circle-blue] You do not have to submit [.h-code]instance[.h-code] in your request. Submitting this value will be ignored by Herald.
