WebsiteWe're hiringCourses & Certifications→ Get started for free
Guides

Getting started with Workbench (DEPRECATED)

Get the Workbench CLI tool set up on your local machine

Suggest Edits

Overview

Root enables flexible, modern digital insurance products to come to life in record time. We achieve this by abstracting and automating most of the complexity of insurance and exposing the rest in a no-code/low-code environment named Workbench.

The Workbench CLI tool is a command line interface (CLI) tool. You can use this tool to set up, configure, and test insurance products on your local machine and push changes to Root.

This tutorial is a step-by-step guide to setting up the Workbench CLI tool on your local machine. The tutorials that follow will guide you on how to use the Workbench CLI tool to make changes to an existing insurance product on Root.

Read more about the functionality offered by the Workbench CLI tool in the Workbench CLI tool commands guide. For an overview of the product features you can configure and how to configure them, see the Product modules overview guide. You can also follow our product showcase below, which overlaps with this tutorial. The demo starts at 8:30.

Step 1: Get set up on Root

🚧

Root access required

From this step forward, you need access to Root. Get in touch with us if you're interested in playing around or building a new insurance product. If you're already started but stuck, reach out to our team at [email protected].

To complete this tutorial, a Root team member needs to set you up on Root by creating a Root account and giving you access to the Root management dashboard. Ensure you have access before continuing. You can log in to the dashboard at:

1.a. Create an organisation and add a product module

Once you have access, you can create a playground organisation by clicking on the "Create an organisation" button. You can call this organisation Playground - [your name].

On the "Add product module" screen, select the "Dinosure" product module and add the following:

  • Name: Dinosure [Your Name]
  • Key: dinosure_[your_name]

Note: Each product module key must be unique. If a product module key with your name already exists, you can add numbers or characters to make it unique.

Your new organisation should now be open on the Root management dashboard. Keep this window open, as we will create an API key from here in Step 4.

Step 2: Set up your local environment

To use the Workbench CLI tool effectively, you need a few things installed on your machine. This works on Mac, Windows and Linux.

2.a. Install NodeJS

We need to install NodeJS in order to set up and use the Workbench CLI tool.

Download NodeJS and install it to your machine.

2.b. Install VS Code

We need a code editor in order to use the Workbench CLI tool. We generally prefer VSCode, by Microsoft, but any IDE will work such as Sublime Text.

Download VS Code and install it to your machine.

2.c. Install Project Snippets extension (optional)

Some IntelliSense functionality in the Workbench CLI tool depends on the Project Snippets extension in VSCode.

Visit Project Snippets to install the extension in VSCode.

Step 3: Install the Workbench CLI tool

Now that we have NodeJS and a code editor set up, we can proceed to install the Workbench CLI tool.

Mac instructions

If you are on Mac, open your Terminal.

🚧

Install global npm packages in an unrestricted directory

If you are using a Mac, you may run into permission issues when trying to install global npm packages to the default directory.

We recommend configuring npm to install global packages into a directory that doesn't require strict permissions. You can do this by running the following commands in your terminal:

Bash example:

mkdir ~/.npm-packages
npm config set prefix ~/.npm-packages
echo 'export PATH=$PATH:$HOME/.npm-packages/bin' >> ~/.bashrc

Zsh example:

mkdir ~/.npm-packages
npm config set prefix ~/.npm-packages
echo 'export PATH=$PATH:$HOME/.npm-packages/bin' >> ~/.zprofile && exec zsh

Alternatively, you can avoid installing Workbench locally by prefixing any workbench commands with npx. Read more here.

In Terminal, type (or copy/paste) npm install -g @rootplatform/cli and press enter. This will download and install the Workbench CLI tool on your machine.

Once that command finishes, you can test that the Workbench CLI tool installed correctly by typing rp help. (All Workbench CLI tool commands use the format rp [command] [options].)

The Workbench CLI tool and your environment is now set up and ready to go.

❗️

Node V16

If you're using Node V16, you might run into some usage issues. This can be resolved by using a tool like nvm to install and run Node V14.x or V12.x. If you use nvm, you may be able to configure your shell to automatically use the correct Node version when running commands in the product module directory.

Windows instructions

If you are on Windows, open Command Prompt.

In Command Prompt, type (or copy/paste) npm install -g @rootplatform/cli and press enter. This will download and install the Workbench CLI tool on your machine.

Once that command finishes, you can test that the Workbench CLI tool installed correctly by typing rp help. (All Workbench CLI tool commands use the format rp [options] [command].)

Your local environment is now set up and ready to go.

Step 4: Create an API key

Let's generate an API key to use in the Workbench CLI tool. Your playground organisation should be open on the Root management dashboard after you created it in Step 2. Otherwise you can open open the dashboard again and then click on your organisation.

First, make sure you are in sandbox mode. If you are in sandbox mode, you will see a thin yellow banner across the top of the window. If you are not in sandbox mode, go to " Data management > Environment > Switch to sandbox mode".

To create your API key, navigate to " Workbench > API Keys".

  1. Click "Create API Key".
  2. Give it a description like <your name> Workbench CLI tool, e.g. Sarah Workbench CLI tool.
  3. Click "Select all". Scroll down to Workbench and ensure read and write are selected.
  4. Click "Create API key", and copy the API key to your clipboard.

Note: You can only see the API key once, so if you've accidentally closed the window before copying the API key, delete the key and create a new one.

Step 5: Clone a product module to your local machine

Now go back to your Terminal (or Command Prompt) and clone (download) your Dinosure product module using the Workbench CLI tool.

  1. cd to your working directory, e.g. Documents (Mac help, Windows help) or just stay in the current directory.
  2. Clone the product module using the command rp clone <api_key> <product_module_key> -h <host>, for example:
rp clone sandbox_ZGEyYzQdOWUtNTM1My00ZmQ5LTk4NDItYmJiMjYwZWQ3NzA5LkCJYkZzYmptUlJ3UmNvTGtVN3ltRl9yQVRCT3ZFNDZb dinosure_jane -h https://sandbox.uk.rootplatform.com

Here you can paste the API key from your clipboard using Cmd+V (Mac) or Ctrl+V (Windows). If you need to verify the name of the product module, you can navigate to " Workbench > Product modules" on the dashboard.

📘

Use the correct host when cloning your product module

Copy the sandbox URL for your region from the domains section of the API reference.

  1. Now navigate with your Terminal/Command Prompt into that project directory using cd <product-module-key> (e.g. cd dinosure_jane). Try ls (Mac) or dir (Windows) to list all the files in the directory. To double check that all the files were downloaded correctly, take a look at the File and folder structure guide.

This new project directory can now be opened with your code editor to see and edit all the files and components of your Dinosure product module.

Well done! You have successfully completed the basic Workbench CLI tool setup. In the next tutorial you will use the Workbench CLI tool to implement your first product update.

Updated 12 months ago