# Create a tenant configuration file
import Image from 'next/image';
This article explains how to **create a tenant configuration file** in the Socotra Insurance Suite.
Overview [#overview]
What will I learn? [#what-will-i-learn]
By the end of this tutorial, you will know:
* What a tenant configuration file is.
* What a tenant is.
* How to create a tenant configuration file from a template.
* How to navigate the Socotra web app to view and configure a tenant.
* How to add, modify, and remove data on the tenant configuration file.
What will I need? [#what-will-i-need]
You’ll need a set of credentials to log into your business account. To learn more about logging into your business account, see: [Log into Socotra](/getting-started/log-into-socotra)
Note about JSON [#note-about-json]
This article should give you a basic understanding of the data model of a tenant configuration file. There are two ways to create a tenant configuration file:
* Through the Socotra web app.
* Manually by writing JSON code.
This tutorial mostly focuses on how to use the Socotra web app, but manually writing JSON code is also a common method. We’ll show some examples of how the configuration is set up in JSON below.
**Don’t worry if you’re not comfortable with JSON just yet**. We’re going to focus on learning how to manipulate this data in the Socotra web app, but it’s useful to have a general idea of how things work behind the scenes for when you learn how to use the Socotra API.
**Tip**: When directly editing JSON code to make a tenant configuration in Socotra, remember this basic principle: There are several directories where you can define policy, billing, and other administrative settings, and it’s possible to link these settings together to make a valid tenant configuration and insurance product(s).
Also keep in mind that the example’s we’re going to cover aren’t the only way to set up a product in Socotra. Socotra is a highly configurable, flexible platform. These examples just show you the basics.
Now, let’s cover the basics of the Socotra data model by exploring what a tenant configuration file is.
Key concepts [#key-concepts]
What is a tenant configuration file? [#what-is-a-tenant-configuration-file]
In Socotra, a **tenant configuration file** defines one or more insurance products.
The tenant configuration file describes all aspects of the product, including exposures and coverages. It’s also where you define billing and administrative settings.
Once created and validated, tenant configuration files are deployed to *tenants*.
What is a tenant? [#what-is-a-tenant]
In Socotra, a **tenant** is a dedicated instance of the Socotra insurance policy administration system. Tenants allow you to isolate data related to insurance products in a highly customizable container. A business account can contain one or more tenants.
We’ll cover tenants in further detail later on in this learning path. For now, it’s enough that you’re familiar with the term.
Next, we'll cover how a tenant configuration file is generally structured.
How is a tenant configuration file structured? [#how-is-a-tenant-configuration-file-structured]
A tenant configuration file contains the settings for the administration of an insurance policy. The settings can be thought of as being subdivided into four categories:
* Global
* Policy
* Billing
* Resources
For right now, we'll start by focusing on the **Policy** category, which defines the structure of an *insurance product*.
What is an insurance product? [#what-is-an-insurance-product]
An **insurance product** is a data model composed of various elements that, when linked together, represent a product that can be used to create quotes and policies for *account holders*.
What is an account holder? [#what-is-an-account-holder]
An **account holder** is a third-party entity (a person or a business) who is capable of being quoted for and being issued a policy for an insurance product.
What is an element? [#what-is-an-element]
An **element** is a building block of an insurance product. Elements are data objects, and they have two required properties:
* category
* type
The **category** defines the kind of element. There are five valid categories:
* product
* policyLine
* exposureGroup
* exposure
* coverage
The **type** is a name that provides a human-readable description of the element.
**Note**: The type must start with a letter or underscore. It also cannot have the same name as a [reserved word/boolean value in the Java programming language](https://en.wikipedia.org/wiki/List_of_Java_keywords). See the [Configuration Deployment](/configuration/general-topics/deployment#configuration_element_name_length_limits) guide for more information on naming restrictions.
Visualizing an insurance product configuration [#visualizing-an-insurance-product-configuration]
The graphic below represents one possible configuration of an insurance product, using the **product**, **exposure**, and **coverage** elements.
In the graphic above:
* Each rectangle represents an **element**.
* Each element has two required properties:
* **category** (the kind of element)
* **type** (a name/description of the element)
* A **product** element is composed of (*contains*) one or more exposure elements.
* An **exposure** element contains one or more coverage elements.
* **Note**: An exposure represents the level of risk or vulnerability held by an individual or business. This is usually what is being insured.
How does this look represented in the JSON code? The annotated screenshots below show a configuration in Visual Studio Code, though you can use any text editor to read and edit JSON.
1. The **product** element “ho3” is located in the products directory.
1. The **category** of the product element is inferred by its placement in the *products* directory name.
2. The **type** of the product element is in the sub-directory name (*products > ho3*)
2. The `contents` array in config.json points to `dwelling`. This is the name of an exposure, as we’ll see in the screenshot below.
1. The exposures element “dwelling” is located in the exposures directory.
1. The category of the exposures element is inferred by its placement in the exposures directory.
2. The type of the exposures element is defined in the subdirectory (*exposures > dwelling*)
1. You could just as easily rename “dwelling” to “home”, and it would have the same functionality; the exposure type would now be “home”.
2. Be aware – when renaming in JSON, you must make sure to update all references to the old name as well.
2. The contents array in config.json likewise points to four coverages that we’ll see in the screenshot below.
1. The four **coverages** elements “coverage\_a”, “coverage\_b”, “personal\_property”, and “water\_backup” can be found in the coverages directory.
Ready to begin? [#ready-to-begin]
Continue onto the next section to learn how to create a tenant configuration file for an insurance product in Socotra.
Part 1 - Creating a configuration file [#part-1---creating-a-configuration-file]
First, you need to **create a configuration file**. There are broadly two ways to create a configuration file:
* Through the Socotra web app
* Manually by writing JSON code
We’re going to focus on creating the configuration through the Socotra web app, but we’ll cover how to directly edit the code later on in this learning path.
Socotra provides a template configuration file of a few mock insurance products. During this tutorial, you’ll use the template to learn more about navigating and modifying a configuration file.
Follow the steps below to create a configuration file from a template in Socotra.
1. Log into the Socotra web app.
1. For more information, see: [Log in to Socotra](/getting-started/log-into-socotra).
2. Click **Configurations** (either in the top-left corner of the screen or in the center of the page).
3. On the Config Files page, click **Add New**.
4. The **Add New** window will appear. This is where we can create a new configuration file. There are three options you an choose from:
1. Start from Template (an example insurance configuration with some data pre-populated).
2. Start from Blank (a bare-bones insurance product with very little configuration).
3. Upload (allows you to upload an insurance product file you’ve pre-configured).
5. For the purpose of this tutorial, **make sure to select Start From Template**.
6. Provide a name for your configuration.
1. We recommend naming your configuration something easily identifiable and associated with the type of insurance product it represents.
2. For this tutorial, we’ll simply call it `my_example_config`.
7. When you're satisfied with your configuration name, click **Confirm**.
8. If successful, a message will appear saying the configuration was successfully added.
Congratulations! You’ve successfully created your first tenant configuration file in Socotra.
Continue onto the next part to learn the basics of configuring it.
Part 2 - Basic editing of the tenant configuration file [#part-2---basic-editing-of-the-tenant-configuration-file]
In Part 1, you learned how to create a configuration file from a template.
In Part 2, you’ll learn how to make basic edits to the tenant configuration file.
View the configuration file [#view-the-configuration-file]
1. In the Config Files list, locate the configuration file you created in Part 1.
2. Click **Edit**.
Once you click **Edit**, you’ll be taken to the config mapping page. This is where you can edit your tenant configuration.
Concept - Attributes [#concept---attributes]
Remember that the configuration file is the definition of one or more insurance product(s).
On the left and center of the screen, you should see four categories. These are called **attribute categories**.
An **attribute category** is a logical grouping of attributes of your tenant configuration.
An **attribute** is a piece of data used to configure your insurance product. Attributes allow you to customize the specifics of a product, including the policy and billing.
There are dozens of nested attributes that make up an tenant configuration, but they broadly fall into four categories:
* Global
* Policy
* Billing
* Resources
We’ll briefly cover each of these categories in the table below. We’ll go further in depth on the data model of Socotra in later tutorials.
| Category | Description | Sub-items |
| --------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Global | Global attributes apply to the entirety of the tenant configuration. | Custom Data Types, Accounts, Defaults, Global Plugins, Aux Data, Custom Events |
| Policy | Policy attributes are configurations for the issuance and administration of any insurance policies. | Products, Attributes, Coverage Terms, Charges, Transaction Types, Auto-Renewal Plans |
| Billing | Billing attributes are configurations for the collection and disbursement of funds. | Billing Plans, Installment Plans, Delinquency Plans, Payments, Disbursements, Shortfall Tolerance Plans |
| Resources | Resources contain data and document generation tools. | Constraint Tables, Tables, Documents |
For right now, we’re going to focus on **Defaults** (under Global). Continue reading the section below to learn about default attributes.
Concept - Default attributes [#concept---default-attributes]
In the context of your tenant configuration, a **default attribute** is an attribute in the “Global” category that sets the standard behavior of your products. Default attributes can be overwritten by more specific attribute settings.
For example, even though default attributes might set a default currency, if you want a specific insurance product to have a different currency, you can configure that product in particular to have a different currency from the default.
Default attributes make it easy to have consistent behaviors across all products, while giving you the flexibility to make changes to specific products.
See the table below for a quick reference of each of the default attributes.
| Default attribute | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Time zone | Defines the default time zone of the tenant |
| Currency | A three-letter currency code that represents the currency used when creating a quote. |
| Installment plan | Points to an installment plan configuration. An installment plan informs the billing system on how to divide the charges for a transaction into installments, which are then used to construct invoices. |
| Term duration | Defines a numerical value to represent a length of time. This attribute is used alongside the Duration basis attribute. This value must be a positive integer greater than or equal to 1. For example, if you want a term to be six months, set *Term duration* to **6** and *Duration basis* to **Months**. |
| Duration basis | Defines a unit of time for measuring the length of a term. Options include: `Hours`, `Days`, `Whole Days`, `None`, `Weeks`, `Months`, `MonthE360` (months based on a 360-day calendar), `Years`. For example, if you want a term to be six months, set *Term duration* to **6** and *Duration basis* to **Months**. |
| Shortfall tolerance plan | Points to a shortfall tolerance plan configuration. A shortfall tolerance plan determines the threshold allowed for payment deficits without penalties or disruptions. A default shortfall tolerance plan can be configured for your tenant as well as for each product. Any plan can additionally be assigned to a quote upon creation. |
| Auto renewal plan | Points to an auto renewal plan configuration. Auto-renewal plans inform the system on how policies should be managed as they approach expiration. A default auto-renewal plan can be configured for your tenant as well as for each product. Any plan can additionally be assigned to a quote upon creation. |
| Billing plan | Points to a billing plan configuration. A billing plan instructs the system on how to generate invoices. In particular, it defines at what state (acceptance or issuance) that an invoice would be generated for a policy. |
| Delinquency plan | Points to a delinquency plan configuration. A delinquency plan instructs the system on how to handle invoices that go unpaid post their due date. |
| Aux Data Settings | The Aux Data setting determines the default length of time until an aux data entry will expire. A different setting/expiration can be used when creating a new aux data entry, however if no setting/expiration is included when creating a new aux data entry, it will use the default setting. |
Edit the default attributes [#edit-the-default-attributes]
In this subsection, you’ll learn how to edit default attributes for your tenant configuration.
Let’s try changing the duration of any policy created using this config. Remember that changing policy duration requires changing two settings:
* Term duration (the amount of time)
* Term basis (the unit of time)
So, let’s suppose we want a policy to last **6 months**.
1. In the **Term Duration** field, type **6**.
2. In the **Duration Basis** dropdown, select **Months**.
You may have noticed that, after editing these fields, a **required** message appears under the Shortfall tolerance plan field. Continue onto the next subsection to learn more.
Concept - Attribute types [#concept---attribute-types]
The Shortfall Tolerance Plan field might be showing as required when you try to alter some of the other settings in Defaults, preventing you from saving any changes.
The reason why this is occurring is because **every default attribute field needs to have a value**.
There are essentially two types of attributes:
* Simple attributes
* Complex attributes
A **simple attribute** is an attribute that only consists of one setting. Examples of simple attributes include currency, term duration, and duration basis. These all have predefined values you can select from, or are otherwise simple enough that they only accept an integer value.
A **complex attribute** is a more advanced configuration. Remember that the default attributes set default settings for your insurance product. So, some of the default attributes point to configurations about a certain aspect of an insurance product.
The configuration file comes with default values you can select from. To select a value for this field, click the dropdown and select a value.
When you make any change to the default values, a dialog box will appear at the top of the screen to indicate that your changes have been automatically saved.
We’ve learned about the basics of configuration files, including their attributes and how to make basic changes. In the next section, we’ll cover how to make more advanced changes to a configuration file.
Part 3 - Advanced editing of the tenant configuration file [#part-3---advanced-editing-of-the-tenant-configuration-file]
In Part 2, you learned about attributes in the configuration file, including how to set default attributes and create new attributes.
In Part 3, you’ll learn how to make more substantive changes to an insurance product.
View the Products menu [#view-the-products-menu]
Start by viewing the Product menu. This is where individual insurance products are defined.
1. In the left sidebar, navigate to **Policy > Products > Ho3**.
2. You should now be viewing the Ho3 (homeowner) product.
| Tab | Description |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Eligible Account Types | Where you choose which account types are eligible for the quotes and policies that will be created based on this product. Account types are created in *Global > Accounts*. |
| Contents | Where you create hierarchical associations between elements. An element can refer to a policy line, exposure group, exposure, or coverage. These elements can have hierarchical relationships with each other. For example, an exposure contains one or more coverages. While you define all of the attributes in the Attributes menu (*Policy > Elements*), the relationship between the elements is defined in the Contents tab. (*Products > \[Selected Product] > Contents*). |
| Charges | Where you choose which charges are associated with the product. Charges are defined in the Charges menu (*Policy > Charges*). |
| Coverage Terms | Where you configure coverage terms. Coverage terms handle configurations related to: deductibles, limits (split limits, aggregate limits, lifetime limits, etc.), benefits ((like benefits for term life payouts), and riders ((like optional inclusion of additional coverage that doesn’t need a full Coverage attribute). |
| Data | Where you can create any custom data you want associated with the insurance product. If a data value isn’t captured in one of the default menus, you can create a custom value in the Data tab. This is also where you can see all of the fields that are inherited from other entities. |
| Static Data | Where you can create custom data that you don’t want to be governed by the data revision rules of policy transactions. You can add or update data here even after a quote has become finalized and immutable. A maximum of 10 static data fields can be added per product. |
| Plugins | Where you manage product-specific plugins. These will overwrite any matching instances within Global Plugins for this product. |
| Documents | Where you manage documents that are generated for this insurance product. Documents are declared and stored on the Documents page (*Resources > Documents*). |
| Settings | Where you can overwrite any default attributes. |
Making changes to the product [#making-changes-to-the-product]
In this section, we’ll cover how to add a new data field to a product.
For the purposes of this tutorial, you’re going to add a field that records the number of prior fraud convictions held by the customer.
1. While viewing your tenant configuration, navigate to **Policy > Products > Personal Auto**. Then, click the **Data** tab.
2. Click **Add New**.
After you click **Add New**, a flyout window will appear.
3. Fill out the **Name** field.
1. This should typically:
1. Be description of the information the field is capturing.
2. Be in `camelCase` or `PascalCase`.
2. For this tutorial, we recommend providing the value `priorFraudConvictions` as the name.
4. Fill out the **Display Name** field.
1. This should typically be based on the **Name** field.
2. For this tutorial, we recommend providing the value `Prior Fraud Convictions` as the display name.
5. Select a value for the **Type** field.
1. The type is the kind of data captured by the field.
2. Examples include string (text), int (integer), etc.
3. For this tutorial, we recommend selecting **string**.
6. Select a value for the **Quantifier** field.
1. This sets whether the field must be provided when making a quote with this insurance product.
2. For this tutorial, we recommend selecting **Optional (?)**.
7. Select a value for the **Scope** field.
1. This sets whether this data is used for generating quick quotes, quotes, or both policies and quotes.
2. For this tutorial, we recommend selecting **Policy + Quote**.
8. For the purposes of this tutorial, we can ignore the **Tags**, **Default value**, **Min length**, **Max length**, and **Regex** fields. We’ll cover these in future learning resources.
9. For the **Options** field, click **Add**.
1. This is where you can add selectable options to represent how many fraud convictions the customer has.
2. Enter “0” for the first value. Then, click **Add** again.
3. Repeat this process to add options 0, 1, 2, and 3+.
10. Review the screenshots below and compare it to what you have configured. If something doesn’t match up, review these steps.
The Add new field flyout window (part 1)
The Add new field flyout window (part 2)
11. Click **Create**.
After clicking Create, the new data field should appear in the list of fields.
Recap [#recap]
In this tutorial, we covered:
* How to create a configuration file from a template.
* How to view and edit the basic settings of a configuration file.
* How to navigate the Products menu.
* How to add new data to configure the product.
Now that we have a configuration representing insurance products, how do we put it into action? The next step is to deploy the configuration file to a tenant. But what is a tenant?
Ready for the next module? [#ready-for-the-next-module]
See [Overview - Tenants](/getting-started/overview-tenants) to continue this learning path.