> 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

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.

```
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:

```
$"{#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="/files/gYuoI0CzZwPgSHyTpuTX" 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.

```
{
  "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.

```
{
  "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.

```
<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.

```
{
  "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.

## 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 Task parameters, the Assign Variable and Code shape when their input type is set to a text-based type, and Return and Throw shapes.

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.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.