Overview

This is the socotra connector module containing a data model, operations and java actions in order to post a submission for a reduced version of the personal-auto product to socotra.

Example use case

A Mendix Quote-and-buy application like D2C Product Launch, Quote and Buy delivers great UX and can be easily connected to policy administration systems to outsource policyholder and policy storage as well as the rating engine. The insurance core platform Socotra makes all of this easily accessible over APIs. Together they can offer an easy-to-use interface where consumers can answer product-related questions and enter their personal information, while in the background a policyholder account and policy draft are created in Socotra. After completion of data entry they will receive a quote that has been created in Socotra using the Socotra rating engine. Several quote versions can be created and the best one be selected by the user. When the consumer decides to buy the selected quote, the quote will be issued in Socotra and can be found on their platform through search of a locator number.

Documentation

Typical usage scenario

• Use a Mendix interface to collect a client’s answers to the personal-auto product questions for a car insurance application
• Send the entered information to Socotra to receive a quote from their rating engine and have a policyholder and a policy draft stored on the Socotra platform
• Update your existing application in the Mendix interface and send a new request to Socotra to create a new quote version
• Finish your application in Mendix and have a quote selected and the policy issued in Socotra

This connector might also serve as a good starting point if you want to develop other REST calls to Socotra than the ones listed in this connector.

Features

Connect to the Socotra rating engine

• Create different quote versions in Socotra
• Store policies in Socotra
• Extend the Mendix export mapping with a custom java action that enables a dynamic key-value structure, single-length-arrays ([“1”]) and fuzzymatching for entities renamed due to multiple occurences of the same name
• The connector is specific to an amended version of the personal-auto product and highly depends on the exact configuration (e.g. no fieldvalues on a policy level).

Implemented REST calls:

• POST_v1_Account_Authenticate: Authenticates the user
• POST_v1_Policyholder_Create: Takes an object containing information about the policyholder and creates a new policyholder on the Socotra platform
• POST_v1_Policy_Create: Creates a policy in status ‘Application in progress’ on the Socotra platform
• GET_v1_Policies_Quotes: Returns a list of associated quotes for a given policy locator id
• GET_v1_Quotes_ByQuoteLocator: Returns the connected quote for a given quote locator
• PATCH_v1_Quote_Lock: Locks and prices a quote in Socotra (the rating engine is used)
• POST_v1_Quotes_CreateNew: Creates a duplicate of the quote with the input quote locator
• PATCH_v1_Quotes: Updates the quote whose locator is used as input parameter with the information from a Mendix object used as the second input parameter
• PATCH_v1_Quotes_Select: Selects the quote belonging to the provided quote locator (when the policy is issued, the selected quote is used)
• POST_v1_Policy_Issue: Issues the policy with the input policy id

Java Actions:

This is a connector that has been developed specifically to the needs of Socotra’s personal-auto product without fieldValues on policy level (like “atfault_claims_past_5_years”). Since everything is configurable in Socotra there are cases where the standard import and export mapping are not dynamic enough which is why java actions have been introduced to replace and extend the mappings.

Exporting Mendix objects to JSON:

• ExportStructureToJSON
• ExportStructureToJSON_Configurable
  • The configurable option has more input settings and can handle matching of primitives and fuzzy matching.

These Java Actions accept a mendix object and produces a full JSON object from mx object reference structure based on entity and attribute name. Will translate any objects which are of the KeyValueEntity type or inherit from it automatically to JSON key value maps. If a sample JSON is provided the Mendix object structure will conform to the sample structure.

Importing JSON response to Mendix objects:

• ImportStructureFromJSON
• ImportStructureFromJSON_Configurable
  • The configurable option has more input settings and can handle fuzzy matching.

Accepts a JSON string and root object entity and produces a full network of mx objects based on entity & attribute name matching.

Limitations

The connector strongly depends on the defined data model and is limited to PolicyCreateRequests that do not contain fieldValues on a policy level. 

The connector might work for any product of the same structure with no such fieldValues on a policy level but that has not been tested by us. The structure that is not covered by the delivered logic is of the following form: 

``fieldValues``: {

        ``key``: [``value``]

    },

Dependencies

• Mendix 9.18.3
• Access to Socotra (sandbox) environment
• commons-lang3-3.12.0
• commons-text-1.10.0
• jackson-annotations-2.14.0-rc1
• jackson-core-2.14.0-rc1
• jackson-databind-2.14.0-rc1

Installation

• Import the module into your app.
• Create your own implementation module

Configuration

Pre-Requisites

• Socotra platform
  1. Have a sandbox environment (for testing purposes).
  2. Amend the personal-auto product as follows:
     • Remove all fields on policy level (e.g., ‘Sales channel’)
• Socotra Connector
  1. Fill in your Username, URL, Password, Hostname in the corresponding constants.

Implementation Example

• Socotra connector implementation module

For all operations: Fill Authentication token string

1. 1. PolicyholderCreateRequest (POST_v1_Policy_Create)
      • Create logic to fill the input parameter ‘PolicyholderCreateRequest’ with information (from the customer)
      • For the operation, set the PolicyHolderCreateRequest object as input parameter
   2.  PolicyCreateRequest (POST_v1_Policyholder_Create)
      • Fill your data into the request data structure from the connector domain model (it will then be transformed into the required JSON file with the Java action ExportStructureToJSON)
      • Hand the PolicyCreateRequest object to the operation
   3. PolicyCreateRequest (POST_v1_Policyholder_Create)
      • Leave the Requestbody empty
      • Hand the quote locator of the quote to update (it will first be duplicated) to the operation
   4. PolicyUpdateRequest (POST_v1_Quotes)
      • Fill your data into the request data structure from the connector domain model (it will then be transformed into the required JSON file with the Java action ExportStructureToJSON_Configurable)
      • Hand the PolicyUpdateRequest object as well as the locator of the just duplicated quote to the operation
   5. For the other calls, just make sure to put the correct locator id as input parameter.

More information on the calls can be found here Socotra Policy API and more information on lifecycles of quotes in Socotra can be found here Quotes in Socotra.