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.
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.
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:
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.
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.
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:
"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:
Save settings and deploy updated product configuration.
Integration is complete. Configured external rater now will be used for the specific products applications.