Conditional Expressions

The Encodian population engine supports conditional expressions which enable you to add logic to your spreadsheet to evaluate defined criteria to ascertain whether certain tokens (and related data) should be inserted into the spreadsheet.

This article covers the following topics and examples:

Conditional Expression Syntax Overview

Example #1 - Basic

Example #2 - Advanced

Example #3 - Tables

Example #4 - Date Time Values

Checking for Null Values

Conditional Expression Operators

Conditional Expression Syntax Overview

Conditional expressions conform to common logical syntactical constructs, see below:

<<if [conditional_expression1]>>
  Show this data
  <<elseif [conditional_expression2]>>
    Show This data
  <<else>>
    This this data
<</if>>

Example #1 - Basic

Example Spreadsheet: Encodian - Template Syntax - Conditions Basic.xlsx

Example JSON Data:

{
  "companyName": "Encodian",
  "invoicePaid": true,
  "invoiceOverdue": false,
  "invoiceDue": "2021-06-01",
  "invoiceValue": 10000
}

Configure the spreadsheet with required conditional expressions and content:

<<if [invoicePaid == false]>>Unpaid<<else>>Paid<</if>>

This generates the following output:

Example #2 - Advanced

Example Spreadsheet: Encodian - Template Syntax - Conditions Advanced.xlsx

Example JSON Data:

{
  "companyName": "Encodian",
  "invoicePaid": false,
  "invoiceDue": "2024-07-01",
  "invoiceValue": 10000,
  "generatedOn": "2024-05-19"
}

Configure the spreadsheet with required conditional expressions and content:

<<if [invoicePaid == false && invoiceDue < generatedOn]>>Unpaid & Overdue<<elseif [invoicePaid == false && invoiceDue > generatedOn]>>Unpaid and due <<[invoiceDue]:"yyyy.MM.dd" >><<else>>Paid<</if>>

This generates the following output:

Example #3 - Tables

Example Spreadsheet: Encodian - Template Syntax - Conditions Tables.xlsx

Example JSON Data:

{
  "contracts": [
  {
    "customerName": "Microsoft",
    "value": 100000.00,
    "expires": "13/06/2021"
  },
  {
    "customerName": "Encodian",
    "value": 0.00,
    "expires": "18/02/2029"
  },
  {
    "customerName": "Heritage",
    "value": 13549.35,
    "expires": "6/12/2025"
  }
 ]
}

Configure the spreadsheet with required conditional expressions and content:

Row 3 > Column A/B: <<foreach [contract in contracts]>><<if [contract.customerName!="Encodian"]>><<[ contract.customerName]>>
Row 3 > Column C/D: <<[contract.expires]:"yyyy.MM.dd">>
Row 3 > Column E/F: <<[contract.value]>><</if>><</foreach>>
Row 4 > Column E/F: <<[contracts.Sum(c =>c.value)]>>

This generates the following output:

Example #4 - Date Time Values

Example Spreadsheet: Encodian - Template Syntax - DateTime.xlsx

Example JSON Data:

{
   "commenced": "2024/10/29",
   "expires": "2025/10/28",
}

Configure the spreadsheet with required conditional expressions and content:

<<if [expires.ToString() == ""]>>None<<else>><<[expires]:"yyyy-MM-dd">><</if>>

NOTE: You must use the ToString() method to compare a DateTime value with a string. If this step is not performed the engine will throw an error stating that a DateTime object cannot be compared with a string.

This generates the following output:

Checking for Null Values

By default the 'JSON Parse Mode' is set to 'Standard' and therefore the populate engine will parse null values as empty strings. When checking for null values we recommend setting the 'JSON Parse Mode' option to 'Strict'.

Example JSON Data:

{ "value": null }

The following options are available for performing a null check:

<<[value ?? "The value is null"]>>

or

<<if [value != null]>>VALUE: <<[value]>><</if>>

Conditional Expression Operators

The following table contains all operators that the Encodian population engine supports

• Binary:  * / % + - << >> < > <= >= == != & ^ | && || ??
• Primary:  x.y x?.y f(x) a[x] a?[x] new
• Unary:  - ! ~ (T)x
• Ternary:  ?:

The population engine follows operator precedence, associativity, and overload resolution rules declared at C# Language Specification 5.0 while evaluating template expressions. However, please consider the following limitations considering the specification:

• Implicit user-defined conversions are supported only when specified explicitly.
• The indexing of multi-dimensional arrays is not supported.
• Whereas the object initializer syntax is supported (including objects of anonymous types), the collection initializer syntax is not.