# Formatting Your Data
Here is a list of available modifiers/helpers. These modifiers/helpers are added along with the tokens(merge field).
| Modifier/Helper | Description | Example |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Uppercase | Convert all characters to uppercase | **{{upper FieldName}}** |
| Lowercase | Convert all characters to lowercase | **{{lower FieldName}}** |
| Capitalize |
Capitalize the first letter
Camel Cased Sentence
|
{{capitalize FieldName}}
{{capitalize FieldName format="words"}}
|
| Abbreviation | Convert text to abbreviation (First letter of each word in caps) | **{{abbreviate FieldName "."}}** |
| Pad | Appends or prepends a single character repeatedly to fill input to given width. |
{{pad number 9}}
{{pad number 5 pad\_with='\*' style='suffix'}}
|
| Concat | Appends text. | **{{concat string1 string2}}** |
| Format Date | Change the format of date, datetime |
|
| Format Number | Change the format of a number (thousands and decimals) |
{{format\_number number decimal\_separator="."}} {{format\_number number thousand\_separator=","}} {{format\_number number precision="2"}} {{format\_number number thousand\_separator="," decimal\_separator="." precision="3"}}
|
| Format Phone |
Change the format of your phone number. It can also be used to format a number
| **{{format\_phone landline "(%3) %3-%4"}}** |
| Number to words | Converts the input number in to words. | **{{number\_to*****\_*****words input}}** |
| Number to Ordinal | Converts the input number to its ordinal form, in words. | **{{number\_to\_ordinal input}}** |
| Join | Joins the input array of strings with given separator (defaults to `,`) |
{{join items ", "}}
{{join FieldName ", " lookup="object.name"}}
|
| Replace | Replaces the match string from input with given replace string | **{{replace str1 str2}}{{replace FieldName (regex "\[0-9]" "g") "\*"}}** |
| Regex | Return a RegExp class instance with given pattern and flags | **{{replace FieldName (regex "(0-9)" "g") "\*"}}** |
| Split | Splits input with given separator (defaults to `,`) | **{{#each (split Fieldname ", ")}} ... {{/each}}** |
| Strip | Strips the input of given match characters (defaults to white space) from given position (`left` or `right` or `both`) |
{{strip FieldName}}
{{strip FieldName "\*" side="left"}}
|
| Sort | Sorts input in the given order (`asc` , `desc`) |
{{# list (sort FieldName lookup="price" order="asc")}} ... {{/list}}
|
| Insert Link | Inserts a URL or Hyperlink in the document | **{{insert\_link url text="clickable display text"}}** |
| Url Encode | Replaces special characters inside a URL with encoded text. | **{{url\_encode URL is\_url=true\|false}}** |
| Url Decode | Decodes encoded URLs into pre-encoded forms. | **{{url\_decode URL is\_url=true\|false}}** |
| Rand | Returns a random value between the specified minimum and maximum values. | **{{rand min max}}** |
| As Number | Converts any given input to a valid number. | **{{as\_number FieldName}}** |
| As String | Converts any given input to a valid string. | **{{as\_string FieldName}}** |
| As Boolean | Converts any given input to True or False. | **{{as\_boolean FieldName}}** |
## **Format Date/Time**
To print date and time in desired format in the document, use this formatter. Format, Locale, and Offset can be adjusted.
#### Syntax
```
{{format_date token_name format="format" input_format="input format" locale="language_code" offset="add/subtract time"}}
```
* **format** - defines output format of the date/time
* **input\_format** - defines the input format of your date string (this must be used for consistent date interpretation if your input format is different from ISO format)
* **language** - output language for date/time. See supported languages below.
* **offset** - add/subtract offset to a given date. This can be used to calculate due dates, valid-until, etc. See offset examples below.
#### Examples:
### Parsing dates accurately with Input Format
If the date values you pass to your date fields are in a specific format (for example, `DD/MM/YYYY`), you can use the `input_format` parameter to specify the format of your input dates.
Example - Syntax:
```
{{format_date due_date input_format='DD/MM/YYYY' format=”dddd, DD MMMM YYYY”}}
```
Input data:
```
due_date = '31/12/2025'
```
Output:
```
Tuesday, 08 April 2025
```
If input\_format is not used, the due\_date value will be treated as an invalid date and the input date will be printed as-is on the document.
### Add/Subtract Time - Manipulate a date and/or time by adding/subtracting time
To adjust a date/time by a specific amount, you need to supply `<+/-> ` as the value for offset. Unit can be "years", "months", "weeks", "days", "hours", "minutes", or "seconds". Here are some examples:
* `+1hours`
* `-3days`
* `+5years+2months-3minutes`
* `+8h`
| Example | Input | Output |
| -------------------------------------------------------------------------- | :--------: | :---------------: |
| `{{format_date _date format="MMMM DD YYYY" locale="en" offset="+1years"}}` | 2019-08-20 | August 20 2020 |
| `{{format_date _date format="MMMM DD, YYYY" offset="+6months"}}` | 2019-08-20 | February 20, 2020 |
| `{{format_date _date offset="+1years"}}` | 2019-08-20 | 08-20-2020 |
## Format Number
This helper can be used to change the format of a number, including its thousands with separators, decimal with separators and precision.
#### Syntax
```
{{format_number number output_format="in" thousand_separator="thousand_sep" decimal_separator="decimal_sep" precision="number_of_decimal_places"}}
```
* **output\_format** (optional) - desired format of the number. Supported formats:
* **default** - millions, billions.
* **in** - lakh, crore.
* **thousand\_separator** (optional, default: `,` comma) - the character the should be used to separate thousands position.
* **decimal\_separator** (optional, default: `.`period) - the character that should be used to separate decimals.
* **precision** (optional, default: not-set) - number of decimal places required.
{{format_number number output_format="in" thousand_separator="," decimal_separator="." precision="2"}}
87904.987
87,904.99
## Abbreviation
The **`abbreviate`** formatter allows you to automatically generate abbreviations by extracting the first letter of each word in a given text field and capitalizing it. This is useful for standardizing text and ensuring consistency in documents.
#### **Syntax:**
```
{{abbreviate token separator}}
```
* `token`: The field from which the abbreviation will be generated.
* `separator` (optional): A character or string to place between the extracted letters. If omitted, the abbreviation will be formed without separators.
#### Example Usage:
| Input Text | Syntax | Output |
| ----------------------- | --------------------------------- | ------ |
| United Nations | `{{abbreviate Organization}}` | UN |
| Central Processing Unit | `{{abbreviate partName "-"}}` | C-P-U |
| John Doe | `{{abbreviate customerName "."}}` | J.D |
## Format Phone
The **`format_phone`** formatter allows you to format phone numbers according to a specified pattern, ensuring consistency and readability in your documents.
**Syntax:**
```
{{format_phone landline format}}
```
* `landline`: The field containing the phone number.
* `format`: The desired format for the output. Ex: `(%3) %3-%4`
Input
Syntax
Output
landline=1234567890
{{format_phone landline "(%3) %3-%4"}}
(123) 456-7890
landline=9876543210
{{format_phone landline "+1-%3-%3-%4"}}
+1-987-654-3210
id_number=123456789012
{{format_phone id_number "%4-%4-%4"}}
1234-5678-9012
## Number to words
The **Number to Words** helper in Docupilot allows you to convert numeric input into words. This functionality supports customizable output formats, including options for language and currency.
#### Syntax
```
{{number_to_words input output_format="in" suffix=" " decimal_suffix=" " language=" "}}
```
* `input`: The numeric value to be converted.
* `output_format` (optional): Defines the format (default: `us`).
* `suffix` (optional): Adds a suffix for currency or other units (e.g., `dollars`, `kg`).
* `decimal_suffix` (optional): Defines a suffix for decimal parts if applicable (e.g., `cents`, `paise`).
* `language` (optional): Specifies the language for the output text. Learn more about available languages [here](#language).
| Example | Input | Output |
| ---------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `{{number_to_words number}}` | 123456 | one hundred and twenty-three thousand four hundred and fifty-six |
| `{{capitalize (number_to_words amount suffix="dollars" decimal_suffix="cents")}}` | 800.658 | Eight hundred dollars six hundred and fifty-eight cents |
| `{{number_to_words currency output_format="in" suffix="rupees" decimal_suffix="paise"}}` | 9893.567 | nine thousand eight hundred and ninety-three rupees five hundred and sixty-seven paise |
| `{{number_to_words price output_format="in" suffix="rupees"}}` | 7000000 | seventy lakh rupees |
| `{{number_to words price suffix="dollars"}}` | 7000000 | seven million dollars |
| `{{number_to_words input language="fr"}}` | 8795 | huit mille sept cent quatre-vingt-quinze |
| `{{number_to_words price suffix="Euros" decimal_suffix="Cents" language="de"}}` | 8790.345 | achttausendsiebenhundertneunzig Euros dreihundertfünfundvierzig Cents |
{% hint style="info" %}
Note:
* The output is always in **words**.
* Decimals will be converted separately using the `decimal_suffix`.
* Use `capitalize` if the first letter needs to be uppercase.
{% endhint %}
## Number to Ordinal
The `number_to_ordinal` formatter converts a numeric input into its ordinal form, expressed in words. This is useful for formatting numbers in legal, financial, or formal documents.
#### Syntax
```
{{number_to_ordinal number}}
```
* `number`: The numeric value to be converted into an ordinal.
#### Example Usage
#### Basic Conversion
```
{{number_to_ordinal number}}
```
**Input:**
```
number = 800
```
**Output:**
```
eight hundredth
```
#### Capitalizing Ordinal Output
```
{{capitalize (number_to_ordinal number1)}}
```
**Input:**
```
number1 = 582
```
**Output:**
```
Five hundred and eighty-second
```
#### Handling Decimal Values
```
{{number_to_ordinal number}}
```
**Input:**
```
number = 789.325
```
**Output:**
```
seven hundred and eighty-ninth
```
{% hint style="info" %}
Note:
* The output is always in **words**.
* Decimals are ignored when determining the ordinal form.
* Use `capitalize` if the first letter needs to be uppercase.
{% endhint %}
## Join
The **Join** helper in Docupilot allows you to combine an array of strings or extract and join a specific property from a list of objects into a single string, using a specified separator. If no separator is provided, a comma (`,`) is used by default.
#### Syntax
```
{{join content separator lookup="lookup_key"}}
```
* `content`: The array of strings to join.
* `separator` (optional): The character or string to separate values (default: `,`).
* `lookup` (optional): The key to extract values from objects in an array.
#### Example Usage
#### Joining a Simple List with a Comma
```
{{join SampleName ","}}
```
**Input:**
```json
[
"John",
"Mary",
"Paul"
]
```
**Output:**
```
John,Mary,Paul
```
#### Joining Object Values Using a Lookup Key
```
{{join employees lookup="Name.Firstname"}}
```
**Input:**
```json
[
{"Name": {"Firstname": "Peter", "Lastname": "Parker"}},
{"Name": {"Firstname": "Tony", "Lastname": "Stark"}},
{"Name": {"Firstname": "Steve", "Lastname": "Rogers"}}
]
```
**Output:**
```
Peter,Tony,Steve
```
{% hint style="info" %}
Note:
* If `lookup` is provided, the helper will extract the specified key from each object before joining.
* The separator can be any character (e.g., `|`, `;`, `-`).
{% endhint %}
## Replace
The **`replace`** formatter allows you to replace specific text or patterns within a string using either direct text matching or regular expressions (regex). This is useful for modifying content dynamically in templates.
#### Syntax
```
{{replace input match_str replace_str}}
```
* `input`: The text to be processed.
* `match_str`: The text or regex pattern to match.
* `replace_str`: The replacement string.
#### Example Usage
**Replacing a Specific Word**
```
{{replace text find replace}}
```
**Input:**
```
text = "Mary Ross"
find = "Ross"
replace = "Jane"
```
**Output:**
```
Mary Jane
```
**Replacing Characters Using Regex**
```
{{replace input (regex "[a]" "g") "e"}}
```
**Input:**
```
input = "Ragax"
```
**Output:**
```
Regex
```
**Using Regex with Replace**
Regex can be used to match multiple occurrences dynamically:
```
{{replace text (regex "[0-9]+" "g") "#"}}
```
**Input:**
```
text = "ID12345XYZ678"
```
**Output:**
```
ID#XYZ#
```
{% hint style="info" %}
Note:
* `match_str` can be either a direct text match or a regex pattern.
* Regex patterns must be enclosed within `(regex "pattern" "flags")`.
* the `g` (global) flag ensures multiple occurrences are replaced.
{% endhint %}
## Regex
The **Regex** helper in Docupilot allows you to apply regular expressions to manipulate text dynamically in your templates. It is useful for pattern matching, replacing, or extracting specific content from text fields.
#### Syntax
```
{{regex pattern flags}}
```
* `pattern`: The regular expression pattern to apply.
* `flags` (optional): Regex flags for customization (default: no flags set).
* Commonly used flags:
* `g` (global) - Applies the regex to all matches.
* `i` (case insensitive) - Ignores case differences.
* `m` (multi-line) - Allows multi-line matching.
#### Example Usage
#### Replacing Lowercase Letters with Asterisks
```
{{replace text (regex "[a-z]" "g") "*"}}
```
**Input:**
```
text = "MaryJane123"
```
**Output:**
```
M***J***123
```
**Replacing Numbers with a Symbol**
```
{{replace text (regex "[0-9]+" "g") "$"}}
```
**Input:**
```
text = "1239HomeAlone42"
```
**Output:**
```
$HomeAlone$
```
#### Extracting Only Numbers
```
{{replace text (regex "[0-9]+" "g") "*"}}
```
**Input:**
```
text = "My number is 456 and my ID is 7890."
```
**Output:**
```
My number is *** and my ID is ****.
```
{% hint style="info" %}
**Note**
* **Regex must be used with a helper like `replace`, `match`, or `test`.**
* Ensure that the regex pattern is correctly formatted.
* Flags modify how the pattern behaves (e.g., `g` for multiple matches).
{% endhint %}
## Strip
The **Strip** helper in Docupilot allows you to remove specific characters from the beginning, end, or both sides of a given input. By default, it removes whitespace.
#### Syntax
```
{{strip input match_str side="left"}}
```
* `input`: The string from which characters will be removed.
* `match_str` (optional): The characters to be stripped (default: whitespace).
* `side` (optional): Determines where to remove characters from. Options:
* `left`: Removes from the beginning.
* `right`: Removes from the end.
* `both` (default): Removes from both sides.
#### Example Usage
#### Removing Whitespace (Default Behavior)
```
{{strip text}}
```
**Input:**
```
text = " Hello World "
```
**Output:**
```
Hello World
```
#### Removing Specific Characters
```
{{strip text "-"}}
```
**Input:**
```
text = "---Hello---"
```
**Output:**
```
Hello
```
#### Stripping Characters from the Left Side
```
{{strip text "0" side="left"}}
```
**Input:**
```
000123450
```
**Output:**
```
123450
```
#### Stripping Characters from the Right Side
```
{{strip "text" "%" side="right"}}
```
**Input:**
```
text = "12345%%%"
```
**Output:**
```
12345
```
{% hint style="info" %}
Note:
* If `side` is omitted, the default behavior removes characters from both sides.
* `match_str` can be any character or set of characters.
* If `match_str` is not specified, only whitespace is removed.
{% endhint %}
## Split
The **`split`** formatter allows you to break a string into an array based on a specified separator. This is useful for handling lists or structured text in templates.
**Syntax:**
```
{{split input separator}}
```
* `input`: The string to be split.
* `separator` (optional): The delimiter used for splitting. This can be a text character or a **regular expression** (Regex). If omitted, the default separator is `,` (comma).
#### Example Usage
#### Splitting by Default Separator (Comma)
```
{{#each (split items)}}
{{this}}
{{/each}}
```
**Input:**
```
items = "apple,banana,cherry"
```
**Output:**
```
apple
banana
cherry
```
#### Splitting by Custom Separator
```
{{#each (split people "|")}}
{{this}}
{{/each}}
```
**Input:**
```
people = "John|Doe|Smith"
```
**Output:**
```
John
Doe
Smith
```
#### Splitting Using Regex:
```
{{#each (split text (regex "\d+" "g"))}}
{{this}}
{{/each}}
```
**Input:**
```
text = John1Doe2Cleveland
```
**Output:**
```
John
Doe
Cleveland
```
{% hint style="info" %}
Note:
* **Split is a nested formatter**, meaning it must be used within other formatters like `each` or `list`.
* When splitting on spaces, use `" "` as the separator.
* *See* [*Regex*](#regex) *for more information on how to use Regular Expressions.*
{% endhint %}
## Sort
The **Sort** helper in Docupilot allows you to arrange data in ascending (`asc`) or descending (`desc`) order based on a specified key. This is useful for organizing lists dynamically in templates.
**Syntax**
```
{{sort content order=order lookup="lookup_key"}}
```
* `content`: The array or list to be sorted.
* `order`: The sorting order (`asc` for ascending, `desc` for descending).
* `lookup` (optional): The key used for sorting within objects.
#### **Example Usage:**
**Sorting Numbers:**
```
{{#each (sort cost order="desc")}}
{{this}}
{{/each}}
```
**Input:** `[100, 50, 200]`
**Output:**
```
200
100
50
```
**Sorting Objects by a Key:**
```
{{#each (sort items lookup="price" order="asc")}}
{{name}} is available at {{price}} per {{unit}}.
{{/each}}
```
**Input:**
```
[
{"name": "Apple", "price": 3, "unit": "kg"},
{"name": "Banana", "price": 1, "unit": "kg"},
{"name": "Cherry", "price": 2, "unit": "kg"}
]
```
**Output:**
```
Banana is available at 1 per kg.
Cherry is available at 2 per kg.
Apple is available at 3 per kg.
```
{% hint style="info" %}
Note:
* **Sort is a nested formatter**, meaning it must be used within other formatters like `each` or `list`.
* The **lookup key** is required when sorting objects.
* Sorting is case-sensitive; ensure consistent casing in text-based sorting.
{% endhint %}
## Filter
The `filter` helper can be used to refine lists by applying specific conditions, effectively narrowing down the data to what's most relevant. The syntax for the `filter` helper is `{{filter items condition}}`, where `items` is the list to be filtered and `condition` is the criteria applied to each item. Conditions can range from straightforward comparisons, like `(department == "Sales")`, to more complex expressions like `((LeadScore > 60 and LeadScore <= 80) and LeadRole == "vp" and LeadIndustry == "Healthcare")`. Here are a few examples showcasing the versatility of the `filter` helper:
1. Print a list of employees from Sales department and their salaries:
```
{{#each (filter Employees (Department == "Sales"))}}
{{FirstName}} | {{LastName}} | {{Salary}}
{{/each}}
```
2. Filter can be combined with sort to handle more advanced use-cases: For example, to print list of products in inventory that are priced higher than or equal to 50$ in descending order of price:
```
{{#each (sort (filter InventoryItems (Price >= 50)) order="desc" lookup="Price")}}
{{ProductName}} | {{Cateogory}} | {{Price}} | {{Margin}}
{{/each}}
```
3. Filtering a list of events to include only those happening in December
```
Following is the event catalog for December:
{{#each (filter Events (Month == "December"))}}
{{EventName}} takes place on {{EventScheduleDate}} at {{EventScheduleTime}}
{{/each}}
```
4. Above example can be modified further to make the month dynamic too, but we need to use Look-backs to achieve the same:
```
Following is the event catalog for {{DesiredMonth}}:
{{#each (filter Events (Month == ../DesiredMonth))}}
{{EventName}} takes place on {{EventScheduleDate}} at {{EventScheduleTime}}
{{/each}}
```
5. Filtering a collection of books to display only those published after the year 2000
```
{{#each (filter Books (PublishedYear > 2000))}}
{{BookName}} | {{Author}} | {{PublishedYear}}
{{/each}}
```
6. Filter a dataset to exclude items marked as inactive
```
{{#each (filter dataSet (status != "inactive"))}}
{{property1}} - {{property2}}
{{/each}}
```
7. Filter Leads that are VPs in Healthcare with lead score greater than 80
```
{{#each (filter Leads (LeadScore > 80 and (lower LeadRole) == "vp" and LeadIndustry == "Healthcare"))}}
{{LeadName}} | {{LeadEmail}} | {{LeadScore}}
{{/each}}
```
8. Print Leads that are from Healthcare or Pharma industry with lead score higher than 80 but lower than 95, in descending order of lead score.
```
{{#each (sort (filter Leads ((LeadIndustry == "Healthcare" or LeadIndustry == "Pharma") and (LeadScore > 80 and LeadScore < 95))) order="desc" lookup="LeadScore")}}
{{LeadName}} | {{LeadEmail}} | {{LeadScore}}
{{/each}}
```
These examples demonstrate the `filter` helper's capability to perform both simple and complex data filtering within a template, making it an essential tool for crafting dynamic content.
Example Template using Filter helper
Example Output using Filter helper
{% hint style="info" %}
Note:
* **Filter is a nested formatter**, meaning it must be used within other formatters like `each` or `list`.
* The **condition** is required when filtering a list of items.
{% endhint %}
## Set and Get
**`{{set ...}}`** and **`{{get ...}}`** can be used to store values and access them later in your template. This is useful when you want to assign calculated values, reuse data, or simplify complex logic.
Syntax:
```
{{set "variable_name" "value"}}
{{get "variable_name"}}
```
* **set** stores a value to a variable name.
* **get** retrieves the stored value for later use.
**Example 1:**
Template:
```
{{set "name" "New York"}}
Welcome to the city {{get "name"}}
```
Output:
```
Welcome to the city New York
```
**Example 2:**
Template:
```
{{set "total" (calc "Price * Qty")}}
Total Amount: {{get "total"}}
```
Input:
```
Price = 100; Qty = 5
```
Output:
```
Total Amount: 500
```
**Example 3:**
Template:
```
{{set "discountPercentage" 20}}
{{#each items}}
{{#if (amount > 500)}}{{set "discountPercentage" 50}}{{/if}}
{{name}} @ {{amount}}
{{/each}}
Discount percentage to be applied = {{get "discountPercentage"}}%
```
Input1:
Output2:
```
ServiceMini @ 20
ServiceMega @ 550
Discount percentage to be applied = 50%
```
{% hint style="warning" %}
**`set`** and **`get`** are recommended over the older **`var`** for better clarity and future compatibility. **`var`** is in now legacy and should be avoided in all new templates.
{% endhint %}
## Var (legacy)
The `var` is a powerful tool designed for both storing and retrieving data within templates, enabling dynamic variable use. This functionality allows users to assign values to tokens directly within their documents through a simple syntax: `{{var "token" value}}`. For instance, assigning a numerical value or even transferring values between tokens is effortlessly done using `{{var "cost" 500}}` or `{{var "amount" MRP}}`, respectively. Retrieving the stored data is just as straightforward; by calling `{{var "token"}}`, the value assigned to the specified token is seamlessly inserted into the document.
#### Storing Data
Syntax: `{{var "token" value}}`
| Example | Output |
| ---------------------- | ------------------------------------------------------------ |
| `{{var "cost" 500}}` | Here the token cost is assigned a value of 500. |
| `{{var "price" 7599}}` | Here the token price is assigned a value of 7599. |
| `{{var "amount" MRP}}` | Here the value in token MRP is assigned to the token amount. |
#### Retrieving Data
Syntax: `{{var "token"}}`
| Example | Output |
| ----------------- | ------ |
| `{{var "cost"}}` | 500 |
| `{{var "price"}}` | 7599 |
## Pad helper
Pad helper fills up the input to the desired width by adding a single character repeatedly either at the beginning or at the end.
Syntax: `{{pad number output_width pad_with='character' style='prefix|suffix'}}`
Example 1:\
`{{pad number 7}}`
| Input | Output |
| ----- | ------- |
| 123 | 0000123 |
Example 2:\
`{{pad number 9 pad_with='#' style='suffix'}}`
| Input | Output |
| ------ | --------- |
| 123456 | 123456### |
## Aggregate
Aggregate functionality helps to accumulate data from a collection of items to return a single result (like adding numbers in a list). It is useful in scenarios like invoice processing, where it can compute totals such as the total number of items sold, invoice sub total, grand total, factoring in discounts, etc.
Example: Consider a case where you want to generate an invoice which can auto-calculate quantity sold, sub total and grand total. Assuming `InvoiceLineItems` is the field which contains all line items where each line item contains properties: `name`, `qty` , `unit_price` and `discount`.
To calculate the total number of items sold as part of this invoice, we need to add `qty` from each line item. It can be done using:
`{{aggregate InvoiceLineItems formula="qty" operation="add"}}`
To compute the invoice total before applying any discounts, we need to add the result of `qty * unit_price` from each line item. This can be achieved using:
`{{aggregate InvoiceLineItems formula="qty * unit_price" operation="add"}}`
To compute discounted invoice total where discounts are applicable as percentage for each line item separately, we need to add the result of `qty * unit_price * (1 - discountPercentage / 100)` for each line item.
`{{aggregate InvoiceLineItems formula="qty * unit_price * (1 - discountPercentage / 100)" operation="add"}}`
*Note that each operator inside formula should have a leading and trailing space to work accurately. For example "qty\*unit\_price" will not work, only "qty \* unit\_price" will. This limitation may be addressed in one of our future updates.*
Sample Invoice using aggregate helper - Input
Sample Invoice using aggregate helper - Output
## Concat
Syntax : `{{concat string1 string2 ....}}`
Example:\
`{{insert_image (concat "https:" url) 300 300}}`
Input:\
`//raw.githubusercontent.com/tiholic/exif-orientation-examples/master/Portrait_0.jpg`
Output:
## Group By
Group by helper groups the data with the value of lookup key as grouping criteria.
Syntax: `{{group_by ListName lookup="lookup_key"}}`
`Key` and `items` can be accessed from inside the iterator(`#each` or `#list`). `Key` contains value of `"lookup_key"` for the current record, `items` contain the records which are present under current group.
**Example 1:**
In this example:
* `employees` is the list being grouped.
* `lookup="Department"` groups the list based on the `Department` field.
* `{{key}}` holds the current group value (i.e., department name).
* `items` contains all employees in that department.
* The inner loop ( `{{#each items}}...{{/each}}` ) displays each employee’s ID, name, and designation under their respective department.
{% hint style="info" %}
In case if you are using this inside a table, ensure to merge all cells in the rows with opening or closing of each.
{% endhint %}
**Sample Input:**
| Emp\_ID | Employee\_Name | Designation | Department |
| ------- | -------------- | ----------- | ---------- |
| E001 | Alice | Analyst | Sales |
| E002 | Bob | Manager | HR |
| E003 | Charlie | Associate | HR |
| E004 | John | Executive | Sales |
**Sample Output :**
This will generate output grouped by department, with employee details listed under each.
**Example 2:**
```handlebars
{{#each (group_by employees lookup="role.code")}}
Number of employees in role {{key}}: {{items.length}} and they are {{join items ", " lookup="name.first"}}
{{/each}}
```
Input: *(JSON)*
```json
{
"employees": [
{ "role": {"code": "TL"}, "name": {"first": "Dave" } },
{ "role": {"code": "TL"}, "name": {"first": "Chris"} },
{ "role": {"code": "PM"}, "name": {"first": "Matt" } },
{ "role": {"code": "TL"}, "name": {"first": "Emma" } },
{ "role": {"code": "PM"}, "name": {"first": "Jenn" } }
]
}
```
Output :
```
Number of employees in role TL: 3 and they are Dave, Chris, Emma
Number of employees in role PM: 2 and they are Matt, Jenn
```
In the above example,
* **"TL"** and "**PM"** are the group **`keys`**.
* `items` corresponding to the key "**TL"** are :
* `{ "role": { "code": "TL" }, "name": { "first": "Emma" } }`
* `{ "role": { "code": "TL" }, "name": { "first": "Chris" } }`
* `{ "role":{ "code": "TL" }, "name": { "first": "Dave" } }`
* `items` corresponding to the key "**PM"** are:
* `{ "role": { "code": "PM" }, "name": { "first": "Jenn" } }`
* `{ "role": { "code": "PM" }, "name": { "first": "Matt" } }`
**Example 3:**
```handlebars
{{#each (group_by places)}}
Number of branches in {{key}}: {{items.length}}
{{/each}}
```
Input: *(JSON)*
```json
{
"places": [
"New York",
"Las Vegas",
"Chicago",
"New York",
"Las Vegas",
"New York"
]
}
```
Output:
```
Number of branches in New York: 3
Number of branches in Las Vegas: 2
Number of branches in Chicago: 1
```
In the above example,
* **"New York"**, "**Las Vegas"** and "**Chicago"** are the group `keys`.
* Number of `items` corresponding to the key "**New York"** are 3.
* Number of `items` corresponding to the key "**Las Vegas"** are 3.
* Number of `items` corresponding to the key "**Chicago"** is 1.
## Inserting a link
To insert a dynamic URL into your document.
Format: **`{{insert_link url text=text}}`**
#### Hyperlink style customization in Word documents
Inserted hyperlinks follow the source style in Builder templates. In case of Word Document templates, style customization can be done by opening **Format > Styles > Search and select "Hyperlink" >** click **Modify > Update to desired style** and click **Ok**
## URL encode
URL encode helper replaces special characters inside a URL with encoded text.
Syntax : `{{url_encode URL is_url=true|false}}`
**Example1:**
Syntax in Template
```handlebars
{{url_encode url is_url=true}}
```
Input sent to the template (JSON):
```json
{
"url": "https://dummyimage.com/600x400/000/fff&text=hello world"
}
```
Generated Output:
```
https://dummyimage.com/600x400/000/fff&text=hello%20world
```
**Example2:**
Syntax in Template
```handlebars
https://example.com?open={{url_encode url_part is_url=false}}
```
Input sent to the template (JSON):
```json
{
"url_part": "https://dummyimage.com/600x400/000/fff&text=hello world"
}
```
Generated Output:
```
https://example.com?open=https%3A%2F%2Fdummyimage.com%2F600x400%2F000%2Ffff%26text%3Dhello%20world
```
## URL decode
URL decode helper decodes encoded URLs into pre-encoded forms.
Syntax : `{{url_decode URL is_url=true|false}}`
**Example1:**
Syntax in Template
```handlebars
{{url_decode url is_url=true}}
```
Input sent to the template (JSON):
```json
{
"url": "https://dummyimage.com/600x400/000/fff&text=hello%20world"
}
```
Generated Output:
```
https://dummyimage.com/600x400/000/fff&text=hello world
```
**Example2:**
Syntax in Template
```handlebars
{{url_decode url is_url=false}}
```
Input sent to the template (JSON):
```json
{
"url": "https%3A%2F%2Fdummyimage.com%2F600x400%2F000%2Ffff%26text%3Dhello%20world"
}
```
Generated Output:
```
https://dummyimage.com/600x400/000/fff&text=hello world
```
{% hint style="warning" %}
Encoding or decoding a URL depends on the value of the parameter 'is\_url'. If the value is true, only the query parameter part of the complete URL is encoded/decoded else, the whole of the URL is encoded/decoded.\
The Default value of is\_url is set as false.
{% endhint %}
## Rand
Rand will return a random value between the min and max values passed.
Syntax: `{{rand min max}}`
| Example | Input | Output |
| ------------------------ | ------------------------- | -------------------------------------------------------------------- |
| {{rand min max}} |
min: 2 max: 500
|
could be any random number between 2 and 500 Ex: 436.89318
|
| {{round (rand min max)}} |
min: 2 max: 500
|
could be any random integer value
ex: 437
|
{% hint style="info" %}
**rand** returns a decimal value between the given min and max. Use **round** along with **rand** to get an integer value.
{% endhint %}
## As Number
As Number converts any given input to a valid number.
Syntax: `{{as_number FieldName}}`
| Example | Input | Output |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------ |
| {{as\_number value}} | value: "**23.000**"(string) | **23**(numerical value) |
|
{{#if (as\_number input\_value) "<=" 100}} Value is less than 100. {{else}} Value is greater than 100. {{/if}}
| input\_value: "**98.767**"(string) | **Value is less than 100.** |
|
{{#if (as\_number input\_value) "<=" 100}} Value is less than 100. {{else}} Value is greater than 100. {{/if}}
| input\_value: "**101.9876**"(string) | **Value is greater than 100.** |
## As String
As String converts any given input to a valid string.
Syntax: `{{as_string FieldName}}`
## As Boolean
As Boolean converts any given input into Boolean values **0**(False) and **1**(True).
String: `{{as_boolean FieldName}}`
Example
Input
Output
{{as_boolean value}}
value: 348
1(True)
{{as_boolean input_value}}
input_value: 0
0(False)
{{#if (as_boolean input_value)}} Input received. {{else}} Input is empty. {{/if}}
input_value: 123.9
Input received
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.docupilot.app/document-template/formatting-your-data.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.