Use Ruby (on Rails) to Convert, Merge and Watermark HTML & Office files to PDF

In this article we explain how to use Ruby to convert MS-Word, Excel, PowerPoint, HTML and other common file formats to PDF as well as to other formats. Read on to learn more about the Muhimbi PDF Converter and how it can assist with the Conversion, Merging, Watermarking, Splitting and Securing of documents.

We previously discussed how to use the popular Muhimbi PDF Converter Services in combination with PHP, Java (Axis2 and wsimport) as well as Microsoft .NET based environments. Today we will discuss a similar example using the increasingly popular Ruby on Rails (ROR) platform.

For those not familiar with the product, the Muhimbi PDF Converter Services is a server based SDK that allows software developers to convert and manipulate typical Office files, including MS-Word, Excel, PowerPoint, Visio, Publisher, AutoCAD, HTML, emails and InfoPath, to PDF and other formats using a robust, scalable but friendly Web Services interface from Java, PHP, Ruby and .NET based solutions. If you have any questions or need more information then please let us know.

Update for 2019: Please note that this example was written in the Ruby 1.8.7 / Rails 3.2.12 (2013) time-frame. Things have moved on since that time and you may find that for more recent Ruby versions you need a different Web Services Framework. However, the concept remains the same, you use a tool to generate proxy classes for the web service, then invoke those proxy classes from your Ruby code. You can find some additional details in our GitHub repository. Talk to us if you get stuck , we love to help.

Installing the base ROR environment

If you are reading this then you probably already have a full ROR environment set up. If that is the case then please take into account that this example has been tested with Ruby 1.8.7-p370 and Rails 3.2.12. You may want to use RVM to select the exact same Ruby version as the soap4r gem used in this example may not be compatible with all ruby versions.

If you don’t have a full Rails environment installed then you may want to follow the instructions below to install it. For the sake of this example we used Ubuntu 12.10.

1. Download and Install Ubuntu 12.10. We set it up to run inside Hyper-V, but that is naturally not a requirement.

2. Install Ruby and Rails as described here. However, rather than using the rvm install 1.9.3 command use rvm install ruby-1.8.7-p370 and set that to the default using rvm use ruby-1.8.7-p370 –default.

3. When deploying to a clean Ubuntu 12.10 system the ExecJS dependency is missing. The easiest way to install this is to issue the following command:

   sudo apt-get install nodejs

That is it as far as the base ROR environment is concerned. You may want to consider installing a decent text editor. For testing purposes we use Sublime-Text.

Creating the Rails application

The Muhimbi PDF Converter exposes a comprehensive API via a standards based Web Services interface (Full Documentation). A number of Web Service frameworks are available for Ruby (Savon, Handsoap), but in this example we use Soap4R to pre-generate Ruby proxies as it is simple, and it works.

In the example below we will create a basic PDF Conversion Rails application. If you are looking to add PDF Conversion to an existing Rails application then I am sure you’ll know how to modify the various steps.

1. Use a terminal application of your choice to navigate to the location where you wish to create the Rails application. We use ~Sites.

2. Execute the following command to create the skeleton for the application:

   rails new MuhimbiPDFConverter –O

3. Navigate to MuhimbiPDFConverter, edit Gemfile using a text editor of your choice and add the following line:

   gem 'soap4r'

4. Install bundler as follows:

   gem install bundler

5. Execute the following command to pull in the applicable gems (Make sure you are still in the MuhimbiPDFConverter directory)

   bundle install

Generating proxies

The quickest way (also from a performance perspective) to interact with a Web Service is to generate proxy classes. This can be achieved easily using soap4r, which has already been added to the application as described above.

Before we can generate the proxies we need to make sure that the Muhimbi Conversion Service has been installed and is running ( Yes, this requires one or more Windows Based Servers. Sorry Linux/Apple experts, there is just no way to achieve a decent conversion fidelity on other platforms. Rest assured that your Ruby application can continue to run on non-Windows systems).

1. Download and Install the Muhimbi PDF Converter Services as described in Chapter 2 of the Administration guide.

2. Open Muhimbi.DocumentConverter.Service.exe.config in your favourite text editor (notepad works as well). A handy shortcut to the configuration/installation folder can be found in the Windows Start Menu Group.

3. Search for baseAddress and change localhost to the DNS name or IP address of the server running the Conversion Service.

4. Restart the Conversion Service as follows:

   Net stop "Muhimbi Document Converter Service"
   Net start "Muhimbi Document Converter Service"

Back on your Ruby system carry out the following steps to generate the proxies:

1. Navigate to MuhimbiPDFConverter/lib

2. Execute the following command. Please replace localhost with the name or ip address of the server that runs the Muhimbi PDF Converter Services.

   bundle exec wsdl2ruby.rb --wsdl https://localhost:41734/Muhimbi.DocumentConverter.WebService/?wsdl --type client

This generates four new files and places them in the lib folder. Note that the generated property and method names follow Ruby’s naming convention and not the convention used in the Muhimbi Developer guide. This mainly impacts the capitalisation of the first letters.

Update: _A third party is maintaining a Ruby Gem for our PDF Converter. Although unsupported and untested by our engineers, _it may be worth checking out_._

Implementing the sample

All prerequisites are in place. Let’s add some code to tie it all together. If you prefer you can download the full example, including generated proxies from our website.

1. Start by generating a controller where the form will be posted to:

   rails generate controller home upload\_file

2. Delete the home page that comes with every new Rails application (Execute in the MuhimbiPDFConverter folder)

   rm public/index.html

3. If you are using Sublime-Text then this is the moment to execute _subl ._ to open the text editor and display the entire folder structure.

4. Edit config/routes.rb and after the following line

   get "home/upload\_file"

   Add

   post "home/upload\_file"
   root :to => 'home#upload\_file'

5. Edit app/views/home/upload\_file.html.erb and add the following HTML

   <form method="post" enctype="multipart/form-data">
     <br />
     <label for="file">Document:</label>
     <input type="file" name="file" id="file" /> <br />
     <label for="outputFormat">Output format:</label>
     <select name="outputFormat" id="outputFormat">
       <option value="PDF">PDF</option>
       <option value="XPS">XPS</option>
       <option value="DOCX">DOCX</option>
       <option value="DOC">DOC</option>
       <option value="ODT">ODT</option>
       <option value="RTF">RTF</option>
       <option value="TXT">TXT</option>
       <option value="MHT">MHT</option>
       <option value="HTML">HTML</option>
       <option value="XML">XML</option>
       <option value="XLS">XLS</option>
       <option value="XLSX">XLSX</option>
       <option value="CSV">CSV</option>
       <option value="ODS">ODS</option>
       <option value="PPT">PPT</option>
       <option value="PPTX">PPTX</option>
       <option value="ODP">ODP</option>
       <option value="PPS">PPS</option>
       <option value="PPSX">PPSX</option>
     </select>
     <br />
     <input type="submit" name="submit" value="Convert" />
   </form>

6. Edit app/controllers/home\_controller.rb and replace it with the following:

   require Rails.root.to_s + '/lib/DocumentConverterServiceDriver'
   require "base64"
   class HomeController < ApplicationController
      def upload_file
         #** Get a reference to the uploaded file and check it was specified
         file = params['file']
         if file
            #** Specify the URL of the server that holds the Conversion Service
            url = "https://localhost:41734/Muhimbi.DocumentConverter.Webservice/?wsdl"
            conversionClient = DocumentConverterService.new(url)
            #** Create OpenOptions and specify the absolute minimum information
            openOptions = OpenOptions.new()
            openOptions.fileExtension = file.original_filename.split(".").last
            openOptions.originalFileName = file.original_filename
            #** Create ConversionSettings and set the minimum fields. See Developer guide for details
            conversionSettings = ConversionSettings.new()
            conversionSettings.format = params['outputFormat']
            conversionSettings.fidelity = "Full"
            conversionSettings.openPassword = ""
            conversionSettings.ownerPassword = ""
            #** Encode the source file into a Base64 encoded byte array
            sourceFile = Base64.encode64(file.read)
            #** Carry out the conversion
            convert = Convert.new(sourceFile, openOptions, conversionSettings)
            result =  conversionClient.convert(convert)
            #** Send the converted file back to the browser. ‘wsdl2ruby’ needs double Base64 decoding for some reason.
            send_data(Base64.decode64(Base64.decode64(result.convertResult)),
               :filename => "convert." + conversionSettings.format,
               :content_type => 'application/octet-stream',
               :disposition => 'attachment')
         end
      end
   end

Please update the url variable with the IP address or DNS name of the server that runs the Muhimbi Conversion Service.

This is a minimum code sample to illustrate how simple it is to convert a file. Our full Developer Guide contains the entire object model, including details about how to Convert, Watermark, Split, Merge and Secure files.

That is it. Start the Rails server as follows:

rails s

Open a web browser and point it to https://localhost:3000. If the browser is opened on a system other than the one that runs the Rails application then replace localhost with the DNS name or IP number of that server.

The sample application is very simple. Select a file to convert (see this list of supported file types, please make sure that the file extension matches its format). Then select the Output format, e.g. PDF, and click the Convert button.

SOAP / Web Service Debugging

The Muhimbi Conversion Service is a Windows Service based on the Microsoft Windows Communication Foundation (WCF) framework. This comprehensive framework is used to expose a standards based Web Services interface that can be consumed by many different platforms including .NET, Java, PHP, SAP, Ruby, Documentum and many others.

Even though WCF Web Services are standards based, standards are not interpreted the same by everyone so from time to time you may need to do some troubleshooting when programming against  the PDF Converter Web Service, especially from non-Microsoft platforms.

For details about how to debug Web Service / SOAP messages, see this Knowledge Base Article.

If you have any questions then leave a comment below or contact us.