Replace Image

Replaces images in a Word document by index or all at once.

Common Properties

Name - The custom name of the node.
Color - The custom color of the node.
Delay Before (sec) - Waits in seconds before executing the node.
Delay After (sec) - Waits in seconds after executing the node.
Continue On Error - Automation will continue regardless of any error. The default value is false.

info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs

In File Descriptor - Unique identifier of the document to replace images in. This comes from the Create Word or Open Word node. Default variable is {{$message.word_fd}}.
Image Replacements - Dictionary object specifying which images to replace. Keys can be:
- Numeric index (0, 1, 2, etc.) to replace specific images
- "*" (asterisk) to replace all images with the same image
- Values are file paths to the new images
- Example: {0: "new_image1.png", 2: "new_image2.png"} or {"*": "replace_all.png"}
Preserve Original Size - Whether to keep the original image dimensions. Default is true.
- When true: New image uses the size of the replaced image
- When false: Uses Default Width/Height settings
Default Width (inches) - Default width for new images when not preserving size. Set to 0 for automatic width.
Default Height (inches) - Default height for new images when not preserving size. Set to 0 for automatic height.

How It Works

The Replace Image node locates and replaces images in the document. When executed, the node:

Validates the file descriptor and replacements dictionary
Retrieves the document from memory
Scans the entire document for all images (including in tables and paragraphs)
Indexes all images found in document order (0, 1, 2, ...)
Processes replacement requests:
- If key is "*": Replaces all images with the same image
- If key is a number: Replaces the image at that index
For each replacement:
- Removes the old image from the run
- Inserts the new image
- Applies size settings (preserve original or use defaults)
Reports the number of images successfully replaced

Image Indexing

Images are indexed in the order they appear in the document:

Index 0: First image in document
Index 1: Second image
Index 2: Third image
And so on...

Images are counted from:

Main document paragraphs
Table cells
All locations in document order

Requirements

Valid file descriptor from Create Word or Open Word node
Non-empty replacements dictionary
Valid image file paths that exist
At least one image in the document to replace
Read permissions for new image files

Error Handling

The node will return specific errors in the following cases:

Empty or invalid file descriptor
Document not found
Invalid replacements format (not a dictionary)
Empty replacements dictionary
Invalid keys (not integer or "*")
Empty or invalid image paths
Image files don't exist at specified paths
No images found in document
Image index out of range (warning, continues with other replacements)

Usage Examples

Example 1: Replace Logo in Template

Scenario: Replace a placeholder logo with client-specific logo

// Template has logo as first image (index 0)
$local.clientLogo = "/logos/client_acme.png";
$local.replacements = {
  0: $local.clientLogo
};

Configuration:

In File Descriptor: {{$message.word_fd}}
Image Replacements: {{$local.replacements}}
Preserve Original Size: true
Default Width: 0
Default Height: 0

Result: First image (logo) is replaced with client logo, maintaining original size.

Example 2: Replace Multiple Charts

Scenario: Update quarterly report charts with new data visualizations

// Replace three specific charts
$local.replacements = {
  0: "/reports/q1_chart.png",
  1: "/reports/q2_chart.png",
  2: "/reports/q3_chart.png"
};

Configuration:

In File Descriptor: {{$message.word_fd}}
Image Replacements: {{$local.replacements}}
Preserve Original Size: true
Default Width: 0
Default Height: 0

Result: First three images in document are replaced with new charts.

Example 3: Replace All Placeholder Images

Scenario: Replace all placeholder images with a standard "Coming Soon" image

// Replace all images at once
$local.replacements = {
  "*": "/images/coming_soon.png"
};

Configuration:

In File Descriptor: {{$message.word_fd}}
Image Replacements: {{$local.replacements}}
Preserve Original Size: false
Default Width: 3
Default Height: 2

Result: All images in document are replaced with the same image, sized to 3x2 inches.

Example 4: Replace with New Sizing

Scenario: Replace product images with updated versions in standardized size

// Replace product images with new size
$local.replacements = {
  0: "/products/product1_new.png",
  1: "/products/product2_new.png",
  2: "/products/product3_new.png"
};

Configuration:

In File Descriptor: {{$message.word_fd}}
Image Replacements: {{$local.replacements}}
Preserve Original Size: false
Default Width: 4
Default Height: 0 (auto)

Result: Product images are replaced with 4-inch width, auto height.

Usage Notes

Images are indexed starting from 0
Replacement operations preserve image position in document
Original formatting and alignment are maintained where possible
Using "*" replaces all images with the same file
Index-based replacement allows selective updates
Out-of-range indices generate warnings but don't stop execution
The node reports how many images were successfully replaced

Tips for Effective Use

Know Your Indices: Map out image positions in template before automation
Test with Small Documents: Verify indices with simple test documents first
Use Preserve Size: Usually best to maintain original layout
Wildcard for Bulk: Use "*" when all images should be the same
Selective Updates: Use specific indices when only some images change
Verify Paths: Ensure all new image files exist before running
Check Image Count: Know how many images are in your template
Consistent Formats: Use same image format (PNG, JPG) for best results

Best Practices

Template Design:
- Document image positions and indices
- Use consistent placeholder images
- Test template with sample data
Image Preparation:
- Pre-process images to correct dimensions
- Use appropriate file formats
- Optimize image file sizes
Error Prevention:
- Validate image files exist
- Check document has expected number of images
- Handle index out-of-range gracefully
Performance:
- Replace only necessary images
- Use efficient image formats
- Optimize image file sizes before replacement

Replacement Strategies

Strategy	Keys	Use Case
Single Image	`{0: "path"}`	Replace one specific image
Multiple Specific	`{0: "path1", 2: "path3"}`	Replace select images
All Images	`{"*": "path"}`	Replace all with same image
Sequential	`{0: "p1", 1: "p2", 2: "p3"}`	Replace first N images

Size Preservation Examples

Preserve Original Size = true

// Template has logo at 2x1 inches
$local.replacements = {0: "new_logo.png"};
// Result: New logo displays at 2x1 inches (same as original)

Preserve Original Size = false

// Template has logo at 2x1 inches
$local.replacements = {0: "new_logo.png"};
// Configuration: Width = 3, Height = 0
// Result: New logo displays at 3x[auto] inches (ignores original size)

Common Errors and Solutions

Error	Cause	Solution
"File Descriptor cannot be empty"	No file descriptor provided	Ensure Create Word or Open Word node runs first
"Image replacements must be a dictionary"	Invalid format	Provide a valid object/dictionary
"Image replacements dictionary cannot be empty"	No replacements	Add at least one key-value pair
"Invalid key [key]"	Key is not integer or "*"	Use numeric indices (0,1,2) or "*"
"Image path cannot be empty"	Empty path value	Provide valid image file paths
"Image file does not exist: [path]"	File not found	Verify image files exist at specified paths
"No images found in the document"	Document has no images	Ensure document contains images to replace
"Warning: Image index [N] not found"	Index out of range	Check document has enough images, or ignore warning
"Document not found"	Invalid file descriptor	Verify file descriptor is correct

Advanced Usage Patterns

Dynamic Index-Based Replacement

// Replace images based on data array
$local.newCharts = [
  "/charts/sales_2025.png",
  "/charts/revenue_2025.png",
  "/charts/growth_2025.png"
];

$local.replacements = {};
$local.newCharts.forEach((path, index) => {
  $local.replacements[index] = path;
});

Conditional Replacement

// Replace different images based on conditions
$local.replacements = {};

if ($local.reportType === "summary") {
  $local.replacements = {
    0: "/charts/summary_chart.png"
  };
} else if ($local.reportType === "detailed") {
  $local.replacements = {
    0: "/charts/detail_chart1.png",
    1: "/charts/detail_chart2.png",
    2: "/charts/detail_chart3.png"
  };
}

Replace with Generated Images

// First, generate charts and save as images
// (using chart generation nodes)

// Then replace in document
$local.generatedCharts = {
  0: "/tmp/generated_chart_1.png",
  1: "/tmp/generated_chart_2.png"
};

$local.replacements = $local.generatedCharts;

Replace All Except Specific

// Replace all images except the logo (index 0)
// Strategy: Replace indices 1, 2, 3... individually
$local.standardImage = "/images/standard_placeholder.png";
$local.replacements = {
  1: $local.standardImage,
  2: $local.standardImage,
  3: $local.standardImage,
  4: $local.standardImage
};
// Logo at index 0 remains unchanged

Determining Image Indices

To find out which index corresponds to which image:

Manual Inspection: Open document and note image order from top to bottom
Test Run: Use a test image and try different indices
Document Maps: Create a map of your templates documenting image positions
Sequential Test: Replace with numbered images (1.png, 2.png, 3.png) to see mapping

Performance Considerations

Large Documents: Scanning for images in large documents takes time
Many Images: Documents with many images require more processing
Image Size: Large replacement images increase processing time
Preserve Size: Faster than recalculating dimensions
Selective Replacement: More efficient than replacing all images

Troubleshooting Tips

Wrong Image Replaced: Verify index mapping, remember indexing starts at 0
Size Issues: Check Preserve Original Size setting and default dimensions
Image Not Replaced: Ensure index exists, check for warnings in output
All Images Same: Verify not using "*" key unintentionally
Quality Loss: Use high-resolution replacement images
Position Changes: Images should stay in original positions, check document structure

Image Index Mapping Example

Template Document:

Page 1:
  - Paragraph: Company Name
  - Image: Logo (INDEX 0)
  - Paragraph: Introduction
  - Image: Banner (INDEX 1)

Page 2:
  - Table:
    - Cell 1: Image: Icon 1 (INDEX 2)
    - Cell 2: Image: Icon 2 (INDEX 3)
  - Paragraph: Chart description
  - Image: Sales Chart (INDEX 4)

Replacement Code:

$local.replacements = {
  0: "/logos/client_logo.png",      // Replace logo
  4: "/charts/new_sales_chart.png"  // Replace sales chart
};
// Icons and banner remain unchanged

Common Properties​

Inputs​

How It Works​

Image Indexing​

Requirements​

Error Handling​

Usage Examples​

Example 1: Replace Logo in Template​

Example 2: Replace Multiple Charts​

Example 3: Replace All Placeholder Images​

Example 4: Replace with New Sizing​

Usage Notes​

Tips for Effective Use​

Best Practices​

Replacement Strategies​

Size Preservation Examples​

Preserve Original Size = true​

Preserve Original Size = false​

Common Errors and Solutions​

Advanced Usage Patterns​

Dynamic Index-Based Replacement​

Conditional Replacement​

Replace with Generated Images​

Replace All Except Specific​

Determining Image Indices​

Performance Considerations​

Troubleshooting Tips​

Image Index Mapping Example​

Common Properties

Inputs

How It Works

Image Indexing

Requirements

Error Handling

Usage Examples

Example 1: Replace Logo in Template

Example 2: Replace Multiple Charts

Example 3: Replace All Placeholder Images

Example 4: Replace with New Sizing

Usage Notes

Tips for Effective Use

Best Practices

Replacement Strategies

Size Preservation Examples

Preserve Original Size = true

Preserve Original Size = false

Common Errors and Solutions

Advanced Usage Patterns

Dynamic Index-Based Replacement

Conditional Replacement

Replace with Generated Images

Replace All Except Specific

Determining Image Indices

Performance Considerations

Troubleshooting Tips

Image Index Mapping Example