Skip to main content

Report Variables

Report variables store named values that can be referenced throughout an output template. Instead of repeating the same value or expression in every component, define it once as a variable and reference it with {{var.VariableName}}.

Variables are defined in the Output Designer at the template level. They are not stored in editions — they are evaluated at output render time.

Variable types​

TypeDescriptionExample
StaticA fixed literal value entered by the designerReportTitle = "Monthly Progress Report"
Expression-basedA formula that computes a value from edition fields, parameters, or other variablesBudgetVariance = [ActualCost] - [BudgetCost]

When to use variables​

ScenarioUse a variable?
The same calculated value appears in multiple components (KPI card, table footer, narrative)Yes — define once, reference everywhere
A literal string (report title, client name) appears on every pageYes — static variable
A complex expression would need to be duplicated in 4 chart seriesYes — expression variable
A value is used in only one placeNo — configure it directly on the component
A value changes per edition (report date, period)No — use an edition field or a parameter

Defining variables​

Step 1 — Open the Variables panel​

  1. Open the blueprint → Output Designer → select the output template.
  2. In the top bar, click Variables (or press V).
  3. The Variables panel opens on the right.

Step 2 — Add a static variable​

  1. Click + Add variable.
  2. Set Type to Static.
  3. Enter:
    • Name — the reference name used in {{var.Name}} syntax. Must be a single word or camelCase with no spaces.
    • Value — the literal value (text, number, date, or boolean).
    • Data type — Text, Number, Currency, Percent, Date, or Boolean.
  4. Click Save.

Example:

SettingValue
NameClientName
ValueApex Infrastructure Ltd
Data typeText

Reference: {{var.ClientName}}

Step 3 — Add an expression variable​

  1. Click + Add variable.
  2. Set Type to Expression.
  3. Enter:
    • Name — reference name (camelCase).
    • Expression — formula using field references, functions, and operators.
    • Output type — the data type of the result.
  4. Click Save.

See Expression Reference for the full function library.

Variable syntax​

In text components, table cells, KPI labels, page headers, and footers, reference a variable with:

{{var.VariableName}}

In expression fields (other variables, calculated fields, conditional formatting), reference a variable with:

var.VariableName

Do not include {{ and }} when referencing variables inside expression editors — those delimiters are for text interpolation only.

Common variable patterns​

Pattern 1 — Report header information​

Define static variables for values that appear consistently across the report:

Variable nameValueUsed in
ClientNameApex Infrastructure LtdCover page, header footer
ProjectNameNorth Station UpgradeCover page, every page header
ContractRefNRN-2024-042Cover page, footer
PreparedByDocument Control TeamCover page

Reference in a text component: Prepared for: {{var.ClientName}}

Pattern 2 — Computed totals referenced in multiple places​

Define an expression variable once and reference it in multiple components:

Variable: TotalActualCost

SUM([sections.CostReport.rows.ActualCost])

This variable can then be referenced in:

  • A KPI card value: {{var.TotalActualCost}}
  • A table footer: Total: {{var.TotalActualCost}}
  • A narrative text component: Total actual cost to date is {{var.TotalActualCost}}.
  • Another expression variable: var.TotalActualCost / var.BudgetAtCompletion

Pattern 3 — RAG summary counts​

RedRisks = COUNTIF([sections.RiskRegister.rows.RAGStatus], "Red")
AmberRisks = COUNTIF([sections.RiskRegister.rows.RAGStatus], "Amber")
GreenRisks = COUNTIF([sections.RiskRegister.rows.RAGStatus], "Green")

Reference in a narrative: There are {{var.RedRisks}} critical risks, {{var.AmberRisks}} amber risks, and {{var.GreenRisks}} risks currently rated green.

Pattern 4 — Threshold labels for conditional text​

ScheduleLabel = IF([sections.Summary.ScheduleRAG] = "Red", "Behind programme", IF([sections.Summary.ScheduleRAG] = "Amber", "At risk of delay", "On programme"))

Reference in a cover page text block: Schedule status: {{var.ScheduleLabel}}

Pattern 5 — Variance calculation with sign formatting​

CostVariance = [sections.Commercial.ActualCost] - [sections.Commercial.BudgetCost]
CostVariancePct = var.CostVariance / [sections.Commercial.BudgetCost]

Reference in a KPI card using the signed_percent format to show +5.2% or -8.4%.

Variable evaluation order​

Variables are evaluated in definition order. A variable can reference another variable defined earlier in the list, but not one defined later.

Example (valid — TotalCost defined before VariancePct):

TotalCost = SUM([sections.Cost.rows.ActualCost])
VariancePct = (var.TotalCost - SUM([sections.Cost.rows.Budget])) / SUM([sections.Cost.rows.Budget])

Example (invalid — circular reference):

A = var.B + 1
B = var.A + 1

Circular references cause a render error. Report Forge will flag this with a validation warning in the Variables panel.

Variable naming rules​

RuleExample
Must start with a letterTotalCost (valid), 1stValue (invalid)
No spaces — use camelCase or PascalCaseBudgetVariance, clientName
No special charactersCostTotal (valid), Cost-Total (invalid)
Case-sensitiveTotalCost and totalCost are different variables
Maximum 50 characters—

Debugging variables​

If a variable reference does not render the expected value:

  1. Open the Variables panel → check the variable definition for syntax errors (shown with a red indicator).
  2. Click Preview in the Output Designer — hover over the {{var.Name}} placeholder to see the resolved value.
  3. Check the data type: a Number variable used in a text context may need explicit formatting with FORMAT() in the expression.
  4. Check evaluation order: ensure any referenced variable is defined before the current variable in the list.