Action Request System 6.

0
Remedy Email Engine Guide

February 2004
Part No: AR-600-EEG-01
Copyright 2002–2004 BMC Software, Inc. All rights reserved.

Remedy, the Remedy logo, all other Remedy product or service names, BMC Software, the BMC Software
logos, and all other BMC Software product or service names, are registered trademarks or trademarks of
BMC Software, Inc. All other trademarks belong to their respective companies.

Remedy, a BMC Software company, considers information included in this documentation to be

proprietary and confidential. Your use of this information is subject to the terms and conditions of the
applicable end user license agreement or nondisclosure agreement for the product and the proprietary and
restricted rights notices included in this documentation.

For license information about the OpenSource files used in the licensed program, please read
OpenSourceLicenses.pdf. This file is in the \Doc folder of the distribution CD-ROM and in the
documentation download portion of the Remedy Electronic Software Distribution (ESD).

Restricted Rights Legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE
COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the
U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS
252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is
BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

Contacting Remedy
If you need technical support for this product, contact Remedy Customer Support by email at
[email protected]. If you have comments or suggestions about this documentation, contact
Information Development by email at [email protected].

This edition applies to version 6.0 of the licensed program.

Remedy, a BMC Software company

www.remedy.com
Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Overview of this manual . . . . . . . . . . . . . . . . . . . . . . . . 10
Action Request System documents . . . . . . . . . . . . . . . . . . . 11

Chapter 1 Overview of the Remedy email engine . . . . . . . . . . . . . . . . . . 15

About the Remedy email engine . . . . . . . . . . . . . . . . . . . . . 16
Email engine terminology . . . . . . . . . . . . . . . . . . . . . . . 18
How the email engine works . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2 Remedy email engine installation and setup . . . . . . . . . . . . . . . 23

Overview of installing the Remedy email engine . . . . . . . . . . . . . . 24
Pre-Installation steps for using MAPI . . . . . . . . . . . . . . . . . . 25
Pre-Installation steps for using MBOX . . . . . . . . . . . . . . . . . . 27
Upgrading to 6.0 email engine . . . . . . . . . . . . . . . . . . . . . 28
Windows: installing the email engine . . . . . . . . . . . . . . . . . . 29
Configuring your incoming mailbox using MAPI . . . . . . . . . . . . 33
Configuring your incoming mailbox using POP3 or IMAP4 . . . . . . . . 35
Configuring your outgoing mailbox using MAPI . . . . . . . . . . . . 37
Configuring your outgoing mailbox using SMTP . . . . . . . . . . . . 40
Windows: upgrading from Remedy mail server to 6.0 email engine . . . . . 43

Contents W 3
Action Request System 6.0

UNIX: installing the email engine . . . . . . . . . . . . . . . . . . . . 50

Additional files required for Linux and AIX installations . . . . . . . . . 55
Installing on UNIX as non-root . . . . . . . . . . . . . . . . . . . . 56
Configuring your incoming mailbox using IMAP4 . . . . . . . . . . . . 57
Configuring your incoming mailbox using POP3 . . . . . . . . . . . . 58
Configuring your incoming mailbox using MBOX . . . . . . . . . . . . 59
Configuring your outgoing mailbox using SMTP . . . . . . . . . . . . 60
UNIX: upgrading the Remedy mail server to 6.0 email engine . . . . . . . 62
Installed files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Files installed for email engine running on Windows systems . . . . . . . 69
Files installed for email engine running on UNIX systems . . . . . . . . . 70
Starting and stopping the email engine . . . . . . . . . . . . . . . . . . 70
UNIX server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Windows server . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Chapter 3 Email configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Email configuration overview . . . . . . . . . . . . . . . . . . . . . . 74
Working with the mailbox configuration form . . . . . . . . . . . . . . 75
Creating and configuring incoming mailboxes . . . . . . . . . . . . . . 76
Configuring your incoming mailbox using MAPI . . . . . . . . . . . . 77
Configuring your incoming mailbox using POP3 or IMAP4 . . . . . . . . 78
Configuring your incoming mailbox using MBOX . . . . . . . . . . . . 80
Advanced configuration settings for incoming mailboxes . . . . . . . . . 82
Creating and configuring outgoing mailboxes. . . . . . . . . . . . . . . 85
Configuring your outgoing mailbox using SMTP . . . . . . . . . . . . 86
Configuring your outgoing mailbox using MAPI . . . . . . . . . . . . 87
Advanced configuration settings for outgoing mailboxes . . . . . . . . . 88
Implementing changes to your mailbox configuration . . . . . . . . . . . 91
Configuring a sent mail folder (MAPI) . . . . . . . . . . . . . . . . . . 92
Testing your mailbox configuration . . . . . . . . . . . . . . . . . . . 93
Testing your incoming mailbox . . . . . . . . . . . . . . . . . . . . 93
Testing your outgoing mailbox . . . . . . . . . . . . . . . . . . . . 96
Configuring email security . . . . . . . . . . . . . . . . . . . . . . . 99
Creating email security keys for incoming mail . . . . . . . . . . . . 100
Security for outgoing mail with query actions . . . . . . . . . . . . . 102
Email options in the AR System configuration file . . . . . . . . . . . . . 103

4 XContents
 Remedy Email Engine Guide

Chapter 4 Email templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

About email templates . . . . . . . . . . . . . . . . . . . . . . . . . 106
Types of templates . . . . . . . . . . . . . . . . . . . . . . . . 106
Creating templates. . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Exporting mail templates. . . . . . . . . . . . . . . . . . . . . . 111
Labels and values used in the templates . . . . . . . . . . . . . . . . . 113
Global and local parameter declarations . . . . . . . . . . . . . . . 122
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Label and value formats . . . . . . . . . . . . . . . . . . . . . . 127
Storing templates in the AR System Email Templates form . . . . . . . . . 131
Adding attachments to templates . . . . . . . . . . . . . . . . . . . . 132
Adding a previously saved attachment to your template . . . . . . . . . 135
Modifying an attachment . . . . . . . . . . . . . . . . . . . . . 135
Deleting an attachment . . . . . . . . . . . . . . . . . . . . . . 136
Exporting templates with attachments to another server . . . . . . . . 136
Setting default templates for specific outgoing mailboxes . . . . . . . . 136
User-Defined instruction templates . . . . . . . . . . . . . . . . . . . 138
Preparing email templates after an upgrade . . . . . . . . . . . . . . . . 145

Chapter 5 Messages and notifications . . . . . . . . . . . . . . . . . . . . . . . 147

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Sending an outgoing email using the Messages form . . . . . . . . . . . . 149
Adding attachments to your email . . . . . . . . . . . . . . . . . . 152
Displaying advanced options . . . . . . . . . . . . . . . . . . . . 156
Sending an email to the AR System . . . . . . . . . . . . . . . . . . . 162
Using email to query the AR System . . . . . . . . . . . . . . . . . . . 166
Email notifications . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Email notifications for UNIX and Windows servers . . . . . . . . . . 169

Chapter 6 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Error and system status logs . . . . . . . . . . . . . . . . . . . . . . 182
Email transmission or instruction failures . . . . . . . . . . . . . . 184
AR System API errors . . . . . . . . . . . . . . . . . . . . . . . 184
Internal email engine errors . . . . . . . . . . . . . . . . . . . . 184
Submitting requests across different time zones . . . . . . . . . . . . . . 185

Contents W 5
Action Request System 6.0

Troubleshooting for Windows servers . . . . . . . . . . . . . . . . . . 185

Verifying permissions for the Windows account . . . . . . . . . . . . 185
Troubleshooting email request processing and notify filters . . . . . . . 186
Debugging options for the Remedy email engine . . . . . . . . . . . . . 187
Updating the emaildaemon.properties file . . . . . . . . . . . . . . . . 189
Performance and configuration settings . . . . . . . . . . . . . . . 191
Creating email debug batch files. . . . . . . . . . . . . . . . . . . . . 194
Debugging the Windows email engine . . . . . . . . . . . . . . . . 195
Debugging the UNIX email engine . . . . . . . . . . . . . . . . . 198

Appendix A Examples of email templates . . . . . . . . . . . . . . . . . . . . . . 201

Modifying templates for search actions with the Remedy Email Engine . . . 202
The modify action . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Sample templates . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
Email content template containing basic actions . . . . . . . . . . . . 213
Email reply with no template specified . . . . . . . . . . . . . . . . 214
Email reply using a result template in HTML format . . . . . . . . . . 215
Email status template in HTML format. . . . . . . . . . . . . . . . 217
Adding a header template and a footer template . . . . . . . . . . . . 219
Email content template in HTML format with a text field and a reply using no
template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Content template in XML format . . . . . . . . . . . . . . . . . . 222

Appendix B Email engine installation worksheet . . . . . . . . . . . . . . . . . . . 225

Installation prompt information . . . . . . . . . . . . . . . . . . . . 226
Email configuration information . . . . . . . . . . . . . . . . . . . . 227
Incoming mailbox (Windows) . . . . . . . . . . . . . . . . . . . 227
Outgoing mailbox (Windows) . . . . . . . . . . . . . . . . . . . 228
General email (UNIX) . . . . . . . . . . . . . . . . . . . . . . . 229
Incoming mailbox (UNIX) . . . . . . . . . . . . . . . . . . . . . 230
Outgoing mailbox (UNIX) . . . . . . . . . . . . . . . . . . . . . 231

6 XContents
 Remedy Email Engine Guide

Appendix C Setting up UNIX mailboxes . . . . . . . . . . . . . . . . . . . . . . . 233

Appendix D Upgrading email option parameters . . . . . . . . . . . . . . . . . . . 235

Appendix E Email engine forms . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Contents W 7
Action Request System 6.0

8 XContents
Preface

Audience
This guide is for administrators who are responsible for installing and
maintaining the Remedy® Email Engine. Before you explore the topics in this
guide, ensure that you understand the terms and concepts discussed in the
Optimizing and Troubleshooting AR System guide, which contains all the
required information for setting up and administering a basic
Action Request System® (AR System®) environment. Your knowledge of
basic administrative AR System tasks is crucial for the successful
implementation of the strategies discussed in this guide.

You must know how to use the AR System, including the Remedy
Administrator, Remedy User, and Remedy Import. Refer to the Installing
AR System guide, the Developing AR System Applications: Basic guide, and the
Developing AR System Applications: Advanced guide for additional
information.

Preface W 9
Action Request System 6.0

Overview of this manual

„ Chapter 1, “Overview of the Remedy email engine,” provides a description
of the Remedy email engine and its functionality.
„ Chapter 2, “Remedy email engine installation and setup,” provides
instructions for installing the Remedy email engine and creating an initial
mailbox configuration.
„ Chapter 3, “Email configuration,” provides information about
configuring mailboxes.
„ Chapter 4, “Email templates,” explains how email templates are created
and used with the AR System email engine.
„ Chapter 5, “Messages and notifications,” provides instructions for
creating email messages and working with notifications.
„ Chapter 6, “Troubleshooting,” provides information about identifying
and diagnosing error messages and other system problems.
„ Appendix A, “Examples of email templates,” provides several sample
email templates and illustrations of resulting email formats.
„ Appendix B, “Email engine installation worksheet,” provides an
installation worksheet to help you install and configure the email engine.
„ Appendix C, “Setting up UNIX mailboxes,” provides guidelines for
establishing a mailbox address for UNIX systems.
„ Appendix D, “Upgrading email option parameters,” provides AR System
configuration parameters used in the Remedy Mail Server and their
equivalents in the 6.0 Remedy email engine.
„ Appendix E, “Email engine forms,” lists the administration, user, and
workflow forms used in the Remedy email engine.

10 XPreface
 Remedy Email Engine Guide

Action Request System documents

The following table lists the documentation available for Action Request
System products.

Unless otherwise noted, online documentation in Adobe Acrobat (PDF)

format is available on AR System product installation CDs, on the Customer
Support web site (http://supportweb.remedy.com), or both. You can order
any of the printed manuals by sending a request to [email protected].

You can access product Help through each product’s Help menu or by
clicking on Help links.

Title and Part Number Description Audience Format

Action Request System 6.0 - Overview of AR System architecture Everyone PDF and
Concepts Guide and features with in-depth examples; Print
AR-600-CG-01 includes information about other
AR System products as well as a
comprehensive glossary for the entire
AR System documentation set.
Action Request System 6.0 - Basic procedures for creating and Administrators PDF and
Developing AR System modifying an AR System application Print
Applications: Basic for tracking data and processes.
AR-600-DABG-01
Action Request System 6.0 - Advanced procedures for extending Administrators PDF and
Developing AR System and customizing AR System Print
Applications: Advanced applications.
AR-600-DAAG-01
Action Request System 6.0 - Server administration topics on Administrators PDF and
Configuring AR System configuring servers and the mid tier, Print
AR-600-CFG-01 maintaining AR System, and licensing
AR System.
Action Request System 6.0 - Server administration topics and Administrators PDF and
Optimizing and Troubleshooting technical essays related to monitoring Print
AR System and maintaining AR System for the
AR-600-OTG-01 purpose of optimizing performance
and troubleshooting problems.

Action Request System documents W 11

Action Request System 6.0

Title and Part Number Description Audience Format

Action Request System 6.0 - Database administration topics and Administrators PDF and
Database Reference Guide rules related to how AR System Print
AR-600-DRG-01 interacts with specific databases;
includes an overview of the data
dictionary tables.
Action Request System 6.0 - Server administration and procedures Administrators PDF and
Remedy DSO Administrator’s for implementing a distributed Print
Guide AR System server environment with
AR-600-DSOG-01 the Remedy Distributed Server Option
(DSO).
Action Request System 6.0 - Flashboards administration and Administrators PDF and
Remedy Flashboards procedures for creating and modifying and Print
Administrator’s Guide flashboards and flashboards Programmers
FB-600-AG-01 components to display and monitor
AR System information.
Action Request System 6.0 - Information about AR System data Administrators PDF and
C API Reference Guide structures, C API function calls, and and Print
AR-600-CAPI-01 OLE support. Programmers

Action Request System 6.0 - Quick reference to C API function Administrators PDF and
C API Quick Reference Guide calls. and Print
AR-600-CAQR-01 Programmers

Action Request System 6.0 - Information about Java classes, Administrators HTML*
Java API methods, and variables that integrate and
with AR System. Programmers
Action Request System 6.0 - Procedures for installing AR System. Administrators PDF and
Installing AR System Print
AR-600-IG-01
Action Request System 6.0 - Procedures for installing, configuring, Administrators PDF and
Remedy Email Engine Guide and using the Remedy Email Engine. Print
AR-600-EEG-01
Action Request System 6.0 - List and expanded descriptions of Administrators PDF and
Error Messages Guide AR System error messages. and Print
AR-600-EMG-01 Programmers

Action Request System 6.0 - Combined index of all books. Everyone PDF and
Master Index Print
AR-600-MI-01

12 XPreface
 Remedy Email Engine Guide

Title and Part Number Description Audience Format

Action Request System 6.0 - New features list, compatibility lists, Everyone PDF and
Release Notes international issues, and open and Print
AR-600-RN-01 fixed issues.

Remedy User help Procedures for using Remedy User. Everyone Product
Help
Remedy Import help Procedures for using Remedy Import. Administrators Product
Help
Remedy Administrator help Procedures for creating and modifying Administrators Product
an AR System application for tracking Help
data and processes.
Remedy Alert help Procedures for using Remedy Alert. Everyone Product
Help
Remedy Configuration Tool help Procedures for configuring the Administrators Product
Remedy Mid Tier. Help
*A JAR file containing the Java API documentation is installed with the AR System server. Typi-
cally, it is stored in C:\ProgramFiles\AR System\Arserver\Api\doc\ardoc60.jar.

Action Request System documents W 13

Action Request System 6.0

14 XPreface
Chapter

1 Overview of the Remedy email

engine

This chapter provides an overview of the Remedy email engine. It includes

the following sections:
„ About the Remedy email engine (page 16)
„ Email engine terminology (page 18)
„ How the email engine works (page 20)

Overview of the Remedy email engine W 15

Action Request System 6.0

About the Remedy email engine

The AR System email engine is a service that transforms emails into an
interface to the AR System server. The email engine enables end-users to
instruct the AR System server to perform queries, submissions, or
modifications to entries, all using email. This feature is particularly useful for
users without direct access (a high-speed network link) to the AR System
server. The email engine can also return the results of such requests in email
formatted using plain text, RTF, HTML, or XML content. In addition, the
email engine can process notifications using workflow actions such as filters
or escalations.

Note: In the 6.0 release, you must install the email engine in order to send
notifications from the AR System server.

The email engine is a stand-alone client program that can be installed and
run on any computer system as an independent service. Running as a service,
the email engine provides the following capabilities:

„ Receiving mail: The Remedy email engine receives email messages from
an email account on your company mail server. These email messages can
include instructions that are then interpreted by the email engine into API
calls to your AR System server. These instructions can involve the
modification of form entries, entry submissions, or the retrieval of
multiple entries from your AR System server.
„ Sending mail: The email engine can be used to send email messages which
can include the results of queries, submissions, or modifications to entries
contained on your AR System server. These emails can be formatted using
templates that specify the layout of a message in either plain text, RTF,
HTML, or XML.
„ Processing notifications: If you choose email when creating a Notify filter
or escalation, you can use the email engine to send text messages, contents
of select fields, or attachments when workflow is triggered.

16 XChapter 1—Overview of the Remedy email engine

 Remedy Email Engine Guide

The email engine can connect to mail servers using the following protocols:

„ Internet Message Access Protocol (IMAP4): When mail arrives, copies of

messages are downloaded from the mail server to your local machine. A
copy of each message remains on the server.
„ Post Office Protocol (POP3): When mail arrives, messages are
downloaded to your local machine and removed from the mail server.
„ Simple Mail Transfer Protocol (SMTP): Used for outgoing mail
transmissions.
„ Messaging Application Programming Interface (MAPI): An interface
designed for use with Microsoft Windows that enables different email
applications to work together to distribute email. This interface is used
primarily with the MS Exchange Server. (Windows only)
„ MBOX: A protocol for storage of mail messages on a UNIX platform.
Messages are stored in a file under the user name with a file type of mbox.
All the settings for the AR System email engine are stored in forms within an
AR System server. The only information stored by the AR System email
engine is the location of the AR System server where the forms are stored. All
logging information—including errors, incoming emails, and outgoing
emails—are stored in separate forms on the AR System server. The forms can
be accessed from either AR System User or a web client.

Note: You may also configure the logs to be stored in a local text file by
specifying a handler property in the logging.properties file. For
information, see “Debugging options for the Remedy email engine” on
page 187.

The email engine provides additional options, including the ability to create
a variety of templates and the ability to include attachments with email
messages. It also supports Multipurpose Internet Mail Exchange (MIME)
types for attachments.

About the Remedy email engine W 17

Action Request System 6.0

Email engine terminology

Throughout this guide, some familiar terms are used in specific ways. It is
important to your understanding of the email engine to review these terms
and be familiar with their meaning as it pertains to this guide.

Mail server Computer system within your environment running a third-

party software program that processes incoming and outgoing
email messages.
Examples might include the MS Exchange server or the UNIX
sendmail program. Mail servers often contain one or more
email accounts.
Email account Refers to a user account on a mail server that permits an end-
user to transmit or receive email messages.
An email account can be associated with one or more email
addresses.
Note: An email account is not the same as an email address.
An email account consists of a user name and often includes a
password. End users must log on to the mail server using an
email account before they can send and receive email.
Mailbox Refers to an entry in the AR System Email Mailbox
Configuration form.
The AR System Email Mailbox Configuration form resides
on your AR System server and will be discussed in greater
detail in Chapter 3, “Email configuration.” A mailbox
contains all of the information required by the email engine to
either access mail from a mail server or to request that mail be
sent by a mail server. As such, a mailbox may contain such
information as the name of the mail server, the protocol used
by that mail server for either sending or receiving mail, and
email account information (if required).
Mailboxes are configured to be either Incoming Mailboxes or
Outgoing Mailboxes.

18 XChapter 1—Overview of the Remedy email engine

 Remedy Email Engine Guide

Incoming Mailbox containing the information required by the email

Mailbox engine to connect to and read email messages from a specific
email account on a mail server.
Email in this email account is treated as if it is directed to the
email engine.
The installation program provides an option for creating and
configuring an initial incoming mailbox. You can use this
mailbox to get started with the email engine; you can then
change these settings or configure additional mailboxes using
the AR System Email Mailbox Configuration form. For more
information, refer to “Creating and configuring incoming
mailboxes” on page 76.
Outgoing Mailbox containing the information required by the email
Mailbox engine to create and send messages.
The email engine will use this mailbox to send notifications,
send the results of queries, and so on.
The installation program provides an option for creating and
configuring an initial outgoing mailbox. You can use this
mailbox to get started with the email engine; you can then
change these settings or configure additional mailboxes using
the AR System Email Mailbox Configuration form. For more
information, refer to “Creating and configuring outgoing
mailboxes” on page 85.

Email engine terminology W 19

Action Request System 6.0

How the email engine works

This section demonstrates how the email engine interacts with the
AR System and your mail server in a sample scenario. Figure 1-1 presents a
sample environment for an email engine implementation. Review the figure
below, paying particular attention to the flow of activity.

Figure 1-1: How the email engine interacts with the AR System server

20 XChapter 1—Overview of the Remedy email engine

 Remedy Email Engine Guide

In this scenario, Shelly wishes to obtain a list of the latest issues stored in the
Fix-it Requests form. Shelly wants the results of this query to be returned in
a nicely formatted email that is easy to read. In addition, Shelly wants to
ensure that her co-workers Katie and Mark will be copied with the results of
this query. All of the steps that both the email engine and the users must take
to make this happen follow.

Step 1 After it is started, the email engine contacts the AR System server. The email
engine will then read in all of the entries in the AR System Email Mailbox
Configuration form and create Incoming and Outgoing mailboxes based
upon the information contained within these entries.

Step 2 Having been notified by the local Remedy administrator that the email
engine is up and running, Shelly composes an email that contains the
necessary instructions to the email engine to perform a query of the Fix-it
Requests form. She sends this message to an email account on the company
mail server that she knows is used by the email engine to poll for incoming
mail.

Step 3 The email engine, after waiting for a prescribed polling period, logs on to the
company mail server using the email account information gathered
previously during step 1. Because the mailbox information tells the email
engine that this particular email account is to be treated as an Incoming
Mailbox, the email engine will read the most recent emails from this account.
The email engine uses one of several email protocols for reading incoming
email from the company mail server (POP3, IMAP4, MBOX, or MAPI). It
will find and read the email that Shelly has sent here.

Step 4 When Shelly composed her email, she included specifically formatted
instructions that could be read and understood by the email engine. The
email engine, having read Shelly's email, now reads those instructions and
translates them into API calls to the AR System server in an attempt to fulfill
her query request.

Step 5 The AR System server responds to the email engine API calls with the
appropriate query information for the Fix-it Request form.

How the email engine works W 21

Action Request System 6.0

Step 6 The email engine, having successfully retrieved the requested information,
now turns to the Outgoing Mailbox that it created during step 1. It uses the
information in the Outgoing Mailbox to formulate a request to the company
mail server. It constructs a message according to formatting instructions
contained in the Outgoing Mailbox it is using. After constructing the
message, the email engine transmits the message to the mail server with
instructions to send the message to Shelly, Mark, and Katie using one of
several outgoing email protocols (SMTP or MAPI).

Step 7 Shelly, Mark, and Katie log on to the mail server to see if they have new mail.
They find the email constructed by the email engine which contains a nicely
formatted list of the most recent Fix-it Requests.

The previous example is a simplified one and is used to illustrate the

relationship the email engine has to other systems in a simplified
environment. Your environment may ultimately differ from the one
presented here in many respects. For example, the email engine may reside
on the same system as the AR System server. Alternatively, you may
configure the Incoming Mailbox and Outgoing mailbox to use the same
email account on your mail server, and so on. Much of the configuration
options available to you will be explained in the upcoming chapters. In
addition, as you proceed through this guide, you will learn about many of the
other email engine features for processing email.

22 XChapter 1—Overview of the Remedy email engine

Chapter

2 Remedy email engine

installation and setup

This chapter contains procedures for installing the Remedy Email Engine
(email engine) on Windows and UNIX operating systems.
It includes the following sections:
„ Overview of installing the Remedy email engine (page 24)
„ Pre-Installation steps for using MAPI (page 25)
„ Pre-Installation steps for using MBOX (page 27)
„ Upgrading to 6.0 email engine (page 28)
„ Windows: installing the email engine (page 29)
„ Windows: upgrading from Remedy mail server to 6.0 email engine
(page 43)
„ UNIX: installing the email engine (page 50)
„ UNIX: upgrading the Remedy mail server to 6.0 email engine (page 62)
„ Installed files (page 69)
„ Starting and stopping the email engine (page 70)

Remedy email engine installation and setup W 23

Action Request System 6.0

Overview of installing the Remedy email engine

The email engine installer is a standalone utility available for both Windows
and UNIX systems (IBM AIX, HP-UX, Solaris, Linux). For Windows, the
installer is an executable: emaild.exe. On UNIX systems, this installer is a
script: ed_install.

This chapter contains instructions that will enable you to either install the 6.0
email engine, or upgrade an older version of the email engine to version 6.0.
Properly installing and configuring the email engine may require some
preparation on your part whether you are installing for the first time or
upgrading an existing installation. As such, we have provided you with a
step-by-step set of instructions that will guide you through the various
sections of this chapter as they may pertain to your environment. You
should begin the installation process starting with these steps, being sure to
follow the instructions outlined within each step before proceeding further.

Step 1 Read the Action Request System 6.0 Release Notes and the compatibility
matrix at: http://supportweb.remedy.com for the latest updates and
instructions for this product.

Step 2 Complete the email engine installation worksheet, found in Appendix B,

“Email engine installation worksheet.” This worksheet will help you prepare
the information you need to install and configure the email engine. If you
have not completed the worksheet in Appendix B, “Email engine installation
worksheet,” it is recommended that you do before proceeding with
installation of the email engine.

Step 3 Perform the pre-installation steps depending upon the mail protocol that
your mail server uses to send or receive emails (for example, MAPI or
MBOX). For specific information, see the following:

„ “Pre-Installation steps for using MAPI” on page 25

„ “Pre-Installation steps for using MBOX” on page 27

Step 4 Identify or install a 5.1.2 (or later) AR System server that the 6.0 email engine
will use. The 6.0 email engine will not work with pre-5.1.2 versions of the
AR System server. This AR System server will be used to store the forms
required by the email engine to function properly.

24 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Step 5 If you are upgrading from the 5.1.x email engine to 6.0, it is important that
you read “Upgrading to 6.0 email engine” on page 28 before going to step 6.
If you are upgrading a pre-5.1 email engine (Remedy Mail Server), proceed
to step 6.

Step 6 Follow one of these installation paths as they pertain to your environment:

„ “Windows: installing the email engine” on page 29

„ “Windows: upgrading from Remedy mail server to 6.0 email engine” on
page 43
„ “UNIX: installing the email engine” on page 50.
„ “UNIX: upgrading the Remedy mail server to 6.0 email engine” on page 62

Pre-Installation steps for using MAPI

If you are using MAPI to send and receive email, you must identify or create
a Windows user account and Exchange profile on the system to which you
will be installing the email engine. You must have permissions as an MS
Exchange administrator and a Windows domain administrator to complete
this procedure.
Note: You may need to consult with your MS Exchange administrator or
your Windows domain administrator to assist you with these steps.

If you are upgrading from the pre-5.1 Remedy Mail Server and you want to
use your existing configuration information, you may proceed directly to
“Windows: upgrading from Remedy mail server to 6.0 email engine” on
page 43 and skip these instructions.

In the “Email engine installation worksheet” on page 225, record the values
of the settings you select for those fields on the worksheet specifically labeled
“MAPI only.” Have the worksheet available when you run the installer, so
you can enter the values when the installer prompts you for them.

Pre-Installation steps for using MAPI W 25

Action Request System 6.0

To prepare the system, configure a Windows domain account and add an

Exchange mailbox and profile, as follows:

X To prepare for a MAPI installation:

1 As part of your system preparation, verify that the MS Exchange server is in
one of the following locations:
„ The same domain as the domain the email engine will reside in.
„ A domain with the appropriate trust relationship if the mail server and the
email engine will reside in different domains.

2 On the machine where the email engine will be installed, install an MS

Exchange client (such as Microsoft Outlook).
Performing this step enables you to obtain the MAPI client libraries. Refer to
your client documentation for specific instructions.
Note: The AR System email engine does not support Outlook Express or
Windows Messaging. Outlook 2000 and Outlook 2002 have an optional
security patch (Microsoft security patch) that will prevent the email
engine from working. In general, if a security fix prevents a service from
accessing an email account, the fix should not be applied to the system
where the email engine is installed because the email engine must access
the email account while running as a service.

3 Create or identify a Windows domain user account with specific permissions

to allow the email engine to start as a service.
This user account must be a member of:
„ Either the domain that the email engine will be installed in or the
Exchange Server domain, if these two domains are different.
„ The local administrator’s group (active directories only).

4 On the email engine system, grant this user two local advanced rights:
„ Act as Part of the Operating System.
„ Log on as a Service.

For Active Directories, ensure that the Effective Rights are set properly to
allow these advanced rights.
5 Create or identify an MS Exchange server mailbox dedicated for use by the
email engine and accessible by the user you created/identified during step 3.
Note: For the purpose of this section, the term “mailbox” is used to refer to
an email account on an MS Exchange server.

26 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

6 Log in to the system as the domain user.

7 Create an MS Exchange profile on the system on which you will install the
email engine. This profile should point to the mailbox you created/identified
in step 5.
8 Verify your Exchange profile is working by sending and receiving emails
using the MS Exchange profile you created.

Pre-Installation steps for using MBOX

If you are using MBOX to receive email, you must identify or create a mail
account before installation. For more information about creating an MBOX
mail account, see Appendix C, “Setting up UNIX mailboxes.”

X To prepare for an MBOX installation:

1 Ensure that you have the following information before you begin the
installation:
„ Inbox Path, which is the path to the mail file that the email engine will be
using. For example: /var/spool/mail/ARSystem.
„ User Home Path, which is the path to the home directory of the user for
whom the mail file has been created. For example: /home/ARSystem.

You can use the worksheet in Appendix B, “Email engine installation

worksheet” to record this information.

Warning: The MBOX store uses the dotlocking mechanism, which is

compatible with most UNIX MUAs and MTAs, to synchronize
concurrent access to the mailbox. You might experience data loss if you
use non-dotlocking mail agents, and mail agents and the MBOX provider
access the same mailboxes at the same time.

2 Verify that the MBOX account is working by sending emails to that account.

Pre-Installation steps for using MBOX W 27

Action Request System 6.0

Upgrading to 6.0 email engine

If you are upgrading from a previous version of the email engine (5.1.x) to
6.0, you will use the same set of instructions for new installations for both
Windows and UNIX. However, you should be aware of the following:

„ Because of field property changes between versions, upgrading the 5.1 or

5.1.1 email engine to 6.0 is not supported. If you upgrade using a pre-5.1.2
email engine, you will get unpredictable results. For example, updates to
base table/view column names only happen for 5 of 11 AR System Email
forms.
„ When Windows users are prompted for an installation directory, the
default installation path will be that of their last installation. You should
accept the default if it represents the path to the 6.0 installation you are
upgrading. Otherwise, you should modify the path to the directory in
which you installed the old email engine.
UNIX users will have to manually enter the path to their old installation,
because the default will be a generic default (not necessarily the path their
old installation).
„ Upgrading the email engine to 6.0 requires that you identify or install a
5.1.2 (or later) AR System server that the email engine will use. The email
engine will not work with older versions of the AR System server.
Note: The 5.1.x email engine does not work with the 6.0 AR System server.

„ When you are prompted to configure new mailboxes, you can skip these
steps completely if you want to use the mailboxes you already have
configured.
You can, of course, configure mailboxes after installation.
„ To start the email engine after upgrading to 6.0, users should stop the old
instance (when appropriate) and restart using the emailstart.sh script
present in the installation directory (UNIX only). Procedures for stopping
or restarting the email engine will be the same for 6.0 as it was for 5.1.x.

28 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Windows: installing the email engine

During the Windows AR System email engine installation, you are asked to
provide certain pieces of information. The following steps describe the
information needed and explain why. You will also use these instructions if
you are upgrading to 6.0 from the 5.1 or 5.1.1 email engine. (But first read
“Upgrading to 6.0 email engine” on page 28.)
To install the email engine, use the information you recorded in the “Email
engine installation worksheet” on page 225.
If you wish to use the MAPI protocol for incoming and outgoing mailboxes,
you must install the email engine on a Windows system. An email engine
installed on a UNIX system will not have access to the proper libraries
necessary to access a mail server using the MAPI protocol (which would be a
MS Exchange server).
Note: If you are upgrading from Remedy Mail Server (pre-5.1), use the
installation instructions in “Windows: upgrading from Remedy mail
server to 6.0 email engine” on page 43 instead.
X To install the Windows email engine:
1 Access the installation software.
„ From the CD:
Log in to Windows as an administrator and insert the CD into the drive.
If autorun is enabled, the CD browser opens. Click Install Products and
then click Remedy Email Engine.
If the CD browser does not start, run <cdrom_dir>\Launch.exe to open the
CD Browser manually. Click Install Products and then click Remedy
Email Engine.
The Welcome screen appears.
„ From the Electronic Software Distribution (ESD) process:
If you have acquired the email engine installer using the ESD process, be
sure to copy the installer files to the machine where you will install it. For
example, if you used the Solaris Sm@rtCert client to download the email
engine for Windows, copy the directory and its contents to your Windows
machine.
From the directory to which you copied the downloaded files, run the
installer executable, emaild.exe.
When you run this file, the installation files are unpacked into a temporary
directory and the Setup program starts. The Welcome screen appears.

Windows: installing the email engine W 29

Action Request System 6.0

2 Click Next to display the Software License Agreement screen.

3 Click the I Agree button to accept the software license agreement and to
display the Choose Destination Location screen.
4 Click Next to accept the default installation directory or click Browse to
choose another directory and then click Next. Preferably, install the email
engine into the directory that contains the AR System.
5 The AR Server to Support EMail Server screen appears. Enter the following
information:
„ In the AR Server Name field, enter the AR System server name, which is
the name of the server that the email engine uses.
„ In the Port Number field, enter the TCP port number the AR System uses
if your AR System server is not using Portmapper.
The AR System server installation program registers the server with a
portmapper by default, so in most cases, you can simply leave the Port
Number field empty.
If your AR System server does not register with portmapper, you must
provide the TCP port that the AR System server uses. You can also use a
TCP port if the email engine is on the other side of a firewall from the
AR System server.
For more information, refer to Registering with a Portmapper in the
Installing AR System guide.
„ In the RPC Port Number field, enter the RPC port number the AR System
server uses if you have configured a private server to use with the email
engine.
Otherwise, in most cases, you can simply leave the RPC Port Number field
empty.
For more information on private servers in the AR System, refer to the
Configuring AR System guide.
Note: If you have multiple AR System servers running on the same machine,
make sure you enter the correct server name and port number (if used).
For example, if you had two servers, polycarp1 (using portmapper) and
polycarp2 using port 9000, and you want to install the email engine with
polycarp2, you must use the real alias name of the server (polycarp2) with
the correct port number (9000) for the installation to work properly.
Otherwise, the email engine service dependency to the AR System server
will be incorrect.

30 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

6 Click Next to display the Administrator Logon Information Required screen

and enter an AR System Administrator user name and password.
The user name must have Administrator privileges on the AR System server.
This user will be used to import the necessary AR System email engine forms
and workflow.
7 Click Next to display the Application Service Password screen and enter the
password, if any.
Note: Either leave the application service password blank during installation,
or set it to the same value that it is set in AR System Administrator. To find
out what the value is in AR System Administrator, go to File > Server
Information, click the Connection Settings tab, and verify the Application
Service Password information. The application service password could be
set by Remedy applications like Approval Server or Flashboards.

8 Click Next to display the Start Copying Files screen. The installer displays
installation-related messages.
9 Click Next to begin copying files.
10 The AR System Email Mailbox Configuration screen appears.
Here you have four options:
„ Click No to postpone configuration until after installation. You will then
need to follow the instructions in Chapter 3, “Email configuration,” to
create either incoming or outgoing mailboxes after installation. Proceed to
step 11 to finish installation of the email engine.
„ Select Incoming and Outgoing from the Mailbox Function menu to
configure both an incoming and an outgoing mailbox, then click Yes. You
can expect to be prompted first to configure the incoming mailbox, then
the outgoing mailbox. Depending upon which protocol your mail server
uses for receiving mail, proceed to one of the following sections to begin
configuration of your incoming mailbox:
„ “Configuring your incoming mailbox using MAPI” on page 33
„ “Configuring your incoming mailbox using POP3 or IMAP4” on
page 35

Windows: installing the email engine W 31

Action Request System 6.0

„ Select Incoming from the Mailbox Function menu to configure only an

incoming mailbox, then click Yes. Depending upon which protocol your
mail server uses for receiving mail, proceed to one of the following
sections to begin configuration of your incoming mailbox:
„ “Configuring your incoming mailbox using MAPI” on page 33
„ “Configuring your incoming mailbox using POP3 or IMAP4” on
page 35

„ Select Outgoing from the Mailbox Function menu to configure only an

outgoing mailbox, then click Yes. Depending upon which protocol your
mail server uses for sending mail, proceed to one of the following sections
to begin configuration of your outgoing mailbox:
„ “Configuring your outgoing mailbox using MAPI” on page 37
„ “Configuring your outgoing mailbox using SMTP” on page 40

11 The remaining files are copied to your system.

If you installed the email engine and the AR System separately, you will get a
reminder that you must restart the AR System server.
The Setup Complete screen appears. Choose Yes to restart your computer
(optional) and click Finish to complete the installation.
For more detailed information about email configuration, refer to Chapter 3,
“Email configuration.”

32 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Configuring your incoming mailbox using MAPI

If you chose to perform the configuration of an incoming mailbox, the
AR System Email Mailbox Configuration - Incoming Mailbox screen
appears.

Use the information you recorded onto the “Email engine installation
worksheet” on page 225 to provide the incoming mailbox configuration
information for the MAPI protocol.

Figure 2-1: Incoming mailbox screen (MAPI)

X To configure your incoming mailbox (MAPI):

1 In the Mailbox Name field, enter a descriptive name for your incoming
mailbox, for example, AREmail - Incoming.

2 From the Email Server Type menu, select MAPI.

3 In the Email Profile field, enter the name of the MS Exchange profile.
This profile should point to your MS Exchange server mailbox dedicated for
use by the email engine.

Windows: installing the email engine W 33

Action Request System 6.0

4 Do one of the following:

„ If you chose to configure an outgoing mailbox, click Next, then go to one
of the following sections depending on the protocol used by your mail
server:
„ “Configuring your outgoing mailbox using MAPI” on page 37
„ “Configuring your outgoing mailbox using SMTP” on page 40

„ If you chose to configure only the incoming mailbox, click Next.

The Email Engine Mapi Logon Settings dialog box appears.

Figure 2-2: MAPI logon settings

5 In the Windows NT User field, enter the name of the user who has domain
permissions to start the email engine as a service as well as access to the
Exchange profile mailbox.
6 In the Password field, enter the user’s password to the domain.
7 In the Windows NT Domain field, enter the domain of the Windows user
account.

34 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

8 Click Next to complete copying files and display the Setup Complete screen.
If you installed the email engine and the AR System separately, you will get a
reminder that you must restart the AR System server.
9 Choose Yes to restart your computer (optional) and click Finish to complete
the installation. For more detailed information about email configuration,
refer to Chapter 3, “Email configuration.”

Configuring your incoming mailbox using POP3 or IMAP4

If you chose to perform the configuration of an incoming mailbox, the
AR System Email Mailbox Configuration - Incoming Mailbox screen
appears.

Use the information you recorded onto the “Email engine installation
worksheet” on page 225 to provide the incoming mailbox configuration
information for the POP3 or IMAP4 protocols.

Figure 2-3: Incoming mailbox screen (POP3 or IMAP4)

The figure above shows the settings available when you configure the
incoming mailbox to use the POP3 protocol. The fields in this dialog box,
however, are exactly the same for the IMAP4 protocol. The only differences
you will see are the default values in the Email Server Port field.

Windows: installing the email engine W 35

Action Request System 6.0

X To configure your incoming mailbox (POP3 or IMAP4):

1 In the Mailbox Name field, enter a descriptive name for your incoming
mailbox, for example, AREmail - Incoming.

2 From the Email Server Type menu, select POP3 or IMAP4.

3 If you are using SSL, select the SSL check box.
This enables the secure socket layer. SSL is available only if you are using
POP3 or IMAP4.
4 In the Email Server Name/IP field, enter the name or IP address of the mail
server used in your organization.
5 In the Email Server Port field, enter the port number used for connecting to
the mail server.
The default port number is determined by the protocol selected and whether
Secure Sockets Layer (SSL) is selected. If you do not enter a port number, the
following default values will be used:
„ POP3: 110
„ POP3 with SSL: 995
„ IMAP4: 143
„ IMAP4 with SSL: 993
6 In the Email Server User field, enter the user name of the administrator or
user for this email account.
Refer to your mail server administrator for your designated email username.
7 In the Email Server Password, enter the password associated with the user
name for this email account.
Refer to your mail server administrator for your designated email password.
8 Do one of the following:
„ If you chose to configure an outgoing mailbox, click Next, then go to one
of the following sections depending on the protocol used by your mail
server:
„ “Configuring your outgoing mailbox using MAPI” on page 37

„ “Configuring your outgoing mailbox using SMTP” on page 40

„ If you chose to configure only the incoming mailbox, click Next to
complete copying files and display the Setup Complete screen.
If you installed the email engine and the AR System separately, you will get
a reminder that you must restart the AR System server.

36 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

9 Choose Yes to restart your computer (optional) and click Finish to complete
the installation.
For more detailed information about email configuration, refer to Chapter 3,
“Email configuration.”

Configuring your outgoing mailbox using MAPI

If you chose to perform the configuration of an incoming mailbox, the
AR System Email Mailbox Configuration - Outgoing Mailbox screen
appears.

Use the information you recorded onto the “Email engine installation
worksheet” on page 225 to provide the outgoing mailbox configuration
information for MAPI.

Figure 2-4: Outgoing mailbox screen (MAPI)

Windows: installing the email engine W 37

Action Request System 6.0

X To configure your outgoing mailbox (MAPI):

1 In the Mailbox Name field, enter a descriptive name for your outgoing
mailbox, for example, AREmail - Outgoing.

2 In the Display Name field, enter the name you want displayed in email clients
for mail sent from this mailbox.
This setting will be the name in the From: line of the outgoing email. Change
the display name to something descriptive for your environment.
3 In the Email Address field, enter the full email address of the administrator
or owner of this mailbox.
The email address you enter and confirm will be the default From: email
address in outgoing emails. As a result, if you entered a Display Name of
ARSystem and an email address of [email protected], the From: line would
look like:
From: ARSystem [[email protected]]

4 From the Email Server Type menu, select MAPI.

5 In the Email Profile field, enter the name of the MS Exchange profile.
This profile should point to your MS Exchange server mailbox dedicated for
use by the email engine.
6 Click Next.

38 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

The Email Engine Mapi Logon Settings dialog box appears.

Figure 2-5: MAPI logon settings

7 In the Windows NT User field, enter the name of the user who has domain
permissions to start the email engine as a service as well as access to the
Exchange profile mailbox.
8 In the Password field, enter the user’s password to the domain.
9 In the Windows NT Domain field, enter the domain of the Windows user
account.
10 Click Next to complete copying files and display the Setup Complete screen.
If you installed the email engine and the AR System separately, you will get a
reminder that you must restart the AR System server.
11 Choose Yes to restart your computer (optional) and click Finish to complete
the installation. For more detailed information about email configuration,
refer to Chapter 3, “Email configuration.”

Windows: installing the email engine W 39

Action Request System 6.0

Configuring your outgoing mailbox using SMTP

If you chose to perform the configuration of an outgoing mailbox, the
AR System Email Mailbox Configuration - Outgoing Mailbox screen
appears.

Use the information you recorded onto the “Email engine installation
worksheet” on page 225 to provide the outgoing mailbox configuration
information for SMTP.

Figure 2-6: Outgoing mailbox screen (SMTP)

X To configure your outgoing mailbox (SMTP):

1 In the Mailbox Name field, enter a descriptive name for your outgoing
mailbox, for example, AREmail - Outgoing.

2 In the Display Name field, enter the name you want displayed in email clients
for mail sent from this mailbox.
This setting will be the name (not the email address) in the From: line of the
outgoing email. Change the display name to something descriptive for your
environment.

40 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

3 In the Email Address field, enter the full email address of the administrator
or owner of this mailbox.
The email address you enter and confirm will be the default From: email
address in outgoing emails. As a result, if you entered a Display Name of
ARSystem and an email address of [email protected], the From: line would
look like:
From: ARSystem [[email protected]]

4 From the Email Server Type menu, select SMTP.

5 If you are using SSL, select the SSL check box.
This enables the secure socket layer.
6 In the Email Server Name/IP field, enter the name or IP address of the mail
server used in your organization.
7 In the Email Server Port field, enter the port number used for connecting to
the mail server.
The default port number is determined by the protocol selected and whether
Secure Sockets Layer (SSL) is selected. If you do not enter a port number, the
following default values will be used:
„ SMTP: 25
„ SMTP with SSL: 465
8 In the Email Server User field, enter the user name of the administrator or
user for this email account.
Refer to your mail server administrator for your designated email username.
9 In the Email Server Password, enter the password associated with the user
name for this email account.
Refer to your mail server administrator for your designated email password.
10 Click Next.
One of two actions occurs:
„ If you selected MAPI as the protocol of your mailbox (either incoming or
outgoing), the Email Engine Mapi Logon Settings dialog box appears. Go
to step 11.
„ Otherwise, the installation program begins copying files to your system
and the Setup Complete screen appears. If you installed the email engine
and the AR System separately, you will get a reminder that you must
restart the AR System server. Go to step 15.

Windows: installing the email engine W 41

Action Request System 6.0

11 In the Windows NT User field, enter the name of the user who has domain
permissions to start the email engine as a service as well as access to the
Exchange profile mailbox.

Figure 2-7: MAPI logon settings

12 In the Password field, enter the user’s password to the domain.

13 In the Windows NT Domain field, enter the domain of the Windows user
account.
14 Click Next.
The installation program begins copying files to your system and the Setup
Complete screen appears. If you installed the email engine and the
AR System separately, you will get a reminder that you must restart the
AR System server.
15 Choose Yes to restart your computer (optional) and click Finish to complete
the installation. For more detailed information about email configuration,
refer to Chapter 3, “Email configuration.”

42 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Windows: upgrading from Remedy mail server to 6.0

email engine
This upgrade procedure directs you step-by-step through the procedures for
upgrading your Remedy Mail Server (pre-5.1) to the 6.0 email engine and
creating an incoming and an outgoing mailbox. Using this procedure, you
can continue to use the same Windows account, domain, mailbox, and
profile you used for the Remedy Mail Server. Use the information you
recorded in the “Email engine installation worksheet” on page 225 to provide
the necessary information to the email engine installer.

Note: If you are upgrading from the 5.1.x email engine, see “Upgrading to 6.0
email engine” on page 28 instead.

Note: If you are installing the email engine to a different system than where
you installed the Remedy Mail Server you are replacing, remember that
the system must still comply with the requirements described in “Pre-
Installation steps for using MAPI” on page 25.

If you wish to use the MAPI protocol for incoming and outgoing mailboxes,
you must install the email engine on a Windows system. An email engine
installed on a UNIX system will not have access to the proper libraries
necessary to access a mail server using the MAPI protocol (which would be a
MS Exchange server).

You can cancel installation any time. Information you entered, however, will
not be saved.

X To upgrade to the 6.0 Windows email engine:

1 Obtain your existing MS Exchange Account configuration information from
the pre-5.1 Mail Server:
„ ExchangeNTAccount
„ ExchangeNTDomain
„ Exchange-Mailbox
„ Exchange-Profile
This information can be found in the ar.cfg or armaild.cfg files.
2 Obtain other email configuration information from the pre-5.1.x Remedy
Mail Server (see Appendix D, “Upgrading email option parameters” for list
of available configuration parameters).

Windows: upgrading from Remedy mail server to 6.0 email engine W 43

Action Request System 6.0

3 Obtain email templates, including identifying:

„ All forms used in templates.
„ Default settings the templates rely on.
4 Verify that the Mailntfy folder is empty.
If it is not, let the old Remedy Mail Server finish processing the remaining
notifications in the Mailntfy directory, until it is empty.
5 Stop and disable the existing mail service (Remedy Mail Server).
6 Access the installation software.
„ From the CD:
Log in to Windows as an administrator and insert the CD into the drive.
If autorun is enabled, the CD browser opens. Click Install Products and
then click Remedy Email Engine.
If the CD browser does not start, run <cdrom_dir>\Launch.exe to open the
CD Browser manually. Click Install Products and then click Remedy
Email Engine.
The Welcome screen appears.
„ From the Electronic Software Distribution (ESD) process:
If you have acquired the email engine installer using the ESD process, be
sure to copy the installer files to the machine where you will install it. For
example, if you used the Solaris Sm@rtCert client to download the email
engine for Windows, copy the directory and its contents to your Windows
machine.
From the directory to which you copied the downloaded files, run the
installer executable, emaild.exe.
When you run this file, the installation files are unpacked into a temporary
directory and the Setup program starts. The Welcome screen appears.
„ During the installation of the AR System server:
At the conclusion of the AR System server installation, you will be
presented with the option to install the AR System email engine. If you
chose to install the email engine in the Setup Complete screen of your
AR System installation, the Remedy email engine installer will be
launched. After the installation files are unpacked, the Welcome screen
appears.
7 Click Next to display the Software License Agreement screen.

44 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

8 Click the I Agree button to accept the software license agreement and to
display the Choose Destination Location screen.
9 Click Next to accept the default installation directory or click Browse to
choose another directory and then click Next. Preferably, install the email
files into the directory that contains the AR System.
10 The AR Server to Support EMail Server screen appears. Enter the following
information:
„ In the AR Server Name field, enter the AR System server name, which is
the name of the server that the email engine uses.
„ In the Port Number field, enter the TCP port number the AR System uses
if your AR System Server is not using Portmapper.
The AR System server installation program registers the server with a
portmapper by default. So in most cases, you can simply leave the Port
Number field empty.
If your AR System server does not register with portmapper, you must
provide the TCP port that the AR System server uses. You must also use a
TCP port if the email engine is on the other side of a firewall from the
AR System server.
For more information, refer to Registering with a Portmapper in the
Installing AR System guide.
„ In the RPC Port Number field, enter the RPC port number the AR System
server uses if you have configured a private server to use with the email
engine.
Otherwise, in most cases, you can simply leave the RPC Port Number field
empty.
For more information on private servers in the AR System, refer to the
Configuring AR System guide.
Note: If you have multiple AR System servers running on the same machine,
make sure you enter the correct server name and port number (if used).
For example, if you had two servers, polycarp1 (using portmapper) and
polycarp2 using port 9000, and you want to install the email engine with
polycarp2, you must use the real alias name of the server (polycarp2) with
the correct port number (9000) for the installation to work properly.
Otherwise, the email engine service dependency to the AR System server
will be incorrect.

Windows: upgrading from Remedy mail server to 6.0 email engine W 45

Action Request System 6.0

11 Click Next to display the Administrator Logon Information Required screen

and enter an AR System Administrator user name and password.
The user name must have Administrator privileges on the AR System server.
This user will be used to import the necessary AR System email engine forms
and workflow.
12 Click Next to display the Application Service Password screen and enter the
password, if any.
Note: Either leave the application service password blank during installation,
or set it to the same value that is set in AR System Administrator. To find
out what the value is in AR System Administrator, go to File > Server
Information, click the Connection Settings tab, and verify the Application
Service Password information. The application service password could be
set by Remedy applications like Approval Server or Flashboards.

13 Click Next to display the Start Copying Files screen.

The installer displays installation-related messages.
14 Click Next to begin copying files.
The AR System Email Mailbox Configuration screen appears.
15 Select Incoming and Outgoing from the Mailbox Function menu to
configure both an incoming and an outgoing mailbox, then click Yes to
configure the email engine now.

46 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

The AR System Email Mailbox Configuration - Incoming Mailbox dialog

box appears. Use the information gathered in step 1 and step 2 to enter the
incoming mailbox configuration information.

Figure 2-8: Incoming mailbox screen

a For Mailbox Name, enter a descriptive name for your incoming mailbox.
b For Email Server Type, specify MAPI.
c For Email Profile, enter the value of the Exchange-Profile configuration
parameter you obtained in step 1. This profile should point to your MS
Exchange server mailbox dedicated for use by the email engine.

Windows: upgrading from Remedy mail server to 6.0 email engine W 47

Action Request System 6.0

16 Click Next to display the AR System Email Mailbox Configuration -

Outgoing Mailbox dialog box. Use the information gathered in step 1 and
step 2 to enter the outgoing mailbox configuration information.

Figure 2-9: Outgoing mailbox screen

a For Mailbox Name, enter a descriptive name for your outgoing mailbox.
b For Display Name, enter the value of the Exchange-Mailbox configuration
parameter you obtained in step 1. The display name will be the name (not
the email address) in the From: line of the outgoing email.
c For Email Address, the email address you enter and confirm will be the
default From: email address in outgoing emails.
d For Email Server Type, specify MAPI.
e For Email Profile, enter the value of the Exchange-Profile configuration
parameter you obtained in step 1.

48 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

17 Click Next to display the Email Engine Mapi Logon Settings dialog box.

Figure 2-10: MAPI logon settings

a In the Windows NT User field, enter the value of the ExchangeNTAccount

configuration parameter you obtained in step 1.
b In the Password field, enter the user’s password to the domain.
c In the Windows NT Domain field, enter the value of the
ExchangeNTDomain configuration parameter you obtained in step 1.
18 Click Next to complete copying files and display the Setup Complete screen.
If you installed the email engine and the AR System separately, you will get a
reminder that you must restart the AR System server. This is optional.
19 Click Finish to complete the installation upgrading your email service to the
new 6.0 email engine.
20 See Appendix D, “Upgrading email option parameters” for information on
converting your old configuration parameters to their functional equivalent
in the 6.0 email engine.
For additional upgrade instructions, see “Preparing email templates after an
upgrade” on page 145.

Windows: upgrading from Remedy mail server to 6.0 email engine W 49

Action Request System 6.0

UNIX: installing the email engine

During the UNIX AR System email engine installation, you are asked to
provide certain pieces of information. The following steps describe the
information needed and explain why. You will also use these instructions if
you are upgrading to 6.0 from the 5.1.x email engine. (But first read
“Upgrading to 6.0 email engine” on page 28.)

To install the email engine, use the information you recorded in the “Email
engine installation worksheet” on page 225.

To use the MBOX protocol for incoming mail, you should install the email
engine on a UNIX system that has access to the UNIX mail directory
receiving the MBOX formatted email.

Note: If you are upgrading from Remedy Mail Server (pre-5.1), use the
installation instructions in “UNIX: upgrading the Remedy mail server to
6.0 email engine” on page 62 instead.

The script writes a log file to: /usr/tmp/ed_install.log.

X To install the UNIX email engine:

1 At the prompt, log in as the root user.
To install the software without root privileges, refer to “Installing on UNIX
as non-root” on page 56.
2 Set any relevant environment variables to control the installation. Refer to
Appendix B, Customizing UNIX Options, in the Installing AR System guide,
for details about the options that you can set.
3 If you are upgrading to 6.0, use the emaild.sh stop command to stop the
email engine.
If the emaild.sh stop command fails to stop the email engine, comment out
the startup of the email engine in the /etc/arsystem/hostname/
armonitor.conf file, then stop and restart the AR System server. (For more
information, see “Starting and stopping the email engine” on page 70.)
Otherwise, any open .jar files or libraries will not be overwritten during the
upgrade.

50 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

4 Access the installation software.

„ From the CD:
If you are installing from the Action Request System 6.0 installation CD:
„ Mount the CD locally or remotely.
„ Change to the directory containing the email engine installation script
as follows:
# cd <CD-ROM_mount_point>/arsystem
The default mount point is /cdrom.

Refer to Appendix C, Mounting a CD-ROM on a UNIX System, in the

Installing AR System guide for details on how to mount the CD.
„ From the Electronic Software Distribution (ESD) process:
If you are installing software obtained through ESD, refer to the procedure
in the Installing AR System guide before proceeding. The installer package
is shipped as a compressed tar file (*.tar.gz). This file will have to be
copied to the system to which the user will be installing the email engine.
It will then need to be uncompressed and extracted. Once extracted,
change directories to the arsystem directory.
5 At the prompt, locate and run the ed_install script:
#./ed_install
A welcome message appears.
6 At the prompt:
Do you wish to install Remedy Email Engine 6.0:
Enter Y to install the Remedy Email Engine 6.0. The script gives you logging
information and system information, such as the amount of free disk space
required.
7 At the prompt:
Enter the product directory name: [/cdrom]
If you are installing from the CD-ROM, the default path should represent the
CD-ROM mount directory. Accept the default or enter the path to your CD-
ROM mount directory if different. Otherwise, enter the absolute path to the
directory that contains the ed_install script (this should be the arsystem
directory).
8 At the prompt, review the license agreement. Press the return key to scroll
through the license agreement.
At any time while reading the license agreement, you can select Q to accept,
reject, or re-read the agreement.

UNIX: installing the email engine W 51

Action Request System 6.0

9 At the license agreement prompt, select 1 to accept the terms of the license
agreement.
Rejecting the license agreement cancels the installation. The Java
requirement prompt appears.
10 At the prompt:
Do you have Java 1.4.1_00 or greater installed?
„ Enter Y and confirm that you have Java 1.4.1_00 (or later) installed on
your system. Go to step 11.
„ Enter N if you do not have Java 1.4.1_00 (or later) installed. If you chose N,
the installation program exits and you are reminded to install Java
1.4.1_00 (or later) before you try installing again. Install the correct JRE
and go back to step 5.
Installing Java version 1.4.1_00 (or later) is mandatory for installation to
finish successfully. Refer to your OS vendor for the latest version of Java. Be
aware that OS patches may be required to support these later versions of Java.
Refer to your OS vendor for download and install directions.
Note: The Java prompts differ slightly, based upon what version of UNIX you
are using. For Linux and AIX platforms, additional .jar files are required
so that the email engine will run correctly. (For more information, see
“Additional files required for Linux and AIX installations” on page 55.)

11 At the prompt:
Please enter the Java installation directory:
Enter the Java 1.4.1_00 (or later) installation directory and confirm the
location.
Note: The installation directory should be the root directory of your Java
installation. This root directory should contain the /bin and /jre
directories of the Java install. The installer path is often simply a link to the
actual Java install directory. A typical Java path is /usr/java1.4.1/j2se.

12 At the prompt:
Please enter an AR Server Name:
Enter and confirm the name of the AR System server that the email engine
will use.

52 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Note: If you have multiple AR System servers running on the same machine,
make sure you enter the correct server name and port number (if used).
For example, if you had two servers, polycarp1 (using portmapper) and
polycarp2 using port 9000, and you want to install the email engine with
polycarp2, you must use the real alias name of the server (polycarp2) with
the correct port number (9000) for the installation to work properly.
Otherwise, the email engine service dependency to the AR System server
will be incorrect.

13 At the prompt:
Please enter an AR Server TCP Port:
Accept this default setting of 0, then enter Y to confirm the setting if the
AR System is running with Portmapper. The AR System server installation
program registers the server with a portmapper by default.
If your AR System server does not register with portmapper, you must give
the TCP port that the server runs on here. You must specify a TCP port if the
email engine is on the other side of a firewall from the AR System server.
For more information, refer to the Registering with a Portmapper section in
the Installing AR System guide.
14 At the prompt:
Please enter an AR Server RPC Port:
If you installed the AR System server using Portmapper, accept this default
setting of 0, then click Y to confirm the setting.
If you have configured a private server that you would like the email engine
to connect to, enter the RPC port number of that server and confirm the
number.
For more information about private servers with the AR System, refer to the
Configuring AR System guide.
15 At the prompt:
Please enter your AR System Admin User Name:
Enter and confirm the AR System Administrator user name and password, in
order to import forms and workflow.
After you have entered your user name and password information the
installer will attempt to log on to your AR System server. If the installer is
unsuccessful at contacting your AR System server, you will be prompted to
ensure that it is running. If you receive this message, ensure that your
AR System server is running before proceeding.

UNIX: installing the email engine W 53

Action Request System 6.0

16 At the prompt:
Please enter the Application Service password:
Enter the Application Service Password, if applicable, and confirm the
password.
Note: Either leave the application service password blank during installation
and configuration, or set it to the same value that is set in AR System
Administrator. To find out what the value is in the Admin Tool, go to File
> Server Information, click the Connection Settings tab, and verify the
Application Service Password information. The application service
password can manually set through the AR System Administrator tool or
set by Remedy applications like Approval Server or Flashboards.

17 At the prompt:
Do you want to perform the configuration now?
Here you have two options:
„ Enter Y (default) if you want to configure the email engine now. Go to
step 18.
The installer will use these configuration settings to create an entry in the
AR System Email Mailbox Configuration form for each mailbox you
configure during installation. As such, you can access the mailboxes you
create here at a later time by using Remedy User and modifying the
corresponding entries in the Remedy Email Mailbox Configuration form.
See Chapter 3, “Email configuration” for more information about the
Remedy Email Mailbox Configuration form.
„ Enter N and go to step 21 to finish the email engine installation. You will
need to create mailboxes for use by the email engine after the installation
is finished. For more detailed information about creating mailboxes, refer
to Chapter 3, “Email configuration.”

18 At the prompt:
Please select the Mailbox function from the following options.
Choose from the following mailbox functions:
„ If you chose both incoming and outgoing mailboxes (b), you can expect to
be prompted first to configure the incoming mailbox, then the outgoing
mailbox.
„ If you chose incoming only (i), you will be prompted to configure the
incoming mailbox.
„ If you chose outgoing only (o), you will be prompted to configure the
outgoing mailbox.

54 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

„ If you chose none (n), the install program will not configure any
mailboxes. Go to step 21 to finish the installation. You will need to
configure the mailboxes after installation to enable processing of
incoming and/or outgoing mail by the email engine. For more detailed
information about creating mailboxes, see Chapter 3, “Email
configuration.”
19 At the prompt:
Are you using SSL?
Enter Y only if you are using the secure socket layer. The default choice is N,
you are not using SSL. Verify with your network or email administrator if SSL
is required for use with the Remedy email engine in your environment.
20 Choose one of the following configuration paths:
„ If, during step 18, you chose either to configure an incoming mailbox (i)
or both an Incoming and Outgoing mailbox (b), you will be prompted for
Incoming Mailbox information at this time. Depending upon which
protocol your mail server uses for receiving mail, proceed to one of the
following sections to begin configuration of your incoming mailbox:
„ “Configuring your incoming mailbox using IMAP4” on page 57
„ “Configuring your incoming mailbox using POP3” on page 58
„ “Configuring your incoming mailbox using MBOX” on page 59
„ If, during step 18, you chose to configure only an outgoing mailbox (o),
proceed to “Configuring your outgoing mailbox using SMTP” on page 60
21 At the prompt:
Directory to install AR System Email Engine 6.0?
Enter the installation directory path or press Enter to accept the default, and
confirm.
The script displays a list of extracted files and error messages (if any). The
installation is complete.

Additional files required for Linux and AIX installations

For Linux and AIX platforms, the email engine requires additional .jar files
for successful installation and operation.

X To install additional jar files:

1 Obtain and install the latest version of the Java 1.4.1_01 (or later) platform.
2 Download the latest JSSE from http://java.sun.com/products/jsse.
3 Extract the zip file.

UNIX: installing the email engine W 55

Action Request System 6.0

4 Copy the jsse.jar file into the <jre>/lib/ext/ location.

5 Download and extract JDK1.4.1 (or later) for the Solaris platform.
6 Copy the sunjce_provider.jar file into the <jre>/lib/ext location.
7 Make sure that the jsse.jar file is located in your system CLASSPATH, or put it
in the /lib/ext folder of your Java installation.

Installing on UNIX as non-root

For general information about performing installation of the email engine as
a non-root user, see the detailed instructions in the Installing AR System
guide.

In addition, you should be aware of the following issues with non-root

installations of the email engine:

„ If you previously installed the 5.1 or 5.1.1 email engine as root, do not
attempt to upgrade to the 6.0 email engine as a non-root user.
„ There might be files you cannot write to as a non-root user (for example,
armonitor.conf). The installer and the install log will inform you which
files you cannot write to. You will have to manually make changes to these
files. For example, if the installer was unable to write to the armonitor.conf
file, you might see the following message on the console while the installer
is running:
Can't write to /etc/arsystem/<machine_name>/armonitor.conf file
You will have to append the contents of
<email_engine_install_dir>/armonitor.conf_tmp to the /etc/
arsystem/<machine_name>/armonitor.conf file.

As such, you would have to open the armonitor.conf_tmp file and cut and
paste the contents of this file to the end of the armonitor.conf file.
„ Before installation, verify that no /tmp/migfiles directory exists as a result
of a previous AR System installation. If this directory does exist, delete it.
„ Make sure you adjust the permission to access the mbox mail files and
directory. If you are using mbox, you must allow the non-root user to
access all files in that directory and also to be able to create files in this
directory.
„ If the JRE (Java Runtime Environment) is not installed as a sub-directory
of the email engine, make sure that the JRE directory has the correct
permissions to permit the non-root user to launch the email engine.

56 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Configuring your incoming mailbox using IMAP4

Use the “Email engine installation worksheet” on page 225 to enter the
incoming mailbox configuration information for the IMAP4 protocol. If you
chose to perform the configuration at this time (by entering Y), you will now
see the following prompts:
X To configure your incoming mailbox (IMAP4):
1 At the prompt:
Please enter the Mailbox Name: [AREmail]
Enter and confirm the default of AREmail, or change it to a more accurate
description of the mailbox, for example, AREmail - Incoming.
2 At the prompt:
Please enter the Incoming Mailbox Server Name:
Enter and confirm the name or IP address of the mail server that this
incoming mailbox will use.
3 At the prompt:
Please select the Incoming Mailbox Server Type from the following
options.
Enter i for IMAP4.
4 At the prompt:
Please enter the port number for the Incoming Mailbox Server :
[143]
Enter and confirm the default setting (143, or 993 if you are have chosen
SSL), or enter the port number used by your mail server if different from the
default. This default port number is determined by the protocol selected and
whether Secure Sockets Layer (SSL) is selected.
5 At the prompt:
Please enter the Incoming Mailbox Server User Name:
Enter and confirm the user name of the email account this mailbox will be
using.
6 At the prompt:
Please enter your Incoming Mailbox Server User password:
Enter and confirm the password for the user.

UNIX: installing the email engine W 57

Action Request System 6.0

7 If you chose to configure the outgoing mailbox, go to “Configuring your

outgoing mailbox using SMTP” on page 60.
If you chose only to configure the incoming mailbox, go to step 8 to finish
the email engine installation. For additional information about email
configuration, refer to Chapter 3, “Email configuration.”
8 At the prompt:
Directory to install AR System Email Engine 6.0?
Enter the installation directory path, or accept the default path and confirm.
The script displays a list of extracted files and error messages (if any). The
installation is complete.

Configuring your incoming mailbox using POP3

Use the “Email engine installation worksheet” on page 225 to enter the
incoming mailbox configuration information for the POP3 protocol. If you
chose to perform configuration at this time (by entering Y), you will now see
the following prompts:
X To configure your incoming mailbox (POP3):
1 At the prompt:
Please enter the Mailbox Name: [AREmail]
Enter and confirm the default of AREmail, or change it to a more accurate
description of the mailbox, for example, AREmail - Incoming.
2 At the prompt:
Please enter the Incoming Mailbox Server Name:
Enter and confirm the name or IP address of the mail server that this
incoming mailbox will use.
3 At the prompt:
Please select the Incoming Mailbox Server Type from the following
options.
Enter p for POP3.
4 At the prompt:
Please enter the port number for the Incoming Mailbox Server :
[110]
Enter and confirm the default setting (110, or 995 if you have chosen SSL),
or enter the port number used by your mail server if different from the
default.

58 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

5 At the prompt:
Please enter the Incoming Mailbox Server User Name:
Enter and confirm the user name of the email account this mailbox will be
using.
6 At the prompt:
Please enter your Incoming Mailbox Server User password:
Enter and confirm the password for the user.
7 If you chose to configure both an Incoming and an Outgoing Mailbox, go to
“Configuring your outgoing mailbox using SMTP” on page 60.
If you chose only to configure the incoming mailbox, go to step 8 to finish
the email engine installation. For additional information about email
configuration, refer to Chapter 3, “Email configuration.”
8 At the prompt:
Directory to install AR System Email Engine 6.0?
Enter the installation directory path or press Enter to accept the default, and
confirm.
The script displays a list of extracted files and error messages (if any). The
installation is complete.

Configuring your incoming mailbox using MBOX

Use the “Email engine installation worksheet” on page 225 to enter the
incoming mailbox configuration information for the MBOX protocol. If you
chose to perform the configuration at this time (by entering Y), you will now
see the following prompts:
X To configure your incoming mailbox (MBOX):
1 At the prompt:
Please enter the Mailbox Name: [AREmail]
Enter and confirm the default of AREmail, or change it to a more accurate
description of the mailbox, for example, AREmail - Incoming.
2 At the prompt:
Please enter the Incoming Mailbox Server Name:
Enter and confirm the host name where your incoming mailbox is
configured.
3 At the prompt:
Please select the Incoming Mailbox Server Type from the following
options.
Enter m for MBOX.

UNIX: installing the email engine W 59

Action Request System 6.0

4 At the prompt:
Please enter the Incoming Inbox Path:
Enter and confirm the full path file name to the mbox file corresponding to
the user email account that will be used, for example, /usr/spool/mail/
ARSystem, where ARSystem is the mbox file name. You can check your /etc/
aliases file, or run the following command:
/usr/lib/sendmail -bv -v [mailbox_user]

5 At the prompt:
Please enter the Incoming User Home Path:
Enter the full path of the user home directory, for example, /usr/ARSystem.
Note: The user under which the email engine service is running must have
full read and write permissions to the directories and files supplied.

6 If you chose to configure the outgoing mailbox, go to “Configuring your

outgoing mailbox using SMTP” on page 60.
If you chose only to configure the incoming mailbox, go to step 7 to finish
the email engine installation. For more detailed information about email
configuration, refer to Chapter 3, “Email configuration.”
7 At the prompt:
Directory to install AR System Email Engine 6.0?
Enter the installation directory path or accept the default, and confirm. The
script displays a list of extracted files and error messages (if any). The
installation is complete.

Configuring your outgoing mailbox using SMTP

Use the “Email engine installation worksheet” on page 225 to enter the
outgoing mailbox configuration information for the SMTP protocol. SMTP
is currently the only protocol available for your outgoing mailbox.
X To configure your outgoing mailbox (SMTP):
1 At the prompt:
Please enter the Mailbox Name: [AREmail]
Enter and confirm the default of AREmail, or change it to a more accurate
description of the mailbox, for example, AREmail - Outgoing.
2 At the prompt:
Please enter a Display Name for the mailbox: [AREmail]
This setting will be the name (not the email address) in the From: line of the
outgoing email. Enter and confirm the default of AREmail, or change it.

60 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

3 At the prompt:
Please enter the Email address:
The email address you enter and confirm will be the default From: email
address in outgoing emails. As a result, if you entered a Display Name of
ARSystem and an email address of [email protected], the From: line would
look like:
From: ARSystem [[email protected]]
4 At the prompt:
Please enter the name or IP Address of your Mail Server:
Enter and confirm the name or IP address of the mail server that this
outgoing mailbox will use.
5 At the prompt:
Please enter the port number for the Outgoing Mailbox Server: [25]
Enter and confirm the default setting (25, or 465 if you are have chosen SSL),
or enter the port number used by your mail server if different from the
default. This default port number is determined by the protocol selected and
whether Secure Sockets Layer (SSL) is selected.
6 At the prompt:
Please enter the Outgoing Mailbox Server User Name:
Enter and confirm the user name of the email account this mailbox will be
using.
7 At the prompt:
Please enter your Outgoing Mailbox Server User password:
Enter and confirm the password for the user.
8 At the prompt:
Directory to install AR System Email Engine 6.0?
Enter the installation directory path or accept the default, and confirm.
The script displays a list of extracted files and error messages (if any). The
installation is complete.

UNIX: installing the email engine W 61

Action Request System 6.0

UNIX: upgrading the Remedy mail server to 6.0

email engine
This upgrade procedure directs you step-by-step through the procedures for
upgrading your Remedy Mail Server (pre-5.1) to the 6.0 email engine and
creating an incoming and an outgoing mailbox.
Note: If you are upgrading from the 5.1.x email engine, see “Upgrading to 6.0
email engine” on page 28 instead.
If you had outgoing email working on a previous version of the AR System,
these step-by-step explanations should allow you to easily keep this working
with the new Remedy email engine. To install the email engine, use the
information you recorded in the “Email engine installation worksheet” on
page 225.
To use the MBOX protocol for incoming mail (not valid for outgoing), you
should install the email engine on a UNIX system that has access to the mail
directory that the UNIX mail server uses to deposit MBOX formatted email.
The script writes a log file to: /usr/tmp/ed_install.log.
X To upgrade to the 6.0 UNIX email engine:
1 At the prompt, log in as the root user.
To install the software without root privileges, refer to “Installing on UNIX
as non-root” on page 56.
2 Set any relevant environment variables to control the installation. Refer to
Appendix B, Customizing UNIX Options, in the Installing AR System guide,
for details about the options that can be set.
3 Access the installation software.
„ From the CD:
If you are installing from the Action Request System 5.1 installation CD:
„ Mount the CD locally or remotely.
„ Change to the directory containing the email engine installation script
as follows:
# cd <CD-ROM_mount_point>/arsystem
The default mount point is /cdrom.

Refer to Appendix C, Mounting a CD-ROM on a UNIX System, in the

Installing AR System guide for details on how to mount the CD.

62 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

„ From the Electronic Software Distribution (ESD) process:

If you are installing software obtained through ESD, refer to the procedure
in the Installing AR System guide before proceeding. The installer package
is shipped as a compressed tar file (*.tar.gz). This file will have to be
copied to the system to which the user will be installing the email engine.
It will then need to be uncompressed and extracted. Once extracted,
change directories to the arsystem directory.
4 At the prompt, locate and run the ed_install script:
#./ed_install

A welcome message appears.

5 At the prompt:
Do you wish to install Remedy Email Engine 6.0:
Enter Y to install the Remedy Email Engine 6.0. The script gives you logging
information and system information, such as the amount of free disk space
required.
6 At the prompt:
Enter the product directory name: [/cdrom]
If you are installing from the CD-ROM, the default path should represent the
CD-ROM mount directory. Accept the default or enter the path to your CD-
ROM mount directory if different. Otherwise, enter the absolute path to the
directory that contains the ed_install script (this should be the arsystem
directory).
7 At the prompt, review the license agreement. Press the return key to scroll
through the license agreement.
At any time while reading the license agreement, you can select Q to accept,
reject, or re-read the agreement.
8 At the license agreement prompt, select 1 to accept the terms of the license
agreement.
Rejecting the license agreement cancels the installation. The Java
requirement prompt appears.

UNIX: upgrading the Remedy mail server to 6.0 email engine W 63

Action Request System 6.0

9 At the prompt:
Do you have Java 1.4.1_00 or greater installed?
„ Enter Y and confirm that you have Java 1.4.1_00 installed on your system.
Go to step 10.
„ Enter N if you do not have Java 1.4.1_00 (or later) installed. If you chose N,
the installation program exits and you are reminded to install Java
1.4.1_00 (or later) before you try installing again. Install the correct JRE
and go back to step 4.
Installing Java version 1.4.1_00 (or later) is recommended. Refer to your OS
vendor for the latest version of Java. Be aware that OS patches may be
required to support these later versions of Java. Refer to your OS vendor for
download and install directions.
Note: The Java prompts differ slightly, based upon what version of UNIX you
are using. For Linux and AIX platforms, additional .jar files are required
so that the email engine will run correctly. (For more information, see
“Additional files required for Linux and AIX installations” on page 55.)

10 At the prompt:
Please enter the Java installation directory:
Enter the Java 1.4.1_01 (or later) installation directory and confirm the
location.
Note: The installation directory should be the root directory of your Java
installation. This root directory should contain /bin and /jre directories.
The installer path is often simply a link to the actual Java install directory.
A more typical Java path is /usr/java1.4.1/j2se.

11 At the prompt:
Please enter an AR Server Name:
Enter and confirm the name of the AR System server that the email engine
uses.
Note: If you have multiple AR System servers running on the same machine,
make sure you enter the correct server name and port number (if used).
For example, if you had two servers, polycarp1 (using portmapper) and
polycarp2 using port 9000, and you want to install the email engine with
polycarp2, you must use the real alias name of the server (polycarp2) with
the correct port number (9000) for the installation to work properly.
Otherwise, the email engine service dependency to the AR System server
will be incorrect.

64 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

12 At the prompt:
Please enter an AR Server TCP Port:
If you installed the AR System server using Portmapper, accept this default
setting of 0, then enter Y to confirm the setting. The AR System server
installation program registers the server with a portmapper by default.
If your AR System server does not register with portmapper, you must give
the TCP port that the server runs on here. You must also use a TCP port if
the email engine is on the other side of a firewall from the AR System server.
For more information, refer to the Registering with a Portmapper section in
the Installing AR System guide.
13 At the prompt:
Please enter an AR Server RPC Port:
If you installed the AR System server using Portmapper, accept the default
setting of 0, then enter Y to confirm the setting.
If you have configured a private server that you would like the email engine
to connect to, enter the RPC port number of that server and confirm the
number.
For more information about private servers with the AR System, refer to the
Configuring AR System guide.
14 At the prompt:
Please enter your AR System Admin User Name:
Enter and confirm the AR System Administrator user name and password, in
order to import forms and workflow.
After you have entered your user name and password information, the
installer will attempt to log on to your AR System server. If the installer is
unsuccessful at contacting your AR System server, you will be prompted to
ensure that it is running. If you receive this message, ensure that your
AR System server is running before proceeding.
15 At the prompt:
Please enter the Application Service password:
Enter the Application Service Password, if applicable, and confirm the
password.

UNIX: upgrading the Remedy mail server to 6.0 email engine W 65

Action Request System 6.0

Note: Either leave the application service password blank during installation
and configuration, or set it to the same value that it is set in AR System
Administrator. To find out what the value is in the Admin Tool, go to File
> Server Information, click the Connection Settings tab, and verify the
Application Service Password information. The application service
password can be set through the AR System Administrator tool or by
Remedy applications like Approval Server or Flashboards.

16 At the prompt:
Do you want to perform the configuration now?
Enter Y (default) to configure the email engine now. Here you will configure
both incoming and outgoing mailboxes (in the order of the installation
default).
17 At the prompt:
Please select the Mailbox function from the following options.
Choose both incoming and outgoing mailboxes (b). You can expect to be
prompted first to configure the incoming mailbox, then the outgoing
mailbox. As a result, the installer will use your configuration settings to create
two records in the AR System Email Mailbox Configuration form for each
mailbox you configure during installation, one record for an incoming
MBOX mailbox, one for an outgoing SMTP mailbox. The configuration for
the incoming and outgoing mailboxes can be accessed at a later time using
the AR System Windows User tool and modifying the corresponding entries
in the AR System Email Mailbox Configuration form. See Chapter 3, “Email
configuration” for more information about the Remedy Email Mailbox
Configuration form.
18 At the prompt:
Are you using SSL?
Enter Y only if you are using the secure socket layer. The default choice is N,
you are not using SSL. Verify with your network or email administrator if SSL
is required for use with the Remedy email engine in your environment.
19 At the prompt:
Please enter the Mailbox Name: [AREmail]
Here you are prompted for the name of the incoming mailbox. Enter and
confirm the default of AREmail, or change it to a more accurate description of
the mailbox, for example, AREmail - Incoming.
20 At the prompt:
Please enter the Incoming Mailbox Server Name:
Enter and confirm the host name where your incoming mailbox is
configured.

66 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

21 At the prompt:
Please select the Incoming Mailbox Server Type from the following
options.
Enter m for MBOX.
22 At the prompt:
Please enter the Incoming Inbox Path:
Enter and confirm the full path file name to the mbox file corresponding to
the user email account that will be used, for example, /usr/spool/mail/
ARSystem, where ARSystem is the mbox file name. You can check your /etc/
aliases file, or run the following command:
/usr/lib/sendmail -bv -v [mailbox_user]
23 At the prompt:
Please enter the Incoming User Home Path:
Enter the full path of the user home directory, for example, /usr/ARSystem.
Note: The user under which the email engine service is running must have
full read and write permissions to the directories and files supplied.

24 At the prompt:
Please enter the Mailbox Name: [AREmail]
Here you are prompted for the name of the outgoing mailbox. Enter and
confirm the default of AREmail, or change it to a more accurate description of
the mailbox, for example, AREmail - Outgoing.
25 At the prompt:
Please enter a Display Name for the mailbox: [AREmail]
This setting will be the name (not the email address) in the From: line of the
outgoing email. Enter and confirm the default of AREmail, or change it.
26 At the prompt:
Please enter the Email address:
The email address you enter and confirm will be the default From: email
address in outgoing emails. As a result, if you entered a Display Name of
ARSystem and an email address of [email protected], the From: line would
look like:
From: ARSystem [[email protected]]
27 At the prompt:
Please enter the Outgoing Mailbox Server Name:
Enter and confirm the name or IP address of the mail server that this
outgoing mailbox will use.

UNIX: upgrading the Remedy mail server to 6.0 email engine W 67

Action Request System 6.0

28 At the prompt:
Please enter the port number for the Outgoing Mailbox Server: [25]
Enter and confirm the default setting (25, or 465 if you are have chosen SSL),
or enter the port number used by your mail server if different from the
default. This default port number is determined by the protocol selected and
whether Secure Sockets Layer (SSL) is selected.
29 At the prompt:
Please enter the Outgoing Mailbox Server User Name:
Enter and confirm the user name of the email account this mailbox will be
using.
30 At the prompt:
Please enter your Outgoing Mailbox Server User password:
Enter and confirm the password for the user.
31 At the prompt:
Directory to install AR System Email Engine 6.0?
Enter the installation directory path to your existing 6.0 installation or press
Enter to accept the default, and confirm.

The script displays a list of extracted files and error messages (if any).
32 At the restart prompt when the email engine installation is finished, restart
the AR System server when you are prompted to do so.
The installation is complete.
33 See Appendix D, “Upgrading email option parameters” for information
about converting your old configuration parameters to their functional
equivalent in the 6.0 email engine. For additional upgrade instructions, see
“Preparing email templates after an upgrade” on page 145.

68 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Installed files
For both Windows and UNIX systems, the email engine is an application
written using Java 1.4.x. The following .jar (Java ARchive) files are installed
with the email engine:

„ Activation.jar
„ arapi60.jar
„ armapi60.jar
„ arutil60.jar
„ emaildaemon.jar
„ imap.jar
„ mail.jar
„ mbox.jar
„ pop3.jar
„ smtp.jar

For a list of forms installed with the server, see Appendix E, “Email engine
forms.” These email engine forms are managed by the AR System server.

Files installed for email engine running on Windows systems

The following files are installed for Windows systems:

Default install directory C:\Program Files\AR System\AREmail

Email Engine DLL Files „ arapi60.dll

„ arjni60.dll
„ armapi60.dll
„ arrpc60.dll
„ arutiljni60.dll
„ arutl60.dll
„ arxmlutil60.dll

EmailStart.bat The startup script is located by default in

C:\Program Files\AR System\AREmail.
EmailDaemon.properties Created at installation time by EMPass.class
and located by default in
C:\Program Files\AR System\AREmail
If this file is not created during installation, the
email engine will not run.
Emaild.exe Starts the email daemon as a service. Used for
remote installations of the email daemon.
Installed by default in
C:\Program Files\AR System\AREmail.

Installed files W 69
Action Request System 6.0

Files installed for email engine running on UNIX systems

The following files are installed for UNIX systems:

Default install directory /usr/ar/AREmail/

emaild.sh Startup script is located by default in /usr/ar/

AREmail/
emailstart.sh Wrapper script to start email engine by calling
the emaild.sh script, so that you do not have to
enter the nohup command. The wrapper script is
located by default in /usr/ar/AREmail/
EmailDaemon.properties Created at installation time by EMPass.class
and located by default in /usr/ar/AREmail/
If this file is not created during installation, the
email engine will not run.

Starting and stopping the email engine

The email engine is configured to start automatically; however, you can
choose to start the process manually.
The following sections explain how to start the mail process for UNIX and
Windows servers.

UNIX server
The AR Monitor will start the email engine automatically when you start the
server. Otherwise, you must start and stop the email engine manually. To do
this, use the command prompt to change directories to the email engine
installation directory and enter either of the following commands:
# emailstart.sh start &

Or:
# nohup emaild.sh start &

To stop the email engine from the command line, enter the following:

# emaild.sh stop &

The email engine can be stopped and started from the command line
independently of the AR System server. If the email engine has been started
by the AR Monitor, issuing the emaild.sh stop command will result in an
automatic restart of the email engine by the AR Monitor.

70 XChapter 2—Remedy email engine installation and setup

 Remedy Email Engine Guide

Windows server
For Windows, the email engine is installed as a service, Remedy Email Engine.
The email engine service will be launched automatically when the system
starts.

Note: By default, the email engine service is launched as the local system
account. However, if you elected to configure a MAPI mailbox during
installation, you were prompted for the Windows account, password, and
domain for a user that has been created for use with your MAPI email
account. The installation creates the email engine service to run with this
account information. If you will be using MAPI but did not configure a
MAPI mailbox during installation, you must change the login information
(in the Services control panel) for the email engine service from the local
system account to the appropriate account.

When you manually stop the AR System through the Services control panel,
the Remedy email engine will also be stopped automatically. But when you
re-start the AR System server again, you must manually start the Remedy
email engine; the email engine will not be started automatically for you.

Using the Services control panel, you can start and stop the email engine
service. Alternatively, you may start and stop the email engine manually as
follows:

„ Open a command prompt in the email engine installation folder and run
the emailstart batch file, located in the email engine installation folder.
To terminate the process, press Ctrl - C in the command prompt.
„ Use the following command:
<email_engine_installation_directory>\java -cp
emaildaemon.jar;arapi60.jar;arutil60.jar;activation;jar;mail.jar;
imap.jar;smtp.jar;pop3.jar;
com.remedy.arsys.emaildaemon.EmailDaemon

Note: To use the java command, your PATH and CLASSPATH environment
variables must be properly configured to use Java 1.4.1_01 (or later). See
your system administrate for details regarding how to set your
environment properly to use the java command. Do not include any
parameters in the previous command, otherwise the system will simply
update the emaildaemon.properties file but will not start the email engine.
For information about updating the emaildaemon.properties file, see
“Updating the emaildaemon.properties file” on page 189.

Starting and stopping the email engine W 71

Action Request System 6.0

Defining a heap size for the Remedy email engine

You can modify the registry as needed for the email engine service for
minimum and maximum heap size. For Java 1.4.x, the options to use are
-ms<size> or -Xms<size> for the minimum, and -mx<size> or -Xmx<size> for
the maximum. For example, you could enter the following from the
command line:

java -mx50m -mx256m myClass

To add a maximum heap size, you must add the following to the registry:

Key:
HKLM\SYSTEM\CurrentControlSet\Services\Remedy Email Engine\Parameters

Tag:
JVM Option Number 2

Value:
-xm<size>

You must also modify the JVM Option Count from 2 to 3.

72 XChapter 2—Remedy email engine installation and setup

Chapter

3 Email configuration

This chapter provides information and instructions for creating and

configuring mailboxes in your email engine environment, as well as
configuring security settings. It includes the following sections:
„ Email configuration overview (page 74)
„ Working with the mailbox configuration form (page 75)
„ Creating and configuring incoming mailboxes (page 76)
„ Creating and configuring outgoing mailboxes (page 85)
„ Implementing changes to your mailbox configuration (page 91)
„ Configuring a sent mail folder (MAPI) (page 92)
„ Testing your mailbox configuration (page 93)
„ Configuring email security (page 99)
„ Email options in the AR System configuration file (page 103)

Email configuration W 73
Action Request System 6.0

Email configuration overview

After installing the email engine, you may need to perform some
configuration before you can use the email engine for processing email. You
may have already performed some of this configuration during installation.
If you opted to forgo configuration during installation, you must complete
the configuration steps detailed in this chapter.

The purpose of this chapter is to provide the email engine with the
information it needs to communicate with your mail server. All of this
information is managed using specialized AR System forms that are created
and imported during installation. A comprehensive list of these forms and
their use is detailed in Appendix E, “Email engine forms.” In this chapter, you
will use these AR System forms to enter the information about your mail
server and the email accounts that the email engine will use to receive
incoming email and which it will use to send outgoing email.

Although the configuration process varies according to the needs of your

environment, it typically involves the following tasks:
„ Create and configure at least one mailbox. If you chose to configure an
incoming or outgoing mailbox (or both) during installation of the email
engine, you were guided through the configuration for incoming and
outgoing mailboxes. You can modify that initial configuration using the
procedures in this section. A common practice is configuring both
outgoing and incoming mailboxes to use the same email account on the
mail server.
„ Create and configure additional incoming and outgoing mailboxes as
needed.
„ Create a security key if needed.
„ Update configuration information if system errors or other email usage
problems occur.
„ If needed, set up or update associations between mailboxes and templates.
„ Update the emaildaemon.properties file if servers are changed. For
information, see “Updating the emaildaemon.properties file” on
page 189.

74 XChapter 3—Email configuration

 Remedy Email Engine Guide

Working with the mailbox configuration form

For the purpose of the Action Request System 6.0 Remedy Email Engine Guide,
a mailbox is an entry in the Remedy Email Mailbox Configuration form
(email engine) containing all of the information required either to access
mail from a mail server or to request that mail be sent by a mail server. At
least one mailbox must be configured in order to use the Remedy email
engine. The mailbox you configure can be used by the email engine for
receiving emails from your mail server (incoming) or it can be used to
transmit email messages (outgoing) using your mail server.

Creating new mailboxes for your environment is done using the AR System
Email Mailbox Configuration form. Figure 3-1 shows an example of the
configuration form (the fields present on the form may vary for different
configurations).

Figure 3-1: Mailbox Configuration form

Working with the mailbox configuration form W 75

Action Request System 6.0

If you chose to configure a mailbox during installation, an entry in this form

will have been created for the mailbox you chose to configure. You can use
those settings to get started with the email engine, modify them, or create as
many additional mailboxes as your environment may require.

Note: For mailboxes configured with the MAPI and MBOX protocols, the
information in the Basic Configuration tab is different. See Figure 3-2 on
page 78 for an example of the MAPI configuration and Figure 3-4 on
page 81 for an example of the MBOX configuration.

The Mailbox Configuration form specifies administrator information,

permissions, and security for each mailbox, as well as how email messages
should be processed for the mailbox. These options fall under the following
general categories:
„ Basic Configuration: The Basic Configuration tab is used primarily to
define connection information for connecting to your mail server. This
may include information such as the protocol used by your mail server for
receiving mail, the name of your mail server (or IP address), and so on.
„ Advanced Configuration: The Advanced Configuration tab is useful for
setting the behavior of this mailbox. This includes fields governing
mailbox default values, parsing behavior, mailbox associations and
mailbox security.

Creating and configuring incoming mailboxes

Incoming mailboxes are used by the email engine to check for emails
containing instructions such as form submissions, queries, and form
modifications.

An incoming mailbox represents information about an email account on

your mail server that the email engine will poll for new messages. Messages
in this email account will be treated as if they have been directed to the email
engine. The email engine will then read and (depending upon your
configuration) parse the content of the message to generate query
information, perform a submission, and so on. Using the AR System Email
Mailbox Configuration form, you can instruct the email engine to treat all
messages found in this email account as incoming messages. In addition,
using this form you can also specify what actions will be taken by the email
engine for each of these email messages.

76 XChapter 3—Email configuration

 Remedy Email Engine Guide

Note: You must create at least one incoming mailbox before you can begin
processing incoming mail using the email engine. If you opted for initial
mailbox configuration during installation, you can use those settings for
your first incoming and outgoing mailboxes. Use the steps in the following
procedure to modify your initial mailbox configurations, or configure
additional mailboxes as needed for your environment.

Using Remedy User, log in to the AR System server you specified during
installation of the email engine (this is where all of the forms are located).
Open the Remedy Email Mailbox Configuration form, then choose from
among the following procedures to create a new incoming mailbox or modify
an existing mailbox:

„ “Configuring your incoming mailbox using MAPI” on page 77

„ “Configuring your incoming mailbox using POP3 or IMAP4” on page 78
„ “Configuring your incoming mailbox using MBOX” on page 80
„ “Advanced configuration settings for incoming mailboxes” on page 82

Configuring your incoming mailbox using MAPI

Use the following procedure to configure the basic settings for incoming
mailboxes using the MAPI protocol. (Windows only)

1 Enter the following general information at the top of the form.

a Mailbox Name: Enter a unique name of up to 255 characters for the
incoming mailbox.
Note: This name is simply used to provide each mailbox you configure with
a unique identity and need not correspond to the name of the email
account to which this mailbox will point.

b Mailbox Function: From the drop-down list, select Incoming.

c Status: From the drop-down list, select Enabled to activate the mailbox
now, or Disabled to keep the mailbox disabled. (If you select Disabled, you
can change this setting later to activate the mailbox.)

Creating and configuring incoming mailboxes W 77

Action Request System 6.0

2 Select the Basic Configuration tab, and perform the following steps for
incoming mailboxes.

Figure 3-2: Basic configuration for incoming mail—MAPI

a Email Server Type: Select MAPI as the email server type.

b Polling Interval (Minutes): The polling interval is the number of minutes
after which the email engine will check for incoming mail from the mail
server for this mailbox.
c Profile Name: Enter the name of the MS Exchange profile to be used for
this mailbox. This field is required because a profile is used to refer to
MAPI email account configuration information. For more information
about MS Exchange profiles, refer to your MS Exchange documentation.
3 Click Save to submit or modify the new incoming mailbox information.
For information regarding the Advanced tab of an incoming mailbox, see
“Advanced configuration settings for incoming mailboxes” on page 82.

Configuring your incoming mailbox using POP3 or IMAP4

Use the following procedure to configure the basic settings for incoming
mailboxes using the POP3 or IMAP4 protocols.

1 Enter the following general information at the top of the form.

a Mailbox Name: Enter a unique name of up to 255 characters for the
incoming mailbox.
Note: This name is simply used to provide each mailbox you configure with
a unique identity and need not correspond to the name of the email
account to which this mailbox will point.

b Mailbox Function: From the drop-down list, select Incoming.

c Status: From the drop-down list, select Enabled to activate the mailbox
now, or Disabled to keep the mailbox disabled. (If you select Disabled, you
can change this setting later to activate the mailbox.) The default is
Enabled.

78 XChapter 3—Email configuration

 Remedy Email Engine Guide

2 Select the Basic Configuration tab, and perform the following steps for
incoming mailboxes.

Figure 3-3: Basic configuration for incoming mail—POP3 and IMAP4

a Email Server Type: Select a server type for this mailbox—either POP3 or
IMAP4.
b Polling Interval (Minutes): The polling interval is the number of minutes
after which the email engine will check for incoming mail from the mail
server for this mailbox.
c Email Server Requires SSL: Select Yes if the mail server requires SSL
transmissions, or accept the default value of No. Verify with your network
or email administrator if SSL is required for use with the AR System email
engine in your environment.
Note: SSL connections through the AR System email engine may fail if the
server certificate is not installed locally. In that case, you should obtain a
correct, valid certificate for the server and use the keytool utility to add it
to a local key storage at <Java_home>\jre\lib\security\cacerts. For more
information about the keytool utility, refer to the information located at
the following URL: http://java.sun.com/products/jdk/1.2/docs/tooldocs/
solaris/
keytool.html

d Email Server Name/IP: Enter the name or IP address of the mail server
used in your organization.

Creating and configuring incoming mailboxes W 79

Action Request System 6.0

e Email Server Port: Enter the port number used for connection to your
mail server. To set this value to the default port number commonly used
by most mail servers, click the Set Default Email Server Port button. You
can use the Set Default Email Server Port button to populate this field with
a default port number. Depending upon the protocol chosen for this
mailbox, the following default values will used:
„ POP3: 110
„ POP3 with SSL: 995
„ IMAP4: 143
„ IMAP4 with SSL: 993
f Email Server User: Enter the user name for this email account.
g Email Server Password: Enter the user password for this email account.
3 Click Save to submit or modify the new incoming mailbox information.
For information regarding the Advanced tab of an incoming mailbox, see
“Advanced configuration settings for incoming mailboxes” on page 82.

Configuring your incoming mailbox using MBOX

Use the following procedure to configure the basic settings for incoming
mailboxes using the MBOX protocol. (UNIX only)

1 Enter the following general information at the top of the form.

a Mailbox Name: Enter a unique name of up to 255 characters for the
incoming mailbox.
Note: This name is simply used to provide each mailbox you configure with
a unique identity and need not correspond to the name of the email
account to which this mailbox will point.

b Mailbox Function: From the drop-down list, select Incoming.

c Status: From the drop-down list, select Enabled to activate the mailbox
now, or Disabled to keep the mailbox disabled. (If you select Disabled, you
can change this setting later to activate the mailbox.) The default is
Enabled.

80 XChapter 3—Email configuration

 Remedy Email Engine Guide

2 Select the Basic Configuration tab, and perform the following steps for
incoming mailboxes.

Figure 3-4: Basic configuration for incoming mail—MBOX

a Email Server Type: Select MBOX as the email server type.

b Polling Interval (Minutes): The polling interval is the number of minutes
after which the email engine will check for incoming mail from the mail
server for this mailbox.
c Inbox Path: Enter the full path file name to the mbox file corresponding to
the user email account that will be used, for example, /usr/spool/mail/
ARSystem, where ARSystem is the mbox file name.
d User Name Path: Enter the full path of the user home directory.
Note: The user under which the email engine service is running must have
full read and write permissions to the directories and files supplied.

Warning: The MBOX store uses the dotlocking mechanism, which is

compatible with most Mail User Agents (MUAs) and Mail Transfer
Agents (MTAs), to synchronize concurrent access to the mailbox. Use of
non-dotlocking mail agents that access the same mailboxes used by the
mbox provider at the same time is likely to result in data loss.

Step 3 Click Save to submit or modify the new incoming mailbox information.

For information regarding the Advanced tab of an incoming mailbox, see

“Advanced configuration settings for incoming mailboxes” on page 82.

Creating and configuring incoming mailboxes W 81

Action Request System 6.0

Advanced configuration settings for incoming mailboxes

Use the following procedure to configure the advanced settings for incoming
mailboxes of all protocols.

1 To select additional configuration options to process incoming mail, select

the Advanced Configuration tab (Figure 3-5).

Figure 3-5: Advanced configuration for incoming mail

Warning: Detailed descriptions of many of these advanced configuration

settings are discussed in greater detail in Chapter 4, “Email templates” and
Chapter 5, “Messages and notifications.” You might want to review this
information before proceeding with advanced configuration.

2 Associated Mailbox Name: Select a name of an outgoing mailbox that will be

used to reply to incoming emails that require a response (for example, query
results).

82 XChapter 3—Email configuration

 Remedy Email Engine Guide

3 Enter the following Action Configuration information:

a Email Action: Select Parse to enable the email engine to detect and process
instructions included in an incoming email message, or accept the default
value of None for no action. For a list of instructions that can be parsed by
the email engine, see “Labels and values used in the templates” on
page 113.
Note: If you will be using templates to perform Submit, Modify, or Query
actions, this must be set to Parse. For more information, see “Incoming
and outgoing mail templates” on page 107.

b Use Original Template Format: Select Yes to enable the system to only use
the parsing mechanism used in the original parsing system and thus
ignoring special HTML fields and XML formats.
The “original parsing system” refers to the processing in the pre-5.1
Remedy Mail Server (armaild/armailex). This functionality is included to
provide backwards compatibility for customers who previously used the
Remedy Mail Server to submit requests through email. This compatibility
is extended to include ignoring data entered in an invalid format (for
example a character string in a number field, or an invalid date format.)
By contrast, the Remedy Email Engine will return an error in these cases.
If this field is set to No, the system will still read the emails properly with
the exception that, in the new format, multiple lines must be encapsulated
with the multiple line delimiters [$$ and $$].
c Reply with Result: Accept the default value of Yes to enable the results of
an Action to be included with an email reply, or select No if results should
not be included.
Note: For more information, see “Actions” on page 116.

d Reply with Entry: Select Yes to return the complete entry of a submit or
modify action. Select No to use the default single-line entry.
The Reply with Result and Reply with Entry configuration option does not
send attachments in the email (although the attachment file name is
specified). To include attachment content with the email and not just the
attachment name, you must use a template. For more information, see
“Adding attachments to your email” on page 152.
e Enable Modify Actions: Select Yes to enable modify actions, or No to
prevent modify actions from being performed.

Creating and configuring incoming mailboxes W 83

Action Request System 6.0

f Default Workflow Form: Enter the name of the form upon which the
email engine will execute instructions found within the incoming email
message (for example, queries, form entry modifications, and form
submittals) should no specific form be specified in the email message.
g Force Default Workflow Form: Select Yes if the Default Workflow Form
should be used regardless of what was specified in an incoming email. This
action will confine all instructions received by this mailbox to the specified
form.
4 Enter the following Incoming Security Configuration information:
In these fields, you specify the level of security to be applied to email
messages to this mailbox. This information is used to determine which
AR System user information to apply when executing instructions parsed
from an incoming email. You can apply any or all of these security
options, depending on the level of security you want.
a Use Security Key: Select Yes to force a security key to be used for incoming
mail to this mailbox. The security key itself is created in the Email Security
form (Figure 3-14 on page 101). When mail arrives to this mailbox, the
AR System server compares the key present within the incoming email
message with the security key that has been associated with this mailbox.
If the security key present in the incoming email message does not match
the associated entry stored in the Email Security form, an error message is
generated.
Note: When Use Security Key is set to Yes, you do not need to supply the user
name and password information in the incoming mail. If the security key
is found in the Email Security form, the server retrieves the user name
from that form and processes the email message on behalf of that user.

For more information about adding security keys, see “Creating email
security keys for incoming mail” on page 100. Security keys provide the
strongest level of security for email transmissions.
b Use Supplied User Information: Accept the default value of Yes to use
AR System server login information that may be included within the
incoming email message. This login information will be extracted from
the email message and used by the email engine as the AR System user
account for executing any instructions such as modifying forms,
submitting queries, and so on.

84 XChapter 3—Email configuration

 Remedy Email Engine Guide

c Use Email From Address: Accept the default value of Yes to use the email
address of the sender as a form of authentication. When mail arrives to
this mailbox, the email engine checks the sender’s address against the
email addresses stored in the AR System User form. If a matching address
cannot be found in the User form, an error message is generated.
5 Click Save to submit or modify the new incoming mailbox information.

Creating and configuring outgoing mailboxes

Outgoing mailboxes contain the information required by the email engine to
create and send messages. Outgoing messages often include results of
queries, notifications triggered by workflow, results from submit actions, or
any other updates that users may wish the email engine to report back with.
Outgoing mailboxes can also be linked to incoming mailboxes such that the
results of any actions taken from a specific incoming mailbox are sent to the
specified outgoing mailbox.

Using the AR System Email Mailbox Configuration form, you can instruct
the email engine to send outgoing messages using the configuration settings
available on this form. In addition, using this form you can also specify what
actions, message content, or other message formatting will be used by the
email engine for each of these outgoing messages.

Note: At least one outgoing mailbox must be created before you can begin
processing outgoing mail. If you opted for initial mailbox configuration
during installation, you can use those settings for your first incoming and
outgoing mailboxes. If you are using notifications, you should specify one
mailbox as the default notification mailbox, which is required to enable
outgoing delivery of notifications by email. Use the steps in the following
procedure to modify your initial mailbox configurations, or configure
additional mailboxes as needed for your environment.

Open the Mailbox Configuration form, then choose from the following
procedures to create a new outgoing mailbox or modify an existing mailbox:

„ “Configuring your outgoing mailbox using SMTP” on page 86

„ “Configuring your outgoing mailbox using MAPI” on page 87
„ “Advanced configuration settings for outgoing mailboxes” on page 88

Creating and configuring outgoing mailboxes W 85

Action Request System 6.0

Configuring your outgoing mailbox using SMTP

Use the following procedure to configure the basic settings for outgoing
mailboxes using the SMTP protocol.

1 Enter the following general information at the top of the form.

a Mailbox Name: Enter a unique name of up to 255 characters for the
outgoing mailbox.
b Mailbox Function: From the drop-down list, select Outgoing.
c Status: From the drop-down list, select Enabled to activate the mailbox
now, or Disabled to keep the mailbox disabled. (If you select Disabled, you
can change this setting later to activate the mailbox.)
2 Select the Basic Configuration tab, and perform the following steps for
outgoing mailboxes.

Figure 3-6: Basic configuration for outgoing mail—SMTP

a Email Server Type: Select SMTP.

b Polling Interval (Minutes): The polling interval is the number of minutes
after which the email engine will check for new outgoing mail waiting to
be sent from this mailbox.
c Email Server Requires SSL: Select Yes if your mail server requires SSL
transmissions, or accept the default value of No. Verify with your network
or email administrator as to whether email sent by the email engine must
use SSL in your environment.
d Email Server Name/IP: Enter the name or IP address of the mail server
used in your organization.
e Email Server Port: Enter the port number used for connection to your
mail server. To use the default SMTP port, click the Set Default Email
Server Port button.

86 XChapter 3—Email configuration

 Remedy Email Engine Guide

f Email Server User: Enter the user name for this email account. This is the
email account on your mail server that the email engine will use to
authenticate its request to have a message sent by your mail server.
g Email Server Password: Enter the user password for this email account.
Note: The Email Server User and corresponding Email Server Password
fields are only required if your mail server requires authentication
information before handling requests to send mail. Check with your mail
server administrator to determine if authentication is required in your
mail environment.

Step 3 Click Save to submit or modify the new outgoing mailbox information.

For information regarding the Advanced tab of an outgoing mailbox, see

“Advanced configuration settings for outgoing mailboxes” on page 88.

Configuring your outgoing mailbox using MAPI

Use the following procedure to configure the basic settings for outgoing
mailboxes using the MAPI protocol.

1 Enter the following general information at the top of the form.

a Mailbox Name: Enter a unique name of up to 255 characters for the
outgoing mailbox.
b Mailbox Function: From the drop-down list, select Outgoing.
c Status: From the drop-down list, select Enabled to activate the mailbox
now, or Disabled to keep the mailbox disabled. (If you select Disabled, you
can change this setting later to activate the mailbox.)
2 Select the Basic Configuration tab, and perform the following steps for
outgoing mailboxes.

Figure 3-7: Basic configuration for outgoing mail—MAPI

a Email Server Type: Select MAPI.

Creating and configuring outgoing mailboxes W 87

Action Request System 6.0

b Polling Interval (Minutes): The polling interval is the number of minutes

after which the email engine will check for new outgoing mail waiting to
be sent from this mailbox.
c Profile Name: Enter the name of the MS Exchange profile to be used for
this mailbox. This field is required because a profile is used to refer to
MAPI email account configuration information. For more information
about MS Exchange profiles, refer to your MS Exchange documentation.
Step 3 Click Save to submit or modify the new outgoing mailbox information.

For the Advanced tab of an outgoing mailbox, see the following procedure.

Advanced configuration settings for outgoing mailboxes

Use the following procedure to configure the advanced settings for outgoing
mailboxes of all protocols.

1 To select additional configuration options to process outgoing mail, select the

Advanced Configuration tab.

Figure 3-8: Advanced configuration for outgoing mail

88 XChapter 3—Email configuration

 Remedy Email Engine Guide

Note: Detailed descriptions of many of these advanced configuration settings

are discussed in greater detail in Chapter 4, “Email templates” and
Chapter 5, “Messages and notifications.” You might want to review this
information before proceeding with advanced configuration.

2 Associated Mailbox Name: This is the name of the incoming mailbox that
will be used to receive instructions or notifications. Enter or select an
associated mailbox using one of the following methods:
Note: You must have configured at least one incoming mailbox before you
can use this field.

„ If you configured this mailbox during installation, enter the name of an

incoming mailbox to serve as the associated mailbox. The default value in
this field will be the incoming mailbox you configured during installation.
(If other mailboxes have already been created, you can select a mailbox
from the menu list.)
„ If you did not select initial mailbox configuration during installation, enter
the name of an incoming mailbox to serve as the associated mailbox. (If
other incoming mailboxes have already been created, you can select a
mailbox from the menu list.)
3 Default Outgoing Mailbox: If Yes is selected, then all outgoing messages for
which an outgoing mailbox is not specified will be sent using information in
this entry.
4 Display Name: This setting will be the name you want displayed in the From:
line of the outgoing email. Change the display name to something descriptive
for your environment.
Note: If you are using the MAPI protocol, you cannot change the Display
Name directly here in the Email Mailbox Configuration form. Instead,
you must change the Display Name through the MS Exchange server.
With MAPI, the sender information is tied to the login name and cannot
be changed. However, you may still want to set this value for information
purposes only.

5 Email Address: The full email address of the administrator or owner of this
mailbox.
The email address you specify will be the default From: email address in
outgoing emails. As a result, if you entered a Display Name of ARSystem and
an email address of [email protected], the From: line would look like:
From: ARSystem [[email protected]]

Creating and configuring outgoing mailboxes W 89

Action Request System 6.0

6 Reply To Address: A reply-to email address for the mailbox owner or

administrator, if you plan to enable users to reply to notification messages
sent from this mailbox. This field is automatically filled with the information
entered in the Email Address field. To specify a different email address for
replies, enter that email address here.
Note: If you are using the MAPI protocol, you cannot change the Reply To
Address directly here in the Email Mailbox Configuration form. Instead,
you must change the Reply To Address through the MS Exchange server.
With MAPI, the Reply To Address is tied to the login name and cannot be
changed within the configuration form. However, you may still want to set
this value for information purposes only.

7 Organization: For email clients that display an organization name, the name
of the mailbox owner, or administrator’s organization.
8 Delete Outgoing Notification Messages: Select Yes (the default setting) to
have outgoing notification messages deleted from the AR System Email
Messages form after they have been sent from this mailbox.
Select No to save system-generated messages (that is, messages generated by
the AR System server and not messages manually entered by a user) in the
AR System Email Messages form.
9 Default Addressing: Enter the email addresses to send to if addresses have
not been specified in the Messages tab for a notify filter or escalation. If
addresses are specified in the Messages tab, those addresses will override the
addresses you enter here. For more information about these values in a notify
filter or escalation, see Chapter 5, “Messages and notifications.”
a Default To: Enter default email addresses for those who should receive
outgoing messages from this mailbox.
b Default CC: Enter default email addresses for those who should receive
copies of outgoing messages from this mailbox.
c Default BCC: Enter default email addresses for those who should receive
blind copies of outgoing messages from this mailbox.
10 Default Templates: If a user creates a message without specifying a template
in the Templates tab for either Notify filter or escalation actions, then this
template will be used by default. For more information about these values in
a notify filter or escalation, see Chapter 5, “Messages and notifications.”
a Header Template: Select or enter a template to be used as the default
header template.

90 XChapter 3—Email configuration

 Remedy Email Engine Guide

b Footer Template: Select or enter a template to be used as the default footer

template.
c Status Template: Select or enter a template to be used as the default status
template.
d Result Template: Select or enter a template to be used as the default
content template.
Step 11 Click Save to submit or modify the new outgoing mailbox information.

Implementing changes to your mailbox configuration

When the email engine is started, it will contact the AR System server and
retrieve all of the entries in the AR System Email Mailbox Configuration
form for the purpose of creating Incoming and Outgoing mailboxes. While
running, the email engine will periodically query the AR System Email
Mailbox Configuration form for updates to any entries (that is, changes in
your mailbox configuration such as a change to the Mailbox Name field). By
default, this query occurs every 30 minutes. As such, any change you may
make to your mailbox settings may not take effect for up to 30 minutes (by
default), unless you chose to stop and then restart the email engine (upon
restart, the email engine will immediately query the Remedy Email Mailbox
Configuration form) which will result in the immediate implementation of
your change.

The time the email engine waits between queries is configurable and is
governed by the following property in the emaildaemon.properties file:

com.remedy.arsys.emaildaemon.<server_name>.Interval = 5

Where <server_name> represents the name of your AR System server.

For more information about this property or the emaildaemon.properties

file, see “Performance and configuration settings” on page 191.

Implementing changes to your mailbox configuration W 91

Action Request System 6.0

Configuring a sent mail folder (MAPI)

Messages sent from an outgoing mailbox are not automatically saved in the
AR System Email Messages form.

System-generated messages, that is, messages generated by the AR System

server and not messages manually entered by a user, are saved in the
AR System Email Messages form only if you have configured the
corresponding Outgoing mailbox to save the outgoing notification messages.
You must properly set the Delete Outgoing Notification Messages parameter
in the Advanced Configuration tab for the Outgoing mailbox in the
AR System Email Mailbox Configuration form:

„ If you set this parameter to Yes, the system-generated messages will be

deleted.
„ If you set this parameter to No, the system-generated messages will be
saved in the form after being sent.

Any manual messages must be deleted by the administrator or a user with

appropriate permissions to perform that task.

When using the MAPI protocol, the Remedy Email Engine does not
automatically save sent messages in the Sent Items folder of the MS Outlook
client. For the MAPI protocol, if you want to save your sent messages in an
Outlook folder, you must update the emaildaemon.properties file by adding
a line that indicates the sent mail folder:

com.remedy.arsys.emaildaemon.<server_name>.MAPI_Sent_Folder=<folder_n
ame>

where:
„ <server_name> is the name of the mail server used by this mailbox.
„ <folder_name> is the name of the folder used to store mail sent by the
email engine.

This setting allows the AR System email engine to recognize the sent items
folder. If you wanted to save messages in your Sent Items folder, use the
following line:

com.remedy.arsys.emaildaemon.<server_name>.MAPI_Sent_Folder=Sent
Items

92 XChapter 3—Email configuration

 Remedy Email Engine Guide

Testing your mailbox configuration

After you have configured a mailbox for use by the email engine, you should
test your mailbox configuration settings by performing one of the following
procedures:

„ “Testing your incoming mailbox” on page 93

„ “Testing your outgoing mailbox” on page 96
These procedures ensure that you have properly configured the Basic
Configuration settings necessary for your mailbox to communicate with
your mail server.

Note: These steps assume you do not require a security key to authenticate
incoming mail Messages. See “Configuring email security” on page 99 for
more details about mailbox security settings.

Testing your incoming mailbox

Use the following steps to verify that you can send mail to your incoming
mailbox.

1 Using the Remedy User, open the AR System Email Mailbox Configuration
form and search for the Incoming Mailbox entry you wish to test.
2 Make a note of the email account or profile that the Incoming Mailbox is
using. Verify with your email administrator the proper email address to use
when directing email to this account/profile.
3 Compose an email using your third-party email client directed to the email
address you identified in step 2. Provide a subject line and some content in
the email message.
4 Send the email message.
5 Obtain the value of the Polling Interval for the Incoming Mailbox you are
testing. This value is set in the Basic Configuration Tab of the AR System
Email Mailbox Configuration form. You may need to wait until the time
indicated by the polling interval before you can determine if the message you
sent during step 4 was received by the email engine.
6 After waiting for the prescribed number of minutes indicated by the polling
interval for this mailbox, open the AR System Email Messages form. An entry
in this form is created whenever new mail arrives to or is sent from the email
engine.

Testing your mailbox configuration W 93

Action Request System 6.0

7 Perform a search of the AR System Email Messages form to determine if the

message you sent during step 4 arrived here. You should see an entry
corresponding to the message you sent in the search results table.

Figure 3-9: Entry created of incoming email message

8 Open the entry by selecting the entry in the search results table. Verify that
the subject line and email content correspond to that which you entered in
step 3.
If you managed to successfully complete steps 1-8 of this test then you have
properly configured your Incoming Mailbox to communicate with your mail
server. If you were unable to complete these steps, please verify the following:
„ The email engine is running.
„ The mail server is running.
„ The Status field of the mailbox should be set to Enabled.
„ The email account used by the Incoming Mailbox is a valid account on the
mail server (POP3/IMAP4) or that the Exchange profile specified for this
mailbox is accessible on the system the email engine is running on
(MAPI).
Note: By default, the email engine service is launched as the local system
account. However, if you elected to configure a MAPI mailbox during
installation, you must change the login information (in the Services
control panel) for the email engine service from the local system account
to the appropriate account.

„ The port number in the mailbox entry is the proper port number for
communicating with your mail server.
„ You have entered the right password for the email account in the
Incoming Mailbox Basic configuration tab (POP3/IMAP4).

94 XChapter 3—Email configuration

 Remedy Email Engine Guide

„ The email address you chose to send the message to was the proper address
for directing email to the email account (POP3/IMAP4) or profile (MAPI)
specified in the Incoming Mailbox.
„ You have waited for a period of time not less than that indicated by the
Polling Interval before checking the AR System Email Messages form for
your message.
Note: Any changes you may make to your mailbox in an effort to
troubleshoot possible configuration problems may not be immediately
recognized by the email engine. For more information, see “Implementing
changes to your mailbox configuration” on page 91.

If you have attempted to troubleshoot your problem using the above tips and
are still unable to proceed, review Chapter 6, “Troubleshooting” for
additional suggestions.

Testing your mailbox configuration W 95

Action Request System 6.0

Testing your outgoing mailbox

Use the following steps to verify that you can send mail from your outgoing
mailbox.

1 Open the AR System Email Messages form in New mode in the Remedy User.

Figure 3-10: Outgoing email message

2 Compose a message using this form as follows:

„ In the Mailbox Name field, select the Outgoing Mailbox you wish to test.
„ For the Message Type field, select Outgoing.
„ In the Message Tab, provide an email address for the From: and To: fields.
Be sure to sent the message to an account that you can access using a third
party email client utility (such as Microsoft Outlook).
„ In the Message Tab provide a subject line and a body.
3 Scroll down to the bottom of the form and click Send.

96 XChapter 3—Email configuration

 Remedy Email Engine Guide

4 Open the AR System Email Messages form in search mode and perform a
query. In the search results table, an entry should exist for the message you
sent during step 3. The value under the Send Message column should read
Yes. This indicates that your message has been flagged to be sent by the
Outgoing Mailbox.

Figure 3-11: Entry created of outgoing email message

5 Open the AR System Email Mailbox Configuration form and search for the
Outgoing Mailbox entry you wish to test.
6 Obtain the value of the Polling Interval for the Outgoing Mailbox you are
testing. This value is set in the Basic Configuration tab of the AR System
Email Mailbox Configuration form. You may need to wait until the time
indicated by the polling interval before you can determine if the message you
sent during step 3 was actually sent by the email engine.

Testing your mailbox configuration W 97

Action Request System 6.0

7 After waiting for the prescribed number of minutes indicated by the polling
interval for this mailbox, open the AR System Email Messages form. Perform
a search of the form to determine if the message you flagged to be sent was,
in fact, sent. If the message was picked up by the Outgoing Mailbox and sent,
you should see the value in the Send Message column indicate Sent and the
Date Sent column should indicate the precise time that the message was sent
to the mail server.

Figure 3-12: Entry created of outgoing email message sent

8 Using a third party email client, verify that the message was sent to the To
address you specified in step 2.
If you managed to successfully complete steps 1-8 of this test then you have
properly configured your Outgoing Mailbox to communicate with your mail
server. If you were unable to complete these steps, please verify the following:
„ The email engine is running.
„ The mail server is running.
„ The Status field of the mailbox should be set to Enabled.
„ Determine if the mail server requires authentication in order for messages
to be sent. If your mail server requires authentication, then you must
ensure that you have provided valid email account information for this
mail server in the Basic Configuration tab for this mailbox (SMTP) or the
name of a valid Exchange profile (MAPI).
„ The port number in the mailbox entry is the proper port number for
communicating with your mail server.
„ You have entered the right password for the email account in the
Outgoing Mailbox Basic configuration tab (SMTP) or that you have
logged in to the system as the domain user account that has permission to
use the MS Exchange profile (MAPI).

98 XChapter 3—Email configuration

 Remedy Email Engine Guide

„ You have waited for a period of time not less than that indicated by the
Polling Interval before checking the AR System Email Messages form to
see if your message was sent.
Note: Any changes you may make to your mailbox in an effort to
troubleshoot possible configuration problems may not be immediately
recognized by the email engine. For more information, see “Implementing
changes to your mailbox configuration” on page 91.

If you have attempted to troubleshoot your problem using the above tips and
are still unable to proceed, review Chapter 6, “Troubleshooting” for
additional suggestions.

Configuring email security

Incoming and outgoing mail use different security mechanisms:

„ Incoming mail messages use security keys for validation.

„ Outgoing mail messages, which include the results of query actions, make
use of AR System access control for forms and fields. If a user does not
have access to the field or form being queried, the field and its contents will
not be contained in the outgoing mail message.
The following sections provide instructions for creating security keys for
incoming mail, and describe how security is handled for outgoing mail.

Configuring email security W 99

Action Request System 6.0

Creating email security keys for incoming mail

A security key can be associated with each incoming mailbox to validate the
permissions for incoming mail to perform various actions on the AR System
server, for example, modifying entries. In the Mailbox Configuration form,
you can specify if a security key is required for mail sent to a mailbox
(Figure 3-13). In the Email Security form, you can create a security key and
associate it with a mailbox (Figure 3-14 on page 101).

Mailbox
Configuration
Form: Security
Key
Requirement
for this
Incoming

Email Security Form:

Security Key Created
for this Incoming
Mailbox

Figure 3-13: Configuring security settings for incoming mail

When mail arrives, the email engine validates the security key included
within the incoming email message against the information in the Email
Security form. If the key is valid, the email engine then checks the name of
the mailbox owner as entered in the form.

100 XChapter 3—Email configuration

 Remedy Email Engine Guide

X To create email security keys for incoming email:

1 From the Remedy User Tool, open the AR System Email Security form in
new mode as shown in Figure 3-14.

Figure 3-14: Email Security form

2 Enter the following information:

„ Status: Select Enabled to activate the key, or Disabled to keep the key
disabled.
„ Key: Enter a set of alphanumeric characters. You can use almost any
combination of letters and numbers for a security key; however, keep the
following precautions in mind when selecting a key:
„ Security keys are case-sensitive. For example, CITYSCAPE, Cityscape, and
cityscape are all different.
„ Do not use names that are common to your working environment and
that could be easily guessed; for example, do not use a favorite product
nickname, your name, or a campus building name.
„ Consider mixing numbers, letters, and special characters to make the
key harder to guess—for example, City2Scape or City!Scape.
„ Do not use spaces, forward slashes, or backslashes.

Configuring email security W 101

Action Request System 6.0

„ User Name: Enter the name of a valid AR System user to which the
security key should apply.
„ Force for Mailbox: Enter Yes to enable the security key for this mailbox
only, or No to enable the key for all mailboxes in your email environment.
If you select Yes, the Mailbox Name field becomes enabled.
„ Mailbox Name: Enter the name of the Incoming Mailbox to which you
want this security key applied.
„ Force from Email Addresses: Enter Yes to require this key for mail
received from specific email accounts. If you select Yes, the Email Address
field becomes enabled.
„ Email Addresses: If you wish to verify incoming messages from a set of
specific email accounts using a security key, enter those email addresses.
„ Expires: Enter Yes if you want the key to expire on a specific date. If you
select Yes, the Expiration Date field becomes enabled.
„ Expiration Date: Enter an expiration date for this security key. Once the
key expires, you can either modify the expiration date in this form, or set
the Expires field to No.
„ Description: Enter a description for the key, such as why it was created or
instructions for modifying or deleting it.

Security for outgoing mail with query actions

The following criteria are used to define security for outgoing mail that
includes the results of a query from the AR System server:
„ When sending a message to a single user, that user will be able to see only
the data they would normally have access to from the AR System
User Tool.
„ When sending a message to more than one user, the data included in the
outgoing message will be limited to that allowed to the user with the lowest
level of permissions. For example, if an outgoing message is sent to both
an administrator and a user with only Public access, only data allowed by
Public access will be included in the email message.

Warning: If one of the recipients of an email message does not have access to
any of the fields used in a query, the message will not be sent because the
system does not allow execution of a query on fields for which a user does
not have access permission.

102 XChapter 3—Email configuration

 Remedy Email Engine Guide

„ If a record is locked by the system through the row-level access feature, it

will be included only if all email recipients have access to that record.
„ If you send a message with query results to a nonregistered AR System
user, the form and fields queried must have Public access, and the
AR System server must be configured to allow guest users.

Email options in the AR System configuration file

The AR System configuration file (ar.conf for UNIX and ar.cfg for Windows)
contains configuration information used by AR System. It can be found in
the following locations:
„ UNIX: <ar_install_dir>/conf/ar.conf
„ Windows: <ar_install_dir>\Conf\ar.cfg

This section describes the configuration options specific to the AR System

email engine. For general information about this file and options available
for other components of the AR System, refer to the Configuring AR System
guide.

Email-AIX-Use-Old-System
IBM AIX only: Enables use of the AR System 5.0 and earlier email
notification method with a version of the Java SDK earlier than 1.4. The
default value is T (use older email notification method).

Email-Delivery-System
IBM AIX only: Specifies that the sendmail utility available on IBM AIX
systems will be used. The default is “usr/lib/sendmail -t -oi- -f “%f””.

Email-Import-Form-By-Default
Specifies whether email forms are imported by default when the
AR System server is started up, if all email forms have been deleted. Valid
values are T (True) and F (False). A value of T means that email forms will
be imported by default when the AR System server is restarted; a value of
F means that the forms will not be imported by default. The default value
is T.

If some, but not all, of the forms have been deleted previously, a message
will appear when you restart the AR System server, informing you that you
must import those forms manually.

Email options in the AR System configuration file W 103

Action Request System 6.0

104 XChapter 3—Email configuration

Chapter

4 Email templates

This chapter provides information and instructions for creating and using
templates for email transmissions. It includes the following sections:
„ About email templates (page 106)
„ Creating templates (page 110)
„ Labels and values used in the templates (page 113)
„ Storing templates in the AR System Email Templates form (page 131)
„ Adding attachments to templates (page 132)
„ User-Defined instruction templates (page 138)
„ Preparing email templates after an upgrade (page 145)

Email templates W 105

Action Request System 6.0

About email templates

Email templates serve to facilitate a variety of functions for both incoming
and outgoing messages. With respect to incoming messages (email directed
by end-users to an email engine incoming mailbox), users can include
templates in their emails that contain specially formatted instructions (also
known as Labels and Values). It is these instructions that the email engine
parses (that is, translates) into commands to the AR System server to
perform a query, submission, modify an entry, or any other such action. For
outgoing messages (sent by the email engine using an outgoing mailbox),
templates can provide formatting and content for messages that include the
results of queries or various other requests.

Templates used for both incoming and outgoing messages can be formatted
using plain text, HTML, Rich Text Format (RTF), or XML. Templates are
defined and stored using forms stored on the AR System server and can be
retrieved for use by the email engine when called upon either by incoming or
outgoing mailboxes.

In this chapter, we will be describing the various types of templates, their use
as they pertain to both incoming and outgoing mailboxes, as well as the
instructions known as Labels and Values that can be included in templates
and used to instruct the email engine to interact with your AR System server.

Note: If you have upgraded from Remedy Mail Server (pre-5.1), you must
modify your existing templates to use some of the new 6.0 features. You
can, however, still use your pre-5.1 email templates created for the
Remedy mail server with the 6.0 Remedy email engine. For more
information, see the “Use Original Template Format” feature described in
“Advanced configuration settings for incoming mailboxes” on page 82.

Types of templates
You can create specific templates for various functions. This section presents
an overview of the different types of templates, they are all described in more
detail later in this chapter.

106 XChapter 4—Email templates

 Remedy Email Engine Guide

Incoming and outgoing mail templates

You can create separate templates to specify different formats for incoming
and outgoing mail. The following is a summary.
„ Content templates. Used for outgoing messages. These templates may be
associated with a specific form and contain the fields and their
corresponding values (including variables) relating to a specific record.
You can create these templates in a text editor (shown in the following
figure), or export them using Remedy Administrator, selecting the form
and fields that are to be contained in the template. Also using the template,
you can specify actions to be performed when the contents of the email are
parsed by the email engine. The content template can also contain
formatting instructions and label value pairs to specify a header, footer,
result, or status template. A content template is attached using either the
AR System Email Messages form, or using workflow with filters and
escalations.

Figure 4-1: Content template: text

About email templates W 107

Action Request System 6.0

„ Header and footer templates. These are often used to place lines of text, or
a graphic on a message (results of a header template shown in the
following figure). They can be specified in the outgoing email using the
AR System Email Messages form. If they are specified in content templates
or an email body as label value pairs, they will be applied to the email reply.

Figure 4-2: Header and footer template

„ Result templates. Defines the format to use when replying to an incoming

or outgoing instruction (action) email with the results of an action (results
shown below). A label value pair must be specified in the email or content
template containing the action. The following figure shows an example of
an HTML-formatted version of a result template.

Figure 4-3: Result template

108 XChapter 4—Email templates

 Remedy Email Engine Guide

„ Status templates. Defines the format to use when status information is

returned when the instruction executed by the email engine results in an
error (as shown in the following figure). A label value pair must be
specified to include specific status information in the email or content
template. (For more information, see “Reserved variables” on page 126.)

Figure 4-4: Status template

If you want graphic elements to appear on your email, you can add these as
attachments to the template in the AR System Email Templates form.

You must store templates in the AR System Email Templates form before you
can use them. Each template is given a unique ID, which may be a Request
ID, or a unique name by which it can be accessed.

User-Defined instruction templates

User-Defined Instruction Templates enable you to associate a template (a
User-Defined Instruction Template) with an incoming email by way of an
entry in the AR System Email User Instruction Templates form. When the
user sends an email with the appropriate entries, the Remedy Email Engine
executes the relevant User-Defined Instruction template.

About email templates W 109

Action Request System 6.0

Using this feature, the administrator can set up variable substitutions to be

used in an email with minimal input from the user. For example, the user
need only send an email with the Action label and a value which identifies the
user instruction, for example, Action: Urgent. The associated template
supplies the rest of the information. User-defined templates look the same as
other templates and are stored in the AR System Email Templates form. For
more information, see “Actions” on page 116 and “User-Defined instruction
templates” on page 138.

Figure 4-5: User-Defined instruction template

Creating templates
In the Remedy Administrator tool, you can generate the email templates
associated with a particular form by choosing the Tools > Export Mail
Templates. The templates are generated as text files; you can modify the
templates in a text editor so that they are in a different format and include all
necessary specifications. You can also create your own custom template
using any text editor. These templates must adhere to the rules outlined in
this document if they are to include fields or variables.

110 XChapter 4—Email templates

 Remedy Email Engine Guide

Exporting mail templates

The mail template displays all of the fields that are visible in the view selected
of the form and that all users have permission to update. Therefore, make
sure that all fields that require a value are visible in the selected view and that
the Allow Any User To Submit check box is selected before performing the
following procedure. The Export operation generates fields in the same order
as in the default administrator view of the form.

Hidden fields are omitted from templates even though they might have
public permissions and be set to enable any user to submit. You can add any
of the fields that are not exported to the template. The user can gain access to
these fields if their security key, supplied user information, or their email
address connects to the correct user name and depending on how the
mailbox was configured. If the user name used by the Remedy Email Engine
has access to this field, then the field is accessible. If the user or administrator
does not provide login authentication, the submission defaults to Mailer
daemon.

1 In the AR System Administrator tool, select a server to administer.

2 Choose Tools > Export Mail Templates.
The Export Mail Templates dialog box appears.

Figure 4-6: Export Mail Templates dialog box

Creating templates W 111

Action Request System 6.0

3 From the Forms to Export list, select the form for which you want to generate
mail templates.
If you want to export more than one form, create a separate email template
for each form.
4 Click Export to open the Export File dialog box.
5 Specify where you want the templates stored, and then save your changes.
The selected template is stored in a single file. If you specify an existing folder
and file name, you have two choices:
„ Overwrite—Overwrites the mail template of an existing file. This option
is useful when you are re-exporting a template that has changed.
„ Append—Appends the contents to an existing file. If several templates are
in a single file, the mail processor will not be able to process the request.

The template is saved as a text file with a *.arm extension. Using the
AR System Email Templates form, users can associate these files with their
mail messages.

The following figure shows a sample template.

#
#File Exported Thur May 23 16:18:03 2004
#

Schema: emTest
Server: studio.Remedy.COM
Login:
Password:
Action: Submit
#Values: Submit, Query
Format: Short
# Values: Short, Full

Submitter !2!:
Short-Description !8!:

In general, lines beginning with a pound sign (#) are treated as comments,
and can occur anywhere in the message. Comments are optional and can be
retained or deleted.

112 XChapter 4—Email templates

 Remedy Email Engine Guide

Labels and values used in the templates

The templates consist of labels and values surrounded by text or graphics,
depending on the format of the template. The Labels are keywords such as
Action, and the values consist of data or commands (for example, Submit).
Values may be specified in the templates or obtained from the configuration
information. The email engine is not case sensitive when parsing the labels.
The following is a table of valid labels; each label is discussed in more detail
following the table.

Label Description Incoming Outgoing Aliases

Form The name of an AR System form. Yes No Schema
Server The server that will be affected by the Yes No
instruction.
Login The User Name used when executing the Yes No User
instruction. User Name
Name
Login
Password Password used when executing the Yes No
instruction.
TCP Port TCP port used when logging in to the Yes No TCP
AR System server.
Authentication Authentication String used when logging Yes No
in to the AR System server.
RPC Number RPC number used when logging in to the Yes No RPC
AR System server.
Language Language used when logging in to the Yes No
AR System server.
Action Denotes the instruction to be executed. Yes No Instruction
Format Specifies the format of the information. Yes Yes
Qualification Qualification for a query-based Yes No Query
instruction. Search
Result Template The name of the template to use in the Yes No Result
reply. ResultTemplate

Labels and values used in the templates W 113

Action Request System 6.0

Label Description Incoming Outgoing Aliases

Status Template The name of the template to use when Yes No Status
Status Information is returned. The Status StatusTemplate
template is only used if an instruction
executed by the email engine results in an
error.
Header The template to be used as the header in No Yes Header
Template the reply email. HeaderTemplate
Footer The template to be used as the footer in No Yes Footer
Template the reply email. FooterTemplate
!Name/ID! The name or ID of an AR System Form Yes Yes
Field. This could also be the name of the
user-defined field located in a master
template.
Key The key associated with a given sender or Yes No Encryption Key
user. Encryption
Request ID The Request ID of the entry on which the Yes No Entry ID
possible action must be executed. EntryID
RequestID

Form
If no AR System form is specified or the specified form does not exist, the
mail process verifies whether a default Workflow form was defined in the
AR System Email Mailbox Configuration form. If not, the item is rejected
because a form must be specified. The alias for this label is Schema. An
example of a label/value pair is Form:<form_name>.

Server
Identifies the server that will be affected by the instruction. If no server is
specified or the specified server does not exist, the mail process defaults to the
server information specified in the emaildaemon.properties file. An example
of a label/value pair is Server:<server_name>. (For more information, see
“Updating the emaildaemon.properties file” on page 189.)

114 XChapter 4—Email templates

 Remedy Email Engine Guide

Login, password, and TCP port

The User name and password used when executing the instruction. If no
values are specified, the mail process verifies whether they were defined in the
AR System Email Mailbox Configuration form. You can configure exactly
how the User name is to be determined for an incoming email with some
instructions:
„ Set a security key in the AR System Email Security Form. You must add
Key: <security_key> to the email.
„ Use the supplied user information: user login name, password, possible
authentication, possible language, possible RPC, and possible TCP inside
the email using the appropriate labels and values.
„ Use the sender’s email address: The Remedy Email Engine will search
through the User form for the appropriate user name by searching for the
email address. It will use the first user it finds whose email address
corresponds.

The passwords and security keys will be encrypted in the AR System Email
Messages form. The aliases for Login are User, User Name, Name, and Login
Name. The alias for TCP Port is TCP.

Note: If you try to send an email in an HTML template, do not use a colon in
the Login, for example, Login: <input type="text" name="!536870918"
size=50/>. Use the format Login <input type="text" name="!536870918"
size=50/> instead. With this format, the email engine can parse correctly
that Login is a label for a field on the form and not an instruction.

RPC number and authentication

Defines the RPC number for the destination server (usually involved when
the user is connecting to private servers), and the name of the external
authentication service that is used to authenticate the user. These values are
the same as those used when logging in to the AR System server. The alias for
RPC Number is RPC.

Language
Defines the locale used when logging in to the AR System server. If no
language is specified, the default values are used. The values are the same as
they are in the Remedy Administrator and AR System clients. The format of
this label/value pair is Language:<language>, for example, Language:en_US.

Labels and values used in the templates W 115

Action Request System 6.0

Actions
Defines the operation to perform on a specific AR System form. The Action
label and corresponding value are required in the incoming email so that the
Parser can generate valid instructions. Valid actions are Submit, Query,
Modify, and a user-defined value. If no value is given for the label, the email
will only be logged and no actual execution will take place. An alias for Action
is Instruction.

Valid values for this label are in Table 4-1, and explained in more detail after
the table.
Table 4-1: Values applied to AR System action labels

Value Description
Submit Submits a new entry on a specific
AR System form. This is valid within any
incoming email. The syntax is
Action:Submit.
Query Searches for entries on a specific
AR System form. The syntax is
Action:Query.
Modify Modifies a specific entry contained within
a specific AR System form. This is only
valid in reply emails (that is, emails that
have been sent to the user from an
AR System server). The syntax is
Action:Modify.
User Defined An instruction defined by the
administrator. The syntax is
Action:<admin_defined text>.

„ Submit Action—By using this action in an email, users can enter values
for field labels, and submit a new record. You can see an examples of a
template with a Submit action on page 130 and in “Email content
template containing basic actions” on page 213.

116 XChapter 4—Email templates

 Remedy Email Engine Guide

„ Query Action—If a search request (or query) returns more than one
match, the beginning of the message indicates the total number of matches
found. You can configure a limit to how many matches are returned; the
maximum number of matches allowed is returned in the message. If a
request exceeds the configured search match limit, an additional message
is provided that indicates what the limit is. See the Configuring AR System
guide for information on configuring limits.
For sample templates with Search (Query) actions, see “Modifying
templates for search actions with the Remedy Email Engine” on page 202.
„ Modify Action—This action enables you to modify existing entries, but
due to the nature of this command and the security implications, the
command may be executed only under the following conditions:
„ The message containing the modify action must be sent from an email
account that will also be used by the email engine to return a response.
This email account must be used by the email engine as both an
Outgoing Mailbox as well as an Incoming Mailbox. That is, an
AR System user sent an email containing the Modify action to another
user. Then the recipient modified certain values in the email and
replied back to the original sender.
„ The user only changed field values and did not add new actions, or
modify existing actions when replying to the email that contained the
modify action.
„ Either the sender or the user of the email supplied a valid Security Key.
Note: Do not modify the Password field (field ID 102).

The Remedy Email Engine will insert a special label and value into the
email if the email contains a modify action. The mailbox must also be
configured to allow modifications. See the Advanced Configuration
instructions (step 1 on page 88) for where to set this. This special label and
value pair is defined as follows:
##Modify##:[$$the encrypted information$$]
The encrypted value contains information, which the Remedy Email
Engine uses to determine the following items:
„ The Request ID of the email being sent.
„ The AR System server to which the email was submitted.
„ The email was originally sent from the same mailbox and from the same
AR System server as that of the recipient.

Labels and values used in the templates W 117

Action Request System 6.0

„ The checksum of all the Modify actions where the checksum is

calculated based on the Request ID, Form Name, and Server Name
referenced in the Action block of the template.
„ The user did not modify any of the existing actions, Form Names,
Server Names, or Request IDs and they only modified possible field
values.

For an example of a modify action and more information, see “To

perform the modify action using an email template:” on page 206.
„ User-Defined Instruction (Action)—This is a text string that has been
determined by the Administrator and used as a value for an Action label.
A user-defined value can consist of any text, as long as it is defined in the
AR System Email User Instruction Templates form for user-defined
instructions. See “User-Defined instruction templates” on page 138, for
more information.

Format
For Query, Submit, and Modify actions, you can specify that requested
information be formatted in full or short form by entering Full or Short after
this keyword. An example of a label/value pair is Format:Full.
The Full format lists the information for all accessible fields, with each entry
separated by a line of hyphens.
The Short format returns only the fields defined in the results list. If no fields
are defined for the results list, it returns the Short Description field.
In Submit and Modify actions, only use the Format label if the advanced
configuration setting Reply with Entry is set to Yes for the incoming mailbox.
For Query, the default format is Short. All matching requests are listed in the
body of the response, one after another.

Qualification
This label and its value are required only for a query-based instruction. The
value can be any properly formatted search. All of the restrictions that apply
to the Advanced Search bar in Remedy User apply when performed through
email. The following is an example:

Qualification: 'Source' = "Phone" OR 'Source' = "email"

A null value will be treated as if it is a “return all records” query,

such as 1 = 1. Aliases for this label are Query and Search.

118 XChapter 4—Email templates

 Remedy Email Engine Guide

Result template
Defines the template to use when replying to an incoming email containing
query instructions. The template is usually associated with a particular form.
This template consists of label/value pairs and variables (see “Variables” on
page 122 for more information) that correspond to AR System fields on the
AR System form being queried. These variables are replaced by the data
found on the AR System form based on the instruction being executed. The
value given for this Result Template label is the name or the Request ID of
the template contained in the AR System Email Template form. When the
Remedy Email Engine receives this label and value, it will retrieve the
template file and use it as required. Aliases for this label are Result and
ResultTemplate. An example of a label/value pair is
Result:<result_template_name>.

Status template
The name of the template to use when Status information is returned. The
template consists of label/value pairs and variables that are replaced with
relevant data. These variables correspond to the Status information returned
if any errors occurred while executing one of the instructions; they make use
of reserved words (see “Reserved variables” on page 126 for more
information). This template does not have to be related to a particular form;
the variables are specific to status information and therefore can be used for
any instruction on any form.The value given for the Status Template label is
the name or Request ID of the template contained on the AR System Email
Template form. When the Remedy Email Engine receives this label/value
pair, it will retrieve the template and use it as required. Aliases for this label
are Status and StatusTemplate. An example of a label/value pair is
StatusTemplate:status_template_name.

Labels and values used in the templates W 119

Action Request System 6.0

Header template and footer template

The templates are used in the creation of outgoing email where the header is
inserted at the beginning of the email and the footer is inserted at the end of
the email. If the templates are used, however, within a Query action block—
that is, after an Action: Query label/value pair—then the header or footer, or
both, are inserted before, or after, or both before and after, each entry that is
retrieved when the action is executed. In this way, entries are clearly
separated from each other. The Header and Footer templates typically
contain basic text, or they could be HTML documents with logos and
graphics, or decorative typefaces. The value given for this label is the name or
Request ID of a template contained on the AR System Email Template form.
When the Remedy Email Engine receives this label/value pair, it will retrieve
the template and use it as required. The label/value pair method is used when
requesting results from a server by way of email. You can also add a header
or footer template to an outgoing email by selecting it in the relevant field of
the Templates tab of the AR System Email Messages form for an outgoing
message. Aliases for the Header Template are Header and HeaderTemplate;
aliases for the Footer Template are Footer and FooterTemplate. An example
of a label/value pair is HeaderTemplate:header_template_name.

!Name! or !ID!
This label indicates an AR System field or the value of a specific variable. The
exclamation marks are required to surround the field name or the ID
number. For example, field ID 8 is !8!. A colon (:) is placed after the second
exclamation point as a delimiter, for example:

!8! : Short description information

Blanks are acceptable. If any characters other than digits and spaces are
between the exclamation points, the reference is not recognized as a field ID.

The argument to the ID/name label should be of the same datatype as that of
the field (datatype information need not be included explicitly as the parser
will determine the appropriate datatype of the field by default). If this is a
query action, and the argument is of a different datatype than defined for this
field, an error will be generated.

120 XChapter 4—Email templates

 Remedy Email Engine Guide

Labels for fields need not be present in any specific order within an email
message. You may precede the field name/id label with any text that you wish
to include. This text will not be parsed by the email engine. It is common
practice to include the actual field name is this way:

Submitter !2!: $USER$

In the above example, the text "Submitter" will be treated as regular text by
the email engine. The field id "!2!" will be parsed and the variable $USER$ will
be the value used for any submit or query action that may have been
specified.

Only fields that have values are used in the request. Fields that do not have
values are ignored.

If you want to specify the Request ID for join forms, use the Request IDs of
the forms referenced by the join form separated by a vertical bar. For
example, a join form Request ID might appear as TT000567|TT000890.

Key
The key label and value pair is not required for the instruction to work; If
your incoming mailbox is configured to require a security key (see “Creating
email security keys for incoming mail” on page 100), then the Key label must
be present in the incoming email message. The passwords and security keys
will be encrypted in the AR System Email Messages form. A key is required
for the Modify action. Aliases for the Key label are Encryption Key and
Encryption. An example of a label/value pair is:

Key:test_key

Request ID
This label is only valid for the Modify action and defines the Request ID or
Entry ID of an entry on the corresponding form against which the Modify
action is to be executed. The Request ID is required for a Modify action as it
serves to identify the specific form entry you wish to modify. Aliases for the
Request ID are Entry ID, EntryID, and RequestID. An example of a label/
value pair is RequestID:0000012345.

Labels and values used in the templates W 121

Action Request System 6.0

Global and local parameter declarations

Any parameter (that is, anything that is not an Action) defined in the email
before an Action label is regarded as global and applies to all the actions
within the email. Thus, you do not have to repeat parameters, such as login
information or form names, for each and every instruction. If the parameter
is defined again after an action statement, then that parameter takes
precedence over the global parameter for that action only. For an example of
this, see “Email content template containing basic actions” on page 213.

Variables
Variables are used only with templates that are to be used as User Instruction
templates for incoming emails or as content templates for new outgoing
emails. They are placeholders that are replaced by specific values defined
when:

„ The user instruction is executed and where the values are defined by a user
sending the email executing this user instruction.
„ The template for new outgoing emails is used as a content template. The
variables are defined by:
„ A qualification and form where the data of the fields specify the variable
values.
„ Field Values field where the variables are defined.

Variables can be used in place of values in the label/value pairs in templates.

The variable is replaced by a value at execution time.

The variable value is determined for outgoing emails in the following order:

1 If you supply an attachment in the Values attachment field of the Attachment

Alternatives tab of the AR System Email Messages form, the attachment will
be used to determine the values for variables contained in the template. See
“To add an attachment alternative:” on page 161 for more information on
how to do this.
2 If you did not supply an attachment in the Values attachment field, but
supplied information in Field Values, or obtained a value using a
qualification in the Qualification field of the Variable Replacement tab of the
AR System Email Messages form, the information will be used to determine
values for variables contained in the template. See the Variable Replacement
tab on page 158 for more information.

122 XChapter 4—Email templates

 Remedy Email Engine Guide

3 If you did not supply field values, but your content template contained a
query to obtain information to substitute in the email, the query information
will be used to generate the message. For query information to be used, a
form, server, and qualification must be supplied. If any one of these items is
missing, the message creation will fail.

The use of variables allows the administrator to create generic templates.

The variable is defined as follows:

#$$variable_name$$#

When used in a label/value format:

Label:[$$#$$Value$$#$$]

See “Basic format” on page 127 for more information on label/value formats.

The name of the variable may be the same as an AR System field and so there
are no restrictions if used in the context of an AR System form. This allows
you to use existing AR System field values to define the value of a variable.
The variable value is retrieved from the same !Field ID! label as that of
AR System fields so the variable name might also be the name or ID of an
existing AR System field.

In content templates used for outgoing emails, variables for field values must
use the field database name, not the field ID. See “Using variables with
notifications” on page 124 for examples.

Example of a field value used as a variable in a Query or Qualification:

Query:[$$’Last Modified By’ = “User” AND ‘Modified Date’ >

“#$$modified_date$$#”$$]

Inside the same template or defined in the instruction template received by

way of the email, this variable could be associated with a value as follows:

!modified_date!:[$$21/01/2004$$]

Note: You cannot use keywords in content templates for outgoing emails in
notifications.

Labels and values used in the templates W 123

Action Request System 6.0

After the parser has extracted all the required information, the variable is
replaced with the appropriate value, resulting in a query as follows:

Query:[$$’Last Modified By’ = “User” AND ‘Modified Date’ > “21/01/

2004”$$]

Note: Variables can only be used for form field values and qualifications. In
addition, they do not work for Login or Server labels. For example, the
variable Login: #$$Joe User$$# would not be correctly parsed by the email
engine and would return an unknown user error. Also, only local fields
(fields after the Action label) can be substituted. Global fields (fields
before the Action label) cannot be substituted. Finally, labels like Server,
Schema, Login, Password, or Key are considered to be global and cannot
be substituted.

Using variables with notifications

When creating templates to be filled in using notifications, the template
variables for field values must use the field name as the variable name, not the
field ID. This is because the server uses the field name (database name) to
assign the values in the AR System Email Messages form.

For example, if the user has a template to mail out the user information
through a notification that looks like the following, it will not work for
notifications:

Login Name : #$$101$$#

Password : #$$102$$#
Group List : #$$104$$#
Full Name : #$$8$$#
Default Notify Mechanism : #$$108$$#
Email Address :#$$103$$#

To use this template in notifications, the user will have to change it so that it
looks like the following:

Login Name : #$$Login Name$$#

Password : #$$Password$$#
Group List : #$$Group List$$#
Full Name : #$$Full Name$$#
Default Notify Mechanism : #$$Default Notify Mechanism$$#
Email Address :#$$Email Address$$#

124 XChapter 4—Email templates

 Remedy Email Engine Guide

Add core fields to the template as follows:

Req Id:#$$Request ID$$#

Submitter:#$$Submitter$$#
Create Date:#$$Create Date$$#
Assigned To:#$$Assigned To$$#
Stat:#$$Status$$#
ShortDescr:#$$Short Description$$#
StatHist:#$$Status History.New.USER$$#

Note: Do not use the Request ID to return entries from display or vendor
forms in a notification. If you construct a content template using the
variable #$$Request ID$$# and use the content template in the Templates
tab of notifications on display or vendor forms, the system will not
generate errors, but it also will not return the Request IDs.

Date formats supported in email templates

Email templates support the following date and time formats.

Format Description
SHORT A numerical date that includes the numerical day, month,
and year is displayed (06/17/04). The order of each
component is based on the Regional Options properties in
the Control Panel.
MEDIUM Longer numerical date description, for example, Jan 12,
1952.
LONG An alphanumeric date that includes the day of the week,
numerical day, month, and year is displayed (for example,
Sunday, June 17, 2004). The order of each component is
based on the Regional Options properties in the Control
Panel.
FULL Completely specified numerical date description, for
example, Tuesday, April 12, 1952 AD.

You cannot mix the different locales for short and long formats. So in the
countries where the valid value is mm/dd/yy, dd/mm/yy is not valid and will
not work, especially when the dd part is greater than 12. You can see
examples of valid date format values when you open Regional Options on
your Control Panel for long and short dates.

Labels and values used in the templates W 125

Action Request System 6.0

Consequently, depending on your locale, 31/01/03 will work as a short date

if your locale is set to dd/mm/yy, not mm/dd/yy. The format 31-Jan-03 will
not work, but you can use Jan 31, 2003 or January 31, 2003.

Reserved variables
Reserved variables are used by the Remedy Email Engine to place the results
of executing an email. You can use them in Result and Status templates, but
not in Content templates. Reserved variables fall under two main categories:
„ Action information—the following formats are valid:
„ #$$Action.Name$$# The action value, such as Submit, Query, and so on.
„ #$$Action.Number$$# The position of the action within the entire
execution list.
„ #$$Action.Form$$# The name of the AR System form involved in this
action.
„ #$$Action.Query$$# The qualification (if any) associated with the
instruction. (This reserved variable is valid only for User Defined
Instruction templates.)
These variables are useful when creating a template that will contain the
results of executing the associated action. They may be defined in a Result
template along with variables that define the fields of a specific form. The
execution module will replace these variables with the correct values
before the results are returned to the sender of the email containing the
actions.

„ Status information—Used to store the results of system-generated errors.

The following formats are valid:
„ #$$ActionStatus.Number$$# The error or warning number.
„ #$$ActionStatus.Type$$# The type of error, such as Severe, Error,
Warning.
„ #$$ActionStatus.Text$$# The message text.
„ #$$ActionStatus.AppendedText$$# The associated appended text.
These are also values that you would define in a Status template; they are
common to all forms.

126 XChapter 4—Email templates

 Remedy Email Engine Guide

If you want to use specific Status History information in the templates, the
following rules apply:
„ You must use the fully qualified status history name, for example
“Status-History.New.USER,” or “Status-History.New.TIME.”
„ You can also use numeric values, for example “15.0.USER,” “Status-
History.0.USER,” or “15.New.USER.”
„ The USER and TIME identifiers are case sensitive.

Label and value formats

There are specific ways in which labels and values are written within an email
so that the Parser can extract the required information. Each of the formats
can be used in plain text, HTML, or rich text documents. The Parser parses
through the documents using all three types of formats. It also keeps the
sequence if the user decides to mix the formats in one document.

Basic format
This format is the simplest. The labels and associated values are written as
follows:

Label:[$$Value$$]

The opening and closing $$ enable the Parser to extract the value from the
email, including situations where the value incorporates multiple lines. If the
value does not incorporate multiple lines, the label/value pair can be written
as follows:

Label:Value

The label and value do not have to be left justified, and can be prefaced by
text on the same line. You do not have to surround the label with any special
characters as the labels are fixed and do not vary, unlike the values.

A variable is written as follows:

#$$variable_name$$#

When used in a label/value format:

Label:[$$#$$variable_name_Value$$#$$]

Labels and values used in the templates W 127

Action Request System 6.0

XML format
XML format can be used in all four types of documents: plain text, HTML,
XML, or rich text. The format is as follows:
<Label>Value</Label>

AR System fields are treated differently. The format is as follows:

<Field ID=”!Field_ID!”>Field Value</Field>

or
<Field Name=”!Field_Name!”>Field Value</Field>

Variables are referenced as #$$variable_name$$# as in the Basic format.

HTML format
The four major HTML field types are:
„ Text fields
„ Radio buttons
„ Check buttons
„ Menu field

These types have a fixed format in HTML; you can use this format in a plain
text document, where the HTML source for the field type may be added in
the plain text email, as well as HTML. In HTML, however, an editor will
automatically generate the correct format when filling in any missing field
values. You can still use the basic format within the HTML document. The
corresponding fields can be used in situations where input is required from
the user. The Email Client must allow or support the ability to edit HTML
fields directly, such an example would be Microsoft Outlook when it is
configured to edit emails with Microsoft Word.

The name tag represents the label and the value tag represents the value.

Text field
In HTML, a text field will typically look as follows:

<input type=”text” name=”Label” size=”20” value =”Value”>

This represents a text field into which data can be typed so it easily represents
a Label Value pair. The name tag contains a label, such as Action, and the
value tag will contain a corresponding value, such as Query.

128 XChapter 4—Email templates

 Remedy Email Engine Guide

Radio buttons
These allow you to design a document where the user can select from a given
range of possibilities. Unlike a text field where only one set of tags between
the <> markers represent a Label and Value pair, radio buttons can contain
several sets of tags that comprise one instruction label and several values. An
example follows:
<input type=”radio” value =”Submit” checked name=”Action” >
<input type=”radio” value =”Query” name=”Action”>

This represents two radio buttons grouped together under the name Action.
The values for the radio buttons would be Submit and Query. The selected
value being determined by the word “checked.” The resulting label/value pair
would be Action:Submit.

Check buttons
Check buttons allow you to design a document where there are several
possibilities, but those possibilities are not grouped together. An example
follows:

<input type=”checkbox” name=”Label” value =”Value”>

or

<input type=”checkbox” name=”Label” value =”Value” checked>

In the first example, the label and value will not be used because the word
“checked” is not included in the definition. But in the second example, the
label and value will be used because the box has been checked.

This field can give the user the ability to select the parameters that are valid
and those that are not.

Menu field
The menu field acts as a selection box where you will be able to create a label
from which any specific value can be selected from a range. In the following
example, the Action label has possible values of Modify, Submit, and Query.

<select size=”1” name=”Action”>

<option value=”Modify”>Modify the entry</option>
<option selected value=”Submit”>Submit the entry</option>
<option value=”Query”>Query the entry</option>
</select>

Labels and values used in the templates W 129

Action Request System 6.0

The type is a select HTML field, the label is Action and the values are Modify,
Submit, and Query. The label/value pair to be used is determined by the tag
containing the word “selected.”

This field also allows the user to specify different visible text in the field with
the correct field values defined underneath.

Additional points when creating or modifying templates

„ Comments are optional. Because the Remedy Email Engine ignores any
lines that do not contain a valid label and value pair, you do not have to
add a # to comments.
„ Diary fields and character fields with a maximum length of over 50
characters can use multiple lines of text.
„ If the user does not enter a value into a field that has a default value
defined, then the default value is loaded. If the user does not enter a value
into a required field and there is no default value defined for it, an error
will result.
„ Values can be entered anywhere after the delimiting character. Leading
and trailing blanks are ignored when a value is read by the Remedy Email
Engine.

The following is an example of a completed template, ready to be saved and

attached to an email. Enter the text shown in bold type.

File exported Tue May 14 9:48:22 2004

Schema: TroubleTicket
Server: ourserver
Login: Chris Cadre
Password: <password>

Action: Submit
Short-Description! 8!:No access to the print server
Description! 9!:Whenever I send a file to the print server, I get a
message that says “unknown host print.”
Impact!108!:Serious
Values: Low, Medium, Serious, Critical
Submitter! 2!:Chris Cadre
Notify-submitter-method! 12!:E-mail
Values: None, Notifier, E-mail
Keywords!295!:Printer

130 XChapter 4—Email templates

 Remedy Email Engine Guide

Storing templates in the AR System Email Templates

form
When you create or export templates, they must be stored in the AR System
Email Templates form to be used recurrently in emails.

Figure 4-7: AR System Email Templates form

X To add a template to the AR System email templates form:

1 Create or export your template.
2 Open the AR System Email Templates form in an AR System client.
3 Click the Template Information tab.
4 Select the template format from the Template Format list, either Text or
HTML.
5 Specify the Encoding so that the Remedy Email Engine can parse the
templates. If you leave the encoding field empty, the default encoding of the
local system is employed.

Storing templates in the AR System Email Templates form W 131

Action Request System 6.0

6 Enter an optional description. It is useful to enter a description indicative of

the function of the template.
7 Right-click in the attachment pool.
8 Select Add from the content list.
The Add Attachment dialog box appears.
9 Browse to the template file you want to add and select it.
10 Click Open.
The file is added to the list of attachments in the Email Templates form. You
can also click and drag a template to the attachment pool on the AR System
Email Templates form if you are using a Windows system.
11 Select the item in the attachment pool, then click the edit button in the
Template Name field.
The name of the attachment is displayed in the Template Name field. For
example:
template_attachment1.htm.

You can edit the file name, for example, to template1.htm.

12 Click Save.

The system will assign a Template ID number to the template. (The Template
ID field is hidden.)

If the template contains a reference to a graphic file, you need to add the
graphic file as an attachment. Refer to the following section for information.

Adding attachments to templates

The AR System Email Attachments form is used to ensure that a specific
attachment is always included with any message that makes use of a specific
template. You can add graphics to HTML templates using this form. This is
particularly useful for header templates if you want to add a company logo to
the header information in your email.

1 Open the AR System Email Templates form in the AR System User tool.
2 From the Template Format menu, choose HTML.
This activates the buttons on the Template Attachments tab to add
attachments to your template.

132 XChapter 4—Email templates

 Remedy Email Engine Guide

3 Add a template file as an attachment.

4 Click Save.
5 Click the Template Attachments tab.

Add
Attachment
button

Figure 4-8: AR System Email Templates form: Template Attachments tab

6 Click the Add Attachment button.

Adding attachments to templates W 133

Action Request System 6.0

The AR System Email Attachments form opens as shown in the following

figure.

Select Template
as the
attachment
Type

Attachment pool

Figure 4-9: AR System Email Attachments form for templates

7 Select Template from the Type list.

8 Right-click in the attachment pool.
9 Select Add from the context list.
The Add Attachment dialog box appears.
10 Browse to the file you want to add and select it.
11 Click Open.
The file is added to the list of attachments on the AR System Email
Attachments form.
If you are using a Windows system, you can also click and drag an attachment
to the attachment pool on the AR System Email Attachments form.
12 Select the item in the attachment pool, then click the edit button in the
Attachment Name field.
The name of template attachment is displayed. For example:
template_attachment1.htm

You can edit the file name, for example, to template1.htm

13 Click Save.
The AR System Email Attachments form closes.

134 XChapter 4—Email templates

 Remedy Email Engine Guide

14 Your attachment will be added to the list in the AR System Email Templates
form. You may need to right-click and select Refresh to see the attachment
listed.
15 Click Save in the AR System Email Templates form.

The email engine will give the template attachment an ID. (The Attachment
ID field is hidden.)

Adding a previously saved attachment to your template

In the Template Attachments tab of the AR System Email Templates form:
1 Click the arrow next to the blank field at the bottom of the pane.
2 Select the attachment.
3 Click the Add Existing button.
Your attachment will be added to the list in the attachment pool.
4 Click Save.

Modifying an attachment
1 Click the Templates Attachments tab in the AR System Email Templates
form.
2 Select the attachment you want to modify.
3 Click the Modify Attachment button. The AR System Email Attachments
form opens (see Figure 4-9 on page 134).
4 Click Search to locate the attachment.
5 The attachment appears on the attachment list.
6 Modify as required. You can modify the Attachment Name.
7 Click Save to save your modification.

Adding attachments to templates W 135

Action Request System 6.0

Deleting an attachment
1 Click the Attachments tab in the AR System Email Templates form.
2 Select the attachment you want to delete.
3 Click Delete Attachment.
The AR System Email Association form opens.
4 Close this form.
5 Click the Refresh Table button to refresh the table in the Attachments tab of
the AR System Email Templates form.
The attachment will be deleted from the list.

Exporting templates with attachments to another server

To export an HTML template from one server and then import the template
onto another server, you must do the following:

X To export templates with attachments to another server:

1 Export the HTML template from the AR System Email Templates form on
the source server.
2 Import the template into the AR System Email Templates form on the target
server.
3 Copy the attachments associated with the template from the source server.
4 Manually add the attachments to the template in the AR System Email
Templates form on the target server.

Setting default templates for specific outgoing mailboxes

An outgoing mailbox can be configured to use default templates. This
includes a default header, footer, content, results, or status template. Only
one default template of each type can be specified for a mailbox. You can
choose to configure your mailbox to use defaults in one or more of the above
categories, for example, you may choose to specify a default header and
footer template but no content template.

136 XChapter 4—Email templates

 Remedy Email Engine Guide

When you set default templates for a specific outgoing mailbox, these
templates are used for this mailbox when no other templates are specified.
Use the AR System Email Mailbox Configuration form—enter the name of
the mailbox in the Mailbox Name field and the names of the templates in the
Default Templates fields on the Advanced Configuration tab, as shown in
Figure 4-10 on page 137.

These Default Templates fields are only displayed for outgoing mailboxes.
See the following figure and “Working with the mailbox configuration form”
on page 75 for more information on configuring mailboxes.

Figure 4-10: Setting default templates in the AR System Email Configuration form

The templates must already be stored in the AR System Email Templates

form.

Adding attachments to templates W 137

Action Request System 6.0

User-Defined instruction templates

User-Defined Instruction templates enable you to associate a template (a
User-Defined Instruction template) with an incoming email by way of an
entry in the AR System Email User Instruction Templates form.

Send Email
3 with User-Defined
Instruction

Outgoing
SMTP MAPI
Incoming
2 Create Entry User
Email
Server MAPI POP3 MBOX IMAP4

AR System Email Engine

AR
Server
Primary
Config-
uration

4 Results

Underlying
Database
Create and Store
1 Email Templates

Figure 4-11: Overview for using instruction templates

138 XChapter 4—Email templates

 Remedy Email Engine Guide

The User sends an email containing an Action label and a value for the Action
that corresponds to an entry in the AR System Email User Instruction
Templates form. The entry in this form is associated with a template which is
then executed and used in the email. Using this feature, the administrator can
set up variable substitutions to be used in an email with minimal input from
the User, for instance, the User may only send an email with an Action label/
value pair, and a variable value. An example follows on page 140.

Creating User-Defined Instruction templates involves the following tasks:

Step 1 Create a template (a User-Defined Instruction template) that contains one or
more instructions and variables. Add the template to the AR System Email
Templates form.

Step 2 Create the following entries in the AR System Email User Instruction
Templates form (see Figure 4-12 on page 140):

„ Enter a valid character string into the Instruction field on this form.
„ Associate the User Instruction Template form with the template you
created by filling in the name of the template in the Template Name
field.

Step 3 Send the email that contains the user-defined instruction to the email server.

Step 4 This user-defined instruction is used or executed when an email is received

by the Remedy Email Engine containing an Action label and a value
corresponding to the valid character string in the Instruction field of the
Email User Instruction Templates form. The value for the variable that
appears after the Action label is then extracted from the email and used to
replace the variable defined in the template. This template is then executed.

User-Defined instruction templates W 139

Action Request System 6.0

You can associate more than one user-defined instruction with a template
containing one or more instructions. The User-Defined Instruction template
looks exactly the same as any other template.

Figure 4-12: AR System User Instruction Templates form

X To create an instruction template:

This example assumes you have created records relating to creating urgent
helpdesk incidents. (See “Email configuration” on page 73 for more
information on how to configure your email system.)
1 Create a template (a User-Defined Instruction template) containing one or
more instructions or actions. See “Creating templates” on page 110 for more
information. The one in this example has been exported using Remedy
Administrator.

140 XChapter 4—Email templates

 Remedy Email Engine Guide

In this example, the template is called IN_Install_AllUrgent, the server in this

example is called mobile1, but substitute your own server name.

Figure 4-13: User-Defined instruction template

This template includes a special header template used with urgent help desk
requests and the default result template.

User-Defined instruction templates W 141

Action Request System 6.0

2 Add your template to the AR System Email Templates form in Remedy User.
(See “To add a template to the AR System email templates form:” on
page 131.)

Figure 4-14: Storing template

Here we created and stored a template, UrgentRequests.

3 Open the AR System Email User Instruction Templates form.
The system will enter the unique ID for the user-defined instruction in the
Instruction Template ID field when you save the instruction.

142 XChapter 4—Email templates

 Remedy Email Engine Guide

4 Enter the name of the template (the User-Defined Instruction template)

containing the instructions (or actions) in the Template Name field, in our
example, UrgentRequests. This template must previously have been added to
the AR System Email Templates form, as in step 2. You can also select it from
the drop-down list of available templates.

Figure 4-15: Creating an entry—User Instruction Template form

5 To restrict the user-defined instruction to one incoming mailbox, enter the

name of your mailbox in the Mailbox Name field, or select from the list.
6 Enter a value for the Instruction field. This is the value that will be used to
identify this template when used in an incoming email, as shown in our
example, Urgent.
7 Save the AR System Email User Instruction Templates form.
8 Send an email using an email application, such as Outlook, containing an
Action label and value equal to the string defined in the Instruction field in
the AR System Email User Instruction Templates form (Urgent), and any
values for the variables. In our example, the email would consist of the
following:
Action: Urgent

User-Defined instruction templates W 143

Action Request System 6.0

The Remedy Email Engine will then retrieve all records of urgent help desk
requests and list them in the email.

Figure 4-16: Email response to User-Defined instruction template

The Remedy Email Engine processes a user-defined instruction after

receiving an incoming email as follows;
„ Retrieves the associated user-defined instruction entry from the
AR System Email User Instruction Templates form and determines which
template is associated with the instruction.
„ Retrieves the associated template from the AR System Email Templates
form.
„ Replaces the variables in the template with the values defined by the
information in the email.
„ Executes the resulting template.

144 XChapter 4—Email templates

 Remedy Email Engine Guide

Preparing email templates after an upgrade

To use your old email templates after an upgrade to the 6.0 email engine, do
the following:

1 Verify the following settings in the Remedy Mailbox Configuration form:

„ Incoming mailbox is Enabled.
„ Email Action for your incoming mailbox is set to Parse.
„ If you want to use your original templates for your incoming mailbox “as
is” without using the 6.0 email template features, make sure Use Original
Template Format is set to Yes.
„ Use Supplied User Information field is set to Yes.
2 If only one form is used for email submissions, set the Default Workflow
Form to that form name.
3 To guarantee that no other form is used for email submissions, set Force
Default Workflow Form to Yes.
4 If the original templates do not include a user name, user password, or form
name, do one of the following:
„ Modify the template to include these parameters and values.
„ Create a template that includes one or more of these values with a user
instruction. For more information, see “User-Defined instruction
templates” on page 138.
„ If additional configuration parameters are used, remember that Reply
With Result set to Yes will send a reply to the sender on a successful or
failed result.

Preparing email templates after an upgrade W 145

Action Request System 6.0

146 XChapter 4—Email templates

Chapter

5 Messages and notifications

This chapter provides information and instructions for creating and

transmitting email messages. It includes the following sections:
„ Overview (page 148)
„ Sending an outgoing email using the Messages form (page 149)
„ Sending an email to the AR System (page 162)
„ Using email to query the AR System (page 166)
„ Email notifications (page 169)

Messages and notifications W 147

Action Request System 6.0

Overview
Email messages can be either outgoing or incoming. Both types of emails use
Label Value pairs as message content; the Remedy Email Engine ignores any
other text.
„ Outgoing emails are sent using the AR System Email Messages form. You
can type the message, or specify templates to use in the body of the email.
See “Sending an outgoing email using the Messages form” on page 149 for
more instructions on using the AR System Email Messages form.
„ Incoming emails are those received by the AR System and can be sent
using an external email client, or an AR System configured mailbox. If you
use a third-party email client, the message is typed in the body of the email
and you can specify a template to use for the results list or to report status.
See “Sending an email to the AR System” on page 162 for more
information.

148 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

Sending an outgoing email using the Messages form

You can send an outgoing email using the AR System Email Messages form.
You can also include attachments with your email using the Attachments tab.
From the Advanced Options tab (see “Displaying advanced options” on
page 156), you can use a template, substitute variables, or use an alternate
attachment as your body content. You will receive a confirmation if your
submission is successful, or you will receive a message identifying any errors
if the submission is rejected. An AR System Email Messages form is shown in
the following figure.

Figure 5-1: AR System Email Messages form

Sending an outgoing email using the Messages form W 149

Action Request System 6.0

Default mailbox
If you do not specify a mailbox for your email message, the settings for the
default mailbox are used. The default outgoing mailbox is the first mailbox
created, or another mailbox specified as your default outgoing mailbox in the
AR System Email Mailbox Configuration form. Set the Default Outgoing
Mailbox field of the AR System Email Mailbox Configuration form to Yes, as
shown in the following figure. The setting in this field for any previous
default mailbox is reset to No. For more information on configuring
mailboxes, see “Working with the mailbox configuration form” on page 75.

Set Default
Outgoing
Mailbox

Figure 5-2: Setting default outgoing mailbox

X To send outgoing email:

1 Open the AR System Email Messages form in either a web client or Remedy
User.
2 Enter your Mailbox Name, or select from the list to specify a mailbox to use
for your email message.
The settings in the AR System Email Mailbox Configuration form for the
specified mailbox will be used, unless overridden by entries in the AR System
Email Messages form. If you leave this field empty, the default outgoing
mailbox will be used (see “Default mailbox” preceding).
3 Select Outgoing from the Message Type list.

150 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

4 Click the Message tab and fill in the header information.

The From, Reply To, Organization, To, CC, and BCC fields will be populated
automatically when you enter the mailbox name if they have been configured
in the AR System Email Mailbox Configuration form. You can override these
settings here.
5 Enter a subject line for your email in the Subject field.
6 Enter a priority number in the Priority field.
Use the following to determine what value to use in the email message within
Remedy in order to get the desired MS Outlook priority. Numbers from 1 to
100 are acceptable.

Email Engine Priority MS Outlook Priority

0 Normal
1 High importance
2 High importance
3 Normal
4 Low importance
5 Low importance
6 Low importance
7 Low importance
8 Low importance
9 Low importance
10 Low importance
...
100 Low importance

By default, emails are sent out from the email engine in the order they were
received, not in the order of priority. But you can set properties in the
EmailDaemon.properties file for the email engine to send high priority emails
first and then lower priority in that order. Use the following properties:
„ To ignore priority (default):
com.remedy.arsys.emaildaemon.SortMessages=false

„ To use the priority:

com.remedy.arsys.emaildaemon.SortMessages=true

For more information on using the EmailDaemon.properties file, see

“Performance and configuration settings” on page 191.

Sending an outgoing email using the Messages form W 151

Action Request System 6.0

7 Click the tab for the appropriate message format, either Plain Text or HTML.
8 Type your message in the Body pane.
You can use either HTML, plain text, or both in your email content.
„ To add an attachment, see “Adding attachments to your email” on
page 152.
„ To send the email with a template other than the default templates for the
specified mailbox, see “Adding a template to an email” on page 157.
„ To add an attachment alternative to be used for the content of your email
instead of typing content in the body panes, or using a template, see “To
add an attachment alternative:” on page 161.

9 Click Send.
You can also save your email and send it later by clicking Save.

Adding attachments to your email

Attachments are sent with an email using the AR System Email Messages
form and the AR System Email Attachments form. The AR System Email
Attachments form (see Figure 5-4 on page 154) is used for storing
attachments for both incoming and outgoing emails. It also stores
attachments for templates, such as a graphic for an HTML template. The
system associates the attachment with a specific email in the AR System
Email Association form.

152 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

X To add attachments to your email:

1 In the AR System Email Messages form, click the Attachments tab.
The Attachments tab is displayed in the following figure:

Figure 5-3: AR System Email Messages form—Attachments tab

Sending an outgoing email using the Messages form W 153

Action Request System 6.0

2 Click Add Attachment.

The AR System Email Attachments form appears as shown in the following
figure.

Attachment pool

Figure 5-4: AR System Email Attachments form

The system will enter a unique ID for the attachment in the Attachment ID
field when you click Save in the AR System Email Attachments form. (The
Attachment ID field is hidden.)
3 Select Email from the Type list.
4 Enter a name for the Attachment in the Attachment Name field. If you don’t
specify a name, the system will refer to the attachment by its filename and
location.
5 Right-click in the attachment pool.
6 Select Add from the list.
The Add Attachment dialog box appears.
7 Browse to the file you want to add and select it.
8 Click Open.
The file is added to the list of attachments. If you are using a Windows
system, you can also drag and drop a file into the attachment pool.

154 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

9 Select the item in the attachment pool, then click the edit button in the
Attachment Name field.
The name of the attachment is displayed in the Attachment Name field. For
example:
template_attachment1.htm.

You can edit the file name, for example, to template1.htm.

10 Click Save.
The AR System Email Attachments form closes.
Your attachment will be added to the list in the AR System Email Messages
form, Attachments tab. You can right-click in the attachment pool field to
select from the context list.
You can add an attachment that you have previously saved with the
AR System Email Attachments form by using the following procedure.

Adding a previously saved attachment to your email

X To add previously saved attachments to email:
1 In the Attachments tab of the AR System Email Messages form, click the
arrow next to the blank field at the bottom of the pane.
2 Select the attachment.
3 Click the Add Existing button.
Your attachment will be added to the list in the attachment pool.
When you send or save your email, the email and the attachment are
associated through the AR System Email Association form. The system will
assign the association a unique ID.

Modifying an attachment
X To modify attachments:
1 Click the Attachments tab in the AR System Email Messages form.
2 Select the attachment you want to modify.
3 Click the Modify Attachment button. The AR System Email Attachments
form opens.
4 Click Search to locate the attachment.
5 The attachment appears on the attachment list.
6 Modify as required. You can modify the Attachment Name.
7 Click Save to save your modification.

Sending an outgoing email using the Messages form W 155

Action Request System 6.0

Deleting an attachment
X To delete attachments:
1 Click the Attachments tab in the AR System Email Messages form.
2 Select the attachment you want to delete.
3 Click Delete Attachment.
The AR System Email Association form opens.
4 Close this form.
5 Click the Refresh Table button to refresh the table in the Attachments tab of
the AR System Email Messages form.
The attachment will be deleted from the list.

Displaying advanced options

To display the Advanced Options, Message Information, and Errors tabs,
select Yes in the Display Advanced Options field of the AR System Email
Message form.

Advanced options
The Templates tab enables you to include a content, header, or footer
template with your email.
„ Content templates replace the body of the email so that you do not have
to enter anything in the body tab of the AR System Email Message form.
The content may be associated with a specific form and contain the fields
and their corresponding values relating to a specific record. You can create
these templates in a text editor, or export them using Remedy
Administrator, selecting the form and the fields to be contained in the
template. Also using the template, you can specify actions to be performed
when the contents of the email are parsed by the email engine. The content
template can also contain formatting instructions.
„ Header and footer templates are often used to place lines of text or a
graphics on an outgoing message. If they are specified in content templates
as a label/value pair, they will be applied to the email reply.
All the templates must be stored in the AR System Email Templates form.

156 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

If you leave these fields blank, the system uses the default templates for the
specified mailbox in the Mailbox Name field, or it uses the default mailbox
and its settings if there is no Mailbox Name entered. The template
specified here will override those configured for the specified mailbox, or
the default mailbox. See “Default mailbox” on page 150, and “Working
with the mailbox configuration form” on page 75 for information on
configuring your mailbox.

Adding a template to an email

X To add templates to email:
1 In the AR System Email Messages form, click the Advanced Options tab.
2 Click the Templates tab.
3 Select a template from the relevant lists, or enter the name of a template as
defined in the AR System Email Templates form.

Figure 5-5: AR System Email Messages form—Advanced Options, Templates tab

Sending an outgoing email using the Messages form W 157

Action Request System 6.0

The Variable Replacement tab enables you to replace any of the variables in
the template with a value at the time of execution. This applies only to the
specific outgoing email and the templates specified in the Templates tab.

Figure 5-6: AR System Email Messages form—Advanced Options, Variable

Replacement tab

You can use the Field Values field or the Qualification field with a particular
form to retrieve required data and substitute it in the email.
„ You can enter a value for a variable in the template in the Field Values
field, for example:
If you have the following variable in your template:
#$$paid_date$$#

In the Field Values field you can enter:

!paid_date!: 05/21/02

This value will then be substituted for the variable when the email is sent
out.

158 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

„ You can also enter a qualification in the Qualification field, such as:
Qualification:[$$’account_ID’ = 123456$$]

Then, 123456 is substituted for the variable representing the value of the
account_ID field in the content template. The system will retrieve only the
record whose value in the account_ID field is 123456.
The rules for entering a qualification are the same as those in the
Qualification bar in Remedy User.
„ In the AR System Form field, you enter the name of the AR System form
to which these values apply.
„ In the AR System Server field, enter the name of the server on which the
form resides.
„ Enter any access information necessary in the AR System Server TCP Port
field and the AR System Server RPC Number field.

Another example of the Variable Replacement feature follows.

Enter a qualification in the Qualification field to search for the Request ID of

a record on which you want to perform an action. This action will be
specified in a Content template. In our example ‘Request ID’= “00000000001”
as shown in the following figure.

Figure 5-7: AR System Email Messages form—Advanced Options, Variable

Replacement tab

Sending an outgoing email using the Messages form W 159

Action Request System 6.0

The email engine searches the specified form for the record, then it
substitutes the Request ID parameter in the Content template with the
Request ID value (00000000001) found with the query.

You can also make this static in the Content template by specifying Request
ID: 00000000001 instead of the variable Request ID: [$$#$$Request ID$$#$$],
but using the Variable Replacement feature allows more flexibility.

The Attachment Alternatives tab enables you to add the content of your
email as an attachment, instead of typing it into the Body field in the Message
tab. You can use plain text, HTML, or Rich Text Format (RTF). The contents
of the attachment appear in the body of the email. You can also add variable
values in the form of an attachment file, instead of entering them in the
Variable Replacement tab, or send another email (stored in .eml format) as
an alternative attachment, and the contents of that attached email will form
the body of the outgoing email message.

Attachment field

Attachment pool

Figure 5-8: AR System Email Messages form—Advanced Options, Attachment

Alternatives

160 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

X To add an attachment alternative:

1 Select an attachment field corresponding to the contents of the attachment.
2 Drag and drop a file into the attachment field.
3 Select an encoding for the attachment or leave the field empty in order to use
the system default. The system needs to be able to read and parse the contents
of these attachments when it creates the outgoing email.

You can only attach one of each type of alternative attachment to a message
form. These attachments are stored as part of the message in the message
form.

Determining message content

When sending an email message, the message content is determined as
follows:
„ If you supply a template, the system uses this as the message body, and uses
the following rules for variables:
„ If you supply an attachment in the Values attachment field of the
Attachment Alternatives tab of the AR System Email Messages form,
the attachment will be used to determine the values for variables
contained in the template.
„ If you did not supply an attachment in the Values attachment field, but
supplied information in the Field Values or a qualification in the
Qualification field of the Variable Replacement tab of the AR System
Email Messages form, the information will be used to determine values
for variables contained in the template.
„ If you did not supply field values, but your content template contained
a query to obtain information to substitute in the email, the query
information will be used to generate the message. For query
information to be used, a form, server, and qualification must be
supplied. If any one of these items is missing, the message creation will
fail.
Note: In terms of performance, a query against another server is more
expensive than a query against the current server. If you are going to send
many emails based on information queried from another server, you
should set up an email system on another server.

„ If none of the above is true, the system uses the template as is.

Sending an outgoing email using the Messages form W 161

Action Request System 6.0

„ If you do not supply a template, but attach a file (HTML or plain text, or
both) to the Content attachment fields in the Attachment Alternatives tab
of the AR System Email Messages form, the system uses these attachments
as the content.
„ If none of the above items are supplied, the system uses the contents of the
Body fields in the Message tab of the AR System Email Messages form for
the body of the email (HTML or plain text, or both).

Message information tab

The Message Information tab records status information about the email,
such as the Message ID, the dates sent and received, and if there is any delay
in sending the message.

The Errors tab

The Errors tab enables users to view error messages if their email is not sent
correctly. If a request fails to submit, the original message is returned, along
with an error message that indicates the reason for the failure. If the
AR System server is not responding, the message is held and periodically
resubmitted until the server responds.

Sending an email to the AR System

You can send an email to a configured AR System mailbox (incoming email)
using a third-party email client. Type the label/value pairs in the body of the
email. The rules for labels, values, and variables are the same as those for
templates.

You can specify a template to be used for the reply. This may be a Status
template, a Header template, a Footer template, or a Result template. Include
the appropriate label such as “Result Template” or “Header Template” (or
their aliases), and specify the template name as the value. There is no label
“Content Template,” therefore this cannot be specified for an incoming
email. You use a Result Template label as the equivalent of the Content
template when you perform a Modify action using incoming mail. See “The
modify action” on page 206 for instructions.

See “Labels and values used in the templates” on page 113 for more
information on rules for labels, values, and variables and for information on
label aliases.

162 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

X To send email to the AR System:

1 In the AR System Administrator tool, choose Tools > Export Mail Templates
to export an email template of a form.
For more information, see “Exporting mail templates” on page 111.
2 Open the email template .arm file in a text editor.
The email template was modified slightly to add additional information to
the entry in the User form, as shown here.

Figure 5-9: Email template in text editor

3 Create a new email using any third-party mail client, for example, MS
Outlook Express.
4 Copy and paste the template information into the email and fill in any
appropriate fields.

Sending an email to the AR System W 163

Action Request System 6.0

The following is an example of an incoming email that submits a record into

the User form to create a new AR System user.

Figure 5-10: Submitting an email through mail clients

5 Send the email to the email engine’s incoming mailbox.

164 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

6 Verify you have received a reply indicating a new entry has been created. You
can also verify the newly submitted entry using a client tool, as shown here.

Figure 5-11: Reply from email engine to MS Outlook Express

You can also follow the email messages created in the AR System Email
Messages form by the email engine. If any errors are generated, you can look
them up in the AR System Email Error Logs form.

Sending an email to the AR System W 165

Action Request System 6.0

Using email to query the AR System

You can send an email query to a configured AR System mailbox (incoming
email) using a third-party email client. Type the label/value pairs in the body
of the email. The rules for labels, values, and variables are the same as those
for templates.

X To use email to query the AR System:

1 In the AR System Administrator tool, choose Tools > Export Mail Templates
to export an email template of a form.
For more information, see “Exporting mail templates” on page 111.
2 Open the email template .arm file in a text editor.
The email template was modified slightly to add additional information to
the entry in the User form, as shown here.

Figure 5-12: Email template in text editor

Tip: Test your queries in the User tool to see if they successfully return any
results. Then cut and paste the query into the email template.

3 Create a new email using any third-party mail client, for example, MS
Outlook Express.
4 Copy and paste the template information into the email and fill in any
appropriate fields.

166 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

The following is an example of an email that queries the User form for all
users that have Administrator privileges.

Figure 5-13: Using email client to query the AR System

5 Send the email to the email engine’s incoming mailbox.

Using email to query the AR System W 167

Action Request System 6.0

6 Verify in the client tool that you have received a reply that lists the results
returned from your query (if any), as shown here.

Figure 5-14: Reply from email engine to MS Outlook Express

You can also follow the email messages created in the AR System Email
Messages form by the email engine. If any errors are generated, you can look
them up in the AR System Email Messages form.

168 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

Email notifications
If you choose Email when creating a Notify filter or escalation, you can send
the following types of information in an email notification:
„ Text messages
„ Contents of selected fields (provided the user being notified has the
appropriate permission for those fields)
„ Attachments (if an attachment field exists on the form)
„ Shortcut—if you select the Add Shortcut option in the Notify dialog box,
a shortcut will be added as an attachment to the email notification. This
shortcut provides a link to the entry on the AR System server.

To send email notifications, you must have AR System Mail Server, or a

mechanism such as Microsoft Outlook, configured. The Remedy Email
Engine may be installed on a separate server as that processing the workflow.
When you install Remedy Email Engine, point to the AR System server you
intend to use. For more information about using filters or escalations to send
notifications, see the Developing AR System Applications: Basic guide.

Note: If you create notifications using the Submit execute condition with
join forms, the fields returned in the notification message will not be
populated. This is because there is no Request ID with join forms during
a Submit operation. In addition, join forms do not send values of fields on
Submit when the Reply with Entry parameter is set to Yes for the incoming
mailbox.

Email notifications for UNIX and Windows servers

When the filter or escalation is triggered, AR System will log a message
containing the notification text (and field contents—these are optional) on
the AR System Email Messages form. The Remedy Email Engine will send the
notification to the designated user.

Email notifications W 169

Action Request System 6.0

Using the AR System Email Mailbox Configuration form, you can configure
your email system to automatically delete notification messages from the
AR System Email Messages form after they have been successfully sent. Use
the Delete Outgoing Messages Selection in the Advanced Configuration tab
of the AR System Email Mailbox Configuration form. This reduces the
number of records stored in your message form.

Figure 5-15: Option to delete outgoing notification messages

For more information on configuring the email system, see Chapter 3,

“Email configuration.”

The Remedy Email Engine must be running to enable you to send email
notifications. There are some configuration options you can set in the Create
Filter (or escalation) dialog box when you create a Notify filter or escalation
to customize your email.

The AR System server creates notifications in the Remedy Email Message

form. The email engine then picks up the entries from the Email Message
form, processes them, and sends the email notifications to the appropriate
people

Configuring email notifications

X To define workflow used in notifications:
1 Make sure that you have an outgoing mailbox configured. Otherwise, you
will not receive any notifications.
2 Create your Notification filter or escalation.
3 Click the If Action tab or the Else Action tab.
4 From the New Action list, select Notify.

170 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

The Notify Filter (or escalation) page of the Create Filter (or escalation)
Dialog Box is displayed.
The fields required to define the Notify filter or escalation appear. The
following figure shows these fields and an example of how a Notify action
might look.

Figure 5-16: Notify filter or escalation action

5 In the Text field, enter the text of the message.

6 In the User Name field, enter the name of the users or groups to notify. For
each recipient, an entry is made in the AR System Email Messages form (see
Figure 5-18 on page 176).
To specify one or more recipients, enter any of the following choices
separated by hard returns (the server evaluates each line separately):
„ AR System user logins
„ AR System groups
„ Direct email addresses
Include the email domain name if you are entering a user’s name (for
example, [email protected]) or a keyword (for example,
[email protected]).

Email notifications W 171

Action Request System 6.0

The order in which these entries appear is the order in which the email
engine searches for addresses.
7 Enter a value in the Priority field; ranges of 1 to 10 are acceptable.
By default, emails are sent out from the email engine in the order they were
received, not in the order of priority. But you can set properties in the
EmailDaemon.properties file for the email engine to send high priority emails
first and then lower priority in that order. Use the following properties:
„ To ignore priority (default):
com.remedy.arsys.emaildaemon.SortMessages=false

„ To use the priority:

com.remedy.arsys.emaildaemon.SortMessages=true

For more information on using the EmailDaemon.properties file, see

“Performance and configuration settings” on page 191.
8 From the Mechanism field, select Email.
The Fields, Messages, and Templates tabs are activated.
Fields tab
X To define the Fields tab:
1 Enter the text that will appear in the subject line of the email.
2 Select which fields have the content you want to select in the email (in
addition to the notification text).
Note: The Request ID of entries from display or vendor forms will not be
returned in a notification. The system will not generate errors, but also will
not return the Request IDs.

The options are:

None None of the fields is included with the notification.

All All of the fields in the request are included with the notification.
Selected Selected fields from the fields list are included with the notification.
Changed Only fields that have changed in the current transaction are
included with the notification.

Make sure that all fields used in variables are selected in the Include Fields list
of the filter. (See Figure 5-10 on page 164.)

172 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

To be able to send the field contents, ensure that users being notified have the
necessary permissions. For more information about access control for users,
see the Configuring AR System guide; for groups, see the Developing
AR System Applications: Basic guide.
3 After the notifications have been sent, the message status will change in the
Email Messages form from Yes to Sent.
4 If you chose to delete Notification messages in your mailbox configuration,
the notification email entry will be deleted from the Remedy Email Messages
form.
Messages and templates tabs
The fields in these tabs are optional. If you leave these fields blank, the
settings relating to the mailbox entered in the Mailbox Name field apply. Or,
if the Mailbox Name field is empty, the default outgoing mailbox settings
apply. The default outgoing mailbox is the first mailbox created, or you can
specify another mailbox in the AR System Email Mailbox Configuration
form. For how to set a default outgoing mailbox, see “Default mailbox” on
page 150 and “Working with the mailbox configuration form” on page 75.
For default template settings for a specified mailbox, see “Setting default
templates for specific outgoing mailboxes” on page 136.

Email notifications W 173

Action Request System 6.0

Any entries in the fields in the Messages and Templates tabs will override the
default settings. If there are no entries in the Messages and Templates tabs,
and no default mailbox exists, an error message will be generated.

Figure 5-17: Notify filter or escalation dialog box—Messages tab

Messages tab
X To define the Messages tab:
1 In the Mailbox Name field, enter the name of the mailbox that you want to
handle the notifications if you do not want to use the default mailbox.
You can use a field or a keyword to substitute the mailbox name. This
mailbox name should correspond to a valid mailbox configured in the
AR System Email Mailbox Configuration form, or at the initial installation of
the email engine.
2 Enter information in the From, Reply To, CC and BCC fields:
„ If you make multiple entries in these fields, separate the entries by hard
returns.
„ You can use the following entries in the fields:
„ AR System user logins
„ AR System groups

174 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

„ Direct email addresses.

Include the email domain name if you are entering a user’s name (for
example, [email protected]) or a keyword (for example,
[email protected])
„ A field
„ A keyword

The order in which these entries appear is the order in which the email
engine searches for addresses.
„ If you fill in these fields, the Remedy Email Engine populates the
equivalent fields in the AR System Email Messages form for the
appropriate User Name (see Figure 5-18 on page 176). If, however, the
information for these fields in the AR System Email Messages form is
supplied from the AR System Email Mailbox Configuration form (that is,
a specified mailbox, or a default mailbox that has already been
configured), you need to display and save the AR System Email Messages
form before you see the entries.

3 In the From field, enter the name to be displayed to indicate where the mail
is from. If this field is blank and there are no entries in the From field on the
Advanced tab of the AR System Email Mailbox Configuration form for the
specified mailbox, or for the default mailbox, there will be no entry in the
email to indicate who the email is from.
4 In the Reply To field, if you enter a group name, a reply will be sent to all the
names in the group. If this field is blank, and there are no entries in the Reply
To field on the Advanced tab of the AR System Email Mailbox Configuration
form for the specified mailbox, or for the default mailbox, there will be no
entry in the email to indicate any Reply To.

Email notifications W 175

Action Request System 6.0

5 In the CC and BCC fields, if there are no entries in these fields or the Default
Addressing section of the Advanced tab of the AR System Email Mailbox
Configuration form for the specified mailbox, or for the default mailbox, no
copies of the email will be sent.

Figure 5-18: AR System Email Messages form

If you specify multiple recipients in the User Name field (see Figure 5-16 on
page 171), the name or names specified in the BCC and CC fields on this
form will only appear in the BCC and CC fields of the AR System Email
Messages form entry for the first user listed in this User Name field. The
permissions applied to the recipients of the CC and BCC fields will be the
same as those of this first listed user. This may be a security issue, especially
if you list a group name with some ambiguity about which is the first name
on the list. You may prefer to list names individually in the User Name field
so that you have more control over the permission status.
6 In the Organization field, enter a company name, an organization, a
keyword, or a field reference to a name that you would like to appear on the
email.

176 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

Templates tab
X To define the Messages tab:
1 In the Header, Content, and Footer fields, specify the names of the templates
to use for a header, content, or footer of the email notification. For more
information on creating and using templates, see Chapter 4, “Email
templates.”
When you create a content template for email notifications, the variable
format must correspond to a field’s database name and not the field label.
The default content template that you set in the AR System Email Mailbox
Configuration form is ignored for workflow notifications. If you want to use
any content template for notifications, you must specify it when creating
workflow, here in the Templates tab in the Notify action for filters and
escalations.
If you are using a content template for email notifications and you want to
see the notification text in the corresponding email, you must use the
following variable format in the content template:
#$$AR Notification Text$$#
If you want to create a content template to show Status History when doing
email notifications, the Status History must be represented in the following
formats:
#$$Status History.New.USER$$#
#$$Status History.Closed.TIME$$#

These formats are based on AR System core field ID 7. In addition, the Status
History strings here shown as examples could be languages other than
English.
Note: You cannot use AR System keywords in content templates for outgoing
emails in notifications.

2 Click Add Action, then save your changes to the filter or escalation.

Email notifications W 177

Action Request System 6.0

You can enter the name of the template directly, or enter a field reference or
keyword that leads indirectly to a template name. The templates specified
here must be stored in the AR System Email Templates form and the name
used here must be the same as that entered in the Template Name field of the
AR System Email Templates form.

Figure 5-19: Notify filter or escalation dialog box—Templates tab

The system determines which templates to use in the following order:

Step 1 The template entries in this tab.

Step 2 The templates set as defaults for the mailbox entered in the Mailbox Name
field of the Messages tab of the Notify action dialog box. (See Figure 5-17 on
page 174.)

Step 3 The templates set as defaults for the default mailbox.

Step 4 No templates are used.

178 XChapter 5—Messages and notifications

 Remedy Email Engine Guide

If no template is used for the Content, the order of fields included in an email
notification is strictly based upon their arrangement in the form view. Using
their X and Y coordinates, the order of fields begins top left to right, then
down (in a zigzag pattern). Fields excluded from the form’s default view are
randomly included at the bottom of the list. If a form includes page fields, the
pages are ignored. The order of fields included in the notification is still based
on their X and Y coordinates in the form.

Displaying Date/Time or numeric values in email notifications

When the AR System server sends data to a client with a different locale, the
format for numeric and date/time data may change to accommodate the
client locale. For example, date/time or numeric values stored on the
AR System server have a decimal separator, but when this data is relayed to a
German client, the decimal separator is displayed as a comma.

Email Notifications do not go through this client transition, therefore the

data in the notification is in the same format as that stored on AR System
server. This may result in incorrect date/time and numeric values being
displayed in a notification to different locales.

Email notifications W 179

Action Request System 6.0

180 XChapter 5—Messages and notifications

Chapter

6 Troubleshooting

This chapter contains troubleshooting information in the following sections:

„ Error and system status logs (page 182)
„ Submitting requests across different time zones (page 185)
„ Troubleshooting for Windows servers (page 185)
„ Debugging options for the Remedy email engine (page 187)
„ Updating the emaildaemon.properties file (page 189)
„ Creating email debug batch files (page 194)

Troubleshooting W 181
Action Request System 6.0

Error and system status logs

The AR System Email Error Logs form (Figure 6-1) stores both error and
system status information. This information can be useful in troubleshooting
problems with email transmission or formatting problems, as well as
problems with the email system environment.

Figure 6-1: AR System Email Error Logs form

Error logs include information such as:

„ Email transmission or instruction failures.
„ AR System API errors.
„ Internal email engine errors.

System status logs include information such as:

„ All incoming emails. (The email is included in the logging message as an
attachment.)
„ All outgoing email. (The email is included in the logging message as an
attachment.)
„ Connection status information for email servers.

182 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

„ Connection status information for the AR System server containing the

configuration, logs, and email forms.
„ Date and time the Remedy Email Engine was started or stopped.
„ Changes to the configuration of the Remedy Email Engine.

Note: You can access the Log Message Information form from both the
Remedy User task finder as well as from the Message Information form.
The Advanced tab in the Message Information form includes an Errors tab
that, when selected, displays the Log Message Information form with log
data for the message you are viewing.

For each log entry, the form provides the following information:
„ The log message ID and the date on which it was created.
„ The mailbox ID number for the message.
„ The message ID number of the message to which the log applies.
„ The message type—either an error log or a status log—and the severity
level of the message. Severity levels are as follows:
„ Severe: Errors that prevent successful execution of a specific task and
may require administrator intervention. This is the default value.
„ Warning: Errors that may cause problems when executing a task.
„ Info: Status information.
„ Config: Information related to mailbox configuration. For
configuration information, see “Working with the mailbox
configuration form” on page 75.
„ Fine: Internal exceptions, which are handled by the application but
logged for tracing purposes.
„ Finer: Trace logs that record specific tasks as they are executed within
the application.
„ Message number: The error number associated with the message.
„ How the message was generated, either by the email engine or by the
AR System server.
„ The error message text, which describes the error.

Error and system status logs W 183

Action Request System 6.0

Email transmission or instruction failures

When an email transmission fails or an instruction cannot be executed, the
system generates an error message and stores it in the AR System Email Error
Logs form. Examples of errors include instructions that refer to a nonexistent
form or an invalid server name. In the following sample error message, a
form called XYZForm, referenced in two instructions, could not be found on
the server—either the form name was entered incorrectly, or the form does
not exist.

Instruction: Submit
Instruction Number: 1
Instruction Template:

Message Type:
Message Number: 303
Message Text: Form does not exist on server
Appended Text: XYZForm

Instruction: Query
Instruction Number: 2
Instruction Template:

Message Type:
Message Number: 303
Message Text: Form does notexist on server
Appended Text: XYZForm

AR System API errors

The email engine will log any AR System API errors that occur while
executing instructions in an email.

Internal email engine errors

Any internal problems with the email engine itself (for example, if the system
runs out of disk space) will be logged.

184 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

Submitting requests across different time zones

A user who submits an email request or query using a date/time field from a
machine that is located in a different time zone from the machine where the
Remedy email engine is installed may experience the following problems:
„ The query result may not be the same as a Remedy User query result.
„ The query result may not be correct.
„ A request may be registered with an unexpected date or time.

These problems occur because the time zone is not adjusted between the
Remedy email engine and the email client machine. To avoid these problems,
users should submit requests and queries to an email engine machine located
in the same time zone.

Troubleshooting for Windows servers

The following sections outline procedures for troubleshooting Windows
server problems.

Verifying permissions for the Windows account

If the Remedy email engine will not run as a service, verify that it can be run
manually using the following procedure.

Note: If you are using MAPI, log in to the server as the Windows account
used to start the email engine service.

X To verify permissions for Windows accounts:

1 Open a command prompt.
2 Change directories to the AR System email installation directory.
3 At the prompt, run emailstart.bat.
4 If the mail process does not run, verify that the email engine user account has
the advanced user rights and necessary permissions as described in the
Installing AR System guide.
5 If you are not using MAPI, verify that the email engine user account has the
appropriate file system permissions on the AR System directory.

Submitting requests across different time zones W 185

Action Request System 6.0

Note: If you are using a MS Exchange server with SMTP and either POP3 or
IMAP4, verify that your Exchange server has the SMTP gateway enabled
as well as either IMAP4 or POP3 functionality.

Troubleshooting email request processing and notify filters

The Remedy email engine can experience problems if email submissions are
not formatted correctly. If an incorrect email address is specified on an
outgoing email notification, or an out-of-office reply is received, items that
are not valid email submissions will reside in the AR System mail server
mailbox.

To avoid such problems, create a rule in your email program that checks the
body of the message for text you require users to include in submissions, such
as query or submit. If the message does not contain this text, set the rule to
forward the email to the AR System administrator and delete it. This rule
performs these functions:
„ It prevents problems with the Remedy email engine due to improper
request formatting.
„ It prevents undeliverable messages from firing duplicate notify filters. If a
message triggers a notify filter and is returned as undeliverable, it is
returned to the mail queue, where it causes the filter to fire again.
„ It alerts the administrator to the types of messages being submitted
incorrectly, so that the administrator can instruct users as to the correct
procedures for formatting and submitting messages.

186 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

Debugging options for the Remedy email engine

The logging.properties file that you can use for debugging the email engine
can be found in the Java lib directory. The following options are available:

Settings Definitions
Global Property Handlers Sets the places where logs can go. In this example, it has been
handlers= set to send logs only to the console.
java.util.logging.ConsoleHandler

Global Property Handlers Enables file logging with console logging.

handlers=
java.util.logging.FileHandler, Note: On UNIX, all console output is directed to a
java.util.logging.ConsoleHandler emaild.sh_log file under the logs subdirectory of the email
installation, but file logging can also be switched on.
Global Logging Level The logging level for the file output. You can set the logging
java.util.logging.FileHandler. level to Finer in the Java logging.properties file to obtain
LEVEL = FINER every log message generated by the system. You can also use
the keyword ALL which means all logs are to be sent to the
output.
Note: Use this option with care, because the contents of the
AR System Email Error Log form can become very large.
Handler Specific Properties File to where logs are made. You can reference the Java
java.util.logging.FileHandler. documentation on this format, as it is specified by Java 1.4.x
pattern = %h/java%u.log logging.
Handler Specific Properties Maximum size of the file. If the system exceeds this length, it
java.util.logging.FileHandler will create a new file.
.limit = 50000

Handler Specific Properties Number to start with. This is appended to the end of the file
java.util.logging.FileHandler. name.
count = 1

Handler Specific Properties Use an XML formatter to format the output, or you can use
java.util.logging.FileHandler. java.util.logging.SimpleFormatter with console logging.
formatter =
java.util.logging.XMLFormatter

Console Handler Specific Properties Logging level for the file output.
java.util.logging.ConsoleHandler.
level = INFO

Console Handler Specific Properties XML formatter for console logging.

java.util.logging.ConsoleHandler.
formatter =
java.util.logging.SimpleFormatter

Debugging options for the Remedy email engine W 187

Action Request System 6.0

Settings Definitions
Main Application Level The level for the entire email engine. This setting for the main
com.remedy.arsys.emaildaemon. application level includes the modules, unless you specify
level = INFO otherwise.
If a level for one of the outputs is lower than this setting, then
this level overrides that level for the given output. In this
example, since this level is INFO, the level for the file handler
will be ignored and also set to INFO.
If the main application level is SEVERE, then only module logs
with a level of SEVERE are allowed. You can override this
behavior by adding one of these module levels, then specifying
that level as FINER, FINE, INFO or WARNING. This level will
be used for all logs originating from that particular module
and only that module.
If you add more than one module level, then logs for more
than one module will be allowed through, and you can set the
levels for the different modules independently.
Module Levels The levels for application modules. You can specify the
com.remedy.arsys.emaildaemon. logging levels for the various modules independently from the
<Module>.level= entire email engine logging level, for only the modules you are
„ ConfigurationModule.level=FINER interested in troubleshooting.
„ CreatorModule.level=FINER
„ ExecutionModule.level=FINER
These application modules allow you combine main
„ ReceiverModule.level=FINER application and module logging.
„ SenderModule.level=FINER For example, if the main application level is set to INFO and
„ MonitorModule.level=FINER you set the level for the Receiver Module to FINER, then you
will see only FINER information in the log for the Receiver
module. If there is no entry in the logging.properties file
for a particular module, then the system defaults to the
application level (that is, INFO).
Note: The level for one of the outputs must be at least FINER,
such as the ConsoleHandler, to actually see the log.
Application levels Level for the outputs to the Remedy Email Error form. You
com.remedy.arsys.emaildaemon. cannot disable this handler as you can with the Console and
ARSystem File. This level could also be overridden if the application level
Handler.level = WARNING defined previously is higher.

188 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

Updating the emaildaemon.properties file

When the Remedy email engine is installed, the emaildaemon.properties file
is created in the email engine installation directory and is populated with the
name of your organization’s email server, username, and password. The
main purpose of the emaildaemon.properties file is to identify the AR System
server your email engine talks to.

Figure 6-2: Sample contents of emaildaemon.properties file

If your email environment changes—for example, if you need to change a

server name or a TCP port—this file must be updated. The following
procedure explains how to update the emaildaemon.properties file.

The emaildaemon.properties file also lets you specify properties you can use
to enhance the performance of the email engine.

Updating the emaildaemon.properties file W 189

Action Request System 6.0

X To update the emaildaemon.properties file:

1 Open a command prompt.
2 Change directories to the AR System email installation directory, and enter
the following command:
For Windows:
<JRE_install_path>\java -cp
emaildaemon.jar;arapi60.jar;arutil60.jar;activation.jar;mail.jar;
imap.jar;smtp.jar;pop3.jar;
com.remedy.arsys.emaildaemon.EmailDaemon<-parameters>

where <JRE_install_path> is the path of your Java Runtime Environment

(JRE) installation and <parameters> represent the parameters you specify to
update the file.
For UNIX:
<JRE_install_path>/java -cp
emaildaemon.jar:arapi60.jar:arutil60.jar:activation.jar:mail.jar:imap
.jar:smtp.jar:pop3.jar com.remedy.arsys.emaildaemon.EmailDaemon -i 1

The UNIX classpath requires colons, not semicolons.

Note: To use this command, make sure that you properly set the
LD_LIBRARY_PATH path for all UNIX platforms.

The following parameters are available:

Table 6-1: Email engine startup parameters (Sheet 1 of 2)

Parameter Description
-s Specifies the server where the email forms (and the configuration
information) are located.
-p Specifies the AR System Application Service password. The email
engine uses the same password as that supplied in AR System
Administrator under File > Server Information > Connection
Settings > Application Service Password.
-t A Transmission Control Protocol (TCP) port for the server to which
the email engine should connect.
-r The Remote Procedure Call (RPC) number of the server to which
the email engine should be connected. This parameter may be useful
if you want to connect to a private server which can benefit
performance if you expect a high volume of mail.
-l The language to be used. (The default is C.)

190 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

Table 6-1: Email engine startup parameters (Sheet 2 of 2)

Parameter Description
-d Used to specify the directory where the EmailDaemon.properties
file is located. If this parameter is not supplied, the system assumes
that this file is stored in the same directory as the emaildaemon.jar
file.
-i The time interval (in minutes) to use when checking the server for
configuration updates (modifications to records in the Email
Mailbox Configuration form). The default is 30 minutes.
-m Monitor module interval (in minutes) to wait before trying to start
the email engine again. The default is 30 minutes. When the
AR System server is not available, it tries to restart the system for
every 30 minutes by default.
-o Specifies MAPI sent folder where sent mail should be stored.

Performance and configuration settings

The following properties are available in the emaildaemon.properties file (as
shown in Figure 6-2 on page 189) to adjust the default performance and
configuration of the email engine. After adding these new settings, you must
stop and restart the email engine to implement them.

Settings Definitions
com.remedy.arsys.emaildaemon. This setting lets you specify the date and time format used by the
ARDATE= email engine for parsing date and time strings. MMMMM dd, yyyy
HH:mm:ss z is equivalent to September 21, 2003 12:08:56 PDT.

com.remedy.arsys.emaildaemon. This setting lets you specify the time format used by the email engine
ARDATEONLY= for parsing date strings. MMMMM dd, yyyy is equivalent to September
21, 2003.

com.remedy.arsys.emaildaemon. This setting lets you specify the time format used by the email engine
ARTIMEONLY= for parsing time strings. HH:mm:ss z is equivalent to 12:08:56 PDT.
com.remedy.arsys.emaildaemon. This performance setting lets you specify the set size of entries to
ChunkSize=100 return when the email engine makes a call to the AR System server.
The default chunk size of entries returned is set to 100.

Updating the emaildaemon.properties file W 191

Action Request System 6.0

Settings Definitions
com.remedy.arsys.emaildaemon. This setting lets you store instructions and instruction parameters in
StoreInstructions=false the AR System server. Setting this option to true let you leave data in
the Instructions form and the Parameters form for troubleshooting
purposes. If you choose the true option, you must remove this
information explicitly.
Execution module in the email engine handles both the parsing and
execution of messages. There will be one message queue created for
each Incoming mailbox. By default, instructions are not stored in
the server.
com.remedy.arsys.emaildaemon. This setting lets you add new log messages for logging instructions
ExecutionModule.level=Fine and instruction parameters.
com.remedy.arsys.emaildaemon. This setting lets you change the default number of how many email
IncomingConnectionRecycleSize messages the email engine receives before the connection is closed
=100
and reopened. By default, the connection is closed and reopened for
every 100 messages.
In the 5.1 and 5.1.1 releases of the email engine, the connection with
mail server was closed only after reading all incoming messages. As
a result, if the email engine crashed or hung before the connection
is closed, the messages marked for deletion may not be deleted from
the mail server.
com.remedy.arsys.emaildaemon. This setting lets you define message queue size. Receiver module
IncomingMessagesQueueSize=100 writes messages to the queue and Execution module reads messages
from this queue to parse and execute. Receiver module still writes
message to server in Remedy Email Messages form, but the
Execution module reads the message from message queue instead of
from the server. This reduces the traffic to the AR System server and
improve the performance. The default message queue size is set to
100.
com.remedy.arsys.emaildaemon. Instruction caching was implemented in the 6.0 release of the email
instructionCacheSize=20 engine. This performance setting lets you specify the size of the
cache used for storing instructions.
The default setting keeps 20 instructions in cache. If there are 20
instructions and another is added, the oldest instruction is removed.
If there are any changes made to the Email Instructions form, the
instruction cache is flushed based on the configuration Interval
setting.

192 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

Settings Definitions
com.remedy.arsys.emaildaemon. Used to specify the interval between checks to see if all the threads
Monitor=30 are functioning properly. This interval is measured in minutes, and
like the configuration interval, the default value is 30. If the
Monitoring system detects that a thread has failed, then it restarts
the thread.
com.remedy.arsys.emaildaemon. This setting lets you define the number of messages to process
OutgoingConnectionRecycleSize before closing the connection to the mail server. This action is
=100
performed to ensure that memory is properly released.
The default setting is 100 messages.
com.remedy.arsys.emaildaemon. This setting lets you specify a string if your AR System server
<server_name>.Authentication requires authentication information before handling requests.
com.remedy.arsys.emaildaemon. This setting lets you define the time interval (in minutes) to use
<server_name>.Interval=30 when checking the server for configuration updates (modifications
to records in the Email Mailbox Configuration form). The default is
30 minutes. For example, to set the interval to 5 minutes, you would
use the following syntax:
com.remedy.arsys.emaildaemon.<server_name>.Interval=5

com.remedy.arsys.emaildaemon. This setting lets you specify what language to use in the email
<server_name>.Language=en_US engine, for example, com.remedy.arsys.emaildaemon.
<server_name>.Language=en_US.

com.remedy.arsys.emaildaemon. This setting lets you specify what RPC port number the AR System
<server_name>.RPC=0 server uses if you have configured a private server to use with the
email engine.
com.remedy.arsys.emaildaemon. This setting lets you specify what TCP port number the AR System
<server_name>.TCP=0 uses if your AR System server is not using Portmapper.
com.remedy.arsys.emaildaemon. This setting lets you specify the port for RMI (remote method
RMIPORT=1099 invocation). This 6.0 feature is used with the EmailAdminAgent.jar
file to stop, suspend, resume, or change logging to the email engine.
com.remedy.arsys.emaildaemon. Lets you keep the sent items in the Email Messages form.
SaveSentItem=True
Set to False if you want to delete the sent items from the Email
Messages form.
com.remedy.arsys.emaildaemon. This setting lets you specify how many security keys are kept in
securityCacheSize=20 cache.
The default setting keeps 20 security keys in cache. If there are 20
keys and another is added, the oldest key is removed. If there are any
changes made to the Email Security form, the cache is flushed based
on the configuration Interval setting.

Updating the emaildaemon.properties file W 193

Action Request System 6.0

Settings Definitions
com.remedy.arsys.emaildaemon. This setting lets you specify how many outgoing emails to query at
SendEmailSetSize=100 a time. The default size of outgoing emails is set to 100.
com.remedy.arsys.emaildaemon. This setting lets you specify the AR System server that the email
Servers engine interacts with.
com.remedy.arsys.emaildaemon. This setting lets you specify if messages with a higher priority setting
SortMessages=false are processed first. The default setting is false.
com.remedy.arsys.emaildaemon. This performance setting lets you specify how many email
templateCacheSize=20 templates are kept in cache.
The default setting keeps 20 templates in cache. If there are 20
templates and another is added, the oldest template is removed. If
there are any changes made to the Email Templates form, the cache
is flushed based on the configuration Interval setting.
com.remedy.arsys.emaildaemon. This performance setting lets you specify the number of users
userChunkSize=5000 (records from the User form) to retrieve from the AR System server
at one time. The default chunk size of users returned is set to 5000.

Creating email debug batch files

Creating a debug email batch file can help resolve issues that may not show
up in the email error log. You accomplish this by setting the debug mode for
the Java process that runs the email engine. You might find this procedure
enormously useful for debugging the email engine, in contrast to using the
AR System Email Error Log form. The contents of the AR System Email Error Log
form can become very large.

194 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

Debugging the Windows email engine

To enable the -Dmail.debug=true debug mode option for Windows, perform
the following steps:

X To debug the Windows email engine:

1 Edit the emailstart.bat file and add the -Dmail.debug=true option after
"%JavaPath%\java" (see example below)
The default location of the emailstart.bat file is
Program Files\AR System\AREmail.
"%JavaPath%\java" -Dmail.debug=true -cp
emaildaemon.jar;arapi60.jar;arutil60.jar;activation.jar;mail.jar;imap
.jar;smtp.jar;pop3.jar;armapi60.jar
com.remedy.arsys.emaildaemon.EmailDaemon

2 Save the batch file as another name, for example, emaildebug.bat.

3 Make sure that the Remedy email system engine service is stopped in the
services window.
4 Open a command prompt, change the directory to the location of the
AR System install directory, and run the new batch file.
This batch file will add debug information to the screen when email is started
from a command prompt. You can also have the output go to a file by adding
> c:\temp\debug.log to the end of the Java statement above.

Sample debug log

Below shows the contents of a sample debug log.

loaded library
DEBUG: JavaMail version 1.4.1_01
DEBUG: successfully loaded file: C:\Program
Files\Java\j2re1.4.1_01\lib\javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
emaildaemon.jar!/META-INF/javamail.providers
DEBUG: Bad provider entry:
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/
AR%20System/AREmail/emaildaemon.jar!/META-INF/javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
imap.jar!/META-INF/javamail.providers
DEBUG: JavaMail version 1.3
DEBUG: successfully loaded file: C:\Program
Files\Java\j2re1.4.1_01\lib\javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
emaildaemon.jar!/META-INF/javamail.providers
DEBUG: Bad provider entry:

Creating email debug batch files W 195

Action Request System 6.0

DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/

AR%20System/AREmail/emaildaemon.jar!/META-INF/javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
imap.jar!/META-INF/javamail.providers
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/
AR%20System/AREmail/imap.jar!/META-INF/javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
smtp.jar!/META-INF/javamail.providers
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/
AR%20System/AREmail/imap.jar!/META-INF/javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
smtp.jar!/META-INF/javamail.providers
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/
AR%20System/AREmail/smtp.jar!/META-INF/javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
pop3.jar!/META-INF/javamail.providers
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
pop3.jar!/META-INF/javamail.providers
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/
AR%20System/AREmail/pop3.jar!/META-INF/javamail.providers
DEBUG: successfully loaded resource: /META-INF/
javamail.default.providers
DEBUG: Tables of loaded providers
DEBUG: Providers Listed By Class Name:
{com.remedy.mail.mapi.MAPITransport=javax.mail.Provider[TRANSPORT,map
itransport,com.remedy.mail.mapi.MAPITransport,[email protected]],
com.remedy.mail.mapi.MAPIStore=javax.mail.Provider[STORE,mapistore,co
m.remedy.mail.mapi.MAPIStore,[email protected]],
com.sun.mail.smtp.SMTPTransport=javax.mail.Provider[TRANSPORT,smtp,co
m.sun.mail.smtp.SMTPTransport,Sun Microsystems, Inc],
com.sun.mail.imap.IMAPStore=javax.mail.Provider[STORE,imap,com.sun.ma
il.imap.IMAPStore,Sun Microsystems, Inc],
com.sun.mail.pop3.POP3Store=javax.mail.Provider[STORE,pop3,com.sun.ma
il.pop3.POP3Store,Sun Microsystems, Inc]}
DEBUG: Providers Listed By Protocol:
{imap=javax.mail.Provider[STORE,imap,com.sun.mail.imap.IMAPStore,Sun
Microsystems, Inc],
mapistore=javax.mail.Provider[STORE,mapistore,com.remedy.mail.mapi.MA
PIStore,[email protected]],
mapitransport=javax.mail.Provider[TRANSPORT,mapitransport,com.remedy.
mail.mapi.MAPITransport,[email protected]],
pop3=javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Sun
Microsy stems, Inc],
smtp=javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTranspo
rt,Sun Microsystems, Inc]}
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/
AR%20System/AREmail/pop3.jar!/META-INF/javamail.providers
DEBUG: successfully loaded resource: /META-INF/
javamail.default.providers
DEBUG: Tables of loaded providers

196 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

DEBUG: Providers Listed By Class Name:

{com.remedy.mail.mapi.MAPITransport=javax.mail.Provider[TRANSPORT,map
itransport,com.remedy.mail.mapi.MAPITransport,[email protected]],
com.remedy.mail.mapi.MAPIStore=javax.mail.Provider[STORE,mapistore,co
m.remedy.mail.mapi.MAPIStore,[email protected]],
com.sun.mail.smtp.SMTPTransport=javax.mail.Provider[TRANSPORT,smtp,co
m.sun.mail.smtp.SMTPTransport,Sun Microsystems, Inc],
com.sun.mail.imap.IMAPStore=javax.mail.Provider[STORE,imap,com.sun.ma
il.imap.IMAPStore,Sun Microsystems, Inc],
com.sun.mail.pop3.POP3Store=javax.mail.Provider[STORE,pop3,com.sun.ma
il.pop3.POP3Store,Sun Microsystems, Inc]}
DEBUG: successfully loaded resource: /META-INF/
javamail.default.address.map
DEBUG: URL jar:file:/C:/Program%20Files/AR%20System/AREmail/
smtp.jar!/META-INF/javamail.address.map
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/
AR%20System/AREmail/smtp.jar!/META-INF/javamail.address.map
DEBUG: java.io.FileNotFoundException: C:\Program
Files\Java\j2re1.4.1_01\lib\javamail.address.map (The system cannot
find the file specified)
DEBUG: successfully loaded resource: /META-INF/
javamail.default.address.map
DEBUG: java.io.FileNotFoundException: C:\Program
Files\Java\j2re1.4.1_01\lib\javamail.address.map (The system cannot
find the file specified)
DEBUG: getProvider() returning
javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Sun
Microsy stems, Inc]
POP3: connecting to host "stubby", port 110
S: +OK stubby.ntense.Remedy.COM POP3 server (Post.Office v3.5.3
release 223 with ZPOP version 1.0 ID# 0-0U10L2S100V35) ready Tue, 4
Feb 2003 09:42:48 -0800
C: USER blip
S: +OK Password required for blip
C: PASS remedy
S: +OK Maildrop has 0 messages (0 octets)
C: STAT
S: +OK 0 0
C: QUIT
S: +OK stubby.ntense.Remedy.COM POP3 server closing connection

Creating email debug batch files W 197

Action Request System 6.0

Debugging the UNIX email engine

To enable the -Dmail.debug=true debug mode option for UNIX, perform the
following steps:

X To debug the UNIX email engine:

1 Open the emaild.sh script.
2 Add the following option to the line that starts the Java process in the
emaild.sh script:
-Dmail.debug=true
3 Edit the emaild.sh script from:
exec ${JAVA_BIN}/java -Djava.library.path=${InstallPath} -cp
${CP_PATH}
com.remedy.arsys.emaildaemon.EmailDaemon -d ${InstallPath}
>${LogFile} 2>&1
To the following:
exec ${JAVA_BIN}/java -Djava.library.path=${InstallPath} -
Dmail.debug=true -cp ${CP_PATH}
com.remedy.arsys.emaildaemon.EmailDaemon -d ${InstallPath}
>${LogFile} 2>&1
4 Stop and start the email engine.

Example of outgoing email using SMTP

Below shows the contents of a sample debug log for outgoing email.

DEBUG: getProvider() returning

javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTransport,Su
n Microsystems, I
nc]
DEBUG SMTP: useEhlo true, useAuth true
DEBUG: SMTPTransport trying to connect to host "cruiser", port 25
DEBUG SMTP RCVD: 220 cruiser.remedy.com ESMTP Sendmail 8.11.6+Sun/
8.11.6; Mon, 10 Feb 2003 12:19:35 -0800 (PST)
DEBUG: SMTPTransport connected to host "cruiser", port: 25
DEBUG SMTP SENT: EHLO cruiser.remedy.com
DEBUG SMTP RCVD: 250-cruiser.remedy.com Hello cruiser.remedy.com
[10.4.30.23], pleased to meet you
250-ENHANCEDSTATUSCODES
250-EXPN
250-VERB
250-8BITMIME
250-SIZE
250-DSN
250-ONEX
250-ETRN
250-XUSR
250 HELP

198 XChapter 6—Troubleshooting

 Remedy Email Engine Guide

DEBUG SMTP Found extension "ENHANCEDSTATUSCODES", arg ""

DEBUG SMTP Found extension "EXPN", arg ""
DEBUG SMTP Found extension "VERB", arg ""
DEBUG SMTP Found extension "8BITMIME", arg ""
DEBUG SMTP Found extension "SIZE", arg ""
DEBUG SMTP Found extension "DSN", arg ""
DEBUG SMTP Found extension "ONEX", arg ""
DEBUG SMTP Found extension "ETRN", arg ""
DEBUG SMTP Found extension "XUSR", arg ""
DEBUG SMTP Found extension "HELP", arg ""
DEBUG SMTP: use8bit false
DEBUG SMTP SENT: MAIL FROM:
DEBUG SMTP RCVD: 250 2.1.0 ... Sender ok
DEBUG SMTP SENT: RCPT TO:
DEBUG SMTP RCVD: 250 2.1.5 ... Recipient ok
Verified Addresses
[email protected]
DEBUG SMTP SENT: DATA
DEBUG SMTP RCVD: 354 Enter mail, end with "." on a line by itself
DEBUG SMTP SENT:
DEBUG SMTP RCVD: 250 2.0.0 h1AKJZh09819 Message accepted for delivery

Example of incoming email using MBOX

Below shows the contents of a sample debug log for incoming email. You can
see the lock file get created, the file is read then saved, and the lock is
removed.

# tail -f emaild.sh_log
DEBUG: java.io.FileNotFoundException: /usr/java1.4.1/j2se/jre/lib/
javamail.address.map (No such file or directory)
DEBUG: getProvider() returning
javax.mail.Provider[STORE,mbox,gnu.mail.providers.mbox.MboxStore,dog@
gnu.org]
mbox: creating /var/mail/arsystem.lock
mbox: reading /var/mail/arsystem
mbox: saving /var/mail/arsystem
mbox: removing /var/mail/arsystem.lock
mbox: creating /var/mail/arsystem.lock
mbox: reading /var/mail/arsystem
mbox: saving /var/mail/arsystem
mbox: removing /var/mail/arsystem.lock
mbox: creating /var/mail/arsystem.lock
mbox: reading /var/mail/arsystem
mbox: saving /var/mail/arsystem
mbox: removing /var/mail/arsystem.lock
mbox: creating /var/mail/arsystem.lock
mbox: reading /var/mail/arsystem
mbox: saving /var/mail/arsystem
mbox: removing /var/mail/arsystem.lock

Creating email debug batch files W 199

Action Request System 6.0

200 XChapter 6—Troubleshooting

Appendix

A Examples of email templates

The examples in this appendix demonstrate how you can use templates to
execute a specific set of instructions on an AR System form. See “Exporting
mail templates” on page 111 for more information on how to export email
templates and “Global and local parameter declarations” on page 122 for
more information on labels and values for templates.
„ Modifying templates for search actions with the Remedy Email Engine
(page 202)
„ The modify action (page 206)
„ Sample templates (page 213)

Examples of email templates W 201

Action Request System 6.0

Modifying templates for search actions with the

Remedy Email Engine
You must use the Action label (or its alias) to perform a search action. The
following examples use templates that have been exported using Remedy
Administrator and show how to modify them, but you can create the
template using a text editor.

X To create an email template to search for a request ID:

1 Export the email template for the form that you want to make available for
searching.
The following is an example of an exported mail template.

File exported Tue May 21 21:38:47 2004

Schema: vacation
Server: quest.Remedy.COM
Login:
Password:
Action: Submit
Values: Submit, Query

Format: Short
Values: Short, Full
Submitter !2!:
Short-Description !8!:

2 Edit the exported file.

a Change the Action:Submit to Action:Query.
b In the fields section of the email template, define only the Request ID.
It must have a field ID value of 1.
a Enter the Request ID of the entry to be retrieved.
b Remove all other fields from the mail template.
The only field in the body should be !1! <Request ID_number>.

202 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

The following example shows an exported template that was modified to

search for a request ID:

File exported Tue May 21 21:38:47 2004

Schema: vacation
Server: quest.Remedy.COM
Login:
Password:
Action: Query
Format: Short
Values: Short, Full

!1!:TT00000000119

X To create an email template to search for a field:

1 Export the email template for the form that you want to make available for
searching.
An example of a mail template for a form follows.

File exported Tue May 21 21:38:47 2004

Schema: AR-HD Calls

Server: narnia
Login:
Password:
Action: Submit
Values Submit, Query
Format: Short
Values Short, Full
Source !5368737933!: Phone
Values: Phone, AR System, email,
NMP, ACD
Caller Impact !5368783455!: Low
Values: High, Medium, Low
Last Name !5386753452!:
Phone Number !5386748345!:

2 Edit the exported file.

a Change the Action:Submit to Action:Query.
b Set the Format option if you want a format other than the default (Short).
c Edit the fields portion of the email template to include the fields you are
searching, but remove all other information.

Modifying templates for search actions with the Remedy Email Engine W 203
Action Request System 6.0

The following example shows an exported template that was modified to

search for multiple fields.

File exported Tue May 21 21:38:47 2004

Schema: AR-HD Calls

Server: narnia
Login:
Password:
Action: Query
Format: Full
Source !5368737933!: Phone
Caller Impact !5368783455!: Low

X To create an email template to search using a qualification:

1 Export the email template for the form that you want to make available for
searching.
The following example shows a mail template for a form:

File exported Tue May 21 21:38:47 2004

Schema: AR-HD Calls

Server: narnia
Login:
Password:
Action: Submit
Values: Submit, Query
Format: Short
Values: Short, Full
Source !5368739331!: Phone
Values: Phone, AR System, email
Caller Impact !5368783455!: Low
Values: High, Medium, Low
Last Name !5386753452!:
Phone Number !5386748345!:

2 Edit the exported file.

a Change the Action:Submit to Action:Query.
b Remove all fields in the message and include a Qualification label.

204 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

The following example shows an exported file that was modified to search
using the Qualification label.

File exported Tue May 21 21:38:47 2004

Schema: AR-HD Calls

Server: narnia
Login:
Password:
Action: Query
Format: Short
Qualification: 'Source' = "Phone" OR 'Source' = "email"
X To create an email template that includes attachments:
The following are examples of email templates that include an attachment
field.

Email template example for an AR System administrator

1 Export the email template for the form that you want to make available for
searching.
2 Edit the template to include the label and value for an attachment field (for
example, Attach!536880912!:), as shown here:
#
# File exported Fri Mar 07 10:30:40 2004
#
Schema: Email Submit
Server: padres.Remedy.COM
Login:
Password:
Action: Submit
# Values: Submit, Query
Format: Short
# Values: Short, Full

Submitter ! 2!:
Short Description ! 8!:
Attach!536880912!: <====== (Manually add this line based upon the
attachment field name and database ID)

Modifying templates for search actions with the Remedy Email Engine W 205
Action Request System 6.0

Email template example for user

1 In a third-party client tool like MS Outlook Express, add all the required
values.
2 Supply the attachment file name including the extension after the attachment
field parameter.
The following is an example of an end-user email template filled out with a
filter.log file attached.
#
# File exported Fri Mar 07 10:30:40 2003
#
Schema: Email Submit
Server: bogus.remedy.com
Login: Demo
Password:
Action: Submit
# Values: Submit, Query
Format: Short
# Values: Short, Full

Submitter ! 2!: Demo

Short Description ! 8!: Submitting email with attachment file.
Attach!536880912!: filter.log

3 Insert your filter.log attachment file anywhere in the email. If the attachment
name including the extension is not supplied in the email template, the email
submission will fail.

The modify action

For more information on the using Modify action in templates, see page 117.
For more information on how to configure steps 1 through 3 that follow, see
“Working with the mailbox configuration form” on page 75.
X To perform the modify action using an email template:
1 You must have an incoming and outgoing mailbox configured and these two
mailboxes must be associated with one another. This association is set in the
Associated Mailbox Name field under the Advanced Configuration tab of the
AR System Email Mailbox Configuration form, as shown in the following
figure.

206 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

2 Set Enable Modify Actions to Yes in the AR System Email Mailbox

Configuration form for the incoming mailbox. (See the following figure.)

Associate the Outgoing

and Incoming
Mailboxes

Set Enable Modify

Actions to Yes

Figure A-1: Enabling modify actions

3 Ensure you have a valid security key.

The modify action W 207

Action Request System 6.0

This is created in the AR System Email Security form; see the following
figure.

Set Security Key

Figure A-2: AR System Email Security Key form

Note: To perform the Modify action on a form using email, you must have a
template and it must be stored in the AR System Email Templates form.

The example assumes you have created a form named TestModify containing
at least the core fields.
For information on how to create templates, see “Creating templates” on
page 110.

208 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

4 Create a template. The following is one example and can be named

TestModify:
Login:
Password:
Key:

Action: Modify
Form: TestModify

Request ID: 00000000001

!2!:
!8!:
!536870914!:

Ensure you have Action, Form, and Request ID labels and that these are not
changed during the procedure.
For more examples of templates, see page 213, page 220, or page 222.
„ For outgoing emails, this template will form the body of the email using
the AR System Email Messages form. See step 7.
„ For incoming emails to the AR System, type the content into the body of
the email using an email client tool. See step 7. You also need to create the
template and store it in the AR System Email Templates form because this
will be used for the reply (the Result template).

5 Add your template to the AR System Email Templates form. (See “Storing
templates in the AR System Email Templates form” on page 131.)
6 Optional. Create a search to search for a specific parameter using a variable.
For example if you need to search for the Request ID 00000000001:
„ For outgoing emails:
„ Include a variable value for the Request ID field in your content
template by replacing the Request ID: 00000000001 label/value pair
with Request ID:[$$#$$Request ID$$#$$].
„ Open the AR System Email Messages form in an AR System web or
Windows client.
„ Select the Display Advanced Options choice to Yes.
„ Click the Advanced Options tab > Variable Replacement tab.

The modify action W 209

Action Request System 6.0

„ Enter a qualification in the Qualification field. Our example is

‘Request ID’=”00000000001”.

Figure A-3: Variable replacement tab of the AR System Email Messages form

The email engine searches the specified form for the record, then it
substitutes the Request ID parameter in the Content template with the
Request ID value (00000000001) found with the query. See page 158 for more
information on using the Variable Replacement tab.
„ For incoming emails, include a variable value for the Request ID field in
your Result (reply) template by replacing the Request ID: 00000000001
label/value pair with Request ID:[$$#$$Request ID$$#$$]. Your template
will be specified as the Result Template in your label/value pair in the body
of your email. Include a query action in the body of your email, the
following is an example:
Action: Query
Qualification: ‘Request ID’ = “00000000001”

210 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

7 Prepare your email.

„ For outgoing emails,
„ Open the AR System Email Messages form, if not already open.
„ Select the Display Advanced Options choice to Yes.
„ Click the Advanced Options tab > Templates tab.
„ Attach the template that you created in step 4 to your email using the
Content Template field. (See the following figure.) This will form the
body of the outgoing email.

Select template
from Content
Template list

Figure A-4: Attach content template

„ For incoming emails, type the following label/value pairs into the body of
the email:
Action:Query
Qualification: ‘Request ID’=”00000000001”
Result Template: TestModify

This is all you need to provide. The Result template contains all the
information required for the email engine to perform first the Query
action and then the Modify action.
If you added the Query action to the template, as in the optional step 6 on
page 209, you can omit the Qualification line.

The modify action W 211

Action Request System 6.0

8 Send your email to an AR System configured mailbox.

The email engine searches the specified form for the record with the request
ID.
„ For outgoing emails, if you have included a query, it substitutes the
Request ID value (in the example 00000000001) found with the query into
the email reply.
„ For incoming emails, the email engine will first send you a reply to the
Query action using the template you created and specified as the Result
Template. It substitutes the Request ID value (in our example
00000000001) found with the query into the template. Reply to this email
without modifying it and continue with step 9.
The email engine will create a Modify Key based on the information in the
Action, Form, and Request ID and add it to the email.
9 Open the email that you sent in the previous step using Outlook, or any other
client.
You will see that Request ID has a value of 00000000001 (if you used the
query, it will be substituted), and a Modify key has been added.
Login:
Password:
Key:

Action: Modify
Form: TestModify

Request ID: [$$00000000001$$]

!2!:
!8!:
!536870914!:

##Modify##:[$$POj2JJV9YHGlOtn1Rfew6rFEa1pFRbdweM3Bsu/
1I1++LShEzYnA3A==$$]

10 Reply to the email.

Note: It is important to reply to the same mailbox as the one from which the
email was sent.

11 In the reply, modify the parameters as required, for example add values in !2!
and !8!.
Do not change the Action, Form and Request ID label/value pairs.
12 Fill in any essential missing parameters—Login, Password (if there is a
password), and Key. You must type in the Key you specified in step 3 on
page 207.

212 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

13 Send the email reply with the modifications included.

The email will be parsed and then the form will be modified. You will receive
the confirmation message:
Instruction <number> has successfully modified the record with Request ID
#$$Request ID$$#.

You can do a search on the form to verify the result.

Sample templates

Email content template containing basic actions

In creating or modifying templates, any values that are defined before the
Action label are global and apply to all the actions specified. Any value
declared after the Action statement takes precedence over the global
definition for that action only. In the following example, the Schema and
Server label/value pairs are global, and therefore apply to both the Submit
and Query actions.

The mailbox was configured on the server to allow the following options:
„ Support incoming and outgoing emails
„ Parse incoming emails
„ Reply to sender with results
„ Use the incoming email address to calculate correct user name

This is the content template in plain text

#$$Company$$# received your WWW submission, and a new ticket has been
created. For future correspondence on this ticket, please respond to
this email or include the full Ticket ID in the subject line.

Service Request ID : #$$Request ID$$#

Prob Description : #$$Short Description$$#

The following included fields would need to be selected in the filter notify
action:

„ Company
„ Request ID
„ Short Description

Sample templates W 213

Action Request System 6.0

For more information on Include Fields, see the Developing AR System

Application: Basic guide.

Email reply with no template specified

The Remedy Email Engine replied with the following results:

Instruction: Submit
Instruction Number: 1
Instruction Template:

Request ID: 000000000000007

Submitter: $USER$
Create Date: Mon May 06 11:47:20 PDT 2004
Assigned To:
Last Modified By: EmailUser
Modified Date: Mon May 06 11:47:20 PDT 2004
Status: New
Short Description: Short Description
Status History: NewEmailUserMon May 06 11:47:20 PDT 2004

Check Box Field: Default 1

Time Field:
Date Field:
Currency Field: 5
Decimal Number Field: 34.44
Date/Time Field:
Radio Button Field: Value 4
Drop-Down List Field: Value 3
Real Number Field:
Integer Field: 10
Diary Field:
Character Field: Character Field
Attachment2:
Attachment:

Instruction: Query
Instruction Number: 2
Instruction Template:

Request ID: 000000000000007

Submitter: $USER$
Create Date: Mon May 06 11:47:20 PDT 2004
Assigned To:
Last Modified By: EmailUser
Modified Date: Mon May 06 11:47:20 PDT 2004
Status: New
Short Description: Short Description
Status History: NewEmailUserMon May 06 11:47:20 PDT 2004

214 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

Check Box Field: Default 1

Time Field:
Date Field:
Currency Field: 5
Decimal Number Field: 34.44
Date/Time Field:
Radio Button Field: Value 4
Drop-Down List Field: Value 3
Real Number Field:
Integer Field: 10
Diary Field:
Character Field: Character Field
Attachment2:
Attachment:

Figure A-5: Reply to action template using default format

The Query action returned the submit entry to the user because it was the
only entry in the record. There was no template defined as a Results
Template, so the Remedy Email Engine used the default internal text format.

Email reply using a result template in HTML format

To specify a Result Template, enter a global label/value pair at the top of the
template as in the following extract:

Schema: AR System Email Test Form

Server: galactica
Result Template: Result_template _name
....

Result template source:

<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-
1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Remedy Email Engine Test Template</title>
</head>

<body>
<p><img border="0" src="art/blue_header_thin_right.gif" >
<center><font face="Times New Roman" size="5"><b>Remedy Email Engine
Test Template</b></font></center></p>
<hr>
<p>This form was submitted by <u><b>#$$Submitter$$#</b></u> and the
relavent information is as follows for Instruction <font
size="5"><b>#$$Action.Name$$#</b></font>:</p>

Sample templates W 215

Action Request System 6.0

<table border="1" width="100%">

<tr>
<td width="50%"> Integer Field</td>
<td width="50%">#$$Integer Field$$#</td>
</tr>
<tr>
<td width="50%"> Character Field&nbsp;</td>
<td width="50%">#$$Character Field$$#</td>
</tr>
<tr>
<td width="50%"> Real Number Field</td>
<td width="50%">#$$Real Number Field$$#</td>
</tr>
<tr>
<td width="50%"> Date/Time Field</td>
<td width="50%">#$$Date/Time Field$$#</td>
</tr>
<tr>
<td width="50%"> Radio Button Field</td>
<td width="50%">#$$Radio Button Field$$#</td>
</tr>
</table>
</body>
</html>

The Result Template must be stored in the AR System Email Templates form
before it can be used in the email. See “Storing templates in the AR System
Email Templates form” on page 131. There is a graphic included, and as this
is not contained in the HTML file, the graphic must be added using the
Template Attachments tab of the AR System Email Templates form. See
“Adding attachments to templates” on page 132.

In this template, there are variables corresponding to a field on the

AR System Test Form on which the template is based (for example:
#$$Character Field$$#, #$$Radio Button Field$$#). The administrator only
specifies the fields in which he is interested. There is also a variable for
#$$Submitter$$# and a reserved variable: #$$Action.Name$$#. See
“Variables” on page 122 for more information about variables.

216 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

When you send your email, the Remedy Email Engine parses and executes
the instructions in the Results template. It formats the reply and substitutes
values for the variables. The reply looks as follows:

For more information on results templates, see Result Template on page 119.

Email status template in HTML format

The Status Template should be stored in the AR System Email Template
form and specified in the content template as a label/value pair:

Schema: AR System Email Test Form

Server: galactica
Status Template: StatusTemplateName
....

Sample templates W 217

Action Request System 6.0

Status template source:

<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html;
charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Status</title>
</head>
<body>
<p>Your instruction to the AR System server returned the
following errors:</p>
<table border="1" width="100%">
<tr>
<td width="25%">Error Number</td>
<td width="25%">Error Type</td>
<td width="25%">Error Text</td>
<td width="25%">Error Appended Text</td>
</tr>
##StatusRepeatStart##
<tr>
<td width="25%">#$$ActionStatus.Number$$#</td>
<td width="25%">#$$ActionStatus.Type$$#</td>
<td width="25%">#$$ActionStatus.Text$$#</td>
<td width="25%">#$$ActionStatus.AppendedText$$#</td>
</tr>
##StatusRepeatEnd##
</table>
<p>If you feel your instruction should not have generated an
error, please contact your Remedy Administrator.</p>
</body>
</html>

When you send your email, the Remedy Email Engine parses and executes
the instructions in the content template. The resulting status email will be
formatted like the following figure. The email engine substitutes values for
the variables.

For more information on status templates, see Status template on page 119.

218 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

Adding a header template and a footer template

For more information on Header and Footer templates, see page 120.

You can add a header and a footer template to the email by specifying a global
Label Value pair at the top of the template, as in the following extract:

Schema: AR System Email Test Form

Server: galactica
Result Template: Result Template
Header Template: Header Template
Footer Template: Footer Template
...

You can also add a header or footer template to an email by selecting it in the
relevant field of the Templates tab of the AR System Email Messages form.
The template fields on the AR System Email Messages form are used to
determine the templates used when creating an outgoing message. The label/
value pair method is used when requesting results from a server by way of
email.

In each case, you must add the templates to the Email Templates form before
it can be used in the email. See “Storing templates in the AR System Email
Templates form” on page 131. If there is a graphic included, the graphic must
be added using the Template Attachments tab of the AR System Email
Templates form, as explained in “Adding attachments to templates” on
page 132.

Sample templates W 219

Action Request System 6.0

Email content template in HTML format with a text field and a

reply using no template
The following example shows the previous action template in HTML, with
the addition of a text field for the character field.

The source is shown as follows:

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=windows-
1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>New Page 1</title>
</head>

<body>
<p>
Schema: AR System Email Unit Test Form<br>
Server: galactica<br>

220 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

<br>
Action: Submit<br>
# Values: Submit, Query<br>
Format: Short<br>
# Values: Short, Full<br>
<br>
Submitter ! 2!: $USER$<br>
Short Description ! 8!: Short Description</p>
<form method="POST" action="--WEBBOT-SELF--"><p>
Character Field: <input type="text" name="!536870919!" size="20"
value="User Defined"></p>
</form><p>
Integer Field !536870921!: 10<br>
Drop-Down List Field !536870923!: value 3<br>
# Values: Default 1, Value 2, Value 3, Value 4,<br>
# Value 5, Value 6<br>
Radio Button Field !536870924!: value 4<br>
# Values: Default 1, Value 2, Value 3, Value 4,<br>
# Value 5, Value 6<br>
Decimal Number Field !536870926!: 34.44<br>
Currency Field !536870927!: 5<br>
Check Box Field !536870930!: 0<br>
# Values: Default 1<br>
<br>
Action: Query<br>
Qualification: 1=1</p>
</body>
</html>

Since a Results template was not used, the reply will be in plain text.

Assigned To:
Last Modified By: EmailUser
Modified Date: Mon May 06 14:45:14 PDT 2004
Status: New
Short Description: Short Description
Status History: NewEmailUserMon May 06 14:45:14 PDT 2004

Check Box Field: Default 1

Time Field:
Date Field:
Currency Field: 5
Decimal Number Field: 34.44
Date/Time Field:
Radio Button Field: Value 4
Drop-Down List Field: Value 3
Real Number Field:
Integer Field: 10
Diary Field:
Character Field: User Defined
Attachment2:

Sample templates W 221

Action Request System 6.0

Attachment:

Instruction: Query
Instruction Number: 2
Instruction Template:

Request ID: 000000000000007

Submitter: $USER$
Create Date: Mon May 06 11:47:20 PDT 2004
Assigned To:
Last Modified By: EmailUser
Modified Date: Mon May 06 11:47:20 PDT 2004
Status: New
Short Description: Short Description
Status History: NewEmailUserMon May 06 11:47:20 PDT 2004

Check Box Field: Default 1

Time Field:
Date Field:
Currency Field: 5
Decimal Number Field: 34.44
Date/Time Field:
Radio Button Field: Value 4
Drop-Down List Field: Value 3
Real Number Field:
Integer Field: 10
Diary Field:
Character Field: Character Field
Attachment2:
Attachment:

The value for the Character Field, which is the actual name of the field, is set
to the value specified within the HTML text field when the submit action is
executed. You paste the entire template into an email client and change the
text field directly before sending this email.

Content template in XML format

The following example shows a content template in XML format.

<?xml version="1.0" encoding="UTF-8"?>

<Root>
<!--Submitter-->
<Field ID="!2!">#$$Submitter$$#</Field>
<!--Short Description-->
<Field ID="!8!">#$$Short Description$$#</Field>
<!--Character Field-->
<Field ID="!536870919!">#$$Character Field$$#</Field>
<!--Integer Field-->
<Field ID="!536870921!">#$$Integer Field$$#</Field>
<!--Drop-Down List Field-->

222 XAppendix A—Examples of email templates

 Remedy Email Engine Guide

<Field ID="!536870923!">#$$Drop-Down List Field$$#</Field>

<!--Radio Button Field-->
<Field ID="!536870924!">#$$Radio Button Field$$#</Field>
<!--Decimal Number Field-->
<Field ID="!536870926!">#$$Decimal Number Field$$#</Field>
<!--Currency Field-->
<Field ID="!536870927!">#$$Currency Field$$#</Field>
<!--Check Box Field-->
<Field ID="!536870930!">#$$Check Box Field$$#</Field>

Sample templates W 223

Action Request System 6.0

224 XAppendix A—Examples of email templates

Appendix

B Email engine installation

worksheet

Copy this worksheet and complete a separate worksheet for each email
engine you plan to install and configure. You will first be prompted for
information listed under Installation Prompt Information. If you decide to
configure the email engine during installation, you will then be prompted for
the information listed under the Email Configuration Information section of
this worksheet. Reproduce the worksheet as needed. This chapter includes
the following sections:
„ Installation prompt information (page 226)
„ Email configuration information (page 227)

Email engine installation worksheet W 225

Action Request System 6.0

Installation prompt information

You will be prompted for the following installation-related information
when you install the email engine:
1 UNIX only: Product directory name (UNIX) _________________________
This is the path to the cdrom mount directory.
2 UNIX only: Do you have Java 1.4.1_00 (or greater) installed on this system?
„ Yes
„ No (if you do not have the correct Java JRE installed, the installation
program exits when you enter N)
Installation directory of the Java 1.4.1_00 (or greater) program if it has
already been installed on this system (for example, /usr/java1.4.1/j2se):
Java 1.4.1_00 directory name: ____________________________________
For Linux and AIX platforms, additional .jar files are required so that the
email engine will run correctly. (For more information, see “Additional files
required for Linux and AIX installations” on page 55.)
3 Email engine installation directory (UNIX: this prompt is at the end)
___________________________________________________________
4 Name of the AR System server that the email engine will use:
Server name __________________________________________________
5 TCP port number (if AR System server is not using Portmapper) of your
AR System server: _____________________________________________
You enter this port number only if you did not register the AR System server
with a portmapper during your installation of the AR System server. For
more information, see Registering with a Portmapper in the Installing
AR System guide.
6 RPC port number (if you have configured a private server to use with the
email engine) of the AR System server: ____________________________
You enter this port number only if you did not register the AR System server
with a portmapper during your installation of the AR System server. For
more information, see Registering with a Portmapper in the Installing
AR System guide.

226 XAppendix B—Email engine installation worksheet

 Remedy Email Engine Guide

7 AR System administrator user name and password:

User name ___________________________________________________
Password: ___________________________________________________
This user must have administrative privileges in order to import forms and
set values in the ar.conf (UNIX) or ar.cfg (Windows) file to manage forms.
8 Application Service password
Password: ___________________________________________________
Required only if your system administrator already entered an Application
Service Password in AR System Administrator. To find out if there is a
password, in AR System Administrator, go to File > Server Information, click
the Connection Settings tab, and verify the Application Service Password
information. You also supply this password, if applicable, to install other
products, such as the Approval Server.

Email configuration information

This information is necessary for configuring your incoming and outgoing
mailboxes.

Incoming mailbox (Windows)

1 Incoming mailbox name
(required)________________________________________
2 Circle one of the following email server types:
„ POP3
„ IMAP4
„ MAPI

3 Are you using SSL (Secure Socket Layer)? Answer Yes or No.
„ Yes
„ No

This enables the secure socket layer. Select SSL only if you are using POP3 or IMAP4.
4 Email server name /IP___________________________________________
Name or IP address of the mail server used in your organization.

Email configuration information W 227

Action Request System 6.0

5 Email server port ______________________________________________

Port used for connecting to the mail server. The default port number is determined
by the protocol selected and whether Secure Sockets Layer (SSL) is selected.
If you do not enter a port number, the following default values will be used:
„ POP3: 110
„ POP3 with SSL: 995
„ IMAP4: 143
„ IMAP4 with SSL: 993
Not required for MAPI.
6 Email server user name __________________________________________
Username of the administrator or user for this email account. See your mail server
administrator for your designated email username. Not required for MAPI.
7 Email server password __________________________________________
Password associated with the user name for this email account. See your mail server
administrator for your designated email password. Not required for MAPI.
8 Email profile (MAPI only) ________________________________________
9 Email Windows account name (MAPI only)
______________________________
10 Email Windows account password (MAPI only)
___________________________
11 Email Windows account domain (MAPI only)
____________________________

Outgoing mailbox (Windows)

1 Outgoing mailbox name (required)
________________________________________
2 Display name ________________________________________________
Full email address of the administrator or owner of this mailbox. The email
address you specify will be the default From: email address in outgoing
emails. As a result, if you entered a Display Name of ARSystem and an email
address of [email protected], the From: line would look like:
From: ARSystem [[email protected]]
3 Email address ________________________________________________
Full email address of the administrator or owner of this mailbox.

228 XAppendix B—Email engine installation worksheet

 Remedy Email Engine Guide

4 Email server type ______________________________________________

Outgoing email: SMTP or MAPI
5 SSL (Secure Socket Layer)________________________________________
Enables the secure socket layer. SMTP only.
6 Email server name /IP___________________________________________
Name or IP address of the mail server used in your organization. SMTP only.
7 Email server port ______________________________________________
Number of the port used for connecting to the server where this mailbox is stored.
The default port number is determined by the protocol selected and whether Secure
Sockets Layer (SSL) is selected. Not required for MAPI.
If you do not enter a port number, the following default values will be used:
„ SMTP: 25
„ SMTP with SSL: 465
8 Email server user name __________________________________________
Username of the administrator or user for this mailbox. See your mail server
administrator for your designated email username. Not required for MAPI.
9 Email server password __________________________________________
Password associated with the user name for this mailbox. See your mail server
administrator for your designated email password. Not required for MAPI.
10 Email profile (MAPI only) ________________________________________
11 Email Windows account name (MAPI only)
______________________________
12 Email Windows account password (MAPI only)
___________________________
13 Email Windows account domain (MAPI only)
____________________________

General email (UNIX)

1 Are you using SSL (Secure Socket Layer)?
„ Yes
„ No

This enables the secure socket layer. Select SSL only if you are using POP3 or IMAP4.

Email configuration information W 229

Action Request System 6.0

Incoming mailbox (UNIX)

1 Incoming mailbox name ________________________________________
2 Incoming mailbox server name ___________________________________
Host name where your incoming mailbox is configured (normally the host
where AR System email is being installed).
3 Circle one of the following email server types:
„ POP3
„ IMAP4
„ MBOX

4 Email server port ______________________________________________

Port used for connecting to the server where this mailbox is stored. The default port
number is determined by the protocol selected and whether Secure Sockets Layer
(SSL) is selected.
An email server port is not required for MBOX.
If you do not enter a port number, the following default values will be used:
„ POP3: 110
„ POP3 with SSL: 995
„ IMAP4: 143
„ IMAP4 with SSL: 993
5 Email server user name __________________________________________
Username of the administrator or user for this email account. See your mail server
administrator for your designated email username. Not required for MBOX.
6 Email server password __________________________________________
Password associated with the user name for this email account. See your mail server
administrator for your designated email password. Not required for MBOX.
7 Incoming inbox path (MBOX only)_________________________________
Full path to the mbox file corresponding to the user email account that will
be used, for example, /usr/spool/ARSystem.
8 Incoming user home path (MBOX only)_____________________________
Full path of the user home directory, for example, /usr/ARSystem.

230 XAppendix B—Email engine installation worksheet

 Remedy Email Engine Guide

Outgoing mailbox (UNIX)

1 Outgoing mailbox name ________________________________________
2 Display name ________________________________________________
Name you want displayed in the From: line of the outgoing email.
3 Email address ________________________________________________
Full email address of the administrator or owner of this mailbox. The email
address you specify will be the default From: email address in outgoing
emails. As a result, if you entered a Display Name of ARSystem and an email
address of [email protected], the From: line would look like:
From: ARSystem [[email protected]]
4 Outgoing mailbox server name ___________________________________
Mail server name or IP address of the email server used in your organization. SMTP
only.
5 Email server type for outgoing email: SMTP only
6 Email server port ______________________________________________
Number of the port used for connecting to the mail server. The default port number
is determined by the protocol selected and whether Secure Sockets Layer (SSL) is
selected. If you do not enter a port number, the following default values will be used
for outgoing email: SMTP: 25
7 Email server user name __________________________________________
Username of the administrator or user for this email account. See your mail
server administrator for your designated email username.
8 Email server password __________________________________________
Password associated with the user name for this email account. Refer to your
mail server administrator for your designated email password.

Email configuration information W 231

Action Request System 6.0

232 XAppendix B—Email engine installation worksheet

Appendix

C Setting up UNIX mailboxes

You can use the following procedure to establish a mailbox address for the
UNIX email engine. These are meant only as generic guidelines. If you have
questions about implementation, you should consult your UNIX system
administrator for details.

To set up the AR System mailbox, you must have UNIX superuser (root user)
access on the UNIX server.

X To set up UNIX mailboxes:

1 Set up an ARSystem user account in the /etc/passwd file, as in the following
example (new entry in bold):
root:x:0:1:0000-Admin(0000):/:/sbin/sh
daemon:x:1:1:0000-Admin(0000):/:
bin:x:2:2:0000-Admin(0000):/usr/bin:
sys:x:3:3:0000-Admin(0000):/:
adm:x:4:4:0000-Admin(0000):/var/adm:
lp:x:71:8:0000-lp(0000):/usr/spool/lp:
smtp:x:0:0:mail daemon user:/:
uucp:x:5:5:0000-uucp(0000):/usr/lib/uucp:
listen:x:37:4:Network Admin:/usr/net/nls:
nobody:x:60001:60001:uid no body:/:
noaccess:x:60002:60002:uid no access:/:
ARSystem:x:50:10:AR System mail user:/home/ARSystem:/bin/sh

Setting up UNIX mailboxes W 233

Action Request System 6.0

2 Edit the /etc/aliases file and add the alias ARSystem with the mailbox of /usr/
spool/mail/ARSystem, as follows:
/etc/aliases file
#######################
# Local aliases below #
#######################
# Email Alias for AR System mailbox
ARSystem:/usr/spool/mail/ARSystem

You can also choose a different name, as needed.

Verify this step for your UNIX operating system; it may be different for your
platform. In particular, the path to your mail folder may be different from /
usr/spool/mail/.
Note: On some UNIX platforms, you need to run the newaliases command
to have the ARSystem aliases recognized. Refer to your UNIX System
Administration documentation or UNIX System administrator if you
have questions or problems. The email directory /usr/spool/mail will vary
between UNIX platforms.

3 Create the mailbox file you defined for this user in the /etc/aliases file or /usr/
lib/aliases file (HPUX), by performing the following command:
# touch /usr/spool/mail/ARSystem

4 Change the group name to daemon, or to the owner of the mailbox alias
name, as in the following example:
# chgrp daemon /usr/spool/mail/ARSystem

Note: The group name varies between UNIX platforms. For most UNIX
platforms, it is the group daemon, while on HPUX it is mail. To verify the
proper group name to use, check the group name for the mail directory by
using the command ls -ldg.

5 Change the mailbox permissions so it is readable and writable by all, as in the

following example:
# chmod 666 /usr/spool/mail/ARSystem
ls -laF /usr/spool/mail/ARSystem
-rw-rw-rw-- 1 daemon 0 May 30 16:55 /usr/spool/mail/ARSystem

234 XAppendix C—Setting up UNIX mailboxes

 Appendix

D Upgrading email option

parameters

This appendix contains a table of the AR System configuration parameters

used in the pre-5.1 Remedy Mail Server and their equivalents (if available) in
the 6.0 Remedy email engine.

Pre-5.1 Email Options Function 6.0 Email Engine

Address The address the mail process watches for „ MBOX: Address is defined by
(UNIX only) AR System messages. the inbox path (the default
mailbox is the mailbox for the
user that starts the email
engine).
„ POP3/IMAP4: Address is
defined by the email server user
name.
Default-Password The AR System password to use if no Must be specified by using a user
password is specified in the submitted instruction template.
message. For more information, see “User-
Defined instruction templates”
on page 138.
Note: The value that is set in the
user instruction template will
not be overwritten by the
incoming email.

Upgrading email option parameters W 235

Action Request System 6.0

Pre-5.1 Email Options Function 6.0 Email Engine

Default-Schema The form to use if no form is specified in the This is defined in the Default
submitted message. Workflow Form field in the
incoming mailbox Advanced
Configuration tab.
Default-Server The AR System server to use if no server is The AR System server that the
specified in the submitted message. email engine connects to that is
defined in the
emaildaemon.properties file.
Default-User The AR System login to use if there is no Must be specified by using a user
login specified in the submitted message. instruction template.
For more information, see “User-
Defined instruction templates”
on page 138.
Note: The value that is set in the
user instruction template will
not be overwritten by the
incoming email.
Include-Original- On- A flag indicating whether to include the full Not Used
Failure text of the original message in a reply to a
failed submission.
Include-Original- On- A flag indicating whether to include the full Not Used
Success text of the original message in a reply to a
successful submission. Valid values are T
and F.
MailNotifyDir Indicates the full path name for the mailntfy Not Used
(Windows only) directory that holds all of the email
notifications the server sends to the
armailex service. The armailex service
deletes them after they are processed.
Exchange-Profile The name given to the configuration of your This parameter is set in the
(Windows only) MS Exchange client’s operation. AR System Email Mailbox
Configuration form in the Basic
Configuration tab for MAPI
Email Server Type only.

236 XAppendix D—Upgrading email option parameters

 Remedy Email Engine Guide

Pre-5.1 Email Options Function 6.0 Email Engine

Exchange-Mailbox The MS Exchange mailbox name referenced This parameter is set in the
(Windows only) in your Exchange client’s profile AR System Email Mailbox
configuration (found in the MS Exchange Configuration form outgoing
Server properties, accessible through the mailbox in the Advanced
Control Panel mail icon). Configuration tab for MAPI
Email Server Type only.
Poll-Interval The number of seconds to wait between This parameter is set in the
polls to the mailbox to check for new AR System Email Mailbox
messages. The minimum interval is 5 Configuration form in the Basic
seconds. Configuration tab for each
mailbox.
Query-Match-Full Defines the maximum number of matches Not Used
that can be returned for a successful Full
Format search request. For example, if a user
submits a search request with Full Format
indicated and the search matches 120 items,
only the first 25 are returned.
Query-Match-Short Defines the maximum number of matches Not Used
that can be returned for a successful Short
Format search request. For example, if a user
submits a search request with Short Format
indicated and the search matches 120 items,
only the first 50 are returned.
Reply-Failure The email address to use for replies to failed Not Used
submissions. Use this to redirect replies for
failed submissions to a third party rather
than the message sender. This field only
applies to submissions, not searches.
To suppress replying to a failed submission,
do the following:
„ For UNIX, set the address to /dev/null
(or to an address directed to /dev/null in
the mail aliases file with a line such as
nobody: /dev/ null). Set Reply-Failure
to Discard if /dev/null does not work for
your system.
„ For Windows, set the address to Discard.

W 237
Action Request System 6.0

Pre-5.1 Email Options Function 6.0 Email Engine

Reply-Success The email address to use for replies to Not Used
successful submissions. Use this to redirect
replies for successful submissions to a third
party rather than the message sender. This
field only applies to submissions, not
searches.
To suppress replying to a successful
submission, do the following:
„ For UNIX, set the address to /dev/null
(or to an address directed to/dev/null in
the mail aliases file with a line such as
nobody: /dev/null).
„ For Windows, set the address to Discard.
Required-Schema The only form for which submissions are If the Force Default Workflow
accepted. If there is a Schema line in the form is set to Yes, then the Default
submitted message, it must contain this Workflow form will be the
form name, or the submission is rejected. If required schema.
there is no Schema line, the Default- Schema
setting in the configuration file must match
this form name, or the submission is
rejected.
SaveSentItem A flag indicating whether to save email items See “Configuring a sent mail
that AR System sends. Valid values for this folder (MAPI)” on page 92 and
option are T and F. The default value is F (do “Performance and configuration
not save sent items). settings” on page 191.
Required-Server The only server for which email message This can be enforced by setting
requests can be submitted. Messages are the application password or by
rejected if any other server is specified. using a security key.
Messages that do not specify a server are
rejected unless the Default-Server option is
defined. If you specify a required server and
a default server, you must use the same
server for both options. The default value is
no required server.
ExchangeNTDomain Windows only: Used during installation. The For information, see “Windows:
name of the domain in which the Exchange upgrading from Remedy mail
account resides. Do not modify this server to 6.0 email engine” on
parameter. page 43.

238 XAppendix D—Upgrading email option parameters

 Remedy Email Engine Guide

Pre-5.1 Email Options Function 6.0 Email Engine

ExchangeNTAccount Windows only: Used during installation. The For information, see “Windows:
name of the Exchange mail server account. upgrading from Remedy mail
Do not modify this parameter. server to 6.0 email engine” on
page 43.
ExchangeNTPassword Windows only: Used during installation. The For information, see “Windows:
encrypted password for the Exchange upgrading from Remedy mail
account. Do not modify this parameter. server to 6.0 email engine” on
page 43.
Email-Notify-From The sender name to use for filter-generated This is set by using the display
email notifications where no subject is name and email address fields on
specified. Only trusted email users may use the Advanced Configuration tab
this name. This field is limited to 29 in the outgoing mailbox.
characters.
LogoffSleep Not Used
Max-Notify-Mail-Line- Not Used
Len
UseDateCheckOnFrom A flag indicating whether to check the date Not Used
format when verifying new messages. In
general, this option exists for backward
compatibility only. Valid values for this
option are Y and N. The default value is N
(do not check date format).
Environment ARDATE The date and time format used by the Not Used
program.
„ UNIX only: This value consists of a string
of operators as defined by the strftime
library call. (Some combinations are
displayed successfully but cannot be
translated for input.) If you do not set this
variable, the system uses the date format
for the language specified by the LANG
environment variable.
„ Windows only: This value consists of a
string of operators as defined by Regional
Settings. If you do not set this variable, the
system uses the date format specified in
the Regional Settings of the user account
that runs the service.

W 239
Action Request System 6.0

Pre-5.1 Email Options Function 6.0 Email Engine

ARDATEONLY The date format used by the program. Not Used
„ UNIX only: This value consists of a string
of operators as defined by the strftime
library call. (Some combinations are
displayed successfully but cannot be
translated for input.) If you do not set this
variable, the system uses the date format
for the language specified by the LANG
environment variable.
„ Windows only: This value consists of a
string of operators as defined by Regional
Settings. If you do not set this variable, the
system uses the date format specified in
the Regional Settings of the user account
that runs the service.
ARRPC UNIX only: The specific RPC socket to The RPC socket that the email
communicate with during the run of the engine uses is defined in the
program. If no AR System server is running emaildaemon.properties file. If
on the identified socket, an error is returned, you want to define an RPC socket
and the program does not run in a template, see “Labels and
values used in the templates” on
page 113.

240 XAppendix D—Upgrading email option parameters

 Remedy Email Engine Guide

Pre-5.1 Email Options Function 6.0 Email Engine

ARTIMEONLY The time format used by the program. Not Used
„ UNIX only: This value consists of a string
of operators as defined by the strftime
library call. (Some combinations are
displayed successfully but cannot be
translated for input.) If you do not set this
variable, the system uses the date format
for the language specified by the LANG
environment variable.
„ Windows only: This value consists of a
string of operators as defined by Regional
Settings. If you do not set this variable, the
system uses the date format specified in
the Regional Settings of the user account
that runs the service.
MAIL UNIX only: The directory where email files This is set using the inbox path. If
are stored. The default is /usr/ mail (HP and the inbox path is not set, then we
Solaris) or /var/spool/mail (IBM). will use this environment
variable.

W 241
Action Request System 6.0

242 XAppendix D—Upgrading email option parameters

Appendix

E Email engine forms

The Remedy Email Engine provides a set of administration, user, and

workflow forms for configuring and processing email from your mail server.
These forms are generated during installation and imported when you restart
your AR System server.

Note: If all of the email forms were deleted for any reason, they are imported
automatically by default when the AR System server is restarted. You can
prevent them from being imported by default when the AR System server
is restarted. To do so, go to the ar.conf (ar.cfg) file and set the option Email-
Import-Form-By-Default to F. For more information, refer to “Email
options in the AR System configuration file” on page 103.

If some, but not all, of the forms were deleted previously, a message will
appear when you restart the AR System server, informing you that you
must import those forms manually.

Email engine forms W 243

Action Request System 6.0

Table E-1 describes the administration forms available with the email engine.

Table E-1: Email administration forms

Administration Form Description

Name
AR System Email Used to create mailboxes and specify their use. For each
Mailbox Configuration mailbox, the form provides a name and email address for
the mailbox administrator, actions associated with the
mailbox, connection and security provisions, and
defaults.
For more information, see “Working with the mailbox
configuration form” on page 75.
AR System Email Used to create, display, and modify templates applied to
Templates email messages. You can use this form to create standard
templates that users can access for creating specific types
of messages.
For each template, this form provides: the unique
template ID; the format used, a name and description for
the template; the language encoding used; and
information about attachments associated with this
template.
For more information, see “About email templates” on
page 106.
AR System Email User Used to store administrator-defined instructions for
Instruction Templates specific actions, and to associate those instructions with
a template defined in the AR System Email Templates
form. These instructions can include variables whose
values are provided when the instructions are executed.
For each instruction template, the form provides the
template name, name of the mailbox with which the
instructions are associated, and the instructions
themselves.
For more information, see Chapter 4, “Email templates.”

244 XAppendix E—Email engine forms

 Remedy Email Engine Guide

Table E-1: Email administration forms

Administration Form Description

Name
AR System Email Error Used to store logs of errors that have occurred during
Logs email transmissions, as well as all incoming and outgoing
mail messages, log connection status information for
email servers and the AR System server, start and stop
times for the email engine, and configuration changes.
Each log entry includes the ID for the mailbox and
message, the message type, message number, how the
error message was generated, and the text of the error
message.
For more information, see “Error and system status logs”
on page 182.
AR System Email Used to either create and enable or disable security keys
Security for incoming mail. A security key can be assigned to an
individual incoming mailbox, or to all incoming
mailboxes.
For more information, see “Creating email security keys
for incoming mail” on page 100.

W 245
Action Request System 6.0

Table E-2 describes the user forms available with the email engine.

Table E-2: Email user forms

User Form Name Description

AR System Email Used to store information for outgoing and incoming
Messages email messages. Each message is stored as an entry in the
AR System Email Messages form.
For each message, this form provides the name of the
mailbox from which the message was generated, the
message type, name and organization of the mailbox
owner; names of recipients sent to and copied; the text of
the message (in either HTML, plain text format, or a
combination of both), and (under a separate tab) a list of
any attachments included with the message.

246 XAppendix E—Email engine forms

 Remedy Email Engine Guide

Table E-2: Email user forms

User Form Name Description

AR System Email Used to create, display, and modify information about
Attachments attachments used with emails and templates, including
incoming email. For each attachment, the form provides
a unique ID, the type of attachment (for example, a text
file), the name of the attachment, whether the
attachment is an email attachment or a template
attachment, the filename, size, and label.
Administrators can access this form from the Template
form if an attachment is needed for a new template.
Users can access attachments from this form when they
compose an email message.
AR System Email Used by the Remedy Email Engine for mapping
Attachment Join form attachments to email messages.
Warning: Because this information is used internally by
the email engine, you should not create or modify entries
in this form.

Table E-3 describes the workflow forms available with the email engine.

Table E-3: Email workflow forms

Workflow Form Name Description

AR System Email Used to store instructions obtained when incoming
Instructions email is parsed.
Warning: Because this information is used internally by
the email engine, you should not create or modify entries
in this form.

W 247
Action Request System 6.0

Table E-3: Email workflow forms

Workflow Form Name Description

AR System Email Used to store parameters specified for administrator-
Instruction Parameters defined instructions.
Warning: Because the information in this form is used
internally by the email engine to store instructions, you
should not create or modify entries in this form.
AR System Email Used to store associations between an email message and
Association one or more attachments, or between a template and one
or more attachments.
„ For incoming messages, this information includes the
association between the message and any attachments
included with the message.
„ For outgoing messages, this information includes
associations for attachments that should be included
when the message is sent.
For each association, the form provides:
„ Unique ID.
„ Source type (email or template). If the source type is
template, the form reflects the association between a
template and any attachments that should be included
when that template is used. An example is an HTML
template with graphics that must be included to
ensure that the message is displayed correctly.
„ Source ID (the ID of the email or template).

„ Destination type (email attachment).

„ Destination ID (the ID of the attachment).

This association enables multiple emails to be associated

with one attachment, or one email to be associated with
multiple attachments.
Warning: Because this information is used internally by
the email engine, you should not create or modify entries
in this form.

248 XAppendix E—Email engine forms

Index

A AR System Email
Action configuration 83, 84 Association form 248
actions Attachment Join form 247
modify 117 Attachments form 134, 154, 247
email template example 206 Configuration form 137
query 117 Error Logs form 182, 245
examples 202 Instruction Parameters form 248
submit 116 Instructions form 247
user-defined 118 Mailbox Configuration form 75, 244
adding Messages form 149, 158, 160, 246
attachment alternative 161 Security form 101, 245
attachments Templates form 131, 244
previously saved 135, 155 User Instruction Templates form 140, 244
to email 152 AR System Email Engine. See email engine
templates 131 ar.cfg, email options in 103
to email 157 ar.conf file, email options in 103
advanced configuration 76, 82, 88 associated mailbox 82, 89
incoming mailbox 82 Association form 248
outgoing mailbox 88 association, email 248
advanced options, displaying in AR System Email Attachment Alternatives tab, AR System Email
Messages form 156 Messages form 160
Advanced Search bar 118 Attachment Join form 247
application service password 190 attachments
AR System adding
API errors 184 alternative 161
email notifications 169 previously saved 135, 155
sending an email to 162 to email 152, 247
server version 24, 28 deleting 136, 156
exporting templates with, to another server
136
modifying 135, 155

Index W 249
Action Request System 6.0

Attachments form 134, 154, 247 server name 79, 86

authentication server password 80, 87
incoming mail security 85 server port 80, 86
SMTP 87 SSL 36, 41, 55, 57, 61, 66, 79, 86
TCP port 30, 45, 53, 65
B Content template 157
basic configuration 76 creating
basic format, templates 127 instruction templates 140
mailboxes 75, 76
C security keys 100
configuration templates 110, 130
Action configuration 83, 84 user-defined instruction templates 139
advanced 76, 82, 88
associated mailbox 82, 89 D
basic 76 date formats in email templates 125
creating a security key 100 debugging
creating and configuring mailboxes 75 options in logging.properties file 187
default addressing 90 UNIX email engine 198
default workflow form 84 Windows email engine 195
email notifications 170 default
email options in ar.conf or ar.cfg file 103 addressing 90
emaildaemon.properties file 191 email mailbox 150
enable modify actions 83 importing forms by 103
incoming emails 78, 79, 81, 86, 87 templates 90
incoming mailbox (UNIX) 230 workflow form 84
incoming mailbox (Windows) 227 display name, for mailboxes 89
Mailbox Configuration form 75, 244 displaying date, time, or numeric values,
mailbox, implementing 91 in notifications 179
outgoing email 88 -Dmail.debug=true debug option
outgoing mailbox (UNIX) 231 UNIX 198
outgoing mailbox (Windows) 228 Windows 195
overview of 74 domains, Windows 26
polling interval 78, 79, 81, 86, 88
profile name 78 E
prompts worksheet 227 email
Remedy Mail Server configuration parame- adding saved attachments 155
ters, using in email engine 235 address, for mailboxes 89
reply 83, 90 administration forms 244
RPC port 30, 45, 53, 65 attachments 152
security 99 configuration information overview 74
incoming email 84 deleting an attachment 156
key 84 email security
outgoing email 102 incoming email 84
sent mail folder 92 outgoing email 102
sent mail folder (MAPI) 92

250 XIndex
 Remedy Email Engine Guide

forms, list of errors 184

AR System Email Association 248 heap size, defining 72
AR System Email Attachment Join 247 installation
AR System Email Attachments 134, 154, UNIX 50, 62
247 Windows 29, 43
AR System Email Error Logs 245 installation overview 24
AR System Email Instruction Parameters installation prompts worksheet 226
248 installed files 69
AR System Email Instructions 247 new mailbox, creating 76, 85
AR System Email Mailbox Configuration notification mailbox 85
75, 244 overview 16
AR System Email Messages 149, 158, 160, pre-5.1 templates, using 83
246 preinstallation considerations 23, 24
AR System Email Security 101, 245 Remedy Mail Server configuration parameters
AR System Email Templates 131 235
AR System Email User Instruction Tem- sample scenario 20
plates 140, 244 security keys, creating 100
incoming 78, 79, 81, 82, 86, 87 starting 70
installation stopping 70
ESD 29, 44 terminology 18
UNIX 50, 62 upgrading from 28
Windows 29, 43 email forms, list of AR System Email Templates
modifying an attachment 155 244
notifications, configuring 170 email notifications, configuring 170
priority in sending 151, 172 email querying AR System 166
receiving 16 email request processing, troubleshooting 186
security keys, creating 100 email server
sending 16 port 80
to the AR System 162 user 80, 87
special forms 243 email templates
templates, exporting 111 date formats 125
user forms 246 modify action 206
workflow forms 247 searching for fields with 203
email engine searching for requests with 202, 204
configuration 73 emaildaemon.properties file
configuration worksheet 227 performance and configuration 191
defined 16 specifying sent mail folder in 92
email association 248 updating 189
email attachments 247 error logs 182
email instruction parameters 248 form 245
email messages 246 overview 182
email security 99, 245 Error Logs form 245
incoming 84
outgoing 102
email templates 244

Index W 251
Action Request System 6.0

errors AR System Email Instructions 247

AR System API 184 AR System Email Mailbox Configuration 75,
internal email engine 184 244
logs 182 AR System Email Messages 149, 158, 160, 246
Errors tab, AR System Email Messages form 162 AR System Email Security 101, 245
ESD (Electronic Software Distribution), installa- AR System Email Templates 131, 244
tion AR System Email User Instruction Templates
UNIX 51, 63 140, 244
UNIX upgrade 63
Windows 29 G
Windows upgrade 44 global fields and variables 124
expiration date, security key 102 global parameter declarations
exporting email templates 111 in templates 122
glossary of key terms 18
F
failures, transmission or instruction 184 H
files Header template 90, 120, 219
emaildaemon.properties 189 heap size, defining for email engine 72
installed 69 HTML (Hypertext Markup Language) format,
logging.properties 187 templates 128
required for AIX and Linux 55
UNIX 70 I
Windows 69 IMAP4
folder, sent mail 92 configuring during installation 35
Footer template 91, 120, 219 configuring during installation (UNIX) 57
force default workflow form option 84 defined 17
formats, template incoming mailbox, configuring 78
basic 127 Microsoft Exchange Server and 186
HTML 128 port number 80
label and values 127 importing forms by default 103, 243
variables 127 inbox path, MBOX 81
XML 128 incoming email 78, 79, 81, 82, 86, 87
forms advanced configuration 82
administration forms 244 security 84
default workflow form 84 incoming mailbox
importing by default 243 advanced configuration 82
special forms 243 configuration information (UNIX) 230
user forms 246 configuration information (Windows) 227
workflow forms 247 configuration, testing 93
forms, list of configuring IMAP4 during installation 35
AR System Email Association 248 configuring IMAP4 during installation
AR System Email Attachment Join 247 (UNIX) 57
AR System Email Attachments 134, 154, 247 configuring MAPI during installation 33
AR System Email Error Logs 245 configuring MBOX during installation
AR System Email Instruction Parameters 248 (UNIX) 59

252 XIndex
 Remedy Email Engine Guide

configuring POP3 during installation 35 L

configuring POP3 during installation (UNIX) label aliases
58 Encryption and Encryption Key 121
defined 76 Entry ID, EntryID, and RequestID 121
IMAP4, configuring 78 Footer and Footer Template 120
MAPI, configuring 77 Header and Header Template 120
MBOX, configuring 80 Query and Search 118
POP3, configuring 78 Result and Result Template 119
security key, creating 100 RPC Number 115
installation Schema 114
email engine Status and Status Template 119
ESD 29, 44 TCP 115
UNIX 50, 62 User, User Name, Name and Login Name 115
files required for Linux and AIX 55 labels
MAPI preinstallation 25 Action 116
MBOX preinstallation 27 Authentication 115
multiple servers 30, 45, 53, 64 Footer Template 120
non-root 56 Form 114
overview steps 24 Format 118
prompts worksheet 226 Header Template 120
instruction or transmission failures 184 Instruction 116
Instruction Parameters form 248 Key 121
Instructions form 247 Language 115
internal email engine errors 184 Login 115
Internet Message Access Protocol. See IMAP4 !Name/ID! 120
IP address, email server 79, 86 Password 115
Qualification 118
J Request ID 121
Java Result Template 119
archive files installed 69 RPC 115
email engine 69 Server 114
files required for Linux and AIX 55 Status Template 119
JRE directory 56 TCP Port 115
SSL 79 variables, substituting with 124
version required 52, 64 labels and values
version required, worksheet UNIX 226 defined 113
format, templates 127
K local parameter declarations
key, security 84, 100, 101 in templates 122
keywords, using in content templates for outgoing local system accounts 71
emails in notifications 177 email engine service 94

Index W 253
Action Request System 6.0

logging 162 mechanism, in notifications 172

AR System Email Error Logs form 182 Message Information tab, AR System Email
debugging 187 Messages form 162
errors 182 messages
severity levels 183 AR System Email Messages form 246
system status 182 content, determining 161
logging.properties file 187 overview 148
sending 149
M system-generated, saving 92
Mailbox Configuration form 75, 244 Messages form 149, 158, 160, 246
mailboxes Messaging Application Programming. See MAPI
associated mailbox 82, 89 Microsoft Exchange profile 88
configuration, implementing 91 MIME (Multipurpose Internet Mail Exchange) 17
configuration, testing 93 modify actions 117
configuring, templates 90 email template example 206
creating and configuring 75 enabling 83
creating new 76, 85 modify key 117, 206
default 150 multiple servers, installing with 30, 45, 53, 64
addressing 90 Multipurpose Internet Mail Exchange. See MIME
templates 90
default templates 136 N
display name 89 non-root installations UNIX 56
email address 89 notifications 169
incoming, defined 76 displaying date, time, or numeric values 179
Mailbox Configuration form 75 keywords, using in content templates for out-
notification mailbox 85 going email 177
outgoing, defined 85 mailbox 85
UNIX AR System mailbox, setting up 233 mechanism 172
MAPI permissions 173, 176
configuring during installation 33 processing 16
configuring outgoing mailbox during installa- submit execute condition 169
tion 37 text 171
defining 17 user name 171
incoming mailbox, configuring 77
local system account 71
outgoing mailbox, configuring 87
preinstallation steps for using 25
reply to address and login 90
sent mail folder, configuring 92
MBOX
configuring during installation (UNIX) 59
defining 17
incoming mailbox, configuring 80
preinstallation 27
preinstallation steps for using 27

254 XIndex
 Remedy Email Engine Guide

O port
outgoing email 149 default 86
advanced configuration 88 email server 80
security for 102 installing with multiple servers 30, 45, 53, 64
outgoing mailbox Post Office Protocol. See POP3
advanced configuration 88 preinstallation
configuration information (UNIX) 231 considerations for AR System Email Engine
configuration information (Windows) 228 23, 24
configuration, testing 96 steps
configuring MAPI during installation 37 for using MAPI 25
configuring SMTP during installation 40 for using MBOX 27
configuring SMTP during installation (UNIX) priority of emails sent 151, 172
60 processing notifications 16
defined 85 profile name 78, 88
MAPI, configuring 87 protocols
SMTP, configuring 86 IMAP4 17, 80, 186
overview email engine 16 MAPI 17
MBOX 17
P POP3 17, 80, 186
parameters SMTP 17, 186
email instruction 248
startup 190 Q
templates 122 query
password actions 117
application service 190 examples 202
email server 80, 87 performance 161
path
inbox 81 R
user name 81 receiving email 16
performance Remedy Mail Server
emaildaemon.properties 191 configuration parameters 235
queries, optimizing 161 templates, using in email engine 83
permissions upgrading to 6.0 email engine 43
notifications 173, 176 reply to address, MAPI 90
verifying for Windows account 185 reply, configuring 90
polling interval 78, 79, 81, 86, 88 requests, submitting across time zones 185
POP3 Result template 91, 119
configuring during installation 35 example 215
configuring during installation (UNIX) 58 RPC port
default port number 80 configuring 30, 45, 53, 65
defined 17 installing with multiple servers 30, 45, 53, 64
incoming mailbox, configuring 78
Microsoft Exchange Server and 186

Index W 255
Action Request System 6.0

S startup parameters 190

sample scenario email engine 20 status
Secure Sockets Layer. See SSL information
security in templates 126
authentication 85 variables 126
email 99, 245 messages 162
incoming email 84 Status template 91, 119
keys, using with incoming mail 84 example 217
outgoing email with query actions 102 submit actions 116
security key 84, 100, 101 notifications 169
expiration date 102 submitting requests across time zones 185
Security form 101, 245 system status logs 182
sending
email 16 T
to the AR System 162 TCP port
outgoing email 149 configuring 30, 45, 53, 65
sent mail folder, specifying 92 templates 106, 111
See also emaildaemon.properties file 92 adding 131
server name, configuration 79, 86 AR System Email Templates form 131
server password, configuration 87 attachments 132
server port configuring
configuration 80 default 90
default 86 Footer template 91
server user 80 Header template 90
servers, port numbers with multiple 30, 45, 53, 64 Result template 91
services Status template 91
local system account 71 Content 157
local system account with email engine 94 creating 107, 110, 130
setting mailbox defaults 136 date formats 125
Simple Mail Transfer Protocol. See SMTP defined 106
SMTP deleting attachments 136
configuring outgoing mailbox during installa- example 130
tion 40 examples 213–220
configuring outgoing mailbox during installa- existing or old, using 83
tion (UNIX) 60 exporting 111
defined 17 exporting with attachments to another server
gateway 186 136
outgoing mailbox, configuring 86 Footer 120, 219
SSL formats
configuration 36, 41, 55, 57, 61, 66, 86 basic 127
Java 79 HTML 128
starting and stopping the email engine labels and values 127
configuration changes, implementing 91 variables 127
UNIX 70 XML 128
Windows 70 Header 120, 219

256 XIndex
 Remedy Email Engine Guide

incoming email 107 upgrading

instruction 138 from 5.1.x email engine 28
creating 140 from Remedy Mail Server 43
label aliases. See label aliases pre-5.1 templates, using 83
labels and values 113 User Instruction Templates form 140, 244
formats 127 user name field, in notifications 171
labels. See labels user name path, MBOX 81
modifying 130 user, email server 80, 87
modifying attachments 135 user-defined actions 118
original templates, using 83 User-Defined Instruction templates
outgoing email 107 defined 109
overview 106 overview 138
parameters 122 users, trusted email 239
pre-5.1, using 83
reserved variables 126 V
Result 119 values
example 215 defined 113
setting defaults for specific mailboxes 136 format, templates 127
Status 119 variables 122
example 217 Variable Replacement tab, AR System Email Mes-
storing 109, 131 sages form 158
types of 106 variables
User-Defined Instruction 109, 138 field values and qualifications, using with 124
using after an upgrade 145 formats 127
variables 122 in templates 122
formats 127
Templates form 131, 244 W
terminology 18 Windows
testing mailbox configuration 93 debugging email engine 195
text field, in notifications 171 domains 26
time zones, submitting requests across 185 email installation ESD 29, 44
transmission or instruction failures 184 files installed 69
troubleshooting servers, troubleshooting for 185
email request processing 186 workflow form, default 84
for Windows servers 185 worksheet
notify filters 186 configuration prompts 227
trusted email users 239 installation prompts 226

U X
UNIX XML (Extensible Markup Language) format, tem-
AR System mailbox, setting up 233 plates 128, 222
debugging email engine 198
files installed 70
installation 50, 62
installation non-root 56

Index W 257
Action Request System 6.0

258 XIndex
*AR-600-EEG-01*
*AR-600-EEG-01*
*AR-600-EEG-01*
*AR-600-EEG-01*
*AR-600-EEG-01*