Dynamically inserting an image in to a document requires two things:
- The template controls where the image will appear
- The data determines what image is used
This article explains how to structure the data.
The Template
Please refer to this article to learn how to use a placeholder image in the template to control where the image appears in the final document.
The three options below assume the template will be using the data item "logoImage".
The Data
The image that will appear in the finished document is determined by the data.
When calling the REST API of Cloud or Tornado, there are three different ways to provide image data.
Send the image in the data as a BASE64 encoded binary representation
In JSON format, the data would look like this:
"logoImage":"image:base64:iVBORw0KGgoAAAA... "
Note that the data must have "image:base64:" appended before the BASE64 data string.
Use an image file name, also called stock images
This approach is useful where the same image (eg: a signature or a logo) will be used multiple times, possibly in many different documents.
The image must be provided to Docmosis before the document generation occurs and the data contains a reference to that image.
CLOUD: The images should be loaded to the Images area either via the Cloud Console or using the API. If you use folders to organise your images, the path should include those folders.
TORNADO: The images should be stored in the same folder used for the templates. You may choose to create a top level folder (for example: "Images") to help separate the images from your templates, in which case your would use:"[userImage:Images/...]"
In JSON format, the data should look like this:
"logoImage":"[userImage:customers/Meta-Logo-Long.png]"
Note the values are surrounded by square "[ ]" brackets. The text "userImage:" precedes the filename. The filename can also include a path to the image.
The URL of the image
In this case the image to be inserted will be provided by a URL. This approach may be useful where the image is dynamically generated or is specific to each document.
"logoImage":"[imageUrl:http://metalegalfinance.com/resources/Meta-Logo-Long.png]"
Note the values are surrounded by square "[ ]" brackets. The text "imageUrl:" precedes the URL path.
The URL needs to be whitelisted, before it can be used.
CLOUD: To whitelist a URL please contact support to organize this.
TORNADO: To whitelist a URL you need to apply a Custom Setting on the Configuration page of the Tornado Console. The setting is: "docmosis.external.resources.whitelist=https://example.com;http://another.com" (without the quotes). To whitelist multiple domains, seperate each URL with a semi-colon. Enter the URL in the Custom Setting textbox, then hit the Save button and then hit Restart (on the Status page).
Please refer to the Web Services Guide for further details on how to format/structure your image data.
