Creating and deploying external keyed images in EngageOne Designer\Generate

If there is a need to use multiple images in the output, these can be placed in the output at run time by using keyed external image references rather than importing all images into EngageOne® Designer.

The first step would be to create an external key map in EngageOne Designer.  This is created in the project by right clicking, selecting "New" and "External Keyed Images Key Map":

User-added image

Once the keymap is created, a key value needs to be entered, with a link to an existing image in the repository, this can be any image, it is simply a placeholder for the final image inserted at runtime:

User-added image

This only requires a single entry, the line number is sequential, the Key will be the key name that is looked for in the external keyed image xml file, and the final image is resolved by the external keyed image specified in this xml file.  

The keyed image link is set in EngageOne Designer from the Insert -> Presentation Objects - > Keyed image:

User-added image


Once this is inserted, the dialog needs to inform which keymap is to be used, and what the key is:

User-added image

In the example above, the key map name is the external key map inserted in the first step (keymap), and the key value is coming from a field in the data (Name):

User-added image

In order to map the key name to the image to be placed in the output, the easiest way is to create the external XML key file using the DOC1MAKE process.  DOC1MAKE is found in the Windows generate resources (this is a Windows only utility).

To create the external keymap, browse to the location of the DOC1MAKE executable. and from a command prompt enter "doc1make" without any parameters and this will provide all the options available:

EngageOne (r) Generate - Key Map Image Metrics Utility v6.6.8.164
Copyright (C) 1993-2019 Pitney Bowes Software Europe Ltd.

Host image metrics generator

                    Usage:

                    doc1make /M<mode> [/R<dpi>][/I<ID>] <file in> <file out> [<dpi>]

Where:
                    /M=<mode>   - mode = I or X or D or S. (default I)
                    I = read metrics from image <file in> and append to <file out>,
                    X = read image metrics file <file in> and create Generate Xml equivalent <file out>
                    D = read in a whole directory of images <file in> and generate Xml key map file <file out>
                    S = simply create a schema file

                    /L          - (optional) create metrics for landscape image (AFP ONLY)
                    /R=<dpi>    - (optional) set image resolution if undefined
                    /T=<ID>     - (optional) image type. Default is deduced from file contents
                    /I=<ID>     - (optional) image name. Default is filename - extension
                    /K=<key>    - key to assign to image
                    /N=<device> - device name for this image
                    /F=<filename> - (optional)filename to use for this image, default is current
                    /E=<Y/N>    - (optional) set embed flag, default is N
                    /D=<0,1,2>  - (optional) Set disposal option
                                 0 = Retain (default)
                                 1 = ClearAfterUse
                                 2 = ClearAfterJob
                    /P=<Y/N>    - (optional) set form-space flag, default is N
                    /C=<delim>  - (optional) image metrics file field delimiter, default is a comma
                    /ecp=<ecp file>  - (optional) file that holds extended codepages
                    /S=<schema> - name of schema file to generate in S mode or reference in X mode (default is extkeyim.xsd)
                    /O=<Y/N>  - (optional)EngageOne: Used in combination with the other modes while using Keymaps with EngageOne

When calling this tool, it is easiest to select the mode where an entry is made for all image present in a single directory using the /M=D option, the syntax for this would be:

doc1make /M=D /N=Output1 (path to where images reside) (path to where the keymap file should be deployed\name_of_keymap.xml)

The /E=Y switch is useful, and this ensures that the image will be embedded in the output.

The /N=Output1 switch can either be defined by the output by number (Output1, Output2 and so forth), but it is also valid to enter the name of the output device, for example /N=AFP300.

If there is a need to add different image types for multiple output streams to an existing keymap xml file, then the mode would be /M=I.

In this instance the folder specified for the /M=D option contains images that match the value of the Name field in the input data (this is case sensitive, so the image names should match the value from the field exactly).

This would give the following entries in an external keymap file:

<?xml version="1.0" encoding="UTF-8"?>
<ExternalKeyedImages Label="Generated by Doc1Make version 6.6.8.164" Version="1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="extkeyim.xsd">
<!-- NotEO doc1make command line = /M=D /N=Output1 C:\images C:\images\mykepmap.xml  -->
    <ImageDefaults Width="480" Height="318" Resolution="96" Embed="true" Disposal="Retain" FormSpace="false"/>
    <Keys>
        <KeyEntry Key="BigDog">
            <Image >
                <ImageDeviceInfo Device="Output1" ImageType="BMP" ResourceName="BIGDOG" FileName="C:\images\BigDog.bmp" Width="480" Height="318" Resolution="0" />
            </Image>
        </KeyEntry>
        <KeyEntry Key="MyDog">
            <Image Width="523" Height="424" Resolution="72" >
                <ImageDeviceInfo Device="Output1" ImageType="BMP" ResourceName="MYDOG" FileName="C:\images\MyDog.bmp" Width="523" Height="424" Resolution="0" />
            </Image>
        </KeyEntry>
        <KeyEntry Key="NoDog">
            <Image Width="270" Height="400" >
                <ImageDeviceInfo Device="Output1" ImageType="BMP" ResourceName="NODOG" FileName="C:\images\NoDog.bmp" Width="270" Height="400" Resolution="0" />
            </Image>
        </KeyEntry>
        <KeyEntry Key="SmallDog">
            <Image Width="260" Height="270" >
                <ImageDeviceInfo Device="Output1" ImageType="BMP" ResourceName="SMALLDOG" FileName="images\SmallDog.bmp" Width="260" Height="270" Resolution="0" />
            </Image>
        </KeyEntry>
    </Keys>
</ExternalKeyedImages>

This tells generate that when the data field "Name" equals, SmallDog, then it will place SmallDog.bmp in the output document.

The Production Guide (Defining External Keyed Images) section describes this in more detail, including which image formats are compatible with the various output streams and how to create the keymap if DOC1MAKE is not available..
UPDATED:  July 20, 2020