Free Support Forum -

Replace text with merge field


I have a number of Word documents that were used for merging via a find a replace vba macro, and I need to convert these to use proper merge fields (with Aspose.Words).

Currently the 'place holders' are just plain text (e.g. [[FirstName]]), and I need to programatically find all of these and convert them to proper merge fields (e.g. «FirstName»). In doing so, I need to preserve the format used for the placeholder (assuming the placeholder is all the same format).

I've been trying to work ut how to do this from the documentation with no success.

I would greatly appreciate if you could provide a code snippet to find and replace a single field. E.g. find all occurances of [[FirstName]]) and replace with «FirstName».

Hi David,

Thanks for your inquiry. Sure, you can find all occurances of [[FirstName]] and replace those with «FirstName» by using the following code snippet:

Dim doc As New Document(“C:\temp\in.docx”)

New ReplaceWithMergeFields(), False)


Private Class ReplaceWithMergeFields

Implements IReplacingCallback


''' NOTE: This is a simplistic method that will only work well when the match

''' starts at the beginning of a run.


Private Function IReplacingCallback_Replacing(ByVal e As ReplacingArgs) As ReplaceAction Implements IReplacingCallback.Replacing

Dim builder As New DocumentBuilder(DirectCast(e.MatchNode.Document, Document))


' Replace '[[FirstName]]' text with a MergeField.

builder.InsertField("MERGEFIELD FirstName \* MERGEFORMAT")

e.Replacement = ""

Return ReplaceAction.Replace

End Function

End Class

I hope, this will help.

Best Regards,

And there is a way to do the same with the java version?

Hi Thiago,

Thanks for your inquiry. Sure, here is how you can replace plain tags such as “[[FirstName]]” with real merge fields in Java.
String templateText = “My name is [[FirstName]]”;
ByteArrayInputStream bais
= new ByteArrayInputStream(templateText.getBytes());
Document doc
= new Document(bais);

doc.getRange().replace(Pattern.compile("[[(.*?)]]"), new ReplaceEvaluatorFindAndInsertMergefield(), false);



static class ReplaceEvaluatorFindAndInsertMergefield implements IReplacingCallback {
<font color="RED"><b>public</b></font> <font color="RED"><b>int</b></font> replacing<font color="BLUE"><b>(</b></font>ReplacingArgs e<font color="BLUE"><b>)</b></font> <font color="RED"><b>throws</b></font> Exception <font color="BLUE"><b>{</b></font>
    Node currentNode <font color="BLUE">=</font> e<font color="BLUE"><b>.</b></font>getMatchNode<font color="BLUE"><b>(</b></font><font color="BLUE"><b>)</b></font><font color="BLUE"><b>;</b></font>

    <font color="GREEN"><i>// The first (and may be the only) run can contain text before the match,

// in this case it is necessary to split the run.
if (e.getMatchOffset() > 0)
currentNode = SplitRun((Run) currentNode, e.getMatchOffset());

    <font color="GREEN"><i>// This array is used to store all nodes of the match for further removing.

ArrayList runs = new ArrayList();

    <font color="GREEN"><i>// Find all runs that contain parts of the match string.

int remainingLength = e.getMatch().group(0).length();
while (
(remainingLength > 0) &&
(currentNode != null) &&
(currentNode.getText().length() <= remainingLength)) {
remainingLength = remainingLength - currentNode.getText().length();

        <font color="GREEN"><i>// Select the next Run node.

// Have to loop because there could be other nodes such as BookmarkStart etc.
do {
currentNode = currentNode.getNextSibling();
while ((currentNode != null) && (currentNode.getNodeType() != NodeType.RUN));

    <font color="GREEN"><i>// Split the last run that contains the match if there is any text left.

if ((currentNode != null) && (remainingLength > 0)) {
SplitRun((Run) currentNode, remainingLength);

    DocumentBuilder builder <font color="BLUE">=</font> <font color="RED"><b>new</b></font> DocumentBuilder<font color="BLUE"><b>(</b></font><font color="BLUE"><b>(</b></font>Document<font color="BLUE"><b>)</b></font> e<font color="BLUE"><b>.</b></font>getMatchNode<font color="BLUE"><b>(</b></font><font color="BLUE"><b>)</b></font><font color="BLUE"><b>.</b></font>getDocument<font color="BLUE"><b>(</b></font><font color="BLUE"><b>)</b></font><font color="BLUE"><b>)</b></font><font color="BLUE"><b>;</b></font>
    builder<font color="BLUE"><b>.</b></font>moveTo<font color="BLUE"><b>(</b></font><font color="BLUE"><b>(</b></font>Run<font color="BLUE"><b>)</b></font> runs<font color="BLUE"><b>.</b></font>get<font color="BLUE"><b>(</b></font>runs<font color="BLUE"><b>.</b></font>size<font color="BLUE"><b>(</b></font><font color="BLUE"><b>)</b></font> <font color="BLUE">-</font> <font color="BROWN">1</font><font color="BLUE"><b>)</b></font><font color="BLUE"><b>)</b></font><font color="BLUE"><b>;</b></font>
    builder<font color="BLUE"><b>.</b></font>insertField<font color="BLUE"><b>(</b></font><font color="PURPLE">"MERGEFIELD \""</font> <font color="BLUE">+</font> e<font color="BLUE"><b>.</b></font>getMatch<font color="BLUE"><b>(</b></font><font color="BLUE"><b>)</b></font><font color="BLUE"><b>.</b></font>group<font color="BLUE"><b>(</b></font><font color="BROWN">0</font><font color="BLUE"><b>) + </b></font></font><span style="color: purple; font-family: 'Courier New';">"\""</span><font color="BLUE" style="font-family: 'Courier New';"><b>,</b></font><span style="font-family: 'Courier New';"> </span><font color="RED" style="font-family: 'Courier New';"><b>null</b></font><font color="BLUE" style="font-family: 'Courier New';"><b>)</b></font><font color="BLUE" style="font-family: 'Courier New';"><b>;</b></font></font></pre><pre><font face="Courier New" size="2">
    <font color="GREEN"><i>//Now remove all runs in the sequence.

for (Run run : (Iterable<Run>) runs)

    <font color="RED"><b>return</b></font> ReplaceAction<font color="BLUE"><b>.</b></font>SKIP<font color="BLUE"><b>;</b></font>
<font color="BLUE"><b>}</b></font>


private static Run SplitRun(Run run, int position) throws Exception {
Run afterRun = (Run) run.deepClone(true);
run.setText(run.getText().substring(0, position));
run.getParentNode().insertAfter(afterRun, run);
return afterRun;

I hope, this helps.

Best regards,

Worked like a charm! Thanks!

Hi, I implemented a solution based on the suggested code but it doesn’t quite work when replacing text within a sentence. For example, if I have the following line of text in my document:

Dear CMGetDataFirstName;,

and I want to replace “CMGetDataFirstName;” with the merge field «ClientFirstName», I am currently getting this:

«ClientFirstName»Dear ,

So it’s correctly replacing the text, but it always puts it at the start of the line.

Here is my code…

Public Sub ConvertMergeField(ByVal textValue As String, ByVal mergeFieldName As String)
Dim options As New FindReplaceOptions
options.ReplacingCallback = New ReplaceWithMergeFields(mergeFieldName)
mWordDoc.Range.Replace(New Text.RegularExpressions.Regex(textValue), “”, options)
End Sub

Private Class ReplaceWithMergeFields
Implements IReplacingCallback

Private m_mergeFieldName As String

Public Sub New(mergeFieldName As String)
m_mergeFieldName = mergeFieldName
End Sub

Private Function IReplacingCallback_Replacing(ByVal e As ReplacingArgs) As ReplaceAction Implements IReplacingCallback.Replacing
Dim builder As New DocumentBuilder(DirectCast(e.MatchNode.Document, Aspose.Words.Document))
builder.InsertField(“MERGEFIELD " & m_mergeFieldName & " * MERGEFORMAT”)
e.Replacement = “”
Return ReplaceAction.Replace
End Function
End Class

In the example above I am calling:

ConvertMergeField(“CMGetDataFirstName;”, “ClientFirstName”)

Hi David,

Thanks for your inquiry. To ensure a timely and accurate response, please attach the following resources here for testing:

  • Your input Word document
  • Aspose.Words generated output DOCX file showing the undesired behavior
  • Please attach your expected document here for our reference. We will investigate the structure of your expected document as to how you want your final output be generated like. You can create expected document using Microsoft Word.
  • Please create a standalone console application (source code without compilation errors) that helps us reproduce your problem on our end and attach it here for testing.

As soon as you get these pieces of information ready, we’ll start investigation into your issue and provide you more information. Thanks for your cooperation.

PS: To attach these resources, please zip them and Click ‘Reply’ button that will bring you to the ‘reply page’ and there at the bottom you can include any attachments with that post by clicking the ‘Add/Update’ button.

Best regards,