20.2. Email Templates

20.2.1. Introduction 

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.

20.2.2. Email Template Syntax 

The base syntax of an Email Template [2] 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>
    <!-- $obj.attr$ placeholders are replaced at runtime --> ②

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

    <!-- HTML --> ④
    <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 dentified 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.

20.2.2.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.

Stock Image Identifiers
Object.attribute	Value
`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.

The XML snippet below shows how it works:

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

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

  <a href="https://mysite.xyz">
    <img alt="mysite.xyz" src="cid:$cid_2$"/> ④
  </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.

20.2.3. 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:

Stationary.
Application.

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$ ①
      $stationary.content$ and additional app placeholders]]></entry> ②

    <!-- HTML -->
    <entry key="html"><![CDATA[HTML with <b>$stationary.header$</b>
      <p>$stationary.content$ and additional cid_ and app placeholders</p>]]> ③
    </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 Email Stationary Types.

20.2.4. 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 --> ①
    <entry key="subject">Text with $obj.attr$ placeholders</entry>

    <!-- Optional stationary --> ②
    <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. If 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.

20.2.5. Email Placeholders Objects 

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

20.2.5.1. Stationary 

Object uniquely used by Email Stationary Template.

Placeholder: Stationary
Object.attribute	Value
`stationary.header`	The `header` entry of the embedded template.
`stationary.content`	The `text` or `html` entry of the embedded template.

20.2.5.2. Application 

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

Placeholder: Application
Object.attribute	Value
`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”

20.2.5.3. Ticket 

A Print Job Ticket. See Job Tickets Web App.

Placeholder: Ticket
Object.attribute	Value
`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).

20.2.5.4. User 

A User as Person.

Placeholder: User
Object.attribute	Value
`user.fullName`	The full name of the user.

20.2.5.5. User Registration 

Placeholder: User Registration
Object	Value
`user_reg.userName`	User Name.
`user_reg.fullName`	User Full Name.
`user_reg.link`	Verification URL.

20.2.6. 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.

Email Stationary Types
Name	Scope
`EmailStationary`	All Email messages

20.2.7. 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.

20.2.7.1. JobTicketCanceled Email 

Email sent when a Job Ticket is canceled. See Job Ticket Configuration Properties.

The following placeholder objects apply:

Placeholder Objects: JobTicketCanceled
Object	Role
`ticket`	Canceled Job Ticket.
`user`	Job Ticket Creator.

20.2.7.2. JobTicketCompleted Email 

Email sent when a Job Ticket is completed successfully. See Job Ticket Configuration Properties.

The following placeholder objects apply:

Placeholder Objects: JobTicketCompleted
Object	Role
`ticket`	Completed Job Ticket.
`user`	Job Ticket Creator.

20.2.7.3. UserRegVerification 

Email sent to verify User Self Registration.

The following placeholder objects apply:

Placeholder Objects: UserRegVerification
Object	Role
`user_reg`	User Self Registration.

20.2.8. 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 Properties for Custom Template Locations
Configuration property	Description
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`

See Config Editor on how to set these items.