Configuring Image Merges

In order to configure image merges, your stored procedures must meeting certain requirements. Then, you can configure the named ranges for your images on the new or existing Excel or Word merge template file.

Note: If you need configuration assistance, please log an extranet case.

Prerequisite Requirements

As a prerequisite, there must be a source dataform containing at least one field of type “File Upload Manager - Database” so that the image file can be retrieved. We advise that you ensure the image file is in a standard image format (PNG, TIF/TIFF, JPG/JPEG, GIF) as other image formats are not guaranteed to be supported.

Troubleshooting tips are listed at the end of this topic.

Stored Procedure Requirements

  • In addition to any other data, the stored procedure must select the file field with an alias beginning with IMG_ as the prefix.

  • If the same image must be used in multiple locations, a duplicate selection of that field with a distinct alias must be selected.

  • We recommend that the file GUID is selected in a portion of the stored procedure that is retrieving a single row of data at a time. There is no reason to pair the file GUID with several rows in a selection.

A sample query using the same image multiple times is as follows:

SELECT a.columnname AS IMG_Sample1, a.columnname AS IMG_Sample2

FROM gen_mytable AS a

WHERE @Key = a.pk AND @ProjectID = a.fkProjectID

Excel Template Named Range Configuration

On either an existing or new Excel merge template, create a named range where the image should be placed. The named range must start with IMG_ to be detected by the merge process as an image location.

  1. With the template file open in Excel, select the cells where the image should be placed.

    Note: 

    • The area selected will be the exact edges of where the image is placed.

    • Please account for any desired effects such as transparency when aligning the range overtop existing cell content.

  2. With the cells still selected, type a name beginning with IMG_ into the Home > Name Box dropdown and press Enter.

    Note: 

    • The name must map to the same full column name as defined in the stored procedure.

    • Ranges that intend to reuse the same image data must be named differently, as indicated above in the Stored Procedure Requirements.

Word Template Named Range Configuration

On either an existing or new Microsoft Word merge template, place a shape or placeholder image where the merged image should be placed. The shape or placeholder must then be named starting with IMG_ to be detected by the merge process as an object to be replaced.

  1. With the template file open in Microsoft Word, move the cursor to where the image should be inserted.

  2. Go to Insert > Shapes > Rectangle and draw a rectangle representing where the image should be placed.

    Note: The rectangle should be at roughly the final aspect ratio when drawn, otherwise, the replacement image may appear stretched.

  3. Apply any desired border and alignment effects, such as an invisible border or align the shape within text. Note: 

    • These effects will be maintained when the resulting image is merged.

    • We recommend adding a visible fill color on all placeholder shapes in case you need to edit them later as you may find transparent placeholder shapes difficult to find in the future if any further edits to the template are needed.

  4. Go to Home > Select > Selection Pane. There should be a text box with a visibility toggle for the shape you have created.

  5. In the text box, type the name of the shape. The name must be mapped to the same full column name as defined in the stored procedure.

Troubleshooting the Merge

  • When the configured merge is run, either by dataform save trigger or by custom link, there must be a value in the corresponding file field(s) for an image to appear in the corresponding "named range" area. Fields left empty or containing a file that is not an image will result in an empty image or be skipped depending on the Template Type.

  • Updated but unsaved file field changes will not appear in the merge and may even result in an error.

  • If the resulting image appears stretched, the template’s specified image area must be adjusted accordingly.

  • Image merges do support transparency only if the source image is transparent. Please check the source image if transparency is not applied as expected to ensure the source image is transparent.

  • If an image appears blank or not replaced after a merge is run, please double check the file in the corresponding dataform field. Is it an image file? If it is anything other than an image file, the merge replacement is skipped. For Word merges: The placeholder shape may now also display the following alt-text if the file is not an image file: “Provided file was not a supported image format.”