Creating Correspondence with Templates and Image Substitution

This tutorial example demonstrates how to create correspondence by using templates including static and dynamic images. We use the CORRESPONDENCE.xsd schema file, the LoanCorrespondence example model, the templates applicant-template.html and applicant-template.docx and example images from the file. If you have not done already, you can download the zip file containing these sources from here:

The LoanCorrespondence model contains a structured data of the referenced Correspondence structured data type, a Correspondence UI Mashup and a Script application for adding image bookmarks. Templates are provided in HTML and Docx format including images, which will be included in the message.

To start with this example, add the CORRESPONDENCE.xsd file to your projects classpath. This structured data type is described in detail in chapter Using the predefined Structured Data Type for Correspondence in the End User Handbook.

Viewing the Example Model

Import the LoanCorrespondence model in the Business Process Modeling perspective. The model contains a structured data CORRESPONDENCE of structured data type CORRESPONDENCE containing the imported Correspondence xsd. It also contains two applications, the Correspondence UI Mashup and a Script application for adding image bookmarks. For details on the Correspondence UI Mashup, please refer to chapter Creating a Correspondence UI Mashup in the End User Handbook. Please take care to replace the URL in the mashup configuration with your context root.

Viewing the Script Application

Let's have a look at the Prepare Image Locations Script application.


The Script application has the following parameters:

Script Parameters
Figure: Script Parameters


The Script Code field contains the following code:

CORRESPONDENCE_OUT = {FieldMetaData: []};

/* Push the "FieldMetaData" array elements. Individual properties:
   - Type:         Metadata field type. Should always equal "image"
   - Name:         Word Docx Bookmark Name 
   - Location:     Document Repository image path (prefixed with repository://)
   - UseImageSize: Boolean indicating if original image size should be resized

// Example adding a static  image bookmark
    Type : "image",
    Name : "OtherLogo",
    Location : "repository:///documents/correspondence-templates/logos/sungard.png",
    UseImageSize : true

// Example adding a dynamic image bookmark based on "CompanyId" Process Data
if (CompanyId) {
        Type : "image",
        Name : "CompanyLogo",
        Location : "repository:///documents/correspondence-templates/logos/" + CompanyId + ".png",
        UseImageSize : true

Script Code
Figure: Script Code

In case the in-parameter CompanyId is empty, a static image bookmark with location "repository:///documents/correspondence-templates/logos/sungard.png" is pushed to the meta data. If CompanyId has a value, this value is used for a dynamic image bookmark. The location is created dynamically with the provided CompanyId data value as "repository:///documents/correspondence-templates/logos/" + CompanyId + ".png".

Viewing the Loan Correspondence Process

The Loan Correspondence process has the following workflow:

  1. Activity Enter Data reads data of the applicant, like name and id of the company
  2. Activity Prepare Image Locations implements the Script application we had a look at in the preceeding section. Data CompanyId has an in-data path and CORRESPONDENCE has an out-data path to the application activity accordingly.
  3. The next activity is the Correspondence UI Mashup using the CORRESPONDENCE input data
  4. A last activity Show Data displays the resulting CORRESPONDENCE data.

Loan Correspondence Process
Figure: Loan Correspondence Process

Uploading and Viewing the Correspondence Templates

Templates are provided in HTML and Docx format including images, which will be included in the message.

In the Workflow Execution perspective open the My Documents view. Upload the following correspondence templates, which are provided in the example ZIP file, in the Common Documents > correspondence-templates folder:

Uploaded Templates
Figure: Uploaded Templates

Create a subfolder logos and upload the example image files sungard.png and XYZ.png. Hereby, sungard.png will be used for the static image replacement and XYZ.png as dynamic image bookmark in our Script application.

Uploaded images
Figure: Uploaded images

Looking at the HTML Template Example

Our HTML template example has the following content:

<p><img src="data:image/jpeg;base64,$base64Encoder.encodeBase64String($dms.retrieveContent('/documents/correspondence-templates/logos/sungard.png'))"/></p>

<p>Dear <strong>$ApplicantName</strong>,</p>

<p>     We have received your loan application, but are missing the following documents.<span style="line-height:1.6em">     </span></p>

<table border="1" cellpadding="1" cellspacing="1" style="width:500px">
         <td>Driver's License</td>
         <td>A copy of your current valid Driver's License is required.</td>
         <td>Pay Slip</td>
         <td>A copy of your recent pay stub is required.</td>

<p>     Kindly send the above in to us at the earliest.</p>


<img src="data:image/jpeg;base64,$base64Encoder.encodeBase64String($user.signature)"/>

<p>$user.firstName $user.lastName</p>

<p> </p>

Image placeholder

The first line

<p><img src="data:image/jpeg;base64,$base64Encoder.encodeBase64String($dms.retrieveContent('/documents/correspondence-templates/logos/sungard.png'))"/></p>

contains an image link to the logo image we like to display at the top of the template. This is the sungard.png image we uploaded to the correspondence-templates/logos folder.

Please refer to section Including Images from the Document Repository of chapter Using Correspondence Templates in the End User Handbook for details on how to include images in templates and message editor source.

Process Data Path usage

The $ApplicantName variable references the Process data path ApplicantName and will be replaced with the value entered for the data accordingly.

User attributes usage

The following user attributes are used:

Please refer to section Using User Attributes of chapter Using Correspondence Templates in the End User Handbook for details on how to use user attributes.

Including the user signature

The image uploaded for the user signature is used. Please refer to section Including the User Signature of chapter Using Correspondence Templates in the End User Handbook for details on how to include the users signature.

Looking at the docx Template Example

Lets have a look at our docx template file. Open the file to view the content in Microsoft Word.

Correspondence Template docx File
Figure: Correspondence Template docx File

Two template images are added in the docx file. Bookmarks are linked to these images.

To view the bookmarks:

  1. In the Insert tab of the Word editor, select Bookmark.

  2. In the Bookmark dialog, you see two bookmarks added, CompanyLogo and signature.

  3. To see where these bookmarks belong to, click the bookmark name and select Go To.

Starting the UI Mashup

Creating a User with Signature

Create a user with an uploaded signature:

  1. Create a user in the Participant Management view and assign him to the Administrator role.
  2. Upload a signature for this user in the Configuration User Profile.

    Add User Signature

Starting the Loan Correspondence Process

To start the Loan Correspondence Process:

  1. Login with the created user account.
  2. In the Workflow Execution perspective, start process Loan Correspondence.
  3. Enter an applicant name and the company name XYZ.

    Enter Data

Using the HTML Template

To use the example HTML template, do the following:

  1. Click the Message entry on the left side of the message content editor.

    Open the Select Template dialog

  2. In the Select Template editor, expand the correspondence-template node.
  3. Select the example applicant-template.html template.

    Select Template

  4. Click OK

Now the message content editor displays the template content with substituted variables, image and signature.

Resulting Message Content
Figure: Message Content with replaced image, variables and signature

Attaching the DOCX Template

Now upload the DOCX template:

  1. Click the Select Attachments Icon icon to open the Select Attachments dialog.

  2. Select applicant-template.docx and click OK.

    Attachments Dialog

You see now the applicant-template.docx template listed in the attachments section.

Attached DOCX template
Figure: Attached DOCX template

Attaching a Document from File System

Additionally we attach a document from our file system:

  1. Click the Select Attachments icon.

    Attachments Dialog

  2. In the file browser select a document from your file system.

You see now the attached document listed in the attachments section.

Attached other file
Figure: Attached file from file system

Complete the Loan Correspondence UI Mashup activity. Activity Show Data displays the CORRESPONDENCE meta data.

Show Data
Figure: Displayed Correspondence data

Viewing the Correspondence in the Document Folder

In the Document Repository view or the Process Documents section in the process history view of the Loan Correspondence process, expand the correspondence folder.

You see the created correspondence, named as correspondence-out-x. It contains the attached docx template as well as the attached local file.

Correspondence displayed in Process Documents
Figure: Correspondence displayed in Process Documents

Viewing the Correspondence in read-only Mode

To view the correspondence in read-only mode, click the created correspondence node correspondence-out-x.

Click Correspondence
Figure: Click Correspondence

The correspondence opens in a read-only viewer.

Viewing the Correspondence
Figure: Viewing the Correspondence in read-only mode

Viewing the Correspondence DOCX Document

To view the resulting document of the attached DOCX template, you have to download the DOCX document first:

  1. Right-click the document and select the option

    Download DOCX document

  2. Click the Download button to start the download.


Now open the downloaded document in Microsoft Word. You see the placeholders in the DOCX template replaced with process data values. The dynamic image reference displays the XYZ.png image provided in the correspondence-templates/logos folder as we entered XYZ as Company Id. This referenced location was created via the Script Application by the following field meta data assignment:

Location : "repository:///documents/correspondence-templates/logos/" + CompanyId + ".png"

Resulting DOCX Document
Figure: Resulting DOCX Document