Aspose Document Conversion

Cloudinary is a cloud-based service that provides an end-to-end image management solution including uploads, storage, manipulations, optimizations and delivery.

Cloudinary offers a rich set of image manipulation and format conversion capabilities. Cloudinary allows you to upload images and non-image raw files to the cloud. Images and PDF files can be converted to various image formats and can be cropped on-the-fly and further manipulated to match the graphic design of your websites and mobile applications.

Aspose is a leading vendor of development components, including a powerful set of file management and conversion products. Cloudinary provides an add-on for using Aspose's Office document conversion capabilities, fully integrated into Cloudinary's image management and manipulation pipeline.

With Aspose's document conversion add-on, you can extend Cloudinary's powerful format conversion and image manipulation capabilities with automatic conversion of your documents, spreadsheets and presentations to PDF documents and image thumbnails. The list of supported file formats for conversion includes: doc, docx, docm, dotx, rtf, xls, xlsx, xlsm, pot, potm, potx, pps, ppsm, pptx, ppt, and pptm.

Convert Office documents to images

To convert Office documents to images, the Aspose add-on first converts them to PDFs. Converting Office documents to the PDF file format can be done while uploading 'raw' files to Cloudinary, either from your server-side code or directly from the browser.

Note
Make sure to embed any custom fonts in the original file.

As the following code sample shows, a Word document is uploaded to Cloudinary as a raw file. The resource_type parameter should be set to either raw or auto (Cloudinary will automatically detect that is is a non-image raw file).

To convert the uploaded document using the Aspose add-on, the raw_convert parameter should be set to aspose.

Ruby:
Cloudinary::Uploader.upload("my_file_name.docx",
  :public_id => "sample_document.docx",
  :resource_type => 'raw', :raw_convert => 'aspose')
PHP:
\Cloudinary\Uploader::upload("my_file_name.docx",
  array(
   "public_id" => "sample_document.docx",
   "resource_type" => "raw",
   "raw_convert" => "aspose"
  ));
Python:
cloudinary.uploader.upload("my_file_name.docx",
  public_id = "sample_document.docx",
  resource_type = "raw",
  raw_convert = "aspose")
Node.js:
cloudinary.uploader.upload("my_file_name.docx",
  function(result) { console.log(result); },
  { public_id: "sample_document.docx",
    resource_type: "raw",
    raw_convert: "aspose"
  });
Java:
cloudinary.uploader().upload("my_file_name.docx", ObjectUtils.asMap(
  "public_id", "sample_document.docx",
  "resource_type", "raw",
  "raw_convert", "aspose"));

Document conversion using the Aspose add-on is performed asynchronously in the background after the upload call is completed. Therefore, the response of the uploaded request mentions that the Aspose raw convert process is in the pending status.

{
 "public_id":"sample_document.docx",
 "version":1393687686,
 "resource_type":"raw",
 "type":"upload",
 "url":"http:\/\/res.cloudinary.com\/demo\/raw\/upload\/v1399208539\/sample_document.docx",
 "info":{"raw_convert":{"aspose":{"status":"pending"}}},
  ...
}

As a result of the upload example above, the uploaded raw document with the public ID of 'sample_document.docx', is immediately available for delivery as-is using the following CDN URL:

https://res.cloudinary.com/demo/raw/upload/sample_document.docx

When the Aspose document conversion is completed for the uploaded image, an image (PDF) resource is also created in your Cloudinary account. The image resource has the same public ID as the uploaded raw document, 'sample_document.docx' in this case. Because it is now an image (PDF), you can manipulate and deliver the generated image resource in any image format, the same way you would manipulate any standard image that was uploaded to Cloudinary.

The following sample code creates an HTML image tag with a Cloudinary URL that generates a PNG image of the uploaded Word document.

Ruby:
cl_image_tag("sample_document.docx.png")
PHP:
cl_image_tag("sample_document.docx.png")
Python:
CloudinaryImage("sample_document.docx.png").image()
Node.js:
cloudinary.image("sample_document.docx.png")
Java:
cloudinary.url().imageTag("sample_document.docx.png");
JS:
cloudinary.imageTag('sample_document.docx.png').toHtml();
jQuery:
$.cloudinary.image("sample_document.docx.png")
React:
<Image publicId="sample_document.docx.png" >

</Image>
Angular:
<cl-image public-id="sample_document.docx.png" >

</cl-image>
.Net:
cloudinary.Api.UrlImgUp.BuildImageTag("sample_document.docx.png")
Android:
MediaManager.get().url().generate("sample_document.docx.png");
iOS:
imageView.cldSetImage(cloudinary.createUrl().generate("sample_document.docx.png")!, cloudinary: cloudinary)
PNG image of the document

Status notification

The Aspose add-on converts documents asynchronously. The conversion usually takes a few seconds, but the conversion time is dependant on the size and complexity of the converted document. As a result, you may want to get notified when the conversion process is completed.

When calling the upload API with Aspose document conversion, you can set the notification_url to a public HTTP or HTTPS URL endpoint of your online web application. Cloudinary sends a POST request to the specified endpoint when a document conversion completes.

Ruby:
Cloudinary::Uploader.upload("my_file_name.docx",
  :public_id => "sample_document.docx",
  :resource_type => 'raw', :raw_convert => 'aspose',
  :notification_url => "http://mysite.example.com/hooks")
PHP:
\Cloudinary\Uploader::upload("my_file_name.docx",
  array(
    "public_id" => "sample_document.docx",
    "resource_type" => "raw",
    "raw_convert" => "aspose",
    "notification_url" => "http://mysite.example.com/hooks"
  ));
Python:
cloudinary.uploader.upload("my_file_name.docx",
  public_id = "sample_document.docx",
  resource_type = "raw",
  raw_convert = "aspose",
  notification_url = "http://mysite.example.com/hooks")
Node.js:
cloudinary.uploader.upload("my_file_name.docx",
  function(result) { console.log(result); },
  { public_id: "sample_document.docx",
    resource_type: "raw",
    raw_convert: "aspose",
    notification_url: "http://mysite.example.com/hooks"
  });
Java:
cloudinary.uploader().upload("my_file_name.docx", ObjectUtils.asMap(
  "public_id", "sample_document.docx",
  "resource_type", "raw",
  "raw_convert", "aspose",
  "notification_url", "http://mysite.example.com/hooks"));

The following JSON snippet is an example of a POST request sent to the notification URL when the document conversion is completed:

{
  "notification_type": "info",
  "info_kind": "aspose",
  "info_status": "complete",
  "public_id": "sample_document.docx",
  "uploaded_at": "2014-03-01T15:43:08Z",
  "version": 1393688588,
  "url":
    "https://res.cloudinary.com/demo/raw/upload/v1393688588/sample_document.docx",
  "secure_url":
    "https://res.cloudinary.com/demo/raw/upload/v1393688588/sample_document.docx",
  "etag": "c558a878b3b309d42b8d97c82c6f924d"
}

The JSON content is signed using your Cloudinary account API secret. For details, see Verifying notification signatures

Generate PDFs from Office documents

Raw documents are automatically converted by the Aspose add-on to PDF files. You can download the converted PDF using Cloudinary's CDN delivery URLs. The following code example returns the PDF delivery URL of the converted Word document.

Ruby:
cloudinary_url("sample_document.docx.pdf")
PHP:
<?php echo cloudinary_url("sample_document.docx.pdf" ); ?>
Python:
cloudinary.CloudinaryImage("sample_document.docx.pdf").build_url()
Node.js:
cloudinary.url("sample_document.docx.pdf");
Java:
cloudinary.url().generate("sample_document.docx.pdf");

The returned URL: https://res.cloudinary.com/demo/image/upload/sample_document.docx.pdf

Cloudinary supports converting and manipulating PDF documents. For example, the following code creates an HTML image tag with a dynamic manipulation URL that generates a JPG image with a width of 300 pixels of the second page of the document.

Ruby:
cl_image_tag("sample_document.docx.jpg", :width=>300, :page=>2, :crop=>"scale")
PHP:
cl_image_tag("sample_document.docx.jpg", array("width"=>300, "page"=>2, "crop"=>"scale"))
Python:
CloudinaryImage("sample_document.docx.jpg").image(width=300, page=2, crop="scale")
Node.js:
cloudinary.image("sample_document.docx.jpg", {width: 300, page: 2, crop: "scale"})
Java:
cloudinary.url().transformation(new Transformation().width(300).page(2).crop("scale")).imageTag("sample_document.docx.jpg");
JS:
cloudinary.imageTag('sample_document.docx.jpg', {width: 300, page: 2, crop: "scale"}).toHtml();
jQuery:
$.cloudinary.image("sample_document.docx.jpg", {width: 300, page: 2, crop: "scale"})
React:
<Image publicId="sample_document.docx.jpg" >
  <Transformation width="300" page="2" crop="scale" />
</Image>
Angular:
<cl-image public-id="sample_document.docx.jpg" >
  <cl-transformation width="300" page="2" crop="scale">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation().Width(300).Page(2).Crop("scale")).BuildImageTag("sample_document.docx.jpg")
Android:
MediaManager.get().url().transformation(new Transformation().width(300).page(2).crop("scale")).generate("sample_document.docx.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation().setWidth(300).setPage(2).setCrop("scale")).generate("sample_document.docx.jpg")!, cloudinary: cloudinary)
page 2 scaled down

You can also convert previously uploaded Office documents using the update Admin API method while specifying the public ID of a previously uploaded raw file and setting raw_convert to aspose.

Ruby:
Cloudinary::Api.update("sample_spreadsheet.xls",
  :raw_convert => "aspose",
  :resource_type => :raw)
PHP:
$api = new \Cloudinary\Api();
$api->update("sample_spreadsheet.xls",
  array("raw_convert" => "aspose",
        "resource_type" => "raw"));
Python:
cloudinary.api.update("sample_spreadsheet.xls",
  raw_convert = "aspose",
  resource_type = "raw")
Node.js:
cloudinary.api.update("sample_spreadsheet.xls",
  function(result) { console.log(result); },
  { raw_convert: "aspose",
    resource_type: "raw" });
Java:
cloudinary.api().update("sample_spreadsheet.xls", ObjectUtils.asMap(
  "raw_convert", "aspose",
  "resource_type", "raw"));

Further image manipulations

Office document conversion using the Aspose add-on can be combined with other image manipulation capabilities.

For example, the following code scales down the fourth page of the processed Word document to a width of 300 pixels while rounding its corners, applying the sepia effect and adding a gray background. Then another uploaded image named aspose_cloud_logo is added as an overlay. The overlay is resized to a relative width of 90% of the underlying image, positioned 20 pixels from the bottom of the containing image and is made 70% semi transparent.

Ruby:
cl_image_tag("sample_document.docx.jpg", :transformation=>[
  {:width=>300, :page=>4, :effect=>"sepia", :radius=>50, :border=>"2px_solid_rgb:999", :crop=>"scale"},
  {:overlay=>"aspose_cloud_logo", :width=>0.9, :flags=>"relative", :opacity=>70, :gravity=>"south", :y=>20}
  ])
PHP:
cl_image_tag("sample_document.docx.jpg", array("transformation"=>array(
  array("width"=>300, "page"=>4, "effect"=>"sepia", "radius"=>50, "border"=>"2px_solid_rgb:999", "crop"=>"scale"),
  array("overlay"=>"aspose_cloud_logo", "width"=>0.9, "flags"=>"relative", "opacity"=>70, "gravity"=>"south", "y"=>20)
  )))
Python:
CloudinaryImage("sample_document.docx.jpg").image(transformation=[
  {'width': 300, 'page': 4, 'effect': "sepia", 'radius': 50, 'border': "2px_solid_rgb:999", 'crop': "scale"},
  {'overlay': "aspose_cloud_logo", 'width': 0.9, 'flags': "relative", 'opacity': 70, 'gravity': "south", 'y': 20}
  ])
Node.js:
cloudinary.image("sample_document.docx.jpg", {transformation: [
  {width: 300, page: 4, effect: "sepia", radius: 50, border: "2px_solid_rgb:999", crop: "scale"},
  {overlay: "aspose_cloud_logo", width: "0.9", flags: "relative", opacity: 70, gravity: "south", y: 20}
  ]})
Java:
cloudinary.url().transformation(new Transformation()
  .width(300).page(4).effect("sepia").radius(50).border("2px_solid_rgb:999").crop("scale").chain()
  .overlay(new Layer().publicId("aspose_cloud_logo")).width(0.9).flags("relative").opacity(70).gravity("south").y(20)).imageTag("sample_document.docx.jpg");
JS:
cloudinary.imageTag('sample_document.docx.jpg', {transformation: [
  {width: 300, page: 4, effect: "sepia", radius: 50, border: "2px_solid_rgb:999", crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("aspose_cloud_logo"), width: "0.9", flags: "relative", opacity: 70, gravity: "south", y: 20}
  ]}).toHtml();
jQuery:
$.cloudinary.image("sample_document.docx.jpg", {transformation: [
  {width: 300, page: 4, effect: "sepia", radius: 50, border: "2px_solid_rgb:999", crop: "scale"},
  {overlay: new cloudinary.Layer().publicId("aspose_cloud_logo"), width: "0.9", flags: "relative", opacity: 70, gravity: "south", y: 20}
  ]})
React:
<Image publicId="sample_document.docx.jpg" >
  <Transformation width="300" page="4" effect="sepia" radius="50" border="2px_solid_rgb:999" crop="scale" />
  <Transformation overlay="aspose_cloud_logo" width="0.9" flags="relative" opacity="70" gravity="south" y="20" />
</Image>
Angular:
<cl-image public-id="sample_document.docx.jpg" >
  <cl-transformation width="300" page="4" effect="sepia" radius="50" border="2px_solid_rgb:999" crop="scale">
  </cl-transformation>
  <cl-transformation overlay="aspose_cloud_logo" width="0.9" flags="relative" opacity="70" gravity="south" y="20">
  </cl-transformation>
</cl-image>
.Net:
cloudinary.Api.UrlImgUp.Transform(new Transformation()
  .Width(300).Page(4).Effect("sepia").Radius(50).Border("2px_solid_rgb:999").Crop("scale").Chain()
  .Overlay(new Layer().PublicId("aspose_cloud_logo")).Width(0.9).Flags("relative").Opacity(70).Gravity("south").Y(20)).BuildImageTag("sample_document.docx.jpg")
Android:
MediaManager.get().url().transformation(new Transformation()
  .width(300).page(4).effect("sepia").radius(50).border("2px_solid_rgb:999").crop("scale").chain()
  .overlay(new Layer().publicId("aspose_cloud_logo")).width(0.9).flags("relative").opacity(70).gravity("south").y(20)).generate("sample_document.docx.jpg");
iOS:
imageView.cldSetImage(cloudinary.createUrl().setTransformation(CLDTransformation()
  .setWidth(300).setPage(4).setEffect("sepia").setRadius(50).setBorder("2px_solid_rgb:999").setCrop("scale").chain()
  .setOverlay("aspose_cloud_logo").setWidth(0.9).setFlags("relative").setOpacity(70).setGravity("south").setY(20)).generate("sample_document.docx.jpg")!, cloudinary: cloudinary)
PNG of spreadsheet

To learn more about all available image manipulation options, see Image transformations and the Image transformation reference.