Contact us Blog

Generating Word documents with dynamic images

Overview

The material below assumes that you are familiar with the process for generating Word documents using Apsona's Document Generator.

Apsona's Word document generator lets you include: Dynamic images are usually produced: To produce dynamic images in your generated document, the general steps are these:

Creating an image merge field

There are two alternative ways to create a merge field for an image. The first is the preferred way, and the second - the one that uses INCLUDEPICTURE - is the older technique that is retained for backward compatibility.

Method 1: The IMAGE specifier

With this method, the merge field for an image can be written either with or without a required width specification, as below: For example, the screen shot below shows two merge fields, one named Photo, with a requirement that should be 250 pixels wide in the generated document, and a second named Photo2 with no width specification. Some things to keep in mind with this method:

Method 2: the INCLUDEPICTURE tag (not recommended)

This is the older technique for creating merge fields, and in some ways is less reliable because Word sometimes refuses to update the generated document correctly. In general, we suggest the use of Method 1 above for most use cases.

Ordinarily, to create a merge field, you simply use Insert - Quick parts - Field in Word, or use a macro, as described elsewhere in our documentation. But with the INCLUDEPICTURE method, for an image URL, there are a few additional steps to take. Essentially you will do the following:
  1. Create a merge field, as usual.
  2. Open the merge field's contents and add an INCLUDEPICTURE tag in Word. You do this by
    • toggling the field code;
    • typing Ctrl-F9 to add an extra pair of braces;
    • moving the MERGEFIELD tag into the newly generated braces; and finally
    • adding the INCLUDEPICTURE tag.
The process is much easier to understand by watching this demo .

An example report for generating QR codes

Once you have produced the merge document, you can use a report as data source for the merge. In this example, we'll use a report that includes a calculated field, shown in the screen shot below. This calculated field produces the URL for the QR code for the record ID of the contact, using the Google Charts QR code generator. Below is the formula it uses:
"https://chart.googleapis.com/chart?cht=qr&chs=150x150&choe=UTF-8&chld=L|2&chl=" +
      {!Contact ID}
Note that the formula relies on the Contact ID field in the report. Also note the parameter chs=150x150 which specifies the size of the generated QR code in pixels. If you want to change it to, say, 100x100, you would instead use chs=100x100.

Handling images stored in Salesforce

Apsona's Document Generator can handle dynamic images stored in either the Document or Attachment object in Salesforce Classic, or as a File attachment in Salesforce Lightning. The key feature here is that for these three use cases (Document, Attachment or File), you can map the image merge field in your document template directly to a field that contains the record ID of a the attachment record to be included (i.e., no need for a field containing a URL).

Images in the Document object

If your image is stored in the Document object, you can use the following process:
  1. Create an Apsona report or view that produces the Document ID along with the other data you wish to merge into the generated document. For example, if you wanted to generate documents from the Contact object, one way to do this is to create a custom field on the Contact object, and have it be populated with the document ID of the image you want to produce for each Contact.
  2. You can then map that custom field directly to the image merge field.

Images in the Attachment object

With images in the Attachment object, the usual setup is that each record in your main object (e.g., Contact) has an associated Attachment record that contains the image data. To handle this case, we suggest the following process. We assume here that you are familiar with generating documents with sublists.

Images as Files in Salesforce Lightning

Salesforce Classic's Attachment data model is very simple. But the Lightning data model for files is more complex, and involves three different objects: ContentDocument, ContentDocumentLink and ContentVersion. This makes it significantly harder to get at the attachment's content. To simplify this process, Apsona's Document Generator includes a pseudo-object called Apsona Lightning Attachment Surrogate. Apsona makes this object available automatically for all profiles. This is not a real object in Salesforce, but rather a "view" that maps to the correct fields within the three Salesforce native objects mentioned above. (Specifically, it maps to the data corresponding to the latest version of each file.) So the steps in Lightning are similar to the ones for the Attachment object in Classic:

Printing the generated document

A key advantage of Method 1 above is that the images are included as part of the generated document, with no additional steps needed on your part. You can also generate PDF documents using the technique of Method 1.

But method 2 (the older INCLUDEPICTURE method) has some disadvantages in this regard. Once you have generated the merged document and downloaded it, you will need to tell Word to update all the images in the document before it can be printed. You can do this by pressing Ctrl-A (select all), followed by F9 (update all fields). You will then see a ready-to-print document, part of which might look like the screen shot below.

If you like, you can download the .docx template that produced this screen shot.

Limitations