BMC® Remedy® Action Request System® 7.

0
Administering BMC Remedy
Email Engine

May 2006
Part No: 58475
Copyright 2006 BMC Software, Inc. All rights reserved.

BMC, the BMC logo, all other BMC 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.

BMC Software, Inc., 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 product download page.

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 Us
If you need technical support for this product, contact Customer Support by email at support@remedy.com.
If you have comments or suggestions about this documentation, contact Information Development by
email at doc_feedback@bmc.com.

This edition applies to version 7.0 of the licensed program.

BMC Software, Inc.

www.bmc.com
Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . 10
Learn about the AR System Developer Community . . . . . . . . . . . . 12
Why should you participate in the Developer Community? . . . . . . . . 12
How do you access the Developer Community? . . . . . . . . . . . . . 12

Chapter 1 Overview of the BMC Remedy Email Engine . . . . . . . . . . . . 13

About the BMC Remedy Email Engine . . . . . . . . . . . . . . . . . . 14
Email engine terminology . . . . . . . . . . . . . . . . . . . . . . . 16
Overview—How the email engine works . . . . . . . . . . . . . . . . . 18
Overview—Improving the appearance of your email. . . . . . . . . . . . 21

Chapter 2 BMC Remedy Email Engine installation and setup . . . . . . . . . 25

Preinstallation steps . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Entering information into the installation worksheet . . . . . . . . . . . 26
Reviewing documentation . . . . . . . . . . . . . . . . . . . . . . 26
Installing components . . . . . . . . . . . . . . . . . . . . . . . 26
Windows—Preinstallation tasks . . . . . . . . . . . . . . . . . . . 27
UNIX—Preinstallation tasks . . . . . . . . . . . . . . . . . . . . . 31
Windows—Installing the email engine . . . . . . . . . . . . . . . . . 32
Loading the software . . . . . . . . . . . . . . . . . . . . . . . . 32
Installing the email engine . . . . . . . . . . . . . . . . . . . . . . 33

Contents
3
BMC Remedy Action Request System 7.0

UNIX—Installing the email engine . . . . . . . . . . . . . . . . . . . 41

Loading the software . . . . . . . . . . . . . . . . . . . . . . . . 41
Installing the email engine . . . . . . . . . . . . . . . . . . . . . . 41
Postinstallation steps . . . . . . . . . . . . . . . . . . . . . . . . . 47
Starting and stopping the email engine . . . . . . . . . . . . . . . . . 47

Chapter 3 Configuring mailboxes in the BMC Remedy Email Engine . . . . . 51

Overview—Email configuration . . . . . . . . . . . . . . . . . . . . 52
Configuring outgoing mailboxes . . . . . . . . . . . . . . . . . . . . 53
Basic outgoing mailbox configuration . . . . . . . . . . . . . . . . . 54
Advanced outgoing mailbox configuration . . . . . . . . . . . . . . . 56
Configuring incoming mailboxes . . . . . . . . . . . . . . . . . . . . 59
Basic incoming mailbox configuration . . . . . . . . . . . . . . . . . 59
Advanced incoming mailbox configuration . . . . . . . . . . . . . . . 61
Testing your mailbox configuration . . . . . . . . . . . . . . . . . . . 65
Testing your outgoing mailbox . . . . . . . . . . . . . . . . . . . . 65
Testing your incoming mailbox . . . . . . . . . . . . . . . . . . . . 67
Configuring email security . . . . . . . . . . . . . . . . . . . . . . . 69
Configuring incoming mailbox security . . . . . . . . . . . . . . . . 69
Configuring outgoing mailbox security . . . . . . . . . . . . . . . . 71
Configuring the email engine for replying with results . . . . . . . . . . 72
Configuring the email engine for modify actions . . . . . . . . . . . . 73
MAPI—Saving outgoing notifications . . . . . . . . . . . . . . . . . . 75
Changing the form entry interval time . . . . . . . . . . . . . . . . . . 76
Configuring SSL for the email engine . . . . . . . . . . . . . . . . . . 76

Chapter 4 Outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Overview—How outgoing email works . . . . . . . . . . . . . . . . . 82
Using outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . 84
Using notifications . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Defining workflow to send email notifications . . . . . . . . . . . . . 86
Dynamically assigning templates to outgoing email . . . . . . . . . . . 99
Displaying date/time or numeric values in email notifications . . . . . . 104
Deleting email notifications . . . . . . . . . . . . . . . . . . . . 104
Using templates with outgoing email . . . . . . . . . . . . . . . . 105

4 Contents
 Administering BMC Remedy Email Engine

Using the Email Messages form to send outgoing email . . . . . . . . . . 108

Sending outgoing email in plain text . . . . . . . . . . . . . . . . 109
Sending outgoing email in HTML . . . . . . . . . . . . . . . . . . 111
Including attachments with outgoing email . . . . . . . . . . . . . . 114
Displaying advanced options for outgoing email . . . . . . . . . . . 117
Determining message content of outgoing email . . . . . . . . . . . 125
Sending reply email—Giving a professional look to outgoing email . . . . . 126
Using header templates as a banner with outgoing email . . . . . . . . 129
Using HTML result templates with outgoing email . . . . . . . . . . . 131
Using XML result templates with outgoing email . . . . . . . . . . . 135
Using HTML content templates with outgoing email . . . . . . . . . . 137
Using status templates with outgoing email . . . . . . . . . . . . . . 138

Chapter 5 Incoming email . . . . . . . . . . . . . . . . . . . . . . . . . 141

Overview—How incoming email works . . . . . . . . . . . . . . . . . 142
Using incoming email . . . . . . . . . . . . . . . . . . . . . . . . . 143
Sending a query instruction to the email engine . . . . . . . . . . . . . . 144
Including qualifications in your email . . . . . . . . . . . . . . . . 148
Using “shorthand” qualification syntax . . . . . . . . . . . . . . . 149
Using the Format label. . . . . . . . . . . . . . . . . . . . . . . 149
Sending a submit instruction to the email engine . . . . . . . . . . . . . 150
Using keywords . . . . . . . . . . . . . . . . . . . . . . . . . 153
Using the Format label . . . . . . . . . . . . . . . . . . . . . . 153
Including attachments with incoming email. . . . . . . . . . . . . . 154
Sending a modify instruction to the email engine . . . . . . . . . . . . . 154
Overview—How modify instructions work with incoming email . . . . . 155
Sending modify instructions in plain text . . . . . . . . . . . . . . 157
Sending modify instructions in HTML . . . . . . . . . . . . . . . . 161
Additional restrictions . . . . . . . . . . . . . . . . . . . . . . 165
Overview—Using workflow to modify requests . . . . . . . . . . . . . . 166
Searching for an entry to modify—Advanced solution . . . . . . . . . . . 174
Using variables with templates . . . . . . . . . . . . . . . . . . . . . 177
Displaying advanced options for incoming email . . . . . . . . . . . . . 178
Message Information tab. . . . . . . . . . . . . . . . . . . . . . 180
Errors tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Contents
5
BMC Remedy Action Request System 7.0

Chapter 6 Using email templates . . . . . . . . . . . . . . . . . . . . . 183

Overview—Email templates . . . . . . . . . . . . . . . . . . . . . . 184
Types of templates . . . . . . . . . . . . . . . . . . . . . . . . 185
Creating templates. . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Exporting mail templates. . . . . . . . . . . . . . . . . . . . . . 188
Using label/value pairs in templates . . . . . . . . . . . . . . . . . . . 191
Form label . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Server label . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Login, Password, and TCP Port labels . . . . . . . . . . . . . . . . 193
RPC Number and Authentication labels . . . . . . . . . . . . . . . 193
Language label . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Action label . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Format label . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Qualification label . . . . . . . . . . . . . . . . . . . . . . . . 197
Result Template label . . . . . . . . . . . . . . . . . . . . . . . 197
Status Template label . . . . . . . . . . . . . . . . . . . . . . . 198
Header Template and Footer Template labels . . . . . . . . . . . . . 198
!Name! or !ID! labels . . . . . . . . . . . . . . . . . . . . . . . 199
Key label . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Request ID label . . . . . . . . . . . . . . . . . . . . . . . . . 200
Label/value pair formats . . . . . . . . . . . . . . . . . . . . . . 200
Global and local parameter declarations . . . . . . . . . . . . . . . 203
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Additional tips when creating or modifying templates . . . . . . . . . 209
Storing templates in the AR System Email Templates form . . . . . . . . . 209
Adding attachments to HTML templates . . . . . . . . . . . . . . . . . 211
Adding a previously saved attachment to your template. . . . . . . . . 213
Modifying an attachment . . . . . . . . . . . . . . . . . . . . . 214
Deleting an attachment . . . . . . . . . . . . . . . . . . . . . . 214
Exporting templates with attachments to another server . . . . . . . . 215
Preparing email templates after an upgrade . . . . . . . . . . . . . . . . 215
Overview—Sending incoming email with user instructions . . . . . . . . 216
Creating and storing a template for use with user instructions . . . . . . 219
Creating user instructions . . . . . . . . . . . . . . . . . . . . . 220
Sending a user instruction in an incoming email . . . . . . . . . . . 222

6 Contents
 Administering BMC Remedy Email Engine

Results of the user instruction . . . . . . . . . . . . . . . . . . . 222

Using variables with user instructions . . . . . . . . . . . . . . . . 224

Chapter 7 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . 225

Troubleshooting outgoing email . . . . . . . . . . . . . . . . . . . . 226
Email engine architecture . . . . . . . . . . . . . . . . . . . . . . . 227
Error and system status logs . . . . . . . . . . . . . . . . . . . . . . 229
Email transmission or instruction failures . . . . . . . . . . . . . . 230
AR System API errors . . . . . . . . . . . . . . . . . . . . . . . 231
Internal email engine errors . . . . . . . . . . . . . . . . . . . . 231
Debugging options for the BMC Remedy Email Engine . . . . . . . . . . 231
Using the EmailDaemon.properties file . . . . . . . . . . . . . . . . . 233
Updating the EmailDaemon.properties file . . . . . . . . . . . . . . 235
Performance and configuration settings . . . . . . . . . . . . . . . 236
Creating email debug batch files . . . . . . . . . . . . . . . . . . . . 242
Windows—Debugging the email engine . . . . . . . . . . . . . . . 242
UNIX—Debugging the email engine . . . . . . . . . . . . . . . . . 245
Fixing common problems with the email engine . . . . . . . . . . . . . 248
Configuring mailboxes . . . . . . . . . . . . . . . . . . . . . . 248
Logging problems with the email engine . . . . . . . . . . . . . . . 250
Defining a heap size for the email engine . . . . . . . . . . . . . . . 252
Troubleshooting startup issues . . . . . . . . . . . . . . . . . . . 253
Determining problems with the mail server . . . . . . . . . . . . . . 256
Stopping and starting the AR System server . . . . . . . . . . . . . . 259
Making changes to mailbox configuration . . . . . . . . . . . . . . 259
Submitting requests across different time zones . . . . . . . . . . . . 260
Verifying permissions for the Windows accounts . . . . . . . . . . . 260
Troubleshooting email request processing and notify filters . . . . . . . 261

Appendix A Examples of email templates . . . . . . . . . . . . . . . . . . 263

Creating email templates to search for Request ID . . . . . . . . . . . . . 264
Creating email templates to search for fields . . . . . . . . . . . . . . . 265
Creating email templates to perform searches using qualifications. . . . . . 266
Creating email templates that include attachments . . . . . . . . . . . . 267
Creating an email content template with Submit and Query actions . . . . . 268

Contents
7
BMC Remedy Action Request System 7.0

Creating an email reply using result templates in HTML format. . . . . . . 270

Sample HTML result template . . . . . . . . . . . . . . . . . . . 271
Email status template in HTML format . . . . . . . . . . . . . . . . . 273
Adding a header template and a footer template . . . . . . . . . . . . . . 275

Appendix B Email engine installation worksheets . . . . . . . . . . . . . . 277

UNIX—Installation and configuration worksheets . . . . . . . . . . . . 278
UNIX—Installation worksheet . . . . . . . . . . . . . . . . . . . 278
UNIX—Configuration worksheet . . . . . . . . . . . . . . . . . . 279
Windows—Installation and configuration worksheets . . . . . . . . . . . 282
Windows—Installation worksheet . . . . . . . . . . . . . . . . . . 282
Windows—Configuration worksheet . . . . . . . . . . . . . . . . 283

Appendix C Setting up UNIX mailboxes . . . . . . . . . . . . . . . . . . . 287

Appendix D Upgrading email option parameters. . . . . . . . . . . . . . . 289

Email engine update parameters. . . . . . . . . . . . . . . . . . . . . 290

Appendix E BMC Remedy Email Engine forms . . . . . . . . . . . . . . . . 297

Email engine administration forms . . . . . . . . . . . . . . . . . . . 298
AR System Email Mailbox Configuration . . . . . . . . . . . . . . . 298
AR System Email Templates form . . . . . . . . . . . . . . . . . . 302
AR System Email User Instruction Templates form. . . . . . . . . . . 304
AR System Email Error Logs form . . . . . . . . . . . . . . . . . . 305
AR System Email Security . . . . . . . . . . . . . . . . . . . . . 306
Email engine user forms . . . . . . . . . . . . . . . . . . . . . . . . 307
AR System Email Messages form . . . . . . . . . . . . . . . . . . 307
AR System Email Attachments form . . . . . . . . . . . . . . . . . 310
AR System Email Attachment Join form . . . . . . . . . . . . . . . 311
Email engine workflow forms . . . . . . . . . . . . . . . . . . . . . . 311
AR System Email Instructions form . . . . . . . . . . . . . . . . . 311
AR System Email Instruction Parameters form . . . . . . . . . . . . 312
AR System Email Association form . . . . . . . . . . . . . . . . . 312

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313

8 Contents
Preface

Important: The compatibility information listed in the product

documentation is subject to change. See the compatibility matrix at http:/
/supportweb.remedy.com for the latest, most complete information about
what is officially supported.

Carefully read the system requirements for your particular operating

system, especially the necessary patch requirements.

Audience
This guide is for administrators who are responsible for installing and
maintaining the BMC® Remedy® Email Engine (email engine). Before you
explore the topics in this guide, you must know how to use the BMC®
Remedy® Action Request System® (AR System®), including BMC Remedy
Administrator, BMC Remedy User, and BMC Remedy Import. See the
Installing guide, the Form and Application Objects guide, and the Workflow
Objects guide for additional information. Your knowledge of basic
administrative AR System tasks is crucial for the successful implementation
of the strategies discussed in this guide.
In addition, make sure that you understand the terms and concepts discussed
in the Optimizing and Troubleshooting guide, which contains all the required
information for setting up and administering a basic AR System
environment.

Preface
9
BMC Remedy Action Request System 7.0

AR System documents
The following table lists documentation available for AR System products.
Unless otherwise noted, online documentation in Adobe Acrobat (PDF)
format is available on AR System product installation CDs, on the Customer
Support site (supportweb.remedy.com), or both.
You can access product Help through each product’s Help menu or by
clicking on Help links.

Title Description Audience

Concepts Overview of AR System architecture and features with Everyone
in-depth examples; includes information about other
AR System products as well as a comprehensive glossary
for the entire AR System documentation set.
Installing Procedures for installing AR System. Administrators
Getting Started Introduces topics that are usually only learned when first Everyone
starting to use the system, including logging in, searching
for objects, and so on.
Form and Application Objects Describes components necessary to build applications in Developers
AR System, including applications, fields, forms, and
views.
Workflow Objects Contains all of the workflow information. Developers
Configuring Contains information about configuring AR System Administrators
servers and clients, localizing, importing and exporting
data, and archiving data.
Installing and Administering Contains information about the mid tier, including mid Administrators
BMC Remedy Mid Tier tier installation and configuration, and web server
configuration.
Integrating with Plug-ins and Discusses integrating AR System with external systems Administrators
Third-Party Products using plug-ins and other products, including LDAP, /Developers
OLE, and ARDBC.
Optimizing and Server administration topics and technical essays related Administrators
Troubleshooting to monitoring and maintaining AR System for the
purpose of optimizing performance and troubleshooting
problems.

10 Preface
 Administering BMC Remedy Email Engine

Title Description Audience

Database Reference Database administration topics and rules related to how Administrators
AR System interacts with specific databases; includes an
overview of the data dictionary tables.
Administering BMC Remedy Server administration and procedures for implementing Administrators
DSO a distributed AR System server environment with the
BMC Remedy Distributed Server Option (DSO).
Administering BMC Remedy Flashboards administration and procedures for creating Administrators
Flashboards and modifying flashboards and flashboards components /Programmers
to display and monitor AR System information.
C API Reference Information about AR System data structures, C API Administrators
function calls, and OLE support. /Programmers
C API Quick Reference Quick reference to C API function calls. Administrators
/Programmers
Java API 1 Information about Java classes, methods, and variables Administrators
that integrate with AR System. /Programmers
Administering BMC Remedy Procedures for installing, configuring, and using the Administrators
Email Engine BMC Remedy Email Engine.
Error Messages List and expanded descriptions of AR System error Administrators
messages. /Programmers
Master Index Combined index of all books. Everyone
Release Notes Information about new features list, compatibility lists, Everyone
international issues, and open and fixed issues.
BMC Remedy User Help Procedures for using BMC Remedy User. Everyone
BMC Remedy Import Help Procedures for using BMC Remedy Import. Administrators
BMC Remedy Administrator Procedures for creating and modifying an AR System Administrators
Help application for tracking data and processes.
BMC Remedy Alert Help Procedures for using BMC Remedy Alert. Everyone
BMC Remedy Mid Tier Procedures for configuring the BMC Remedy Mid Tier. Administrators
Configuration Tool Help
1.
A JAR file containing the Java API documentation is installed with the AR System server.
Typically, it is stored in C:\Program Files\AR System\Arserver\Api\doc\ardoc70.jar on
Windows and /usr/ar/<server_name>/api/doc/ardoc70.jar on UNIX.

AR System documents
11
BMC Remedy Action Request System 7.0

Learn about the AR System Developer Community

If you are interested in learning more about AR System, looking for an
opportunity to collaborate with fellow AR System developers, and searching
for additional resources that can benefit your AR System solution, then this
online global community sponsored by BMC Remedy is for you.
In the Developer Community, you will find collaboration tools, product
information, resource links, user group information, and be able to provide
BMC Remedy with feedback.
The Developer Community offers the following tools and information:

Community message board

Community Downloads

AR System Tips & Tricks

Community recommended resources

Product information

User Experience Design tips

Why should you participate in the Developer Community?

You can benefit from participating in the Developer Community for the
following reasons:

The community is a direct result of AR System developer feedback.

BMC Remedy provides unsupported applications and utilities by way of
Community Downloads, an AR System application.

BMC Remedy posts the latest AR System product information in the
Developer Community to keep you up to date.

It is an opportunity to directly impact product direction through online
and email surveys.

It’s free!

How do you access the Developer Community?

Go to supportweb.remedy.com, and click the Developer Community link.

12 Preface
Chapter

1 Overview of the BMC Remedy

Email Engine

This chapter provides an overview of the BMC Remedy Email Engine. The
following topics are provided:

About the BMC Remedy Email Engine (page 14)

Email engine terminology (page 16)

Overview—How the email engine works (page 18)

Overview—Improving the appearance of your email (page 21)

Overview of the BMC Remedy Email Engine
13

BMC Remedy Action Request System 7.0

About the BMC Remedy Email Engine

The BMC Remedy Email Engine is a service that transforms email into an
interface that communicates with the AR System server. It is included as part
of the AR System and does not require an additional license. The email
engine enables 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 also returns the results of such
requests in email that is formatted using plain text, HTML, or XML content.
In addition, the email engine can process notifications using workflow
actions such as filters or escalations.

Note: In the 7.0 release, you must install the email engine 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 BMC 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 and translated into API calls to your AR System server. These
instructions can involve modifying form entries, submitting entries, or
retrieving multiple entries from your AR System server.

Sending mail—You can use the email engine 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 plain
text, 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.

14 Chapter 1—Overview of the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

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 BMC Remedy Email Engine are stored in forms within
an AR System server. All logging information—including errors, incoming
emails, and outgoing emails—is also stored in separate forms on the
AR System server. The forms can be accessed from either BMC Remedy User
or a web client. The only information stored by the email engine is the
location of the AR System server where the forms are stored.

Note: You can 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 BMC Remedy Email Engine” on page 231.

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

About the BMC Remedy Email Engine
15

BMC Remedy Action Request System 7.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 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 a 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. Users must log in 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 is discussed in greater detail in
Chapter 3, “Configuring mailboxes in the BMC Remedy
Email Engine.” A mailbox contains all of the information
required by the email engine to access mail from a mail server
or to request that mail be sent by a mail server. As such, a
mailbox can 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 Incoming Mailboxes or
Outgoing Mailboxes.

16 Chapter 1—Overview of the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

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, see “Configuring incoming mailboxes” on
page 59.
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, see “Configuring outgoing mailboxes” on
page 53.
Instructions The term “Instruction” is used in two ways:

In a broader sense, instructions see all the parameters
contained in an email message that do certain actions; for
example, log in to the server, query for all tickets assigned to
Joe User, and return the results in HTML format.

In a more narrow sense, instructions see a specific set of
actions used in an email message; for example, Query,
Submit, or Modify. The word Instruction can also be used as
an alias for Action in a label/value pair.

Email engine terminology
17

BMC Remedy Action Request System 7.0

Overview—How the email engine works

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

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

Underlying
AR
Database
System
Server

HD Incident

AR System Email Mailbox

6.3 Email Engine
Configuration Form

Field 1

Printer Broken
Field 2

Field 3 Abcd ef ghijkl mno

Query
4
1 instructions
Email translated into
Engine API calls to 5 Server queries
ticket on HD
AR System admin server Incident form
installs and configures and returns
email engine results

Incoming Mailbox Outgoing Mailbox

3 6 Outgoing email
is formatted
Email engine
and assembled
parses query
instructions
POP3 MBOX SMTP

IMAP4 MAPI MAPI

Mail
Server

Email Email

account account

1 2

Users log in to
7 mail server to
receive new email

2
Query email
sent to incoming
mailbox

Shelly Katie Mark

18 Chapter 1—Overview of the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

In the XYZ Company, Shelly needs a list of the latest issues stored in the HD
Incident form. She wants the results of this query to be returned in an easy-
to-read email. In addition, Shelly wants to make sure that her co-workers,
Katie and Mark, will be copied with the results of this query. All of the steps
that the email engine and the users must take to make this happen follow.

Step 1 The local BMC Remedy administrator installs the email engine. During
installation, he configures Incoming and Outgoing mailboxes to work with
the company mail server.

When the installation process is finished and the email engine is started, the
email engine contacts the AR System server. The email engine then reads in
all of the entries in the AR System Email Mailbox Configuration form and
creates Incoming and Outgoing mailboxes based on the information
contained within these entries.

Step 2 After the local BMC Remedy administrator notifies the user base 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 HD
Incident 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 in 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.

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 reads Shelly’s email, interprets the 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 HD Incident form.

Overview—How the email engine works
19

BMC Remedy Action Request System 7.0

Step 6 The email engine, having successfully retrieved the requested information,
turns to the Outgoing Mailbox that it created in step 1. It uses the
information in the Outgoing Mailbox to format the email message 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
the outgoing email protocols (SMTP or MAPI).

Step 7 Shelly, Mark, and Katie log in to the mail server to see if they have new mail.
They find the email constructed by the email engine, which contains a neatly
formatted list of the most recent 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 might ultimately differ from the one
presented here in many respects. For example, the email engine might reside
on the same system as the AR System server. Alternatively, you might
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.

20 Chapter 1—Overview of the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Overview—Improving the appearance of your email

To improve the appearance of your email, Figure 1-2 shows how the email
engine can assign HTML templates to outgoing email.

Figure 1-2: Templates dynamically assigned through workflow

Underlying
AR Database
System
Server
Server executes filter workflow that triggers Notify action.
3 Urgent header template is dynamically assigned.

Email Templates

Field 1 Template Components

Field 2 6.3 Email Engine

Field 3
Field 1 Abcdefg

Field 2 Hijklm

Field 3 Nopqrst

2
Email engine
parses instructions.
Instructions then
translated into 6.3 Email Engine

API calls to server.

Field 1 Abcdefg

Field 2 Hijklm

Field 3 Nopqrst
Incoming Mailbox Outgoing Mailbox

Outgoing email is
4 assembled according
to formatting instructions:
¥ HTML header template
Email ¥ HTML result template
Engine ¥ Field values returned
from server

Mail
Server

Email Email

account account

1 2

Schema: HD Incident
Action: Submit
Impact: Urgent

Urgent email
5 Urgent email
sent to Francie

1 sent to
incoming
Frontline

mailbox.

Shelly Francie Frontline

Overview—Improving the appearance of your email
21

BMC Remedy Action Request System 7.0

The local BMC Remedy administrator at XYZ is pleased by the response of

the BMC Remedy user community to the email engine. Users feel
comfortable using email to query the AR System server, as well as to submit
and modify entries. But he does hear occasional grumbling in the hallway.
Why is BMC Remedy email so boring? Why can’t BMC Remedy email look
more like what they receive from their favorite online auction website or
online bookstore? Figure 1-2 illustrates one possible solution.
Realizing the importance of AR System notifications, he takes advanced steps
to replace the plain text email generated by the email engine. To improve its
look and feel, he designs better looking HTML pages that will be used as
header, footer, result, and content templates. He works with a graphic artist
to create interesting bitmaps.
Most important, he designs data-driven workflow that dynamically assigns
the correct templates based on the ticket’s impact. The templates are
designed so that users can quickly tell if a ticket’s impact is urgent, high,
medium, or low.

Step 1 Shelly is visiting an important client in Chicago. She desperately needs

information from the corporate website within the hour to close an
important deal, but the web server is down and her web client keeps
returning errors. She composes an email with status marked Urgent and
sends it to the Incoming mailbox.

Step 2 The email engine receives the email from the mail server. It parses the
instructions in her email, and makes the appropriate API calls to the
AR System server.

Step 3 When her new request is submitted, the server fires a filter that triggers a
Notify action. Under normal circumstances, email notifications are
formatted with a standard HTML header and result template. But if a
submission is marked Urgent, the filter workflow creates an email
notification with the Urgent header template dynamically assigned.

Step 4 The email engine constructs the message according to formatting

instructions contained in the Outgoing Mailbox it is using. This message
consists of the field values from the HD Incident form (submitter, short
description, status, assignee, and so on) along with the header and reply
templates that are stored by the AR System server in the AR System Email
Templates form. The email engine then transmits the message to the mail
server with instructions to send the message to Francie Frontline, the first
line Customer Support engineer.

22 Chapter 1—Overview of the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Step 5 Francie Frontline logs in to the mail server to see if she has new mail. She sees
the Urgent email constructed by the email engine. She clicks the direct access
URL in her email and the ticket opens in her browser. Because the email is
marked Urgent, its importance jumps to the top of her To Do list. She
troubleshoots and quickly resolves the problem. When Francie marks the
ticket as Fixed, the server fires a filter Notify action. Shelly then receives an
email notification by the system that her web access problems have been
solved. She can now access the information she needs to close her sale.

For more information, see “Dynamically assigning templates to outgoing

email” on page 99.

Overview—Improving the appearance of your email
23

BMC Remedy Action Request System 7.0

24 Chapter 1—Overview of the BMC Remedy Email Engine

Chapter

2 BMC Remedy Email Engine

installation and setup

This chapter describes how to install the BMC Remedy Email Engine on
Windows and UNIX systems.
The following topics are provided:

Preinstallation steps (page 26)

Windows—Installing the email engine (page 32)

UNIX—Installing the email engine (page 41)

Postinstallation steps (page 47)

BMC Remedy Email Engine installation and setup
25

BMC Remedy Action Request System 7.0

Preinstallation steps
This section describes the preinstallation steps you should complete before
you install the email engine.

Entering information into the installation worksheet

Print out the worksheets in Appendix A and use them to record information
you will need during the installation, including information you obtain
during the preinstallation steps. For example, you will need to record the
name of the server that will connect to the email engine.

Reviewing documentation
Before you complete any preinstallation tasks, see the following
documentation.

What Where Comments

Specific information about open Action Request System 7.0 Release Before you can access the
issues, localization, and other Notes: release notes, you must log in
information for Version 7.0 http:// to the Customer Support
supportweb.remedy.com Website.
Most current product compatibility Product Compatibility Matrix: Before you can access the
information http:// compatibility matrix, you
supportweb.remedy.com must log in to the Customer
Support Website.

Installing components
Install the following before you install the email engine:

A compatible AR System server

A compatible Java Runtime Environment (JRE).
See the product compatibility matrix on the Customer Support website for
more information.

26 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

Windows—Preinstallation tasks
This section describes the preinstallation tasks you should complete before
you install the email engine on Windows.

Environment variables
Set any relevant environment variables to control the installation. For
example, set the PATH and CLASSPATH environment variables to use the
correct version of Java. See the Installing guide for more information about
environment variables.

Secure Socket Layer option

Check to see if your environment requires the Secure Socket Layer (SSL)
option. For more information, see “Configuring SSL for the email engine” on
page 76.

MAPI and MBOX preparation

The tables in this section explain the steps you must follow to set up the
system if you are using the MAPI or MBOX mail protocols.
You do not need to prepare the system if you are using the IMAP4, POP3, or
SMTP protocols.

Note: MAPI users only: If you are upgrading your email engine from a
previous email engine version, and you do not need to change your
existing MAPI configuration information, skip this section and go to
“Windows—Installing the email engine” on page 32, or “UNIX—
Installing the email engine” on page 41.

MAPI preparation steps

To prepare the system to use the MAPI protocol, you must install
MS Exchange server and client, create and configure a Windows domain user
account, and then create an MS Exchange mailbox for use with the email
engine only. While logged in as the Windows domain user account, you must
create an MS Exchange profile on the same computer where you plan to
install the email engine.

Preinstallation steps
27
BMC Remedy Action Request System 7.0

Note: You must be a Windows domain administrator or MS Exchange

administrator to perform these steps.

What Where Comments

Install components
MS Exchange server At one of the following locations:

Same domain as the email engine
domain.

A domain with the appropriate trust
relationship to the email engine
domain.
MS Exchange client Same machine as the machine where you The clients contain the
plan to install the email engine. libraries that the email
protocols will use.
See the product compatibility
matrix for more information
about compatible clients for
the email engine.

Create and configure a Windows domain account

Create a Windows domain At one of the following locations: Enter the name of this user in
user account.
On the same domain as the email the Windows—Configuration
engine. worksheet at:

On a domain with appropriate trust
Windows—Incoming
relationships. mailbox: Server User

Windows—MAPI logon
settings: Windows NT User
Assign group and domain At one of the following locations: Group membership:
membership to the domain
On the same domain as the email
Local administrator’s group
user account. engine. (active directories only).

On a domain with appropriate trust Domain membership:
relationships.
Email engine domain
or

Exchange Server domain

28 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

What Where Comments

Grant the domain user On the computer where you plan to install Advanced rights:
advanced rights. the email engine.
Act as Part of the
Operating System

Log on as a Service
Note: Active directories only:
Make sure that the
Effective Rights option
shares the correct advanced
rights.

Create and configure an MS Exchange profile

Create an MS Exchange email On the computer where you plan to install Log in as the domain user to
profile. the email engine. create this profile.
Enter this value in the
Windows—Configuration
worksheet entry: MAPI -
Email Profile.

Configure the profile. Configure the profile to:

Work exclusively with the
email engine.

Be accessible by the
Windows domain user
account you created earlier
in the sub-table section:
“Create and configure a
Windows domain account.”

Point to the MS Exchange
server and mailbox.

Check your profile setup

Log in as the domain user you From the computer where you plan to
created earlier. Using the MS install the email engine.
Outlook client, send and
receive emails to verify that
the MS Exchange profile is
functioning correctly.

Preinstallation steps
29
BMC Remedy Action Request System 7.0

MBOX preparation steps

To prepare the system for using the MBOX protocol:

Create an email account and account user.

Give the email account user full read and write permissions to relevant
directories and files.

Verify that the account can send and receive emails.
See Appendix C, “Setting up UNIX mailboxes.”

BMC Remedy mail server upgrade

If you are upgrading from BMC Remedy mail server, you should:
1 Complete the preinstallation steps in the preinstallation section that are
relevant to the mail protocol you will choose for the email engine.
2 Transfer existing information from the ar.cfg or armaild.cfg files to the
worksheet.
Use the following mapping table as a guide.
BMC Remedy mail server Mapping equivalent in the email
information engine
ExchangeNTAccount Enter this information into the Windows
NT User line of the worksheet.
ExchangeNTDomain Enter this information into the Windows
equivalent to the domain user NT Domain line of the worksheet.
Exchange-Mailbox Enter this information into the Display
Name line of the worksheet.

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 BMC Remedy Mail Server finish processing the
remaining notifications in the Mailntfy directory, until it is empty.

30 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

5 Stop and disable the BMC Remedy Mail Server.

See Appendix D, “Upgrading email option parameters” for information
about converting your old configuration parameters to their functional
equivalent in the 7.0 email engine.

UNIX—Preinstallation tasks
Check if the preinstallation steps in this section pertain to your installation.

Environment variables
Set any relevant environment variables to control the installation. See the
Installing guide for more information about setting and customizing UNIX
options.

Upgrades from the BMC Remedy Email Engine

Use the emaild.sh stop command to stop the existing email engine before
you install the new email engine. If you do not stop the existing email engine,
none of the open email engine files and libraries will be updated.
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, and then stop and restart the AR System server. (For
more information, see “Postinstallation steps” on page 47.)

Upgrading from email engine version 5.1 or 5.1.1

You must be running on the 5.1.2 (or later) version of the email engine to
upgrade to version 7.0.

Installing as a non-root user

Installing as a non-root user is not recommended.
This section lists limitations and actions you should follow to install the
email engine as a non-root user.
Creating directories
Create the logging.properties and javamail.providers files.

Preinstallation steps
31
BMC Remedy Action Request System 7.0

Writing to files
Only root users can write to the armonitor.conf file. Because non-root users
do not have permission to write to this file, the installer creates a temporary
file instead (armonitor.conf_temp). After installation, you must append the
contents of the armonitor.conf_temp file to the armonitor.conf file.
Deleting existing files
If you have AR System installed, delete the /tmp/migfiles directory.
Allocating permissions
Give the non-root user permission to the following directories:

MBOX mail directory and all its contents

JRE (Java Runtime Environment) directory and all its contents, especially
the <Java_home>/jre/lib directory
For more information about installing as a non-root user, see the Installing
guide.

Windows—Installing the email engine

After you have completed the worksheet and the preinstallation sections, use
the steps in this section to install the email engine on Windows.

Loading the software

This section describes the steps to access the installation software from a CD
or from the Web.

To access the installation software

1 From the CD:
a Log in to Windows as an administrator and insert the CD into the drive.
b If autorun is enabled, the CD browser opens. Click Install Products and
then click BMC Remedy Email Engine.
c If the CD browser does not start, run the email engine installer,
emaild.exe.

32 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

2 From ESD:
a If you downloaded the email engine to a location that is not the
installation location, copy the downloaded directory and its contents to
the computer where you will install the email engine.
b From the download directory, run the file emaild.exe.
When you run this file, the installation files are unpacked into a temporary
directory and the Setup program starts.

Installing the email engine

This section provides the steps to install the email engine on a computer that
has no existing email engines (new install), and on a computer with one or
more existing email engines installed (upgrade or overwrite).
The section is divided into the following subsections:

“Entering basic information” on page 33, which describes steps to enter
server-related information, including port numbers.

“Entering configuration information” on page 35, which describes steps
to enter configuration information for incoming and outgoing mailboxes.

“Completing the installation” on page 40, which describes the steps to
complete the installation.
To accept the defaults for any of the options in the following procedures,
click Next.

Entering basic information

This section provides the steps to start the installation and enter product
directory and licensing information.

To enter basic information

1 After you load the media, the Welcome screen appears. Click Next to display
the Software License Agreement screen.
2 Click the I Agree button to accept the software license agreement and to
display the Choose Destination Location screen.

Windows—Installing the email engine
33

BMC Remedy Action Request System 7.0

3 Click Next to accept the default installation directory or click Browse to

choose another directory, and then click Next.
Upgrades or overwrites only: By default, the email engine will be installed in
the installation directory of the existing email engine. You can choose to
install the email engine into a different directory.
New installs only: By default, the email engine will be installed in the
C:\Program Files\AR System\AREmail directory. You can choose to install
the email engine into a different directory.
The AR Server to Support Email Server screen appears.
4 Enter the following information in the fields:
a AR Server Name—Name of the AR System server that this email engine
will connect to.

WARNING: For multiple AR System servers on the same machine only:

To maintain the correct dependency relationship between your email
engine and its dedicated AR System server, make sure you enter the
correct AR System server for the email engine you are installing.

b Port Number—TCP port number for the AR System server that the email
engine will connect to.
You do not have too enter a value if the AR System server is using a
portmapper.

Note: You must enter a TCP port if the email engine and the AR System
server are on the opposite sides of a firewall.

For more information about registering portmappers, see the Installing

guide.
c RPC Port Number—RPC port number for the AR System server.
Enter an RPC port only if you have already configured a private server to
use with the email engine.
For more information about private servers in the AR System, see the
Configuring guide.

34 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

5 Click Next to display the Administrator Logon Information Required screen.

Enter an AR System Administrator user name and password.
The user name must have Administrator privileges on the AR System server.
This user name will be used only during installation to import the necessary
AR System email engine forms and workflow.
6 Click Next to display the Application Service Password screen.
7 Enter the password designated for this server.
An Application Service password is required. This password is set in the
Server Information dialog box in BMC Remedy Administrator.
8 Click Next to display the Start Copying Files screen. The installer displays
installation-related messages.
9 Click Next to begin copying files.

Entering configuration information

This section describes the prompts for entering email engine configuration
information. Incoming mailboxes can be configured using MAPI, POP3, or
IMAP4. Outgoing mailboxes can be configured using MAPI or SMTP.
After the installer copies the files, the AR System Email Mailbox
Configuration screen appears. Choose one of the following options:
1 Click No to configure the email engine after installation.
Use this option if you are upgrading or overwriting and you do not want to
change the configuration settings.
See the configuration chapter for more information about configuring the
email engine after installation. Go to “Completing the installation” on
page 40.
2 Select Incoming, Outgoing, or Incoming and Outgoing from the Mailbox
Function menu to configure incoming mailboxes, outgoing mailboxes, or
both.
Use this option if you are:

Performing a new install.

Creating additional mailboxes.

Upgrading from BMC Remedy mail server (pre-5.1).

Windows—Installing the email engine
35

BMC Remedy Action Request System 7.0

If you selected Outgoing only, go to “Configuring your outgoing mailbox”

on page 38.
If you selected Incoming, or Incoming and Outgoing, go to “Configuring
your incoming mailbox.”
Configuring your incoming mailbox
Follow the steps in this section to configure your incoming mailbox.

To configure your incoming mailbox

1 Click Next to display the BMC Remedy Email Mailbox Configuration -
Incoming Mailbox screen. Different choices become enabled when you select
the mail protocol (Server Type).

Figure 2-1: Incoming Mailbox screen

36 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

2 MAPI only:
Enter the following information in the fields:
a Mailbox Name—Enter a descriptive mailbox name.
Use a name that describes the function of the mailbox. For example, enter
ARSystemEmail - Incoming.

b Server Type—Select MAPI from the menu.

c Email Profile—Enter the name of the MS Exchange profile you created in
the “Windows—Preinstallation tasks” section on page 27.
If you chose to configure only an incoming mailbox, go to “Entering
MAPI logon settings” on page 39.
If you chose to configure both incoming and outgoing mailboxes, go to
“Configuring your outgoing mailbox” on page 38.
3 POP3 or IMAP4 only:
Enter the following information in the BMC Remedy Email Mailbox
Configuration - Incoming Mailbox screen fields:
a Mailbox Name—Enter a mailbox name.
Use a name that describes the function of the mailbox. For example, enter
ARSystemEmail - Incoming.

b Server Type—Select POP3 or IMAP4.

c SSL—Check the box to enable Secure Socket Layer (SSL).
d Server Name/IP—Enter the name or IP address of your company’s mail
server.
e Server Port—Enter the mail server port number.
f Server User—Enter the name of the user of the email account.
g Server Password—Enter the password corresponding to the server user.
h If you chose to configure both an incoming and outgoing mailbox, go to
“Configuring your outgoing mailbox” on page 38. If you chose to
configure only an incoming mailbox, go to “Completing the installation”
on page 40.

Windows—Installing the email engine
37

BMC Remedy Action Request System 7.0

Configuring your outgoing mailbox

Follow the steps in this section to configure your outgoing mailbox.

To configure your outgoing mailbox

1 Click Next to display the BMC Remedy Email Mailbox Configuration -
Outgoing Mailbox.
a MAPI only:
Enter the following information in the fields:

Mailbox Name—Enter a mailbox name.
Use a name that describes the function of the mailbox. For example,
enter ARSystemEmail - Outgoing.

Display Name—Enter a descriptive name that appears in the From: line
of outgoing emails.

Email Address—Enter the email address of the server user that you
entered previously in step f.
For example, if you entered a display name of ARSystem and an email
address of arsystem@remedy.com, the From: line would be:
From: ARSystem [arsystem@remedy.com]

Server Type—Select MAPI from the menu.

Profile—Enter the name of the MS Exchange profile that is dedicated
for use with the email engine.
Go to “To enter MAPI logon settings” on page 39.
b SMTP only:
Enter the following information in the fields:

Mailbox Name—Enter a descriptive name for your outgoing mailbox.
For example, enter AREmail - Outgoing.

Display Name—Enter a descriptive name that appears in the From: line
of outgoing emails.

Email Address—Enter the full email address of the mailbox user.
If you entered a display name of ARSystem and an email address of
arsystem@remedy.com, the From: line would be:
From: ARSystem [arsystem@remedy.com]

38 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

Server Type—Select SMTP from the menu.

SSL—Check the box to use Secure Socket Layer (SSL), if applicable.

Server Name/IP—Enter the name or IP address of your company’s mail
server.

Server Port—Enter the mail server port number (default is 25).

Server User—Enter the name of the user of the email account (null if
not applicable).

Server Password—Enter the password corresponding to the server user
(null if not applicable).
Go to “Completing the installation” on page 40.
Entering MAPI logon settings
Follow the steps in this section to enter MAPI logon settings. You must enter
these settings if you use MAPI.

To enter MAPI logon settings

1 Click Next to display the Email Engine MAPI Logon Settings screen.

Figure 2-2: MAPI Logon Settings screen

Windows—Installing the email engine
39

BMC Remedy Action Request System 7.0

Enter the following information in the fields:

a Windows NT User—Enter the name of the Windows domain user that
you created in the “Windows—Preinstallation tasks” section on page 27.
This user has access to the Exchange profile mailbox and also has
Windows NT domain permissions to start the email engine as a service.
b Password—Enter the password corresponding to the Windows NT User.
c Windows NT Domain—Enter the Windows NT domain.

Note: To configure more incoming and outgoing mailboxes, see Chapter 3,

“Configuring mailboxes in the BMC Remedy Email Engine.”

Completing the installation

1 Click Next to complete copying files and to display the Setup Complete
dialog box.
2 In the Setup Complete dialog box, choose Yes to restart your computer
(optional) and click Finish to complete the installation.
The remaining files are copied to your system. If you have problems, see
“Stopping and starting the AR System server” on page 259.

40 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

UNIX—Installing the email engine

After you have completed the steps in the section “UNIX—Preinstallation
tasks” on page 31 and the UNIX installation worksheets in Appendix B, use
the steps in this section to install the email engine on UNIX.

Loading the software

This section describes the steps to access the installation software from a CD
or from the Web.

To access the installation software

1 From the CD:

Mount the CD locally or remotely.

Use the following command to change to the directory containing the
email engine installation script:
# cd <CD-ROM_mount_point>/arsystem

The default mount point is /cdrom.

See the Installing guide for more information about mounting a CD.
2 From Electronic Software Distribution (ESD):
Download the *.tar.gz file to the arsystem directory of the computer where
you are installing the email engine.

Installing the email engine

This section provides the steps to install the email engine on a computer that
has no existing email engines (new install), and on a computer with one or
more existing email engines installed (upgrade or overwrite).
The section is divided into the following subsections:

“Entering basic information” on page 42, which describes steps to enter
server-related information, including port numbers.

“Entering configuration information” on page 35, which describes steps
to enter configuration information for incoming and outgoing mailboxes.

“Completing the installation” on page 40, which describes the steps to
complete the installation.

UNIX—Installing the email engine
41

BMC Remedy Action Request System 7.0

To accept the defaults for any of the options in the following procedures,
press ENTER.

Note: These procedures do not display the UNIX prompts, but rather the
steps correspond to sequential actions that you must take during
installation.

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

Entering basic information

This section provides the steps to start the installation and enter product
directory and licensing information.

To enter basic information

1 Log in as the root user.
To install the software without root privileges, see “Installing as a non-root
user” on page 31.
2 Run the ed_install script, located in the arsystem directory.
#./ed_install

3 At the prompt to install the BMC Remedy Email Engine 7.0, enter y.
The installer displays logging and system messages.
4 At the product directory prompt, enter the name of the directory where the
CD-ROM is mounted and where the ed_install file is located.
Typically, the product directory is called arsystem.
5 At the license agreement prompt, press one of the following keys:

Press ENTER to view the entire licensing agreement.

Press q to return a prompt that allows you to accept, reject, or re-read the
agreement.
If you do not accept the terms of the licensing agreement, the installation
terminates.

42 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

6 At the Java prompt that asks if you have Java SDK installed, choose one of the
following actions:
a Type n to terminate the installation if you do not have a compatible Java
SDK installed. Install a compatible Java product and restart the
installation.
b Type ENTER if you have already installed a compatible Java product.
7 At the Java installation directory prompt, enter the directory path to your
Java root directory and confirm the location.
A typical path is: /usr/java<version>/<root_directory_location>
The root directory contains the /bin and /jre directories.
8 At the AR System server name prompt, enter and confirm the name of the
server that the email engine will connect to. This server can also be a private
server that you have already configured.
For more information about private servers, see the Configuring guide.

WARNING: For multiple AR System servers on the same machine only:

To maintain the correct dependency relationship between your email
engine and its dedicated AR System server, make sure you enter the
correct AR System server for the email engine you are installing.

9 At the TCP port for the AR System server prompt, perform one of the
following tasks:

Press ENTER to accept the defaults if you have registered the server you
chose in step 8 with a portmapper and you do not want to assign a port
number.

Enter a TCP port for the AR System server that you will use with the email
engine you are installing.
10 Confirm your selection.

Note: 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 about ports, see the Installing guide.

UNIX—Installing the email engine
43

BMC Remedy Action Request System 7.0

11 At the RPC port for the AR System server prompt, perform one of the
following tasks:

Press ENTER to accept the defaults if you have registered the server you
chose in step 8 with a portmapper and you do not want to assign a port
number.

Enter the RPC port for the AR System server you entered in step 8 on
page 43.
12 Confirm your selection.
For more information about ports, see the Installing guide.
13 At the BMC Remedy Admin User Name prompt, enter and confirm the
AR System Administrator user name and password. The AR System
Administrator has permissions to import forms and workflow.
If your AR System server is not running, the installer prompts you to check
the server. Make sure your AR System server is running before proceeding.
14 At the Application Service password prompt, enter the Application Service
Password designated for this system.
An Application Service password is required. This password is set in the
Server Information dialog box in BMC Remedy Administrator.
15 At the configuration prompt, press one of the following keys:

Enter n to configure the email engine after installation.
Use this option also if you are upgrading and you do not want to change
the configuration settings.
See the configuration chapter for more information about configuring the
email engine after installation.
Go to “Completing the installation” on page 47.

Enter y to configure the email engine during the installation.
Use this option if you would like to send and receive email immediately
after installation, or you are upgrading from BMC Remedy mail server.
After you install, you can change configuration values in the AR System
Email Mailbox Configuration form.

44 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

16 At the mailbox function prompt, press one of the following keys:

Enter n to skip the configuration steps. Go to “Completing the
installation” on page 47.

Enter b to configure incoming and outgoing mailboxes.

Enter i to configure the incoming mailbox only.

Enter o to configure the outgoing mailbox only.
17 At the Secure Socket Layer (SSL) prompt, enter y if you are using SSL.

Entering configuration information

This section describes the prompts for entering email engine configuration
information. On UNIX, incoming mailboxes can be configured using POP3,
IMAP4, or MBOX. Outgoing mailboxes can be configured using SMTP.
Configuring an incoming mailbox
Use the steps in this section to configure an incoming mailbox.

To configure your incoming mailbox

Enter the following information at the prompts:
1 POP3 or IMAP4 only:
a Mailbox Name—Enter a mailbox name.
Use a name that describes the function of the mailbox. For example, enter
ARSystemEmail - Incoming.

b Server Type—Select POP3 or IMAP4.

c SSL—Check the box to enable Secure Socket Layer (SSL).
d Server Name/IP—Enter the name or IP address of your company’s mail
server.
e Server Port—Enter the mail server port number (default is 110).
f Server User—Enter the name of the user or administrator of the email
account.
g Server Password—Enter the password corresponding to the server user.
h If you chose to configure both an incoming and outgoing mailbox, go to
“Configuring your outgoing mailbox” next. If you chose to configure only
an incoming box, go to “Completing the installation” on page 40.

UNIX—Installing the email engine
45

BMC Remedy Action Request System 7.0

2 MBOX only:
a Name—Enter a mailbox name.
Use a name that describes the function of the mailbox. For example, enter
ARSystemEmail - Incoming.

b Server name—Enter the name of the server that will connect to the email
engine.
c Server Type—Select m for MBOX.
d Incoming Mailbox Path—Enter the full path to your incoming mailbox.
Enter the full path to the incoming mailbox MBOX file for the user account.
For example:
/usr/spool/mail/ARSystem

where ARSystem is the MBOX file name.

To confirm that the path you entered is the correct path, perform one of
the following tasks:

Look in your /etc/aliases file.

Run the following command:

/usr/lib/sendmail -bv -v <mailbox_user>

e Incoming User Home Path—Enter the full path of the user home
directory. For example: /home/ARSystem.
If you chose to configure both an incoming and outgoing mailbox, go to
“Configuring your outgoing mailbox” on page 38. If you chose to configure
only an incoming box, go to “Completing the installation” on page 40.
Configuring your outgoing mailbox
The next prompts in the sequence are related to outgoing mailbox
configurations with SMTP.

To configure your outgoing mailbox with SMTP

Enter the following information in the fields:
a Mailbox Name—Enter a descriptive name for your outgoing mailbox. For
example: AREmail - Outgoing.
b Display Name—Enter a descriptive name that appears in the From: line of
outgoing emails.

46 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

c Email Address—Enter the full email address of the administrator or

owner of the mailbox.
If you previously entered a display name of ARSystem and an email address
of arsystem@remedy.com, the From: line would be:
From: ARSystem [arsystem@remedy.com]

d Server Name/IP—Enter the name or IP address of your company’s mail

server.
e Server Port—Enter the mail server port number (default is 25).
f Server User—Enter the name of the user or administrator of the email
account (null if not applicable).
g Server Password—Enter the password corresponding to the server user
(null if not applicable).
Go to “Completing the installation” on page 40.

Completing the installation

To complete the installation, enter the installation directory at the prompt.
The script displays a list of extracted files and error messages (if there are
any).

Note: After you complete the installation, restart the server. Restarting the
server will restart the email engine.

Postinstallation steps
This section describes optional postinstallation steps.

Starting and stopping the email engine

The email engine is configured to start automatically in both UNIX and
Windows.
If the email engine fails to start automatically, use the instructions in this
section to start it manually.
This section also includes instructions to stop the email engine manually.

Postinstallation steps
47
BMC Remedy Action Request System 7.0

Note: The email engine will also stop if you stop the AR System server
manually from the Services window. However, the engine will not start
again when you restart the AR System server—you must restart the engine
manually.

UNIX—Starting and stopping the email engine

Use the following instructions to start and stop the email engine on UNIX.

To start the email engine on UNIX manually

1 Change directories to the email engine installation directory.
cd <email_engine_install_dir>

2 Enter one of the following commands to start the email engine manually:
emaild.sh start &

or
# nohup emaild.sh start &

To stop the email engine on UNIX manually

1 Enter the following command to change directories to the email engine
installation directory:
cd <email_engine_install_dir>

2 Enter the following commands to stop the email engine:

# emaild.sh stop &

After you issue this command, AR Monitor stops the email engine service
and immediately restarts it automatically.
If the emaild.sh command fails to stop the email engine, comment out the
following line in the armonitor.conf file, then reissue the emaild.sh
command:
/etc/arsystem/<server_name>/armonitor.conf

Windows—Starting and stopping the email engine

Use the following instructions to start and stop the email engine on
Windows.

48 Chapter 2—BMC Remedy Email Engine installation and setup

 Administering BMC Remedy Email Engine

To start and stop the email engine on Windows manually

1 From the Services window:
a Choose Start > Settings > Control Panel > Administrative Tools >
Services.
b Select the BMC Remedy Email Engine service.
c Right-click the service and choose Start or Stop.
The email service will start or stop immediately.
2 From a command line:
a Change directories to the email engine installation directory.
cd <email_engine_install_dir>

b Enter one of the following commands to start the email engine:

emailstart

or
java -cp emaildaemon.jar;arapi70.jar;arutil70.jar;activation;
jar;mail.jar;imap.jar;smtp.jar;pop3.jar;
com.remedy.arsys.emaildaemon.EmailDaemon

c Enter the following command to stop the email engine:

emailstop

Note: MAPI mailbox users only: If you did not configure your MAPI mailbox
during installation, change the email engine login information in the
Services window to your Windows user account.

Postinstallation steps
49
BMC Remedy Action Request System 7.0

50 Chapter 2—BMC Remedy Email Engine installation and setup

Chapter

3 Configuring mailboxes in the

BMC Remedy Email Engine

This chapter explains how to create and configure email engine mailboxes
and how to set security options.
The following topics are provided:

Overview—Email configuration (page 52)

Configuring outgoing mailboxes (page 53)

Configuring incoming mailboxes (page 59)

Testing your mailbox configuration (page 65)

Configuring email security (page 69)

MAPI—Saving outgoing notifications (page 75)

Changing the form entry interval time (page 76)

Configuring SSL for the email engine (page 76)

Configuring mailboxes in the BMC Remedy Email Engine
51

BMC Remedy Action Request System 7.0

Overview—Email configuration
This chapter describes how to configure your mailboxes. A mailbox is an
entry in the AR System Email Mailbox Configuration form that contains all
of the information required to access email from a mail server or to request
that email be sent by a mail server. You must configure at least one mailbox
to communicate with your mail server to send or receive email.
The minimal configuration tasks you must perform to send and receive email
are creating and configuring outgoing and incoming mailboxes. You can
change initial configuration information in the respective forms later.
If you entered mailbox configuration information during installation, you
will be able to send and receive emails. However, you must perform
additional steps to set up advanced mailbox options, such as default values,
parsing, and mailbox security. Check the procedures in this chapter for
configuration options that you did not set during installation.
Configuration information is stored in forms on the AR System database.
For more information about email engine forms, see Appendix E, “BMC
Remedy Email Engine forms.”

52 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Configuring outgoing mailboxes

This section describes procedures to create and configure outgoing
mailboxes. The configuration information you choose in these procedures is
stored in the AR System Email Mailbox Configuration form. You must create
at least one outgoing mailbox to process outgoing mail.

Figure 3-1: Setting default outgoing mailbox

Set default outgoing

mailbox

Based on the configuration options you choose in this section, the email
engine creates and sends messages. Outgoing messages might include results
from actions specified in incoming messages, such as query or workflow
results.
Outgoing mailboxes can also be linked to incoming mailboxes, such that the
results of any actions from a specific incoming mailbox are sent to the
specified outgoing mailbox.

Note: To use notifications with email, you must designate one mailbox as
your default notification mailbox.

Configuring outgoing mailboxes
53

BMC Remedy Action Request System 7.0

Basic outgoing mailbox configuration

This section describes how to perform a basic configuration for your
outgoing mailbox. The following figure shows an example of the Basic
Configuration tab for the SMTP email protocol.

Figure 3-2: Basic Configuration tab for outgoing mailboxes

Outgoing mailboxes support the following mail protocols: MAPI and SMTP.

To create a basic configuration for your outgoing mailbox

1 MAPI only:
a Enter the following information in the fields above the tabs:

Mailbox Name—Enter a descriptive mailbox name.
Use a name that describes the function of the mailbox.
For example, enter ARSystemEmail - Outgoing.

Mailbox Function—Select Outgoing.

Status—Select Enabled to enable the options.
b Enter the following information in the Basic Configuration tab:

Server Type—Select MAPI from the menu.

Polling Interval—Select a polling interval for the email engine to check
for new incoming email from the mail server.

Profile Name—Enter the name of the MS Exchange profile you created
in the preinstallation section of the installation chapter.
This field is required because a profile is used to see MAPI email
account configuration information. For more information about MS
Exchange profiles, see your MS Exchange documentation.

54 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

c Click Save.
2 SMTP only:
a Enter the following information in the fields above the tabs:

Mailbox Name—Enter a descriptive mailbox name.
Use a name that describes the function of the mailbox.
For example, enter ARSystemEmail - Outgoing.

Mailbox Function—Select Outgoing.

Status—Select Enabled to enable the options.
b Enter the following information in the Basic Configuration tab:

Server Type—Select SMTP from the menu.

Polling Interval—Select a polling interval for the email engine to check
for new incoming email from the mail server.

SSL—Check the box to enable Secure Socket Layer (SSL). For more
information, see “Configuring SSL for the email engine” on page 76.

Server Name/IP—Enter the name or IP address of your company’s mail
server.

Server Port—Enter the mail server port number, or click Set Default
Email Server Port to accept the default port.

Server User—Enter the name of the user of the email account. The
email engine uses this email account to authenticate requests for
outgoing messages

Server Password—Enter the password corresponding to the server user.
Enter a user and password only if your mail server requires
authentication information before sending out email.
c Click Save.

Configuring outgoing mailboxes
55

BMC Remedy Action Request System 7.0

Advanced outgoing mailbox configuration

This section describes how to perform an advanced configuration for your
outgoing mailbox in the Advanced Configuration tab. Figure 3-3 shows an
example of the Advanced Configuration tab.

Figure 3-3: Advanced Configuration tab for outgoing mailboxes

An outgoing mailbox can be configured to use default templates, including a

default header, footer, content, results, or status template. You can choose to
configure your mailbox to use defaults in one or more of the categories; for
example, you can choose to specify a default header and footer template but
no content template. Only one default template of each type can be specified
for a mailbox. Templates must already be stored in the AR System Email
Templates form.
Outgoing mailboxes support the MAPI and SMTP mail protocols.

Important: Before you enter your choices, consider reviewing the

information about advanced configuration settings in Chapter 6, “Using
email templates.”

56 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

To create an advanced configuration for your outgoing mailbox

1 Enter the following information in the fields at the top of the tab:
a Associated Mailbox Name—Enter the name of an incoming mailbox to
associate with your outgoing mailbox.
This incoming mailbox receives instructions and must have already been
created.

Note: To use modify actions, you must have an incoming and outgoing
mailbox configured, and these two mailboxes must be associated with one
another. For more information, see “Modify action” on page 195.

b Default Outgoing Mailbox—Select Yes to make this outgoing mailbox the

default mailbox.
The default mailbox routes all email that does not have a specified
outgoing mailbox associated with it.
c Display Name—Enter a descriptive name that appears in the From: line of
outgoing emails.
MAPI only: This option is not used.
d Email Address—Enter the email address of the server user that you created
in step b on page 55
For example, if you entered a display name of ARSystem and an email
address of arsystem@remedy.com, the From: line would be:
From: ARSystem [arsystem@remedy.com]

MAPI only: This option is not used.

e Reply To Address—Specify an email address where replies to your
outgoing emails should be sent, or accept the default server user email
address already in this field.
MAPI only: This option is not used.
f Organization—Enter the name of the organization or company if your
email client displays your organization’s name.

Configuring outgoing mailboxes
57

BMC Remedy Action Request System 7.0

g Delete Outgoing Notification Messages—Select Yes to have workflow-

generated notification messages deleted from the AR System Email
Messages form after they have been sent from this mailbox.
Select No to save workflow-generated messages in the AR System Email
Messages form, or if you are going to use email templates to modify
records.
System administrators or other users with the appropriate permissions
must delete manual messages.
2 Enter information in the Default Addressing section for notifications and
escalations:
a Default To—Enter all email addresses that should receive outgoing
messages from this mailbox if no other email address is specified in the
message.
b Default CC—Enter all email addresses that should receive copies of
outgoing messages from this mailbox if no other email address is specified
in the message.
c Default BCC—Enter all email addresses that should receive blind copies
of outgoing messages from this mailbox if no other email address is
specified in the message.
3 Enter information in the Default Templates section for notifications and
escalations:
a Header Template—Select or enter a default header template if no other
header template is specified.
b Footer Template—Select or enter a default footer template to be used if no
other footer template is specified.
c Status Template—Select or enter a default status template to be used if no
other status template is specified.
d Result Template—Select or enter a default result/content template to be
used if no other result template is specified.
4 When you have selected or entered your choices, click Save.
For more information about notifications and escalations, see “Defining
workflow to send email notifications” on page 86

58 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Configuring incoming mailboxes

This section describes procedures to create and configure incoming
mailboxes. The configuration information you choose in these procedures is
stored in the AR System Email Mailbox Configuration form.
Based on this information, the email engine polls incoming mailboxes for
new messages, processes the messages, parses the contents (if the incoming
mailbox is set to parse), and performs the actions specified in the messages,
such as modifying requests or executing queries.
Incoming mailboxes support the following mail protocols: MAPI, POP3,
IMAP4, and MBOX.

Basic incoming mailbox configuration

Enter the information to create a basic configuration for your incoming
mailbox in the Basic Configuration tab on the AR System Email Mailbox
Configuration form. The following figure shows an example of this tab.

Figure 3-4: Basic Configuration tab for incoming mailboxes

During basic configuration, you enter the following information:

Mailbox information, such as the mailbox name

Server information, such as the mail protocol associated with the server
and the server port number

Configuring incoming mailboxes
59

BMC Remedy Action Request System 7.0

To create a basic configuration for your incoming mailbox

1 MAPI only:
a Enter the following information in the fields above the tabs:

Mailbox Name—Enter a descriptive mailbox name.
Use a name that describes the function of the mailbox. For example,
enter ARSystemEmail - Incoming.

Mailbox Function—Select Incoming.

Status—Select Enabled to enable the options.
b Enter the following information in the Basic Configuration tab:

Email Server Type—Select MAPI from the menu.

Polling Interval—Select a polling interval for the email engine to check
for new incoming email from the mail server.

Profile Name—Enter the name of the MS Exchange profile you created
in the preinstallation section in the installation chapter.
This field is required because a profile is used to see MAPI email
account configuration information. For more information about MS
Exchange profiles, see your MS Exchange documentation.
2 POP3 or IMAP4 only:
a Enter the following information in the fields above the tabs:

Mailbox Name—Enter a mailbox name.
Use a name that describes the function of the mailbox. For example,
enter ARSystemEmail - Incoming.

Mailbox Function—Select Incoming.

Status—Select Enabled to enable the options.
b Enter the following information in the Basic Configuration tab:

Server Type—Select POP3 or IMAP4.

Polling Interval—Select a polling interval for the email engine to check
for new incoming email from the mail server.

SSL—Check the box to enable Secure Socket Layer (SSL). For more
information, see “Configuring SSL for the email engine” on page 76.

60 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Server Name/IP—Enter the name or IP address of your company’s mail

server.

Server Port—Enter the mail server port number.

Server User—Enter the name of the user of the email account.

Server Password—Enter the password corresponding to the server user.
3 MBOX only:
a Enter the following information in the fields above the tabs:

Mailbox Name—Enter a mailbox name.
Use a name that describes the function of the mailbox. For example,
enter ARSystemEmail - Incoming.

Mailbox Function—Select Incoming.

Status—Select Enabled to enable the options.

Server Type—Select MBOX.

Polling Interval—Select a polling interval for the email engine to check
for new incoming email from the mail server.

Inbox Path—Enter the complete path to the MBOX file that
corresponds to the user email account.
For example, enter /usr/spool/mail/ARSystem, where ARSystem is the
file name.
4 When you have selected or entered your choices, click Save.

Advanced incoming mailbox configuration

Enter the information to create an advanced configuration for your
incoming mailbox in the Advanced Configuration tab on the AR System
Email Mailbox Configuration form. The following figure shows an example
of this tab.

Configuring incoming mailboxes
61

BMC Remedy Action Request System 7.0

Figure 3-5: Advanced Configuration tab for incoming mailboxes

Advanced configuration steps are shared by all mail protocols (MAPI, POP3,
IMAP4, and MBOX). During advanced configuration, you enter
information about associated mailboxes, templates, and forms, and
information related to mailbox security.

Important: Before you enter your choices, consider reviewing the

information about advanced configuration settings in Chapter 6, “Using
email templates.”

To create an advanced configuration for your incoming mailbox

1 Select an outgoing mailbox from the Associated Mailbox Name list. This
mailbox is used to reply to incoming emails that require responses, such as
incoming queries.

Note: To use modify actions, you must have an incoming and outgoing
mailbox configured, and these two mailboxes must be associated with one
another. For more information, see “Modify action” on page 195.

62 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

2 Complete the Action Configuration section:

a Email Action—Select Parse to enable the email engine to detect and
process instructions included in an incoming email message. This is
required if you use templates to perform Submit, Modify, or Query
actions.
See “Using label/value pairs in templates” on page 191 and “Incoming and
outgoing mail templates” on page 185 for more information about
templates and parsing.
b Upgrades from BMC Remedy Mail Server only; original template format
Use Original Template Format:

Select Yes to enable original parsing system processing.
Original parsing ignores special HTML fields, XML formats, and data
entered in an invalid format, such as a character string in a number
field. If this option is enabled, the email engine returns an error when it
encounters these types of fields or formats.

Select No to enable normal parsing.

Note: If you choose No, you must make sure that multiple lines in emails are
encapsulated with the [$$ and $$] multiple-line delimiters.

c Reply with Result—Select Yes to enable the email engine to return the
results of an action in an email.
Reply with Result allows the email sender to know if the incoming email
succeeded or failed. For more information, see “Action label” on page 194.
d Reply with Entry—Select Yes to return the complete entry of a submit or
modify action.

Note: To include attachments in an email, you must use a template. For more
information, see “Including attachments with incoming email” on
page 154.

e Enable Modify Actions—Select Yes to enable the email engine to modify

existing entries.

Configuring incoming mailboxes
63

BMC Remedy Action Request System 7.0

f Default Workflow Form—Enter the name of the default form on which

the email engine executes instructions from the incoming email message.
For example, the email engine might execute queries, form-entry
modifications, and form submittals.

Note: If you define a default workflow form, then incoming templates do not
require the Form (or Schema) label. For more information, see “Form
label” on page 192.

g Force Default Workflow Form—Select Yes to confine all instructions

from the incoming email message to the form that you specified in the
Default Workflow Form field.

Note: If an incoming template specifies a schema, the schema will not be

processed and the default workflow form instead will be used.

3 Complete the Incoming Security Configuration section:

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 enable a security key for incoming email.
When you enable this option, the information is added to the Email
Security form, so you do not have to supply the user name and password
in the incoming email. If you choose to enable the option, you must create
and configure the security key. See “Configuring incoming mailbox
security” on page 69.
b Use Supplied User Information—Select Yes to use AR System server login
information from the incoming email message.
If this option is enabled, the email engine uses this login information to
execute instructions in the incoming email message, such as instructions
to modify requests or submit queries.
For more information about login syntax, see “Login, Password, and TCP
Port labels” on page 193.

64 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

c Use Email From Address—Select Yes to use the email address of the
sender as a form of authentication.
If this option is enabled, the email engine returns an error if the sender’s
email address is different from the email address stored in the AR System
User form.
4 When you have selected or entered your choices, click Save.

Testing your mailbox configuration

You must test your mailbox configurations to make sure that your mailbox
communicates to your mail server correctly.

Note: If your email engine requires a security key to authenticate incoming

email, skip this section and see “Configuring email security” on page 69.

Testing your outgoing mailbox

Use the following steps to verify that you can send email from your outgoing
mailbox. If you complete the steps successfully, your outgoing mailbox is
configured correctly. If you are unable to complete the steps, see Chapter 7,
“Troubleshooting,” for more information.

To test your outgoing mailbox

1 In BMC Remedy User, open the AR System Email Messages form in New
mode.
2 In the AR System Email Messages form, create a message as follows:
a Mailbox Name—Select the name of the outgoing mailbox to test.
b Message Type—Select Outgoing.
c Message Tab—Enter email addresses for the From: and To: fields.

Note: Choose an email address that you can access with a third-party utility,
such as Microsoft Outlook.

d Message Tab—Enter a subject line and body content.

Testing your mailbox configuration
65

BMC Remedy Action Request System 7.0

3 Click Send.
4 Open the AR System Email Messages form in search mode.
5 Perform a query for the email message you sent.
6 In the results table, check for the following information:
a An entry corresponding to the email message.
b The value under the Send Message column = Yes.
A Yes value indicates that the outgoing mailbox has queued your email to
be sent.

Figure 3-6: Entry created of outgoing email message

7 Open the AR System Email Mailbox Configuration form in search mode.

8 Wait for the amount of time specified in the Polling Interval for the Outgoing
Mailbox you are testing (see the Basic Configuration tab).

Tip: Set the interval to one minute to view results promptly.

9 Open the AR System Email Messages form in search mode.

10 Enter the name of the outgoing mailbox to test and click Search.
11 In the results table, check for the following information:
a An entry corresponding to the email message exists in the table.
b The value in the Send Message column is Sent.
c The value in the Date Sent column is the precise time that the email
message was sent to the mail server.

66 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Figure 3-7: Entry created for the outgoing email message

12 Using a third-party email client, verify that the message was sent to the To
address you specified in step c on page 65.
If your test fails, see Chapter 7, “Troubleshooting.”

Testing your incoming mailbox

Use the following steps to verify that you can receive email in your incoming
mailbox. If you complete the steps successfully, your incoming mailbox is
configured correctly. If you are unable to complete the steps, see Chapter 7,
“Troubleshooting,” for more information.
Before you perform the test, obtain the correct email address for your email
account or profile from your email server administrator.

To test your incoming mailbox

1 In BMC Remedy User, open the AR System Email Mailbox Configuration
form.
2 Search for the name of the incoming mailbox to test.
3 Compare the email account you obtained from your email server
administrator with the email account or profile that your incoming mailbox
uses. If necessary, change the form entry to match the email account you
obtained from your administrator.
4 In a third-party email client, create an email containing a subject line and
body content.
5 Send the email to the email address you verified in step 3.
6 Wait for the amount of time specified in the Polling Interval for the Incoming
Mailbox you are testing (see the Basic Configuration tab).
7 Open the AR System Email Messages form in Search mode.

Testing your mailbox configuration
67

BMC Remedy Action Request System 7.0

8 Select a mailbox name and perform a search. The results table displays the
entry corresponding to the message you sent. Figure 3-8 shows an example
of an entry.

Figure 3-8: Test entry example

9 Double-click the entry to open the form containing the information for that
entry.
10 Make sure that the subject line and content in the form are the same as the
subject line and content of the test email you sent. If they are the same, your
test was successful.
If your test fails, see Chapter 7, “Troubleshooting.”

68 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Configuring email security

Incoming and outgoing emails use different security mechanisms.

Incoming email messages use security keys, the user’s login and password,
or the user’s email address for validation. As long as the email has one of
the previous security mechanisms, the email engine will execute the
appropriate action.
You can configure the email engine to use all three methods. But if the
email message is performing a modify action, then only a security key will
validate the user’s request.

Outgoing email messages, which include the results of query actions, use
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 included in the outgoing email message.
The following sections provide instructions for creating security keys for
incoming email, describe how security is handled for outgoing email, and
provide instructions for configuring the email engine to allow modify
actions.

Configuring incoming mailbox security

Security keys associated with an incoming mailbox validate the permissions
for incoming emails to perform various actions, such as modifying entries,
on the AR System server. In the AR System Email Mailbox Configuration
form, you specified whether a security key is required for email sent to a
mailbox (see “Advanced incoming mailbox configuration” on page 61). If
you chose to use a security key, you must create the key and associate it with
a mailbox in the AR System Email Security form.
When mail arrives, the email engine validates the security key included in the
incoming email message against the information in the AR System Email
Security form. If the key is valid, the email engine checks the mailbox owner
name in the form.

Configuring email security
69

BMC Remedy Action Request System 7.0

To create email security keys

1 In BMC Remedy User, open the AR System Email Security form in New
mode.

Figure 3-9: AR System Email Security form

2 Enter the following information in the fields:

a Status—Select Enabled to activate the key.
b Key—Enter a set of alphanumeric characters. Consider the following
issues before you enter the characters:

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 or

that could be easy to guess. For example, do not use a favorite product
nickname, your name, or a campus building name.

Mix numbers, letters, and special characters to make the key more
difficult to guess, for example: City2Scape or City!Scape.

Do not use spaces, forward slashes, or backslashes.

70 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

c User Name—Enter the name of a valid AR System user to which the

security key applies.
d Force for Mailbox—Select Yes to enable the security key for this mailbox
only. Enter No to enable the key for all mailboxes in your email
environment.
e Mailbox Name—Enter the name of the incoming mailbox that the
security key applies to.
f Force from Email Addresses—Select Yes to require this key for emails
received from specific email addresses.
Allows the key to work only if it comes from the mailbox contained in the
email addresses field.
g Email Addresses—Enter the email addresses that the security key should
apply to, if you enabled the Force from Email Addresses key.
h Expires—Select Yes if you want the key to expire on a specific date. If you
select Yes, the Expiration Date field becomes enabled.
i 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.
j Description—Enter a description of the key. For example, explain why the
key was created or include instructions to modify or delete it.

Configuring outgoing mailbox security

Outgoing email 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
included in the outgoing email message.
The email server uses the following criteria to define security for outgoing
emails that contain query results:

An email sent to only one user will contain data that only the user has
permission to view in BMC Remedy User.

An email sent to more than one user will only contain data that only the
user with the most restricted permissions can view in BMC Remedy User.

Configuring email security
71

BMC Remedy Action Request System 7.0

For example, if an email is sent to both an administrator with full access

permissions and to a user with only Public access, only data allowed by
Public access will be included in the email.

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

If a record is locked by the system through the row-level access feature, the
record will be included only if all email recipients have access to it.

If an email that includes query results is sent 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.

Configuring the email engine for replying with results

When you set the Reply with Result and Reply with Entry fields on the
AR System Email Mailbox Configuration form to Yes, the email engine sends
reply email back to the sender. The email engine formats the data from the
form back to the “Email From Address,” letting the sender see what was
submitted, queried, or modified on the form.

To configure the email engine for replying with results

1 Log in to BMC Remedy User.
2 Open the AR System Email Mailbox Configuration form in Search mode.
3 Search for and open the records for your incoming and outgoing mailboxes.
4 Make sure that you have an incoming mailbox and an outgoing mailbox
associated with each other.
5 Click the Advanced Configuration tab of the outgoing mailbox.
6 (Recommended for testing purposes) Set the Delete Outgoing Notification
Messages field to No.
7 Save your changes.
8 Click the Advanced Configuration tab of the incoming mailbox that you want
the modify instruction sent from.

72 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

9 Set the Email Action field to Parse.

10 Set the Use Original Template Format field to No.
11 Set the Reply With Result field to Yes.
12 Set the Reply With Entry field to Yes.
13 Set the Enable Modify Actions field to No.
14 Set the Force Default Workflow Form field to No.

Note: To use reply with results, make sure that you set one of the following
parameters to Yes.

15 Set the Use Security Key field to Yes.

16 Set the Use Supplied User Information field to Yes.
17 Set the Use Email From Address field to Yes.
18 Save your changes.

Configuring the email engine for modify actions

Modifications are executed by sending a modify instruction or modify action
to the email engine. Typically, you want only trusted users making changes
to records, especially if they are using email as a client to the AR System
server. For security reasons, incoming email with modify instructions do not
work by default; you must configure the incoming mailbox to accept modify
actions.

Important: You must provide a security key for every user who sends modify
instructions to the email engine.

To configure the email engine for modify actions

1 Log in to BMC Remedy User.
2 Open the AR System Email Mailbox Configuration form in Search mode.
3 Search for and open the records for your incoming and outgoing mailboxes.
4 Make sure that you have an incoming mailbox and an outgoing mailbox
associated with each other.

Configuring email security
73

BMC Remedy Action Request System 7.0

5 Click the Advanced Configuration tab of the incoming mailbox you want the
modify instruction sent to.
6 Set the Email Action field to Parse.
7 Make sure the Reply with Result field is set to No.
8 Set the Enable Modify Actions field to Yes.
This enables the email engine to receive modify actions. (This field is set to
No by default.)
9 Set the Use Security Key field to Yes.
10 Save your changes.
11 Click the Advanced Configuration tab of the outgoing mailbox that you want
the modify instruction sent from.
12 Set the Delete Outgoing Notification Messages field to No.
You cannot modify a record by email if you delete outgoing email messages.
13 Open the AR System Email Security form in New mode.
You use this form to create a valid security key for every AR System user who
is allowed to modify entries using the email engine.
14 Create a user record as follows:
a Set Status to Enabled.
b Create a security key.
c Make sure the Force For Mailbox field is set to No (default).
The Force From Email Address enforces the email address that is
associated with the key to be used. You can set this field to Yes or No. If
you set this field to Yes, then the From Address of the reply sent by the user
is checked with the security key entry’s From Address specified in the
security form.
d Enter other information as needed, for example, an expiration date.

Note: Users making modifications must have a write license unless they are
the submitter or the submitter mode is set to locked.

74 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

15 Save your changes.

Figure 3-10 shows Francie Frontline’s security key in the AR System Email
Security form.

Figure 3-10: User in AR System Email Security form

Set security key

MAPI—Saving outgoing notifications

If you use the MAPI email protocol and you want to save messages on the
Exchange server, you must configure your outgoing mailbox to save
outgoing notification emails in an Outlook folder.
To save outgoing notifications, add the following line to the
EmailDaemon.properties file:
com.remedy.arsys.emaildaemon.<AR_System_server>.MAPI_Sent_Folder=<fol
der_name>

where:

<AR_System-server> is the name of the AR System server associated with
the Email Engine.

MAPI—Saving outgoing notifications
75

BMC Remedy Action Request System 7.0

<folder_name> is the name of the folder that stores the outgoing

notification emails. Enter Sent Items here to save messages to your Sent
Items folder on Outlook.

Changing the form entry interval time

When the email engine starts, it retrieves all the entries in the AR System
Email Mailbox Configuration form and creates incoming and outgoing
mailboxes. Every 30 minutes, the email engine automatically queries the
form for changes to the form entries and updates the information.
To enable changes to form entries before the next default query time, stop
and restart the email engine.
To shorten the default time interval in the EmailDaemon.properties file, set
the polling parameter. For example, shorten the time to 5 minutes:
com.remedy.arsys.emaildaemon.<AR_System_server_name>.Interval = 5

For more information about this property or the EmailDaemon.properties

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

Configuring SSL for the email engine

Enterprise and stand-alone certification authorities (CA) can issue
certificates for secure email using SSL. This section explains in general terms
how to configure the Secure Socket Layer (SSL) for use with the email engine.
There is no “One Size Fits All” CA solution. You must consider various
factors when using SSL, for example, what CA you decide to use.
Configuration differs considerably whether you use a commercial CA
authority like VeriSign, or you configure a certificate server in a non-active
directory environment using Microsoft’s Certification Authority
management console.

Note: Secure Sockets Layer (SSL) is an open standard developed by Netscape

Communications for establishing and protecting web communications
and preventing the interception of critical information, such as credit card
numbers.

Figure 3-11 illustrates a digitally signed email message that uses SSL.

76 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Figure 3-11: Email with digital signature

Dig
me
in e

For more information, you can read an excellent description of general CA

procedures (for Windows systems) at the following URL:
http://www.jsiinc.com/SUBM/tip6300/rh6395.htm

To configure SSL for the email engine

1 Set up a local CA or search for a CA to use with your mail server.
You must decide whether to use a commercial CA (for example, VeriSign) or
use a CA created in-house. Most Windows system administrators can set up
a CA on a Windows server in just a few minutes. The primary difference
between a commercial or in-house CA is that a “cert” (certificate) issued by
Verisign is trusted far and wide, while a cert issued by an in-house CA is
trusted by no one outside the organization.
2 In Exchange System Manager (performed by an Exchange system
administrator only), return the properties for the IMAP virtual server.
a Use the Certificate Wizard to generate a cert request.
b Save it where you can easily access it.

Configuring SSL for the email engine
77

BMC Remedy Action Request System 7.0

c Submit the cert request to the CA.

The steps needed to submit and receive a cert from a CA vary, depending
on the CA.
d Wait for the reply.
e Use the Certificate Wizard a second time to install the cert received from
the CA.
After you complete these steps, the IMAP server is equipped with a
certificate.
3 Make sure that email users obtain their own certificate.
a Generate a personal certificate through the CA that users will use for
signing and encrypting their email messages. With a local CA, the cert will
probably be retrieved and installed using the browser.
b In the email client, go to the properties of your IMAP account and select
the new cert to use for signing and encrypting email messages, as shown in
Figure 3-12.

Figure 3-12: Selecting a cert to use with your IMAP account

78 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

 Administering BMC Remedy Email Engine

Two users who have properly configured the certs on their mail client
must then exchange certificates so that their communications can be
secured.
c Send email messages that are signed, but not encrypted, between the two
users.

Figure 3-13: Signed email

Bu
sig

Outlook Express has large buttons for signing and encrypting messages, as
shown in Figure 3-13. The email client should automatically notice the
signed message and store the certificate, so that it can be used to encrypt
further messages exchanged between the users.

Configuring SSL for the email engine
79

BMC Remedy Action Request System 7.0

80 Chapter 3—Configuring mailboxes in the BMC Remedy Email Engine

Chapter

4 Outgoing email

This chapter provides information and instructions for creating and

transmitting outgoing email messages from the email engine. The following
topics are provided:

Overview—How outgoing email works (page 82)

Using outgoing email (page 84)

Using notifications (page 85)

Using the Email Messages form to send outgoing email (page 108)

Sending reply email—Giving a professional look to outgoing email
(page 126)

Outgoing email
81
BMC Remedy Action Request System 7.0

Overview—How outgoing email works

Figure 4-1 presents a sample scenario that demonstrates how the email
engine sends outgoing notifications. In this scenario, John, the local BMC
Remedy administrator, has decided to test the notification capabilities of the
BMC Remedy Email Engine.

Figure 4-1: How the email engine send outgoing email notifications

Underlying
Database

AR
System
Server

HD Incident

6.3 Email Engine

Escalation
Field 1 Abcdefg

Field 2 Hijklm

Field 3 Nopqrst

AR System
1 admin defines
2 Server executes
SLA
escalation workflow
that triggers Notify
action

Email messages
Outgoing
To: Abcdefg records
From: Hijklm

Message: Nopqrstuvwxyz
1234567890

Email
Engine

Outgoing Mailbox

3 Outgoing email
is formatted
and assembled

Mail
Server

Email
account

User receives
4 urgent ticket
assigned to him

Bob
Backline

82 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Step 1 In the XYZ Company, the IT department has a service-level agreement (SLA)
that urgent HD incident tickets must have a response in one hour. The BMC
Remedy administrator designs an escalation that triggers a Notify action to
send an email notification to the backline support engineers if the SLA is not
met. Because of a sudden swell of incoming tickets, the front line engineers
are swamped and cannot respond to one of the urgent request in one hour.
As a result, the AR System server triggers an escalation.

Step 2 Because John has configured the Notify escalation to use email as the
notification mechanism, when the escalation is triggered, the AR System
server creates an outgoing record in the AR System Email Messages form.
The email engine monitors the AR System Email Messages form for all
outgoing messages, and then sends the messages to the outgoing mailbox on
the mail server.

Step 3 The email engine constructs the message according to formatting

instructions contained in the Outgoing Mailbox it is using. This message
consists of the field values from the HD Incident form (submitter, short
description, its urgent status, assignee, and so on). The email engine then
transmits the message to the mail server with instructions to notify Bob
Backline, the back line Customer Support engineer.

Step 4 Bob’s email client receives the new email. He reads that an urgent ticket has
been assigned to him. Most importantly, Bob sees that all the necessary
details of the ticket are contained in the email constructed by the email
engine.

For more information, see the following sections:

“Configuring outgoing mailboxes” on page 53

“Defining workflow to send email notifications” on page 86

Overview—How outgoing email works
83

BMC Remedy Action Request System 7.0

Using outgoing email

Important: The examples of outgoing email in this chapter make extensive
use of label/value pairs, aliases, variables, templates, and special keyword
syntax as message content; the BMC Remedy Email Engine ignores any
other text. For more information, see the detailed reference material and
examples of their use in Chapter 6, “Using email templates.”

The sections in this chapter are divided into the three types of outgoing email
in the BMC Remedy Email Engine:

Notifications—The most important use of outgoing email is using
workflow to send notifications to users. The AR System uses the email
engine to send all notifications, not just email. You must install the email
engine to send notifications from the AR System server. For more
information, see “Using notifications” on page 85.

Replies to senders—The next most common function of outgoing email is
making replies to senders (who send email to the incoming mailbox) with
results. When you created an incoming mailbox, one crucial task you
performed was associating an outgoing mailbox, specifically for the
purpose of replying to emails that require a response, for example, query
results. For more information, see “Sending reply email—Giving a
professional look to outgoing email” on page 126.

Messages form—You have the ability to send outgoing email using the
AR System Email Messages form. You can type the message, or specify
contents templates to use in the body of the email. Typically, you only use
the AR System Email Messages form for configuring or troubleshooting
the email engine. The average user will never see or need this form. For
more information, see “Using the Email Messages form to send outgoing
email” on page 108.

84 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Using notifications
The most important use of the BMC Remedy Email Engine is sending
notifications to users because the AR System uses it to send all notifications,
not just email. You must install the email engine to send notifications from
the AR System server.
One major benefit of the email engine is the ability to notify users with a
professional-looking HTML-formatted email. Figure 4-2 illustrates a
notification generated by the email engine that a ticket was created and sent
to a user. In the notification email, users can then click a direct access URL to
open the ticket in a browser and view additional details about the ticket.

Figure 4-2: Email notification sent by the email engine

User clicks direct

access URL in
notification email

Direct access URL opens

email ticket in browser
(also formatted in HTML)

Using notifications
85
BMC Remedy Action Request System 7.0

If you choose Email as the delivery mechanism 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 install the BMC Remedy Email Engine.
The BMC Remedy Email Engine can be installed on a separate server from
the AR System server processing the workflow. When you install BMC
Remedy Email Engine, point to the AR System server you intend to use. For
more information about using filter or escalation workflow, see the Form and
Application Objects 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.

Defining workflow to send email notifications

When the filter or escalation is triggered (for example, from a filter submit or
modify action, as shown in Figure 4-3), the AR System server will log a
message containing the notification text (and field contents—these are
optional) on the AR System Email Messages form. The email engine then
picks up the entries from the form, processes them, and sends the email
notifications to the designated user (or group).

86 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Figure 4-3: Filter window

In a Notify action from filter or escalation workflow (see Figure 4-4 on

page 88), you can select email as a notification mechanism. When you select
email, the bottom part of the window displays three tabs—Fields, Messages,
and Templates—that are used to define the configuration and contents of
your email message.

Tip: This section borrows from the Email Engine: Administering (Webcast)
available from BMC Remedy Training. This webcast includes .def and
data files you can download and modify for your own use. For more
information,seehttp://www.remedy.com/solutions/services/education/.

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

Using notifications
87
BMC Remedy Action Request System 7.0

To define workflow to send email

1 Make sure that you have an outgoing mailbox configured with Default
Outgoing Mailboxset to Yes or set Mailbox Namein the workflow to the configured
outgoing mailbox. Otherwise, you will not receive any notifications.
For more information, see Chapter 3, “Configuring mailboxes in the BMC
Remedy Email Engine.”
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.
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. Figure 4-4 shows these fields and an example of how a
Notify action might look.

Figure 4-4: Notify filter or escalation action

88 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

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

There is a 32 KB limit to the amount of text you can include in Email
notifications, instead of the 255-character limitation that existed in previous
versions of AR System. You can use the Text list to insert fields from the
current form or keywords into the text. The field or keyword will be
expanded when the notification is sent, to a maximum of 32 KB.
You can include sophisticated AR System functionality in the text of an email
notification. Figure 4-5 demonstrates the use of a direct access URL that
performs a search that goes directly to the request the user needs to view.
The $Impact$ incident, <a href="http://polycarp/arsys/servlet/
ViewFormServlet?server=polycarp&form=HD+Incident&eid=$Request
ID$">$Request ID$</a>, has been assigned to you.

This direct access URL appears in the notification email as a link that the user
clicks to display the ticket in a browser (as shown in Figure 4-2 on page 85).

Figure 4-5: Direct access URL used in email notification

Direct access URL

For detailed information about creating and using direct access URLs, see the
Form and Application Objects guide.
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 4-9 on page 95). You can enter a maximum of 255 characters.
To specify one or more recipients, enter any of the following choices
separated by hard returns (the server evaluates each line separately) in the
User Name field:

AR System user logins

AR System groups

Direct email addresses

Using notifications
89
BMC Remedy Action Request System 7.0

Include the email domain name if you are entering a direct email address (for
example, Joe.User@acme.com) or a keyword (for example,
$USER$@acme.com).

The order in which these entries appear is the order in which the email engine
searches for addresses.
If the contents of the User Name field do not match an existing User or
Group definition, the system interprets the field contents as a literal address
and sends the notification to that address by SMTP, IMAP, MAPI, or POP
mail protocols. This address can be an email address representing users who
are not using AR System, an alias for a group, or an email address
representing a program.

WARNING: Do not use group notifications as an email system for broadcast

type items because the server processes a notification for each member. An
email alias is more efficient.

If you are using a field reference (for example, $Submitter$), do not include
the domain name as part of the notification because the email address is
being read from the Email Address field of the user’s entry in the User
form.

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 about using the EmailDaemon.properties file, see

“Performance and configuration settings” on page 236.
8 From the Mechanism field, select Email.
The Fields, Messages, and Templates tabs become activated. For more
information, see “Defining fields in email notifications” on page 91 and
“Using the Messages and Templates tabs” on page 93.

90 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

9 Select the Add Shortcut check box to include the originating request as an
ARTask attachment in the email that is sent.
10 Save the filter or escalation.

Defining fields in email notifications

You use the Fields tab to define the subject line of the email and indicate
which fields (if any) to include in the body of the email, as shown in Figure 4-
6.

Figure 4-6: Subject line and fields in email notification

Subject line of email

Fields included in email

To define the Fields tab

1 Enter the text that will appear in the subject line of the email.
Subject text can include the use of keywords, for example, $USER$. The field
or keyword will be expanded when the notification is sent. If you enter a field
name in the Subject Line field, the notification will contain the value of the
field in the database. You can enter a maximum of 255 characters.
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.

Using notifications
91
BMC Remedy Action Request System 7.0

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.

Note: If you use a content template to format the email, the template will
override any of the options that are selected. For example, if an
administrator selected All, but the template only uses a few fields, only the
fields in the template appear in the email.

Make sure that all fields used as variables in header, footer, and content
templates are selected in the Include Fields list of the filter. (For more
information, see “Variables” on page 203.)
To be able to send the field contents, make sure that users being notified have
the necessary permissions. For more information about access control for
users, see the Configuring guide; for groups, see the Form and Application
Objects guide.
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-like 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 actual X and
Y coordinates in the form.
3 To include attachments in an email notification, select the attachment fields
from the Fields list.

92 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Figure 4-7: Including attachments with notifications

Attachment fields
you can include in
notifications

Make sure the receiver of the notification has permission to the attachment
field on the AR System form. Figure 4-7 shows that this notification will be
sent to the ticket assignee ($Assigned To$). To receive the attachment, the
$Assigned To$ group must have permission to the field, which the AR System
administrator defines when the field is created.
After the notifications are sent, the message status changes in the Email
Messages form from Yes to Sent.
If you chose to delete Notification messages in your mailbox configuration,
the notification email entry is deleted from the BMC Remedy Email Messages
form. (See “Deleting email notifications” on page 104.)

Using the Messages and Templates tabs

The Messages and Templates tabs allow you to determine at run time which
user the email came from, which mailbox to use, which templates to use, and
so on. 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.
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.

Using notifications
93
BMC Remedy Action Request System 7.0

Figure 4-8: Notify filter or escalation dialog box—Messages tab

Defining messages in email notifications

You use the Messages tab to define your mailbox configuration settings. If
you leave these fields blank, the values in your notification email default to
your current mailbox configuration settings.

To define the Messages tab

1 In the Mailbox Name field, enter the name of the outgoing 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.
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.

94 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

You can use the following entries in the fields:

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, Joe.User@acme.com) or a keyword
(for example, $USER$@acme.com).

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 BMC Remedy Email Engine populates the
equivalent fields in the AR System Email Messages form for the
appropriate User Name (Figure 4-9).

Figure 4-9: AR System Email Messages form

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.

Using notifications
95
BMC Remedy Action Request System 7.0

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.
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.
If you specify multiple recipients in the User Name field (see Figure 4-4 on
page 88), the name or names specified in the CC and BCC fields on this form
will appear only in the CC and BCC 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 might be a security issue, especially if you list a
group name with some ambiguity about which is the first name on the list.
You might 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.

Defining templates in email notifications

You use the Templates tab to define any templates to use in the email. If you
leave these fields blank, the values in your notification email default to your
current mailbox configuration settings. You could create workflow that
substitutes a specially designed urgent template to alert a manager to the
email’s importance. Figure 4-10 illustrates an email sent by the email engine
if an urgent ticket is created and no user is assigned (( 'TR.Impact' =
"Urgent") AND ( 'Impact' != 'DB.Impact') AND ( 'Assigned To' =
$NULL$ )).

96 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Figure 4-10: Urgent email generated by email engine

Tip: A more “advanced” solution can use a Set Fields action to dynamically
set template values using data-driven workflow on a transaction basis. For
example, a filter could read a value from a hidden field on a form. By
default, a notification would use a default header template. But if a ticket
was marked urgent, workflow would substitute a value that uses the urgent
header template instead. For more information, see “Dynamically
assigning templates to outgoing email” on page 99.

To define the Templates 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.
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.

Using notifications
97
BMC Remedy Action Request System 7.0

Figure 4-11: Notify filter or escalation dialog box—Templates tab

For more information about creating and using templates, see Chapter 6,
“Using 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.
If you want to use a content template for notifications, you must specify it
when creating workflow 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$$#

98 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

These formats are based on AR System core field ID 7. In addition, the Status
History strings shown here 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, and save your changes to the filter or escalation.
The system determines which templates to use in the following order:
a The template entries in this tab.
b 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 4-8
on page 94.)
c The templates set as defaults for the default mailbox.
d No templates are used.
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.

Dynamically assigning templates to outgoing email

The BMC Remedy Email Engine gives developers more control over the
content and format of email sent from AR System. Content creation and
formatting, including the use of graphics, are accomplished by designing and
storing the templates and images in the AR System Email Templates form.
The templates stored in this form are then used by the email engine to format
outgoing email.

Using notifications
99
BMC Remedy Action Request System 7.0

The filter and escalation Notify action integrates with email engine
templates, allowing dynamic template assignment. With templates stored as
“data in a form,” you can see them using workflow. The Templates tab of the
Notify action allows you to assign header, content, and footer templates. As
demonstrated in “Defining templates in email notifications” on page 96, you
can hard-code these templates by using the template name. You could also
dynamically assign templates through workflow.
Suppose that the XYZ software company uses four HTML header templates
(already stored in the AR System Email Templates form) to provide a banner
at the top of outgoing emails that are sent when records are assigned. The
templates are designed so that technicians can quickly tell if an incident’s
impact is urgent, high, medium, or low. The following table shows which
header template to use for an incident based on the impact:

Impact Template Name

Urgent Header_Urgent.htm

High Header_High.htm

Medium Header_Medium.htm

Low Header_Low.htm

You can create a data-driven approach to dynamically assign the correct

template for the appropriate impact.
The following procedure assumes your email engine is properly configured,
your users have their own email mailboxes set up, you have created and
stored your templates, and so on. This procedure requires that you first
create the following AR System objects.

Two regular forms (XYZ Templates and XYZ Incidents)

Selection field on templates form

Hidden character field on incident form

Filter using Set Fields and Notify actions

Search menu for template form (optional)

100 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

To dynamically assign templates to outgoing email

1 Create a regular form (for example, XYZ Templates).
2 Add a selection field to the XYZ Templates form.
This field should use the same attributes you plan on using to determine
template assignment. In this example, the Impact selection field attributes
are used—Low, Medium, High, and Urgent.
3 Create a character field (for example, Template Name) to store the value of the
template to be used.
4 (Optional) Attach a character field search menu that queries the AR System
Email Templates form as a further enhancement.
5 Log in to BMC Remedy User and open the XYZ Templates form in New
mode.
6 Create the records for each Impact type, selecting the proper value for the
Template Name field.
Four records are created—one for each of the impact values. Figure 4-12
illustrates that the urgent impact type uses the Header_Urgent.html
template.

Figure 4-12: Template records

Using notifications
101

BMC Remedy Action Request System 7.0

7 Create a regular form (for example, XYZ Incidents).

8 Add a hidden character field (for example, Header Template) to the XYZ
Incident form (Figure 4-13).
This field stores the name of the header template to be used with each
incident when it is created or modified.

Figure 4-13: Form with hidden fields

Hidden fields to
store templates

9 Create a filter to set the value for the Header Template field on the XYZ
Incident form.
a In the Basic tab, select XYZ_Incidents as the form.
b Select Submit and Modify as the execute conditions.
c Enter 'TR.Impact' != $NULL$ as the Run If qualification.
Here you want the filter to fire on Submit or Modify whenever the value of
the Impact field changes (that is, when the filter detects there is a new
transaction value in the Impact field).
10 In the If Action tab, create a Set Fields action with the following parameters:
a Read the value for the field from the XYZ_Templates form.
b Enter 'Impact' = $Impact$ as the Set Fields If qualification.

102 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

c Select Header Template as the field name and $Template Name$ as its
value.
With this workflow, the name of the proper template, based on its impact, is
stored with each incident. Here you define the filter to query the XYZ
Templates form created earlier where ‘Impact’ = $Impact$, and you set the
value of the Header Template field on the XYZ Incident form from the value
of the template name field on the XYZ Templates form.
11 On the filter, create a Notify action.
a Place the variable $Header Template$ in the Header field.
b Enter other parameters as needed, for example, $Submitter$ as the user
name, relevant text (including request ID of the ticket), and so on.
The result of this filter is data-driven automatic template assignment
workflow.
12 In the XYZ Incidents form, create a new ticket (for example, for Joe User)
and assign it an urgent value.
The filter workflow executes and creates a new ticket. This workflow will also
create an email notification with the proper header template dynamically
assigned based on its impact level. When Joe User opens his email client, he
receives the following email:

Figure 4-14: Email notification with Urgent header template

Using notifications
103

BMC Remedy Action Request System 7.0

This sample email could be easily enhanced with a content template used
specially for urgent tickets.

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 might 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 might result in incorrect date/time and numeric values being
displayed in a notification to different locales. For more information, see
“Submitting requests across different time zones” on page 260.

Deleting email notifications

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. This
default setting reduces the number of records stored in your message form.

Tip: Most of the time, you will only use the AR System Email Messages form
for troubleshooting the email engine. When you first start using the email
engine, you might not want notifications automatically deleted to make
sure they are sent to the expected users, outgoing email is formatted
correctly, and so on. But after your email engine is running correctly, you
should automatically delete email notifications, unless you are using email
templates to modify records; otherwise, your server can quickly fill up
with email notifications.

If you configure the system to delete messages automatically, the email

engine will not permit you to modify records. The email engine includes a
security feature that checks the outgoing records to verify that incoming
email with a modify action comes from the same server.

104 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

To delete email notifications

1 In the AR System Email Mailbox Configuration form, open the entry of your
outgoing mailbox.
2 Click the Advanced Configuration tab.

Figure 4-15: Option to delete outgoing notification messages

3 Set the Delete Outgoing Notification Messages field to Yes.

4 Save your changes.
For more information about configuring the email system, see “Advanced
outgoing mailbox configuration” on page 56.

Using templates with outgoing email

Email templates can help you with outgoing mail from the email engine, for
example, with email generated from notification actions or escalations. A
mail template exported with BMC Remedy Administrator lists all the
available field labels you could use, for example, in creating an outgoing
email.

Note: Replies to incoming email are not discussed in this section. For
information, see “Sending reply email—Giving a professional look to
outgoing email” on page 126.

Using notifications
105

BMC Remedy Action Request System 7.0

You can use content templates with notifications or escalations to arrange the
fields and values of the entry that triggered the notification. Content
templates used with notifications or escalations can contain the following
information:

Plain text

Variables
For example, the #$$AR Notification Text$$# variable is replaced by the
text entered in the Text Field of Notification group in BMC Remedy
Administrator.

Core fields
For example, core fields are replaced with their actual values in the email
that is sent out. You use the following syntax with core fields:
#$$<DatabaseNameOfField>$$#

Form fields
You can use the fields on the form on which the notification action or
escalation is based in content templates. You use the following syntax with
form fields:
#$$<DatabaseNameOfField>$$#

Content templates used with notifications or escalations cannot contain the

following information:

Keywords—Keyword substitution in content templates is not
implemented in the 7.0 email engine. As a result, $USER$ or $DATABASE$ in
content template will not be replaced with actual values.

Field IDs—Field IDs are not substituted with entry values. As a result,
#$$536870925$$#isincorrect.Instead,youshoulduse#$$Id_Integer$$#where
Id_Integer is the database name of the field

The following example illustrates a content template for outgoing

notifications:
#$$AR Notification Text$$#

CORE FIELDS:
-----------------
RequestId: #$$Request ID$$#
EmployeeName:#$$Name_Char$$#
Submitter:#$$Submitter$$#
ShortDescr:#$$Short Description$$#
LastModifiedBy:#$$Last Modified By$$#
Modified Date:#$$Modified Date$$#

106 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Status:#$$Status$$#
StatHist-User:#$$Status History.New.USER$$#
StatHist-Time:#$$Status History.New.TIME$$#

Employee Info General Fields:

------------------------------
Employee Name : #$$Name_Char$$#
Employee Id: #$$Id_Integer$$#
Employee Salary in Decimal : #$$Salary_Decimal$$#
Employee Salary in Currency : #$$Salary_Currency$$#
Employee Gender : #$$Gender_Dropdown$$#
Employee Marital Status : #$$Marital Status_Radio$$#
Employee Interests: #$$Interests_Dairy$$#
Employee Skills : #$$Skills_CheckBox$$#
Employee Vacation Left : #$$Vacation_real$$#
PresentOrPermAddChoiceField : #$$PresentOrPermAddChoiceField$$#

Joining Details:
---------------
JoiningDate_Date : #$$JoiningDate_Date$$#
JoiningDateTime_DateTime : #$$JoiningDateTime_DateTime$$#
Joininig Date_Time : #$$Joininig Date_Time$$#

XML outgoing content templates

You can specify outgoing content templates in XML format, as shown in the
following example:
<?xml version="1.0" encoding="UTF-8"?>
<Root>
<NotificationText>#$$AR Notification Text$$#</NotificationText>
<RequestID>ReqId: #$$Request ID$$#</RequestID>
<Submitter>Sub: #$$Submitter$$#</Submitter>
<ShortDescr>SD: #$$Short Description$$#</ShortDescr>
<EmpName>Emp Name: #$$name_char$$#</EmpName>
</Root>

HTML outgoing content templates

You can specify outgoing content templates in HTML format. HTML
outgoing content templates can contain graphic images. The following code
is an example of HTML outgoing content template that contains a GIF
image:
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<metahttp-equiv="Content-Type"content="text/html;charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">

Using notifications
107

BMC Remedy Action Request System 7.0

<title>Lighthouse</title>
</head>

<body>
<p><font face="Arial Black"> #$$AR Notification Text$$# </font></p>
<p><img border="0" src="./images/lighthouse.gif" width="174"
height="188"></p>
<p><font face="Arial Black"><b>Lighthouse</b></font></p>
<p><font face="Arial Black"> RequestID: #$$Request ID$$# </font></p>
<p><font face="Arial Black"> EmployeeName:#$$Name_Char$$#</font></p>
</body>

</html>

Using the Email Messages form to send outgoing email

You can use the AR System Email Messages form to send outgoing email, as
shown in Figure 4-16. You can type the message, or specify content templates
to use in the body of the email. To send email from the BMC Remedy Email
Engine, you must use a specific label/value pair syntax along with the Action
label in the body of the email.

Figure 4-16: AR System Email Messages form

108 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

You can include attachments with your email using the Attachments tab.
From the Advanced Options tab, you can use a template, substitute variables,
or an alternate attachment as your body content. (For information, see
“Displaying advanced options for outgoing email” on page 117.)

Sending outgoing email in plain text

You can use the email engine to send outgoing email in plain text. Plain text
email 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 plain text, HTML, or
XML.

To send outgoing email in plain text

1 Open the AR System Email Messages form in New mode in a web client (as
shown in Figure 4-17) or BMC Remedy User.

Figure 4-17: AR System Email Messages form (displayed in browser)

Using the Email Messages form to send outgoing email
109

BMC Remedy Action Request System 7.0

Tip: To view the AR System Email Messages form in a browser, use the
following syntax:
http://<host>/arsys/forms/<server>/<form>
For more information, see the Form and Application Objects guide.

2 From the Mailbox Name menu, select an outgoing 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. (For more information, see “Configuring outgoing
mailboxes” on page 53.)
3 Select Outgoing from the Message Type list.
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.
a In the To field, enter the name of the user you are sending the email to.
b Enter other information as needed, for example, an organization.
5 Enter a subject line for your email in the Subject field.
6 (Optional) Enter a priority number in the Priority field.
Use the following to determine what value to use in the email message within
BMC Remedy 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 (default)
4 Low importance
...
100 Low importance

110 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

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 about using the EmailDaemon.properties file, see

“Performance and configuration settings” on page 236.
7 Click the Plain Text Body tab and enter your message text.
There are no syntax requirements for typing “plain” text in your outgoing
message. However, any label/value pairs that you include must follow their
specific syntax. For more information, see Chapter 6, “Using email
templates.”

To add an attachment, see “Including attachments with outgoing email”
on page 114.

To send the email with a template other than the default templates for the
specified mailbox, see “Using the Templates tab” on page 117.

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
“Using the Variable Replacement tab” on page 119.
8 Click Send to send the mail from the outgoing mailbox to the user.

Sending outgoing email in HTML

You can use the email engine to send outgoing email messages in HTML or
XML, 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 plain text,
HTML, or XML.

Using the Email Messages form to send outgoing email
111

BMC Remedy Action Request System 7.0

To send outgoing messages in HTML

1 Open the AR System Email Messages form in New mode to create an
outgoing message.
See “Using the Email Messages form to send outgoing email” on page 108 for
sample contents of an outgoing message, especially steps 2 through 6.
2 Click the HTML Body tab.
3 Enter HTML contents, as in the following example:
Server: polycarp<BR>
Login:Francie Frontline<BR>
Password <input type="password" name="Password" size="15"
maxlength="14"> <BR>
Key:1234<BR>
Action: Modify<BR>
Form:TestSecurityForm<BR>
Request ID: 000000000000003<BR>
Assigned To <input type="text" name="!4!" size="20" value="Assignee">
<BR>
Short Description <input type="text" name="!8!" size="40"
value="Enter a short description">
<BR>
Status
<input type="radio" value="New" name="!7!"/> New
<input type="radio" value="Assigned" name="!7!" /> Assigned
<input type="radio" value="Fixed" name="!7!"/> Fixed
<input type="radio" value="Rejected" name="!7!"/> Rejected
<input type="radio" value="Closed" name="!7!"/> Closed
<BR>

In addition to HTML formats, any label/value pairs that you include must
follow specific syntax requirements. For more information, see Chapter 6,
“Using email templates.”
See any standard HTML reference book or reputable online source (http://
www.w3.org/) for how to define HTML, especially input type controls.
Additional HTML examples are demonstrated in “Sending modify
instructions in HTML” on page 161.
4 Click Send to send the mail from the outgoing mailbox to the user.
The email engine generates the email in Figure 4-18.

112 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Figure 4-18: Outgoing email (HTML format)

This outgoing email contains the following HTML input features:

Password control field—Users become nervous about sending passwords
in clear text. For security, this HTML message includes a Password control
field as an input type. When the user enters their password, the text is
masked; asterisks appear instead of the typed symbols or letters, as shown
in Figure 4-19.

Figure 4-19: Password field with encryption

Text input fields—Users modify the contents of the Assigned To and

Short Description fields by using text input fields.

Radio buttons—Users modify the status by selecting an input type Radio
control field. They can select only one radio button option.

Using the Email Messages form to send outgoing email
113

BMC Remedy Action Request System 7.0

Including attachments with outgoing 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 4-21 on page 115) stores attachments for
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.

To add attachments to your email

1 In the AR System Email Messages form, click the Attachments tab (Figure 4-
20).

Figure 4-20: AR System Email Messages form—Attachments tab

2 Click Add Attachment to open the AR System Email Attachments form

(Figure 4-21).

114 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Figure 4-21: AR System Email Attachments form

Attachment pool

3 Select Email from the Type list.

4 Right-click in the attachment pool and choose Add from the menu.
The Add Attachment dialog box appears.
5 Browse to the file you want to add and select it.
6 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.
7 Enter a name for the Attachment in the Attachment Name field.
If you do not specify a name, the system will see the attachment by its file
name and location. To change the name:
a Select the item in the attachment pool, and 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.

b Edit the file name as needed, for example, to template1.htm.

8 Click Save.
Your attachment is 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.

Using the Email Messages form to send outgoing email
115

BMC Remedy Action Request System 7.0

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 is 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
Use the following procedure to modify attachments in outgoing email.

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 to open the AR System Email
Attachments form.
4 Click Search to locate the attachment.
The attachment appears on the attachment list.
5 Modify the attachment as required. You can also modify the Attachment
Name.
6 Click Save to save your modification.

Deleting an attachment
Use the following procedure to delete attachments in outgoing email.

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 to open the AR System Email Association form.
4 Close this form.

116 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

5 Click the Refresh Table button to refresh the table in the Attachments tab of
the AR System Email Messages form.
The attachment is deleted from the list.

Displaying advanced options for outgoing email

For outgoing messages, you can include advanced options like replacing
variables. You can also view information and errors of the outgoing message.
To display the Advanced Options, Message Information, and Errors tabs,
perform the following tasks:

To display advanced options

1 Create an outgoing message.
2 Select Yes in the Display Advanced Options field of the AR System Email
Message form.
3 Select one of the advanced option tabs: Advanced Options, Message
Information, or Errors.

Advanced Options tab

The Advanced Options tab lets you replace templates, add variables, or use
alternative attachments.
Using the Templates tab
The Templates tab enables you to include a content, header, or footer
template with your outgoing 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 can 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 BMC Remedy
Administrator, selecting the form and the fields to be contained in the
template. Using the template, you can also specify actions to be performed
when the email engine parses contents of the email. The content template
can also contain formatting instructions.

Using the Email Messages form to send outgoing email
117

BMC Remedy Action Request System 7.0

Header and footer templates are often used to place lines of text or
graphics on an outgoing message. If header and footer templates are
specified in content templates as a label/value pair, they will be applied to
the email reply.
All the templates you use here must be previously stored in the AR System
Email Templates form.
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 “Configuring outgoing mailboxes” on page 53 for information
about configuring your outgoing mailbox.
Adding templates to outgoing email
Use the following procedure to add templates to outgoing email.

To add templates to outgoing email

1 In the outgoing message, display the advanced options and click the
Advanced Options tab.
2 Click the Templates tab.
3 Select templates from the relevant menu lists, or enter the name of a template
as defined in the AR System Email Templates form (Figure 4-22).

118 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

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

Using the Variable Replacement tab

The Variable Replacement tab (Figure 4-23) 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.

Using the Email Messages form to send outgoing email
119

BMC Remedy Action Request System 7.0

Figure 4-23: AR System Email Messages form—Advanced Options, Variable

Replacement tab (displayed in browser)

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.

To replace a field value using a variable replacement

1 Create an outgoing message.
2 Fill in header information.
3 Display the advanced options and click the Advanced Options tab.
4 Click the Templates tab.
5 Select a content template.
For example, this content template (which modifies an entry) uses the
following label/value pairs:
Server: polycarp
Login:
Password:
Key:

Action: Modify
Form: TestSecurityForm

120 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Request ID: [$$#$$Request ID$$#$$]

Submitter !2!:
Short description !8!:

This template includes a variable value for the Request ID field by replacing
the Request ID: 00000000001 label/value pair with
Request ID:[$$#$$Request ID$$#$$].

6 Click the Variable Replacement tab.

7 Enter a value for a variable in the template in the Field Values field, as shown
in Figure 4-23.
For example, with the following variable in your template:
Short Description !8!: #$$Short Description$$#

you would enter in the Field Values field:

!Short Description!: Create entry for new hire.

This value will then be substituted for the variable when the outgoing email
is sent.
When an entry is created in the Email Messages form for the outgoing
message, the Field Values field of the Variable Replacement tab is populated
with the database name of the field and its value in the entry. This database
name is matched with the database name that is specified within #$$…$$# in
the content template, and a substitution is made accordingly. So, make sure
to use the exact database name in content template delimited by #$$…$$#.
If you create an outgoing email from the Email Messages form instead of
using a notification or escalation, then you can use the field ID in the Field
Values field of the Variable Replacement tab. In the same tab, you can specify
the form name and qualification criteria. As a result, when the outgoing
email is sent, the qualification criteria is evaluated, entries that match the
criteria are retrieved, and the values of the entries are substituted for the field
IDs in the Field Values field. If a template is specified in the Templates tab
and the template contains field IDs, then those field IDs are substituted with
the values of field IDs in the field value of the Variable Replacement tab of the
Email Messages form.
8 Enter the name of the server on which the form resides.
9 Enter the name of the AR System form to which these values apply.
10 Enter any access information necessary in the AR System Server TCP Port
field and the AR System Server RPC Number field.

Using the Email Messages form to send outgoing email
121

BMC Remedy Action Request System 7.0

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

a record on which you want to perform an action (Figure 4-24).
This action will be specified in a Content template.

Figure 4-24: AR System Email Messages form—Advanced Options, Variable

Replacement tab (displayed in browser)

12 Send the outgoing email.

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

122 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Figure 4-25: Email with qualification replaced

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.

Using the Email Messages form to send outgoing email
123

BMC Remedy Action Request System 7.0

Using the Attachment Alternatives tab

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 or HTML. 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.

Figure 4-26: AR System Email Messages form—Advanced Options, Attachment

Alternatives

Attachment field
(for example, HTML)

Attachment pool

To add an attachment alternative

1 Create an outgoing message.
2 Fill in header information.
3 Display the advanced options and click the Advanced Options tab.
4 Click the Attachment Alternatives tab.

124 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

5 In the attachment pool, do the perform the following tasks:

a Right-click an attachment field corresponding to the contents of the
attachment, as shown in Figure 4-26.
b Select Add to open the Add Attachment dialog box.
c Select a file.
6 Select an encoding for the attachment or leave the field empty 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 attach only one of
each type of alternative attachment to a message form. These attachments are
stored as part of the message in the message form.
7 Send the outgoing email.

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.

Errors tab
The Errors tab enables users to view error messages if an email is not sent
correctly. For example, if the To field has an invalid character like a space,
then an error is generated and is viewable in the Error tab.

Determining message content of outgoing email

When sending an email message, the message content is determined
according to the following sequence:

Step 1 If you supply a template, the system uses it 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.

Using the Email Messages form to send outgoing email
125

BMC Remedy Action Request System 7.0

If you do not supply an attachment in the Values attachment field, but

supply 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 do not supply field values, but your content template contains 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 these points is true, the system uses the template as is.
Step 2 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.

Step 3 If none of the items in the previous steps is 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).

Sending reply email—Giving a professional look to

outgoing email
One of the major benefits of the BMC Remedy Email Engine is the ability to
send intuitive, user-friendly email messages that are professional looking.
Email messages consist of header, content, result, and (optionally) footer
components. Each component can be text or HTML. Usually, header and
footer templates are used as defaults in the outgoing mailbox, and content
templates are used in outgoing messages or filter notifications.

126 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Imagine a user sends an incoming email to search for all urgent open tickets.
Without the use of header or content templates, the email engine returns the
following reply email:

Figure 4-27: Reply email in ASCII format

This email is a simple ASCII-format message generated by the BMC Remedy

Email Engine. It is functional but quite plain.
Figure 4-28 shows the same outgoing email generated by the BMC Remedy
Email Engine, but this time configured to use an HTML header template and
an HTML result template when replying.

Sending reply email—Giving a professional look to outgoing email
127

BMC Remedy Action Request System 7.0

Figure 4-28: Reply email with HTML templates

The difference between the two outgoing emails is evident. The ASCII email
contains all the important details, but is plain. Using HTML templates,
outgoing email conveys the same information but is much more inviting to
read.

Note: Although most mail clients can display HTML, there might be some
clients that cannot display HTML. You need to assess which mail clients
are supported in your organization before implementing a pure HTML
solution.

128 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Using header templates as a banner with outgoing email

Adding a header to outgoing email messages can enrich the user experience.
With a basic knowledge of HTML, you can make your messages look
professional. Adding a header requires creating a template, and then
configuring the outgoing mailbox to use the new default header template.

Note: To add a footer template, you would use the same steps as described in
the following procedure.

To add a header template

1 Create a header image for the banner in your outgoing message.
2 Create an HTML header file (header_default.html) that contains the rug.gif
bitmap.
The following is a sample HTML header file that includes the bitmap:
<html>
<head>
<title>Default Header</title>
</head>
<body>
<table width="816" bgcolor="#99CC00">
<tr>
<td vAlign="top" width="196"><img src="rug.gif" width="200" height="90"
lowsrc="rug.gif"></td>
<td vAlign="top" width="608">
<div align="center">
<p>&nbsp;</p>
<p><b><font face="Geneva, Arial, Helvetica, san-serif" size="4">7.0 Email
Engine Demo </font></b></p>
</div>
</td>
</tr>
</table><hr>
</body>
</html>

This HTML code creates the following header:

Sending reply email—Giving a professional look to outgoing email
129

BMC Remedy Action Request System 7.0

Figure 4-29: Header template

3 Create an entry in the AR System Email Templates form for your header
template:
a Select HTML as the template format.
b Enter Header Default as the template name.
c Add header_default.html as an attachment.
d Click Add Attachment in the Template Attachments tab.
The AR System Email Attachments form appears.
e Select Template as the type.
f Enter rug.gif as the attachment name.
g Add rug.gif as an attachment and save the email attachment entry.
The AR System Email Attachments form closes.
h Click Refresh Table to display the bitmap template attachment.
i Save the template entry.
For more information, see “Adding attachments to HTML templates” on
page 211.
4 Open the outgoing mailbox entry in the AR System Email Mailbox
Configuration form.
5 Under the Advanced Configuration tab, specify Header Default as the default
header template.
6 Send a sample outgoing email.
Figure 4-30 displays the email sent by the BMC Remedy Email Engine to
your mail client.

130 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Figure 4-30: Outgoing message with header template

Using HTML result templates with outgoing email

If you do not specify a result template for reply email, the email engine uses
a default formatting for the returned data. To make this information easier
to read, you can format this data by creating a result template with field
variables.
To allow users to see the formatted results of their email action, you can easily
create a result template in a text editor. The following result template is a
simple example that formats the returned text with field variables:
XYZ Corporation

#$$Submitter$$# has successfully created a #$$Status$$# ticket.

Ticket Number: #$$Request ID$$#

#$$Assigned To$$# has been assigned to your request.

Problem Description: #$$Short Description$$#

Using an HTML result template (as shown in Figure 4-31) gives you greater
control over the appearance of the returned data and makes the return email
look much more professional.

Sending reply email—Giving a professional look to outgoing email
131

BMC Remedy Action Request System 7.0

For more information about data formats and labels, field variables, and
result templates, see Chapter 6, “Using email templates.”
The following example walks you through the procedure for using result
templates with outgoing email. The example is simple but complete, and you
can easily add more functionality.

To use HTML result templates with outgoing email

1 Make sure the email engine is properly configured to send reply results.
For more information, see “Configuring the email engine for replying with
results” on page 72.
2 Create a result template for your reply email.
Figure 4-31 is an HTML result template designed for this exercise. The fields
that are referenced in the result correspond to fields used in the HD Incident
form. The variables for field values must use the field name (its database
name) as the variable name, not the field ID.

Figure 4-31: HTML result template

3 Create an entry in the AR System Email Templates form for your result
template.
For more information, see “Adding attachments to HTML templates” on
page 211.

132 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

4 Export an email template from the HD Incident form.

For more information, see “Exporting mail templates” on page 188.
5 Create a new email in your email client and address the email to the BMC
Remedy email inbox account.
6 Copy and paste the contents of the exported email template into the new
email, and then fill out the required information for the template.
7 Add the result template parameter to the email, and then make sure you filled
in all the required fields.
Your email should look like the following example:
#
# File exported Tue Sep 28 17:01:33 2004
#
Schema: HD Incident
Server: POLYCARP.eng.remedy.com
Login: Demo
Password:
Action: Submit
Result: Results Template Default
# Values: Submit, Query
Format: Short
# Values: Short, Full

Last Name+ !536870916!: Stamps

First Name !536870917!: Ivan
Location !536870918!: Sunnyvale
Email Address !536870920!: stamps3@eng.remedy.com
Phone !536870919!: 408-555-1212
Category !536870913!: Networking
Type !536870914!: VPN
Item !536870915!: Cisco
Problem Summary ! 8!: Need to install VPN Client.
Status ! 7!: New
# Values: New, Assigned, WIP, Resolved, Closed
Submitter ! 2!: $USER$
Impact !536870927!: Low
# Values: Low, Medium, High, Urgent

8 Send the email to the incoming mailbox.

If you properly configured the email engine and included all the required
fields and the result template in your email, you should receive a reply email
(as shown in Figure 4-32) that includes the results of your submission.

Sending reply email—Giving a professional look to outgoing email
133

BMC Remedy Action Request System 7.0

Figure 4-32: Reply with results email

For more information, see “Creating an email reply using result templates in
HTML format” on page 270.

134 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Using XML result templates with outgoing email

You can use XML when creating templates for outgoing email. The following
example uses XML format when creating a result template. The results from
a query are returned in XML.

To use XML with outgoing email

1 Create a template file (for example, result_employee.xml) using XML format:
<?xml version="1.0" encoding="UTF-8" ?>
<Employee name="#$$Employee Name$$#">
<age>#$$Age$$#</age>
<salary>#$$Salary$$#</salary>
<address>
<street>#$$Street$$#</street>
<city>#$$City$$#</city>
<state>#$$State$$#</state>
<zip>#$$Zip$$#</zip>
</address>
</Employee>

This simple example contains an XML attribute (name), an attribute value

(#$$Employee Name$$#), and several elements (age) with their values (#$$Age$$#).

Tip: You can easily validate your XML file by displaying it in a browser.

2 Add the template as a text template to the AR System Email Template form.
The name of this XML template is employee. For information, see “Storing
templates in the AR System Email Templates form” on page 209.
3 Send an incoming email to the email engine that queries the server and
returns the results using the XML template, for example:
Action:Query
User: Demo
Server:polycarp
Schema:employee
Result Template:employee
Employee Name ! 536870913!:John Doe

This email specifies that the employee XML template be used in the outgoing
email to return the results of the query.
Figure 4-33 displays the outgoing email generated by the BMC Remedy
Email Engine.

Sending reply email—Giving a professional look to outgoing email
135

BMC Remedy Action Request System 7.0

Figure 4-33: Reply from email engine using XML template

Observe how the query results of this email are displayed in XML format. If
your outgoing mailbox is configured to include an HTML header, the
resulting email (combining an HTML header template with an XML result
template) would no longer be displayed in purely XML format.

136 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Using HTML content templates with outgoing email

Rather than entering raw HTML into your outgoing email, you can create
HTML templates to include content similar to header templates. For
example, if you need to send a questionnaire seeking input from users, you
can include HTML fields in the email message so that users can enter input
using text boxes, radio buttons, and so on, instead of as plain text.

To add content to an outgoing email message

1 Create an HTML template that you will include in your outgoing message.
The following sample HTML template defines font styles and colors in the
<BODY> tag. You can include embedded styles in your content file, but the BMC
Remedy Email Engine does not support linking your HTML template to a
cascading style sheet.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Remedy/BMC Picnic</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#FF0000" VLINK="#800000"
ALINK="#FF00FF" BACKGROUND="?">
<i><fontcolor=#006633face="Arial,Helvetica"><h1>Remedy/BMCCompanyPicnic</
h1></font></i><hr>
<i><fontcolor=#777777face="Arial,Helvetica"><h3>AreyoucomingtotheRemedy/BMC
company picnic?&nbsp;
<input type=radio name="F7">Yes</radio>
<input type=radio name="F7">No</radio></font></i><br/>
<i><font color=#777777 face="Arial, Helvetica">Number of additional
guests&nbsp;<inputtype=textname="Num_Guests"size=2></font></i></input>
</BODY>
</html>

2 Create an entry in the AR System Email Templates form for your content
template, for example, Remedy_Picnic_Invite.html.
For more information, see “Adding attachments to HTML templates” on
page 211.
3 Open the outgoing mailbox entry in the AR System Email Mailbox
Configuration form.
4 UndertheAdvancedConfigurationtab,specifyRemedy_Picnic_Invite.htmlas
the content template.

Sending reply email—Giving a professional look to outgoing email
137

BMC Remedy Action Request System 7.0

5 (Optional) Include a header or footer template.

Otherwise, your email will use any default templates configured for your
outgoing mailbox.
6 Send a sample outgoing email.
Figure 4-34 displays the outgoing email sent by the BMC Remedy Email
Engine to your mail client.

Figure 4-34: Outgoing message with header and HTML content templates

Using status templates with outgoing email

When an error occurs while executing instructions from an incoming email,
the BMC Remedy Email Engine automatically generates an outgoing email
with relevant status information. This system-generated email is simple,
containing only basic information, for example, the type of instruction that
failed, error messages, and so on:
Instruction: Query
Instruction Number: 1
Instruction Template:
Message Type:
Message Number: 24

138 Chapter 4—Outgoing email

 Administering BMC Remedy Email Engine

Message Text: No matching requests (or no permission to requests) for

qualification criteria.
Appended Text: TestSecurityForm

By using an HTML status template, your outgoing email can be more

professional-looking as well. The following procedure shows you how to
create an HTML template that will format status in a more attractive format,
as shown in Figure 4-35.

To include status templates with outgoing email

1 Create a status template.
The following is a sample HTML template created to display status:
<html>
<head>
<title>Status Template</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table width="75%" border="1" cellspacing="1" cellpadding="3">
<tr>
<td colspan="4">
<div align="center"><b>Your request to the AR Server returned
the following
error. If you have questions, contact your <a
href="mail%20to:%20stamps1@eng.remedy.com">Administrator</a>.</b></
div>
</td>
</tr>
<tr>
<td width="12%">Error Number</td>
<td width="28%">#$$ActionStatus.Number$$#</td>
<td width="18%">Message 1</td>
<td width="42%">#$$ActionStatus.Text$$#</td>
</tr>
<tr>
<td width="12%">Error Type</td>
<td width="28%">#$$ActionStatus.Type$$#</td>
<td width="18%">Message 2</td>
<td width="42%">#$$ActionStatus.AppendedText$$#</td>
</tr>
</table>
</body>
</html>

This HTML template defines a simple table with two rows for the error
number and error types. It also includes an email address that users can
respond to if they have questions. Of course, your HTML template could
include color, special fonts, and so on.

Sending reply email—Giving a professional look to outgoing email
139

BMC Remedy Action Request System 7.0

2 Create an entry in the AR System Email Templates form for your status
template, for example, Status_default.html.
For more information, see “Adding attachments to HTML templates” on
page 211.
3 Open the outgoing mailbox entry in the AR System Email Mailbox
Configuration form.
4 Under the Advanced Configuration tab, specify Status_default.html as the
status template.
5 (Optional) Include a header or footer template.
The sample email shown in Figure 4-35 uses the default header template
configured for the outgoing mailbox.
6 Send an incoming email to the BMC Remedy Email Engine that will generate
an outgoing status email, for example, a bogus query that returns no records.
Figure 4-35 displays the outgoing status email generated by the BMC
Remedy Email Engine.

Figure 4-35: Outgoing message with default header and HTML status templates

140 Chapter 4—Outgoing email

Chapter

5 Incoming email

This chapter provides information and instructions for sending email

messages to the AR System server using the email engine. The following
topics are provided:

Overview—How incoming email works (page 142)

Using incoming email (page 143)

Sending a query instruction to the email engine (page 144)

Sending a submit instruction to the email engine (page 150)

Sending a modify instruction to the email engine (page 154)

Overview—Using workflow to modify requests (page 166)

Searching for an entry to modify—Advanced solution (page 174)

Using variables with templates (page 177)

Displaying advanced options for incoming email (page 178)

Incoming email
141

BMC Remedy Action Request System 7.0

Overview—How incoming email works

Figure 5-1 presents a sample scenario that demonstrates how the email
engine receives incoming email.

Figure 5-1: How the email engine receives incoming email

Underlying
Database

AR
System
Server

HD Incident

6.3 Email Engine

Printer Broken

Abcd ef ghijkl mno

1 AR System admin
configured incoming
4
mailbox in email
Server creates
engine.
ticket.

Email
Engine
Incoming Mailbox

Email engine parses

3 instructions. Instructions
then translated into API
calls to server.

Email Mail
account Server

2 Submit email sent

to incoming mailbox.
"Printer
broken!"

Joe User

142 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Step 1 In the XYZ Company, the BMC Remedy administrator has configured the
BMC Remedy Email Engine to receive email submissions using email as a
client to the AR System server. To make email easier to use, he has created
and sent to his user base several email templates that cover typical work
situations, for example, submitting entries to the HD Incident form,
querying the status of their tickets, and so on.

Step 2 Joe User cannot print his document because his favorite printer has a paper
jam that he cannot fix. Rather than opening BMC Remedy User, he opens
one of the email templates and sends an email to submit a request to the HD
Incident form.

Step 3 The email engine receives the email from the mail server. It parses the
instructions in his email, and makes the appropriate API calls to the
AR System server.

Step 4 The server creates an entry in the HD Incident form. Slightly suspicious of
using email to create trouble tickets and also wanting to verify the status of
his printer problem, Joe User opens the HD Incident form in BMC Remedy
User. He is pleasantly surprised to find his entry, already assigned to the
frontline Customer Support engineer who is fixing the printer.

For more information, see “Sending a submit instruction to the email

engine” on page 150.

Using incoming email

Email sent to the email engine to access the AR System server must follow a
specific syntax. The syntax is specified by a given set of labels that are
recognized by the email engine. You can give different values to the labels.
“Using label/value pairs in templates” on page 191 provides a table of labels
that you can use to send incoming email to the email engine.

Important: The examples of incoming email in this chapter make extensive

use of label/value pairs, aliases, variables, templates, and special keyword
syntax as message content; the BMC Remedy Email Engine ignores any
other text. For more information, see the detailed reference material and
examples of their use in Chapter 6, “Using email templates.”

Using incoming email
143

BMC Remedy Action Request System 7.0

Using incoming email, users can submit, query, or modify entries on the
AR System server. Users can send incoming emails through an external email
client to a configured mailbox on the email engine. If users send email
through a third-party email client, they can either enter the content into the
body of the email or they can specify a template.
The message content of incoming email must follow a particular syntax that
is specified by a given set of label/value pairs, for example:
Schema: HD Incident
Server: polycarp
Login: Joe User
Password: 12345
Action: Submit

The rules for label/value pairs and variables are exactly the same as those for
templates.

Tip: Like BMC Remedy User, incoming email can trigger workflow that fire
on submit or modify. Email functions like any other BMC Remedy client
to the AR System. For example, if the transaction meets the filter’s Run If
condition, the filter will fire, regardless of whether the client is BMC
Remedy User or an email.

Sending a query instruction to the email engine

The easiest way to send queries to the email engine is to think of email as
simply another client of the AR System, like BMC Remedy User. When
performing queries with BMC Remedy User, users must perform certain
basic actions, for example, logging in, opening a form, and then performing
a query.
Using email as an AR System client is no different. To execute query
instructions to the email engine, the following information must be included:

AR System server name

AR System Login and Password to authenticate a user

Form name on which to execute the instruction

Query action

144 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

The major difference between BMC Remedy User and an email client is that
BMC Remedy User sends its queries directly to the AR System server, while
incoming email is first processed by the email engine and then sent to the
server.

To send a query
1 Create a new email message in your mail tool.
2 Address the email message to the incoming mailbox.
3 To execute a query that returns all fields of all entries in the HD Incident
form, enter the following information in your email message to the email
engine:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Query

Tip: Copy and paste these examples into your mail client, and then modify
them as needed.

Figure 5-2 shows the minimum of information you need to send a query
email. Here a label called Action specifies an instruction. To send a query to
the email engine, the label Action must be set to Query.

Figure 5-2: Query instruction email

Sending a query instruction to the email engine
145

BMC Remedy Action Request System 7.0

4 Send your email.

5 (Optional) Use the AR System Email Messages form to verify that the email
engine has received your email.

Figure 5-3: Incoming email received and outgoing mail sent

After the email engine has parsed the instruction and sent the query to the
AR System server, the server returns the query results that the email engine
sends back to the email client (as shown in Figure 5-4).
Otherwise, the email engine will return an error message that indicates
missing parameters or an error while parsing the qualifier.
6 Open the returned email to see the results of your query (Figure 5-4).

146 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Figure 5-4: Results returned

Tip: One benefit of the BMC Remedy Email Engine is that outgoing email
from the email engine can include a formatted header or footer, like the
HTML header template shown in Figure 5-4. For more information, see
“Incoming and outgoing mail templates” on page 185.

This email message sent from the email engine shows that all fields of all
entries in the HD Incident form were returned. In effect, your email query
was an unqualified search of the HD Incident form, useful for our example,
but certainly a performance impact on the server. You should always include
a qualification in your email queries.

Sending a query instruction to the email engine
147

BMC Remedy Action Request System 7.0

Including qualifications in your email

You can limit the entries returned by a query by using a label called
Qualification. The syntax of the value given to the qualification is the same
as what is used in the Advanced Search Bar in BMC Remedy User. As a result,
any search that executes in the Advanced Search Bar in BMC Remedy User
will also work with the Qualification label.

Tip: Create a user-defined instruction that runs the query. This allows the
user to quickly execute queries based on instructions that the
administrator has predefined.

To include qualifications in an incoming email message

1 Create an email.
2 To execute a query that returns all tickets submitted by Francie Frontline,
include the Qualification label with the following query value in your email
message to the email engine:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Query
Qualification: 'Submitter' = "Francie Frontline"

This query returns all fields of all records that were submitted by Francie
Frontline. In the qualification, the field name Submitter must be the same as
the database name of the field. Also, field names are case sensitive, and must
exactly match the database name of the field.
You can also query entries using field IDs instead of the database name of the
field. For example, the following Qualification label will produce the same
results when the Submitter field has a field ID equal to 2.
Qualification: '2' = "Francie Frontline"

In your qualification, you can also include relational operators. The

following qualification retrieves an entry whose employee ID = 9 and that
was submitted by Francie Frontline.
Qualification: 'Employee_Id' = 9 AND 'Submitter' = "Francie Frontline"

148 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Using “shorthand” qualification syntax

Like BMC Remedy User, which allows you to enter criteria into form fields
themselves (without entering them into the Advanced Search Bar), the email
engine supports a “shorthand” syntax of qualification criteria. For example,
when the Submitter field has a field ID equal to 2, the following syntax
produces exactly the same results as if you had entered “Francie Frontline” in
the Submitter field in BMC Remedy User:
!2!: Francie Frontline

You can use this same shorthand syntax to search for request IDs. The
following template searches for request ID from the HD Incident form:
Schema: HD Incident
Server: polycarp
Login: Demo
Password:
Action: Query

!1!:TT00000000119

Your email query can include multiple fields to search for all new urgent
requests:
File exported Tue May 21 21:38:47 2004

Schema: HD Incident
Server: polycarp
Login: Demo
Password:
Action: Query
Status !7!: New
Caller Impact !536870927!: Urgent

If the qualification does not match any entries, the email returned from the
email engine will indicate this.

Using the Format label

Observe that the confirmation email sent from the outgoing mailbox
(Figure 5-4 on page 147) listed all the fields of the form. This is the default
behavior of query instructions. You could use the Format label to send an
email query instruction that includes only the fields specified in the results
list of a form, just like the results you would see in BMC Remedy User.

Sending a query instruction to the email engine
149

BMC Remedy Action Request System 7.0

To use the Format label

1 Create an email.
2 To execute a query that returns only the fields specified in the results list,
include the Format label with the Short value in your email message to the
email engine:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Query
Format: Short

If the Format is not explicitly specified, by default, it will be automatically

assigned a value of Full, which will return all fields in the form.

Sending a submit instruction to the email engine

Like BMC Remedy User, you can use email as a client of the AR System to
submit entries on the server. To submit an entry into an AR System form,
send an email with instructions with the Action label set to Submit.
To execute submit instructions to the email engine, the following
information must be included:

AR System server name

AR System Login and Password to authenticate a user

Form name on which to execute the instruction

Submit action

Any mandatory fields

To use the Submit action label in an incoming email

1 Create a new email message in your mail tool.
2 Address the email message to the incoming mailbox.

150 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

3 To execute a submit action that creates an entry that contains the text
“Printer not working” in the Short Description field of the HD Incident
form, enter the following information in your email message to the email
engine:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Submit
!Submitter!: Francie Frontline
!Short Description!: Printer not working

The field name between the exclamation marks must exactly match the field
name in the database and is case sensitive.
As with a Query action, Submit actions can also use the field ID instead of the
database field name. The following syntax will return the same results if the
Short Description field ID equals 8:
!8!: Printer not working

You can add a comment before the exclamation mark used with field names
as in the following example. The email engine will parse only the characters
between the exclamation marks, for example, the field ID (8) of the Short
Description field:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Submit
What is the problem!8!: Printer not working
Who is submitting!2!: Francie Frontline

If the value for the field is more than one line, then enclose it between [$$ and
$$]. For example, if you have a longer value for the Short Description, it
could be sent to the email engine as:
! Short Description!: [$$This is a longer description
which spans multiple lines, so
use this syntax.$$]

The email engine will correctly parse the syntax when the email is submitted.
4 Send your email.
If you successfully submitted your email, the email returned will look
something like this:
Instruction 1 has successfully created a new record with Request ID :
000000000000001

Sending a submit instruction to the email engine
151

BMC Remedy Action Request System 7.0

If the incoming mailbox is configured to Reply With Entry, then all the fields
of the newly created entry will be returned to the sender. (For more
information about this configuration option, see “Advanced incoming
mailbox configuration” on page 61.)
If the entry cannot be created, the email engine will return an error message
(as shown in Figure 5-5) that indicates missing parameters. Make sure your
incoming email includes all required fields, for example, Submitter.

Figure 5-5: Error message reply from email engine

Tip: Another benefit of the email engine is that status from the email engine
can be formatted, like the status template shown in Figure 5-5. For more
information, see “Incoming and outgoing mail templates” on page 185.

152 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Using keywords
You can use keywords such as $USER$ to supply the actual value for the field.
Instead of specifying a text value, you can use keywords, as the following
example shows:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Submit
!Submitter!: $USER$
!Short Description!: Printer not working

Using the Format label

Like the Query instruction, you can use the Format label to specify if you
want your confirmation email from a Submit instruction to include all fields
from the form or only those fields in the results list. To use the Format label,
you must configure the incoming mailbox Reply With Entry parameter to
Yes. If Reply With Entry is set to No, then the Format label is ignored and the
confirmation email will contain only the Request ID number.

Note: Join forms do not send values of fields on Submit when the Reply with
Entry parameter is set to Yes for the incoming mailbox.

By default, the Format label is set to Full, which means all fields in the form
are included in the confirmation email. If you want the confirmation
message to include only fields from the results list, then set the Format label
to Short:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Submit
Format: Short
!Submitter!: Francie Frontline
!Short Description!: Create entry for new hire.

Sending a submit instruction to the email engine
153

BMC Remedy Action Request System 7.0

Including attachments with incoming email

Submit instructions can also include attachments.

To include attachments
1 Create a new email message in your mail tool.
2 Address the email message to the incoming mailbox.
3 To include an attachment in an email, use the attachment field name or field
ID:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <mypassword>
Action: Submit
!Submitter!: Francie Frontline
!Short Description!: I am including the filter.log file.
Attachment field !536880912!: filter.log

Your label/value pair syntax should not see the attachment pool, but to
specific attachment fields.
4 Insert your attachment file anywhere in the email.
If the attachment name including the extension is not supplied, the email
submission will not pass the attachment to the attachment field.
Do not include two attachment files with the same name, as in the following
example:
Attachment field 1 !536880912!: filter.log
Attachment field 2 !536880913!: filter.log

The email engine will accept the email submit instruction; however, the email
engine is unable to recognize which of the two filter.log files to insert into
the 536880912 attachment field.

Sending a modify instruction to the email engine

Sending a modify instruction to the email engine is more complicated than
sending query or submit instructions. To allow users to modify an entry, you
must configure the BMC Remedy Email Engine to accept modification
requests.
Do not delete outgoing email notifications with modify instructions.

154 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Overview—How modify instructions work with incoming email

Figure 5-6 presents a sample scenario that demonstrates how to send modify
instructions in an email message.

Figure 5-6: Using incoming email to modify requests

AR System admin

1 configured email engine

to allow modify entries.

Underlying

Key: 1234 Database

Action: Modify

HD Incident

6.3 Email Engine

Outgoing

Field 1
Jklm Nop Qrst
Field 2

Abcd ef ghijkl mno

Field 3

Email Messenger
Form
AR
5 Server modifies
ticket.

System
Server

Email engine
4
parses modify Email

instructions. Engine

Incoming Mailbox

Mail
Server

Email
account

Key: 1234
Action: Modify
Request ID: 55
Worklog: Service Patch 6

Key: 1234
Action: Modify
Request ID: 55

Francie Frontline
3 Joe User replies
to email.
2 sends email with
modify instructions.

Sending a modify instruction to the email engine
155

BMC Remedy Action Request System 7.0

Step 1 The AR System administrator at XYZ has enabled the BMC Remedy Email
Engine to modify entries in the AR System server. He has associated the
incoming and outgoing mailboxes. He has enabled the incoming mailbox to
accept modify instructions. Finally, he has created and sent security keys to
trusted users of the AR System, for example, the IT department. For more
information, see “Configuring the email engine for modify actions” on
page 73.

Note: The incoming and outgoing mailboxes in the email engine can be one
physical mailbox, performing both the incoming and outgoing functions.

Step 2 Joe User has a serious problem with his PC. He needs an IT engineer to install
the latest service patch and has submitted an entry on the HD Incident form
(Request ID 000000000000055). Francie Frontline, who has AR System
Administrator privileges, is working on Joe’s ticket. She needs Joe to verify
his current PC configuration and modify his ticket with updated
information. She sends an email to Joe that includes the following mandatory
parameters:

Key

Action: Modify

Form name

Server name

Request ID
Her email to Joe must contain at least these items for modify instructions to
work properly. She also includes names of fields that Joe can modify. After
she sends her email, a copy of the email is stored in the Messages form and
the email is sent to Joe.

Step 3 Joe User replies to the email. He updates the worklog label/value pair in the
email, for example, Worklog !536870922!: I’m running Service Patch 6.
Because he has used email to submit and query AR System entries, he knows
how to include additional fields to update information about the new
department he was transferred to, for example, !Department!: Product
Marketing.

156 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Step 4 The email engine receives the reply from the mail server and verifies that
Francie’s original email exists in the email engine (in the AR System Email
Messages form) and that the sender’s email address is contained in the
recipient field of the original email. It then parses the modify instruction in
Joe’s email, and modifies the ticket in the HD Incident form.

Step 5 The email engine returns the results to the sender, Joe User. If the email had
failed for some reason (for example, Joe modified the encryption value or he
tried to use a different Request ID), the email engine returns an error message
that indicates faulty parameters or other problems.

For more information, see the following detailed procedures.

Sending modify instructions in plain text

Executing a modify instruction is a two-step operation:

Step 1 The AR System administrator sends an outgoing message from the

AR System Email Messages form to the user who wants to modify an entry.
The message can be sent in plain text or HTML format. (To use HTML, see
page 161.)

Step 2 The user replies to the message with new values of the entry the user wants to
modify (see page 160).

Sending modify instructions

To send modify instructions to a user

1 Log in to BMC Remedy User as an AR System Administrator user.
2 Open the AR System Email Messages form in New mode, and enter the
following information:
a In the Mailbox Name field, select an outgoing mailbox.
b In the To field, enter the name of the user you are sending the email to.
c In the Reply To field, enter the email address of the incoming mailbox that
has been configured to accept modify instructions.
d Enter other information as needed, for example, an organization.

Sending a modify instruction to the email engine
157

BMC Remedy Action Request System 7.0

3 Click the Plain Text Body tab to create an outgoing message (plain text) with
the following information:

AR System Server Name.

AR System Login and Password to authenticate a user.

Label Key to specify the security key—the security key can be supplied by
the Administrator in the outgoing message or provided by the user in the
reply.

The Action Label, which describes the type of action or instruction to be
executed. In this example, the Action Label is set to Modify.

Form or Schema name on which to execute the instruction.

Request ID of the entry the user can modify.
You can optionally provide field IDs or database names of fields that have
values that can be modified. You must make sure the fields have permissions
that allow users to make modifications.
Following is the content of an outgoing message sent by the AR System
administrator through the outgoing mailbox of the email engine:
Server: polycarp
Login: Joe User
Password:
Key:
Action: Modify
Schema: HD Incident
Request ID: 000000000000003
!536870913!:

This message allows Joe User to modify Request ID 000000000000003 of the

HD Incident form. The Problem Summary field has been specified in the
outgoing message. Joe User can also modify additional fields in his email
reply by adding more field IDs.
Figure 5-7 shows an outgoing message you might send to a user, in this case
to Joe User.

158 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Figure 5-7: Sample outgoing message sent by administrator to user

You can substitute field IDs for database names. For example, if the Problem
Summary field is field ID 8, then you could replace the database name with
its field identifier !8! and produce the same results:
!8!:

Optionally, you can enter comments before the field ID, for example:
Enter problem summary!8!:

Note: Since there are no content template labels, you can use a result
template as its equivalent when performing a Modify action with
incoming mail.

When you send the email, the email engine appends an internal label called
##Modify##. The email engine generates an encrypted value for this label
using the Server Name, Schema Name, and Request ID (as shown in
Figure 5-8).
4 Click Send to send the mail from the outgoing mailbox to the user.

Sending a modify instruction to the email engine
159

BMC Remedy Action Request System 7.0

Replying to email containing modify instructions

To reply to an email containing modify instructions

1 Open your email client.
Joe User received an email that looks like Figure 5-8.

Figure 5-8: Modify instruction sent to user

2 Open a reply window for the email that contains the modify instructions.

Note: You must reply to the same mailbox as the one from which the email
was sent.

3 In the reply, modify parameters as needed.

For example, you could assign values for !8!, the Problem Summary field.

160 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

WARNING: The user who is replying cannot add additional submit, query or
modify instructions to the email. Do not change the Request ID, Schema
name, or Server label/value pairs when replying to the administrator’s
email.

4 Fill in any missing parameters as needed—Login, Password (if there is a

password), and Key. (For information about creating security keys, see
“Testing your mailbox configuration” on page 65.)
The following example shows the content of a sample reply from Joe User:
Server: polycarp
Login: Joe User
Password: yadayada
Key:1234
Action: Modify
Schema: HD Incident
Request ID: 000000000000003
!536870913!: Bob Backline
Comments!8!: Modified last name from Frank Frontline to Bob Backline
##Modify##:[$$ckI2UoIK4gNibZMvL7k7uI/eDhsoIU5JBTYvh5DMXaQnhPhicyCT/
g==$$]

In this example, Joe User also modified the contents of the Short Description
field (field ID 8).
5 Send the email reply.
When the incoming mailbox of the email engine receives the reply from the
user, it makes sure that the original email sent by the administrator exists
within the email engine and that the sender’s email address is contained in
the recipient field of the original outgoing email.
The email engine then parses the email. If you successfully modified the
entry, the email engine will return the results to the email client. Otherwise,
the email engine returns an error message that indicates any missing
parameters or other problems.

Sending modify instructions in HTML

In addition to the plain text format, you can also send modify messages from
the AR System Email Messages form in HTML format. Using HTML form
controls gives administrators greater control over the content that users can
modify. By sending modify instructions in HTML, you are forcing users to
respond to the modify instructions exclusively with the HTML controls you
have defined.

Sending a modify instruction to the email engine
161

BMC Remedy Action Request System 7.0

To send modify instructions using HTML

1 Using the AR System Email Messages form, create an outgoing message in
New mode.
See “Sending modify instructions in plain text” on page 157 for sample
contents of an outgoing message.
2 Click the HTML Body tab.
3 Enter contents like the following example:
Server: polycarp<BR>
Login: Joe User<BR>
Password <input type="password" name="Password" size="15"
maxlength="14"> <BR>
Key:1234<BR>
Action: Modify<BR>
Form:HD Incident<BR>
Request ID: 00005<BR>
Assigned To <input type="text" name="!4!" size="20" value="Assignee">
<BR>
Short Description <input type="text" name="!8!" size="40"
value="Enter a short description">
<BR>
Status
<input type="radio" value="New" name="!7!"/> New
<input type="radio" value="Assigned" name="!7!" /> Assigned
<input type="radio" value="WIP" name="!7!"/> WIP
<input type="radio" value="Resolved" name="!7!"/> Resolved
<input type="radio" value="Closed" name="!7!"/> Closed
<BR>

This example of an HTML-formatted outgoing message allows Joe User to

do the following task to entry 00005:

Enter a password in an input type Password control field. When users
enter their password, stars appear instead of the typed symbols or letters.

Modify the contents of the Assigned To and Short Description fields.

Modify the status in an input type Radio control field. Users can select
only one radio button option.
Unlike the plain text email where users can modify additional fields in their
email reply by adding more field IDs, HTML is much more restrictive. The
only fields that users can modify are the HTML controls you have defined in
the outgoing message. As a result, using the HTML format can help prevent
user errors.

162 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Another useful HTML format is including system information (for example,

server name or form name) in hidden fields. The data is still within the
message, but users do not see it. You make visible only those fields that users
need to see, and disguise the rest as hidden fields.
The following example is a Help Desk request message with Schema and
Action as hidden fields with default values supplied:
<h1>Help Desk Request</h1><hr>
<input type=hidden name="Schema" value="Help Desk"/>
<input type=hidden name="Action" value="Submit"/>
Name: <input type=text name="Login"/><br/>
Password: <input type=password name="Password"/><br/>
Problem Description: <input type=text name="Short Description"/>

Note: See any standard HTML reference book or reputable online source
(http://www.w3.org/) for how to define input type controls.

4 Send the outgoing email.

The user will receive an email that looks like Figure 5-9.

Figure 5-9: Modify instruction (HTML format) sent to user

Sending a modify instruction to the email engine
163

BMC Remedy Action Request System 7.0

5 To execute the modification, reply to the email received with the modified
values for the HTML fields that you can see and have permission to change.

Figure 5-10: Modify instruction (HTML format) sent to user

Using the HTML controls you have defined, click in a field to modify its
contents, for example, enter Assigning this ticket to Bob Backline in
the Short Description field. Also observe that Joe’s password is encrypted
(Figure 5-10).
With HTML, users can modify only the fields you provide. As a result,
creating outgoing HTML email requires some planning by administrators.
For example, if Joe User could not enter his password, the email engine
would reject the modify action due to permission problems. Email is no
different than any other AR System client. Like logging in to BMC Remedy
User, he could not use email to “log in” to the email engine without entering
a password.

164 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Additional restrictions
Remember the following restrictions when using email to modify entries:

The email engine does not support the Modify All operation. Only one
entry can be modified with one modify instruction. However, you can
include multiple modify instructions in one email message if you include
the full login information (server, login, and password) for each entry that
you want to modify, as in the following example:
Server: polycarp
Login: Francie Frontline
Password:
Key:1234
Action: Modify
Schema: HD Incident
Request ID: 000000000000003
!536870913!:

Server: polycarp
Login: Francie Frontline
Password:
Key:1234
Action: Modify
Schema: HD Incident
Request ID: 000000000000004
!536870913!:

You can combine the modify instruction with submit or query

instructions in a single message, provided multiple instructions (modify
with submit or query) have been sent from the administrator.

Users cannot add new instructions when replying to the message
containing modify instructions.

Sending a modify instruction to the email engine
165

BMC Remedy Action Request System 7.0

Overview—Using workflow to modify requests

Figure 5-11 presents a sample scenario that demonstrates how to use
workflow to modify requests.

Figure 5-11: Using workflow to modify requests

AR AR System verifies security mechanisms

System 4 and modifies the request.

Server

1
AR System admin
configured incoming
mailbox to accept
modify actions.
Created security key. 2 AR System receives submit request.
Filter workflow triggers Notify action.
Email sent includes Modify template.

Email
Engine

Incoming Mailbox Outgoing Mailbox

Mail
Server

User receives email.

3 Reply email includes
modify information:
¥ Login and password
¥ Security key
¥ Modify action keyword

166 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Step 1 The AR System administrator at XYZ has enabled the BMC Remedy Email
Engine to modify entries in the AR System server. He has associated the
incoming and outgoing mailboxes, enabled the incoming mailbox to accept
modify instructions, and created and sent security keys to trusted users of the
AR System. For more information, see “Configuring the email engine for
modify actions” on page 73.

Note: The incoming and outgoing mailboxes in the email engine can be one
physical mailbox, performing both the incoming and outgoing functions.

Step 2 The AR System receives a submit request. A filter uses email to send a
notification that a request has been received. This email was formatted using
a modify template.

Step 3 The user receives the message in her email client and then replies to it. She
modifies the request by entering the following information:

Login and password

Security key

Modifications to values of fields
She presses the Send button to reply back to the AR System server.

Step 4 The AR System server verifies the security key, the user’s email address, and
the Request ID. These security mechanisms make sure that only the entry sent
for modification is being modified and that it is being modified by the user
who the original email was sent to.

Creating workflow to modify requests

The following example walks you through the procedure for creating
workflow to modify requests. The example is simple but complete, and you
can easily add more functionality. For example, you could create a Run If
qualification in your filter to search for records marked Urgent and that are
assigned to your Managers group.
In this example, make sure that the Demo user is still active and has an email
address that works with the email engine. Make sure your incoming and
outgoing mailboxes work correctly. Finally, set the polling intervals on your
incoming and outgoing mailboxes to one minute so that you can quickly
verify your results.

Overview—Using workflow to modify requests
167

BMC Remedy Action Request System 7.0

Creating a security key

Use the following values to create an AR System Email Security record. You
must provide a security key for every user who sends modify instructions to
the email engine, in this example, Demo.

To create a security key

1 In BMC Remedy User, open the AR System Email Security form in New
mode.
2 Set the Status field to Enabled.
3 In the Key field, define your security key, for example, patience.
4 Enter Demo as the User Name.
5 Set the Force For Mailbox field to No.
6 Set the Force From Email Addresses to No.
7 Set the Expires field to No.
8 Leave the rest of the fields blank and save the record.
Creating a sample form for your modify example
You are creating a sample form used exclusively for the purposes of this
exercise. Later you will create and modify a record in this form to verify the
workflow process.

To create a sample form

1 Create a new form and name it appropriately, for example, Modify Email
Workflow.

2 Do not add any new fields.

3 Save the form.
Creating filter workflow that triggers a Notify action
Use the following information to create a filter that executes on the Submit
condition of the Modify Email Workflow form and triggers a Notify action.

168 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

To create filter workflow

1 Create a filter.
2 Enter a filter name, for example, Modify Email Filter.
3 Select Modify Email Workflow as the Form Name.
4 Select Submit as the Execute On condition.
5 Leave the Run If condition blank.
After you verify that you can use your filter workflow to modify requests, you
can add a Run If qualification later.
6 Click the If Action tab.
7 From the New Action list, select Notify.
8 In the User Name field, enter Demo.
9 From the Mechanism list, select Email.
10 In the Subject field, enter Modify Email Workflow.
11 In the Text field, enter the following information as the text of the message:
Login:
Password:
Key:

Action: Modify
Form: Modify Email Workflow

Request ID: $Request ID$

Submitter!2!: $Submitter$
Short Description:!8!: $Short Description$

The Modify action in the text of the outgoing message is the special
instruction that allows the email engine to modify an entry on the AR System
server. The Modify action is valid only in Reply with Result emails. For more
information, see “Modify action” on page 195.
12 Save your filter.
Exporting an email template
Export an email template from the Modify Email Workflow form. For more
information, see “Exporting mail templates” on page 188.

Overview—Using workflow to modify requests
169

BMC Remedy Action Request System 7.0

To export email templates

1 In BMC Remedy Administrator, choose Tools > Export Mail Templates.
2 From the Forms to Export list, select the Modify Email Workflow form.
3 Click Export.
4 Save the email template in .arm format to your desktop.
5 Open the email template in a text editor.
Creating a submit email
Here you open a new email message and paste the contents of the exported
mail template into the new email. You use this email to submit a record to
the Modify Email Workflow form.

To create a test email

1 Create a new email in your email client.
2 Address the email to the BMC Remedy email inbox account.
3 Create a subject line, for example, Modify Email Workflow.
4 Copy and paste the contents of the exported email template into the new
email, and then fill out the required information for the template, for
example:
#
# File exported Tue Sep 21 15:34:56 2004
#
Schema: Modify Email Workflow
Server: POLYCARP.eng.remedy.com
Login: Demo
Password:
Action: Submit
# Values: Submit, Query
Format: Short
# Values: Short, Full

Submitter !2!: Demo

Short Description !8!: Email Test

5 Send the email to the incoming mailbox.

170 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Replying to email notifications

The email client sends your submit email to the incoming mailbox on the
mail server. The email engine, after receiving the email from the mail server,
parses the instructions in your email, and makes the submit API calls to the
AR System server. The server then creates a record in the Modify Email
Workflow form. The incoming mailbox is configured to reply with results
and generates an email response. In addition, when a record is submitted,
filter workflow triggers a Notify action that includes instructions for
modifying the record.
The following procedure describes how you reply to email notifications
generated by workflow.

To reply to email notifications

1 Open the AR System Email Messages form in Search mode.
2 Confirm that the incoming mailbox has received your message, and then sent
the Reply with Result email (as shown in Figure 5-12).

Figure 5-12: Incoming and outgoing messages in Email Messages form

Overview—Using workflow to modify requests
171

BMC Remedy Action Request System 7.0

3 In BMC Remedy User, open the Modify Email Workflow form in Search
mode.
4 Make sure a new record was created in the Modify Email Workflow form.
5 Check for new mail in your mail client.
If you properly configured the email engine and all your permissions are
working correctly, you should receive an email notification (as shown in
Figure 5-13) from the filter that you created previously.

Figure 5-13: Notification email (sent from filter) with modify key

Figure 5-13 shows the modify key added to the notification:

##Modify##:[$$ckI2UoIK4gNQ0qROehOucPFOokiXb/DfA07EiNObusaHtOquCV/
FSA==$$]

Important: You cannot modify a record through email without this

##Modify## key. Do not edit this key in any way!

6 Reply to the returned email.

172 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

7 Enter the following information into the body of the email:

Login: Demo
Password:
Key: patience

Action: Modify
Form: Modify Email Workflow

Request ID: 000000000000002

Submitter!2!: Demo
Short Description:!8!: Modifying requests with workflow is great!
##Modify##:[$$ckI2UoIK4gOt6aqHF2QE9x5d1nqwf6FJLifugKurp68lQH9XRehnEw=
=$$]

Make sure you add the Login and security key. Update the Short Description
so that you can verify that modifications work on records in the Modify
Email Workflow form.

8 Send the reply email.

9 In the AR System Email Messages form, confirm that the incoming mailbox
has received the email with the modify instruction (as shown in Figure 5-14).

Figure 5-14: Modify message returned to incoming mailbox

Overview—Using workflow to modify requests
173

BMC Remedy Action Request System 7.0

10 In BMC Remedy User, refresh the query results of the Modify Email
Workflow form.

The modify action should have modified the Short Description in the record.

Searching for an entry to modify—Advanced solution

This advanced solution builds on all the information you have learned up to
now, for example, sending query and modify instructions to the email
engine, the use of templates, and so on. The procedure assumes you have
created a form named TestSecurityForm containing at least the core fields.

To search for an entry to modify

1 Make sure you have an incoming mailbox and an outgoing mailbox
configured and associated with one another.
2 Set Enable Modify Actions to Yes in the AR System Email Mailbox
Configuration form for the incoming mailbox.
3 Make sure you have a valid security key.
4 Create a template (TestModify) that includes a modify action.
You will use this template for the reply email; see the Result Template label
in step 6.
Server: polycarp
Login:
Password:
Key:

Action: Modify
Form: TestSecurityForm
Request ID: [$$#$$Request ID$$#$$]
!2!:
!8!:

Because this template replaces the hard-coded label/value pair (Request ID:
000000000000026) with a variable value
(Request ID:[$$#$$Request ID$$#$$]), you can construct an email that gives
you the flexibility to search for a specific parameter.
5 Add the TestModify template to the AR System Email Templates form.

174 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

6 Use your mail client to create an incoming mail. Include a Query action in
the body of your email.
For example:
Server: polycarp
Login: Demo
Password:
Action: Query
Form: TestSecurityForm
Qualification: 'Request ID' = "000000000000026"
Result Template: TestModify

This email provides all the information required for the email engine to
perform the query action, and then to perform the modify action in the
TestModify template.

Tip: If the Qualification was part of the TestModify template, you could have
omitted the Qualification line from the email.

7 Send your email to the incoming mailbox.

The email engine generates a reply (Figure 5-15) to the Query action, using
the template you created in step 4 and specified as the Result Template. You
can see that the Request ID value found from the query was substituted in the
reply, using the variable in the template.

Searching for an entry to modify—Advanced solution
175

BMC Remedy Action Request System 7.0

Figure 5-15: Reply email generated from email engine

Request ID variable
substituted in reply,
based on template

Key included in reply

email generated by
email engine

The email engine also creates a Modify Key based on the information in the
Action, Form, and Request ID and adds it to the email.
8 Open the reply email and modify the parameters as required.
For example, add values in !2! (a different name) and !8! (modifying the short
description). Do not change the Action, Form, and Request ID label/value
pairs.
9 Fill in any essential missing parameters—Login, Password (if there is a
password), and Key.
10 Send the email reply with the modifications included.

Note: You must reply to the same mailbox as the one from which the email
was sent.

The email engine parses the email and the server modifies the entry. The
email engine then sends you a confirmation message, as shown in Figure 5-
16.

176 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Figure 5-16: Confirmation email that modify action was successful

You can perform a search on the form to verify the result.

Using variables with templates

With incoming email, you can also use variables in templates. Variables are
useful when you need to be able to send different values for the fields to
submit an entry. Variables allow you to substitute different values for
appropriate fields.
Use the following syntax for variables:
#$$Variable Name$$#

If you expect the value of a variable to span multiple lines, then enclose the
variable with brackets:
[$$
…
$$]

Using variables with templates
177

BMC Remedy Action Request System 7.0

The following example of a template file (.arm file) submits a new employee
name into the Employee Information form:
Schema: Employee Information
Server: server1
Action: Submit
Short Description !8!: $DATABASE$
Submitter !2!:$USER$
Employee Name !VEmployee Name!: [$$#$$VEmployee_Name$$#$$]

The characters between exclamation marks exactly match the field ID or

database name of the field on the form. The variable is called
VEmployee_Name. Since the variable might span multiple lines, it is enclosed
between brackets [$$…$$].
When you send a submit instruction, you also can provide a value for
variable $$VEmployee_Name$$, as shown in the following example:
Schema: Employee Information
Server: server1
Action: Submit
Short Description !8!: $DATABASE$
Submitter !2!:$USER$
!VEmployee_Name!: [$$Joe Smith$$]

Displaying advanced options for incoming email

For incoming email, the most important use of the Advanced Options tab is
to view message information and errors of incoming email. This information
is used mostly for troubleshooting.
The Attachment Alternatives tab (Figure 5-17) displays any attachments in
the incoming email. It displays the links to the message as it is rendered by
the email engine in plain text, HTML, and email client formats.

178 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Figure 5-17: Attachment alternatives information for incoming email

Formats of incoming
email message
displayed

For more information, see Chapter 7, “Troubleshooting.”

To display advanced options

1 Open the AR System Email Messages form in Search mode.
2 Select an incoming email message.
3 Select Yes in the Display Advanced Options field of the AR System Email
Message form.
4 Select one of the advanced option tabs: Advanced Options, Message
Information, or Errors.

Note: For incoming email, you typically will not see information under the
Templates and Variable Replacement tabs.

Displaying advanced options for incoming email
179

BMC Remedy Action Request System 7.0

Message Information tab

The Message Information tab records status information about incoming
email, such as its Message ID, the date the email was received, and how the
message was parsed, as shown in Figure 5-18.

Figure 5-18: Message information for incoming email

180 Chapter 5—Incoming email

 Administering BMC Remedy Email Engine

Errors tab
The Errors tab enables users to view error messages if incoming email is not
received correctly. If a request fails to submit or query, the original message
is returned, along with an error message that indicates the reason for the
failure. Figure 5-19 illustrates an incoming query that did not return any
results. Information includes the severity of the error, error number, date
created, and error message text.

Figure 5-19: Error information for incoming email

Displaying advanced options for incoming email
181

BMC Remedy Action Request System 7.0

182 Chapter 5—Incoming email

Chapter

6 Using email templates

This chapter provides information and instructions for creating and using
templates for outgoing and incoming email. The following topics are
provided:

Overview—Email templates (page 184)

Creating templates (page 188)

Using label/value pairs in templates (page 191)

Storing templates in the AR System Email Templates form (page 209)

Adding attachments to HTML templates (page 211)

Preparing email templates after an upgrade (page 215)

Overview—Sending incoming email with user instructions (page 216)

Using email templates
183

BMC Remedy Action Request System 7.0

Overview—Email templates
This chapter describes the various types of templates, their use in incoming
and outgoing mailboxes, as well as label/value pairs. Labels are keywords
unique in the email engine and values are their data. Label/value pairs can be
included in templates and used to instruct the email engine to interact with
your AR System server.

Tip: The term “template” can be slightly misleading, because email templates
are more than simply the pattern of label/value pairs you export using
BMC Remedy Administrator. In addition to exported label/value pairs, a
variety of email templates function as the actual headers, footers, and
content of your email messages.

Email templates serve two main functions for incoming and outgoing
messages:

For incoming messages (email that users send to an incoming mailbox),
users can include templates in their emails that contain specially
formatted instructions. These instructions use combinations of field labels
and their values, usually referred to as label/value pairs. The email engine
parses (that is, translates) these instructions into commands to the
AR System server to perform a query, submit or modify an entry, or
complete any other such action.

For outgoing messages (sent by the email engine using an outgoing
mailbox), templates can provide formatting of content in messages that
include the results of queries or various other requests.
Templates used for incoming and outgoing messages can be formatted using
plain text, HTML, or XML. Templates are defined and stored in forms on the
AR System server and can be retrieved for use by the email engine when
called upon by incoming or outgoing mail.

184 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

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

Incoming and outgoing mail templates

You can create separate templates to specify different formats for incoming
and outgoing mail.

Content templates. Used for outgoing messages. These templates can be
associated with a specific form and contain the fields and their
corresponding values relating to a specific record. They can also contain
plain text or reserved variables.
You can create these templates in a text editor (shown in the following
figure), or export them using BMC Remedy Administrator, selecting the
form and fields that are to be contained in the template.
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 the AR System Email Messages form or using
workflow with filters and escalations.

Figure 6-1: Content template—plain text

When using a content template with workflow, make sure that you include
the fields specified in the content template in the Fields tab of the Notify
action. Content templates can also be formatted in HTML, similar to the
result template shown in Figure 6-3 on page 186.

Overview—Email templates
185

BMC Remedy Action Request System 7.0

Header and footer templates. Used to place lines of text or a graphic at the
beginning or end of a message. (A header template is shown in Figure 6-
2.) 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 6-2: Header and footer template—HTML

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

instruction with the results of an action. A label/value pair must be
specified in the email containing the action. Result templates can be either
HTML or plain text. Figure 6-3 shows an example of an HTML-formatted
version of a result template.

Figure 6-3: Result template—HTML

Status templates. Used when the execution of an incoming instruction

results in an error (as shown in Figure 6-4). A label/value pair must be
specified to include specific status information in the email or content
template. Status templates can be either HTML or plain text. (For more
information, see “Reserved variables” on page 207.)

186 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Figure 6-4: Status template—HTML

User-defined instruction templates

A special use of templates are user-defined instruction templates that enable
administrators to associate a 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 BMC Remedy Email
Engine executes the relevant template.
Using this feature, the administrator can set up variable substitutions to be
used in an email with minimal input from the user. The associated template
supplies the rest of the information. For example, the template shown in
Figure 6-5 logs the user Demo in to the server reepicheep, queries the HD
Incident form for all tickets with an urgent status, and returns the full
information about all fields that this user has access to. But all that the user
needs to do is send an incoming email with the Action label/value pair that
identifies the user instruction, for example, Action: Urgent.

Overview—Email templates
187

BMC Remedy Action Request System 7.0

Figure 6-5: User-Defined instruction template

User-defined templates look the same as other templates and are stored in the
AR System Email Templates form. For more information, see “Action label”
on page 194 and “Overview—Sending incoming email with user
instructions” on page 216.

Creating templates
In BMC Remedy Administrator, you can generate the email templates
associated with a particular form by choosing 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 guide if they are to include fields, variables, and label/value pairs.

Exporting mail templates

The mail template displays all of the fields that are visible in the selected view
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.

188 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Hidden fields are omitted from templates even though they might have
public permissions and are 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 BMC Remedy Email
Engine has access to this field, then the field is accessible.

To export mail templates

1 In BMC Remedy Administrator, select a server to administer.
2 Choose Tools > Export Mail Templates.
The Export Mail Templates dialog box appears.

Figure 6-6: Export Mail Templates dialog box

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; that is, perform this procedure for each form.
4 Click Export to open the Export File dialog box.

Creating templates
189

BMC Remedy Action Request System 7.0

5 If you are creating a new file, specify where you want the templates stored,
and then enter a file name.
Otherwise, 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.
6 Save your changes.
The template is saved as a single text file with an *.arm extension. Using the
AR System Email Templates form, users can associate these files with their
mail messages.
The following example shows an email template exported using BMC
Remedy Administrator.
#
# File exported Fri Apr 30 09:54:36 2004
#
Schema: HD Email
Server: POLYCARP.eng.remedy.com
Login:
Password:
Action: Submit
# Values: Submit, Query
Format: Short
# Values: Short, Full

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.

190 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Using label/value pairs in templates

For the most part, email templates consist of a label/value pair surrounded
by text or graphics, depending on the format of the template. The label is a
keyword such as Action. The value consists of data or commands (for
example, Submit). A value can be specified in the templates or obtained from
the configuration information. The email engine is not case sensitive when
parsing the labels. The following table lists valid labels; each label is discussed
in more detail following the table.

Label Description Incoming Outgoing Aliases Page

Form Name of an AR System form. Yes No Schema page 192
Server Server that will be affected by the Yes No page 192
instruction.
Login User name used when executing Yes No User page 193
the instruction. User Name
Name
Login
Password Password used when executing Yes No page 193
the instruction.
TCP Port TCP port used when logging in Yes No TCP page 193
to the AR System server.
RPC Number RPC number used when logging Yes No RPC page 193
in to the AR System server.
Authentication Authentication string used when Yes No page 193
logging in to the AR System
server.
Language Language used when logging in Yes No page 194
to the AR System server.
Action Denotes the instruction to be Yes No Instruction page 194
executed.
Format Specifies the format of the Yes Yes page 196
information.
Qualification Qualification for a query-based Yes No Query page 197
instruction. Search

Using label/value pairs in templates
191

BMC Remedy Action Request System 7.0

Label Description Incoming Outgoing Aliases Page

Result The name of the template to use Yes No Result page 197
Template in the reply. ResultTemplate
Status The name of the template to use Yes No Status page 198
Template when Status Information is StatusTemplate
returned.
Header The template to be used as the No Yes Header page 198
Template header in the reply email. HeaderTemplate
Footer The template to be used as the No Yes Footer page 198
Template footer in the reply email. FooterTemplate
!Name/ID! The database name or ID of an Yes Yes page 199
AR System Form Field.
Key The key associated with a given Yes No Encryption Key page 199
sender or user. Encryption
Request ID The Request ID of the entry on Yes No Entry ID page 200
which the possible action must EntryID
be executed.
RequestID

Form label
The Form label identifies the form that the instruction will use. 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 Form label/value pair is Form:<form_name>.

Server label
The Server label 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 Server label/value pair is Server:<server_name>. (For more
information, see “Using the EmailDaemon.properties file” on page 233.)

192 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Login, Password, and TCP Port labels

The Login and Password labels identify the user name and password used
when executing the instruction. You can configure exactly how the user
name is to be determined for an incoming email:

Set a security key in the AR System Email Security form. You must add
Key:<security_key>
to the email. If Key:<security_key> matches an entry in
the AR System Email Security form, then the corresponding user name is
used.

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

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

The TCP Port label identifies the TCP/IP port of the AR System server, if your
AR System server is not using Portmapper. The alias for TCP Port is TCP.

RPC Number and Authentication labels

These labels define 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.

Using label/value pairs in templates
193

BMC Remedy Action Request System 7.0

Language label
The Language label 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 BMC Remedy Administrator and AR System
clients. The format of the Language label/value pair is Language:<language>,
for example, Language:en_US.

Action label
The Action label defines the operation to perform on a specific AR System
form. The Action label/value pair 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 6-1, and explained in more detail after
the table.
Table 6-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 the Submit action in an email, users can enter values for field labels,
and submit a new record. You can see an example of a template with a Submit
action in “Sending a submit instruction to the email engine” on page 150.

194 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Query action
The Query action lets you search for existing entries. To increase server
performance, 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 guide for
information about configuring limits.
For sample templates with Search (Query) actions, see “Sending a query
instruction to the email engine” on page 144.

Modify action
The Modify action enables you to modify existing entries, but due to the
nature of this command and the security implications, the command can be
executed only under the following conditions:

The message containing the modify action must be sent from an
AR System administrator to the user.

The user can only change field values and cannot add new actions, or
modify existing actions when replying to the email that contains the
modify action. The user must not modify the modify key included in the
email.

The sender or the user of the email must supply a valid Security Key.

Note: Do not modify the Password field (field ID 102).

The incoming mailbox must be configured to allow modifications. For

more information, see “Configuring the email engine for modify actions”
on page 73.

In the outgoing mailbox, make sure the Delete Outgoing Notification
Messages field is set to No. You cannot modify a record by email if you
delete outgoing email messages.
The BMC Remedy Email Engine will insert a special label and value into the
email if the email contains a Modify action. This special label/value pair is
defined as follows:
##Modify##:[$$the encrypted information$$]

Using label/value pairs in templates
195

BMC Remedy Action Request System 7.0

The encrypted value contains information, which the BMC 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.

Form name.
For more information, see “Overview—Using workflow to modify requests”
on page 166 and “Sending a modify instruction to the email engine” on
page 154.

User-defined instruction
This action is a text string that has been determined by the AR System
administrator and is 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. For more
information, see “Overview—Sending incoming email with user
instructions” on page 216.

Format label
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 Format 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 Full. All matching requests are listed in the
body of the response, one after another.

196 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Qualification label
The Qualification 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 BMC Remedy User
apply when performed through email. The following is a sample qualification
string:
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.

Result Template label

If the email engine is configured to send an email reply, you can specify a
result template that formats the reply for you. You include the Result
Template label, and specify the template name as the value. The Result
Template label defines the template to use when replying to an incoming
email containing query instructions.
The Result template is usually associated with a particular form. This
template consists of label/value pairs and variables (see page 203 for more
information) that correspond to fields on the AR System form being queried.
These variables are replaced by the data found on the form based on the
instruction being executed. For example, you can include variables in your
template that let users click a direct access URL to open a specific Request ID:
<TD width="17%"><a href="http://polycarp/arsys/servlet/
ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request
ID$$#">#$$Request ID$$#</a> </TD>

Figure A-3 on page 271 illustrates how this variables is used in a result
template. The value given for this Result Template label is the name or
Request ID of the template contained in the AR System Email Template
form. When the BMC 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 result template label/value pair
is Result:<result_template_name>.
For more instructions, see “Using HTML result templates with outgoing
email” on page 131 and “Creating an email reply using result templates in
HTML format” on page 270.

Using label/value pairs in templates
197

BMC Remedy Action Request System 7.0

Status Template label

The Status Template label is 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. (For more information,
see “Reserved variables” on page 207.)
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 status template contained on the AR System Email
Template form. When the BMC 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 status template label/
value pair is StatusTemplate:<status_template_name>.

Header Template and Footer Template labels

These labels define the templates 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, graphics, and 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 BMC 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.
Aliases for the Header Template are Header and HeaderTemplate; aliases for
the Footer Template are Footer and FooterTemplate. An example of a header
template label/value pair is HeaderTemplate:<header_template_name>.

198 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

!Name! or !ID! labels

These labels indicate 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.
Labels for fields need not be present in any specific order within an email
message. You can precede the field name/ID label with any text that you want
to include. This text will not be parsed by the email engine. It is common
practice to include the actual field name in this way:
Submitter !2!: $USER$

In the previous 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 might 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 label
If your incoming mailbox is configured to require a security key, then the Key
label/value pair must be present in the incoming email message. A key is
required to use the Modify action. The passwords and security keys will be
encrypted in the AR System Email Messages form. Aliases for the Key label
are Encryption Key and Encryption. An example of a Key label/value pair is
Key:<test_key>.

Using label/value pairs in templates
199

BMC Remedy Action Request System 7.0

For more information, see “Configuring incoming mailbox security” on

page 69.

Request ID label
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 want to modify. Aliases for the
Request ID are Entry ID, EntryID, and RequestID. An example of a request
ID label/value pair is RequestID:0000012345.

Label/value pair formats

Your email must use specific syntax for label/value pairs so that the parser
can extract the required information. Each of the following formats can be
used in plain text, HTML, or XML documents.

Basic format
The basic format is the simplest. You can associate a label with a constant
value or a variable value. The labels and associated constant 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

Tip: You should use the [$$ ... $$] variable syntax when the BMC Remedy
Email Engine needs to parse multi-line values. Strictly speaking, you do
not need to use this multi-line syntax for all label/value pairs, but it is a
good practice to adopt if you think the values in a variable might exceed a
single line.

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.

200 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

You can associate a label with a variable also. A variable is written as follows:
#$$variable_name$$#

When used in a label/value format:

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

XML format
The XML 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. To view

a template using XML, see “Using XML result templates with outgoing
email” on page 135.

HTML format
The four major HTML field types are:

Text fields

Radio buttons

Checkbox buttons

Menu field
These types have a fixed format in 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. To create a template using
HTML field types, see “Sending outgoing email in HTML” on page 111.
The name tag represents the label, and the value tag represents the value.

Using label/value pairs in templates
201

BMC Remedy Action Request System 7.0

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.
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/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 would be determined by the word “checked.” The resulting label/value
pair would be Action:Submit.
Checkbox buttons
Checkbox 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.

202 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

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

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.”
The menu field also allows the user to specify different visible text in the field
with the correct field values defined underneath.

Global and local parameter declarations

Any parameter defined in the email before an Action label is regarded as
global and applies to all the actions within the email. As a result, 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 more information, see “Creating an email content template with Submit
and Query actions” on page 268.

Variables
The use of variables allows the administrator to create generic templates.
Variables are used only with templates that are to be used as user-defined
instruction templates for incoming email, result templates for incoming
email, or as content templates for new outgoing email. 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 values of the fields in the entry that triggers the
notification.
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 is defined as follows:
#$$variable_name$$#

Using label/value pairs in templates
203

BMC Remedy Action Request System 7.0

When used in a label/value format, use the following syntax:

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

For more information about label/value formats, see page 200.

The name of the variable can be the same as an AR System field, 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.
However, 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 205 for specific examples.
For outgoing emails, the variable value is determined in the following order:

Step 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
“Using the Attachment Alternatives tab” on page 124 for more information
about how to do this.

Step 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. For more information, see
“Using the Variable Replacement tab” on page 119.

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

204 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Variable examples
The following is an 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 user-defined instruction template

received by way of the email, this variable could be associated with a value as
follows:
!modified_date!:[$$21/01/2004$$]

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 database 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$$#

Using label/value pairs in templates
205

BMC Remedy Action Request System 7.0

To use this template in notifications, the user will have to change it so that it
looks like the following example:
Login Name : #$$Login Name$$#
Password : #$$Password$$#
Group List : #$$Group List$$#
Full Name : #$$Full Name$$#
Default Notify Mechanism : #$$Default Notify Mechanism$$#
Email Address :#$$Email Address$$#

Add the following core fields to the template:

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 month, day,
and year is displayed (for example, 06/18/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,
month, day, and year is displayed (for example, Friday, June
18, 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.

206 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

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.
As a result, depending on your locale, 31/01/04 will work as a short date if
your locale is set to dd/mm/yy, not mm/dd/yy. The format 31-Jan-04 will not work,
but you can use Jan 31, 2004 or January 31, 2004.

Reserved variables
The BMC Remedy Email Engine uses reserved variables to place the results
of executing an email. You can use reserved variables in Result and Status
templates, but not in Content templates. Reserved variables fall under two
main categories:

Action information—Useful when creating a template that will contain
the results of executing the associated action. They can be defined in a
Result template along with variables that define the fields of a specific
form. The email engine will replace these variables with the correct values
before the results are returned to the sender of the email containing the
actions.
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 can 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.

Using label/value pairs in templates
207

BMC Remedy Action Request System 7.0

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$$#Thetypeoferror,suchasSevere,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. Figure 6-7 displays an email that includes these
reserved variables for status information. This particular email uses the
HTML status template found on page 187.

Figure 6-7: Reserved variables for status information used in outgoing email

#$$ActionStatus.Number$#
#$$ActionStatus.Text$#

#$$ActionStatus.Type$# #$$ActionStatus.Appended
Text$#

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
Status-History.New.TIME

You can also use numeric values, for example:

15.0.USER
Status-History.0.USER
15.New.USER

The USER and TIME identifiers are case sensitive.

208 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Additional tips when creating or modifying templates

You might find the following tips helpful when using email templates:

Diary fields and character fields with a maximum length of over 50
characters can use multiple lines of text.

Values can be entered anywhere after the delimiting character. Leading
and trailing blanks are ignored when the email engine reads a value.

Comments are optional. Because the BMC Remedy Email Engine ignores
any lines that do not contain a valid label/value pair, you do not have to
add a # symbol in front of comments.

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.

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.

Storing templates in the AR System Email Templates form
209

BMC Remedy Action Request System 7.0

Figure 6-8: AR SystemEmail Templates form

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 new mode in BMC Remedy
User.
3 Click the Template Information tab.
4 Select the template format (Text or HTML) from the Template Format list.
5 Specify the Encoding so that the BMC Remedy Email Engine can parse the
templates. If you leave the Encoding field empty, the default encoding of the
local system is employed.
6 Right-click in the attachment pool, and choose Add from the menu that
appears.
The Add Attachment dialog box appears.
7 Browse to the template file you want to add and select it.
8 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 if you are using a
Windows system.

210 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

9 Select the item in the attachment pool, and click the edit button next to 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.

10 (Optional) Enter a description.
It is useful to enter a description indicative of the function of the template.
11 Click Save.
The system assigns a Template ID number to the template. (The Template ID
field is hidden.)
If an HTML template contains a reference to a graphic file, you need to add
the graphic file as an attachment. See the following section for information.

Adding attachments to HTML templates

Use the AR System Email Attachments form to make sure 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.

Note: The BMC Remedy Email Engine does not support linking your HTML
template to a cascading style sheet.

To add attachments to HTML templates

1 Open the AR System Email Templates form in new mode in BMC Remedy
User.
2 From the Template Format menu, choose HTML.
This activates the buttons on the Template Attachments tab to add
attachments to your template.
3 Add a template file as an attachment.
4 Click Save.

Adding attachments to HTML templates
211

BMC Remedy Action Request System 7.0

5 Click the Template Attachments tab.

Figure 6-9: AR System Email Templates form—Template Attachments tab

Add
Attachment
button

6 Click the Add Attachment button.

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

Figure 6-10: AR System Email Attachments form for templates

Select Template
as the
attachment
Type

Attachment pool

7 Select Template from the Type menu.

212 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

8 Right-click in the attachment pool, and choose Add from the menu that
appears.
The Add Attachment dialog box appears.
9 Browse to the file you want to add and select it.
10 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.
11 Select the item in the attachment pool, and click the edit button next to the
Attachment Name field.
The name of the template attachment is displayed. For example:
template_attachment1.htm

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

12 Click Save.
The AR System Email Attachments form closes.
13 Your attachment will be added to the list in the AR System Email Templates
form. You might need to right-click and select Refresh to see the attachment
listed.
14 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

To add a previously saved attachment to your template

1 In the Template Attachments tab of the AR System Email Templates 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 is added to the list in the attachment pool.
4 Click Save.

Adding attachments to HTML templates
213

BMC Remedy Action Request System 7.0

Modifying an attachment

To modify 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 6-10 on
page 212).
4 Click Search to locate the attachment.
The attachment appears on the attachment list.
5 Modify the attachment as required. You also can modify the Attachment
Name.
6 Click Save.

Deleting an attachment

To delete 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.
4 Click the Refresh Table button to refresh the table in the Attachments tab.
The attachment is deleted from the list.

214 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Exporting templates with attachments to another server

You can export an HTML template from one server and then import the
template onto another server.

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 AAR System Email
Templates form on the target server.

Preparing email templates after an upgrade

If you have upgraded from BMC Remedy Mail Server (pre-5.1), you might
have to modify your existing templates to use the new 7.0 features, for
example, the ability to use HTML in your templates. There is, however, a
configuration setting that allows you to continue to use your pre-5.1 email
templates as-is with the 7.0 email engine. For more information, see the “Use
Original Template Format” feature described in “Advanced incoming
mailbox configuration” on page 61.
To use your old email templates after an upgrade to the 7.0 email engine, use
the following procedure.

To prepare email templates after an upgrade

1 Verify the following settings in the AR System Email Mailbox Configuration
form:

Incoming mailbox is Enabled.

Email Action for your incoming mailbox is set to Parse.

Use Original Template Format is set to Yes, if you want to use your
original templates for your incoming mailbox “as is” without using the 7.0
email template features.

Use Supplied User Information field is set to Yes.

Preparing email templates after an upgrade
215

BMC Remedy Action Request System 7.0

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, perform one of the following tasks:

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 “Overview—Sending incoming
email with user instructions” on page 216.

Overview—Sending incoming email with user

instructions
A good analogy for understanding user instructions is that they are “macros”
for email. You can make email engine interaction easier for your users by
creating custom actions that reduce the need to learn the email engine syntax
of label/value pairs, variables, and so on. These custom actions are called user
instructions. Figure 6-11 provides a sample scenario of how to create user
instructions for your user community.

216 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Figure 6-11: Overview for using instruction templates

User sends email

4 with user-defined
instructions.

3 Template associated
with user instructions.

Email
Engine
Email
Server 2 Creates user
instructions.

AR
Server
Primary
Config-
uration

5 Results.

Underlying
Database

1 Admin creates and stores

email templates.

User-defined instruction templates automate actions to make it easy to

perform common user actions. Like macros, you can create predefined
submit and query actions with these instruction templates.
Every user instruction must be associated with an email template. Templates
provide generic layout for similar emails that are sent from or into the email
engine, simplifying email engine interactions for users. User Instruction
templates enable you to associate a template with an incoming email by way
of an entry in the AR System Email User Instruction Templates form.

Overview—Sending incoming email with user instructions
217

BMC Remedy Action Request System 7.0

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 that is
then executed. 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 can only send an email with an Action label/value pair, and
a variable value.
Creating user instructions involves the following tasks:

Step 1 The administrator creates a template, and then adds the template to the
AR System Email Templates form.

The user instruction template looks exactly the same as any other template.
It can be formatted like any other template (submit, modify, query, and so
on).

Step 2 The administrator creates a user instruction in the AR System Email User
Instruction Templates form by entering an instruction name into the
Instruction field on this form.

Step 3 The administrator associates the template created in step 1 with the user
instruction name.

Step 4 The user sends an incoming email that contains the user-defined instruction
to the BMC Remedy Email Engine. The email contains 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 extracted from the email, and the associated
template is then executed.

Step 5 As a result, the email engine constructs a message according to the template
instructions and sends the message to the user.

218 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Creating and storing a template for use with user instructions

As an administrator, you can use a text editor to define templates by creating
a text file with an extension of .arm, and then attaching the .arm file to an entry
in the AR System Email Templates form.

To create templates for use with user instructions

1 Use a text editor to define a template, and name the file with an .arm
extension.
The following example is a template file (IN_Install_AllUrgent.arm) that
queries all urgent records in the TestSecurityForm form.
Schema: TestSecurityForm
Server: polycarp
Login: Demo
Password:
Action: Query
Format: Full
Header Template: Header_Urgent.html
Result Template: Default Content
Qualification: 'Status' <= 2 AND 'Impact' = 3

A template can contain one or more instructions. See “Creating templates”

on page 188 for more information.

Tip: Test the template by sending email to the incoming mailbox and see if it
returns the expected results.

2 In BMC Remedy User, open the AR System Email Templates form in New
mode.
3 Attach your IN_Install_AllUrgent.arm file to an entry in the AR System Email
Templates form.

Overview—Sending incoming email with user instructions
219

BMC Remedy Action Request System 7.0

Figure 6-12: Storing template

4 Click the Template Attachments tab to add any header, footer, and result
templates that are used with your template.
5 Save your changes.
Your UrgentRequests template was created and now stored.

Creating user instructions

After storing your templates, you must associate a name with the User
Instruction by creating an entry in the AR System User Instruction
Templates form. The User Instruction name will be used as a value for the
Action Label in the email that is sent by the user to the incoming mailbox.

Note: You can associate more than one user instruction with a template
containing one or more instructions.

220 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

To create a user instruction

1 In BMC Remedy User, open the AR System User Instruction Templates form
in New mode.
2 Complete the form as follows. (See Figure 6-13 for an example.)
a Do not enter a template ID. The system will create the unique ID in the
Instruction Template ID field when you save the entry.
b From the Template Name menu, select the template that contains that
actions you want to associate with the user instruction.

Figure 6-13: Creating an entry—User Instruction Template form

You can only use templates that are stored in the AR System Email
Templates form, for example, UrgentRequests. (See “Creating and storing
a template for use with user instructions” on page 219.)
c To restrict the user instruction to one incoming mailbox, select a mailbox
from the Mailbox Name menu.
d Enter a character string value for the Instruction field.
This is the value that will be used to identify this template when used in an
incoming email, for example, Urgent.

Overview—Sending incoming email with user instructions
221

BMC Remedy Action Request System 7.0

Sending a user instruction in an incoming email

All authorized users can send an email to the incoming mailbox of the email
engine with the name of the User Instruction as the value of the Action Label.

To send a user instruction

1 Create a new email message in your mail tool.
2 Address the email message to the incoming mailbox.
3 Enter the user instruction in your email.
The user instruction consists of an Action label and value equal to the string
defined in the Instruction field in the AR System Email User Instruction
Templates form (Submit). The power of customized user instructions is that
your email could simply consist of the following text:
Action: Submit

Your email should include any values for the variables if any variables exist
in the template associated with the user instruction.
4 Send the email.

Results of the user instruction

The BMC Remedy Email Engine will then retrieve all records of urgent
requests from the AR System server and list them in the email, as shown in
Figure 6-14.

222 Chapter 6—Using email templates

 Administering BMC Remedy Email Engine

Figure 6-14: Email response to user instruction

After receiving an incoming email, the BMC Remedy Email Engine processes
a user instruction as follows:

Retrieves the associated user 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 template with substituted values in the incoming email.
As you can see, templates and user instructions can make it easier for your
users to interact with the email engine, reducing the need for them to learn
the email engine syntax. Instead, all they need to do is use the user instruction
name as the value of the Action Label.

Overview—Sending incoming email with user instructions
223

BMC Remedy Action Request System 7.0

Using variables with user instructions

You can also use variables with user instructions. Variables are useful when
you need to be able to send different values for the fields to submit an entry.
For example, you can create a user instruction that submits information into
the User Instruction form.
The user might send a user instruction in the following email:
Login:Frank Frontline
Password:mypassword
Action: Submit
!Employee_Name!: [$$Joe Smith$$]

The characters between the exclamation marks match the variable name in
the template that is associated with the user instruction (Submit). The email
engine will then:
1 Match the string between exclamation marks in the email with the variable
name in the template.
2 Retrieve the database name or field ID between the exclamation marks in the
template.
3 Substitute the field with that database name with the value sent in the email.

224 Chapter 6—Using email templates

Chapter

7 Troubleshooting

This chapter contains troubleshooting information. The following topics are

provided:

Troubleshooting outgoing email (page 226)

Email engine architecture (page 227)

Error and system status logs (page 229)

Debugging options for the BMC Remedy Email Engine (page 231)

Using the EmailDaemon.properties file (page 233)

Creating email debug batch files (page 242)

Fixing common problems with the email engine (page 248)

Troubleshooting
225
BMC Remedy Action Request System 7.0

Troubleshooting outgoing email

You will find the AR System Email Messages form especially helpful in
troubleshooting outgoing email. Performing a search in the form lets you see
the current status of email messages, for example, if outgoing messages are
being processed, if they were sent, or if there was an error, as shown in
Figure 7-1.

Figure 7-1: Status of email messages

It is a good practice to keep the AR System Email Messages form open when
using the examples in the chapter, or when you are experimenting with the
email engine. You can quickly see how the emails are being processed by the
email engine.

226 Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Email engine architecture

The BMC Remedy Email Engine consists of multiple modules that run in
threads, as shown in Figure 7-2. All the modules of the email engine are
designed to be thread safe, and to increase speed and scalability.
Some modules run in their own threads, while some modules run in the same
thread sequentially. For example, the architecture of the email engine is
designed so that each incoming mailbox uses two threads to process email in
the message queue—that is, the Receiver and Execution modules. But each
outgoing mailbox actually uses only one thread running sequentially from
the Creator module to the Sender module to format and send outgoing
messages.

Figure 7-2: Modules and threads in BMC Remedy Email Engine

You can specify various troubleshooting parameters, for example, the queue
size of email messages or how finely you want to log information within a
module. For more information, see “Debugging options for the BMC
Remedy Email Engine” on page 231 and “Using the
EmailDaemon.properties file” on page 233.

Email engine architecture
227

BMC Remedy Action Request System 7.0

The following table describes the purpose of each of the email engine
modules.

Module Description and purpose

Monitor Monitors the mailbox for statistical information such as when the
connection dropped and the length of time the connection was
down.
Receiver Runs in separate threads to maximize speed and reliability.

Reads incoming mails from the mail server.

Creates entries in AR System Email Messages form.

Adds messages to message queue.
Execution Parses and executes messages in the message queue.
Creator Primarily responsible for creating an email based on a template
and the data it retrieves from AR System.

Monitors the AR System Email Messages form for outgoing
messages.

Formats messages to be sent.
Sender Runs in a single thread with the Creator module to maximize speed
and reliability. It sends formatted messages to the mail server.
Logging Logs messages, errors, and warnings to the AR System Email
Errors form or local file.
Configuration Maintains configuration information for the system specified in
the AR System Mailbox Configuration form and
EmailDaemon.properties file.

228 Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Error and system status logs

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

Figure 7-3: 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 about:

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.

Connection status information for the AR System server containing the
configuration, logs, and email forms.

Error and system status logs
229

BMC Remedy Action Request System 7.0

Date and time the BMC Remedy Email Engine was started or stopped.

Changes to the configuration of the BMC Remedy Email Engine.

Tip: You can access the Email Error Logs form from the BMC Remedy User
Object List as well as from the Email Messages form. The Advanced tab in
the Email Messages form includes an Errors tab that, when selected,
displays the same log data for the message you are viewing that is also
displayed in the Email Error Logs form. If you click the table field entry
under the Errors tab, the entry created in the Email Error Logs form
appears.

For more information, see “AR System Email Error Logs form” on page 305.

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 see 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 not exist on server
Appended Text: XYZForm

230 Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

AR System API errors

The email engine will log any AR System API errors that occur while
executing instructions in an email. For more information, see the Optimizing
and Troubleshooting guide.

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.

Debugging options for the BMC Remedy Email Engine

The logging.properties file that you use for debugging the email engine is
usually found in the Java lib directory. For specific issues, see “Fixing
common problems with the email engine” on page 248.
The following options are available:

Setting Definition
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 an
java.util.logging.ConsoleHandler emaild.sh_log file under the log’s subdirectory of the
email installation, but file logging can also be switched on.
Global Logging Level Logging level for the file output. You can set the logging level
java.util.logging.FileHandler. to Finer in the Java logging.properties file to obtain every
LEVEL = FINER 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 Logs 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.

Debugging options for the BMC Remedy Email Engine
231

BMC Remedy Action Request System 7.0

Setting Definition
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
formatter = logging.
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.SimpleFormatte
r
Main Application Level 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.

232 Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Setting Definition
Module Levels Levels for application modules. You can specify the logging
com.remedy.arsys.emaildaemon. levels for the various modules independently from the entire
<Module>.level= email engine logging level, for only the modules you are

ConfigurationModule.level=FINER interested in troubleshooting.

CreatorModule.level=FINER These application modules allow you to combine main

ExecutionModule.level=FINER application and module logging.

ReceiverModule.level=FINER For example, if the main application level is set to INFO and

SenderModule.level=FINER you set the level for the Receiver Module to FINER, then you

MonitorModule.level=FINER 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 BMC Remedy Email Error form.
com.remedy.arsys.emaildaemon. You cannot disable this handler as you can with the Console
ARSystem and File. This level could also be overridden if the application
Handler.level = WARNING level defined previously is higher.

Using the EmailDaemon.properties file

When the 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, user name, and password. The
main purpose of the EmailDaemon.properties file is to identify the
AR System server your email engine communicates with.

Using the EmailDaemon.properties file
233

BMC Remedy Action Request System 7.0

Figure 7-4: Sample contents of EmailDaemon.properties file

Tip: When discussing the internal components of the BMC Remedy Email
Engine, the term “email daemon” is frequently used. For example, “email
daemon” is used to describe background processes launched at start-time,
email “handlers,” the use of various threads to carry out different tasks
(for example, sending mail, receiving mail, parsing instructions), and so
on. In UNIX, these background processes are usually called “daemons,”
whereas for Windows they are called “services.” Following the UNIX
convention, the file you use to set parameters for the email engine is called
EmailDaemon.properties. For the most part, you should think of the
BMC Remedy Email Engine as synonymous with the email daemon.

To use the EmailDaemon.properties file, see “Fixing common problems

with the email engine” on page 248.

234 Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Updating the 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.

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;arapi70.jar;arutil70.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:arapi70.jar:arutil70.jar:activation.jar:mail.jar:imap
.jar:smtp.jar:pop3.jar com.remedy.arsys.emaildaemon.EmailDaemon
<parameters>

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.

Table 7-1 lists the available parameters:

Table 7-1: Email engine startup parameters

Parameter Description
-s Server where the email forms (and the configuration information)
are located.
-p AR System Application Service password. The email engine uses the
same password as that supplied in BMC Remedy Administrator
under File > Server Information > Connection Settings >
Application Service Password.

Using the EmailDaemon.properties file
235

BMC Remedy Action Request System 7.0

Table 7-1: Email engine startup parameters

Parameter Description
-t TCP port for the server to which the email engine should connect.
-r RPC number of the server to which the email engine should be
connected. This parameter can be useful if you want to connect to a
private server. This can enhance performance if you expect a high
volume of mail.
-l Language to be used. (The default is C.)
-d 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 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 MAPI sent folder where sent mail should be stored.

Performance and configuration settings

The EmailDaemon.properties file also lets you specify properties you can
use to enhance the performance of the email engine. For specific
troubleshooting issues, see “Fixing common problems with the email
engine” on page 248.

236
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

The following properties are available in the EmailDaemon.properties file 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 additional email headers. The
AdditionalMailHeaders=X-Loop- additional email headers are to be separated by comma.
Detect
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
ARDATEONLY= engine 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
ARTIMEONLY= engine for parsing time strings. HH:mm:ss z is equivalent to
12:08:56 PDT.
com.remedy.arsys.emaildaemon. This setting lets you specify the set size of entries to return when
ChunkSize=100 the email engine makes a call to the AR System server. The
default chunk size of entries returned is set to 100.
com.remedy.arsys.emaildaemon. Specifies whether you can use a comma as a separator when
CommaValidAddressSeparator= entering multiple addresses in the To and CC lines. By default,
true this property is set to true.
Set this property to false if user names in mail server contains
commas. (This is usually needed only when using MAPI
protocol.) For example, if a name is stored on the mail server as
follows:
Smith, John
and
Cho, Rick
You would need to use semicolons to separate the addresses:
Smith, John; Cho, Rick

com.remedy.arsys.emaildaemon. This setting specifies the amount of time the thread waits before
Exchange-Wait-Time=1 processing the next message when there are more messages to be
processed. The unit of time is milliseconds.
com.remedy.arsys.emaildaemon. This setting lets you add new log messages for logging
ExecutionModule.level=Fine instructions and instruction parameters.

Using the EmailDaemon.properties file  237

BMC Remedy Action Request System 7.0

Settings Definitions
com.remedy.arsys.emaildaemon. This setting lets you specify whether to fetch the user and group
FetchUserGroupInfoOnDemand= information about demand as opposed to loading all users and
false groups at startup. The default value for this property is false.
If there are many users or groups, you might want to set this
property to true to reduce the startup time for email.
com.remedy.arsys.emaildaemon. This setting lets you change the default number of how many
IncomingConnectionRecycleSize= email messages the email engine receives before the connection
100 is closed 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 was closed, the messages marked for deletion
might 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 messages to server in AR System Email Messages
form, but the Execution module reads the message from the
message queue instead of from the server. This reduces the
traffic to the AR System server and improves the performance.
The default message queue size is set to 100.
com.remedy.arsys.emaildaemon. This setting lets specify the size of the cache used for storing
instructionCacheSize=20 instructions, to improve performance.
The default setting keeps 20 instructions in cache. If there are 20
instructions and another is added, the oldest instruction is
removed. If any changes are made to the Email Instructions
form, the instruction cache is flushed based on the
configuration Interval setting.
com.remedy.arsys.emaildaemon. If you run multiple email engines for a single server, this setting
Mailboxes= specifies which mailboxes this email engine should process. The
value should contain comma-separated mailbox names. If the
value is empty, the email engine processes all of the mailboxes
configured for the server. If the value is not empty, the email
engine processes the specified mailboxes only.

238
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Settings Definitions
com.remedy.arsys.emaildaemon. This setting lets you change the polling interval value from
MailboxPollingUnitIsMinutes= minutes (as configured in the AR System Email Configuration
true form) to seconds. Setting the value to false means interpret the
polling number as seconds, for example,
com.remedy.arsys.emaildaemon.
MailboxPollingUnitIsMinutes=false.

Note: Whatever measure of unit you select applies to all enabled

configured mailboxes.
com.remedy.arsys.emaildaemon. Together, these settings let you specify the maximum size of
MaxAttachSize specific attachment types that you will allow in an email
com.remedy.arsys.emaildaemon. message. For example, to set the maximum size of .doc, .pdf,
MaxAttachSizeFileExtensions and .xls attachments to 1000000 bytes (1MB), you would use
the following syntax:
com.remedy.arsys.emaildaemon.MaxAttachSize=1000000
com.remedy.arsys.emaildaemon.MaxAttachSizeFileExtens
ions=doc,pdf,xls
File extensions that are not defined have no size limit.
Email with attachments that exceed this maximum size are
logged to the AR System Email Error Logs form. Extension
types in MaxAttachSizeFileExtensions are separated with
commas. Optionally, you can then create workflow against this
form to process these messages separately.
com.remedy.arsys.emaildaemon. This setting lets you specify the interval between checks to see if
Monitor=30 all the threads 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 specify the number of sender threads per
NumberOfSenderThreads=1 outgoing mailbox that the email daemon uses. The optimum
number of threads depends on many factors including the
number of mailboxes, hardware of the machine, and so on. The
default value for this setting is 1.
com.remedy.arsys.emaildaemon. This setting lets you specify the size of the queue that the email
OutgoingMessagesQueueSize= daemon maintains for the outgoing mails.
100
The default size of outgoing message queue size is set to 100. The
optimum number of message queue size to be specified depends
on the load on the email daemon.

Using the EmailDaemon.properties file  239

BMC Remedy Action Request System 7.0

Settings Definitions
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 make sure that memory is properly released.
The default setting is 100 messages.
com.remedy.arsys.emaildaemon. This setting lets you specify the port for RMI (remote method
RMIPORT=1099 invocation). This feature is used with the
EmailAdminAgent.jar file to stop, suspend, resume, or
change logging to the email engine.
com.remedy.arsys.emaildaemon. This setting lets you keep the sent items in the Email Messages
SaveSentItem=True form.
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 any
changes are made to the Email Security form, the cache is
flushed based on the configuration Interval setting.
com.remedy.arsys.emaildaemon. This setting lets you specify how many outgoing emails to query
SendEmailSetSize=100 at a time. The default size of outgoing emails is set to 100.
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 (for
example, if you have modified records in the Email Mailbox
Configuration form) or updates to templates (for example, if
you modified templates in the Email Templates 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>.Interva
l=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
<server_name>.RPC=0 AR System server uses if you have configured a private server to
use with the email engine.

240
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Settings Definitions
com.remedy.arsys.emaildaemon. This setting lets you specify what TCP port number the
<server_name>.TCP=0 AR System uses if your AR System server is not using
Portmapper.
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
SortMessages=false setting are processed first. The default setting is false.
com.remedy.arsys.emaildaemon. This setting lets you store instructions and instruction
StoreInstructions=true parameters in the AR System server. Setting this option to true
lets 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 specify how many email templates are kept
templateCacheSize=20 in cache, to improve performance.
The default setting keeps 20 templates in cache. If there are 20
templates and another is added, the oldest template is removed.
If any changes are made to the Email Templates form, the cache
is flushed based on the configuration Interval setting.
com.remedy.arsys.emaildaemon. This setting lets you specify how the email engine behaves when
UseNameIfNoEmailAddress=true the To, CC, or BCC field has a display name instead of an email
address.
If this property is true (the default), the display names that do
not have associated email address are not removed from the To,
CC or BCC fields.
If this setting is false, the display names that do not have
associated email addresses are removed from the To, CC or BCC
fields.
com.remedy.arsys.emaildaemon. This setting lets you specify the number of users (records from
UserChunkSize=5000 the User form) to retrieve from the AR System server at one
time, to improve performance. The default chunk size of users
returned is set to 5000.

Using the EmailDaemon.properties file  241

BMC Remedy Action Request System 7.0

Creating email debug batch files

Creating a debug email batch file using the -Dmail.debug=true debug mode
can help resolve issues that might 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 useful for debugging the email
engine in contrast to using the AR System Email Error Logs form. The
contents of the AR System Email Error Logs form can become very large.

Tip: If you are having problems with the email engine, BMC Remedy
Customer Support frequently will ask you to use to -Dmail.debug=true
debug mode to troubleshoot the issue.

Windows—Debugging the email engine

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

To debug the Windows email engine

1 Edit the emailstart.bat file and add the -Dmail.debug=true option after
"%JavaPath%\java":
"%JavaPath%\java" -Dmail.debug=true -cp
emaildaemon.jar;arapi70.jar;arutil70.jar;activation.jar;mail.jar;imap
.jar;smtp.jar;pop3.jar;armapi70.jar
com.remedy.arsys.emaildaemon.EmailDaemon

The default location of the emailstart.bat file is

C:\Program Files\AR System\AREmail.

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

3 Make sure that the BMC Remedy Email 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.out to the end of the previous Java statement.

242
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Sample debug log

The contents of a sample debug log follow.
C:\Program Files\AR System\AREmail>echo off
Application has started Version: 07.00.00
Using JRE: 1.4.1_02
Checking connection to server: polycarp ...
loaded library
Successfully connected.
DEBUG: JavaMail version 1.3
DEBUG: successfully loaded file: C:\Program
Files\Java\j2re1.4.1_02\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: 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: 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,mapi@remedy.com],
com.remedy.mail.mapi.MAPIStore=javax.mail.Provider[STORE,mapistore,co
m.remedy.mail.mapi.MAPIStore,mapi@remedy.com],
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]}

Creating email debug batch files  243

BMC Remedy Action Request System 7.0

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,mapi@remedy.com],
mapitransport=javax.mail.Provider[TRANSPORT,mapitransport,com.remedy.
mail.mapi.MAPITransport,mapi@remedy.com],
pop3=javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Sun
Microsystems, Inc],
smtp=javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTranspo
rt,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_02\lib\javamail.address.map (The system cannot
find the file specified)
DEBUG: JavaMail version 1.3
DEBUG: successfully loaded file: C:\Program
Files\Java\j2re1.4.1_02\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: 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: 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,mapi@remedy.com],
com.remedy.mail.mapi.MAPIStore=javax.mail.Provider[STORE,mapistore,co
m.remedy.mail.mapi.MAPIStore,mapi@remedy.com],
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]}

244
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

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,mapi@remedy.com],
mapitransport=javax.mail.Provider[TRANSPORT,mapitransport,com.remedy.
mail.mapi.MAPITransport,mapi@remedy.com],
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: /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_02\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 "essmail2", port 110
S: +OK Microsoft Exchange 2000 POP3 server version 6.0.6249.0
(essmail2.eng.remedy.com) ready.
C: USER stamps3
S: +OK
C: PASS password
S: +OK User successfully logged on.
C: STAT
S: +OK 0 0
C: QUIT
S: +OK Microsoft Exchange 2000 POP3 server version 6.0.6249.0 signing
off.

UNIX—Debugging the email engine

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

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

Creating email debug batch files  245

BMC Remedy Action Request System 7.0

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.

246
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Example of outgoing email using SMTP

The contents of a sample debug log for outgoing email follow.
DEBUG: getProvider() returning
javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTransport,Su
n Microsystems, Inc]
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 2004 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
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
rsteck@remedy.com
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

Creating email debug batch files  247

BMC Remedy Action Request System 7.0

Example of incoming email using MBOX

The contents of a sample debug log for incoming email follow. 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

Fixing common problems with the email engine

This section describes how to diagnose and solve some problems you might
encounter with the BMC Remedy Email Engine. The most common issue
reported is that the email engine is not receiving or sending any new emails.
The email engine can be a powerful and useful tool if configured and used
correctly.

Configuring mailboxes
A common problem that users experience with the email engine is that they
cannot send or receive email. A straightforward way to troubleshoot this
problem is to verify that you have properly configured your incoming and
outgoing mailboxes.

248
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Testing your incoming mailbox

If you were unable to test your incoming mailbox configuration successfully,
verify the following conditions:

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

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 make to your mailbox in an effort to troubleshoot

possible configuration problems, might not be immediately recognized by
the email engine. For more information, see “Changing the form entry
interval time” on page 76.

Fixing common problems with the email engine  249

BMC Remedy Action Request System 7.0

Testing your outgoing mailbox

If you were unable to test your outgoing mailbox configuration successfully,
verify the following conditions:

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 make
sure 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 you have logged in
to the system as the domain user account that has permission to use the
MS Exchange profile (MAPI).

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 make to your mailbox in an effort to troubleshoot

possible configuration problems, might not be immediately recognized by
the email engine. For more information, see “Changing the form entry
interval time” on page 76.

Logging problems with the email engine

The reason you have problems sending or receiving email can depend on
when the error occurs and the frequency at which it occurs. The best way to
troubleshoot these problems is by creating log files and examining your
console output.

250
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

To use the email engine logs and console output

1 Stop the email engine, and then re-start the email engine from the command
line using debug mode. For more information, see “Creating email debug
batch files” on page 242.
2 Examine the AR System Email Error Logs form. The email daemon always
uses the AR System Email Error Logs form when logging errors and
warnings. This should be the first place any administrator looks to identify
an issue.
3 Consult the console output to access more details, such as stack traces and the
exact exceptions thrown. The location of the console output depends on how
the application is executed and on which system.

(Recommended) For both Windows and UNIX, when the email engine is
started from the command line, all console output is piped to the open
console window. This is the quickest and easiest way to identify an issue
because you can see where the output actually occurred and you can trace
any errors.

When the email daemon is executed on Windows as a service, the output
is located under the logs subdirectory of the email engine installation (by
default, c:\Program Files\AR System\AREmail\Logs). You might find
two files: stdout.log and stderr.log. Both files contain the console
output, but stdout.log contains normal output, such as the startup
information and possible debug output, while stderr.log contains any
errors generated while the application was running.
On any UNIX system, you can view the console output under the logs
sub-directory of the email engine installation, as you can with Windows,
but in UNIX, the console output is stored in just one file called
emaild.sh_log.

4 Make sure that console logging is turned on in the logging.properties file,

located in the <Java_install>/lib directory.
5 Enable the console output with the following handler property:
handlers= java.util.logging.ConsoleHandler

6 Set the level for console logging.

Usually, the level is set to INFO by default, which locates most problems with
the email engine. You set this level with the following line:
java.util.logging.ConsoleHandler.level = INFO

Fixing common problems with the email engine  251

BMC Remedy Action Request System 7.0

7 Set the level for the entire application. Make sure that the following two lines
are located in the logging.properties file:
com.remedy.arsys.emaildaemon.level = INFO
com.remedy.arsys.emaildaemon.ARSystemHandler.level = INFO

The first line sets the level for the entire application; the second line sets the
level for logging to the AR System Email Error Logs form. The level for the
form logging should never be set lower than this. Otherwise, the table will fill
up very quickly and use unnecessary space.

Defining a heap size for the email engine

Sometimes you see “out of memory” errors if you run out of heap space. You
should set your heap size according to your memory needs. BMC Remedy
cannot recommend exact settings; try modifying the minimum and
maximum settings, and then stopping and restarting the email engine. You
might see dramatic improvements in performance.

Windows—Setting the heap size

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:
java -ms50m -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.

UNIX—Setting the heap size

For Java 1.4.x, the options to use are -Xms<size> for the minimum, and
-Xmx<size> for the maximum. For example, you could insert the following
line into the emaild.sh file:
java -Xms50m -Xmx256m com.remedy.arsys.emaildaemon.EmailDaemon

252
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Troubleshooting startup issues

After installing the new email engine, users might find that email has not
been sent or received. In this situation, new email, ready to be sent, has the
status set to Yes, but the status does not change to Error or Sent. This is a
common problem with the email engine and is usually easy to fix. The
following troubleshooting sections describe three common scenarios and
their possible solutions.

Identifying invalid application service passwords

When viewing the AR System Email Error Logs form, you might not find any
errors. Further, it might seem that the email daemon is not working at all. In
this situation, the most likely problem is that the email engine is not able to
communicate with the AR System server. You might have supplied an invalid
application service password during installation.

To determine the use of an invalid password

1 Use the debug mode to start the email engine from the command line. For
more information, see “Creating email debug batch files” on page 242.
2 Review the console output and note the JRE version used by the email engine.
The JRE version should be 1.4.1_01 or higher. Typically, a functioning email
daemon outputs the following status information:
C:\Program Files\AR System\AREmail>echo off
Application has started Version: 07.00.00
Using JRE: 1.4.1_02
Checking connection to server: polycarp ...
loaded library
Successfully connected.

From this console output, you can see that the email daemon is using the
correct JRE version, 1.4.1_02.

Note: Installing Java version 1.4.1_00 (or later) is mandatory for installation
of the email engine to finish successfully. If you do not have the correct
Java version, the installation program exits and you are reminded to install
Java 1.4.1_00 (or later) before you try installing again.

Fixing common problems with the email engine  253

BMC Remedy Action Request System 7.0

The console output also shows that the email daemon has loaded the
AR System API library correctly. If the email daemon was unable to connect
to the AR System server, you might see the following error:
Application has started Version: 07.00.00
Using JRE: 1.4.1_02
loaded library
8-Apr-2004 11:06:52 AM com.remedy.arsys.emaildaemon.LoggingModule
doWork
SEVERE: Invalid password for an existing user

If you see this, the Application Service Password you supplied during
installation is incorrect. To fix the problem, you must edit the startup script.
3 Open the startup script file in a text editor—on Windows, EmailStart.bat,
on UNIX, emaild.sh.
4 Append the following statement to the end of the line that starts the email
engine:
-s <ar_system_server_name> -p <application_service_password>

5 Execute the script, which updates the system with the correct password by
applying the changes to the EmailDaemon.properties file.
6 Edit the script again, remove this addition, and restart your system.

Removing invalid application service passwords

Use one of the following methods to remove the invalid password:

To remove an invalid password using BMC Remedy Administrator

1 Log in to BMC Remedy Administrator.
2 Select the server on which the email engine is installed.
3 Open the Server Information window.
4 Click the Connection Settings tab.
5 If there is a password in the Application Service Password field, remove it.
6 Save your changes.
7 Stop and start the AR System server.
8 Stop and re-start the email engine.
After the password is removed, the console output should show that the
email daemon has successfully connected to the AR System server with no
errors.

254
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

To remove an invalid password using the EmailDaemon.properties

file
1 Open the EmailDaemon.properties file, usually located in the email engine
installation directory.
2 Locate the following line:
com.remedy.arsys.emaildaemon.<ar_system_server_name>.Password=<applic
ation_service_password>

It might look like the following example:

com.remedy.arsys.emaildaemon.polycarp.Password=zB1<V+%WHAmgwobh7mZL_~
|L}7+isE

3 Change its contents to the following text:

com.remedy.arsys.emaildaemon.polycarp.Password=

4 Stop and start the AR System server.

5 Stop and re-start the email engine.
After the password is removed, the console output should show that the
email daemon has successfully connected to the AR System server with no
errors.

Determining if the wrong AR System server is specified

Another common problem is that you specified the wrong AR System server
name when you installed the email engine. You can fix this problem by
executing a search and replace on the contents of the
EmailDaemon.properties file.

To determine if a wrong AR System server is specified

1 Open the EmailDaemon.properties file.
2 Replace all references to the incorrect server name with the correct server
name. The search and replace functionality is required, since the file uses the
server name in several places.
3 Check the connection to the AR System Server if you are using a specific TCP
port or RPC number. Update these references as well in the
EmailDaemon.properties file:
com.remedy.arsys.emaildaemon.<ar_system_server_name>.TCP=4040
com.remedy.arsys.emaildaemon.<ar_system_server_name>.RPC=0

Fixing common problems with the email engine  255

BMC Remedy Action Request System 7.0

Remember that the <ar_system_server_name> tag is the name of the server

against which the email engine is running and could be an alias like
production (for example,
com.remedy.arsys.emaildaemon.production.TCP=4040).

4 Examine the AR System Email Mailbox Configuration forms to make sure

that you have configured your mailboxes correctly. Check to make sure that
you have not disabled any of the mailboxes.
5 Save your changes to the EmailDaemon.properties file.
6 Stop and re-start the email engine.
The console output should show that the email daemon has successfully
connected to the AR System server with no errors.

Determining problems with the mail server

If the email daemon is able to connect to the AR System server, but incoming
email is not logged and outgoing emails have not been sent, errors should be
logged in the form and on the console, assuming that console logging has
been enabled properly. Some error messages you might encounter with the
mailbox include:

Unknown Host Exception

Authentication Failed Exception

Connect Exceptions, such as Connection Refused
In these situations, the problem is usually because the mailbox has not been
configured properly in the AR System Email Mailbox Configuration form.
The connection exception error might also occur if the email server (such as
MS Exchange) is too busy to handle the connection or you have connected
too many times in a given time period (due to a DOS attack). Use the
following procedure to check the mail server.

To determine problems with the mail server

1 Log in to BMC Remedy User.
2 Open the AR System Email Mailbox Configuration form in Search mode.
3 Open the entries for both the incoming and outgoing mailboxes.
4 Check the email server name. Confirm that you can ping or connect from the
system by using an email client, such as MS Express.

256
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

5 Confirm the email server supports the protocol you supplied, for example,
MAPI or SMTP.
6 Confirm the email server port.
7 If you are unsure, click the Set Email Server Port button to force this value to
be the default for that protocol. Each protocol has a different default value,
unless the mail server has been configured differently. If this is the case, check
the value with your email server administrator.
8 Check the User Name and Password. Retype them if necessary.

Windows—Fixing MAPI transport problems

When using the email engine on Windows, your primary email server is MS
Exchange, and you have specified MAPI as the protocol to use, you might
encounter the following MAPI transport error when starting the email
daemon:
Application has started Version: 07.00.00
Using 1.4.1_02
loaded library
8-Apr-2004 12:00:36 PM javax.mail.Session getService
SEVERE: mapitransport
javax.mail.NoSuchProviderException: mapitransport
at javax.mail.Session.getService(Session.java:760)
at javax.mail.Session.getTransport(Session.java:685)
at javax.mail.Session.getTransport(Session.java:628)
at javax.mail.Session.getTransport(Session.java:608)
at com.remedy.arsys.emaildaemon.SenderModule.openTransport
(SenderModule.java:103)
at com.remedy.arsys.emaildaemon.CreatorModule.doWork
(CreatorModule.java:323)
at com.remedy.arsys.emaildaemon.ThreadBase.run
(ThreadBase.java:259)
at java.lang.Thread.run(Thread.java:536)

You typically see this problem when the JavaMail System does not know what
transport setting to use for MAPI, and the library cannot locate the correct
class to use for MAPI.

Fixing common problems with the email engine  257

BMC Remedy Action Request System 7.0

To fix the MAPI transport problem (Windows)

1 Locate the javamail.providers file in the lib directory of the JRE
installation. This is the same location as the logging.properties file. You
can create this file if necessary.
2 On the first line, verify (or add) the following text:
protocol=mapistore; type=store; class=com.remedy.mail.mapi.MAPIStore;
vendor=mapi@remedy.com;

3 On the second line, verify (or add) the following text:

protocol=mapitransport; type=transport;
class=com.remedy.mail.mapi.MAPITransport; vendor=mapi@remedy.com;

4 Stop and re-start the email engine.

These settings make sure that the JavaMail System uses the class created to
support MAPI for both incoming and outgoing mailboxes.

UNIX—Fixing MAPI transport problems

On UNIX, where you might be using MBOX as your protocol, you will see a
similar error except that the mapitransport string will be labeled mbox. You
fix this problem in exactly the same way as on Windows.

To fix the MAPI transport problem (UNIX)

1 Locate the javamail.providers file in the lib directory of the JRE
installation. This is the same location as the logging.properties file. You
can create this file if necessary.
2 On the second line, verify (or add) the following to the javamail.providers
file:
protocol=mbox; type=store; class=gnu.mail.providers.mbox.MboxStore;
vendor=mapi@remedy.com;

3 Stop and re-start the email engine.

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.

258
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

Stopping and starting the AR System server

If you stop the AR System, the email daemon stops all the appropriate
threads until the AR System server is started again. During this time, the
email daemon stops all the threads monitoring this AR System server for new
outgoing emails and also all the associated mailboxes for new incoming
emails. After these threads have been stopped, the email daemon goes to
sleep for the configured time period (the default setting is 30 minutes).
When that time expires, the email daemon then checks if the AR System
server is running and takes one of two actions based on the results:

If the AR System server is still down, the email daemon will go back to
sleep for the configured time period.

If the AR System server is running, the email daemon will restart all the
appropriate threads and continue to run as it normally should.
You can adjust the configuration time that the email daemon monitors the
AR System server by modifying the following line in the
EmailDaemon.properties file:
com.remedy.arsys.emaildaemon.Monitor=<num>

Where <num> is any valid integer and this parameter is measured in minutes.
If you set <num> to 5, the email daemon waits five minutes before checking
to see if the server is running.

Note: The name of the server is not used in this line. If you do not want to
wait, restart the email daemon as soon as the AR System server starts.

Making changes to mailbox configuration

If you make changes to the configuration of any mailbox or remove the
mailbox by deleting the entry for this mailbox, you do not need to restart the
email engine. The email daemon will notice the change, but not immediately.
The email daemon usually checks for configuration changes every 30
minutes (the default setting). If you want to shorten this time, add or modify
the following line in the EmailDaemon.properties file:
com.remedy.arsys.emaildaemon.<ar_system_server_name>.Interval=<num>

Where <num> represents an integer value and the parameter is measured in

minutes.

Fixing common problems with the email engine  259

BMC Remedy Action Request System 7.0

Note: By shortening the time, the email daemon will make more frequent
calls to the AR System server. If you are not making many changes to the
configuration, you should wait the default 30 minutes, or manually restart
the entire email engine system after making the configuration changes.

The same process applies when you make changes to an existing user, if you
change the Internet email address on the form. The email daemon notices
this change based on the predefined interval.

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 than the machine where the
email engine is installed, might experience the following problems:

The query result might not be the same as a BMC Remedy User query
result.

The query result might not be correct.

A request might be registered with an unexpected date or time.
These problems occur because the time zone is not adjusted between the
BMC 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. For more information, see
“Displaying date/time or numeric values in email notifications” on page 104.

Verifying permissions for the Windows accounts

If the BMC Remedy Email Engine will not run as a Windows 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.

260
Chapter 7—Troubleshooting

 Administering BMC Remedy Email Engine

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

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

Troubleshooting email request processing and notify filters

The 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 BMC 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 the administrator can instruct users as to the correct
procedures for formatting and submitting messages.

Fixing common problems with the email engine  261

BMC Remedy Action Request System 7.0

262
Chapter 7—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. You can copy
and paste these examples into the body of an email message, or you can use
the examples to create your own templates. For more information, see
Chapter 6, “Using email templates.”
The following topics are provided:

Creating email templates to search for Request ID (page 264)

Creating email templates to search for fields (page 265)

Creating email templates to perform searches using qualifications
(page 266)

Creating email templates that include attachments (page 267)

Creating an email content template with Submit and Query actions
(page 268)

Creating an email reply using result templates in HTML format
(page 270)

Email status template in HTML format (page 273)

Adding a header template and a footer template (page 275)

Examples of email templates  263

BMC Remedy Action Request System 7.0

Creating email templates to search for Request ID

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

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: polycarp
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.
c Enter the Request ID of the entry to be retrieved.
d Remove all other fields from the mail template. (The only field in the body
should be !1! <RequestID_number>.)
The following example shows an exported template that was modified to
search for a request ID:
Schema: vacation
Server: polycarp
Login:
Password:
Action: Query
Format: Short
Values: Short, Full
!1!:TT00000000119

264
Appendix A—Examples of email templates

 Administering BMC Remedy Email Engine

Creating email templates to search for fields

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: polycarp
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.
The following example shows an exported template that was modified to
search for multiple fields.
Schema: AR-HD Calls
Server: polycarp
Login:
Password:
Action: Query
Format: Full
Source !5368737933!: Phone
Caller Impact !5368783455!: Low

Creating email templates to search for fields  265

BMC Remedy Action Request System 7.0

Creating email templates to perform searches using

qualifications

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

The following example shows an exported file that was modified to search
using the Qualification label.
Schema: AR-HD Calls
Server: polycarp
Login:
Password:
Action: Query
Format: Short
Qualification: 'Source' = "Phone" OR 'Source' = "email"

266
Appendix A—Examples of email templates

 Administering BMC Remedy Email Engine

Creating email templates that include attachments

The following is an example of an email template that includes an attachment
field.

To create an email template that includes attachments

1 Export the email template for the form that you want to make available for
submitting.
Make sure that the form contains an attachment pool and a valid attachment
field.
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: polycarp
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)

Note: Make sure that you use the ID of the attachment field, not the
attachment pool.

3 In a third-party client tool such as MS Outlook Express, create a new email.

4 Copy and paste the template into the body of the email
5 Add all the required values, for example, Login name, password, and so on.
6 Supply the attachment file name including the extension after the attachment
field parameter.

Creating email templates that include attachments  267

BMC Remedy Action Request System 7.0

The following is an example of a user email template filled out with a

filter.log file attached.

Schema: Email Submit

Server: polycapr
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

7 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.
8 Send the email to the incoming mailbox.

Creating an email content template with Submit and

Query actions
The following example submits an entry into a form, then queries that same
form.
When 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.
Schema: HD Incident
Server: polycarp
Login: Demo
Password:

Action: Submit
# Values: Submit, Query
Format: Full
# Values: Short, Full
Submitter ! 2!: $USER$
Short Description ! 8!: Need to create new post office box.
!Last Name!: Stampovich
!First Name!: Ivan

268
Appendix A—Examples of email templates

 Administering BMC Remedy Email Engine

!Email!: stampovic@remedy.com
!Location!: Sunnyvale
!Phone!: 222-3333
!Status!: Assigned
!Impact!: Medium
!Item!: Email
!Category!: Applications
!Type!: Office
!Problem Summary!: Need to create new post office box.
!536870920!: boot.ini

Action: Query
Qualification: 1=1

If you did not specify a template for the email reply, the BMC Remedy Email
Engine would reply with the results shown in Figure A-1:

Figure A-1: Reply to action template using default format

In addition, the Query action returned the Submit entry to the user, along
with any other entries that met the qualification. Because no template was
defined as a Results Template, the BMC Remedy Email Engine used the
default internal text format.

Creating an email content template with Submit and Query actions  269
BMC Remedy Action Request System 7.0

Creating an email reply using result templates in HTML

format
For the email engine to include a Result Template in the reply email, enter
the Result Template label/value pair as a global declaration in the body of
your email, as in the following extract:
Schema: HD Incident
Server: polycarp
Result: HDIN Content
Login: Demo
Password:
....

When the BMC Remedy Email Engine sends the reply email, it will use the
result template shown in Figure A-2:

Figure A-2: Reply to action email using a result template

For a detailed example, see “Using HTML result templates with outgoing
email” on page 131.

270
Appendix A—Examples of email templates

 Administering BMC Remedy Email Engine

The Result Template must be stored in the AR System Email Templates form
before it can be used in the email. For more information, see “Storing
templates in the AR System Email Templates form” on page 209. If graphics
are included, and these are not contained in the HTML file, the graphics must
also be added using the Template Attachments tab of the AR System Email
Templates form. For more information, see “Adding attachments to HTML
templates” on page 211.
In this template, variables correspond to a field on the HD Incident form on
which the template is based (for example, #$$Last Name$$#). The
administrator only specifies the fields that are of interest. For more
information, see “Variables” on page 203.
When you send your email, the BMC Remedy Email Engine parses and
executes the instructions in the Results template. It formats the reply and
substitutes values for the variables. For more information about results
templates, see “Result Template label” on page 197.

Sample HTML result template

If you create your result templates with HTML, you can professionally
format the reply results that users see.

Figure A-3: HTML result template

Creating an email reply using result templates in HTML format  271

BMC Remedy Action Request System 7.0

The following HTML code was used to create the result template shown in
Figure A-3. Copy, paste, and then adapt what you need for your own result
template.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>HDIN_Content</TITLE>
<META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<META content="MSHTML 6.00.2800.1126" name=GENERATOR></HEAD>
<BODY>
<TABLEcellSpacing=0cellPadding=0width=772border=0><!--DWLayoutTable-->
<TBODY>
<TR>
<TD vAlign=top width=772 height=234>
<TABLE borderColor=#cccccc cellSpacing=1 cellPadding=1 width="100%"
border=0>
<TBODY>
<TR borderColor=#cccccc>
<TD colSpan=5>
<HR>
</TD></TR>
<TR borderColor=#cccccc>
<TD width="11%"><B><I>Incident #</I></B></TD>
<TD width="17%"><a href="http://polycarp/arsys/servlet/
ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request
ID$$#">#$$Request ID$$#</a> </TD>
<TD width="21%">&nbsp;</TD>
<TD width="14%">&nbsp;</TD>
<TD width="37%">&nbsp;</TD></TR>
<TR borderColor=#cccccc>
<TD colSpan=5><B><FONT color=#008000 size=3><U>Requester

Information________________________________________________________________________
____</U></FONT></B></TD></TR>
<TR borderColor=#cccccc>
<TD width="11%" height=56>
<DIV align=center><IMG height=40 src="people.gif"
width=38></DIV></TD>
<TD width="17%" height=56><B><FONT size=3>Last Name</FONT></B></TD>
<TD width="21%" height=56><FONT size=3>#$$Last Name$$#</FONT></TD>
<TD width="14%" height=56><B><FONT size=3>Email</FONT></B></TD>
<TD width="37%" height=56><FONT size=3>#$$Email
Address$$#</FONT></TD></TR>
<TR borderColor=#cccccc>
<TD colSpan=5><FONT size=3><B><FONT color=#008000><U>Incident

Information________________________________________________________________________
______</U></FONT></B></FONT></TD></TR>
<TR borderColor=#333333>
<TD borderColor=#cccccc width="11%" rowSpan=3>
<DIV align=center><FONT size=3></FONT><FONT size=3><B><IMG height=43
src="tools.gif" width=46></B></FONT></DIV></TD>
<TD borderColor=#cccccc width="17%"><B><FONT
size=3>Impact</FONT></B></TD>

272
Appendix A—Examples of email templates

 Administering BMC Remedy Email Engine

<TD borderColor=#cccccc width="21%"><FONT

size=3>#$$Impact$$#</FONT></TD>
<TD borderColor=#cccccc width="14%"><B><FONT
size=3>Status</FONT></B></TD>
<TD borderColor=#cccccc width="37%"><FONT
size=3>#$$Status$$#</FONT></TD></TR>
<TR>
<TD width="17%"><B><FONT size=3>Category</FONT></B></TD>
<TD width="21%"><FONT size=3>#$$Category$$#</FONT></TD>
<TD width="14%"><B><FONT size=3>Type</FONT></B></TD>
<TD width="37%"><FONT size=3>#$$Type$$#</FONT></TD></TR>
<TR>
<TD width="17%"><B><FONT size=3>Item</FONT></B></TD>
<TD width="21%"><FONT size=3>#$$Item$$#</FONT></TD>
<TD width="14%"><B><FONT size=3>Assigned To</FONT></B></TD>
<TD width="37%"><FONT size=3>#$$Assigned To$$#</FONT></TD></TR>
<TR>
<TD borderColor=#cccccc colSpan=5>
<HR>
<FONT size=3></FONT></TD></TR></TBODY></TABLE></TD></TR></TBODY></
TABLE><B><FONT
color=#008000 size=3></FONT></B></BODY></HTML>

Email status template in HTML format

For the email engine to include a Status Template in the reply email—for
example, to format the reply if there is an error—enter the Status Template
label/value pair as a global declaration in the body of your email, as in the
following extract:
Schema: HD Incident
Server: polycarp
Status Template: Status Default
Login: Demo
Password:
....

The Status Template must likewise be stored in the AR System Email

Template form.
When you send your email, the BMC Remedy Email Engine parses and
executes the instructions in the content template. If there is an error, the
resulting status email will be formatted like Figure A-4. The email engine
substitutes values for the variables.

Email status template in HTML format  273

BMC Remedy Action Request System 7.0

Figure A-4: Reply with status template

For more information about status templates, see “Status Template label” on
page 198.

274
Appendix A—Examples of email templates

 Administering BMC Remedy Email Engine

Adding a header template and a footer template

For the email engine to include a Header Template (or Footer Template) in
the reply email, enter the Header Template label/value pair as a global
declaration in the body of your email, as in the following extract:
Schema: HD Incident
Server: polycarp
Result Template: Result Template
Header Template: Default Header
Footer Template: Default Footer
...

The resulting email including the header template will be formatted like
Figure A-5.

Figure A-5: Reply with header 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.

Adding a header template and a footer template  275

BMC Remedy Action Request System 7.0

In each case, the templates must be stored in the AR System Email Templates
form before they can be used in the email. For more information, see
“Storing templates in the AR System Email Templates form” on page 209. If
graphics are included, and these are not contained in the HTML file, the
graphics must also be added using the Template Attachments tab of the
AR System Email Templates form. For more information, see “Adding
attachments to HTML templates” on page 211.
For more information, see “Header Template and Footer Template labels”
on page 198.

276
Appendix A—Examples of email templates

Appendix

B Email engine installation

worksheets

This appendix contains installation worksheets for UNIX and Windows. The
worksheets include both basic installation and configuration information.
Use a separate worksheet for each email engine.
The following topics are provided:

UNIX—Installation and configuration worksheets (page 278)

Windows—Installation and configuration worksheets (page 282)

Email engine installation worksheets  277

BMC Remedy Action Request System 7.0

UNIX—Installation and configuration worksheets

This section includes worksheets for installing and configuring the email
engine on UNIX. You might need to obtain some of the configuration
information from your email server system administrator.

UNIX—Installation worksheet
Print this sheet for each of the email engines you are installing. Fill out your
values ahead of time and use your values in conjunction with the installation
instructions.

Required Description Your value

information
Installation Path to the directory where the email engine
directory CD-ROM is mounted and where the ed_install file is
located.
Note: Upgrades or overwrites only: Make sure that the default
path is the path to your existing installation.
Java installation Path to the Java root directory, which contains the
directory /bin and /jre directories.
Default path: /usr/java<version>/
<root_directory_location>

AR Server name Name of the AR System server that the email engine
connects to.
Note: For multiple AR System servers on the same machine: To
maintain the correct dependency relationship between the
email engine and its dedicated AR System server, enter the
AR System server that connects to the email engine you are
installing.
Port number TCP port number for the AR System server that the email
engine connects to.
Do not enter a value if the server you specified uses a
portmapper.
Note: You must specify a port number if the email engine and
AR System server are on opposite sides of a firewall.

278
Appendix B—Email engine installation worksheets

 Administering BMC Remedy Email Engine

Required Description Your value

information
RPC port RPC port number for the AR System server that the email
number engine connects to.
Do not enter a value if the server you specified uses a
portmapper.
AR System Name of the user that has administrator privileges for the
administrator AR System server. This user must have permissions to import
user name and manage forms, and to set values in the ar.conf file.
AR System Password for the AR System administrator user.
administrator
password
Application Password associated with some applications, such as
Service Flashboards. To set the password, choose File > Server
password Information and click the Connection Settings tab.

UNIX—Configuration worksheet
Print this sheet for each of the email engines you are installing. Fill out your
values before you install according to the type of email protocol you are using
(for example, MAPI or POP3) and the type of mailbox you are configuring
(incoming or outgoing). Use your values in conjunction with the
configuration instructions during installation.
If you configure your incoming and outgoing mailboxes during installation,
your email engine will be able to send and receive email immediately because
the values are stored in the AR System Email Mailbox Configuration form.
You can modify these values after you complete the installation.

UNIX—Incoming mailbox
Use this worksheet to record your values for the incoming mailbox.

Incoming mailbox Description Your value

information
MBOX
Name Descriptive incoming mailbox name (for example,
ARSystemEmail-Incoming).

UNIX—Installation and configuration worksheets  279

BMC Remedy Action Request System 7.0

Incoming mailbox Description Your value

information
Server Name Name of the email server that the email engine
connects to.
Note: For multiple AR System servers on the same
machine: To maintain the correct dependency
relationship between the email engine and its
dedicated AR System server, enter the AR System
server that connects to the email engine you are
installing.
Server Type Type of email protocol that the server uses. MBOX
Incoming Mailbox Full path to the incoming mailbox for the user
Path account.
For example: /usr/spool/mail/ARSystems
Check the /etc/aliases file to confirm that the
path you enter is the correct path. Or run the
following command:
/usr/lib/sendmail -bv -v [mailbox_username]

Incoming User Home Full path of the user account home directory.
Path For example: /usr/ARSystem
POP3 or IMAP4
Mailbox Name Descriptive incoming mailbox name (for example,
ARSystemEmail-Incoming).
Server Type Type of email protocol that the server uses. POP3 or IMAP4
SSL Secure Socket Layer option enabled.
Server Name/IP Name or IP address of your company’s email
server.
Note: For multiple AR System servers on the same
machine: To maintain the correct dependency
relationship between the email engine and its
dedicated AR System server, enter the AR System
server that connects to the email engine you are
installing.

280
Appendix B—Email engine installation worksheets

 Administering BMC Remedy Email Engine

Incoming mailbox Description Your value

information
Server Port Port number for your company’s email server.
Default values:

POP3: 110

POP3 with SSL: 995

IMAP4: 143

IMAP4 with SSL: 993

Server User Name of the user or administrator of the email
account. Obtain this information from your email
server administrator.
Server Passwords Password associated with the server user.

UNIX—Outgoing mailbox
Use this worksheet to record your values for the outgoing mailbox. On
UNIX, all outgoing mailboxes are configured using SMTP.

Outgoing mailbox Description Your value

information for SMTP
Mailbox Name Descriptive name (for example, ARSystemEmail-
Outgoing).

Display Name Descriptive name that appears in the From: line of

outgoing emails.
Email Address Email address of the email account owner.
Note: If your display name is ARSystem and your
emailaddressisarsystem@remedy.com,yourFrom:
line would be:
From: ARSystem [arsystem@remedy.com]

Server Name/IP Name or IP address of your company’s email

server.
Server Port Port number for your company’s email server.
Default values are:

SMTP: 25

SMTP with SSL enabled: 465

UNIX—Installation and configuration worksheets  281

BMC Remedy Action Request System 7.0

Outgoing mailbox Description Your value

information for SMTP
Server User Name of the user or administrator of the email
account.
Server Password Password associated with the server user.

Windows—Installation and configuration worksheets

This section includes worksheets for installing and configuring the email
engine on Windows. You might need to obtain some of the configuration
information from your email server system administrator.

Windows—Installation worksheet
Print this sheet for each of the email engines you are installing. Fill out your
values ahead of time and use your values in conjunction with the installation
instructions. The information about this worksheet begins after the
Welcome and software license agreement screens are displayed during
installation.

Required information Description Your value

Installation directory Path to the directory where you plan to install the
email engine.
AR Server Name Name of the AR System server that the email engine
connects to.
Note: For multiple AR System servers on the same
machine: To maintain the correct dependency
relationship between the email engine and its
dedicated AR System server, enter the AR System
server that connects to the email engine you are
installing.
Port Number TCP port number for the AR System server that the
email engine connects to.
Do not enter a value if the server uses a portmapper.
RPC Port Number RPC port number for the AR System server that the
email engine connects to.
Do not enter a value if the server uses a portmapper.

282
Appendix B—Email engine installation worksheets

 Administering BMC Remedy Email Engine

Required information Description Your value

AR System Name of the user who has administrator privileges
Administrator User for the AR System server. This user must have
Name permissions to import and manage forms, and to set
values in the ar.cfg file.
AR System Password of the AR System administrator user.
Administrator Password
Application Service Password associated with some applications, such as
Password Flashboards. To set the password, choose File >
Server Information and click the Connection
Settings tab.

Windows—Configuration worksheet
Print this sheet for each of the email engines you are installing. Fill out your
values ahead of time according to the type of email protocol you are using
(for example, MAPI or POP3) and the type of mailbox you are configuring
(incoming or outgoing). Use your values in conjunction with the
configuration instructions during the installation.
If you configure your incoming and outgoing mailboxes during installation,
your email engine will be able to send and receive email immediately.

Windows—Incoming mailbox
Use this worksheet to record your values for the incoming mailbox.

Incoming mailbox Description Your value

information
MAPI
Mailbox Name Descriptive name (for example, ARSystemEmail-
Incoming).
Server Type MAPI server. MAPI
Email Profile Name of the MS Exchange profile you created in
the preinstallation section in Chapter 2, “BMC
Remedy Email Engine installation and setup.”
POP3 or IMAP4
Mailbox Name Descriptive name (for example, ARSystemEmail-
Incoming).

Windows—Installation and configuration worksheets  283

BMC Remedy Action Request System 7.0

Incoming mailbox Description Your value

information
Server Type POP3 or IMPAP4 server.
SSL Secure Socket Layer option enabled.
Server Name/IP Name or IP address of your company’s email
server.
Server Port Port number for your company’s email server.
Server User Name of the user or administrator of the email
account.
Server Passwords Password associated with the server user.

Windows—Outgoing mailbox
Use this worksheet to record your values for the outgoing mailbox.

Outgoing mailbox Description Your value

information
MAPI
Mailbox Name Descriptive name (for example, ARSystemEmail-
Outgoing).

Display Name Descriptive name that appears in the From: line of

outgoing emails.
Email Address Email address of the email account owner.
Note: If your display name is ARSystem and your
emailaddressisarsystem@remedy.com,yourFrom:
line would be:
From: ARSystem [arsystem@remedy.com]
Server Type Type of server protocol. MAPI
Profile Name of the MS Exchange profile you created in
the preinstallation section in Chapter 2, “BMC
Remedy Email Engine installation and setup.”
SMTP
Mailbox Name Descriptive name (for example, ARSystemEmail-
Outgoing).

Display Name Descriptive name that appears in the From: line of

outgoing emails.

284
Appendix B—Email engine installation worksheets

 Administering BMC Remedy Email Engine

Outgoing mailbox Description Your value

information
Email Address Email address of the email account owner
Note: If your display name is ARSystem and your
emailaddressisarsystem@remedy.com,yourFrom:
line would be:
From: ARSystem [arsystem@remedy.com]

Server Type Type of server protocol. SMTP

SSL Secure Socket Layer option enabled.
Server Name/IP Name or IP address of your company’s email
server.
Server Port Port number for your company’s email server. Port
used for connecting to the server where this
mailbox is stored.
Default values are:

SMTP: 25

SMTP with SSL enabled: 465
Server User Name of the user or administrator of the email
account. Obtain this information from your email
server administrator.
Server Password Password associated with the server user.

Windows—Installation and configuration worksheets  285

BMC Remedy Action Request System 7.0

Windows—MAPI logon settings

If you chose MAPI for incoming mailboxes, use this worksheet to record
your logon settings.

Logon settings Description Your value

Windows NT user Name of the domain user who has access to the
Exchange profile mailbox. This user also has
domain permissions to start the email engine as a
service.
Password Password corresponding to the Windows user.
Windows NT Domain Name of the Windows domain you created in the
preinstallation section of Chapter 2, “BMC
Remedy Email Engine installation and setup.”

286
Appendix B—Email engine installation worksheets

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.

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  287

BMC Remedy Action Request System 7.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 might be different for
your platform. In particular, the path to your mail folder might be different
from /usr/spool/mail/.

Note: On some UNIX platforms, you need to run the newaliases command to
have the ARSystem aliases recognized. See 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 they are 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

288
Appendix 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 BMC Remedy Mail Server and their equivalents (if
available) in the 7.0 email engine.

Upgrading email option parameters  289

BMC Remedy Action Request System 7.0

Email engine update parameters

Pre-5.1 email options Function 6.0 (or greater) email engine
equivalent
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
“Overview—Sending incoming
email with user instructions” on
page 216.
Note: The value that is set in the
user instruction template will
not be overwritten by the
incoming email.
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.

290
Appendix D—Upgrading email option parameters

 Administering BMC Remedy Email Engine

Pre-5.1 email options Function 6.0 (or greater) email engine

equivalent
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
“Overview—Sending incoming
email with user instructions” on
page 216.
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.
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.

Email engine update parameters  291

BMC Remedy Action Request System 7.0

Pre-5.1 email options Function 6.0 (or greater) email engine

equivalent
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,
perform one of the following tasks:

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).SetReply-Failureto
Discard if /dev/null does not work for
your system.

For Windows, set the address to Discard.

292
Appendix D—Upgrading email option parameters

 Administering BMC Remedy Email Engine

Pre-5.1 email options Function 6.0 (or greater) email engine

equivalent
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, perform one of the following
tasks:

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 “MAPI—Saving outgoing
that AR System sends. Valid values for this notifications” on page 75 and
option are T and F. The default value is F (do “Performance and configuration
not save sent items). settings” on page 236.
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 “Upgrades
name of the domain in which the Exchange from the BMC Remedy Email
account resides. Do not modify this Engine” on page 31.
parameter.

Email engine update parameters  293

BMC Remedy Action Request System 7.0

Pre-5.1 email options Function 6.0 (or greater) email engine

equivalent
ExchangeNTAccount Windows only: Used during installation. The For information, see “Upgrades
name of the Exchange mail server account. from the BMC Remedy Email
Do not modify this parameter. Engine” on page 31.
ExchangeNTPassword Windows only: Used during installation. The For information, see “Upgrades
encrypted password for the Exchange from the BMC Remedy Email
account. Do not modify this parameter. Engine” on page 31.
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.

294
Appendix D—Upgrading email option parameters

 Administering BMC Remedy Email Engine

Pre-5.1 email options Function 6.0 (or greater) email engine

equivalent
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.propertiesfile.Ifyou
on the identified socket, an error is returned, want to define an RPC socket in a
and the program does not run. template, see “Using label/value
pairs in templates” on page 191.

Email engine update parameters  295

BMC Remedy Action Request System 7.0

Pre-5.1 email options Function 6.0 (or greater) email engine

equivalent
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 the inbox path is not set, then the
and Solaris) or /var/spool/mail (IBM). mail environment variable is
used.

296
Appendix D—Upgrading email option parameters

Appendix

E BMC Remedy Email Engine

forms

The BMC 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.
The following topics are provided:

Email engine administration forms (page 298)

Email engine user forms (page 307)

Email engine workflow forms (page 311)

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. To prevent
these forms from being imported by default when the AR System server is
restarted, go to the ar.conf (ar.cfg) file and set the option Email-
Import-Form-By-Default to F. For more information, see “Configuring
SSL for the email engine” on page 76.

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.

BMC Remedy Email Engine forms  297

BMC Remedy Action Request System 7.0

Email engine administration forms

This section describes the following administration forms that are available
with the email engine:

AR System Email Mailbox Configuration

AR System Email Templates

AR System Email User Instruction Templates

AR System Email Error Logs

AR System Email Security

AR System Email Mailbox Configuration

Use the AR System Email Mailbox Configuration form to create mailboxes
and specify their use. For each 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 “Configuring outgoing mailboxes” on page 53
and “Configuring incoming mailboxes” on page 59.

Incoming mailbox—Basic and Advanced Configuration

tabs
Field name Description
Mailbox Name Enter the name of the incoming mailbox.
Mailbox Function Select whether mailbox is Incoming or Outgoing.
Status Select Enabled to activate the mailbox. Select Disabled to
keep the mailbox disabled.
Email Server Type Select the email protocol. Incoming mailboxes include
following protocols:

POP3

IMAP4

MBOX

MAPI

298
Appendix E—BMC Remedy Email Engine forms

 Administering BMC Remedy Email Engine

Field name Description

Polling Interval Enter the number of minutes after which the email engine
(Minutes) will check for incoming mail from the mail server for this
mailbox.
Email Server Enables the secure socket layer. Used only with POP3 and
Requires SSL IMAP4.
Inbox Path Enter the full path file name to the mbox file corresponding to
the user email account that will be used. Used only with
MBOX.
Email Server Name/ Enter the name or IP address of the mail server used in your
IP organization. Used only with POP3 and IMAP4.
Email Server Port Enter 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. Used only
with POP3 and IMAP4.
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
Email Server User Enter the user name of the administrator or user for this
email account. Used only with POP3 and IMAP4.
Email Server Enter the user name of the administrator or user for this
Password email account. Used only with POP3 and IMAP4.
Profile Name Enter the name of the MS Exchange profile to be used for
incoming mailbox. Used only with MAPI.
Associated Mailbox Enter the name of an outgoing mailbox used to reply to
Name incoming emails that require a response.
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.
Use Original Select Yes to enable the system to use only the parsing
Template Format mechanism used in the original parsing system (pre-5.1
Remedy Mail Server) and thus ignore special HTML fields
and XML formats.

Email engine administration forms  299

BMC Remedy Action Request System 7.0

Field name Description

Reply With Result Select Yes to enable the results of an Action to be included
with an email reply, or select No if results should not be
included.
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.
Enable Modify Select Yes to enable modify actions, or No to prevent modify
Actions actions from being performed.
Default Workflow Enter the name of the form upon which the email engine will
Form execute instructions found within the incoming email
message if no specific form is specified in the email message.
Force Default Select Yes if the Default Workflow Form should be used
Workflow Form regardless of what was specified in an incoming email. This
action will confine all instructions received by this mailbox to
the specified form.
Use Security Key Select Yes to force a security key to be used for incoming mail
to this mailbox.
Use Supplied User Select Yes to use AR System server login information that
Information might be included within the incoming email message.
Use Email From Select Yes to use the email address of the sender as a form of
Address authentication.

Outgoing mailbox—Basic and Advanced Configuration

tabs
Field name Description
Mailbox Name Enter the name of the outgoing mailbox.
Mailbox Function Select whether mailbox is Incoming or Outgoing.
Status Select Enabled to activate the mailbox. Select Disabled to
keep the mailbox disabled.
Email Server Type Select the email protocol. Outgoing mailboxes include the
following protocols:

SMTP

MAPI

300
Appendix E—BMC Remedy Email Engine forms

 Administering BMC Remedy Email Engine

Field name Description

Polling Interval Enter the number of minutes after which the email engine
(Minutes) will check for new outgoing mail waiting to be sent from this
mailbox.
Email Server Enables the secure socket layer. Used only with SMTP.
Requires SSL
Email Server Name/ Enter the name or IP address of the mail server used in your
IP organization. Used only with SMTP.
Email Server Port Enter 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. Used only
with SMTP.
If you do not enter a port number, the following default
values will be used:

SMTP: 25

SMTP with SSL: 465
Email Server User Enter the user name of the administrator or user for this
email account. Used only with SMTP.
Email Server Enter the user name of the administrator or user for this
Password email account. Used only with SMTP.
Profile Name Enter the name of the MS Exchange profile to be used for the
outgoing mailbox. Used only with MAPI.
Associated Mailbox Enter the name of the incoming mailbox that will be used to
Name receive instructions or notifications.
Default Outgoing Select Yes so that all outgoing messages for which an
Mailbox outgoing mailbox is not specified will be sent using
information in this entry.
Display Name Enter the name you want displayed in the From line of the
outgoing email.
Email Address Enter the full email address of the administrator or owner of
this mailbox.
Reply To Address Enter the 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.
Organization For email clients that display an organization name, enter the
name of the mailbox owner, or administrator’s organization.

Email engine administration forms  301

BMC Remedy Action Request System 7.0

Field name Description

Delete Outgoing Select Yes to have outgoing notification messages deleted
Notification from the AR System Email Messages form after they have
Messages been sent from this mailbox.
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.
Default To Enter the default email addresses for those who should
receive outgoing messages from this mailbox.
Default CC Enter the default email addresses for those who should
receive copies of outgoing messages from this mailbox.
Default BCC Enter the default email addresses for those who should
receive blind copies of outgoing messages from this mailbox.
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.
Header Template Enter the template to be used as the default header template.
Footer Template Enter the template to be used as the default footer template.
Status Template Enter the template to be used as the default status template.
Result Template Enter the template to be used as the default result template.

AR System Email Templates form

Use the AR System Email Templates form to create, display, and modify
templates applied to 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
and a name and description for the template; the language encoding used;
and information about attachments associated with this template.
If you want graphic elements to appear in 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.

302
Appendix E—BMC Remedy Email Engine forms

 Administering BMC Remedy Email Engine

For more information, see “Storing templates in the AR System Email

Templates form” on page 209.

Field name Description

Template Format Choose the format of template, either Text or HTML.
Encoding Choose the language setting used to read and parse the
contents of templates. If no setting is specified, the default
encoding of the local system is employed.
Template Name Enter the name of the email template.
The contents of the Template Name field are automatically
populated if you attach a new file, then click inside the field.
You can edit the name as needed.
After saving your template, the AR System Email Templates
form uses data-driven workflow to populate menus in the
email engine forms that use templates, for example, when
you add an email template to a Notify action.
Description (Optional)
File Name Select the template files from the Attachment field. Includes
size and label information.
Add Attachment Click to open the AR System Email Attachments form in New
button mode. Lets you select and add an attachment (for example,
(HTML templates HTML file or bitmap) that is always used with a specific
only) template.

Modify Attachment Click to open the AR System Email Attachments form in

button Search mode so you can modify an attachment. The template
(HTML templates will not be available for use until the email engine cache is
only) updated.

Delete Attachment Click to delete the attachment from AR System Email

button Attachments form.
(HTML templates
only)

Email engine administration forms  303

BMC Remedy Action Request System 7.0

Field name Description

Refresh Table Click to refresh the table after you have added, modified, or
button deleted an attachment.
(HTML templates
only)
Add Existing menu Adds an existing attachment to the template.
(HTML templates
only)

AR System Email User Instruction Templates form

Use the AR System Email Templates form to store administrator-defined
instructions for 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 “Overview—Sending incoming email with user
instructions” on page 216.

Field name Description

Instruction System-generated unique ID. The contents of this field are
Template ID read-only.
Template Name Menu lets you select template that is executed as the content
of user instruction and used in the email.
Mailbox Name Menu lets you associate incoming mailbox used with user
instruction.
Instruction Valid character string consisting of Action label and value
used to access user instruction field.

304
Appendix E—BMC Remedy Email Engine forms

 Administering BMC Remedy Email Engine

AR System Email Error Logs form

Use the AR System Email Error Logs form to store logs of errors that have
occurred during 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
the 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 229.

Field name Description

Log Message ID and Message ID and date on which error was created.
Create Date
Mailbox ID Number of the message to which the log applies.
Number
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 might require administrator intervention. This is the
default value.
Warning: Errors that can cause problems when executing a
task.
Info: Status information.
Config: Information related to mailbox configuration. For
configuration information, see “Configuring outgoing
mailboxes” on page 53 and “Configuring incoming
mailboxes” on page 59.
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 Error number associated with the message.
Generated By Error generated either by the email engine or by the
AR System server.
Message Text Description of the error.

Email engine administration forms  305

BMC Remedy Action Request System 7.0

AR System Email Security

Use the AR System Email Security form to either create and enable or disable
security keys for incoming mail. A security key can be assigned to an
individual incoming mailbox, or to all incoming mailboxes.
For more information, see “Configuring incoming mailbox security” on
page 69.

Field name Description

Security ID System-generated unique ID. The contents of this field are
read-only.
Status Menu that lets you activate the key. Select Disabled to keep
the key disabled.
Key Name of key consisting of a set of alphanumeric characters.
You can use almost any combination of letters and numbers
for a security key.
User Name Name of a valid AR System user to whom the security key
should apply.
Force for Mailbox Enables the security key for this mailbox only. Select No to
enable the key for all mailboxes in your email environment.
Mailbox Name Name of the Incoming Mailbox to which you want this
security key applied.
Force from Email Key required for mail received from specific email accounts.
Addresses If you select Yes, the Email Address field becomes enabled.
Email Addresses Option that verifies incoming messages from a set of specific
email accounts using a security key.
Expiration Date 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 Description for the key, such as why it was created or
instructions for modifying or deleting it.

306
Appendix E—BMC Remedy Email Engine forms

 Administering BMC Remedy Email Engine

Email engine user forms

This section describes the user forms available with the email engine:

AR System Email Messages

AR System Email Attachments

AR System Email Attachment Join

AR System Email Messages form

Use the AR System Email Messages form to store information for outgoing
and incoming 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 HTML, plain text format, or a combination of both); and (under
a separate tab) a list of any attachments included with the message.
For information about using the Email Messages form to troubleshoot traffic
between incoming and outgoing email, see Chapter 4, “Outgoing email.”

Field name Description

Mailbox Name Name of configured mailbox.
Mailbox Type Select whether mailbox is Incoming or Outgoing.
Display Advanced Select Yes to display the advanced options available for
Options viewing email information and errors.

Message tab
Field name Description
From: Name of the mailbox the email is sent from.
Reply To: 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.
Organization: For email clients that display an organization name, the name
of the mailbox owner, or administrator’s organization.

Email engine user forms  307

BMC Remedy Action Request System 7.0

Field name Description

To: Email addresses for those who should receive outgoing
messages from this mailbox.
CC: Email addresses for those who should receive copies of
outgoing messages from this mailbox.
BCC: Email addresses for those who should receive blind copies of
outgoing messages from this mailbox.
Subject: Subject line for your email.
Priority: Value to use in the email message to get the desired MS
Outlook priority. Numbers from 1 to 100 are acceptable.

Attachments tab
Field name Description
Add Attachment Includes attachment with outgoing email.
Modify Attachment Lets you modify attachment or attachment name.
Delete Attachment Removes attachment from outgoing email.
Refresh Table Refreshes table after you have added, modified, or deleted an
attachment.
Add Existing Includes previously saved attachment with outgoing email.

Advanced Options tab—Templates, Variable

Replacements, and Attachment Alternatives tab
Field name Description
Header Template Template to be used as the header template.
Content Template Template to be used as the content template.
Footer Template Template to be used as the footer template.
Field Values Value for a variable in the template.
AR System Server With qualification variables, name of the server on which the
form resides.
AR System Server With qualification variables, any access information
TCP Port necessary.

308
Appendix E—BMC Remedy Email Engine forms

 Administering BMC Remedy Email Engine

Field name Description

AR System Server With qualification variables, any access information
RPC Number necessary.
AR System Form With qualification variables, name of the AR System form to
which these values apply.
Qualification Query used to retrieve data and substitute it in the email.
Attachment Attachment pool enables you to add the content of your
Alternatives email as a plain text, HTML, or RTF attachment, instead of
(attachment pool) typing it into the Body field in the Message tab.
Plain Text Content Language encoding used.
Attachment
Encoding
HTML Content Language encoding used.
Attachment
Encoding
RTF Content Language encoding used.
Attachment
Encoding
Values Attachment Language encoding used.
Encoding

Message Information tab

Field name Description
Message ID and Message ID and date on which error was created.
Date Received
Execute/Send At Number of the message to which the log applies.

Email engine user forms  309

BMC Remedy Action Request System 7.0

Field name Description

Parse Message Indicates if incoming message was parsed. Options are:

No

Yes

Error

Parsed & Executed
Send Message Indicates if outgoing message was sent. Options are:

No

Yes

Error

Sent

Error Sending-Retrying

Errors tab
Field name Description
Log Message Type Enables users to view error messages if their email is not sent
(attachment pool) correctly. If a request fails to submit, the original message is
returned.
Log Message Text If a request fails to submit, the error message that indicates
the reason for the failure is returned.

AR System Email Attachments form

Use the AR System Email Attachments form to create, display, and modify
information about 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
file name, size, and label.

310
Appendix E—BMC Remedy Email Engine forms

 Administering BMC Remedy Email Engine

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.

Field name Description

Type Email or Template attachment.
Used for storing attachments for both incoming and
outgoing emails. It also stores attachments for templates,
such as a graphic for an HTML template.
Attachment Name Name of attachment.
File Name Enables users to view error messages if their email was not
(attachment pool) sent correctly.

AR System Email Attachment Join form

The BMC Remedy Email Engine uses the AR System Email Attachment Join
form for mapping 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.

Email engine workflow forms

This section describes the workflow forms available with the email engine.

AR System Email Instructions

AR System Email Instruction Parameters

AR System Email Association

AR System Email Instructions form

The BMC Remedy Email Engine uses the AR System Email Instructions form
to store instructions obtained when incoming email is parsed.

WARNING: Because this information is used internally by the email engine,

you should not create or modify entries in this form.

Email engine workflow forms  311

BMC Remedy Action Request System 7.0

AR System Email Instruction Parameters form

The BMC Remedy Email Engine uses the AR System Email Instruction
Parameters form to store parameters specified for administrator-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 Association form

The BMC Remedy Email Engine uses the AR System Email Association form
to store associations between an email message and 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 make sure 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.

312
Appendix E—BMC Remedy Email Engine forms

Index

A AR System
Action label 194 API errors 231
actions installing 33
definition 17 sending an email to 143
modify 195 stopping and starting, troubleshooting 259
query 195 AR System Email
examples 264 Association form 312
submit 194 Attachment Join form 311
user-defined 196 Attachments form
Add Shortcut, including ARTask attachments 91 description 310
adding attachments HTML templates 212
alternative 124 outgoing email 115
HTML templates 213 use 310
outgoing 116 Error Logs form
adding templates accessing 230
to Email Templates form 210 description 305
to outgoing email 118 using 229
advanced configuration Instruction Parameters form 311, 312
incoming mailbox 61 Instructions form 311
outgoing mailbox 56 Mailbox Configuration form 298, 302
advanced email solutions, overview 21 Messages form
advanced options advanced options 178
incoming email 178 browser, displaying in 110
outgoing email 117 description 307
advanced search bar, qualification label 197 troubleshooting, used with 226
appearance of email, improving 22 using 307
application service passwords variable replacements 108
determining invalid 253 Security form 306
removing invalid 254 Templates form for storing templates 209
startup parameters 235 User Instruction Templates form 304
AR System Email Engine. See email engine

Index  313
BMC Remedy Action Request System 7.0

architecture of email engine 227 C

ARTask attachments, including in notifications 91 certification authorities (CA)
Association form, description 312 article describing CA procedures 77
association, email 311, 312 configuring 76
Attachment Alternatives tab, using 124 check buttons, HTML 202
Attachment Join form 311 client
attachments email 144
adding modifying entries 154
alternative 124 submitting entries 150
description 310 configuration
outgoing email 116 advanced
previously saved 213 incoming mailbox 61
to email 310 outgoing mailbox 56
deleting email notifications, deleting
Email Templates form 214 automatically 104
outgoing email 116 email security 69
exporting templates with, to another EmailDaemon.properties file 237
server 215 form entry interval time, changing 76
maximum size, setting 239 incoming mailboxes 59
modifying security 69
Email Templates form 214 Mailbox Configuration form 298
outgoing email 116 modify actions 73
outgoing email, including 114 outgoing mailboxes 53
submissions, including with incoming security 71
email 154 overview 52
templates 211 performance 76
Attachments form Remedy Mail Server configuration
description 310 parameters, using in email engine 290
HTML templates 212 reply with results 72
outgoing email 115 retrieval time, changing form entry 76
use 310 SSL 76
Authentication label 193 TCP port 34
testing 65
B troubleshooting mailbox 259
basic format, templates 200 UNIX
BMC Remedy Administrator incoming mailbox, during installation 45
invalid passwords, removing 254 installation, during 45
templates, exporting mail 188 outgoing mailbox, during installation 46
BMC Remedy Email Engine. See email engine Windows
BMC Remedy Mail Server incoming mailbox, during installation 36
configuration parameters 290 installation, during 35
original template format, using 63 outgoing mailbox, during installation 38
upgrading to 6.x email engine console output used in troubleshooting 250
UNIX 31
Windows 30

314
Index
 Administering BMC Remedy Email Engine

content templates email (continued)

description 185 client (continued)
HTML outgoing 107 entries, submitting 150
outgoing email, HTML 137 queries, sending 144
XML outgoing 107 deleting an attachment 116
creating digital signatures 76
instruction templates 219 forms list
templates AR System Email Association 312
additional tips 209 AR System Email Attachment Join 311
using Remedy Administrator 188 AR System Email Attachments 115, 212,
user instructions 218, 220 310
workflow to modify requests 167 AR System Email Error Logs 305
AR System Email Instruction
D Parameters 311, 312
data-driven workflow, using 97 AR System Email Instructions 311
date formats in email templates 206 AR System Email Mailbox
debugging Configuration 298
See also troubleshooting AR System Email Messages 108, 120, 307
-Dmail.debug=true batch files 242 AR System Email Security 306
options in logging.properties file 231 AR System Email Templates 210
sample debug log AR System Email User Instruction
MBOX 248 Templates 304
SMTP 247 improving appearance 22
Windows 243 modifying an attachment 116
UNIX email engine 245 notifications, deleting automatically 104
Windows email engine 242 priority in sending 90, 111
default workflow form 64 querying AR System 144
digital signatures 76 receiving 14
direct access URLs, using in notifications 89 request processing, troubleshooting 261
displaying date, time, or numeric values, sending 14
in notifications 104 sending to the AR System 143
-Dmail.debug=true debug option special forms 297
UNIX 245 templates. See templates
Windows 242 user forms 307
domains warning, not using in notifications 90 workflow forms 311
email account, definition 16
E email engine
email administering (Webcast) 87
account, definition 16 architecture 227
adding saved attachments 116 definition 14
administration forms 298 email association 312
client email attachments 310
AR System 144 email instruction parameters 311, 312
entries, modifying 154 email messages 307
errors 231

Index  315
BMC Remedy Action Request System 7.0

email engine (continued) errors (continued)

forms 297 logs 229
heap size, defining 252 outgoing email 125
installation escalations. See workflow
UNIX 41 examples, copying and pasting into mail client 145
Windows 32 expiration date, security key 306
mail server, relation to 18 exporting email templates
modify actions, configuring 73 description 188
overview 14 outgoing workflow 169
Remedy Mail Server configuration
parameters 290 F
sample scenario 18 failures, transmission or instruction 230
security 306 fields
starting 47 notifications, defining in 91
startup parameters 235 order in notifications 92
stopping 47 files
templates 304 EmailDaemon.properties 233
terminology 16 logging.properties 231
threads 227 filters. See workflow
UNIX footer templates 198, 275
starting 48 description 186
stopping 48 HTML 186
Windows label 198
starting 48 Form label 192
stopping 48 Format label 196
Email Messages form. See AR System Email incoming email, using with 153
Message form formats, template
EmailDaemon.properties file basic 200
configuring 237 HTML 201
invalid passwords, removing 255 label and values 200
performance and configuration 237 variables 201
updating 235 XML 201
using 233 forms
Entry ID label 200 administration forms 298
environment variables, setting default workflow 64
UNIX 31 entry interval times, changing 76
Windows 27 importing by default 297
Error Logs form sample for modify actions 168
described 305 system-generated forms 297
overview 229 user forms 307
troubleshooting email engine 229 workflow forms 311
errors forms list
AR System API 231 AR System Email Association 311, 312
incoming email 181 AR System Email Attachment Join 311
internal email engine 231

316
Index
 Administering BMC Remedy Email Engine

forms list (continued) HTML (continued)

AR System Email Attachments outgoing email, sending 111
description 310 radio buttons 202
HTML templates 212 references and examples 112
outgoing email 115 result template sample code 271
AR System Email Error Logs 305 result templates 186
AR System Email Instruction Parameters 311, status templates 186
312 templates 201
AR System Email Instructions 311 text fields 202
AR System Email Mailbox Configuration 298,
302 I
AR System Email Messages 307 ID label 199
description 307 IMAP4
overview 108 definition 15
variable replacements 120 incoming mailbox, configuring 60
AR System Email Security 306 Microsoft Exchange Server and 261
AR System Email Templates 210 importing forms by default 297
AR System Email User Instruction incoming email
Templates 304 advanced options 178
attachments 154
G Format label, with queries 149
global fields and variables 205 Format label, with submits 153
global parameter declarations in templates 203 modifying entries 154
glossary 16 overview 143
qualifications, including 148
H sample scenario 142
header templates sending queries 144
description 186 submitting entries 150
HTML 186 syntax for label/value pairs 144
HTML banners in outgoing email 129 templates 185
label 198 templates, using 177
reply template, adding to 275 user instructions, sending 222
using 198 user-defined instructions 216
heap size, defining for email engine 252 using 143
HTML workflow triggered 144
check buttons 202 incoming mailboxes, configuring
field types, allowable 201 See also incoming email, mailboxes
format email, using to 147 advanced 61
format of templates 201 description 59
header templates 186 IMAP4 60
input controls 113 MAPI 60
menu fields 202 MBOX 61
modify instructions, sending 161 POP3 60
notifications, sending from workflow 85 security 69
outgoing content templates 107

Index  317
BMC Remedy Action Request System 7.0

incoming mailboxes, configuring (continued) J

testing 67 Java
UNIX during installation 45 components required for installation 26
Windows during installation 36 correct version needed for installation 253
incoming mailboxes, definition 17 JRE directory 32
installation
See also preinstallation K
components 26 Key label 199
documentation, reviewing 26 key terms describing email engine 16
email engine keywords
UNIX 41 content templates for outgoing emails in
Windows 32 notifications, using in 99
Java, correct version needed 253 submissions 153
MAPI
logon settings, entering 39 L
mailbox, changing login information 49 label aliases
preparation 27 Encryption and Encryption Key 199
MBOX preparation 27 Entry ID, EntryID, and RequestID 200
preinstallation Footer and Footer Template 198
steps 26 Header and Header Template 198
UNIX tasks 31 Query and Search 197
Windows tasks 27 Result and Result Template 197
setup 25 RPC Number 193
SSL 27 Schema 192
UNIX 41 Status and Status Template 198
basic information, entering 42 TCP 193
completing 47 User, User Name, Name, and Login
configuration information, entering 45 Name 193
environment variables, setting 31 label/value pairs
Windows 32 See also templates
basic information, entering 33 definition 191
completing 40 format, templates 200
configuration information, entering 35 syntax
environment variables, setting 27 Action label 194
worksheet, using 26 format 200
instruction or transmission failures 230 same as templates 144
Instruction Parameters form 311, 312 sending email 108
instructions labels
definition 17 Action 194
modify, sending (HTML) 161 Authentication 193
modify, sending (plain text) 157 Footer Template 198
Instructions form 311 Form 192
internal email engine errors 231 Format 196
Internet Message Access Protocol. See IMAP4 incoming queries 149
interval time, changing form entry 76 incoming submits 153

318
Index
 Administering BMC Remedy Email Engine

labels (continued) mailboxes (continued)

Header Template 198 configuration
Instruction 194 troubleshooting 259
Key 199 configuration overview 52
Language 194 creating 53
Login 193 definition 16
Modify 157 polling interval 60, 239
!Name/ID! 199 See also incoming mailboxes
Password 193 UNIX AR System mailbox, setting up 287
Qualification 197 outgoing mailboxes
incoming email, using with 148 MAPI
Query 144 definition 15
Request ID 200 email engine login information, changing after
Result Template 197 installation 49
RPC 193 incoming mailbox, configuring 60
Server 192 logon settings, entering 39
Status Template 198 outgoing mailbox, configuring 54
Submit outgoing notifications, saving 75
incoming email 150 preparation steps for installation 27
TCP Port 193 transport problems
variables, substituting with 205 UNIX, fixing 258
Language label 194 Windows, fixing 257
local parameter declarations in templates 203 upgrading 27
local system accounts for email engine service 249 MBOX
logging definition 15
AR System Email Error Logs form 229 incoming mailbox, configuring 61
debugging 231 preparation steps for installation 30
errors 229 sample debug log 248
logging.properties file 231 mechanism, used for notifications 90
message information 125, 180 menu fields, HTML 202
severity levels 305 Message Information tab
system status 229 status information for incoming email 180
troubleshooting problems 250 status information for outgoing email 125
Login label 193 messages
AR System Email Messages form 307
M content, determining 125
mail server notifications, used in 94
definition 16 overview 85
email engine, relation to 18 Messages form
troubleshooting 256 description 307
Mailbox Configuration form 298 outgoing email overview 108
mailboxes variable replacement 120
changing configuration 65 Messages tab, notifications 93
Messaging Application Programming. See MAPI
MIME (Multipurpose Internet Mail Exchange) 15

Index  319
BMC Remedy Action Request System 7.0

modify actions notifications (continued)

action label 195 HTML, using 85
additional restrictions 165 keywords, using in content templates for
constraints 165 outgoing email 99
email engine, configuring 73 mechanism 90
enabling 63 Messages tab, using 93
entries, using incoming email 154 messages, defining 94
HTML, using 161 permissions 92, 96
instructions, sending (HTML) 161 processing 14
instructions, sending (plain text) 157 replying 171
Modify label, incoming email 157 saving (MAPI) 75
plain text, using 157 subject lines 91
querying entries 174 submit execute condition with join forms 86
replying 160 templates
sample form, creating 168 definition 96
sample scenario 155 order used 99
searching entries 174 tab, using 93
modify key 195 text 89, 169
Multipurpose Internet Mail Exchange. See MIME user name 89
variable, using 205
N
Name label 199 O
non-root installations with UNIX 31 outgoing email
Notes advanced options 117
displaying HTML in mail clients 128 attachment alternatives 124
Java version, correct version needed for errors 125
installation 253 messages 125
notifications, creating with join forms using templates 117
Submit execute condition 86 variable replacements 119
Password field, do not modify 195 AR System Email Messages form 108
queries and optimizing performance 126 attachments, including 114
style sheets linked to HTML not dynamically assigning templates 99
supported 211 field value, replacing 120
notes HTML, sending in 111
restricted use of keywords in content message content, determining 125
templates 99 plain text, sending in 109
notifications professional appearance 126
ARTask attachments, including 91 result templates, using 131
deleting automatically 104 sample scenario 82
direct access URLs 89 syntax for label/value pairs 108
displaying date, time, or numeric values 104 template types 185
field order 92 templates, creating 105
fields, defining 91 troubleshooting 226
filter workflow, creating 168 using header templates as banners 129
groups, not using 90 using HTML content templates 137

320
Index
 Administering BMC Remedy Email Engine

outgoing email (continued) polling interval

using status templates 138 minutes, configuring 60
XML templates 135 seconds, configuring 239
outgoing mailboxes, configuring POP3
See also mailboxes definition 15
advanced 56 incoming mailbox, configuring 60
description 53 Microsoft Exchange Server and 261
MAPI 54 Post Office Protocol. See POP3
security 71 postinstallation
SMTP 55 UNIX, stopping and starting email engine 48
testing 65 Windows, stopping and starting email
UNIX during installation 46 engine 48
Windows during installation 38 preinstallation
outgoing mailboxes, definition 17 See also installation
overviews MAPI and MBOX 27
advanced email solutions 21 MAPI preparation steps 27
configuration 52 MBOX preparation steps 30
email engine 14 non-root user issues 31
incoming email 143 Remedy mail server upgrade
modify instructions with incoming email 155 UNIX 31
templates 184 Windows 30
workflow to modify requests, using 166 upgrading UNIX from email engine 5.1 or
5.1.1 31
P priority of emails sent 90, 111
parameters processing notifications 14
email instruction 311, 312 professional looking email 126
startup 235 protocols
templates 203 IMAP4 15, 261
Password label 193 MAPI 15
passwords MBOX 15
application service, specifying 235 POP3 15, 261
identifying invalid 253 SMTP 15, 261
removing invalid 254
performance Q
EmailDaemon.properties 237 Qualification label 197
queries, optimizing 126 qualifications
retrieval time, changing form entry 76 incoming email, including 148
permissions label/value pairs syntax 148
notifications 92, 96 short hand syntax 149
verifying for Windows account 260 templates, adding to 175
plain text testing 148
modify instructions, sending 157 query action
outgoing email, sending 109 description 195
incoming email 144
label 144

Index  321
BMC Remedy Action Request System 7.0

query action (continued) sending email

modifying entry 174 email engine, using 14
performance 126 incoming email, using 143
using 264 Server label 192
servers
R stopping and starting AR System 259
radio buttons in HTML format 202 wrong server specified 255
receiving email 14 services
replying local system account with email engine 249
configuring email engine 72 troubleshooting 260
modify actions, not changing 161 shorthand qualifications 149
modify instructions 160 Simple Mail Transfer Protocol. See SMTP
notifications 171 Sm@rtCert client 33
Request ID label 200 SMTP
requests, submitting across time zones 260 configuring during installation 46
restrictions when modifying entries 165 definition 15
result templates gateway 261
description 186 outgoing mailbox 55
HTML 186 sample debug log 247
label 197 SSL
outgoing email, using with 131 See also security
sample HTML 271 certification authorities (CA), configuring 76
RPC Number label 193 configuring 76
installation 27
S starting and stopping email engine
sample scenarios server, stopping and starting 259
email engine 18 startup parameters 235
incoming email 142 troubleshooting 253
modify actions 155 UNIX 47
outgoing email 82 Windows 47
user instructions 216 status information
search. See query reserved variables 208
Secure Sockets Layer. See SSL templates 208
security status messages
See also SSL incoming email 180
article describing certification authority 77 outgoing email 125
certification authorities (CA) 76 status templates
configuring 69 description 186
email 306 example 273
keys 70 formatting email 152
modify actions 73, 168 HTML 186
security key label 198
expiration date 306 outgoing email, HTML 138
Security form 306 subject lines in notifications 91

322
Index
 Administering BMC Remedy Email Engine

submit actions templates (continued)

action label 194 formats (continued)
notifications with join forms 86 labels and values 200
Submit label, incoming email 150 variables 201
submitting requests across time zones 260 XML 201
submitting Header 198, 275
email in filter workflow 170 incoming email 177, 185
entries, using incoming email 150 instruction 216
keywords 153 creating 219
syntax labels and values 191
formats of label/value pairs 200 formats 200
incoming email label/value pairs 144 misleading use of term 184
outgoing email label/value pairs 108 modifying 209
qualifications 148 notifications, used in 96
shorthand qualification syntax 149 order used in notifications 99
template label/value pairs 194 outgoing email 185
system status logs 229 using 105
system-generated forms 297 outgoing email, used with 119
overview 184
T parameters 203
TCP port qualifications, adding to 175
configuring 34 requests with, searching 266
label 193 reserved variables 207
templates Result 197
See also label/value pairs Status 198
adding 210 example 273
AR System Email Templates form 209 storing 209, 302
attachments 211 user instructions 219
modifying 214 syntax for label/value pairs 194
Content 119 testing 219
creating 185, 188, 209 tips 209
data-driven workflow, using to set 97 types of 185
date formats 206 User-Defined Instruction 187, 216
definition 184 using after an upgrade 215
deleting attachments 214 variables 203
dynamic assignment for outgoing email 99 formats 201
examples 268–269 Templates form 210
exporting 188 Templates tab
exporting with attachments to another notifications 93
server 215 using 117
fields with, searching 265 terminology 16
Footer 198, 275 text fields
formats HTML 202
basic 200 notifications 89, 169
HTML 201

Index  323
BMC Remedy Action Request System 7.0

threads, used in email engine 227 troubleshooting (continued)

time zones, submitting requests across 260 logging problems 250
tips logging.properties file, using for
copying and pasting examples into mail debugging 231
client 145 mail server 256
data-driven workflow, using 97 mailbox configuration, making changes
email engine, administering (Webcast) 87 to 259
Email Errors Log form, accessing 230 MAPI transport problems
Email Messages form in browser, UNIX, fixing 258
displaying 110 Windows, fixing 257
EmailDaemon.properties file, using 234 notify filters 261
HTML, using to format email 147 outgoing email 226
incoming email can trigger workflow 144 permissions for Windows accounts,
multi-line syntax in variables 200 verifying 260
qualifications to template, adding 175 sample debug log 243
security keys with modify actions 73, 168 starting email engine 253
status templates, using to format email 152 startup parameters 235
templates, testing 219 submitting requests across time zones 260
templates, use of term slightly misleading 184 system status logs 229
testing qualifications 148 time zones, submitting requests across 260
XML file, validating 135 transmission or instruction failures 230
transmission or instruction failures 230 wrong server specified 255
troubleshooting trusted email users 294
See also debugging
advanced options for incoming email 178 U
API errors 231 UNIX
configuration, testing 65 AR System mailbox, setting up 287
console output 250 configuration during installation 45
debugging email engine 242 debugging email engine 245
-Dmail.debug=true debug mode 242 installation 41
Email Messages, using 226 basic information, entering 42
email request processing 261 completing 47
EmailDaemon.properties file incoming mailbox, configuring during 45
performance and configuration non-root 31
settings 236 outgoing mailbox, configuring during 46
using 233 MAPI transport problems, fixing 258
error logs 229 notifications from server 86
failures, transmission or instruction 230 preinstallation tasks 31
fixing common problems 248 starting email engine 48
internal errors 231 stopping email engine 48
invalid application service passwords upgrading from email engine 5.1 or 5.1.1 31
determining 253 upgrading
removing 254 email engine 5.1 or 5.1.1, from 31
MAPI issues 27

324
Index
 Administering BMC Remedy Email Engine

upgrading (continued) W
old templates, using 215 warnings
original template format, using from Remedy domain names, not using 90
Mail Server 63 group notifications, not using 90
URLs, direct access in notifications 89 internal information should not be
User Instruction Templates form 304 modified 311, 312
user instructions modify actions, not changing during reply 161
creating 220 multiple AR System servers 34, 43
incoming email, sending 222 Windows
results 222 accounts, verifying permissions 260
sample scenario 216 AR System, installing 33
variables, using 224 debugging email engine 242
user name field, in notifications 89 installation
User-Defined Instruction templates basic information, entering 33
actions, user-defined 187 completing 40
definition 187 configuration during 35
overview 216 description 32
sample scenario 216 incoming mailbox, configuring during 36
user-defined actions 196 outgoing mailbox, configuring during 38
users MAPI transport problems, fixing 257
modify actions, using security keys 73, 168 notifications from server 86
trusted email 294 preinstallation tasks 27
services, troubleshooting 260
V software, loading for installation 32
values starting email engine 48
definition 191 stopping email engine 48
field, replacing in outgoing email 120 workflow
format, templates 200 data-driven
variables 203 templates, dynamically assigning 99
Variable Replacement tab templates, setting 97
AR System Email Messages form 119 default form 64
using 119 dynamically assigning templates to outgoing
variables email 99
field values and qualifications, using with 205 messages in notifications, using 94
formats 201 modify requests, creating to 167
multi-line syntax 200 notifications, defining in 86
notifications, using in 205 notify action in filter 168
reserved 207 overview, using to modify requests 166
templates with incoming email 177 templates in notifications, using 96
templates, used in 203 triggered by incoming email 144
user instructions, using with 224 troubleshooting 261
UNIX servers 86
Windows servers 86
worksheet, preinstallation 26

Index  325
BMC Remedy Action Request System 7.0

X
XML
file, validating 135
format of templates 201
outgoing content templates 107
templates 201
templates, using with outgoing email 135

326
Index
*58475*
*58475*
*58475*
*58475*
*58475*