File and folder structure

Navigate your local product module folder with confidence

Overview

This guide will introduce you to the different files and folders you will find within your product module folder when you clone a product module from Root (or from GitHub). To clone your first product module, follow the workbench onboarding tutorial.

.root-config.json

This config file represents your product module's basic setup and settings.

PropertyDefinition
configVersionString. This is the version of your config file, which is associated with the version of your local Workbench CLI tool installation.

You can update your config file to the latest version by running npm install -g @rootplatform/cli, and then pulling only the config file from Root by running rp pull --config. Note: This will overwrite your local config file with the latest draft version from Root.
productModuleNameString. The name of your product module.
productModuleKeyString. The unique key used to identify your product module across Root.

To create a quote using your product module, you need to pass the product module key as the type parameter in your request to the quote endpoint.
organizationIdString. The UUID of the organisation that owns the product module.
hostString. For most product modules, this is "api.rootplatform.com". If you have questions about this property, please contact support at [email protected].
codeFileOrderArray. Specifies the order in which your product module code files will run. See the code section.
settingsObject. The general and billing settings for your product are specified here. Read more in the settings guide.
alterationHooksArray. This property lists the alteration hooks that are enabled for your product module, each with its own name and key. Read more in the alteration hooks guide.
scheduledFunctionsArray. This property lists the scheduled functions that platform will execute for policies issued under this product module. Read more in the scheduled functions guide.
fulfillmentTypesArray. A fulfillment type serves as a template for fulfillment requests. Read more in the disbursement blocks guide.

.root-auth

This file contains your API key, which authorises you to pull and push product module changes to Root. Your API key needs to be included in this file as follows:

ROOT_API_KEY=<your API Key>

When you clone a product module from Root to your local machine, this file will automatically be included in the folder.

However, if you are cloning a product module from GitHub, this file will not be included, as it is listed in the .gitignore file, which tells git to ignore it. In this case, you will need to create the file yourself and add a valid sandbox or production API key created under the organisation that owns the product module.

README.md

You can add a README file to a product module to communicate important information about the project. This file can contain information such as:

  • What the product is
  • Who the client, underwriting insurer and IP owner are
  • Links to any related files on Google Drive
  • Who maintains and contributes to the project
  • What are the outstanding tasks still to complete in this module

code

📘

Type checking in JavaScript

By default, we add a VS Code setting to your product module code directory to enable type checking. This allows you to leverage some of TypeScript's advanced type checking and error reporting functionality in regular JavaScript files - a great way to catch common programming mistakes.

These type checks use the type declaration files included under code > types and code > unit-tests > types.

To turn off type checking, open the relevant jsconfig.json file and set compilerOptions.checkJs to false.

This file contains your product module code. You can read more about how to configure your product module using product module code in the product module code guide.

The product module code consists of multiple JavaScript files. When the product module code is executed, these files are concatenated by the platform, in the order specified in the .root-config.json file, under the codeFileOrder property.

Note: Since these files are concatenated, you do not need any import or require statements to import functions or variables from one file to another. Instead, you can add code to these files as if they are a single, long file.

📘

Split product module code into separate files

You can use the product module code files to organise your code into logical sections. For example, you can include the code for each hook in a separate file, with a further file for helper functions.

You are free to add or remove code files to suit your requirements.

docs

This file contains the product specific API reference for your product module. This is used to document the product-specific endpoints that you have configured for your product, to facilitate external integrations with your product on Root.

This file will typically document at least the quote hook and the application hook for your product module. You can also use this file to document your products claims blocks and alteration hooks, depending on whether any external integrations depend on these features.

Read more about how to configure the API documentation for your product module in the API docs guide (work-in-progress).

documents

This folder contains the HTML templates for your policy documents, such as the policy schedule and welcome letter. All policy documents are configured in HTML, except for the terms file which is a flat PDF file.

You can add supplementary terms files in documents > supplementary-terms. Each supplementary terms file must be a PDF document. The filename (without the extension) of each supplementary terms file will be used as the supplementary terms file type.

Read more about building HTML document templates for your product module in the policy documents guide.

workflows

The files in this folder allow you to configure selected user workflows on the Root management dashboard. Not all of these workflows are required for all product modules. For example, if your product uses an external front end to issue policies, you will not need to configure the quote and application schemas for your product module.

You can use quote-schema.json and application-schema.json to configure the quote and application input forms for your product, which will be rendered on the Root management dashboard as part of the policy issuing workflow. These schemas are not required if you use an external front end to issue policies. See the Schemas guide for details on how to configure these schemas. Read more about the quote and application hooks in the quote hook and application hook guides.

The alteration-hooks folder will contain the alteration schemas (if any) for your product. These schemas will only be relevant if you have defined alteration hooks. The names of the files will depend on the alteration hook keys. Empty files with the correct filenames will be generated automatically by the Workbench CLI tool when you clone or pull a product module with alteration hooks defined. These schemas are configured in the same way as the quote and application schemas - see the schemas guide for details.

claims-blocks.json is used to configure the claims blocks for your product module. Nearly all products will require claims blocks, as this is a requirement for enabling the claims workflow on Root. See the claims blocks overview guide for more details on how claims blocks fit into the claims workflow and how to configure them.

The file embed-config.json is used to configure the Embed flow for your product module. This is an optional feature for adding a white-labelled, self-service onboarding flow and policy management solution to your existing digital customer journey. See the Embed guide for details on how to configure and implement Embed.

sandbox

This folder is used for testing policy documents PDFs generated from HTML templates. Read more about using the rp render command to test your policy document templates in the workbench commands guide.

Changes to this folder do not result in any changes to your product module configuration on Root.

Other files and folders

The .gitignore file is only relevant if you use GitHub to collaborate with others on a product module. This file ensures that your secret API key is not uploaded to GitHub.

The .vscode folder is used by VS Code's IntelliSense feature to generate Root-specific code snippets.