Replace Text

Replaces text in a Word document using search and replace operations.

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 text in. This comes from the Create Word or Open Word node. Default variable is {{$message.word_fd}}.
• Replacements - Dictionary object containing text replacements. Keys are the text to find, values are the replacement text. Example: {"old text": "new text", "Hello": "Hi"}.

Options

• Case Sensitive - Whether the search should be case-sensitive. Default is true.
  • When true: "Hello" will not match "hello"
  • When false: "Hello" will match "hello", "HELLO", "HeLLo", etc.
• Whole Words Only - Whether to match only complete words. Default is false.
  • When true: "cat" will not match "category"
  • When false: "cat" will match "cat" in "category"

How It Works

The Replace Text node performs find-and-replace operations throughout the entire document. When executed, the node:

1. Validates the file descriptor and replacements dictionary
2. Retrieves the document from memory
3. Processes replacements in the main document paragraphs
4. Processes replacements in all tables (including cells)
5. Processes replacements in headers and footers of all sections
6. Applies case sensitivity and whole word settings as configured
7. Updates the document with all replacements

Replacement Coverage

The node searches and replaces text in:

• Main document paragraphs
• Table cells
• Headers (all sections)
• Footers (all sections)

Requirements

• Valid file descriptor from Create Word or Open Word node
• Non-empty replacements dictionary
• Dictionary keys must be non-empty strings
• Dictionary values must be strings (can be empty for deletion)

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
• Empty search text (dictionary key)
• Non-string replacement value
• Template file errors (warnings, not fatal)

Usage Examples

Example 1: Fill Template with Data

Scenario: Replace placeholder text in a template document

// Create replacements for contract template
$local.replacements = {
  "{{CLIENT_NAME}}": "Acme Corporation",
  "{{CONTRACT_DATE}}": "January 15, 2025",
  "{{CONTRACT_AMOUNT}}": "$50,000",
  "{{PAYMENT_TERMS}}": "Net 30 days"
};

Configuration:

• In File Descriptor: {{$message.word_fd}}
• Replacements: {{$local.replacements}}
• Case Sensitive: true
• Whole Words Only: false

Result: All placeholders are replaced with actual values throughout the document.

Example 2: Update Company Name

Scenario: Replace old company name with new name after rebranding

// Replace company name throughout document
$local.replacements = {
  "OldCorp Inc.": "NewBrand Solutions",
  "OldCorp": "NewBrand"
};

Configuration:

• In File Descriptor: {{$message.word_fd}}
• Replacements: {{$local.replacements}}
• Case Sensitive: false
• Whole Words Only: true

Result: Company name is updated throughout, matching various capitalizations.

Example 3: Standardize Terminology

Scenario: Replace inconsistent terminology with standard terms

// Standardize terms
$local.replacements = {
  "customer": "client",
  "purchase": "procurement",
  "vendor": "supplier"
};

Configuration:

• In File Descriptor: {{$message.word_fd}}
• Replacements: {{$local.replacements}}
• Case Sensitive: false
• Whole Words Only: true

Result: All instances of old terms replaced with standard terminology.

Example 4: Dynamic Data Replacement

Scenario: Replace multiple placeholders with data from database

// Get customer data
$local.customer = $message.customer_data;

// Build replacements
$local.replacements = {
  "[NAME]": $local.customer.name,
  "[EMAIL]": $local.customer.email,
  "[PHONE]": $local.customer.phone,
  "[ADDRESS]": $local.customer.address,
  "[ACCOUNT_NUMBER]": $local.customer.account_id
};

Configuration:

• In File Descriptor: {{$message.word_fd}}
• Replacements: {{$local.replacements}}
• Case Sensitive: true
• Whole Words Only: false

Usage Notes

• Replacements are processed in the order provided in the dictionary
• Text in headers and footers is also replaced
• Original formatting is preserved where possible
• Multiple replacements can be performed in a single operation
• Empty replacement value effectively deletes the search text
• Replacements affect all instances of the search text

Tips for Effective Use

1. Use Unique Placeholders: Use distinctive markers like {{PLACEHOLDER}} or [FIELD_NAME]
2. Order Matters: If replacements overlap, order them carefully in the dictionary
3. Test Case Sensitivity: Know your data - use case-insensitive for user input
4. Whole Words: Enable for precise matching (e.g., "cat" vs "category")
5. Escape Special Characters: Be aware that some characters may need special handling
6. Verify Templates: Test template documents before automation
7. Handle Missing Data: Provide default values for missing replacement data

Best Practices

• Template Design:
  • Use clear, unique placeholder syntax
  • Document all placeholders in template
  • Test templates with sample data
• Data Preparation:
  • Validate all replacement values before creating dictionary
  • Convert numbers to strings
  • Handle null/undefined values
• Error Prevention:
  • Ensure all expected placeholders exist in document
  • Check for typos in placeholder names
  • Verify replacement data is complete

Placeholder Naming Conventions

Convention	Example	Best For
Double Curly Braces	{{NAME}}	Template systems, highly visible
Square Brackets	[NAME]	Simple templates, less intrusive
Angle Brackets	<NAME>	XML-like documents
Double Underscores	__NAME__	Plain text documents
Percent Signs	%NAME%	Environment variable style

Case Sensitivity Examples

Case Sensitive = true

$local.replacements = {
  "Hello": "Hi"
};
// Replaces: "Hello"
// Doesn't replace: "hello", "HELLO", "HeLLo"

Case Sensitive = false

$local.replacements = {
  "Hello": "Hi"
};
// Replaces: "Hello", "hello", "HELLO", "HeLLo" → all become "Hi"

Whole Words Only Examples

Whole Words Only = false

$local.replacements = {
  "cat": "dog"
};
// "cat" → "dog"
// "category" → "dogegory"
// "concatenate" → "condogenate"

Whole Words Only = true

$local.replacements = {
  "cat": "dog"
};
// "cat" → "dog"
// "category" → "category" (unchanged)
// "concatenate" → "concatenate" (unchanged)

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
"Replacements must be a dictionary"	Invalid replacements format	Provide a valid object/dictionary
"Replacements dictionary cannot be empty"	No replacements provided	Add at least one key-value pair
"Search text cannot be empty"	Empty string as dictionary key	Ensure all keys are non-empty strings
"Replacement text must be a string"	Non-string value	Convert values to strings
"Document not found"	Invalid file descriptor	Verify file descriptor is correct
"Warning: Header/Footer template not found"	Missing template in header/footer	Non-fatal warning, can be ignored

Advanced Usage Patterns

Conditional Replacements

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

if ($local.customerType === "premium") {
  $local.replacements["[DISCOUNT]"] = "20%";
  $local.replacements["[TIER]"] = "Premium";
} else {
  $local.replacements["[DISCOUNT]"] = "10%";
  $local.replacements["[TIER]"] = "Standard";
}

// Add common replacements
$local.replacements["[DATE]"] = new Date().toLocaleDateString();

Building Replacements from Data

// Convert array of data to replacements
$local.fields = ["name", "email", "phone", "address"];
$local.customer = $message.customer_data;
$local.replacements = {};

$local.fields.forEach(field => {
  $local.replacements[`{{${field.toUpperCase()}}}`] = $local.customer[field] || "N/A";
});

Multiple Document Processing

// Process multiple documents with same replacements
$local.replacements = {
  "[YEAR]": "2025",
  "[COMPANY]": "Acme Corp",
  "[VERSION]": "2.0"
};

// Use same replacements object with different file descriptors
// Document 1: $message.word_fd_1
// Document 2: $message.word_fd_2
// Document 3: $message.word_fd_3

Performance Considerations

• Large Documents: Replacement operations on large documents may take time
• Many Replacements: Processing many replacements increases execution time
• Complex Patterns: Whole word matching with case-insensitive search is slower
• Table-Heavy Documents: Documents with many tables require more processing

Troubleshooting Tips

1. Text Not Replaced: Verify placeholder exists in document exactly as specified
2. Partial Replacements: Check case sensitivity and whole word settings
3. Unexpected Results: Review replacement order and overlapping patterns
4. Missing Replacements: Ensure all keys in dictionary have non-empty values
5. Header/Footer Issues: Verify templates exist (warnings can usually be ignored)

Template Design Example

Template Document (contract_template.docx):

CONTRACT AGREEMENT

This agreement is made on {{DATE}} between {{CLIENT_NAME}}
and Acme Corporation.

Contract Amount: {{AMOUNT}}
Payment Terms: {{PAYMENT_TERMS}}
Project Duration: {{DURATION}}

Client Contact: {{CLIENT_EMAIL}} | {{CLIENT_PHONE}}

Automation Code:

$local.replacements = {
  "{{DATE}}": "January 15, 2025",
  "{{CLIENT_NAME}}": "Tech Solutions Inc.",
  "{{AMOUNT}}": "$75,000",
  "{{PAYMENT_TERMS}}": "Net 30 days",
  "{{DURATION}}": "6 months",
  "{{CLIENT_EMAIL}}": "contact@techsolutions.com",
  "{{CLIENT_PHONE}}": "(555) 123-4567"
};

Result: Fully populated contract with all placeholders replaced.