Data Fields

Many Socotra entities can be extended with a fieldValues array, which defines the additional data insurers wish to be persisted with each object. Each element of the array takes this general form:

{
  "name": "a_string",
  "title": "Enter text",
  "type": "string",
  "optional": true,               // optional
  "width": 12,                    // optional
  "condition": {                  // optional
    "another_field_name": ["value1", "orValue2"]
  },
  "newline": true,                // optional
  "heading": "My Section Heading" // optional
}

The following entities can contain field values:

• Policyholders (with exceptions: see Policyholder Exceptions below)

• Policies

• Exposures

• Perils

• Premium Reports

• Claims

• Sub Claims

• Payments (except for lookup and group type field values)

Note

See the notification Peril Field Names for information about reserved property names.

Socotra supports these data types for field values:

• Date

• Email

• Media

• Number

• String

• Select

• Group

• Lookup

Policyholder Exceptions

Policyholders cannot be defined with the following field types:

• Media

• Group

• Lookup

Additionally, the title attribute on supported types should not be used in the policyholder field definition; instead, the title functionality is served by prompt in policyholder.form.json. Field definition examples below should be adjusted accordingly when used as the basis for policyholder field definitions.

Attributes available on all data types

Attribute	Required	Valid Values	Description
name	yes	String with no spaces	Identifier for the field name
title	yes	String	Prompt text in the UI
type	yes	Field type name, as a string
optional	no	Boolean
condition	no	Array of fieldName-array pairs	The condition parameter allows control of when a field can and should be set. If the value in the referenced field matches one of the values in the array (logical OR), then this field can be set. If multiple fields are referenced, the condition must pass on each of them (logical AND).
width	no	Integer from 1-12	Applies to the Socotra UI - defaults to 6 (half the width of the workflow)
newline	no	Boolean	Applies to the Socotra UI - starts a new line with this field
heading	no	String	Applies to the Socotra UI - specifies a section heading to display before this field

Note

For string based fields, there is a limit of 20,000 characters. Only the first 2,700 characters will be indexed and available for search through the user interface.

Optionality

Fields can be designated as optional in configuration. For these fields, they do not need to be set at create time. To remove a value from an optional field that already has a value, set it to the empty array: [].

Data Types

Date

Attribute	Required	Valid Values	Description
precision	yes	“second”, “day”, “month”, “year”
minimum	no	1/1/15
maximum	no	1/1/15
minimumOffset	no	field (precision), amount (number), roundToDay (boolean)
maximumOffset	no	field (precision), amount (number), roundToDay (boolean)
showCalendar	no	Boolean	Indicates if the calendar selector widget should be shown in the Socotra UI

{
  "name": "date_field_example",
  "title": "calendar date entry",
  "type": "date",
  "precision": "day",
  "minimumOffset": {
    "field": "day",
    "amount": -1,
    "roundToDay": true
  },
  "maximumOffset": {
    "field": "day",
    "amount": 1,
    "roundToDay": true
  },
  "showCalendar": true
}

Email

The email data type is similar to a string but subject to validation that the content is a valid email address.

No specific attributes

{
  "name": "email_field_example",
  "title": "email entry",
  "type": "email"
}

Media

This allows the user to upload and store files of any type on the policy.

Attribute	Required	Valid Values	Description
repeatable	no	Boolean	Indicates that the media field can contain multiple instances

{
  "name": "media_field_example",
  "title": "Media Upload",
  "type": "media",
  "width": 12,
  "repeatable": true
}

Number

Attribute	Required	Valid Values	Description
minimum	no	Integer
maximum	no	Integer
decimalPlaces	no	Integer

{
  "name": "number_field_example",
  "title": "number entry (integer, optional)",
  "type": "number",
  "decimalPlaces": 0,
  "optional": true
}

String

Attribute	Required	Valid Values	Description
regex	no	Regex string	The regex is applied to the entire string. No start and end markers for the expression are necessary.
maximum	no	Integer	The maximum number of ASCII characters to be stored in the field. This parameter defaults to 200 and may not exceed 20,000. Non ASCII characters need more space so if there are unicode characters mixed in the actual limit will be smaller.
multiline	no	Boolean

{
  "name": "text_field_example",
  "title": "large text entry with 3000 character max length",
  "type": "string",
  "multiline": true,
  "maximum": 3000
}

Select

Attribute	Required	Valid Values	Description
values	yes	Array of strings	The allowed values for the field
repeatable	no	Boolean	Indicates if one key can contain several values

{
  "name": "select_field_example",
  "title": "dropdown entry",
  "type": "select",
  "values": [
    "Option 1",
    "Option 2",
    "Option 3",
    "And so on"
  ]
}

Group

Attribute	Required	Valid Values	Description
fields	yes	Array of fields	Can contain any field type except “group”
repeatable	no	Boolean	Indicates that the group can contain multiple instances

While the values for all other field types are available directly in the fieldValues object, fields with the group type instead have an array of locators. Those locators can be used to address the field group, which is exposed as a unit in the “Field Groups By Locator” object.

More information for working with groups is available at: Field Groups

{
  "name": "group_example",
  "title": "field group",
  "type": "group",
  "fields": [
    {
      "name": "group_string_example",
      "title": "string in field group",
      "type": "string"
    },
    {
      "name": "group_number_example",
      "title": "number in field group",
      "type": "number"
    }
  ],
  "repeatable": true
}

Lookup

Attribute	Required	Valid Values	Description
table	yes	String	The name of the datasource
match	no	Array of strings	If the datasource contains multiple columns, this specifies the names of the fields to match in left-to-right order in the datasource. The values available are those in the next column that match the preceding values.

Suppose you have a table representing cars, called vehicle_make_model, with three columns: vehicle_make, vehicle_model, and vehicle_year. Use the following configuration for fields representing make, model, and year that only allow a combination matching a row in the table.

[
  {
    "name": "vehicle_make",
    "title": "Vehicle Make",
    "type": "lookup",
    "table": "vehicle_make_model"
  },
  {
    "name": "vehicle_model",
    "title": "Vehicle Model",
    "type": "lookup",
    "table": "vehicle_make_model",
    "match": ["vehicle_make"]
  },
  {
    "name": "vehicle_year",
    "title": "Vehicle Year",
    "type": "lookup",
    "table": "vehicle_make_model",
    "match": ["vehicle_make", "vehicle_model"]
  }
]

Conditions

In the below example, the condition statement indicates that this field should only have data if the following expression is true:

(select_field_example == "Option 1" OR select_field_example == "Option 3") AND (number_field_example == 1 OR number_field_example == 5)

{
  "name": "conditional_text_field",
  "title": "Text entry to explain a previous entry",
  "type": "string",
  "multiline": true,
  "optional": true,
  "width": 12,
  "condition": {
      "select_field_example": ["Option 1", "Option 3"],
      "number_field_example": ["1", "5"]
  }
}

Reserved Peril Field Names

Important

The following field names should not be used on perils because they conflict with existing peril properties:

• deductible

• deductibleType

• indemnityPerItem

• indemnityPerItemType

• indemnityPerEvent

• indemnityPerEventType

• indemnityPerAggregate

• indemnityPerAggregateType

• lumpSumPayment

• lumpSumPaymentType