Maintainable Envision Code

This page groups the maintainability tutorials so you can move from one-off scripts to reusable building blocks.

Table of contents

Extract a Reusable Pure Function

Turn repeated calculations into a reusable function.

1. Paste the script and run it.
2. You should now see the net revenue per line and a total KPI.
3. Change the discount rate and re-run to confirm the function is reused.

def pure netRevenue(qty: number, price: number, discount: number) with
  return qty * price * (1 - discount)

table Lines = with
  [| as Sku, as Qty, as Price, as Discount |]
  [| "A-100", 4, 12.5, 0.10 |]
  [| "B-200", 2, 18.0, 0.05 |]
  [| "C-300", 6, 9.0, 0.00 |]

Lines.Net = netRevenue(Lines.Qty, Lines.Price, Lines.Discount)

show scalar "Total net revenue" { unit:"$" } with sum(Lines.Net)

show table "Net revenue by line" with
  Lines.Sku
  Lines.Qty
  Lines.Price { unit:"$" }
  Lines.Discount { unit:"%" }
  Lines.Net { unit:"$" }

You should now have one clean function to reuse across dashboards.

Build a Small Process Function for Aggregations

Wrap an aggregation pattern into a process so you can reuse it.

1. Paste the script and run it.
2. You should now see a running maximum for the demand series.
3. Change one demand value and re-run to verify the process updates the whole column.

def process runningMax(n: number) with
  keep best = -1e9
  best = max(best, n)
  return best

table Series = with
  [| as Day, as Demand |]
  [| date(2024, 1, 1), 18 |]
  [| date(2024, 1, 2), 22 |]
  [| date(2024, 1, 3), 15 |]
  [| date(2024, 1, 4), 28 |]
  [| date(2024, 1, 5), 21 |]

Series.RunningMax = runningMax(Series.Demand) scan Series.Day

show table "Running maximum" with
  Series.Day
  Series.Demand
  Series.RunningMax

You should now have a reusable process for running metrics.

Split Code into Modules and import Them

Create a small module so your main script stays focused on the dashboard.

1. In the playground, create a module named sample/sales-math and paste this module code, then save it.
2. Create a new script and paste the main script below.
3. Run the script. You should now see the revenue KPIs computed via the imported function.

Module sample/sales-math:

// Module "sample/sales-math"
export def pure lineRevenue(qty: number, price: number) with
  return qty * price

export const defaultCurrency = "USD"

Main script:

import "sample/sales-math" as Sales with
  lineRevenue
  defaultCurrency

table Lines = with
  [| as Sku, as Qty, as Price |]
  [| "A-100", 4, 12.5 |]
  [| "B-200", 2, 18.0 |]
  [| "C-300", 6, 9.0 |]

Lines.Revenue = lineRevenue(Lines.Qty, Lines.Price)

show summary "Revenue" with
  sum(Lines.Revenue) as "Total" { unit:"#(defaultCurrency)" }

show table "Lines" with
  Lines.Sku
  Lines.Qty
  Lines.Price { unit:"#(defaultCurrency)" }
  Lines.Revenue { unit:"#(defaultCurrency)" }

You should now have a modular setup you can reuse across scripts.

Package Reusable Logic for Multiple Dashboards

Package shared logic once, then reuse it in multiple dashboards.

1. Create a module named sample/kpi-kit and paste the module code below.
2. Paste the first script to build a KPI dashboard.
3. Paste the second script to build a trend dashboard, reusing the same module.

Module sample/kpi-kit:

// Module "sample/kpi-kit"
export const currency = "USD"
export const kpiColor = "#0f4c81"

export def pure revenue(qty: number, price: number) with
  return qty * price

Dashboard A (KPIs):

import "sample/kpi-kit" as Kit

table Lines = with
  [| as Sku, as Qty, as Price |]
  [| "A-100", 4, 12.5 |]
  [| "B-200", 2, 18.0 |]
  [| "C-300", 6, 9.0 |]

Lines.Revenue = Kit.revenue(Lines.Qty, Lines.Price)

show scalar "Total revenue" { tileColor: #(Kit.kpiColor) ; unit:"#(Kit.currency)" } with
  sum(Lines.Revenue)

Dashboard B (Trend):

import "sample/kpi-kit" as Kit

keep span date = [date(2024, 1, 1) .. date(2024, 1, 6)]

Day.t = date - date(2024, 1, 1)
Day.Price = 10 + Day.t
Day.Qty = 5 + Day.t
Day.Revenue = Kit.revenue(Day.Qty, Day.Price)

show linechart "Daily revenue" with
  Day.Revenue { unit:"#(Kit.currency)" ; color: #(Kit.kpiColor) }

You should now see how a small shared module keeps dashboards consistent.