Execute Mail Merge and Fill Merge Fields in Microsoft Word Documents

[![Mail merge][1] documents from a single template and a structured data source. For example, it can be used to create a letter that can be sent out to many recipients with only small changes, such as unique addresses or a change in the greeting line. Mail merge is also used to generate business reports, purchase orders, receipts, catalogs, inventories, and invoices etc.

Aspose.Words Cloud Mail Merge allows you to generate these documents from a template and XML in any language including .NET, Java, PHP, Ruby, Rails, Python, jQuery and many more. You can use it with any language or platform that supports REST. (Almost all platforms and languages support REST and provide native REST clients to work with REST APIs).

This post covers mailmerge in RUBY, read the Aspose.Words Cloud documentation for other languages. To execute a mailmerge, you need to upload a template to Aspose Cloud or any supported third party storage and then send a POST request (passing XML data in the request body) to generate documents based on template and data. The following steps describe the process in detail.

Decide which Type of Mail Merge to Execute

Aspose.Words Cloud supports simple mail merge and mailmerge with regions (to fill table fields and add rows dynamically). If you want to insert simple or non-repeating data, for example Name, Address and Code fields on an envelope or To and From fields in a letter, use simple mailmerge (also called mailmerge without regions).

If you are preparing reports, invoices and purchase orders, or other documents, and want to insert tables, rows or repeating data, or if you want your documents to dynamically grow based on your input data, use mailmerge with regions.

Prepare a Template

In order to prepare your template to perform a simple mail merge (without regions, similar to the classic mail merge available in Microsoft Word) insert one or more merge fields in the places you want to be populated with data from the data source. See Simple MailMerge Explained and Prepare a Document for more details.

If you want to dynamically grow portions inside the document, use mail merge with regions. To specify a mail merge region in the document you need to insert two mail merge fields to mark the beginning and end of the mail merge region. All document content that is included inside a mail merge region will automatically be repeated for every record in the data source (in most cases this is a table). See Prepare a Document for more details.

Format XML

If you want to execute simple mail merge and there are no «TableStart:TableName»«TableEnd:TableName» type merge fields in the Microsoft Word document, you can use the following XML structure to send in the request body.

<CollectionName> <field1>Value1</field1>  <field2>Value2</field2>
</CollectionName>

Note: You can select any text for CollectionName in the XML but field names must match the names of the merge fields in the Word document.

If you want to execute mail merge with regions and your merge fields are within «TableStart:TableName»«TableEnd:TableName» regions, you can use the following XML structure to send in the request body.

<CollectionName>  <ItemName> <field1>Value1</field1> <field2>Value2</field2> </ItemName> <ItemName> <field1>Value1</field1>
 <field2>Value2</field2>
 </ItemName>
</CollectionName>

Note: You can select any text for CollectionName in your XML but ItemName must match TableStart and TableEnd region name (for example «TableStart:ItemName»«TableEnd:ItemName» in this case) and field names must match the names of the merge fields in your Word document.

Mail Merge using RUBY REST

Before you execute mail merge, you need to upload your template Word file to Aspose Cloud or any supported third party storage. See Upload File examples or Section 2 of the complete code for more details.

Once you upload your template, you can use the following URI to execute mail merge.

http://api.aspose.com/v1.1/words/Sample.docx/executeMailMerge

There are several optional parameters you can use with the above mentioned URI. All or specific parameters can be used according to your requirement. Following is the detail of these optional parameters.

withRegions – This parameter can be set to true if you want to execute mail merge with regions. See Section 3 of the complete code.
mailMergeDataFile – This parameter can be set to specify the XML data file if you want to upload XML file to storage instead of passing XML in the request body.
cleanup – This parameter can be set specify different cleanup options e.g. if you want to remove empty paragraphs, unused fields and empty tables etc. See executeMailMerge resource.
filename – This parameter can be used to specify name of the file generated as a result of mail merge.
storage – This parameter can be used to set storage name if you are using a third party storage.
folder – This parameter can be used to set the name/path of the folder where template file is uploaded.

After building URI, you need to go through the following steps:

Set App SID and App Key. See Section 1 of the complete code.
Sign URI. See Section 3 of the complete code and [Sign URI][2] method for more details.
Set XML to post. See Section 4 of the complete code.
Send a POST request to Aspose Cloud service. See Section 5 of the complete code and [ProcessCommand][3] method for more details.
Get output file name from the response stream if you have not specified filename parameter and then download output file. See Section 6 of the complete code.

Following is the complete code.

 ####### Section 1 ######

app_sid

 '77****-****-****-****-80*********'

app_key

 '****************'

file_name

 "TestMailMerge.doc"

file_path

 File**.**join**(**Dir

pwd

 "MailMerge"

 "TestMailMerge.doc"

)

 output_file

 File**.**join**(**Dir

pwd

 "MailMerge"

 "MyOutput.doc"

)

 ####### End Section 1 ######

####### Section 2 ######

#build URI to upload file in the Aspose cloud
storage

str_uri

 'http://api.aspose.com/v1.1/storage/file/'

 file_name

signed_str_uri

 sign**(**str_uri

 app_sid

 app_key

)

 upload_file_binary**(**file_path

 signed_str_uri

)

 p  'Input Word document uploaded successfully'

####### End Section 2 ######

####### Section 3 ######

#build URI to execute mail merge with regions

str_uri

 'http://api.aspose.com/v1.1/words/'

 file_name

 '/executeMailMerge?withRegions=true'

;

 #sign URI

signed_str_uri

 sign**(**str_uri

 app_sid

 app_key

)

 ####### End Section 3 ######

####### Section 4 ######

#Set XML or load XML from XML file

xml

 '<?xml version="1.0"
encoding="utf-8"?>

 <Orders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="OrdersSchema.xsd">

 <Item>

 <Name>BBQ Chicken Pizza</Name>

 <Price>6.00</Price>

 <Quantity>1</Quantity>

 <ItemTotal>6.00</ItemTotal>

 </Item>

 <Item>

 <Name>1.5 Litre
Coke</Name>

 <Price>4.00</Price>

 <Quantity>2</Quantity>

 <ItemTotal>8.00</ItemTotal>

 </Item>

 <Item>

 <Name>Hawaiian Pizza</Name>

 <Price>4.00</Price>

 <Quantity>1</Quantity>

 <ItemTotal>4.00</ItemTotal>

 </Item>

 <Item>

 <Name>Fries</Name>

 <Price>1.00</Price>

 <Quantity>2</Quantity>

 <ItemTotal>2.00</ItemTotal>

 </Item>

 </Orders>'

output_file_name

nil

 ####### End Section 4 ######

####### Section 5 ######

#Execute mail merge

responseStream

 RestClient**.**post
signed_str_uri

xml

{

:accept

 'application/json'

 :content_type

 :xml

}

 json

 JSON**.**parse

(

responseStream

)

 ####### End Section 5 ######

####### Section 6 ######

#Extract output file name

output_file_name

 json**[**'Document'

][

'FileName'

to_s

p  'Mail merge has been excuted'

#Build and sign URI to download output DOC

str_uri

 'http://api.aspose.com/v1.1/storage/file/'

 output_file_name

;

 signed_str_uri

 sign**(**str_uri

 app_sid

 app_key

)

 #Download and save output DOC after executing mail merge

responseStream

 RestClient**.**get

(

signed_str_uri

 :accept

 'application/json'

)

 save_file**(**responseStream

 output_file

)

 p  'Output file has been downloaded successfully'

####### End
Section 6 ######

Mail Merge using RUBY SDK

If you want to use our RUBY SDK to execute mail merge, you can download this SDK from [Aspose Cloud SDK for RUBY][4]. In order to use RUBY SDK, you need to perform following steps:

Set base product URI, App SID and App Key. See Section 1 of the complete code.
Set XML to pass in the request body. See Section 2 of the complete code.
Create object of MailMerge class passing the template name to the constructor. See Section 3 of the complete code.
Call execute_mail_merge method for simple mail merge and execute_mail_merge_with_regions method for mail merge with regions. See Section 3 of the complete code.

Following is the complete code.

####### Section 1 ######

# Specify App SID and App Key

app_sid

 "45******-1***-4***-a***-a***********"

app_key

 "94******************************"

Aspose

::Cloud::

Common

AsposeApp**.**new

(

app_sid

 app_key

)

 #specify base product URI

Aspose

::Cloud::

Common

Product

set_base_product_uri

(

"http://api.aspose.com/v1.1"

)

 # set parameters

file_name

 "TestExecutewithRegion.doc"

####### End Section 1 ######

####### Section 2 ######

#Set XML or load XML from XML file

xml

 '<?xml version="1.0"
encoding="utf-8"?>

 <Orders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="OrdersSchema.xsd">

 <Item>

 <Name>BBQ Chicken Pizza</Name>

 <Price>6.00</Price>

 <Quantity>1</Quantity>

 <ItemTotal>6.00</ItemTotal>

 </Item>

 <Item>

 <Name>1.5 Litre
Coke</Name>

 <Price>4.00</Price>

 <Quantity>2</Quantity>

 <ItemTotal>8.00</ItemTotal>

 </Item>

 <Item>

 <Name>Hawaiian Pizza</Name>

 <Price>4.00</Price>

 <Quantity>1</Quantity>

 <ItemTotal>4.00</ItemTotal>

 </Item>

 <Item>

 <Name>Fries</Name>

 <Price>1.00</Price>

 <Quantity>2</Quantity>

 <ItemTotal>2.00</ItemTotal>

 </Item>

 </Orders>'

####### End Section 2 ######

####### Section 3 ######

# Creating the object of MailMerge
Class

mailmerge

 Aspose

Cloud

Words

MailMerge**.**new

(

file_name

)

 # execute mail with regions

output_path

 mailmerge**.**execute_mail_merge_with_regions**(**xml

)

 ####### End Section 3 ######

Convert Word to HTML and Vice Versa using REST APIs

[1]: https://blog.aspose.com/wp-content/uploads/sites/2/2014/02/aspose-Words-for-CloudAPIs_100.png “Mail Merge”)](https://blog.aspose.com/wp-content/uploads/sites/2/2014/02/aspose-Words-for-CloudAPIs_100.png)Mail merge allows you to produce several (potentially very large numbers of [2]: https://www.aspose.com/docs/display/rest/REST+API+Methods [3]: https://www.aspose.com/docs/display/rest/REST+API+Methods [4]: https://github.com/aspose-words-cloud/aspose-words-cloud-ruby

Decide which Type of Mail Merge to Execute#

Prepare a Template#

Format XML#

Mail Merge using RUBY REST#

Mail Merge using RUBY SDK#

Related Post:#

Decide which Type of Mail Merge to Execute

Prepare a Template

Format XML

Mail Merge using RUBY REST

Mail Merge using RUBY SDK

Related Post: