16.2. Email Templates

Email templates are a powerful instrument to customize layout and content of email messages. Templates are defined as XML files, and are located in the /opt/savapage/server/custom/template/ directory by default (alternative locations can be configured).

Default templates are present in the SavaPage i18n jars. Therefore, after a first-time installation the custom template/ directory will be empty. However, when SavaPage finds a suitable i18n XML file in the custom directory, that belongs to an Email Message Type, it will use that template.

You can create i18n variants of template XML files by appending the locale to the base file name. For example: template_de.html is the German variant of template.xml.

16.2.1. Email Template Syntax

The base syntax of an Email Template is described by example in the following XML file:

<?xml version= "1.0" encoding= "UTF-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> 1

<properties>
    <!-- $obj.attr$ placeholders are replaced at runtime --> 2

    <!-- TEXT --> 3
    <entry key="text"><![CDATA[Text with $obj.attr$ placeholders.]]></entry>

    <!-- HTML --> 4
    <entry key="html"><![CDATA[<b>HTML</b><p>
      with $obj.attr$ and other placeholders</p>]]>
    </entry>

</properties>

1

DTD of XML persisted java.util.Properties file.

2

Placeholder object attributes are identified by a $ character at the beginning and the end. Valid objects are defined for each Email Message Type. The global Application Object is valid for all types.

3

Content for plain text message body.

4

Content for html message body.

16.2.1.1. Embedded Images

HTML content may contain Embedded (Inline) Images.

Images are first defined in separated template entries with keys that have cid_ prefix. Those keys can then be used as placeholders for cid scheme values. SavaPage email processor will embed the image file and replace cid placeholders with a unique Content-ID for the Embedded (Inline) Image.

Custom image files are referred to by their relative path from the custom template/ directory. Internal stock images can simply be referred to by their upper-case identifier, as shown in the table below.

Object.attributeValue

SAVAPAGE_ICON

SavaPage Icon: 32 x 32 pixels, 705 bytes.

SAVAPAGE_LOGO

SavaPage Logo with "SavaPage" text at the bottom: 148 x 174 pixels, 5.6 kB.

Table 16.1. Stock Image Identifiers


The XML snippet below shows how it works:

<entry key="cid_1">SAVAPAGE_ICON</entry>           1
<entry key="cid_2">images/mysite-logo.png</entry>  2

<entry key="html"><![CDATA[
  <img src="cid:$cid_1$" alt="$app.name$">         3

  <a href="https://mysite.xyz">
    <img alt="mysite.xyz" src="cid:$cid_2$"/>      4 
  </a>

]]></entry>

1

cid_1 holds a stock image.

2

cid_2 holds the relative path to a custom image file.

3

Note that the URL of the image has scheme cid. SavaPage email processor will embed the image and replace $cid_1$ with a unique Content-ID for the Embedded (Inline) Image with key cid_1.

4

The cid_2 image is handled just as its cid_1 sibling.

16.2.2. Email Stationary Template

An Email Stationary Template is used by an Email Message Template as container to embed its content in. A stationary is typically used by many Email Messages Types, and thus gives a common look-and-feel to various email output.

A Stationary Template contains the following placeholder objects:

And this is how it looks like:

<?xml version= "1.0" encoding= "UTF-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">

<properties>

    <!-- TEXT -->     
    <entry key="text"><![CDATA[Plain text with $stationary.header$  1
$stationary.content$ and additional app placeholders]]></entry>     2

    <!-- HTML -->
    <entry key="html"><![CDATA[HTML with <b>$stationary.header$</b>
      <p>$stationary.content$ and additional cid_ and app placeholders</p>]]> 3
    </entry>

</properties>

1

$stationary.header$ is replaced by the header entry of the embedded template.

2

$stationary.content$ is replaced by the text entry of the embedded template.

3

$stationary.content$ is replaced by the html entry of the embedded template.

Note

SavaPage uses its own stationary types. These types can be overwritten. See Section 16.2.5, “Email Stationary Types”.

16.2.3. Email Message Template

Email Message Templates are used by Email Message Types.

Template and Type are tied by name.

For example: the JobTicketCompleted message type will look for the nearest i18n version of a JobTicketCompleted.xml template file. In this way, JobTicketCompleted_de.xml will be the perfect match when a German email message is requested.

Email Message Template adds the entry key subject to the syntax. Optionally, entry keys stationary and header can be used to link to an Email Stationary Template.

The syntax is described by example in the following XML file:

<?xml version= "1.0" encoding= "UTF-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>

    <!-- Email subject -->        1
    <entry key="subject">Text with $obj.attr$ placeholders</entry>
 
    <!-- Optional stationary -->  2
    <entry key="stationary">EmailStationary</entry>
    <entry key="header">Stationary header with placeholders</entry>

    <!-- TEXT -->     
    <entry key="text"><![CDATA[Plain text with placeholders.]]></entry>

    <!-- HTML -->
    <entry key="html"><![CDATA[<p>HTML with placeholders.</p>]]></entry>

</properties>

1

The subject text of the email.

2

The stationary value (just the template file basename, without the .xml suffix) refers to EmailStationary.xml, including i18n EmailStationary_*.xml variants. When a stationary is linked this way, the header value is injected into the stationary.header placeholder of the target stationary, and the text and html values are injected into the stationary.content placeholder of their counterpart stationary entry.

16.2.4. Email Placeholders Objects

Placeholder Objects are used in Email Stationary, and in Email Message Templates tied to Email Messages Types.

16.2.4.1. Stationary

Object uniquely used by Email Stationary Template.

Object.attributeValue

stationary.header

The header entry of the embedded template.

stationary.content

The text or html entry of the embedded template.

Table 16.2. Placeholder: Stationary


16.2.4.2. Application

A global object with SavaPage application attributes. This object can be used in any Email Message Type context.

Object.attributeValue

app.name

Application name: SavaPage

app.nameVersion

Formatted name and version, like:

SavaPage Major.Minor.Revision

app.nameVersionBuild

Formatted name, version and build, like:

SavaPage Major.Minor.Revision (Build)

app.slogan

Short slogan describing the application:

Open Print Portal

Table 16.3. Placeholder: Application


16.2.4.3. Ticket

A Print Job Ticket. See Chapter 5, Job Tickets Web App.

Object.attributeValue

ticket.number

Ticket number.

ticket.name

Document name.

ticket.operator

Name of the Job Ticket Operator.

ticket.returnMessage

The return message to Job Ticket Creator (optional).

Table 16.4. Placeholder: Ticket


16.2.4.4. User

A User as Person.

Object.attributeValue

user.fullName

The full name of the user.

Table 16.5. Placeholder: User


16.2.5. Email Stationary Types

SavaPage uses its own Email Stationary Types. As the table below shows, currently there is just one type in use. You can use this type in your own custom Email Message Template files. Or, you can override this type by creating your own EmailStationary.xml i18n variants in the custom template/ directory.

NameScope

EmailStationary

All Email messages

Table 16.6. Email Stationary Types


16.2.6. Email Message Types

The sections below describe email message types that can be customized. The list is limited for now, but will grow as more messages are refactored for this purpose.

Note

The global Application Object is valid for each message type.

16.2.6.1. JobTicketCanceled Email

Email sent when a Job Ticket is canceled. See Table 3.3, “Job Ticket Print Configuration Properties”.

The following placeholder objects apply:

ObjectRole

ticket

Canceled Job Ticket.

user

Job Ticket Creator.

Table 16.7. Placeholder Objects: JobTicketCanceled


16.2.6.2. JobTicketCompleted Email

Email sent when a Job Ticket is completed successfully. See Table 3.3, “Job Ticket Print Configuration Properties”.

The following placeholder objects apply:

ObjectRole

ticket

Completed Job Ticket.

user

Job Ticket Creator.

Table 16.8. Placeholder Objects: JobTicketCompleted


16.2.7. Custom Template Locations

Custom templates are located in the /opt/savapage/server/custom/template/ directory. Sub-locations can be defined for different template groups. These sub-locations can then be activated for different applications, with the following configuration properties:

Configuration propertyDescription

custom.template.home

Home location of all template files, relative to the default location. For example: a value of group-1 will resolve to:

/opt/savapage/server/custom/template/group-1

custom.template.home.mail

Home location of Email template files, relative to the default location. For example: a value of group-1/mail will resolve to:

/opt/savapage/server/custom/template/group-1/mail

Table 16.9. Configuration Properties for Custom Template Locations


See Section 4.10.14.10, “Config Editor” on how to set these items.