Getting Started Guide

Socotra’s philosophy is that software platforms should be understandable and configurable by anyone. In this guide, we present several exercises and examples which anyone can follow to discover how easy Socotra is to configure.

If you would like to try Socotra but don’t have an evaluation account, please contact us at

Please direct questions about this guide to


Tutorial 1.1: Set Up

Log in to Socotra Configuration Studio. Your username and password were emailed to you by Socotra Support (

Configuration studio comes pre-loaded with example auto and term-life products. You can use the editor to add details of your insurance product (for example, policy fields, rating values, forms, documents, etc.)

When you are ready to deploy changes and create your Socotra test instance, click the Deploy link at the right side of the screen.

Tutorial 1.2: Log into your test instance

After you’ve deployed your configuration, you’ll need a username and password in order to access Socotra. (Note, this is different than the credentials you just used to configure your system.)

To see how this works, click General Settings, and then the Test Users tab. The data you see there seeds your test Socotra instance with initial users; they can also be created later using Socotra’s administration tools, which is the method for production environments.

You will see that the pre-loaded configuration json has a fictitious user, “Alice Lee,” with username “alice.lee” and password “socotra”.

After deploying, click Go to Instance on the right side of the screen to log into your test instance:


Product Configuration

Tutorial 2.1: Vehicle Color

The included configuration includes a simplified “toy” auto insurance product called “simple-auto.” Within your Socotra instance (not the configuration studio), first create a policyholder, using whatever names, date of birth, etc. that you choose. Then, from the policyholder screen, click Start New Application and then select Simple Auto.

Now, let’s go back to Configuration Studio and add a select widget for the vehicle color on the Vehicle Exposure. An exposure in Socotra is the item that is to be covered - in this case the vehicle.

There is only one update needed in order to do this. In configuration studio, navigate to:

> Home > Simple Auto (under Products) > Vehicle (under Exposures) > Fields

Add a new field by clicking the Add New button. Enter the following attributes:

  • For Title, enter “Vehicle Color”

  • For Name, enter “vehicle_color”

  • For Type, choose “Select”

Click Create Field and you will go back to the field list, and you’ll see your new Vehicle Color field at the end of the list. Click it to get to more settings.

You’ll want to enter new color options in the Values section. In the Values textbox, enter “Blue”. Then click Add New Value and enter Green in the next box. Continue with each of “Red”, “Yellow”, “Black”, and “White”.

Confirm your change by clicking Validate and then click Deploy (see Tutorial 1.1). Then go back to Socotra to see if your changes were successful: Click on the first exposure in the list (“Vehicle”) in the Policy Details section, and you should see a dropdown for Vehicle Color in the Exposure Details section.


Where you place the property in the list determines its relative location on the page in the Socotra UI. You can change the order by dragging fields up and down in configuration studio.

The Simple Auto Policy - Exposure UI should look like something like this after you complete this exercise:



Tutorial 3.1: Rates Update

Let’s say that your actuary stopped by your desk to say that in her analysis, the risk profile for motorcycles has increased, and our premium rates are too low. We’ll modify the rates table to charge additional premium for motorcycles.

To make this change we need to update the rates table. Navigate to:

> Home > Simple Auto > Tables

There is only one table defined for this product, and you should see it displayed in a spreadsheet-like format with columns key and value.

For the premium calculation formula, we are currently charging a “base rate” of 3.7% of the vehicle value. That base rate is multiplied by a rate table factor that is based on the vehicle type. If you’re curious, the premium calculation for a the peril “Third Party Liability” is viewable in the calculation file at:

> Home > Simple Auto > Vehicle > Perils (third_party_liability) > Premium

For now though, go back to the rate table you just viewed.

Notice the additional rate being charged for Motorcycles. The current value is “2” which means it is twice the base rate. You’ll see that a “Car” is only being charged 1x the base rate, i.e., no additional charge, since it has a lower risk profile. Increase the Motorcycle rate value to “2.5”:

Confirm your change and click Deploy Configuration. Then login to Socotra (by clicking Go to Instance.)

Testing your rating change

To see if your change was successful, try creating a new policy to see what Socotra calculates for the premium for a Motorcycle with a value of $10,000 that is sold “Direct.”

Your new rate calculation should be as follows:


Tutorial 3.2: Discount Increase

Your marketing team has decided to provide a larger discount to customers purchasing policies directly for Third Party Liability (“TPL”) coverage. You need to update your TPL premium formula to reflect the revised VAT rate. Your pricing formula is in:

> Home > Simple Auto > Vehicle > Perils (third_party_liability) > Premium

Open the pricing formula file. On Line 8, you can see how the discount being provided to customers that purchase directly is 10% (since it’s a factor of 0.9). Increase the discount to 20% by changing the factor to 0.8. Confirm your change and click Deploy. Then login to Socotra to see if your change was successful.

If you need a reference, see an example here.

Testing your discount adjustment

To see if your change was successful, try creating a new policy to see what Socotra calculates for the premium for a Motorcycle with a value of $10,000 that is sold “Direct.”

Your new rates calculation after you complete Tutorial 3.1 and 3.2:



Tutorial 4.1: Policy Schedule Update

In Tutorial 2.1, we added “Vehicle Color” to the workflow. Now let’s add “Vehicle Color” to the Policy Schedule document. Open the Policy Schedule file at:

> Home > Simple Auto > Documents > schedule

After the line related to Vehicle Make, Model, and Year (Line 45) add the following configuration as Line 46:

<b>Vehicle Color:</b> {{exp_v.vehicle_color}} <br>

Confirm your change and click Deploy Then login to Socotra to see if your change was successful. Follow these steps:
  1. Create a new Simple Auto policy

  2. Create an Exposure

  3. Select Price

  4. Select Finalize

  5. Download the Policy Schedule document


In Socotra, finalizing a policy locks in the price. It also generates invoices and related documents for the policy.

If you need a reference, see an example here.

The Simple Auto Policy Schedule should look like this after you complete this exercise. Notice the “Vehicle Color” line after Vehicle License Plate Number:



Tutorial 5.1: On Risk Report


The following report will show empty values if no policies have been issued in your instance of Socotra. In order to issue a policy, navigate to the policy and choose “Issue Policy” from the list of drop-down options in the top right corner.


Socotra allows you to run reports. Let’s create a report to understand what coverage is on risk. Select the Socotra logo in the top left corner to return to the home screen and click Run Report.


Select the “On-Risk Report” on the next page:


Select the Products you wish to export data on and choose an as-of date.


The “As-of Date” should be at least one day ahead of the effective start date of your first policy. Socotra runs reports as of 00:00:00 on that date, and as of that time, the policy did not exist.


After you run the report, you should see the policies you have previously created. You can also export the results to CSV.