External rater

Socotra app manifest supports a special type of integration - External Rater. This enables app developers to create an application which contains logic for calculating prices for new business, endorsements and renewals in Socotra Core engine. Creating new rater application or converting existing application into Socotra Marketplace app format allows developers to provide much better experience for app users - platform will handle application hosting, health and integration with customer selected tenant.

Overview

External rater application in Marketplace supports everything described in Socotra Core documentation. Marketplace platform will handle automatic launch of the application and it’s integration with customer-selected Core tenant.

Platform will NOT register external rater instance with any of customer’s products. This step requires that customer admin make a decision about which existing products must use newly installed external rater app. This may have material impact on customer’s business and can’t be automatic, must be performed by a human.

Currently app manifest supports only static hardcoded values for additional header fields in external rater registration section.

Converting existing app to Marketplace app

Official documentation about Socotra Core external rater integration is here https://docs.socotra.com/production/tooling/external-rater.html

This section is focusing on converting your existing application into socotra marketplace app format and allowing customers to start an instance of external rater and manually integrate it in their existing products.

Assume publisher already has an existing custom-built application which works as an external rater. To convert this application into Marketplace format we need to do the following:

1. Create socotra-app.json app manifest file (via CLI or editor, follow the main documentation for more specific details ) and configure name and version fields
2. In app manifest, extend “socotra” property and add “externalRaters” section. For example:

{
  "name": "socotra/alexey-extrater",
  "version": "1.0.37",
    "socotra": {
    "externalRaters": [
      {
        "name": "first-rater-endpoint-name",
        "path": "/product-raters/first-rater",
        "headers": {
          "x-static-header": "headerValue-001",
          "x-api-username": "John"
          "x-api-secret": "static-api-key"
        }
      },
      {
        "name": "second-rater-endpoint-name",
        "path": "/product-raters/second-rater-url?with=static_queryString"
      }
    ]
    }
}

One application may have multiple entries in externalRaters section, which means that every entry in this collection will be registered as a separate external rater integration in customer’s Core tenant. Each external rater entry must contain following fields:

name (required) - provide unique names for raters or application will fail on start - Socotra Core requires all external rater integrations to have unique names.

IMPORTANT: Platform does not guarantee that this exact name will be used, as if customer has multiple external raters (from different versions of the app) registered in their tenant - to guarantee uniqueness of the rater name, a suffix may be added to the rater name. It will use provided name as a prefix for the full name and customer must use full name presented in running app details page to connect their products to this instance of external rater.

path (required) - relative path to identify application endpoint where external rater request will be sent.

headers (optional) - a collection of static headers in key-value pair format, which will be added to every request from Socotra Core to external rater instance. Currently app developers can only define static keys and values in this collection, which means - all registered integrations will have the same custom headers set.

Platform team planning to implement a feature, to allow publisher to define required inputs from customer to be used as headers, and every customer must specify those during installation process (such fields as unique license key or api access username\token), which will be added as a static header for their specific external rater app instance.

Package your application as a Docker image and publish it in Marketplace using either UI interface or CLI tool socotra-app . Certain steps such as uploading image to socotra marketplace can be done only via CLI. For details please refer to main documentation pages.

Platform internals

When customer starts a fully configured instance of external rater application and connects it to their environment and tenant, Marketplace platform will do the following:

Launch specific version of docker image, previously uploaded by developer.

Guide customer through configuration steps where they would select environment, tenant, product and fill all required fields from app-manifest.

Provision a publicly routable base url in a customer selected region, for example: https://nptm6hg1o723.sandbox.outpost.marketplace.socotra.com/

Take every entry in externalRaters section of socotra-app.json manifest and create an integration of type external_rater with name, path and headers configured in the section.

Record full name of created external_rater integration and present it to customer.

To connect specific product to the instance of external rater - customer admin must manually edit policy.json file (usually via Socotra config studio UI or text editor) associated with a selected product and add entry "externalRater": "<external_rater_name>" to it. After new configuration is published - external rater buttons will be displayed in Socotra UI for new business endorsements and renewals pages.

For app customers

How to connect external rater to an existing product

Socotra official latest documentation for External Rater integration can be found here. Documentation outlines 3 steps required for integration of an external rater into your tenant products:

1. Stand up a web service that accepts requests from the Socotra API for all pricing requests
2. Create the external rater configuration with a unique name, identify the URL endpoint and optionally, set one more headers to be sent with the request (to be used for authentication or other purposes) via the UI Administrative Panel or Integrations API.
3. Include the entry "externalRater": "<external_rater_name>" in the policy.json file associated with the product for which the external rater service will be used.

By launching and configuring an external rater application from Socotra Marketplace we completed 1st and 2nd steps. Running application stands up a service to accept requests from Socotra API and automatically registers an external rater configuration with Socotra tenant you selected during configuration step. To complete the integration, admin only needs to manually add "externalRater":"<external_rater_name>" entry in `policy.json`` file for corresponding products.

To do this, we need following information:

• Tenant, which was used to configure external rater application, launched in Socotra Marketplace
• Product, which must be integrated with configured external rater.
• Registered external rater integration name.

Follow these steps to complete the integration procedure

• Find a registered external rater’s name. To do this, admin needs to login into Socotra Tenant with administrative credentials. This will allow them to see all registered external rater integrations, under “Integrations” section, like on a screenshot below:

• Copy the name of external rater that needs to be integrated with a product and navigate to product configuration.
• Open Socotra Config Studio, login as an administrator.
• Select a specific product which we want to integrate with and open product settings.
• Add external rater name to the corresponding section of the product settings:

Save settings and deploy updated product configuration.

Integration is complete. Configured external rater now will be used for the specific products applications.