# Variables & Dynamic Content

This guide explains how to use variables in [PromptOwl](https://promptowl.ai) to create dynamic, reusable prompts that adapt to different contexts and inputs.

---

## Table of Contents

1. [Understanding Variables](#understanding-variables)
2. [Variable Syntax](#variable-syntax)
3. [System Variables](#system-variables)
4. [Custom Variables](#custom-variables)
5. [Artifact and Folder Variables](#artifact-and-folder-variables)
6. [Block Output Variables](#block-output-variables)
7. [Question-Based Variables](#question-based-variables)
8. [Memory Variables](#memory-variables)
9. [Variable Resolution](#variable-resolution)
10. [Best Practices](#best-practices)
11. [Troubleshooting](#troubleshooting)

---

## Understanding Variables

Variables allow you to insert dynamic content into your prompts at runtime.

### Why Use Variables?

| Benefit | Example |
|---------|---------|
| **Reusability** | Same prompt, different company names |
| **Personalization** | Include user-specific context |
| **Data Integration** | Pull in artifact content |
| **Workflow Chaining** | Pass output between blocks |

### Variable Types Overview

| Type | Source | Example |
|------|--------|---------|
| **System** | Built-in, automatic | ``\{memory\}``, ``\{last_message\}`` |
| **Custom** | User-defined | ``\{company_name\}``, ``\{product\}`` |
| **Artifact** | Data Room content | ``\{context\}`` → artifact content |
| **Block Output** | Previous block | ``\{output_analysis\}`` |
| **Question** | User input | ``\{user_goal\}`` |

---

## Variable Syntax

### Basic Format

Variables use curly braces: ``\{variable_name\}``

**Examples:**
```
Hello `{user_name}`, welcome to `{company_name}`!

Based on the following context:
`{context}`

Please analyze and respond.
```

### Naming Rules

| Rule | Valid | Invalid |
|------|-------|---------|
| Alphanumeric | ``\{user_name\}`` | `\{user-name\}` |
| Underscores OK | ``\{company_info\}`` | `\{company info\}` |
| No spaces | `\{productDetails\}` | `\{product details\}` |
| Case sensitive | `\{Name\}` ≠ ``\{name\}`` | - |

### Where Variables Work

| Location | Variables Supported |
|----------|-------------------|
| System context | Yes |
| Block instructions | Yes |
| Human messages | Yes |
| Variation text | Yes |

---

## System Variables

PromptOwl provides three built-in system variables automatically available at runtime.

### `\{memory\}`

Contains user memories if memory is enabled.

**What It Contains:**
- All user memories as formatted text
- Categorized by type (Preferences, Personal, etc.)
- Injected automatically when memory is enabled

**Example Usage:**
```
Consider the following about the user:
`{memory}`

Now respond to their question.
```

### `\{last_message\}`

Contains the most recent message in the conversation.

**What It Contains:**
- Content of the last user or assistant message
- Useful for follow-up processing

**Example Usage:**
```
The user just said: `{last_message}`

Provide a follow-up question based on this.
```

### `\{chat_history\}`

Contains the full conversation history.

**What It Contains:**
- All messages formatted with roles
- User and assistant messages included
- Chronological order

**Example Usage:**
```
Based on this conversation:
`{chat_history}`

Summarize the key points discussed.
```

### System Variable Availability

| Variable | Simple Prompt | Sequential | Supervisor |
|----------|--------------|------------|------------|
| `\{memory\}` | Yes | Yes | Yes |
| `\{last_message\}` | Yes | Yes | Yes |
| `\{chat_history\}` | Yes | Yes | Yes |

---

## Custom Variables

Define your own variables for dynamic content.

### Creating Custom Variables

1. Open prompt for editing
2. Find the **Variables** section
3. Click **Add Variable**
4. Enter variable name and value
5. Use ``\{variable_name\}`` in your prompt


### Variable Manager Interface

| Element | Description |
|---------|-------------|
| Variable name | The key used in ``\{name\}`` syntax |
| Variable value | Content to be inserted |
| Import button | Import from artifacts/folders |
| Clear button | Remove the value |

### Example: Company Context

**Variables:**
```
company_name: Acme Corporation
industry: Software Development
tone: Professional but friendly
```

**Prompt:**
```
You are a customer service representative for `{company_name}`,
a `{industry}` company. Respond in a `{tone}` manner.
```

**Resolved:**
```
You are a customer service representative for Acme Corporation,
a Software Development company. Respond in a Professional but friendly manner.
```

### Static vs Dynamic Variables

| Type | When Resolved | Use Case |
|------|---------------|----------|
| Static (text) | At prompt save | Fixed values |
| Dynamic (artifact) | At runtime | Changing content |

---

## Artifact and Folder Variables

Import content from your Data Room into prompts.

### Importing an Artifact

1. In Variables section, click **Import**
2. Select **Artifact** tab
3. Choose the artifact to import
4. Assign a variable name
5. Artifact content becomes the variable value


### Importing a Folder

For RAG (retrieval) rather than direct injection:

1. In Variables section, click **Import**
2. Select **Folder** tab
3. Choose the folder
4. Folder becomes available for AI retrieval

### How Artifact Variables Work

**Storage Format:**
```
context: artifact-60a7f5c3d8e9f12b4c5d6e7f
```

**At Runtime:**
1. System detects `artifact-` prefix
2. Fetches artifact content from database
3. Replaces variable with actual content
4. Content escaped to prevent injection

### Artifact vs Folder Import

| Import Type | Behavior | Best For |
|-------------|----------|----------|
| **Artifact** | Entire content injected | Small, specific documents |
| **Folder** | AI searches and retrieves | Large knowledge bases |

### Content Escaping

Artifact content is automatically escaped:
- `\{` becomes `\{\{`
- `\}` becomes `\}\}`

This prevents accidental variable injection from artifact content.

---

## Block Output Variables

Pass outputs between blocks in sequential prompts.

### How It Works

In a sequential prompt:
1. Block 1 generates output
2. Output stored as `\{output_block1id\}`
3. Block 2 can reference this output
4. Chain continues for all blocks

### Automatic Block Output Names

| Block | Output Variable |
|-------|-----------------|
| Block 1 | `\{output_abc123\}` |
| Block 2 | `\{output_def456\}` |
| Block 3 | `\{output_ghi789\}` |

The block ID becomes part of the variable name.

### Using Block Outputs

**In Human Message field:**
```
{output_previousBlockId}
```

**In Block Instructions:**
```
Based on the analysis: `{output_analysis_block}`

Now provide recommendations.
```

### Default Behavior

If you don't specify a human message for a block:
- System automatically uses previous block's output
- Format: `\{output_previousBlockId\}`

### Example: Multi-Stage Analysis

**Block 1 (Research):**
```
Research the topic and provide key findings.
```
Output stored as: ``\{output_research\}``

**Block 2 (Analysis):**
```
Human Message: Based on this research: `{output_research}`
Instructions: Analyze the findings and identify patterns.
```
Output stored as: ``\{output_analysis\}``

**Block 3 (Recommendations):**
```
Human Message: `{output_analysis}`
Instructions: Provide actionable recommendations.
```

---

## Question-Based Variables

Collect user input through questions to populate variables.

### How Questions Work

1. Define questions in prompt settings
2. Questions shown to user at chat start
3. Answers stored as variables
4. Variables used in prompt

### Creating Questions

1. Open prompt settings
2. Find **Questions** section
3. Add question text
4. Assign variable name
5. Set visibility and requirements


### Question Properties

| Property | Description |
|----------|-------------|
| **Text** | The question shown to user |
| **Variable** | Variable name for the answer |
| **Visible** | Whether to show the question |
| **Required** | Must be answered to proceed |
| **Run Frequency** | Once or every time |

### Run Frequency Options

| Option | Behavior |
|--------|----------|
| **Once** | Ask first time, cache answer |
| **Every Time** | Ask at each conversation start |

### Example: Personalized Assistant

**Questions:**
1. "What is your name?" → ``\{user_name\}``
2. "What is your role?" → ``\{user_role\}``
3. "What are you working on?" → ``\{current_project\}``

**Prompt:**
```
Hello `{user_name}`! As a `{user_role}` working on `{current_project}`,
I'm here to help. What can I assist you with?
```

---

## Memory Variables

Long-term context that persists across conversations.

### How Memory Works

1. User creates memories (persistent context)
2. Memories categorized by type
3. When memory enabled on prompt, ``\{memory\}`` variable populated
4. AI uses memory context in responses

### Memory Categories

| Category | Example Content |
|----------|-----------------|
| **Preferences** | "I prefer concise answers" |
| **Personal** | "My name is Sarah" |
| **Professional** | "I work at Acme Corp" |
| **Technical** | "I use Python 3.11" |
| **Schedule** | "I'm in EST timezone" |
| **Prompt Specific** | Context for specific prompt |

### Enabling Memory

1. Open prompt settings
2. Find **Memory** toggle
3. Enable memory
4. ``\{memory\}`` now available in prompt

### Using Memory in Prompts

**Implicit Use:**
When memory is enabled, it's automatically included in context.

**Explicit Reference:**
```
User preferences and context:
`{memory}`

Based on this information, respond appropriately.
```

### Memory vs Question Variables

| Feature | Memory | Questions |
|---------|--------|-----------|
| Persistence | Permanent | Per-session (if "once") |
| User control | User manages | Defined by prompt |
| Scope | All prompts (if enabled) | Single prompt |

---

## Variable Resolution

Understanding how variables are processed at runtime.

### Resolution Order

1. **Custom variables** defined on prompt
2. **Artifact/folder content** fetched and inserted
3. **Question answers** from user input
4. **System variables** (memory, last_message, chat_history)
5. **Block outputs** from previous blocks

### Resolution Process

```
Prompt Template with `{variables}`
           ↓
Fetch artifact content (if artifact- prefix)
           ↓
Merge all variable sources
           ↓
String replacement: `{name}` → value
           ↓
Escape special characters
           ↓
Final prompt sent to AI
```

### Handling Missing Variables

| Scenario | Behavior |
|----------|----------|
| Variable undefined | Replaced with empty string |
| Artifact not found | Empty string, error logged |
| Block output missing | Empty string, warning logged |

### Type Conversion

| Value Type | Conversion |
|------------|------------|
| String | Used directly |
| Number | Converted to string |
| Boolean | Converted to string |
| Object/Array | JSON stringified |
| null/undefined | Empty string |

---

## Best Practices

### Variable Naming

**Do:**
- Use descriptive names: ``\{company_overview\}``
- Use underscores for readability: ``\{user_profile_summary\}``
- Be consistent across prompts

**Don't:**
- Use single letters: ``\{c\}``
- Use reserved names: ``\{system\}``, ``\{prompt\}``
- Mix naming conventions

### Variable Organization

**Group Related Variables:**
```
# Context Variables
company_name
industry
target_audience

# Style Variables
tone
format
length
```

### Artifact Variables

**Do:**
- Use for stable reference content
- Keep artifact content focused
- Update artifacts when info changes

**Don't:**
- Import very large artifacts inline
- Use for frequently changing data
- Forget about sync status

### Sequential Workflow Variables

**Do:**
- Name blocks descriptively (helps identify outputs)
- Document expected outputs
- Handle missing outputs gracefully

**Don't:**
- Create circular references
- Skip documenting block purposes
- Assume outputs will always exist

### Security Considerations

**Do:**
- Sanitize user input in questions
- Be careful with artifact content
- Test variable injection scenarios

**Don't:**
- Put sensitive data in variables
- Trust unvalidated user input
- Expose internal variable names

---

## Troubleshooting

### Variable Not Resolving

**Symptoms:** ``\{variable_name\}`` appears in output

**Solutions:**
1. Check variable name spelling (case sensitive)
2. Verify variable is defined
3. Check variable has a value
4. Confirm using correct syntax ``\{name\}`` not `\{`\{name\}`\}`

### Artifact Content Empty

**Symptoms:** Variable resolves to nothing

**Solutions:**
1. Check artifact exists in Data Room
2. Verify artifact has content
3. Check artifact is synced
4. Confirm artifact ID is correct

### Block Output Missing

**Symptoms:** Sequential block gets empty input

**Solutions:**
1. Verify previous block executed
2. Check block ID in variable name
3. Review previous block for errors
4. Check human message references correct block

### Memory Not Appearing

**Symptoms:** ``\{memory\}`` is empty

**Solutions:**
1. Verify memory is enabled on prompt
2. Check user has created memories
3. Confirm memories aren't empty
4. Test with explicit memory content

### Question Answers Not Saved

**Symptoms:** Must re-answer questions

**Solutions:**
1. Check run frequency setting
2. Verify answer was submitted
3. Check for validation errors
4. Try clearing and re-answering

### Unexpected Characters in Output

**Symptoms:** Extra `\{\{` or `\}\}` in text

**Solutions:**
1. This is intentional escaping
2. Artifact content with braces gets escaped
3. Review source content if problematic
4. Consider alternative formatting

### Variable Shows "undefined"

**Symptoms:** Literal "undefined" in output

**Solutions:**
1. Variable value is JavaScript undefined
2. Set explicit empty string instead
3. Check variable initialization
4. Review data source

---

## Quick Reference

### Variable Types Summary

| Type | Syntax | Source |
|------|--------|--------|
| System | ``\{memory\}`` | Built-in |
| Custom | ``\{company\}`` | User-defined |
| Artifact | ``\{context\}`` | Data Room |
| Block Output | ``\{output_id\}`` | Previous block |
| Question | ``\{answer\}`` | User input |

### System Variables

| Variable | Content |
|----------|---------|
| ``\{memory\}`` | User memories |
| ``\{last_message\}`` | Most recent message |
| ``\{chat_history\}`` | Full conversation |

### Common Patterns

**Personalization:**
```
Hello `{user_name}`, how can I help you today?
```

**Context Injection:**
```
Using this information: `{context}`
Answer the following question.
```

**Sequential Chaining:**
```
Based on: {output_previousBlock}
Now continue with the next step.
```

### Variable Checklist

- [ ] Variable names are descriptive
- [ ] All variables have values defined
- [ ] Artifact variables point to valid artifacts
- [ ] Block outputs reference correct IDs
- [ ] Questions configured with correct frequency
- [ ] Memory enabled if using ``\{memory\}``

---

## Related Guides

- [Editing and Maintaining Prompts](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/editing-maintaining-prompts)
- [Understanding Agents and RAG](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/understanding-agents-rag)
- [Artifacts and Saved Responses](https://nest.promptowl.ai/d/promptowl-documents/platform/enterprise/artifacts-saved-responses)