Field Groups

A field group is a related set of attributes, similar to fieldValues but with several values grouped together. They can be single or many (repeatable) and are defined in the fields array in the JSON configuration file for the associated entity.

The following entity types can contain field groups:

• Policies

• Exposures

• Perils

• Premium Reports

• Claims

• Sub Claims

Note

Note: payments may contain field values but cannot contain field groups.

A driver is a common group type that is used in motor insurance and described as in the example below in exposure.json:

{
  "name": "driver",
  "title": "Drivers",
  "optional": true,
  "type": "group",
  "fields": [
    {
      "name": "firstname",
      "title": "Driver - First Name",
      "width": 3,
      "type": "string",
      "optional": true
    },
    {
      "name": "lastname",
      "title": "Last Name",
      "width": 3,
      "type": "string",
      "optional": true
    },
    {
      "name": "dl_number",
      "title": "Driver License Number",
      "width": 3,
      "newline": false,
      "type": "string",
      "optional": true
    }
  ],
  "repeatable": true,
  "maximum": 6
}

In the following examples, we’ll use the following drivers as our dataset:

firstname	lastname	dl_number
John	Doe	A7743991
Jane	Richards	C13245677

API Access

Field groups values are often available in API responses through a combination of the fieldValues and fieldGroupsbyLocator attributes in the characteristics object. When retrieving the fieldValues, the group’s locator is provided as the fieldValue. The locator can be used to find the group’s subvalues via the fieldGroupsbyLocator as shown in the example below.

Example Policy Characteristics

{
"fieldValues": {
  "driver": [
    "1b149253-9376-4190-bc38-05a04fdeee30",
    "b96e7837-c764-4af3-83b8-4449e3119d0d"
  ]
},
"fieldGroupsByLocator": {
  "b96e7837-c764-4af3-83b8-4449e3119d0d": {
    "firstname": ["John"],
    "lastname": ["Doe"],
    "dl_number": ["A7743991"]
  },
  "1b149253-9376-4190-bc38-05a04fdeee30": {
    "firstname": ["Jane"],
    "lastname": ["Richards"],
    "dl_number": ["C13245677"]
  }
}

To create a driver in this configuration, create the field Group with the FieldGroups attribute and leave it out of the fieldValues map. Socotra will automatically generate a unique identifier for each fieldGroup as explained above.

Policy Creation

This subset of a PolicyCreateRequest shows how to specify field group data:

{
  "fieldGroups": [
    {
      "fieldName": "driver",
      "fieldValues": {
        "firstname": "John",
        "lastname": "Doe",
        "dl_number": "A7743991"
      }
    }
  ],
  "fieldValues": {}
}

Liquid Access

To access field group attributes in liquid, the object model remains the same as the API. The first step is to retrieve the array of group locators and then retrieve that element from the fieldGroupsbyLocator component.

For example:

{% for driver_loc in exp_v.drivers %}
    {% assign driver = exp_c.field_groups_by_locator[driver_loc] %}
    {{driver.firstname}} <br>
    {{driver.lastname}} <br>
    {{driver.dob}}<br>
    <br>
{% endfor %}

Endorsements

In Liquid, for endorsement document rendering there is a group notation so that the lookup is unnecessary. In the template, you can access fieldGroups directly from the fieldValues object.

{% for driver in exp_v.drivers %}
    {{driver.firstname}}<br>
    {{driver.lastname}}<br>
    {{driver.dob}}<br>
    <br>
{% endfor %}