Placeholders | EzeScan Help Center

Placeholders insert dynamic values into text, such as a field's value, details of the logged-in user, or today's date. They can be used anywhere a setting accepts placeholders, for example field defaults, file names, email templates and generated PDFs.

The easiest way to create a placeholder is with the Placeholder Builder. It lets you pick a value and add methods, and shows the resulting placeholder text.

How placeholders work

A placeholder is wrapped in double braces. Inside, it starts with a value and can be followed by one or more methods, each after a pipe (|):

{{value}}
{{value | method()}}
{{value | method1() | method2("argument")}}

Methods run from left to right. Each one receives the result of everything to its left.
Text arguments go in double quotes, for example replace(" ", "-"). Numbers and true/false don't need quotes.
An argument can itself be a placeholder value, for example equals(fields["other_field"]).
Pipes and commas inside quotes or parentheses are treated as part of the argument, not as separators.
Some methods, such as add or coalesce, can also be used on their own with all their values as arguments: {{add(fields["a"], fields["b"])}}.

For example, this takes a field's value, keeps the second item of a pipe-separated list, and removes surrounding spaces:

{{fields["field_id"] | split("|", 2) | trim()}}

Values

Every placeholder starts with one of these values.

Fields and metadata

Placeholder	Description
`{{fields["field_id"]}}`	The value of a field. Inside a grid row, this refers to the field in the same row.
`{{metadata["metadata_id"]}}`	The value of a metadata item. Commonly used in processing stages, where earlier stages may have updated the metadata. See also `attribute`.

Current user

Placeholder	Description
`{{user["email"]}}`	Email address of the currently logged in user.
`{{user["username"]}}`	User name of the currently logged in user.
`{{user["displayName"]}}`	Display name of the currently logged in user.
`{{user["id"]}}`	Id of the currently logged in user.
`{{user["udv.department"]}}`	Gets the value of the “department” user defined value that has been configured in Users \| User Defined Values
`{{user["manager.id"]}}`	User name of the manager for the currently logged in user.
`{{user["manager.email"]}}`	Email address of the manager for the currently logged in user.
`{{user["manager.displayName"]}}`	Display name of the manager for the currently logged in user.
`{{user["manager.udv.department"]}}`	Gets the value of the managers “department” user defined value that has been configured for the current user.

Page

Placeholder	Description
`{{page["id"]}}`	Id of the page the current item or field is on.
`{{page["name"]}}`	Name of the page.
`{{page["type"]}}`	Type of the page, for example RIA or DFA.

Indexing item

Available in the fields of Remote Indexing Assistant items.

Placeholder	Description
`{{item["id"]}}`	GUID of the item.
`{{item["name"]}}`	Name of the item.
`{{item["size"]}}`	Size of the item.
`{{item["queueId"]}}`	GUID of the queue the item is in.
`{{item["queueName"]}}`	Name of the queue.
`{{item["queueTypeId"]}}`	GUID of the queue type.
`{{item["queueTypeName"]}}`	Name of the queue type.

Date and time

Placeholder	Description	Example
`{{date}}`	The current server date, as `yyyyMMdd`.	`20231225`
`{{time}}`	The current server time, as `hhmmss`.	`055322`
`{{now}}`	The current server date and time. Use with `format`.	`{{now \| format("{0:yyyy-MM-dd HH:mm}")}}`

Use format to change the output, for example {{date | format("{0:dd/MM/yyyy}")}} or {{time | format("{0:hh-mm-ss}")}}.

Text methods

Method	Description	Example	Input	Result
`format`	Inserts the value into a .NET format string, where `{0}` is the value. Also formats numbers and dates.	`format("%{0}%")` `format("{0:0.00}")`	`Cat` `123`	`%Cat%` `123.00`
`toLower`	Converts to lower case.	`toLower()`	`Cat`	`cat`
`toUpper`	Converts to upper case.	`toUpper()`	`Cat`	`CAT`
`toTitle`	Capitalises the first letter of each word and lower-cases the rest.	`toTitle()`	`the MOUSE likes cheese`	`The Mouse Likes Cheese`
`toSentence`	Capitalises the first letter of each sentence. Other letters are unchanged.	`toSentence()`	`the MOUSE likes cheese. yum yum!`	`The MOUSE likes cheese. Yum yum!`
`trim`	Removes leading and trailing whitespace, including tabs and line breaks.	`trim()`	`Cat`	`Cat`
`replace`	Replaces all occurrences of the first text with the second.	`replace(" ", "")`	`This is some text`	`Thisissometext`
`split`	Splits on a separator and returns the item at the given position, starting at 1.	`split("\|", 2)`	`Cat\|Dog`	`Dog`
`left`	Returns the given number of characters from the start.	`left(3)`	`123456789`	`123`
`right`	Returns the given number of characters from the end.	`right(3)`	`123456789`	`789`
`sanitiseText`	Removes or converts types of characters. See SanitiseText.	`sanitiseText("spaces")`	`John Smith`	`JohnSmith`
`coalesce`	Returns the first of its arguments that has a value.	`{{coalesce(fields["a"], fields["b"], fields["c"])}}`	a: empty b: `My Value` c: `Other`	`My Value`

SanitiseText

Removes or converts types of characters, for example to clean up a value before using it in a file name or reference number.

{{fields["field_id"] | sanitiseText("type")}}

To apply several types, either list them or chain the method. Both give the same result, and types run in the order given:

{{fields["field_id"] | sanitiseText("alpha", "commas", "spaces")}}
{{fields["field_id"] | sanitiseText("alpha") | sanitiseText("commas") | sanitiseText("spaces")}}

The Placeholder Builder applies one type per method. To apply several types, add Sanitise Text once for each type.

Sanitisation types

Type names are not case-sensitive. A type that isn't recognised is ignored.

Type

Builder option

What it does

spaces

Spaces

Removes all whitespace, including spaces, tabs and line breaks.

lineBreaks

Line Breaks

Removes line breaks only.

punctuation

Punctuation

Removes punctuation, such as ! " # % & ' ( ) * , - . / : ; ? @ [ \ ] _ { }.

punctuationIgnorePeriod

Punctuation, ignore period

Same as punctuation, but keeps full stops.

period

period

Removes full stops (.).

commas

Commas

Removes commas (,).

quotes

Quotes

Removes double quotes ("). Single quotes are kept.

symbols

Symbols

Removes symbols, such as $ + < = > ^ ` | ~ © ®.

alpha

Alpha

Removes letters.

numeric

Numeric

Removes numbers.

alphaNumeric

Alpha/Numeric

Removes letters and numbers, leaving only other characters.

invalidFilenameCharacters

Invalid file name characters

Removes characters that aren't allowed in file names, such as < > : " / \ | ? *.

toAscii

Convert to ASCII

Converts text to plain ASCII, keeping as much information as possible. Unlike the other types, it converts characters where it can rather than deleting them:

Characters	Becomes	Example
Accented letters	The plain letter	`é` → `e`, `Ñ` → `N`
Full-width and special forms	The plain version	`Ａ` → `A`, `①` → `1`, `ﬁ` → `fi`, `…` → `...`
Dashes and minus sign	A hyphen	`– — −` → `-`
Curly and angled quotes	Straight quotes	`‘ ’` → `'`, `“ ” « »` → `"`
Special spaces	A normal space	Non-breaking space → space
Some letters	Spelled out	`ß` → `ss`, `æ` → `ae`, `œ` → `oe`, `ø` → `o`, `ł` → `l`, `đ`/`ð` → `d`, `þ` → `th`
Anything else that isn't ASCII	Removed	Non-Latin scripts (such as Chinese or Cyrillic), emoji, and invisible characters such as zero-width spaces

Examples

Placeholder	Input	Result
`{{fields["name"] \| sanitiseText("spaces")}}`	`John Smith`	`JohnSmith`
`{{fields["ref"] \| sanitiseText("punctuation")}}`	`ABC-123/45.6`	`ABC123456`
`{{fields["ref"] \| sanitiseText("punctuationIgnorePeriod")}}`	`ABC-123/45.6`	`ABC12345.6`
`{{fields["amount"] \| sanitiseText("alpha", "commas", "spaces")}}`	`AUD 1,250`	`1250`
`{{fields["title"] \| sanitiseText("toAscii")}}`	`Café – “Résumé”`	`Cafe - "Resume"`
`{{fields["title"] \| sanitiseText("invalidFilenameCharacters")}}`	`Report: Q1/Q2?`	`Report Q1Q2`

Date methods

Date values must be read as a date before they can be formatted or used in date methods. Use format with a .NET date format to output them.

Method	Description	Example	Input	Result
`asDate`	Reads the value as a date in the given format.	`asDate("dd/MM/yyyy") \| format("{0:yyyyMMdd}")`	`12/02/2021`	`20210212`
`asVariableDate`	Reads the value as a date using the server's locale, so the exact format doesn't need to be known.	`asVariableDate() \| format("{0:dd/MM/yyyy}")`	`25 Jan 2023`	`25/01/2023`
`asFinancialYear`	Returns the financial year a date falls in. See arguments.	`asFinancialYear("01/07")`	`01/04/2018`	`2017-2018`
`asFinancialMonth`	Returns the month number within the financial year. See arguments.	`asFinancialMonth("01/07")`	`01/05/2018`	`11`

Financial year arguments

asFinancialYear and asFinancialMonth take the same two arguments:

Argument	Required	What to enter	Example
First	Yes	The day the financial year starts, written as day/month. Always `dd/MM`, wherever you are.	`"01/07"` for 1 July (Australia) `"01/04"` for 1 April (UK)
Second	No	How the field's date is written, so it can be read correctly. Leave it out if the date is in the server's normal format.	`"dd/MM/yyyy"` for `25/12/2023` `"yyyy-MM-dd"` for `2023-12-25`

Placeholder	Field value	Result
`{{fields["date"] \| asFinancialYear("01/07")}}`	`15/03/2024`	`2023-2024`
`{{fields["date"] \| asFinancialYear("01/07", "yyyy-MM-dd")}}`	`2024-08-15`	`2024-2025`
`{{fields["date"] \| asFinancialMonth("01/07")}}`	`15/07/2024`	`1` (July is the first month)
`{{fields["date"] \| asFinancialMonth("01/07")}}`	`15/06/2024`	`12` (June is the last month)

If the date can't be read, the value is returned unchanged.

Number methods

add, subtract, multiply and divide can be used two ways:

On their own, with all values as arguments. The operation runs from the first value onwards: {{subtract(fields["a"], fields["b"], "5")}} is a − b − 5.
After a pipe, applying to the incoming value: {{fields["a"] | subtract("5")}} is a − 5.

Method	Example	Input	Result
`add`	`{{add(fields["a"], fields["b"], fields["c"])}}` `{{fields["a"] \| add("20")}}`	a: `10`, b: `15`, c: `20`	`45` `30`
`subtract`	`{{subtract(fields["a"], fields["b"], fields["c"])}}` `{{fields["a"] \| subtract("20")}}`	a: `100`, b: `10`, c: `20`	`70` `80`
`multiply`	`{{multiply(fields["a"], fields["b"], fields["c"])}}` `{{fields["a"] \| multiply("20")}}`	a: `1`, b: `3`, c: `6`	`18` `20`
`divide`	`{{divide(fields["a"], fields["b"], fields["c"])}}` `{{fields["a"] \| divide("20")}}`	a: `100`, b: `5`, c: `2`	`10` `5`
`math`	`{{math("add", fields["a"], fields["b"], fields["c"], "10")}}` The first argument is `add`, `subtract`, `multiply` or `divide`, so the operation can come from another value.	a: `100`, b: `5`, c: `2`	`117`
`sum`	`{{sum(fields["a"], fields["b"])}}`	a: `5`, b: `10`	`15`
`round`	`{{fields["a"] \| round(2)}}` `{{round(0.9944, 2)}}` The number is the decimal places to keep.	a: `10.256`	`10.26` `0.99`

Comparisons and conditions

Comparison methods return true or false. Follow them with condition to output different text depending on the result:

{{fields["field_id"] | exists() | condition("Has a value", "Is empty")}}

Method	Returns true when the value…	Example	Input	Result
`exists`	is not empty, null or whitespace	`exists()`	`Value`	`true`
`equals`	is the same as the argument	`equals("Hi")`	`Hi`	`true`
`startsWith`	starts with the argument	`startsWith("Fri")`	`Friday`	`true`
`endsWith`	ends with the argument	`endsWith("ay")`	`Saturday`	`true`
`contains`	contains the argument	`contains("ver")`	`Conversion`	`true`
`matches`	matches a regular expression	`matches("[0-9]{2}")`	`abc123IAM`	`true`
`greaterThan`	is greater than the number	`greaterThan(5)`	`5.10`	`true`
`greaterThanEquals`	is greater than or equal to the number	`greaterThanEquals(5)`	`5`	`true`
`lessThan`	is less than the number	`lessThan(10)`	`10`	`false`
`lessThanEquals`	is less than or equal to the number	`lessThanEquals(10)`	`10`	`true`
`condition`	Not a comparison: returns the first argument if the input is `true`, otherwise the second. Either argument can be another placeholder expression. `condition("yes", "no")`		`true`	`yes`

Handling missing values

Normally, if a method fails, for example split asks for a position that doesn't exist or a field has no value, the whole placeholder fails with an error. Add nullable() to return an empty string instead:

{{fields["field_id"] | nullable() | split("|", 4)}}

nullable() doesn't change the value. It only changes how failures are handled for the methods after it.
It can go at the start, as in {{nullable() | property("test") | trim()}}, or after the value.
It only applies to the placeholder it's in. If text contains several placeholders, add nullable() to each one that needs it.
It's available in the Placeholder Builder as Nullable.

Placeholder	Scenario	Result
`{{fields["f"] \| nullable() \| split("\|", 4)}}`	`f` = `value1\|value2\|value3`	empty
`{{fields["f"] \| nullable() \| split("\|", 3)}}`	`f` = `value1\|value2\|value3`	`value3`
`{{fields["f"] \| nullable() \| trim()}}`	Field `f` doesn't exist	empty
`{{fields["f"] \| nullable() \| trim()}}-{{fields["f"] \| trim()}}`	Field `f` doesn't exist	Error: the second placeholder isn't nullable
`{{fields["f"] \| nullable() \| trim()}}-{{fields["f"] \| nullable() \| trim()}}`	Field `f` doesn't exist	`-`

Collections

Some fields, such as check boxes and multi-selects, hold several values.

Method	Description	Example	Input	Result
`join`	Joins the values with a separator.	`join(" \|\| ")`	`Value 1`, `Value 2`	`Value 1 \|\| Value 2`
`count`	Returns the number of values.	`count()`	`Value 1`, `Value 2`	`2`
`pivot`	Combines several values into a collection, so collection methods such as `join` can be used. Fields that don't exist are skipped.	`{{pivot(fields["a"], fields["b"], fields["c"]) \| join(", ")}}`	a: `Yes`, b: `Yes`, c: `No`	`Yes, Yes, No`

Properties and attributes

Some values contain named parts rather than a single piece of text. Use these methods to pick out one part.

property

Returns a named part of an object value, such as the answer to one question in a Likert field or a value produced by kfiDeserialise. On a collection, it returns the item with that name.

{{fields["field_id"] | property("name")}}

If the value doesn't have named parts, it's returned unchanged.

attribute

Returns extra information recorded about a metadata value, rather than the value itself. For example, when processing extracts a value from a document, it records where the value came from and how confident the extraction was.

{{metadata["metadata_id"] | attribute("name")}}

Attribute	Description
`source`	Name of the configuration or stage that set the value.
`sourceType`	Type of the source that set the value.
`configurationType`	Type of extraction configuration used, where the value was identified from a document.
`confidence`	Confidence score of the extracted value.
`boundingRegions`	Location of the value in the document, as JSON.

Which attributes are available depends on what set the value. Use nullable() if an attribute might not be present:

{{metadata["invoice_total"] | nullable() | attribute("confidence") | greaterThanEquals(0.8) | condition("OK", "Check")}}

kfiDeserialise

Reads a value in the KFI lookup format, so that its parts can be used with property. Only the first record is used.

{{fields["lookup"] | kfiDeserialise() | property("name")}}

Format	Meaning
`name=value`	A named value.
`\|\|`	Separates named values.
`##`	Separates records.
`~`	Escapes the next character, so `~=` and `~~` can be used in names and values.

Placeholder	Input	Result
`{{fields["lookup"] \| kfiDeserialise() \| property("Surname")}}`	`Id=42\|\|Surname=Smith\|\|Given=John`	`Smith`

Grids

Within a grid row, {{fields["field_id"]}} refers to the field in the same row. To use data from the whole grid, apply these methods to the grid field.

Reading values

Method	Description	Example
`cell`	The value of one cell. Rows start at 1.	`{{fields["grid"] \| cell(1, "supplierName")}}`
`count`	The number of rows.	`{{fields["grid"] \| count()}}`
`join`	Joins the values in one column, for example `row1\|row2\|row3`. A comma can't be used as the separator.	`{{fields["grid"] \| join("\|", "columnFieldId")}}`
`sum`	The total of a column. Returns nothing if any value isn't a number.	`{{fields["grid"] \| sum("columnFieldId")}}`

Outputting the whole grid

For the methods that take includeHeaders, pass true to include column names as the first row.

Method

Example

Output

gridAsText

{{fields["grid"] | gridAsText(" | ", true)}}
Arguments: separator, includeHeaders. A comma can't be used as the separator.

col_1 | col_2 | col_3
value1 | value2 | value3

gridAsCsv

{{fields["grid"] | gridAsCsv(true)}}
Argument: includeHeaders.

col_1,col_2,col_3
value1,value2,value3

gridAsHtml

{{fields["grid"] | gridAsHtml(true)}}
Argument: includeHeaders. One table row per grid row.

col_1	col_2	col_3
value1	value2	value3

gridAsVerticalHtml

{{fields["grid"] | gridAsVerticalHtml()}}
One block per grid row, with each column as a label and value.

Entry #1
col_1:	Value 1
col_2:	Value 2
Entry #2
col_1:	Value 1
col_2:	Value 2

The HTML methods are useful in emails and generated PDFs. They output a plain <table>; the examples above use this CSS, which you can add to your template:

CSS

<style>
  table, th, td {
    border: 1px solid;
    padding: 12px 15px;
    border-collapse: collapse;
  }
</style>

Likert fields

A Likert field returns its whole results table:

{{fields["likert_field_id"]}}

To get the answer to one question, use property with the question id:

{{fields["likert_field_id"] | property("question_id")}}

Barcodes

Generates a barcode image as a Base64 encoded string.

{{barcode("value")}}
{{barcode("value", "type")}}
{{barcode("value", "type", "dpi")}}

Argument	Description	Default
`value`	The text to encode. Can be a placeholder value, such as `fields["barcode_value"]`.	Required
`type`	`Pdf417`, `QR` or `Code128`.	`Pdf417`
`dpi`	Resolution in dots per inch.	`96`

To show the barcode in a generated PDF in indexing or forms, use it as an image source:

<img src="{{barcode(fields["barcode_value"], "QR")}}"/>

Worked examples

Show text only when a field has a value

{{fields["workflow"] | exists() | condition(format("{0} || uA1 || new workflow", fields["workflow"]), "")}}

fields["workflow"] gets the field value.
exists() returns true if it has a value.
condition(...) chooses the output: if true, format(...) builds the text, replacing {0} with the field value; if false, it returns an empty string.

Format an amount, or show a message if there isn't one

{{fields["gst_amount"] | greaterThan(0) | condition(format("${0}", fields["gst_amount"]), "No GST")}}

Returns the GST amount with a dollar sign, such as $12.50, if it's greater than 0. Otherwise returns No GST.

Nested calculations

{{multiply(add(fields["value1"], fields["value2"]), subtract(fields["value1"], fields["value2"]))}}

Calculates (value1 + value2) × (value1 − value2).

Build a safe file name

{{fields["title"] | sanitiseText("toAscii", "invalidFilenameCharacters") | trim()}}

Converts the title to plain ASCII, removes characters that aren't allowed in file names, and trims surrounding spaces. For example, Café: “Q1/Q2” Report becomes Cafe Q1Q2 Report.

Age from a date of birth

Calculates the number of whole years between a date field and today. Replace DATE_FIELD_ID with the id of the date field.

{{fields["DATE_FIELD_ID"] | asDate("yyyy-MM-dd") | format("{0:MM}") | greaterThanEquals(date | format("{0:MM}")) | condition(fields["DATE_FIELD_ID"] | asDate("yyyy-MM-dd") | format("{0:MM}") | equals(date | format("{0:MM}")) | condition(fields["DATE_FIELD_ID"] | asDate("yyyy-MM-dd") | format("{0:dd}") | greaterThan(date | format("{0:dd}")) | condition(subtract(date | format("{0:yyyy}"), fields["DATE_FIELD_ID"] | asDate("yyyy-MM-dd") | format("{0:yyyy}"), "1"), subtract(date | format("{0:yyyy}"), fields["DATE_FIELD_ID"] | asDate("yyyy-MM-dd") | format("{0:yyyy}"))), subtract(date | format("{0:yyyy}"), fields["DATE_FIELD_ID"] | asDate("yyyy-MM-dd") | format("{0:yyyy}"), "1")), subtract(date | format("{0:yyyy}"), fields["DATE_FIELD_ID"] | asDate("yyyy-MM-dd") | format("{0:yyyy}")))}}

Method index

Area	Methods
Text	`format`, `toLower`, `toUpper`, `toTitle`, `toSentence`, `trim`, `replace`, `split`, `left`, `right`, `sanitiseText`, `coalesce`
Dates	`asDate`, `asVariableDate`, `asFinancialYear`, `asFinancialMonth`
Numbers	`add`, `subtract`, `multiply`, `divide`, `math`, `sum`, `round`
Conditions	`exists`, `equals`, `startsWith`, `endsWith`, `contains`, `matches`, `greaterThan`, `greaterThanEquals`, `lessThan`, `lessThanEquals`, `condition`
Error handling	`nullable`
Collections	`join`, `count`, `pivot`
Objects	`property`, `attribute`, `kfiDeserialise`
Grids	`cell`, `count`, `join`, `sum`, `gridAsText`, `gridAsCsv`, `gridAsHtml`, `gridAsVerticalHtml`
Barcodes	`barcode`