Ruby Code Sample to Execute Mail Merge and Fill Merge Fields in Microsoft Word Documents in Cloud

Mail merge allows you to produce several (potentially very large numbers of) documents from a single template and a structured data source. It 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 share mail merge using Cloud API in RUBY, read the Aspose.Words for Cloud documentation for other languages.

http://www.aspose.com/docs/display/wordscloud/Working+with+Mail+Merge

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. 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: http://www.aspose.com/docs/display/wordsnet/Mail+Merge+with+Regions+Explained

and Prepare a Document: http://www.aspose.com/docs/display/wordsnet/Prepare+a+Document for more details.

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. 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 method for more details.
• Set XML to post. See Section 4 of the complete code.
• Send a POST request to Aspose for Cloud service. See Section 5 of the complete code and ProcessCommand 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.

Here 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 => icon mad Execute Mail Merge and Fill Merge Fields in Microsoft Word Documents in RUBY ml}
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) ‘Output file has been downloaded successfully’

####### EndSection 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.

####### 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 ######

Overview: Aspose for Cloud

Aspose for Cloud is a cloud-based document generation, conversion and automation platform for developers that offer a unique suite of APIs to work with Word documents, Excel spreadsheets, PowerPoint presentations, PDFs, and email formats and protocols. It supports all features for file processing, document scanning, barcodes creation and recognition, and allows extracting text or images too. You can also work with SaaSpose APIs using REST SDKs that can be called from .NET, Java, PHP and Ruby etc.

More about Aspose for Cloud

- Homepage of Aspose.Words for Cloud: http://www.aspose.com/cloud/word-api.aspx

- Code Samples and Other details for Simple Mail Merge Explained: http://www.aspose.com/docs/display/wordsnet/Simple+Mail+Merge+Explained

-Aspose.Words for Cloud Documentation: http://www.aspose.com/docs/display/wordscloud/Working+with+Mail+Merge

- Download Aspose Cloud SDKs for Ruby: https://github.com/asposeforcloud/Aspose_Cloud_SDK_For_RUBY

- Ask technical questions/queries from Aspose for Cloud Support Team: http://www.aspose.com/community/forums/default.aspx?GroupID=15