Configuration Walkthrough

The Socotra Configuration

Socotra configurations are defined using files, mostly JSON, organized in a pre-defined folder structure. The Socotra application loads this folder structure to get settings and product definitions. The top-level of the folder structure is as follows. All these items are required, and can be seen in the pre-loaded configuration in Socotra Configuration Studio.

Socotra Configuration File/Folder Structure

  • payment/

  • policyholder/

  • products/

  • security/

  • scripts/

  • config.json

Product Lines

Configuration for a given product is stored in a folder under the products/ folder. The name of this folder determines the name of the product as it appears in the application. Capitalization and spaces are handled automatically. For example, the product defined in a folder named “my-product” will display as “My Product” in the application interface.

Product names cannot contain emojis or the following characters:

$, @, =, ;, /, \\, :, +, ,, {, }, ^, %, `, [, ], >, <, ~, #, *, ?, |

These non-alphanumeric characters are allowed:

-, _, . , (, ), !, ', ", &

Product File/Folder Structure

  • products/

    • [myProductName]/

      • perms.json

      • policy/


The perms.json file is obsolete and can be ignored if it is found in your configuration.


At the policy level, Socotra allows the user to define the data to collect about the policy, as well as document templates and rate tables to be used in premium calculation.

Policy File/Folder Structure

  • policy/

    • policy.json

    • fees.json

    • policy.calculations.liquid

    • schedule.template.liquid (filename user-defined)

    • invoice.template.liquid (filename system-defined)

    • tables/

    • exposures/

    • taxes/


Though the placement of tables in a config might suggest that tables are scoped at the product level, they are actually scoped at the tenant level. We recommend that each table have a unique name to avoid unexpected lookup results. One common technique is to preface each table with the product name.


Policy.json defines what data will be collected about the policy contract itself, as well as what documents will be created upon issuance. The Fields array may contain a list of field definitions, as discussed here.


  "fields": [],
  "documents": [
      "displayName": "Name to appear in the UI",
      "fileName": "filename.pdf",
      "templateName": "name of the template file in the Policy folder"

fees.json and policy.calculations.liquid

See Fees


Exposures consist of an exposure definition file as well as a folder outlining the perils and limits defined for this product line on this exposure type.

Exposure File/Folder Structure

  • exposures/

    • [myExposureName]/

      • exposure.json

      • perils/


This defines the data to collect about the asset or person being insured, as well as what label to show in the UI. Fields are discussed here.


  "name": "exposure_identifier",
  "displayName": "Exposure name to display in the application",
  "fields": []


The perils folder contains a definition of the coverage available for the exposure type in question in this product line. A variety of covered perils and limits can be predefined, or a generic peril can be created so the agent or underwriter can specify it on the fly. Limits of indemnity, deductibles, and/or fixed benefits may be defined.

Peril File/Folder Structure

  • perils/

    • [myPerilName1].json

    • [myPerilName1].premium.liquid

    • [myPerilNameN].json

    • [myPerilNameN].premium.liquid


Each JSON file in this folder names the peril being covered and the limits on that peril. To force a limit to take a particular value, define it here. Otherwise, leave it absent and the user will be prompted to enter it during the application/underwriting process.


  "name": "peril_identifier",
  "displayName": "Peril name to display in the application",
  "fields": [],
  "indemnityPerItem": "unlimited",
  "indemnityPerEvent": "unlimited",
  "indemnityInAggregate": "30000000",
  "deductible": "500000",
  "lumpSumPayment": "0"


See Premiums


Socotra generates policy documents when the application is finalized. Which documents are generated is determined by the documents block in policy.json, and the content of those documents is determined by a template written in a syntax called Liquid. See Document Templates for details.

Example: policy.json

  "documents": [
      "displayName": "Policy Schedule",
      "fileName": "schedule.pdf",
      "templateName": "schedule.template.liquid"
      "displayName": "Policy Schedule Email",
      "fileName": "schedule_email.html",
      "templateName": "schedule.template.liquid",
      "type": "html"

Taxes and Fees

See Taxes and Fees