> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oration.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Variables & Templating

> Create personalized, context-aware agent prompts using dynamic variables, conditional logic, and data formatting

## Overview

Oration enables dynamic content in agent prompts and conversations. Create personalized, context-aware interactions by injecting variables, applying filters, and using conditional logic directly in your agent prompts.

Use double curly braces `{{ }}` for variables and `{% %}` for logic tags to create data-driven prompts that adapt to each conversation.

### Key Benefits

* **Dynamic Personalization**: Insert customer names, account details, and contextual information
* **Conditional Logic**: Show different content based on customer data or conversation state
* **Data Formatting**: Apply filters to format dates, numbers, and text automatically
* **Reusable Templates**: Create flexible prompts that work across different scenarios

***

## Using Dynamic Variables in Conversations

### Basic Variable Injection

Inject dynamic variables into your agent prompts:

```liquid theme={null}
Hello {{name}}, welcome to {{companyName}}! 

I see you're calling about your account {{account.id}}. 
How can I help you today?
```

### Conditional Content

Use conditional logic to personalize responses based on customer data:

```liquid theme={null}
{% if customer.isPremium %}
As a premium member, I can offer you priority support and exclusive options.
{% else %}
I'd be happy to help you today. Did you know we offer premium support for faster service?
{% endif %}

{% if customer.lastPurchaseDate %}
I see your last purchase was on {{customer.lastPurchaseDate | date: "%B %d, %Y"}}.
{% endif %}
```

### Working with Nested Variables

Oration supports complex nested data structures in variables. You can access nested properties using dot notation and work with arrays and objects seamlessly.

### Accessing Nested Properties

```liquid theme={null}
<!-- Access nested object properties -->
{{customer.profile.firstName}}
{{customer.address.street}}
{{order.items.first.name}}

<!-- Access array elements by index -->
{{customer.orders[0].total}}
{{customer.phoneNumbers[1]}}
```

### Working with Objects

```liquid theme={null}
<!-- Customer profile object -->
Customer: {{customer.profile.firstName}} {{customer.profile.lastName}}
Email: {{customer.profile.contact.email}}
Address: {{customer.profile.address.street}}, {{customer.profile.address.city}}

<!-- Account details -->
Account Type: {{account.settings.type | capitalize}}
Preferences: {{account.settings.preferences.notifications}}
```

### Working with Arrays

```liquid theme={null}
<!-- Loop through arrays -->
Your recent orders:
{% for order in customer.orders %}
  - Order #{{order.id}}: {{order.total | currency}} on {{order.date | date: "%B %d, %Y"}}
{% endfor %}

<!-- Access array properties -->
Total orders: {{customer.orders.size}}
Latest order: {{customer.orders.first.total | currency}}
{% if customer.orders.size > 0 %}
Most recent purchase was {{customer.orders.first.date | date: "%B %d"}}.
{% endif %}

<!-- Convert arrays to natural language sentences -->
{% assign productNames = products | map: "name" %}
Available products: {{productNames | array_to_sentence_string}}
<!-- Output: "Product A, Product B, and Product C" -->

{% assign customerInterests = customer.interests %}
I see you're interested in {{customerInterests | array_to_sentence_string}}.
<!-- Output: "I see you're interested in technology, sports, and music." -->

<!-- Convert arrays with custom conjunctions -->
{{customer.phoneNumbers | array_to_sentence_string: "or"}}
<!-- Output: "555-1234, 555-5678, or 555-9999" -->

<!-- Handle different array sizes naturally -->
{% if customer.preferences.size == 1 %}
Your preference is {{customer.preferences.first}}.
{% else %}
Your preferences are {{customer.preferences | array_to_sentence_string}}.
{% endif %}
```

### Complex Nested Structures

```liquid theme={null}
<!-- Multi-level nesting -->
{{organization.departments.sales.manager.name}}
{{user.preferences.notifications.email.frequency}}

<!-- Nested conditionals -->
{% if customer.subscription.plan.features.premiumSupport %}
  You have access to our premium support team.
  Support hours: {{customer.subscription.plan.supportHours.start}} - {{customer.subscription.plan.supportHours.end}}
{% endif %}

<!-- Nested arrays and objects -->
{% for contact in customer.emergencyContacts %}
  Emergency Contact: {{contact.name}} ({{contact.relationship}})
  Phone: {{contact.phone | default: "Not provided"}}
{% endfor %}
```

### Safe Navigation

Use conditional checks to avoid errors when nested properties might not exist:

```liquid theme={null}
<!-- Safe access with conditional checks -->
{% if customer.profile %}
  Name: {{customer.profile.firstName | default: "Not provided"}}
{% endif %}

{% if customer.orders.size > 0 %}
  Last order: {{customer.orders.first.total | currency}}
{% else %}
  No previous orders found.
{% endif %}

<!-- Using default filters for safe access -->
{{customer.profile.firstName | default: "Valued Customer"}}
{{customer.address.city | default: "your area"}}
```

***

## Default Variables

Oration provides several built-in system variables that are always available in your prompts:

### System Variables

| Variable      | Description                   | Example                                        |
| ------------- | ----------------------------- | ---------------------------------------------- |
| `language`    | Current conversation language | `"en-US"`                                      |
| `currentTime` | Full current date and time    | `"Monday, August 27, 2024 at 12:25:37 PM IST"` |
| `currentDate` | Current date only             | `"Monday, August 27, 2024"`                    |

### Usage Examples

```liquid theme={null}
Today is {{currentDate}} and the current time is {{currentTime}}.

{% if language == "en-US" %}
I'll be speaking with you in English today.
{% elsif language == "es-ES" %}
Hablaré contigo en español hoy.
{% endif %}
```

### Custom Dynamic Variables

Define custom variables that are evaluated at runtime:

```liquid theme={null}
<!-- These would be defined in your agent configuration -->
Welcome to {{company.name}}! 
Your account balance is {{customer.balance | currency}}.
The weather today is {{weather.current | capitalize}}.
```

***

## Data Formatting Filters

Filters transform variable output using the pipe `|` operator. Most useful filters for agent prompts:

### Text Formatting

```liquid theme={null}
<!-- Capitalize first letter -->
{{customer.name | capitalize}}

<!-- Convert to uppercase -->
{{product.code | upcase}}

<!-- Convert to lowercase -->
{{customer.email | downcase}}

<!-- Remove extra whitespace -->
{{customer.notes | strip}}

<!-- Truncate long text -->
{{description | truncate: 100}}

<!-- Replace text -->
{{phone | replace: "-", " "}}
```

### Date and Time Formatting

```liquid theme={null}
<!-- Format dates -->
{{order.date | date: "%B %d, %Y"}}          <!-- August 27, 2024 -->
{{order.date | date: "%m/%d/%Y"}}           <!-- 08/27/2024 -->
{{order.date | date: "%A, %B %d"}}          <!-- Monday, August 27 -->

<!-- Relative time -->
{{order.date | date: "%-d days ago"}}
```

### Number Formatting

```liquid theme={null}
<!-- Format as currency -->
{{price | currency}}                        <!-- $29.99 -->
{{price | currency: "EUR"}}                 <!-- €29.99 -->

<!-- Round numbers -->
{{rating | round: 1}}                       <!-- 4.7 -->

<!-- Add commas to large numbers -->
{{revenue | number_with_delimiter}}         <!-- 1,234,567 -->
```

### Conditional and Logic Filters

```liquid theme={null}
<!-- Default values -->
{{customer.name | default: "Valued Customer"}}

<!-- Check if empty -->
{% unless customer.email == blank %}
I'll send a confirmation to {{customer.email}}.
{% endunless %}

<!-- Map values -->
{% assign statusText = order.status | map: "pending" => "Processing", "shipped" => "On the way" %}
```

### Advanced Filter Combinations

```liquid theme={null}
<!-- Chain multiple filters -->
{{customer.name | strip | capitalize | default: "Guest"}}

<!-- Format complex data -->
Your account ({{account.id | upcase}}) has a balance of {{account.balance | currency}} 
as of {{account.lastUpdated | date: "%B %d at %I:%M %p"}}.

<!-- Conditional formatting -->
{% assign urgency = ticket.priority | downcase %}
This is a {% if urgency == "high" %}🔴 HIGH PRIORITY{% elsif urgency == "medium" %}🟡 MEDIUM PRIORITY{% else %}🟢 STANDARD{% endif %} request.
```

***

## Essential Liquid JS Keywords & Syntax

Understanding these key Liquid JS keywords will help you create more powerful and flexible agent prompts. These are the most commonly used control structures and operators.

### Control Flow Keywords

#### Conditionals

```liquid theme={null}
<!-- if/elsif/else -->
{% if customer.status == "premium" %}
  Premium customer benefits apply.
{% elsif customer.status == "standard" %}
  Standard customer service available.
{% else %}
  Basic support provided.
{% endif %}

<!-- unless (opposite of if) -->
{% unless customer.email == blank %}
  I'll send you a confirmation email at {{customer.email}}.
{% endunless %}

<!-- case/when for multiple conditions -->
{% case customer.priority %}
  {% when "high" %}
    🔴 High priority support
  {% when "medium" %}
    🟡 Medium priority support
  {% when "low" %}
    🟢 Standard support
  {% else %}
    Regular customer service
{% endcase %}
```

#### Loops and Iteration

```liquid theme={null}
<!-- for loop -->
{% for order in customer.orders %}
  Order {{forloop.index}}: {{order.total | currency}}
{% endfor %}

<!-- for loop with conditions -->
{% for item in cart.items %}
  {% if item.onSale %}
    🏷️ SALE: {{item.name}} - {{item.price | currency}}
  {% endif %}
{% endfor %}

<!-- for loop with else (when array is empty) -->
{% for order in customer.orders %}
  {{order.id}}: {{order.total | currency}}
{% else %}
  No orders found.
{% endfor %}
```

### Variable Assignment and Manipulation

```liquid theme={null}
<!-- assign - create variables -->
{% assign fullName = customer.firstName | append: " " | append: customer.lastName %}
{% assign discountRate = 0.15 %}
{% assign isEligible = customer.years >= 2 %}

<!-- capture - capture block content as variable -->
{% capture greeting %}
  Hello {{customer.name}}, welcome to {{company.name}}!
{% endcapture %}

<!-- increment/decrement -->
{% assign counter = 0 %}
{% increment counter %}  <!-- counter is now 1 -->
{% decrement counter %}  <!-- counter is now 0 -->
```

### Comparison and Logic Operators

```liquid theme={null}
<!-- Equality operators -->
{% if status == "active" %}Active account{% endif %}
{% if status != "inactive" %}Account is working{% endif %}

<!-- Comparison operators -->
{% if customer.age >= 18 %}Adult customer{% endif %}
{% if order.total < 100 %}Small order{% endif %}
{% if balance > 0 %}Positive balance{% endif %}
{% if items <= 5 %}Few items{% endif %}

<!-- Logical operators -->
{% if customer.isPremium and customer.balance > 0 %}
  Premium customer with positive balance
{% endif %}

{% if customer.email == blank or customer.phone == blank %}
  Missing contact information
{% endif %}

<!-- Contains operator -->
{% if customer.interests contains "technology" %}
  Tech-savvy customer detected
{% endif %}
```

### Special Keywords and Properties

```liquid theme={null}
<!-- Loop properties (available in for loops) -->
{% for item in items %}
  {% if forloop.first %}First item: {% endif %}
  {% if forloop.last %}Last item: {% endif %}
  {{item.name}} ({{forloop.index}} of {{forloop.length}})
{% endfor %}

<!-- Size property -->
{% if customer.orders.size > 5 %}
  Frequent customer with {{customer.orders.size}} orders
{% endif %}

<!-- Empty/blank checks -->
{% if customer.notes != empty %}
  Notes: {{customer.notes}}
{% endif %}

{% if customer.email != blank %}
  Email on file: {{customer.email}}
{% endif %}

<!-- Array access -->
{{customer.orders.first.date}}  <!-- First element -->
{{customer.orders.last.total}}   <!-- Last element -->
{{customer.phoneNumbers[0]}}     <!-- By index -->
```

### Flow Control Keywords

```liquid theme={null}
<!-- break - exit loop early -->
{% for order in customer.orders %}
  {% if order.status == "cancelled" %}
    {% break %}
  {% endif %}
  Processing order {{order.id}}
{% endfor %}

<!-- continue - skip to next iteration -->
{% for item in cart.items %}
  {% if item.outOfStock %}
    {% continue %}
  {% endif %}
  Available: {{item.name}}
{% endfor %}
```

### Comments and Documentation

```liquid theme={null}
<!-- Single line comment -->
{%- comment -%}
  Multi-line comment
  This won't appear in output
{%- endcomment -%}

<!-- Liquid whitespace control -->
{%- if customer.name -%}    <!-- Remove whitespace before -->
  Hello {{customer.name}}!
{%- endif -%}               <!-- Remove whitespace after -->
```

### Advanced Keywords

```liquid theme={null}
<!-- tablerow - create table rows -->
{% tablerow product in products cols:3 %}
  {{product.name}}: {{product.price | currency}}
{% endtablerow %}

<!-- raw - output liquid code without processing -->
{% raw %}
  {{customer.name}} will not be processed
{% endraw %}

<!-- include/render (if partials are supported) -->
{% render 'customer-info', customer: customer %}
```

### Best Practices with Keywords

```liquid theme={null}
<!-- Use meaningful variable names -->
{% assign customerGreeting = "Hello " | append: customer.name %}

<!-- Combine keywords effectively -->
{% if customer.orders.size > 0 %}
  {% assign latestOrder = customer.orders.first %}
  {% if latestOrder.status == "delivered" %}
    Your recent order ({{latestOrder.id}}) was delivered {{latestOrder.deliveredDate | date: "%B %d"}}.
  {% endif %}
{% else %}
  This appears to be your first order with us!
{% endif %}

<!-- Use case statements for cleaner multiple conditions -->
{% case customer.subscription.type %}
  {% when "basic" %}
    Basic plan features available
  {% when "premium" %}
    Premium features unlocked
  {% when "enterprise" %}
    Full enterprise access
{% endcase %}
```

***

## Best Practices

### Always Provide Fallbacks

```liquid theme={null}
<!-- Good: Provides fallback -->
Hello {{customer.name | default: "there"}}!

<!-- Bad: Could result in empty output -->
Hello {{customer.name}}!
```

### Use Meaningful Variable Names

```liquid theme={null}
<!-- Good: Clear and descriptive -->
{{customer.preferredName | default: customer.firstName}}

<!-- Bad: Unclear abbreviations -->
{{cust.pref | default: cust.fn}}
```

### Format Data Consistently

```liquid theme={null}
<!-- Consistent date formatting -->
Account created: {{account.createdDate | date: "%B %d, %Y"}}
Last login: {{account.lastLogin | date: "%B %d, %Y"}}

<!-- Consistent currency formatting -->
Current balance: {{account.balance | currency}}
Credit limit: {{account.creditLimit | currency}}
```

### Keep Logic Simple

```liquid theme={null}
<!-- Good: Simple and readable -->
{% if customer.isPremium %}
You have premium support access.
{% endif %}

<!-- Avoid: Overly complex nested logic -->
{% if customer.type == "premium" and customer.status == "active" and customer.balance > 0 %}
<!-- Complex nested conditions -->
{% endif %}
```

***

## Common Use Cases

### Customer Service Agent

```liquid theme={null}
Hello {{customer.firstName | default: "there"}}! I'm {{agent.name}}, your support specialist.

{% if customer.supportHistory.size > 0 %}
I can see we've helped you {{customer.supportHistory.size}} time{% if customer.supportHistory.size > 1 %}s{% endif %} before. 
Your last interaction was about {{customer.supportHistory.first.subject}}.
{% endif %}

What can I help you with today?
```

### Sales Agent

```liquid theme={null}
Hi {{lead.name}}! Thanks for your interest in {{product.name}}.

{% if lead.budget %}
I see you mentioned a budget of {{lead.budget | currency}}. 
{% endif %}

{% if lead.company %}
I'd love to learn more about how {{product.name}} could help {{lead.company}} 
{% if lead.industry %}in the {{lead.industry}} industry{% endif %}.
{% endif %}

What specific challenges are you looking to solve?
```

### Appointment Scheduling

```liquid theme={null}
{% assign nextSlot = availableSlots.first %}
{% if nextSlot %}
I have availability {{nextSlot.date | date: "%A, %B %d"}} at {{nextSlot.time | date: "%I:%M %p"}}.
{% else %}
I don't have any immediate availability, but I can check next week.
{% endif %}

{% if customer.timezone %}
All times are in {{customer.timezone}} timezone.
{% endif %}
```

***

## Technical Reference

Oration's dynamic templating is powered by **LiquidJS**, a robust templating engine that provides the syntax and filters described in this guide. For advanced use cases and additional filters not covered here, you can refer to the [LiquidJS documentation](https://liquidjs.com/) for complete technical details and extended functionality.

***

> Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai)