Execute Mail Merge and Fill Merge Fields in Microsoft Word Documents in RUBY

Aspose.Words for Cloud logoMail merge allows you to produce several (potentially very large numbers of) 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 for 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 mail merge in RUBY, read the Aspose.Words for Cloud documentation for other languages. To execute a mail merge, you need to upload a template to Aspose for 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 for Cloud supports simple mail merge and mail merge 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 mail merge (also called mail merge 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 mail merge 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 Mail Merge 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 Mail Merge with Regions Explained and 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 for 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:

  1. Set App SID and App Key. See Section 1 of the complete code.
  2. Sign URI. See Section 3 of the complete code and Sign URI method for more details.
  3. Set XML to post. See Section 4 of the complete code.
  4. Send a POST request to Aspose for Cloud service. See Section 5 of the complete code and ProcessCommand method for more details.
  5. 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 for Cloud SDK for RUBY. In order to use RUBY SDK, you need to perform following steps:

  1. Set base product URI, App SID and App Key. See Section 1 of the complete code.
  2. Set XML to pass in the request body. See Section 2 of the complete code.
  3. Create object of MailMerge class passing the template name to the constructor. See Section 3 of the complete code.
  4. 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 ######

To keep up with our news, you can follow us on Twitter or follow our Facebook page.

One Response to Execute Mail Merge and Fill Merge Fields in Microsoft Word Documents in RUBY

  1. Pingback: Execute Simple Mail Merge & Mail Merge with...

Leave a Reply