This guide covers the full feature suite of the Workbench CLI tool. To set up the Workbench CLI tool, follow the Workbench setup tutorial first. To learn more about the configurability of product modules and workflows on Root, refer to the Product modules & workflows guide section.

Commands

rp create [api key] [product module name] [product module key]

Creates a new blank starter template product module on Root, and enables it for the organisation linked to your API key. The new product module is automatically cloned to a new directory on your local machine (see rp clone). Note: Product module keys must be unique across all organisations on Root.

Use cd to navigate into the new directory in order to make changes to your new product module.

Optional: -h or --host flag

Defaults to https://api.rootplatform.com/. This optional flag will determine the host from where the product module will be created. To ensure you reference the correct domain, please refer to the domains section of the API reference.

Example

Below is an example of creating a product module and navigating into the new directory.

$ rp create sandbox_GDIwZGYxg5LTgMTE4YzWkhhKZV5xdVLZENTNt "Pet Insurance" pet_insurance -h https://api.uk.rootplatform.com/
Product module 'pet_insurance' successfully created on the Root Platform
Product module 'pet_insurance' successfully cloned into './pet_insurance' directory.
$ cd pet_insurance

rp clone [api key] [product module key]

This command creates a new directory and clones the latest draft version of your product module from Root to your local machine for local editing. This command is only used once for the initial setup of your product module on your local machine.

Use cd to navigate into the new directory in order to use the other commands.

Optional: -h or --host flag

Defaults to https://api.rootplatform.com/. This optional flag will determine the host from where the product module will be cloned. To ensure you reference the correct domain, please refer to the domains section of the API reference.

Example

Below is an example of cloning a product module and navigating into the new directory. After this step is completed, all the other rp commands can be used.

$ rp clone sandbox_NDIwZGYxg5LTgMTE4YzWkhhKZV5xdVLZENTNt dinosure -h https://api.uk.rootplatform.com/
Product module 'dinosure' successfully cloned into './dinosure' directory.
$ cd dinosure

rp pull

This command pulls all files and configurations of your product module from Root and overrides the local files. By default, this command pulls the latest draft version, not the live version.

Optional: -f or --force flag

Use the -f or --force flag to ignore the diff check and force the pull.

Warning: this overrides _all local files to match the version on Root exactly._

Optional: -l or --live flag

This optional flag will pull the live version from Root.

Optional: -ns or --no-sort flag

By default, the CLI tool will attempt to sort the keys of incoming JSON objects to match the key order of corresponding local JSON objects. You can choose to skip sorting of object keys and write them in the same order received from the Root platform by including this flag.

Example

$ rp pull
No changes to pull, local version is in sync with Root

rp push

This command pushes all the local files and configurations to Root which create a new draft version of the product module on the platform.

You can issue policies from a draft version over the API or on the dashboard in Sandbox. To deploy the draft version to live, please contact the Root team (they will review your changes and action the deploy).

Optional: -f or --force flag

Use the -f or --force flag to ignore the diff check and force the push.

Optional: -ns or --no-sort flag

By default, the CLI tool will attempt to sort the keys of incoming JSON objects to match the key order of corresponding local JSON objects. You can choose to skip sorting of object keys and write them in the same order received from the Root platform by including this flag.

Example

$ rp push
No changes to push, local version is in sync with Root

rp publish

This command publishes the current draft version to live. As a result, all policies that were previously issued based on the live version will now reference the newly published version.

Optional: -f or --force flag

Use the -f or --force flag to ignore the confirmation step and force the publish

rp render

This command renders the document templates locally in the ./sandbox/output directory. It compiles a PDF file for each valid HTML document in the ./documents directory.

👍

Productivity tip

For best use during active document development, use all three the -m, -p <policy-id> and -w flags simultaneously in order to generate new documents every time changes are saved. Open the document using Preview on Mac and it will automatically refresh. This results in a real-time view of the end-result.

Optional: -m or --merge flag

Use the -m or --merge flags to execute the handlebars and merge in the merge variables located in /sandbox/merge-vars.json.

Optional: -p <policy id> or --policy-id <policy id> flag

Supply an ID for an existing sandbox policy ID with the -p or --policy-id option to fetch the corresponding merge variables. This will be ignored if the merge flag is set to false.

Optional: -w or --watch flag

Use the watch flag to enable live-reload that will re-render all the documents every time any of the template or merge-var files are saved.

Example

$ rp render -m -w
Documents successfully generated in the './sandbox' directory with merge-vars injected.
Watching for template or merge-var changes to re-render documents.

rp test

This command will run any tests specified in code > unit-tests locally. Any files ending in .js in this directory will be appended to the product module code files, after which the tests will be executed and test results returned in the console.

The test suite relies on Mocha & Chai for tests.

• Introduction to testing
• Comprehensive guide of Mocha + Chai

👍

Productivity tip

For best use during active code development, use the -w flag to rerun the test suite every time changes are saved. This allows rapid feedback and encourages writing more tests.

Optional: -w or --watch flag

Use the watch flag to enable live-reload of the test suite when changes to either the code or test files are saved.

Example

$ rp test -w rp test -w
Started test suite.


  getQuote
    ✓ should return an integer suggested premium
    ✓ should return a suggested premium of R115.17 (in cents)


  2 passing (8ms)

Completed test suite.
Watching for code or test file changes.

rp lint

This command will run eslint on the product module code.

Optional: -f or --fix flag

Use the -f or --fix flag to automatically apply the eslint fixes to the product module code.

rp logs

This command displays the recent sandbox execution logs for the product module.

Optional: -c or --count flag

Use the count option to specify the number of code runs to fetch logs for.

Optional: -f or --function-name flag

Use the function-name option to specify a function name to filter the code runs. For example, validateQuoteRequest.

Optional: -p or --policy-id flag

Use the policy-id option to filter code runs by a specific policy id.

Optional: -s or --status flag

Use the status flag to specify a status to filer the code runs

Example

$ rp logs
2023-04-14T05:44:28.281Z [complete] validateQuoteRequest
No logs

2023-04-14T05:44:30.071Z [failed] getQuote
2023-04-14T05:44:32.683Z [error] Product module code execution terminated due to a code error.
2023-04-14T05:44:32.680Z [error] Error: "Expecting value: line 1 column 1 (char 0)"
2023-04-14T05:44:32.675Z [debug] {
  nominated_start_date: '2023-04-05',
  name: { title: 'mr', first_name: 'John', last_name: 'Doe' },
  gender: 'M',
  date_of_birth: '1990-01-01',
  occupation_type: 'employed'
 }
2023-04-14T05:46:56.864Z [failed] validateQuoteRequest
2023-04-14T05:46:58.571Z [error] Product module code execution terminated due to a code error.
2023-04-14T05:46:58.568Z [error] Validation failed

rp generate

This command generates workflow schemas, payloads and API Docs based on the Joi validation in the product module code. It saves the schemas and API Docs in the ./sandbox directory and creates payloads in the /payloads directory.

Optional: -w <step> or --workflow <step>

You can use the optional -w or --workflow flag to specify the workflow step for which you want to generate the schema. Currently, the supported steps are quote, application and alterations, which correspond to the quote, application and alteration workflows, respectively. The command will generate the workflow schema for the quote hook, application hook or alteration hooks, depending on the specified step.

Optional: -p <step> or --payload <step>

You can use the optional -p or --payload flag to specify the workflow step for which you want to generate the payload. The command will generate the payload for the quote hook, application hook or alteration hooks, depending on the specified step.

Optional: -ad or --api-docs

You can use the optional -ad or --api-docs to generate the API reference for the quote and application step. The command will generate the API reference for the quote hook and application hook .

Example

To use this command, you need to refactor the validateQuoteRequest and / or validateApplicationRequest function to create the quoteSchema or applicationSchema variables, respectively. The example below is for the application step.

const applicationSchema = Joi.object().keys({
  // The Joi validation schema can be completed here
})

const validateApplicationRequest = (data, policyholder, quote_package) => {
  const validationResult = Joi.validate(
    data,
    applicationSchema.required()
  );
  return validationResult;
}

📘

Defining the Joi schema

To correctly define Joi objects and ensure the accurate generation of components from Joi, please refer to the Schema components documentation.

By following these steps, you will be able to generate the expected output for the application step automatically, as shown below.

Workflow Schema

To generate the workflow schema for the quote hook or alteration hook, simply replace the word "application" with "quote" or "alterations" respectively.

$ rp generate -w application
Schemas successfully generated in the './sandbox' directory

Payloads

To generate the payload for the quote hook hook, simply replace the word "application" with "quote".

$ rp generate -p application
Payloads successfully generated in the 'payloads' directory 

API Docs

To generate the API docs the following command will create the skeleton for both the quote and application steps.

$ rp generate -ad
API docs successfully generated in the './sandbox' directory 

rp invoke

With this command you can quickly create a quote, application and/or policy in sandbox mode on Root. By default, the command completes all steps required to issue a policy (quote, policyholder, application and issue policy). Upon success, a link will be provided to view the policy on the Root dashboard.

To use this feature, you need to include quote and application payloads in the ./payloads directory. These payloads represent the body of the API request that will be sent to the relevant Root endpoint. The payload files need to be named quote.json and application.json, respectively.

An example is provided below for the quote.json file.

{
  "type": "dinosure_demo",
  "cover_amount": 10000000,
  "cardio_fitness_level": "couch_potato",
  "age": 40,
  "smoker": false,
  "early_warning_network_benefit": true,
  "extraction_benefit": true
}

By default, the command will use the latest draft version of the product module to issue a policy. The policyholder will be created automatically based on the policyholder type allowed, as defined in the .root-config.json file.

Optional: -q or --quote flag

Create only a quote and display the quote package in the terminal.

Optional: -a or --application flag

Create a quote and an application and display the application in the terminal.

Optional: -c or --claim flag

Create a policy and open a related claim.

Optional: -l or --live flag

Use the live version of the product module.

Optional: -v or --verbose flag

Display the quote, application and policy objects created during the policy issue flow.

Example

$ rp invoke --claim
Claim opened successfully! Click here to view on dashboard.

rp diff

This command allows you to see line-by-line changes in your local product module definition, compared to the latest draft, in the command line interface.

Optional: -c or --code

This option allows you to view the changes made to code files specifically.

Optional: -ut or --unit-tests

This option allows you to view the changes made to unit tests specifically.

Example

$ rp diff -c                                                                 

Code files in ./code

--- main.js
+++ main.js
@@ -7,316 +7,316 @@
  ***************
  */
 
 const dateOfBirthFromID = (id) => {
-  let birthDate = moment(id.toString().slice(0, 6), "YYMMDD");
+  let birthDate = moment(id.toString().slice(0, 6), 'YYMMDD')
   if (birthDate.isSameOrAfter(moment())) {
-    birthDate = moment(`19${id.toString().slice(0, 6)}`, "YYYYMMDD");
+    birthDate = moment(`19${id.toString().slice(0, 6)}`, 'YYYYMMDD')
   }
-  return birthDate;
-};
+  return birthDate
+}

Optional -d or --documents

This option allows you to observe the modifications applied to the document files (policy-schedule.html, certificate.html, quote-summary.html, anniversary-letter.html, member-certificate.html). In the case of the terms file, individual line distinctions will not be displayed; however, there will be an indication if the terms file has been revised.

Optional -ad or --api-docs

This option allows you to view the changes in the api-docs.yaml file

Optional -rm or --read-me

This option allows you to view the changes in the README.md file

rp ai

This command allows you to leverage off AI when building a product module. Create a .ai-auth file inside the root directory of your product module to use. For OpenAI requests, the file must be structured as follows:

OPEN_AI_API_KEY=sk-12345

❗️

.ai-auth security

Make sure to add .ai-auth to your .gitignore to keep your AI Key private.

Optional: -w or --workflow flag

Uses the provided .csv file name to generate a Joi schema in the /sandbox directory.

$ rp ai --workflow quote
Generating output via OpenAI....
Joi schema successfully generated in the './sandbox' directory 

The .csv file must have the following header row located in a directory labelled /specifications.

field,data_type,requirement_type,validation,description,parent_key,parent_key_requirement_type

Here is an example file called quote.csv:

field,data_type,requirement_type,validation,description,parent_key,parent_key_requirement_type
cover_amount,Integer,Required,"[label: value]
One of [R6,000: 6000, R12,000: 12000, R18,000: 18000, R30,000: 30000, R42,000: 42000]",The chosen cover for the policy.,,
partner_included,Boolean,Required,"[true, false]",To indicate if a partner has cover on the policy.,,
date_of_birth,String,Required,"Must be in YYYY-MM-DD format in the past. 
This is used to run through the Age validation business rule: B2",The date of birth of the main member,main_member,Required
title,Dropdown,Required,"[label: value]
One of [Mr:mr, Mrs:mrs, Miss:miss, Mx:mx, Sir:sir, Dr:dr, Adv:adv, Ms:ms, Prof:prof]",The title of the partner,partner,Required if partner_included is true else forbidden

//...etc

This will generate a Joi schema inside the /sandbox directory which you can then copy into your codebase. Note the structure will vary based on the AI Model's interpretation of the .csv file.

const partnerTitle = Joi.string()
  .valid(['mr', 'mrs', 'miss', 'mx', 'sir', 'dr', 'adv', 'ms', 'prof'])
  .required();

const mainMemberSchema = Joi.object({
  date_of_birth: Joi.dateOfBirth().required(), // Assuming dateOfBirth() is a custom validation function
});

const partnerSchema = Joi.object({
  title: partnerTitle,
});

const schema = Joi.object({
  cover_amount: Joi.number()
    .valid([6000, 12000, 18000, 30000, 42000])
    .required(),
  partner_included: Joi.boolean().required(),
  main_member: mainMemberSchema.required(),
  partner: Joi.when('partner_included', {
    is: true,
    then: partnerSchema,
    otherwise: Joi.forbidden(),
  }),
});

This schema is constructed based on the requirements and validations specified in the CSV. It includes:

- A `cover_amount` that must be one of the specified values.
- A `partner_included` boolean to indicate if a partner is included in the policy.
- A `main_member` object that requires a `date_of_birth`, which utilizes a custom `dateOfBirth()` validation function.
- A conditional `partner` object that is required if `partner_included` is `true`. This object requires a `title`, which must be one of the specified values. If `partner_included` is `false`, the `partner` object is forbidden.