Data Auto-Fill

The Data Auto-Fill feature allows updating policy information before committing. This alleviates the need for end-users or integrated systems to have all of the information required to establish a transaction.

For example, upon supplying a VIN for a vehicle, the auto-fill feature could be used to populate the Make, Model, Year, and features for the vehicle.

Data Auto-Fill is available for these transactions:

  • Policy Create

  • Policy Update

  • Endorsement Create

  • Endorsement Update

  • Renewal Create

  • Renewal Update

The supplementary auto-fill information can be retrieved from an internal plugin or external systems via an External Service Integration.

Note

This feature is intended to be a substantial improvement over External Data Calls. Use of both for a single product is not supported. Support for external data calls will be removed from future releases, but not until a notice of deprecation is made and all customers have an opportunity to migrate.

Resolving the Auto-Fill Call Sequence

For each defined operation, Socotra will identify the sequence of external integration calls. This will always be a single list for a single request. To construct the list, Socotra will:

  • Use the sequence as given in the autofill property in the create or update request if it is set. (See the section below on the API for “Per-Event” Autofill) If the property is not set:

  • Use the call definition that has an operation property that equals <productName>.<transactionName>.<transactionAction>, such as personal-auto.newBusiness.create.

  • If there is no match Socotra will try <productName>.<transactionName>.*, such as personal-auto.newBusiness.*

  • If there is still no match Socotra will try <productName>.*.*, such as personal-auto.*.*

  • Finally, if there is no match Socotra will look for an operation with *.*.* (i.e., any transaction.)

If Socotra does find a match it will use the sequence as given, and otherwise there will be no auto-fill calls for the policy transaction.

transactionName can be any of:

  • newBusiness

  • endorsement

  • renewal

  • *

transactionAction can be any of:

  • create

  • update

  • *

Note, the following operation structures are not supported:

  • *.<transactionName>.<transactionAction>

  • <productName>.*.<transactionAction>

  • *.<transactionName>.*

  • *.*.<transactionAction>

After a match is made, Socotra will determine the sequence of calls to be made. This is in the form of external service integration names and references to the internal plugin (an array of strings).

Execution

When a transaction is being executed, the autofill process will work as follows:

  • Determine the series of external calls needed (an ordered list of external service integration names) based on the process listed in the previous section.

  • Assemble a request as defined in the Call Protocol section

  • The policy create/update request data (for new business) or endorsement / renewal data will be updated based on the response.

  • Repeat for each name in the integrations sequence

This will happen for these events:

  • Policy / quote creation

  • Draft policy / quote update

  • Endorsement creation

  • Endorsement update

  • Renewal creation

  • Renewal update

Setting Up Data Auto-Fill

External Calls

To establish and manage auto-fill integration points, use the External Service Integration API and create an integration with type data_autofill.

Then, establish the sequence of calls, or “operations” with these endpoints:

Add an autofill operation
PUT /integrations/autofill
AutofillIntegrationCreateRequest
required
callSequence [string]
operation string
Fetch autofill operations
GET /integrations/autofill
AutofillIntegrationResponse
required
AutofillCallResponse
required
locator string
callSequence [string]
operation string
Fetch an individual operation
GET /integrations/autofill/{locator}
Remove an operation
DELETE /integrations/autofill/{locator}
    Request:
    NamePositionTypeRequired
    locatorpathstringrequired
    Response: void

Internal Plugin

Logic which does not depend on an external call can be embedded in a new plugin called DataAutofill which can take the place of an external call:

If the name in the call sequence equals internal then the call will be sent to the plugin instead of externally. The payload put in the data input object will be the same as for an external call, and the required response will be the same as well.

If the Autofill plugin is not defined and an internal call is specified, the transaction will fail.

API for “Per Event” Autofill

The following objects will have a new, optional, autofill property which is a sequence (array) of strings identifying external service integration names:

If the autofill property is set for the transaction being executed, then the sequence given will be used. If not, Socotra will check to see if there is a configured sequence for that product/transaction/event combination as described in the next section.

If autofill is missing or set to null, it will be deemed to be not specified so the default for the operation will be used. If autofill is set to an empty array, no autofill operations will run for that request.

Protocol for Communication from Socotra and External Services

Outbound (from Socotra)

Socotra will send an AutofillPayload object to each autofill service:

AutofillPayload
required
policyholderLocator string
productName string
operation string newBusiness | endorsement | renewal | reinstatement | cancellation | manual | feeAssessment
operationType string create | update

optional
policyLocator string
endorsementLocator string
quoteLocator string
renewalLocator string
configVersion integer
AutofillUpdateRequest
required
policyEndTimestamp timestamp
policyStartTimestamp timestamp

optional
endorsementName string
endorsementEffectiveTimestamp timestamp
fieldValues map<string,[string]>
updateFieldGroups [AutofillFieldGroupUpdateRequest]
removeFieldGroups [string]
removeExposures [string]
AutofillFieldGroupCreateRequest
required
fieldName string

optional
fieldValues map<string,[string]>
AutofillFieldGroupUpdateRequest
required
fieldGroupLocator string
fieldName string

optional
fieldValues map<string,[string]>
AutofillExposureCreateRequest
required
exposureName string

optional
fieldValues map<string,[string]>
AutofillExposureUpdateRequest
required
updateFieldGroups [AutofillFieldGroupUpdateRequest]
removeFieldGroups [string]
exposureLocator string
removePerils [string]

optional
fieldValues map<string,[string]>
AutofillPerilCreateRequest
required
name string

optional
fieldValues map<string,[string]>
AutofillPerilUpdateRequest
required
addFieldGroups [FieldGroupCreateRequest]
updateFieldGroups [FieldGroupUpdateRequest]
removeFieldGroups [string]
perilLocator string

optional
fieldValues map<string,[string]>

Inbound (to Socotra)

The following object should be returned from the external service:

AutofillResponse
required
fieldValues map<string,[string]>

optional
endorsementEffectiveTimestamp timestamp
policyEndTimestamp timestamp
policyStartTimestamp timestamp
updateFieldGroups [AutofillFieldGroupUpdateRequest]
removeFieldGroups [string]
removeExposures [string]

For new business, the draft policy data will be updated based on the response. For endorsements or renewals, the endorsement or renewal itself will be updated.

After the first call, the process will be repeated for each subsequent external service defined for the product or transaction.

Note

If any of the properties is missing from the response, it will be interpreted to mean “unchanged.” To clear a value the property can be set to an empty array.

Policy Creation

For policy creation, none of these properties are allowed. They should not be sent to the external service, and if included in the response with a non-empty array as the value, then the transaction will fail:

  • updateFieldGroups

  • removeFieldGroups

  • updateExposures

  • removeExposures

  • updatePerils

  • removePerils

Note

Autofill message sizes are limited to 5MB. Transactions that require messages larger than 5MB will fail.