> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/reference/process-development/handlebars.md).

# Handlebars

Low-code feature in Frends.

Handlebars is a templating syntax in Frends that lets you embed C# expressions and reference values into text-based parameter fields. Rather than switching an entire field to an Expression type, Handlebars allows most of the field to remain as readable plain text while selected parts are resolved dynamically at runtime. This makes it particularly useful for building JSON payloads, XML messages, SQL statements, file names, URLs, and other textual content where only a few values need to come from the Process context.

## How Handlebars works

Any content placed inside double curly braces is treated as a Handlebars expression.

```handlebars
Customer {{#var.CustomerID}} requested {{#var.ProductName}}.
```

The part outside `{{ }}` is treated as a text literal and passed through as-is. The part inside `{{ }}` is treated as a C# expression and evaluated at runtime. The resolved value is then inserted in place of the expression block.

Because Handlebars performs an implicit `ToString()` conversion, any C# value — number, boolean, date, or object property — is automatically converted to a string before it is inserted into the surrounding text. This is equivalent to wrapping the expression in a C# formatted string interpolation:

```csharp
$"{#var.CustomerID.ToString()}"
```

This means it is often more convenient to use Handlebars to insert a single value into a text field than to switch the field type to Expression just to call `.ToString()` on the result.

### Compilation and runtime evaluation

When you save a Process, Frends compiles it to C#. During this compilation, the structure and syntax of Handlebars expressions are validated alongside the rest of the Process. Type mismatches and syntactically invalid expressions are caught at save time.

The actual values, however, are resolved at runtime. This means errors that depend on runtime data — such as a null reference, an unexpected data shape, or a collection that does not exist — will only surface during Process execution, not when saving.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2FI8D1gLRMkpIh3ZcAvPa8%2Fimage.png?alt=media&amp;token=6c84af44-46b4-41ee-8247-b26abcd1b15e" alt=""><figcaption><p>Handlebars used within a JSON payload mapping.</p></figcaption></figure>

### Supported field types

Handlebars can be used in fields of type `Text`, `JSON`, `XML`, and `SQL`. These are all considered text-based types in Frends, and all of them evaluate Handlebars expressions when the Process runs.

Expression fields do not use Handlebars — in those fields, the entire value is already treated as a C# expression. Decision shapes (Exclusive and Inclusive) are locked to Expression fields and require a C# expression that resolves to a boolean. Handlebars should not be used there.

Trigger parameter fields behave differently from standard Process fields. They are treated as plain text and do not evaluate Handlebars or C# code. The only exception is `#env` references, which can be used directly in Trigger parameters without `{{ }}` syntax and are translated into their values before the Process starts.

### Content escaping in structured formats

Because Handlebars inserts the resolved value as raw text, any characters in that value which have special meaning in the target format are not automatically escaped. This can cause problems when inserting user-provided or external data into structured formats such as JSON, XML, or SQL.

#### JSON

In JSON, a string value that contains a quotation mark or a backslash will break the surrounding JSON structure. If `#var.CustomerName` contains the value `O'Brien \"Jr.\"` as a string, inserting it directly into a JSON string produces invalid JSON.

```json
{
  "name": "O'Brien \"Jr.\""
}
```

To handle this safely, escape the value before inserting it. For JSON, `JsonConvert.ToString()` from the Newtonsoft.Json library — available by default in Frends — produces a properly quoted and escaped JSON string token. Because it includes the surrounding quotation marks itself, they should be omitted from the template.

```json
{
  "name": {{JsonConvert.ToString(#var.CustomerName)}}
}
```

This produces a valid JSON string regardless of what characters the value contains.

#### XML

For XML, `System.Security.SecurityElement.Escape()` handles characters such as `<`, `>`, `&`, and `\"` that have structural meaning in XML markup.

```xml
<Customer>
  <Name>{{System.Security.SecurityElement.Escape(#var.CustomerName)}}</Name>
</Customer>
```

#### SQL

For SQL fields, prefer parameterized queries where the Task supports them rather than escaping values manually in Handlebars. This avoids the risk of SQL injection when values originate from external input.

## Reference values in Handlebars

Frends reference values — `#var`, `#trigger`, `#env`, `#result`, and `#process` — are the main way to access runtime data inside Handlebars expressions. They follow the same hashtag-based syntax used elsewhere in Frends expressions, but wrapped in `{{ }}` when used in text fields.

```json
{
  "customerId": "{{#var.CustomerID}}",
  "source": "{{#env.Integration.SourceSystem}}",
  "body": "{{#trigger.data.Payload}}",
  "previousResponse": "{{#result[HTTP Request].Body}}",
  "instanceId": "{{#process.InstanceId}}"
}
```

These reference values work the same way as in Expression fields — the difference is only that here they sit inside a text field rather than occupying the entire field. For full details on each reference value type, see the Reference Values page.

## Block helpers

In addition to simple value injection, Frends supports Handlebars block helpers for conditionals and loops. These allow you to include logic directly in text-based fields without falling back to a Code Task or building the logic in a separate shape. This was introduced as part of the low-code improvements in Frends 6.4.

Block helpers use an opening directive such as `{{#if}}` or `{{#each}}` and a matching closing directive such as `{{/if}}` or `{{/each}}`. The directives are case-insensitive and whitespace around them does not affect how the template compiles.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2FhPAbteGGPtXlDhbEknjD%2Fimage.png?alt=media&amp;token=3993aa97-46b4-4cc4-82d8-2072a1081c80" alt=""><figcaption><p>Building a list of Orders as XML with conditional fields.</p></figcaption></figure>

### Conditionals: if, else if, else

The `{{#if}}` block evaluates a condition and includes only the content of the matching branch in the output. Any C# expression that resolves to a boolean can be used as the condition.

```handlebars
{{#if #var.Status == "active"}}
  Customer is active.
{{else if #var.Status == "pending"}}
  Customer is pending approval.
{{else}}
  Customer status is unknown.
{{/if}}
```

The `{{else if}}` clause is optional and can appear multiple times. The `{{else}}` clause is also optional and must appear at most once, after any `{{else if}}` clauses. The `{{/if}}` closing directive is mandatory.

Each condition is only evaluated if all preceding conditions returned false, so the block behaves like a standard if/else-if/else chain in C#. Nested conditionals and nested `{{#each}}` blocks are supported within the body.

Frends validates the structure of conditionals at save time. Errors such as a missing `{{/if}}`, an `{{else}}` appearing before `{{else if}}`, or a duplicate `{{else}}` are reported clearly when saving the Process.

### Iteration: each

The `{{#each}}` block iterates over a collection and repeats the body for each element. The collection can be any reference value that resolves to an array, list, or enumerable.

```xml
<Customers>
{{#each #var.CustomerList}}
  <Customer>
    <Id>{{this.Id}}</Id>
    <Name>{{this.Name}}</Name>
  </Customer>
{{/each}}
</Customers>
```

Inside the loop body, `{{this}}` refers to the current element and `{{@index}}` gives the zero-based position of the element in the collection. Properties of the current element are accessed with dot notation on `{{this}}`.

```json
[
{{#each #var.Orders}}
  {
    "index": "{{@index}}",
    "orderId": "{{this.OrderId}}",
    "amount": "{{this.Amount}}"
  }{{#if @index < #var.Orders.Count - 1}},{{/if}}
{{/each}}
]
```

Whitespace inside the block body is preserved in the output, so formatting the template for readability may affect the whitespace in the generated content. The `{{#each}}` and `{{/each}}` directives are mandatory as a matched pair.

## Where Handlebars can be used

Handlebars is available in any Task or shape input field that uses a text-based type. The most common places are Visual Data Mapper mappings, Task parameters, the Assign Variable and Code shape when their input type is set to a text-based type, and Return and Throw shapes.

Block helpers follow the same field type rule. Conditionals and each loops can be used in the same text-based fields as simple Handlebars expressions.

Handlebars is not evaluated in Trigger parameters. If you need a dynamic value at the Trigger level, Environment Variables can be used directly with `#env` references without `{{ }}` syntax. All other dynamic content should be handled inside the Process after the Trigger has started.

## Examples

Here are some examples on how to use Handlebars in Processes.

### Dynamic JSON body with conditional field

A Task sending data to an API can include a field that appears conditionally depending on the Process context.

```json
{
  "orderId": "{{#var.OrderID}}",
  "customerId": "{{#trigger.data.CustomerID}}",
  {{#if #var.IncludeNote}}
  "note": "{{#var.Note}}",
  {{/if}}
  "source": "{{#env.Integration.SourceSystem}}"
}
```

### XML output from a collection

An XML body can be generated from an array of items without a separate Code Task or Foreach shape.

```xml
<Orders>
{{#each #var.OrderList}}
  <Order>
    <Id>{{this.OrderId}}</Id>
    <Status>{{this.Status}}</Status>
  </Order>
{{/each}}
</Orders>
```

### Dynamic file name with formatted date

Handlebars can mix reference values with standard C# method calls.

```handlebars
export_{{DateTime.Now.ToString("yyyyMMdd")}}_{{#var.BatchId}}.csv
```

### Conditional value in a plain text field

A notification message can vary its content based on a status value.

```handlebars
Order {{#var.OrderID}} has been {{#if #var.Status == "completed"}}completed successfully{{else}}received and is being processed{{/if}}.
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/reference/process-development/handlebars.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
