Word Find & Replace

Word Find & Replace

Type: word-find-replace  ·  Package: Word Activities v1.0.4  ·  Output: int

Finds a text and replaces it throughout the document. It is the basis of the template pattern: you take a .docx with placeholders ({NAME}, {DATE}) and replace them with real data to generate personalized documents.

How it works

Replaces every occurrence of find with replace in the document body, tables included. By default it is not case-sensitive (caseSensitive = false). It accepts session or path — see the two modes:

• With path: opens the file, replaces and saves it to the same path automatically (even if nothing was replaced).
• With session (or inside a body): replaces in memory; save afterwards with Word Save.

Good to know:

• Text fragments: Word stores text in fragments according to formatting. The search runs inside each fragment, so a placeholder with mixed formatting (for example, half of it in bold) or one that Word split while spell-checking is not found. Type placeholders in one go and with a single format; if one is not replaced, delete it and type it again in full.
• Scope: only the document body; headers and footers are not changed.
• Formatting: the new text keeps the formatting of the fragment where the placeholder was.
• caseSensitive is set in the editor; it does not accept expressions.

Required parameters

Parameter	Type	Default	Description
find	string	—	Text to find. Cannot be empty.
replace	string	—	Replacement text. If the expression returns nothing, the placeholder is removed.

Optional parameters

Parameter	Type	Default	Description
session	ZoanWordSession	—	Session from Word Open (instead of path). Inherited automatically inside a body.
path	string	—	Path to the .docx (quick mode: opens, changes and saves by itself). Only used when there is no session.
caseSensitive	bool	false	Match upper and lower case exactly.

Output

Returns an int with the number of text fragments changed. If the same fragment contains the placeholder several times, all are replaced but they count as one. Use it to check whether anything changed: 0 means the text was not found.

Example

Fill in a letter template with several placeholders:

Copy File   source = asset("template.docx")   destination = letterPath   overwrite = true
Word Open   path = letterPath
 └─ body:
      Word Find & Replace   find = "{NAME}"    replace = customer.name   → output: n
      Word Find & Replace   find = "{DATE}"    replace = today().ToString("MM/dd/yyyy")
      Word Find & Replace   find = "{AMOUNT}"  replace = str(amount)
      Word Save
If   condition = n == 0
 └─ then:
      Log   level = warning   message = "The template has no {NAME} placeholder"

Template pattern

Create your template in Word with easy-to-spot placeholders ({NAME}), copy the template to the output path (so the original stays untouched) and replace each placeholder. It is the simplest way to generate professionally formatted documents.

Common errors

Message	Cause and fix
'session' or 'path' is required.	There is no session and no path. Pass path or use the activity inside a Word Open/Create body.
File not found.	The path does not exist on the robot’s machine.
'find' is required.	find is empty.
Access error on save (path mode)	The file is open in Word or another program, or there is no write permission.

Related activities

• Word Read Text — read the document.
• Word to PDF — convert the filled-in letter to PDF.
• Copy File — duplicate the template before filling it in.