Preview Templates with Sample Data

The Build a Doc Word Add-in allows you to preview your templates with real data before deploying them to production. This helps identify issues early and ensures your templates produce the expected output.

Please see the Create a Template quickstart for a detailed walkthrough of previewing your first document using the add-in.

Prerequisites

Build a Doc subscription and API key
Microsoft Word (Desktop or Online)
Build a Doc Word Add-in installed
A Word template with Build a Doc syntax (see Word Template Syntax)
JSON data that matches your template structure

Accessing the Preview Feature

Open your Word template
Open the Build a Doc Add-in pane (Home → Add-ins → Build a Doc)
Navigate to the Build tab
Enter or paste your JSON data
Click Preview

Preparing Your Data

JSON Structure

Ensure your JSON structure matches your template placeholders. For comprehensive guidance on structuring your JSON data, see Structure JSON Data for Build a Doc.

Template:

Invoice #<<[Invoice.Number]>>
Customer: <<[Invoice.Customer.Name]>>

JSON:

[
  {
    "Name": "Invoice",
    "Data": {
      "Number": "INV-2025-001",
      "Customer": {
        "Name": "John Smith"
      }
    }
  }
]

Using Sample Data

Create realistic sample data that exercises all template features:

Include values for all placeholders
Test arrays with multiple items for loops
Include edge cases (empty arrays, null values)
Test conditional branches

Interpreting Preview Results

Successful Preview

Generated PDF appears in the preview pane
All placeholders replaced with data values
Formatting preserved from template

Preview Errors

If the preview fails:

Check the error message displayed
Common issues: JSON syntax errors, missing properties, template syntax errors

Testing Scenarios

Test Conditionals

Create data sets that trigger different conditional branches:

Test 1: VIP Customer

[
  {
    "Name": "Invoice",
    "Data": { "Customer": { "IsVIP": true, "Name": "Premium Client" } }
  }
]

Test 2: Standard Customer

[
  {
    "Name": "Invoice",
    "Data": { "Customer": { "IsVIP": false, "Name": "Regular Client" } }
  }
]

Test Loops

Test with varying array sizes:

Empty array:

[{ "Name": "Invoice", "Data": { "Items": [] } }]

Single item:

[{ "Name": "Invoice", "Data": { "Items": [{ "Name": "Product A" }] } }]

Multiple items:

[
  {
    "Name": "Invoice",
    "Data": { "Items": [{ "Name": "Product A" }, { "Name": "Product B" }] }
  }
]

Test Formatting

Verify date and number formatting:

[
  {
    "Name": "Invoice",
    "Data": {
      "OrderDate": "2025-01-22T14:30:00",
      "Amount": 1234.56
    }
  }
]

The preview pane includes tools for reviewing your document:

Tool	Function
Zoom +/-	Adjust magnification
Fit to Width	Auto-fit document width
Search	Find text in preview
Print	Print the preview
Download	Save preview locally

Common Issues

Blank Placeholders

Cause: JSON property path doesn’t match template

Fix: Verify paths match exactly (case-sensitive)

JSON Validation Errors

Cause: Invalid JSON syntax

Fix: Use a JSON validator/formatter tool

Template Syntax Errors

Cause: Malformed template expressions

Fix: Check for missing >> or unclosed loops

Best Practices

Test frequently - Preview after each significant template change
Use realistic data - Test with production-like data
Test edge cases - Empty values, long text, special characters
Compare versions - Keep previous working versions for comparison
Document test data - Maintain test data sets for regression testing