Email Engine 700

BMC Remedy Action Request System 7.
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 OverviewHow the email engine works . . . . . . . . . . . . . . . . . 18 OverviewImproving 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 WindowsPreinstallation tasks . . . . . . . . . . . . . . . . . . . 27 UNIXPreinstallation tasks . . . . . . . . . . . . . . . . . . . . . 31 WindowsInstalling the email engine . . . . . . . . . . . . . . . . . 32 Loading the software . . . . . . . . . . . . . . . . . . . . . . . . 32 Installing the email engine . . . . . . . . . . . . . . . . . . . . . . 33
Contents
BMC Remedy Action Request System 7.0
UNIXInstalling 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

OverviewEmail 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 . . . . . . . . . . . . 73 Configuring the email engine for replying with results . . . . . . . . . . 72 Configuring the email engine for modify actions MAPISaving outgoing notifications . . . . . . . . . . . . . . . . . . 75 Changing the form entry interval time . . . . . . . . . . . . . . . . . . 76 Configuring SSL for the email engine . . . . . . . . . . . . . . . . . . 76
Chapter 4
Outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . 81
OverviewHow 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
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 Determining message content of outgoing email . . . . . . . . . . . 117 . . . . . . . . . . . 125
Sending reply emailGiving 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

OverviewHow 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 OverviewHow modify instructions work with incoming email . . . . . 155 Sending modify instructions in plain text Additional restrictions . . . . . . . . . . . . . . 157 Sending modify instructions in HTML . . . . . . . . . . . . . . . . 161 . . . . . . . . . . . . . . . . . . . . . . 165 OverviewUsing workflow to modify requests . . . . . . . . . . . . . . 166 Searching for an entry to modifyAdvanced solution . . . . . . . . . . . 174 Using variables with templates . . . . . . . . . . . . . . . . . . . . . 177 Displaying advanced options for incoming email . . . . . . . . . . . . . 178 Message Information tab. . . . . . . . . . . . . . . . . . . . . . 180 Errors tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Contents
Chapter 6
Using email templates . . . . . . . . . . . . . . . . . . . . . 183

OverviewEmail 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 OverviewSending 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
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 WindowsDebugging the email engine . . . . . . . . . . . . . . . 242 UNIXDebugging 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
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

UNIXInstallation and configuration worksheets . . . . . . . . . . . . 278 UNIXInstallation worksheet . . . . . . . . . . . . . . . . . . . 278 UNIXConfiguration worksheet . . . . . . . . . . . . . . . . . . 279 WindowsInstallation and configuration worksheets . . . . . . . . . . . 282 WindowsInstallation worksheet . . . . . . . . . . . . . . . . . . 282 WindowsConfiguration worksheet . . . . . . . . . . . . . . . . 283
Appendix C Appendix D
Setting up UNIX mailboxes . . . . . . . . . . . . . . . . . . . 287 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
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 products Help menu or by clicking on Help links.
Title Concepts Description Audience
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. Procedures for installing AR System. Administrators
Installing 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. Describes components necessary to build applications in Developers AR System, including applications, fields, forms, and views. Contains all of the workflow information. Contains information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data. Developers Administrators
Form and Application Objects
Workflow Objects Configuring
Installing and Administering BMC Remedy Mid Tier Integrating with Plug-ins and Third-Party Products Optimizing and Troubleshooting
Contains information about the mid tier, including mid Administrators tier installation and configuration, and web server configuration. Discusses integrating AR System with external systems using plug-ins and other products, including LDAP, OLE, and ARDBC. Administrators /Developers
Server administration topics and technical essays related Administrators to monitoring and maintaining AR System for the purpose of optimizing performance and troubleshooting problems.
10 Preface
Title Database Reference
Description
Audience
Database administration topics and rules related to how Administrators AR System interacts with specific databases; includes an overview of the data dictionary tables. Server administration and procedures for implementing Administrators a distributed AR System server environment with the BMC Remedy Distributed Server Option (DSO). Flashboards administration and procedures for creating Administrators and modifying flashboards and flashboards components /Programmers to display and monitor AR System information. Information about AR System data structures, C API function calls, and OLE support. Quick reference to C API function calls. Information about Java classes, methods, and variables that integrate with AR System. Procedures for installing, configuring, and using the BMC Remedy Email Engine. List and expanded descriptions of AR System error messages. Combined index of all books. Information about new features list, compatibility lists, international issues, and open and fixed issues. Procedures for using BMC Remedy User. Procedures for using BMC Remedy Import. Procedures for creating and modifying an AR System application for tracking data and processes. Procedures for using BMC Remedy Alert. Administrators /Programmers Administrators /Programmers Administrators /Programmers Administrators Administrators /Programmers Everyone Everyone Everyone Administrators Administrators Everyone
Administering BMC Remedy DSO Administering BMC Remedy Flashboards C API Reference C API Quick Reference Java API 1 Administering BMC Remedy Email Engine Error Messages Master Index Release Notes BMC Remedy User Help BMC Remedy Import Help BMC Remedy Administrator Help BMC Remedy Alert Help BMC Remedy Mid Tier Configuration Tool Help
1.
Procedures for configuring the BMC Remedy Mid Tier. Administrators
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
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. Its free!
How do you access the Developer Community?

Go to supportweb.remedy.com, and click the Developer Community link.
12 Preface
Chapter
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) OverviewHow the email engine works (page 18) OverviewImproving the appearance of your email (page 21)
Overview of the BMC Remedy Email Engine
13
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 mailThe 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 mailYou 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 notificationsIf 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 1Overview of the 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) MBOXA 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 informationincluding errors, incoming emails, and outgoing emailsis 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
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 thirdparty 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.
Incoming mailbox
Mailbox containing the information required by the email 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
Mailbox containing the information required by the email 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
OverviewHow 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
AR System Server HD Incident

AR System Email Mailbox Configuration Form
Field 1 Field 2 Field 3
Underlying Database
6.3 Email Engine
Printer Broken
Abcd ef ghijkl mno
1
Email Engine AR System admin installs and configures email engine
Query
4 5
Server queries ticket on HD Incident form and returns results
instructions translated into API calls to server
Incoming Mailbox
Outgoing Mailbox
3
Email engine parses query instructions
POP3 IMAP4 MBOX MAPI SMTP MAPI
Outgoing email is formatted and assembled
Mail Server
Email account 1
Email account 2 Users log in to mail server to receive new email
7 2
Query email sent to incoming mailbox
Shelly
Katie
Mark
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 easyto-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 Shellys 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.
OverviewHow the email engine works
19
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.
OverviewImproving 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 System Server Server executes filter workflow that triggers Notify action. Urgent header template is dynamically assigned. Database
Email Templates
Field 1 Field 2 Field 3 Abcdefg Hijklm Nopqrst
Template Components
6.3 Email Engine
2
Email engine parses instructions. Instructions then translated into API calls to server.
6.3 Email Engine
Abcdefg Hijklm Nopqrst
Incoming Mailbox
Outgoing Mailbox
4
Email Engine
Outgoing email is assembled according to formatting instructions: HTML header template HTML result template Field values returned from server
Mail Server
Email account 1
Email account 2
Schema: HD Incident Action: Impact: Submit Urgent
Urgent email sent to incoming mailbox.
Urgent email sent to Francie Frontline
Shelly
Francie Frontline
21
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 cant 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 tickets impact. The templates are designed so that users can quickly tell if a tickets 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.
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.
23
Chapter
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) WindowsInstalling the email engine (page 32) UNIXInstalling the email engine (page 41) Postinstallation steps (page 47)
BMC Remedy Email Engine installation and setup
25
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 Specific information about open issues, localization, and other information for Version 7.0 Most current product compatibility information Where Action Request System 7.0 Release Notes:
http:// supportweb.remedy.com
Comments Before you can access the release notes, you must log in to the Customer Support Website. Before you can access the compatibility matrix, you must log in to the Customer Support Website.
Product Compatibility Matrix:

http:// supportweb.remedy.com
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 2BMC Remedy Email Engine installation and setup
WindowsPreinstallation 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 WindowsInstalling 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.
27
Note: You must be a Windows domain administrator or MS Exchange administrator to perform these steps.
What Install components MS Exchange server
Where
Comments
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 user account. At one of the following locations: On the same domain as the email engine. On a domain with appropriate trust relationships. Enter the name of this user in the WindowsConfiguration worksheet at: WindowsIncoming mailbox: Server User WindowsMAPI logon settings: Windows NT User Group membership: Local administrators group (active directories only). Domain membership: Email engine domain or Exchange Server domain
Assign group and domain membership to the domain user account.
At one of the following locations: On the same domain as the email engine. On a domain with appropriate trust relationships.
What Grant the domain user advanced rights.
Where
Comments
On the computer where you plan to install 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 WindowsConfiguration 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.
29
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 information ExchangeNTAccount Mapping equivalent in the email engine 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.
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.
UNIXPreinstallation 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.
31
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.
WindowsInstalling 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.
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.
33
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 NameName 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 NumberTCP 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 NumberRPC 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.
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).
35
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
2 MAPI only:
Enter the following information in the fields:

a Mailbox NameEnter a descriptive mailbox name.
Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming.
b Server TypeSelect MAPI from the menu. c Email ProfileEnter the name of the MS Exchange profile you created in
the WindowsPreinstallation 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 NameEnter a mailbox name.
b Server TypeSelect POP3 or IMAP4. c SSLCheck the box to enable Secure Socket Layer (SSL). d Server Name/IPEnter the name or IP address of your companys mail
server.
e Server PortEnter the mail server port number. f Server UserEnter the name of the user of the email account. g Server PasswordEnter 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.
37
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 NameEnter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Outgoing. Display NameEnter a descriptive name that appears in the From: line of outgoing emails. Email AddressEnter 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 TypeSelect MAPI from the menu. ProfileEnter 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 NameEnter a descriptive name for your outgoing mailbox. For example, enter AREmail - Outgoing. Display NameEnter a descriptive name that appears in the From: line of outgoing emails. Email AddressEnter 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:
Server TypeSelect SMTP from the menu. SSLCheck the box to use Secure Socket Layer (SSL), if applicable. Server Name/IPEnter the name or IP address of your companys mail server. Server PortEnter the mail server port number (default is 25). Server UserEnter the name of the user of the email account (null if not applicable). Server PasswordEnter 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
39

a Windows NT UserEnter the name of the Windows domain user that
you created in the WindowsPreinstallation 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 PasswordEnter the password corresponding to the Windows NT User. c Windows NT DomainEnter 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.
UNIXInstalling the email engine

After you have completed the steps in the section UNIXPreinstallation 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.
41
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.
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.
43
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.
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 NameEnter a mailbox name.
b Server TypeSelect POP3 or IMAP4. c SSLCheck the box to enable Secure Socket Layer (SSL). d Server Name/IPEnter the name or IP address of your companys mail
server.
e Server PortEnter the mail server port number (default is 110). f Server UserEnter the name of the user or administrator of the email
account.
g Server PasswordEnter 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.
45
2 MBOX only: a NameEnter a mailbox name.
b Server nameEnter the name of the server that will connect to the email
engine.
c Server TypeSelect m for MBOX. d Incoming Mailbox PathEnter 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 PathEnter 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

a Mailbox NameEnter a descriptive name for your outgoing mailbox. For
example: AREmail - Outgoing.

b Display NameEnter a descriptive name that appears in the From: line of
outgoing emails.
c Email AddressEnter 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:
d Server Name/IPEnter the name or IP address of your companys mail
server.
e Server PortEnter the mail server port number (default is 25). f Server UserEnter the name of the user or administrator of the email
account (null if not applicable).

g Server PasswordEnter 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.
47
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 serveryou must restart the engine manually.
UNIXStarting 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:
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
WindowsStarting and stopping the email engine

Use the following instructions to start and stop the email engine on Windows.
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.
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.
49
Chapter
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: OverviewEmail configuration (page 52) Configuring outgoing mailboxes (page 53) Configuring incoming mailboxes (page 59) Testing your mailbox configuration (page 65) Configuring email security (page 69) MAPISaving 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
OverviewEmail 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 3Configuring mailboxes in the 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.
53
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 NameEnter a descriptive mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Outgoing. Mailbox FunctionSelect Outgoing. StatusSelect Enabled to enable the options.
b Enter the following information in the Basic Configuration tab:
Server TypeSelect MAPI from the menu. Polling IntervalSelect a polling interval for the email engine to check for new incoming email from the mail server. Profile NameEnter 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.
c Click Save. 2 SMTP only: a Enter the following information in the fields above the tabs:
Mailbox NameEnter a descriptive mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Outgoing. Mailbox FunctionSelect Outgoing. StatusSelect Enabled to enable the options.
Server TypeSelect SMTP from the menu. Polling IntervalSelect a polling interval for the email engine to check for new incoming email from the mail server. SSLCheck the box to enable Secure Socket Layer (SSL). For more information, see Configuring SSL for the email engine on page 76. Server Name/IPEnter the name or IP address of your companys mail server. Server PortEnter the mail server port number, or click Set Default Email Server Port to accept the default port. Server UserEnter the name of the user of the email account. The email engine uses this email account to authenticate requests for outgoing messages Server PasswordEnter 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.
55
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.
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 NameEnter 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 MailboxSelect 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 NameEnter a descriptive name that appears in the From: line of
outgoing emails. MAPI only: This option is not used.

d Email AddressEnter 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:
MAPI only: This option is not used.

e Reply To AddressSpecify 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 OrganizationEnter the name of the organization or company if your
email client displays your organizations name.
57
g Delete Outgoing Notification MessagesSelect 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 ToEnter all email addresses that should receive outgoing
messages from this mailbox if no other email address is specified in the message.
b Default CCEnter 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 BCCEnter 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 TemplateSelect or enter a default header template if no other
header template is specified.

b Footer TemplateSelect or enter a default footer template to be used if no
other footer template is specified.

c Status TemplateSelect or enter a default status template to be used if no
other status template is specified.

d Result TemplateSelect 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
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
59
To create a basic configuration for your incoming mailbox

1 MAPI only: a Enter the following information in the fields above the tabs:
Mailbox NameEnter a descriptive mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming. Mailbox FunctionSelect Incoming. StatusSelect Enabled to enable the options.
Email Server TypeSelect MAPI from the menu. Polling IntervalSelect a polling interval for the email engine to check for new incoming email from the mail server. Profile NameEnter 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 NameEnter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming. Mailbox FunctionSelect Incoming. StatusSelect Enabled to enable the options.
Server TypeSelect POP3 or IMAP4. Polling IntervalSelect a polling interval for the email engine to check for new incoming email from the mail server. SSLCheck the box to enable Secure Socket Layer (SSL). For more information, see Configuring SSL for the email engine on page 76.
Server Name/IPEnter the name or IP address of your companys mail server. Server PortEnter the mail server port number. Server UserEnter the name of the user of the email account. Server PasswordEnter the password corresponding to the server user.
3 MBOX only: a Enter the following information in the fields above the tabs:
Mailbox NameEnter a mailbox name. Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming. Mailbox FunctionSelect Incoming. StatusSelect Enabled to enable the options. Server TypeSelect MBOX. Polling IntervalSelect a polling interval for the email engine to check for new incoming email from the mail server. Inbox PathEnter 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.
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.
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.
2 Complete the Action Configuration section: a Email ActionSelect 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 ResultSelect 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 EntrySelect 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 ActionsSelect Yes to enable the email engine to modify
existing entries.
63
f Default Workflow FormEnter 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 FormSelect 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 KeySelect 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 InformationSelect 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.
c Use Email From AddressSelect 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 senders email address is different from the email address stored in the AR System User form.
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 NameSelect the name of the outgoing mailbox to test. b Message TypeSelect Outgoing. c Message TabEnter 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 TabEnter a subject line and body content.
65
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.
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.
67
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.
Configuring email security

Incoming and outgoing emails use different security mechanisms. Incoming email messages use security keys, the users login and password, or the users 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 users 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.
69
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 StatusSelect Enabled to activate the key. b KeyEnter 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.
c User NameEnter the name of a valid AR System user to which the
security key applies.

d Force for MailboxSelect 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 NameEnter the name of the incoming mailbox that the
security key applies to.

f Force from Email AddressesSelect 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 AddressesEnter the email addresses that the security key should
apply to, if you enabled the Force from Email Addresses key.
h ExpiresSelect Yes if you want the key to expire on a specific date. If you
select Yes, the Expiration Date field becomes enabled.

i Expiration DateEnter 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 DescriptionEnter 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.
71
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.
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.
73
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 entrys 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.
15 Save your changes.
Figure 3-10 shows Francie Frontlines security key in the AR System Email Security form.
Figure 3-10: User in AR System Email Security form
Set security key
MAPISaving 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.
MAPISaving outgoing notifications
75
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.
<folder_name>
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 Microsofts 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.
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.
77
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
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.
79
Chapter
Outgoing email
This chapter provides information and instructions for creating and transmitting outgoing email messages from the email engine. The following topics are provided: OverviewHow 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 emailGiving a professional look to outgoing email (page 126)
Outgoing email
81
OverviewHow 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 Field 2 Field 3 Abcdefg Hijklm Nopqrst
AR System admin defines SLA
Server executes escalation workflow that triggers Notify action
Email messages
Outgoing records
To: From: Message:
Abcdefg Hijklm Nopqrstuvwxyz 1234567890
Email Engine
Outgoing Mailbox
3
Mail Server
Outgoing email is formatted and assembled
Email account
User receives urgent ticket assigned to him
Bob Backline
82 Chapter 4Outgoing email
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 Bobs 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
OverviewHow outgoing email works
83
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: NotificationsThe 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 sendersThe 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 emailGiving a professional look to outgoing email on page 126. Messages formYou 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.
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
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 fieldsprovided the user being notified has the appropriate permission for those fields Attachmentsif an attachment field exists on the form Shortcutif 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 contentsthese 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).
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 tabsFields, Messages, and Templatesthat 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, see http://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
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
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
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 users 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.
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 46.
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
The options are:

None All Selected Changed None of the fields is included with the notification. All of the fields in the request are included with the notification. Selected fields from the fields list are included with the notification. 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 forms 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.
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 boxMessages 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.
You can use the following entries in the fields: AR System user logins AR System groups Direct email addressesInclude the email domain name if you are entering a users 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
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 emails 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$ )).
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 boxTemplates 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 fields 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$$#
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 forms 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
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 incidents impact is urgent, high, medium, or low. The following table shows which header template to use for an incident based on the impact:
Impact Urgent High Medium Low Template Name
Header_Urgent.htm Header_High.htm Header_Medium.htm 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)
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 usedLow, 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 createdone 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
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.
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
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.
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 emailGiving a professional look to outgoing email on page 126.
Using notifications
105
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: KeywordsKeyword 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 IDsField 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$$#

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"> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> <meta name="ProgId" content="FrontPage.Editor.Document">
Using notifications
107

<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
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)
109
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 0 1 2 3 4 ... 100 Low importance MS Outlook Priority Normal High importance High importance Normal (default) Low importance
By default, emails are sent out from the email engine in the order they were received, not in the order of priority. But you can set properties in the EmailDaemon.properties file for the email engine to send high priority emails first and then lower priority in that order. Use the following properties: To ignore priority (default):
com.remedy.arsys.emaildaemon.SortMessages=false
To use the priority:

com.remedy.arsys.emaildaemon.SortMessages=true
For more information 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.
111
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.
The email engine generates the email in Figure 4-18.
Administering BMC Remedy Email Engine Figure 4-18: Outgoing email (HTML format)
This outgoing email contains the following HTML input features: Password control fieldUsers 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 fieldsUsers modify the contents of the Assigned To and Short Description fields by using text input fields. Radio buttonsUsers modify the status by selecting an input type Radio control field. They can select only one radio button option.
113
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 formAttachments tab
2 Click Add Attachment to open the AR System Email Attachments form
(Figure 4-21).
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.
115
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.
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.
117
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).
Administering BMC Remedy Email Engine Figure 4-22: AR System Email Messages formAdvanced 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.
119
BMC Remedy Action Request System 7.0 Figure 4-23: AR System Email Messages formAdvanced 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
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.
121
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 formAdvanced 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).
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.
123
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 formAdvanced 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.
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.
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.
125
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 emailGiving 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.
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.
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.
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> </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:
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.
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.
131
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.
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.
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.
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.
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.
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><font color=#006633 face="Arial, Helvetica"> <h1>Remedy/BMC Company Picnic</ h1></font></i><hr> <i><font color=#777777 face="Arial, Helvetica"><h3>Are you coming to the Remedy/BMC company picnic? <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 <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.
Configuration form.
4 UndertheAdvancedConfigurationtab,specifyRemedy_Picnic_Invite.htmlas
the content template.
137
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

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.
139
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.
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
Chapter
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: OverviewHow 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) OverviewUsing workflow to modify requests (page 166) Searching for an entry to modifyAdvanced solution (page 174) Using variables with templates (page 177) Displaying advanced options for incoming email (page 178)
Incoming email
141
OverviewHow 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
AR System admin configured incoming mailbox in email engine.
4
Server creates ticket.
Abcd ef ghijkl mno
Email Engine Incoming Mailbox
Email engine parses instructions. Instructions then translated into API calls to server.
Email account
Mail Server
2
"Printer broken!"
Submit email sent to incoming mailbox.
Joe User
142 Chapter 5Incoming email
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
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 filters 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
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
145
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).
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.
147
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"
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.
149
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.
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
151
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.
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.
153
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.
OverviewHow 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 configured email engine to allow modify entries.
Underlying
Key: 1234 Action: Modify
Database
HD Incident
6.3 Email Engine
Outgoing
Jklm Nop Qrst

Abcd ef ghijkl mno
Email Messenger Form AR System Server
Server modifies ticket.
Email engine parses modify instructions.
4
Email 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
Joe User replies to email.
Francie Frontline sends email with modify instructions.
155
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 Joes 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!: Im 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.
Step 4 The email engine receives the reply from the mail server and verifies that
Francies original email exists in the email engine (in the AR System Email Messages form) and that the senders email address is contained in the recipient field of the original email. It then parses the modify instruction in Joes 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.
157
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 keythe 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.
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).
159
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.
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 administrators email.
4 Fill in any missing parameters as neededLogin, 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 senders 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
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.
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.
The user will receive an email that looks like Figure 5-9.
Figure 5-9: Modify instruction (HTML format) sent to user
163
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 Joes 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.
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.
165
OverviewUsing 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 System Server
AR System verifies security mechanisms and modifies the request.
1
AR System admin configured incoming mailbox to accept modify actions. Created security key.
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. Reply email includes modify information: Login and password Security key Modify action keyword
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 users 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.
167
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.
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.
169
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
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
171
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.
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
173
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 modifyAdvanced 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.
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 modifyAdvanced 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 parametersLogin, 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 516.
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
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.
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.
179

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
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
181
Chapter
Using email templates
This chapter provides information and instructions for creating and using templates for outgoing and incoming email. The following topics are provided: OverviewEmail 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) OverviewSending incoming email with user instructions (page 216)
Using email templates
183
OverviewEmail 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 6Using email templates
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 templateplain 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.
185
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 62.) 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 templateHTML
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 templateHTML
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.)
Administering BMC Remedy Email Engine Figure 6-4: Status templateHTML
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.
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 OverviewSending 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.
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
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: OverwriteOverwrites the mail template of an existing file. This option is useful when you are re-exporting a template that has changed. AppendAppends the contents to an existing file. If several templates are in a single file, the mail processor will not be able to process the request.
The template is saved as a 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.
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 Form Server Login Description Name of an AR System form. Incoming Outgoing Aliases Yes No No No User User Name Name Login Password TCP Port RPC Number Password used when executing the instruction. TCP port used when logging in to the AR System server. Yes Yes No No No No TCP RPC page 193 page 193 page 193 page 193 Schema Page page 192 page 192 page 193
Server that will be affected by the Yes instruction. User name used when executing Yes the instruction.
RPC number used when logging Yes in to the AR System server.
Authentication Authentication string used when Yes logging in to the AR System server. Language Action Format Qualification Language used when logging in to the AR System server. Denotes the instruction to be executed. Specifies the format of the information. Qualification for a query-based instruction. Yes Yes Yes Yes
No No Yes No Query Search Instruction
page 194 page 194 page 196 page 197
191
Label Result Template Status Template Header Template Footer Template !Name/ID! Key Request ID
Description
Incoming Outgoing Aliases No No Result ResultTemplate Status StatusTemplate Yes Yes Yes No No Encryption Key Encryption Yes Entry ID EntryID RequestID Header HeaderTemplate No Yes Yes Footer FooterTemplate
Page page 197 page 198
The name of the template to use Yes in the reply. The name of the template to use Yes when Status Information is returned. The template to be used as the header in the reply email. The template to be used as the footer in the reply email. The database name or ID of an AR System Form Field. The key associated with a given sender or user. The Request ID of the entry on which the possible action must be executed. No
page 198 page 198 page 199 page 199 page 200
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.)
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 senders 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.
193
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 Submit Query Modify
Description Submits a new entry on a specific AR System form. This is valid within any incoming email. The syntax is Action:Submit. Searches for entries on a specific AR System form. The syntax is Action:Query. 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. An instruction defined by the administrator. The syntax is Action:<admin_defined text>.
User-Defined
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.
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$$]
195
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 OverviewUsing 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 OverviewSending 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.
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.
197
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 blockthat is, after an Action: Query label/value pairthen 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>.
!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>.
199
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.
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.
201
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.

<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$$#
203
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.
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$$#
205
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 SHORT Description 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. Longer numerical date description, for example, Jan 12, 1952. 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. Completely specified numerical date description, for example, Tuesday, April 12, 1952 AD.
MEDIUM LONG
FULL
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 informationUseful 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.
207
Status informationUsed 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. The associated appended text.
#$$ActionStatus.AppendedText$$#
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.
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.
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.
211
5 Click the Template Attachments tab.

Figure 6-9: AR System Email Templates formTemplate 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.
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.
213
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.
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
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 OverviewSending incoming email with user instructions on page 216.
OverviewSending 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.
Administering BMC Remedy Email Engine Figure 6-11: Overview for using instruction templates
User sends email with user-defined instructions.
3
Email Engine Email Server
Template associated with user instructions.
Creates user instructions.
AR Server Primary Configuration
Results.
Underlying Database
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.
OverviewSending incoming email with user instructions
217
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.
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.
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.

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.
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 entryUser 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.
221
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.
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.
223
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.
Chapter
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
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 7Troubleshooting
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 queuethat 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
The following table describes the purpose of each of the email engine modules.
Module Monitor Description and purpose Monitors the mailbox for statistical information such as when the connection dropped and the length of time the connection was down. 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 Creator Parses and executes messages in the message queue. 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 Logging Runs in a single thread with the Creator module to maximize speed and reliability. It sends formatted messages to the mail server. Logs messages, errors, and warnings to the AR System Email Errors form or local file.
Receiver
Configuration Maintains configuration information for the system specified in the AR System Mailbox Configuration form and EmailDaemon.properties file.
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
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 servereither 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
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 Global Property Handlers Definition 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= Note: On UNIX, all console output is directed to an java.util.logging.FileHandler, emaild.sh_log file under the logs subdirectory of the java.util.logging.ConsoleHandler
email installation, but file logging can also be switched on.
Global Logging Level

java.util.logging.FileHandler. LEVEL = FINER
Logging level for the file output. You can set the logging level to Finer in the Java logging.properties file to obtain every log message generated by the system. You can also use the keyword ALL, which means all logs are to be sent to the output.
Note: Use this option with care because the contents of the
AR System Email Error Logs form can become very large.

Handler Specific Properties
java.util.logging.FileHandler. pattern = %h/java%u.log
File to where logs are made. You can reference the Java documentation on this format, as it is specified by Java 1.4.x logging.
Debugging options for the BMC Remedy Email Engine
231
Setting Handler Specific Properties

java.util.logging.FileHandler .limit = 50000
Definition Maximum size of the file. If the system exceeds this length, it will create a new file. Number to start with. This is appended to the end of the file name. Use an XML formatter to format the output, or you can use java.util.logging.SimpleFormatter with console logging. Logging level for the file output.

java.util.logging.FileHandler. count = 1

java.util.logging.FileHandler. formatter = java.util.logging.XMLFormatter
Console Handler Specific Properties

java.util.logging.ConsoleHandler . level = INFO
Console Handler Specific Properties

java.util.logging.ConsoleHandler . formatter = java.util.logging.SimpleFormatte r
XML formatter for console logging.
Main Application Level

com.remedy.arsys.emaildaemon. level = INFO
Level for the entire email engine. This setting for the main application level includes the modules unless you specify 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.
Setting Module Levels

com.remedy.arsys.emaildaemon. <Module>.level= ConfigurationModule.level=FINER CreatorModule.level=FINER ExecutionModule.level=FINER ReceiverModule.level=FINER SenderModule.level=FINER MonitorModule.level=FINER
Definition Levels for application modules. You can specify the logging levels for the various modules independently from the entire email engine logging level, for only the modules you are interested in troubleshooting. These application modules allow you to combine main application and module logging. For example, if the main application level is set to INFO and you set the level for the Receiver Module to FINER, then you will see only FINER information in the log for the Receiver module. If there is no entry in the logging.properties file for a particular module, then the system defaults to the application level (that is, INFO).
Note: The level for one of the outputs must be at least FINER,
such as the ConsoleHandler, to actually see the log. Application levels

com.remedy.arsys.emaildaemon. ARSystem Handler.level = WARNING
Level for the outputs to the BMC Remedy Email Error form. You cannot disable this handler as you can with the Console and File. This level could also be overridden if the application 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 organizations 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.
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.
Updating the EmailDaemon.properties file

If your email environment changesfor example, if you need to change a server name or a TCP portthis 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
-s -p
Description Server where the email forms (and the configuration information) are located. 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.
235
BMC Remedy Action Request System 7.0 Table 7-1: Email engine startup parameters
Parameter
-t -r
Description TCP port for the server to which the email engine should connect. 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. Language to be used. (The default is C.) 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. 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. 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. MAPI sent folder where sent mail should be stored.
-l -d
-i
-m
-o
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.
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
com.remedy.arsys.emaildaemon. AdditionalMailHeaders=X-LoopDetect com.remedy.arsys.emaildaemon. ARDATE=
Definitions This setting lets you specify additional email headers. The additional email headers are to be separated by comma. This setting lets you specify the date and time format used by the 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. This setting lets you specify the time format used by the email engine for parsing date strings. MMMMM dd, yyyy is equivalent to September 21, 2003. This setting lets you specify the time format used by the email engine for parsing time strings. HH:mm:ss z is equivalent to 12:08:56 PDT. This setting lets you specify the set size of entries to return when the email engine makes a call to the AR System server. The default chunk size of entries returned is set to 100. Specifies whether you can use a comma as a separator when entering multiple addresses in the To and CC lines. By default, 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
com.remedy.arsys.emaildaemon. ARDATEONLY= com.remedy.arsys.emaildaemon. ARTIMEONLY= com.remedy.arsys.emaildaemon. ChunkSize=100 com.remedy.arsys.emaildaemon. CommaValidAddressSeparator= true
and
Cho, Rick
You would need to use semicolons to separate the addresses:

Smith, John; Cho, Rick
com.remedy.arsys.emaildaemon. Exchange-Wait-Time=1 com.remedy.arsys.emaildaemon. ExecutionModule.level=Fine
This setting specifies the amount of time the thread waits before processing the next message when there are more messages to be processed. The unit of time is milliseconds. This setting lets you add new log messages for logging instructions and instruction parameters.
237
Settings
com.remedy.arsys.emaildaemon. FetchUserGroupInfoOnDemand= false
Definitions This setting lets you specify whether to fetch the user and group information about demand as opposed to loading all users and 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. IncomingMessagesQueueSize=100
This setting lets you define message queue size. Receiver module 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. This setting lets specify the size of the cache used for storing 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. instructionCacheSize=20
com.remedy.arsys.emaildaemon. Mailboxes=
If you run multiple email engines for a single server, this setting 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.
Settings
com.remedy.arsys.emaildaemon. MailboxPollingUnitIsMinutes= true
Definitions This setting lets you change the polling interval value from minutes (as configured in the AR System Email Configuration 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. MaxAttachSize com.remedy.arsys.emaildaemon. MaxAttachSizeFileExtensions
Together, these settings let you specify the maximum size of specific attachment types that you will allow in an email message. For example, to set the maximum size of .doc, .pdf, 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. Monitor=30
This setting lets you specify the interval between checks to see if 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. This setting lets you specify the number of sender threads per 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. This setting lets you specify the size of the queue that the email daemon maintains for the outgoing mails. 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.
com.remedy.arsys.emaildaemon. NumberOfSenderThreads=1
com.remedy.arsys.emaildaemon. OutgoingMessagesQueueSize= 100
239
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. RMIPORT=1099
This setting lets you specify the port for RMI (remote method invocation). This feature is used with the EmailAdminAgent.jar file to stop, suspend, resume, or change logging to the email engine. This setting lets you keep the sent items in the Email Messages form. Set to False if you want to delete the sent items from the Email Messages form.
com.remedy.arsys.emaildaemon. SaveSentItem=True
com.remedy.arsys.emaildaemon. securityCacheSize=20
This setting lets you specify how many security keys are kept in 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. SendEmailSetSize=100 com.remedy.arsys.emaildaemon. <server_name>.Authentication com.remedy.arsys.emaildaemon. <server_name>.Interval=30
This setting lets you specify how many outgoing emails to query at a time. The default size of outgoing emails is set to 100. This setting lets you specify a string if your AR System server requires authentication information before handling requests. This setting lets you define the time interval (in minutes) to use 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. <server_name>.Language=en_US
This setting lets you specify what language to use in the email engine, for example, com.remedy.arsys.emaildaemon. <server_name>.Language=en_US. This setting lets you specify what RPC port number the AR System server uses if you have configured a private server to use with the email engine.
com.remedy.arsys.emaildaemon. <server_name>.RPC=0
Settings
com.remedy.arsys.emaildaemon. <server_name>.TCP=0
Definitions This setting lets you specify what TCP port number the AR System uses if your AR System server is not using Portmapper. This setting lets you specify the AR System server that the email engine interacts with. This setting lets you specify if messages with a higher priority setting are processed first. The default setting is false. This setting lets you store instructions and instruction 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. Servers com.remedy.arsys.emaildaemon. SortMessages=false com.remedy.arsys.emaildaemon. StoreInstructions=true
com.remedy.arsys.emaildaemon. templateCacheSize=20
This setting lets you specify how many email templates are kept 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. UseNameIfNoEmailAddress=true
This setting lets you specify how the email engine behaves when 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. UserChunkSize=5000
This setting lets you specify the number of users (records from 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.
241
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.
WindowsDebugging 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.
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]}
243

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]}

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.
UNIXDebugging 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
245
3 Edit the emaild.sh script from:

exec ${JAVA_BIN}/java -Djava.library.path=${InstallPath} -cp ${CP_PATH} com.remedy.arsys.emaildaemon.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1
To the following:
exec${JAVA_BIN}/java -Djava.library.path=${InstallPath} -Dmail.debug=true -cp ${CP_PATH} com.remedy.arsys.emaildaemon.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1
4 Stop and start the email engine.
Example of outgoing email using SMTP

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
247
Example of incoming email using MBOX

The contents of a sample debug log for incoming email follow. You can see the lock file get createdthe 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.
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.
249
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.
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
251
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.
WindowsSetting 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.
UNIXSetting 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
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.
253
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 editoron 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.
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
255
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.
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.
WindowsFixing 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.
257
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.
UNIXFixing 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.
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.
259
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.
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.
261
Appendix
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
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 AExamples of email templates
Creating email templates to search for fields

To create an email template to search for a field
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
Creating email templates to perform searches using qualifications

To create an email template to search using a qualification
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"
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

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

!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
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.
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
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> <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%"> </TD> <TD width="14%"> </TD> <TD width="37%"> </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>

<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 emailfor example, to format the reply if there is an errorenter 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.
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
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.
Appendix
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: UNIXInstallation and configuration worksheets (page 278) WindowsInstallation and configuration worksheets (page 282)
Email engine installation worksheets
277
UNIXInstallation 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.
UNIXInstallation 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 information Installation directory Description Path to the directory where the email engine CD-ROM is mounted and where the ed_install file is located.
Note: Upgrades or overwrites only: Make sure that the default
Your value
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 BEmail engine installation worksheets
Required information RPC port number
Description RPC 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.
Your value
AR System administrator user name AR System administrator password Application Service password
Name of the user that has administrator privileges for the AR System server. This user must have permissions to import and manage forms, and to set values in the ar.conf file. Password for the AR System administrator user.
Password associated with some applications, such as Flashboards. To set the password, choose File > Server Information and click the Connection Settings tab.
UNIXConfiguration 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.
UNIXIncoming mailbox
Use this worksheet to record your values for the incoming mailbox.
Incoming mailbox information MBOX Name Descriptive incoming mailbox name (for example, ARSystemEmail-Incoming). Description Your value
279
Incoming mailbox information Server Name
Description Name of the email server that the email engine connects to.
Note: For multiple AR System servers on the same
Your value
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 Incoming Mailbox Path Type of email protocol that the server uses. Full path to the incoming mailbox for the user 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]
MBOX
Incoming User Home Path POP3 or IMAP4 Mailbox Name Server Type SSL Server Name/IP
Full path of the user account home directory. For example: /usr/ARSystem
Descriptive incoming mailbox name (for example, ARSystemEmail-Incoming). Type of email protocol that the server uses. Secure Socket Layer option enabled. Name or IP address of your companys email server.
POP3 or IMAP4
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.
Incoming mailbox information Server Port
Description Port number for your companys email server. Default values:
POP3: 110 POP3
Your value
with SSL: 995 with SSL: 993
IMAP4: 143 IMAP4
Server User
Name of the user or administrator of the email account. Obtain this information from your email server administrator. Password associated with the server user.
Server Passwords
UNIXOutgoing mailbox
Use this worksheet to record your values for the outgoing mailbox. On UNIX, all outgoing mailboxes are configured using SMTP.
Outgoing mailbox information for SMTP Mailbox Name Display Name Email Address Description Descriptive name (for example, ARSystemEmailOutgoing).
Your value
Descriptive name that appears in the From: line of outgoing emails. Email address of the email account owner.
Note: If your display name is ARSystem and your
emailaddressisarsystem@remedy.com,yourFrom: line would be:

Server Name/IP Server Port
Name or IP address of your companys email server. Port number for your companys email server. Default values are: SMTP: 25 SMTP with SSL enabled: 465
281
Outgoing mailbox information for SMTP Server User Server Password
Description Name of the user or administrator of the email account. Password associated with the server user.
Your value
WindowsInstallation 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.
WindowsInstallation 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 Installation directory AR Server Name Description Path to the directory where you plan to install the email engine. Name of the AR System server that the email engine connects to.
Your value
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.
Required information AR System Administrator User Name AR System Administrator Password Application Service Password
Description Name of the user who has administrator privileges for the AR System server. This user must have permissions to import and manage forms, and to set values in the ar.cfg file. Password of the AR System administrator user. Password associated with some applications, such as Flashboards. To set the password, choose File > Server Information and click the Connection Settings tab.
Your value
WindowsConfiguration 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.
WindowsIncoming mailbox
Use this worksheet to record your values for the incoming mailbox.
Incoming mailbox information MAPI Mailbox Name Server Type Email Profile Descriptive name (for example, ARSystemEmailIncoming). MAPI server. Name of the MS Exchange profile you created in the preinstallation section in Chapter 2, BMC Remedy Email Engine installation and setup. MAPI Description Your value
POP3 or IMAP4 Mailbox Name Descriptive name (for example, ARSystemEmailIncoming).
283
Incoming mailbox information Server Type SSL Server Name/IP Server Port Server User Server Passwords
Description POP3 or IMPAP4 server. Secure Socket Layer option enabled. Name or IP address of your companys email server. Port number for your companys email server. Name of the user or administrator of the email account. Password associated with the server user.
Your value
WindowsOutgoing mailbox
Use this worksheet to record your values for the outgoing mailbox.
Outgoing mailbox information MAPI Mailbox Name Display Name Email Address Descriptive name (for example, ARSystemEmailOutgoing).
Description
Your value
Descriptive name that appears in the From: line of outgoing emails. Email address of the email account owner.

Server Type Profile
Type of server protocol. Name of the MS Exchange profile you created in the preinstallation section in Chapter 2, BMC Remedy Email Engine installation and setup.
MAPI
SMTP Mailbox Name Display Name Descriptive name (for example, ARSystemEmailOutgoing).
Descriptive name that appears in the From: line of outgoing emails.
Outgoing mailbox information Email Address
Description Email address of the email account owner

Your value

Server Type SSL Server Name/IP Server Port
Type of server protocol. Secure Socket Layer option enabled. Name or IP address of your companys email server. Port number for your companys email server. Port used for connecting to the server where this mailbox is stored. Default values are: SMTP: 25 SMTP with SSL enabled: 465
SMTP
Server User
Name of the user or administrator of the email account. Obtain this information from your email server administrator. Password associated with the server user.
Server Password
285
WindowsMAPI logon settings

If you chose MAPI for incoming mailboxes, use this worksheet to record your logon settings.
Logon settings Windows NT user Description 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 corresponding to the Windows user. Name of the Windows domain you created in the preinstallation section of Chapter 2, BMC Remedy Email Engine installation and setup. Your value
Password Windows NT Domain
Appendix
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
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 CSetting up UNIX mailboxes
Appendix
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
Email engine update parameters

Pre-5.1 email options
Address
Function The address the mail process watches for AR System messages.
6.0 (or greater) email engine equivalent MBOX: Address is defined by 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. Must be specified by using a user instruction template. For more information, see OverviewSending incoming email with user instructions on page 216.
Note: The value that is set in the
(UNIX only)
Default-Password
The AR System password to use if no password is specified in the submitted message.
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. The AR System server to use if no server is specified in the submitted message. The AR System server that the email engine connects to that is defined in the EmailDaemon.properties file.
Default-Server
290 Appendix DUpgrading email option parameters

Default-User
Function The AR System login to use if there is no login specified in the submitted message.
6.0 (or greater) email engine equivalent Must be specified by using a user instruction template. For more information, see OverviewSending 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-OriginalOn- A flag indicating whether to include the full Not used. Failure text of the original message in a reply to a
failed submission.
Include-OriginalOn- 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
(Windows only)
Indicates the full path name for the mailntfy Not used. directory that holds all of the email notifications the server sends to the armailex service. The armailex service deletes them after they are processed. The name given to the configuration of your This parameter is set in the MS Exchange clients operation. AR System Email Mailbox Configuration form in the Basic Configuration tab for MAPI Email Server Type only. The MS Exchange mailbox name referenced in your Exchange clients profile configuration (found in the MS Exchange Server properties, accessible through the Control Panel mail icon). The number of seconds to wait between polls to the mailbox to check for new messages. The minimum interval is 5 seconds. This parameter is set in the AR System Email Mailbox Configuration form outgoing mailbox in the Advanced Configuration tab for MAPI Email Server Type only. This parameter is set in the AR System Email Mailbox Configuration form in the Basic Configuration tab for each mailbox.
Exchange-Profile
(Windows only)
Exchange-Mailbox
(Windows only)
Poll-Interval
291

Query-Match-Full
Function
6.0 (or greater) email engine equivalent
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. 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. 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.
Query-Match-Short
Reply-Failure

Reply-Success
Function
Not used. The email address to use for replies to 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 accepted. If there is a Schema line in the submitted message, it must contain this form name, or the submission is rejected. If there is no Schema line, the Default- Schema setting in the configuration file must match this form name, or the submission is rejected. A flag indicating whether to save email items that AR System sends. Valid values for this option are T and F. The default value is F (do not save sent items).
If the Force Default Workflow form is set to Yes, then the Default Workflow form will be the required schema.
SaveSentItem
See MAPISaving outgoing notifications on page 75 and Performance and configuration settings on page 236.
Required-Server
This can be enforced by setting The only server for which email message the application password or by requests can be submitted. Messages are using a security key. rejected if any other server is specified. 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. Windows only: Used during installation. The For information, see Upgrades name of the domain in which the Exchange from the BMC Remedy Email Engine on page 31. account resides. Do not modify this parameter.
ExchangeNTDomain
293

ExchangeNTAccount
Function
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. 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. The sender name to use for filter-generated email notifications where no subject is specified. Only trusted email users may use this name. This field is limited to 29 characters. This is set by using the display name and email address fields on the Advanced Configuration tab in the outgoing mailbox. Not used. Not used. A flag indicating whether to check the date 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). The date and time format used by the 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. Not used.
ExchangeNTPassword
Email-Notify-From
LogoffSleep Max-Notify-Mail-LineLen UseDateCheckOnFrom
Environment ARDATE
Not used.

ARDATEONLY
Function The date format used by the 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.
6.0 (or greater) email engine equivalent Not used.
ARRPC
UNIX only: The specific RPC socket to communicate with during the run of the program. If no AR System server is running on the identified socket, an error is returned, and the program does not run.
The RPC socket that the email engine uses is defined in the EmailDaemon.properties file. If you want to define an RPC socket in a template, see Using label/value pairs in templates on page 191.
295

ARTIMEONLY
Function The time format used by the 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.
6.0 (or greater) email engine equivalent Not used.
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.
Appendix
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 EmailImport-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
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 mailboxBasic and Advanced Configuration tabs

Field name Mailbox Name Mailbox Function Status Email Server Type Description Enter the name of the incoming mailbox. Select whether mailbox is Incoming or Outgoing. Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled. Select the email protocol. Incoming mailboxes include following protocols: POP3 IMAP4 MBOX MAPI
298 Appendix EBMC Remedy Email Engine forms
Field name Polling Interval (Minutes) Email Server Requires SSL Inbox Path
Description Enter the number of minutes after which the email engine will check for incoming mail from the mail server for this mailbox. Enables the secure socket layer. Used only with POP3 and IMAP4. 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 Email Server Password Profile Name Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4. Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4. 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. Select Yes to enable the system to use only the parsing mechanism used in the original parsing system (pre-5.1 Remedy Mail Server) and thus ignore special HTML fields and XML formats.
Use Original Template Format
299
Field name Reply With Result
Description 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. Select Yes to return the complete entry of a submit or modify action. Select No to use the default single-line entry. Select Yes to enable modify actions, or No to prevent modify actions from being performed. Enter the name of the form upon which the email engine will execute instructions found within the incoming email message if no specific form is specified in the email message. Select Yes if the Default Workflow Form should be used regardless of what was specified in an incoming email. This action will confine all instructions received by this mailbox to the specified form. Select Yes to force a security key to be used for incoming mail to this mailbox. Select Yes to use AR System server login information that might be included within the incoming email message. Select Yes to use the email address of the sender as a form of authentication.
Reply With Entry Enable Modify Actions Default Workflow Form Force Default Workflow Form
Use Security Key Use Supplied User Information Use Email From Address
Outgoing mailboxBasic and Advanced Configuration tabs

Field name Mailbox Name Mailbox Function Status Email Server Type Description Enter the name of the outgoing mailbox. Select whether mailbox is Incoming or Outgoing. Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled. Select the email protocol. Outgoing mailboxes include the following protocols: SMTP MAPI
Field name Polling Interval (Minutes) Email Server Requires SSL
Description Enter the number of minutes after which the email engine will check for new outgoing mail waiting to be sent from this mailbox. Enables the secure socket layer. Used only with SMTP.
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 Email Server Password Profile Name Enter the user name of the administrator or user for this email account. Used only with SMTP. Enter the user name of the administrator or user for this email account. Used only with SMTP. 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 Mailbox Display Name Email Address Reply To Address Select Yes so that all outgoing messages for which an outgoing mailbox is not specified will be sent using information in this entry. Enter the name you want displayed in the From line of the outgoing email. Enter the full email address of the administrator or owner of this mailbox. 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. For email clients that display an organization name, enter the name of the mailbox owner, or administrators organization.
Organization
301
Field name Delete Outgoing Notification Messages Default Addressing
Description Select Yes to have outgoing notification messages deleted from the AR System Email Messages form after they have been sent from this mailbox. Enter the email addresses to send to if addresses have not been specified in the Messages tab for a notify filter or escalation. Enter the default email addresses for those who should receive outgoing messages from this mailbox. Enter the default email addresses for those who should receive copies of outgoing messages from this mailbox. Enter the default email addresses for those who should receive blind copies of outgoing messages from this mailbox. 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. Enter the template to be used as the default header template. Enter the template to be used as the default footer template. Enter the template to be used as the default status template. Enter the template to be used as the default result template.
Default To Default CC Default BCC Default Templates
Header Template Footer Template Status Template 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.
For more information, see Storing templates in the AR System Email Templates form on page 209.
Field name Template Format Encoding Description Choose the format of template, either Text or HTML. 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. 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 File Name Add Attachment button (HTML templates only) (Optional) Select the template files from the Attachment field. Includes size and label information. Click to open the AR System Email Attachments form in New mode. Lets you select and add an attachment (for example, HTML file or bitmap) that is always used with a specific template.
Template Name
Modify Attachment Click to open the AR System Email Attachments form in Search mode so you can modify an attachment. The template button (HTML templates will not be available for use until the email engine cache is updated. only) Delete Attachment button (HTML templates only) Click to delete the attachment from AR System Email Attachments form.
303
Field name Refresh Table button (HTML templates only) Add Existing menu (HTML templates only)
Description Click to refresh the table after you have added, modified, or deleted an attachment.
Adds an existing attachment to the template.
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 OverviewSending incoming email with user instructions on page 216.
Field name Instruction Template ID Template Name Mailbox Name Instruction Description System-generated unique ID. The contents of this field are read-only. Menu lets you select template that is executed as the content of user instruction and used in the email. Menu lets you associate incoming mailbox used with user instruction. Valid character string consisting of Action label and value used to access user instruction field.
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 Message Type Number of the message to which the log applies. Either an error log or a status logand 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 Generated By Message Text Error number associated with the message. Error generated either by the email engine or by the AR System server. Description of the error.
305
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 Security ID Status Key Description System-generated unique ID. The contents of this field are read-only. Menu that lets you activate the key. Select Disabled to keep the key disabled. Name of key consisting of a set of alphanumeric characters. You can use almost any combination of letters and numbers for a security key. Name of a valid AR System user to whom the security key should apply. Enables the security key for this mailbox only. Select No to enable the key for all mailboxes in your email environment. Name of the Incoming Mailbox to which you want this security key applied. Key required for mail received from specific email accounts. If you select Yes, the Email Address field becomes enabled. Option that verifies incoming messages from a set of specific email accounts using a security key. 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 for the key, such as why it was created or instructions for modifying or deleting it.
User Name Force for Mailbox Mailbox Name Force from Email Addresses Email Addresses Expiration Date
Description
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 Mailbox Name Mailbox Type Display Advanced Options Description Name of configured mailbox. Select whether mailbox is Incoming or Outgoing. Select Yes to display the advanced options available for viewing email information and errors.
Message tab
Field name From: Reply To: Description Name of the mailbox the email is sent from. 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. For email clients that display an organization name, the name of the mailbox owner, or administrators organization.
Organization:
307
Field name To: CC: BCC: Subject: Priority:
Description Email addresses for those who should receive outgoing messages from this mailbox. Email addresses for those who should receive copies of outgoing messages from this mailbox. Email addresses for those who should receive blind copies of outgoing messages from this mailbox. Subject line for your email. 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 Add Attachment Description Includes attachment with outgoing email.
Modify Attachment Lets you modify attachment or attachment name. Delete Attachment Refresh Table Add Existing Removes attachment from outgoing email. Refreshes table after you have added, modified, or deleted an attachment. Includes previously saved attachment with outgoing email.
Advanced Options tabTemplates, Variable Replacements, and Attachment Alternatives tab

Field name Header Template Content Template Footer Template Field Values AR System Server AR System Server TCP Port Description Template to be used as the header template. Template to be used as the content template. Template to be used as the footer template. Value for a variable in the template. With qualification variables, name of the server on which the form resides. With qualification variables, any access information necessary.
Field name AR System Server RPC Number AR System Form Qualification Attachment Alternatives (attachment pool) Plain Text Content Attachment Encoding HTML Content Attachment Encoding RTF Content Attachment Encoding Values Attachment Encoding
Description With qualification variables, any access information necessary. With qualification variables, name of the AR System form to which these values apply. Query used to retrieve data and substitute it in the email. Attachment pool enables you to add the content of your email as a plain text, HTML, or RTF attachment, instead of typing it into the Body field in the Message tab. Language encoding used.
Language encoding used.

Field name Message ID and Date Received Execute/Send At Description Message ID and date on which error was created. Number of the message to which the log applies.
309
Field name Parse Message
Description 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 Log Message Type (attachment pool) Log Message Text Description Enables users to view error messages if their email is not sent correctly. If a request fails to submit, the original message is returned. 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.
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 Type Description 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 File Name (attachment pool) Name of attachment. Enables users to view error messages if their email was not 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.
Email engine workflow forms
311
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.
Index
A
Action label 194 actions definition 17 modify 195 query 195 examples 264 submit 194 user-defined 196 Add Shortcut, including ARTask attachments 91 adding attachments alternative 124 HTML templates 213 outgoing 116 adding templates to Email Templates form 210 to outgoing email 118 advanced configuration incoming mailbox 61 outgoing mailbox 56 advanced email solutions, overview 21 advanced options incoming email 178 outgoing email 117 advanced search bar, qualification label 197 appearance of email, improving 22 application service passwords determining invalid 253 removing invalid 254 startup parameters 235 AR System API errors 231 installing 33 sending an email to 143 stopping and starting, troubleshooting 259 AR System Email Association form 312 Attachment Join form 311 Attachments form description 310 HTML templates 212 outgoing email 115 use 310 Error Logs form accessing 230 description 305 using 229 Instruction Parameters form 311, 312 Instructions form 311 Mailbox Configuration form 298, 302 Messages form advanced options 178 browser, displaying in 110 description 307 troubleshooting, used with 226 using 307 variable replacements 108 Security form 306 Templates form for storing templates 209 User Instruction Templates form 304 AR System Email Engine. See email engine
Index
313
architecture of email engine 227 ARTask attachments, including in notifications 91 Association form, description 312 association, email 311, 312 Attachment Alternatives tab, using 124 Attachment Join form 311 attachments adding alternative 124 description 310 outgoing email 116 previously saved 213 to email 310 deleting Email Templates form 214 outgoing email 116 exporting templates with, to another server 215 maximum size, setting 239 modifying Email Templates form 214 outgoing email 116 outgoing email, including 114 submissions, including with incoming email 154 templates 211 Attachments form description 310 HTML templates 212 outgoing email 115 use 310 Authentication label 193
C
certification authorities (CA) article describing CA procedures 77 configuring 76 check buttons, HTML 202 client email 144 modifying entries 154 submitting entries 150 configuration advanced incoming mailbox 61 outgoing mailbox 56 email notifications, deleting automatically 104 email security 69 EmailDaemon.properties file 237 form entry interval time, changing 76 incoming mailboxes 59 security 69 Mailbox Configuration form 298 modify actions 73 outgoing mailboxes 53 security 71 overview 52 performance 76 Remedy Mail Server configuration parameters, using in email engine 290 reply with results 72 retrieval time, changing form entry 76 SSL 76 TCP port 34 testing 65 troubleshooting mailbox 259 UNIX incoming mailbox, during installation 45 installation, during 45 outgoing mailbox, during installation 46 Windows incoming mailbox, during installation 36 installation, during 35 outgoing mailbox, during installation 38 console output used in troubleshooting 250
B
basic format, templates 200 BMC Remedy Administrator invalid passwords, removing 254 templates, exporting mail 188 BMC Remedy Email Engine. See email engine BMC Remedy Mail Server configuration parameters 290 original template format, using 63 upgrading to 6.x email engine UNIX 31 Windows 30
314 Index
content templates description 185 HTML outgoing 107 outgoing email, HTML 137 XML outgoing 107 creating instruction templates 219 templates additional tips 209 using Remedy Administrator 188 user instructions 218, 220 workflow to modify requests 167
D
data-driven workflow, using 97 date formats in email templates 206 debugging See also troubleshooting -Dmail.debug=true batch files 242 options in logging.properties file 231 sample debug log MBOX 248 SMTP 247 Windows 243 UNIX email engine 245 Windows email engine 242 default workflow form 64 digital signatures 76 direct access URLs, using in notifications 89 displaying date, time, or numeric values, in notifications 104 -Dmail.debug=true debug option UNIX 245 Windows 242 domains warning, not using in notifications 90
E
email account, definition 16 adding saved attachments 116 administration forms 298 client AR System 144 entries, modifying 154
email (continued) client (continued) entries, submitting 150 queries, sending 144 deleting an attachment 116 digital signatures 76 forms list AR System Email Association 312 AR System Email Attachment Join 311 AR System Email Attachments 115, 212, 310 AR System Email Error Logs 305 AR System Email Instruction Parameters 311, 312 AR System Email Instructions 311 AR System Email Mailbox Configuration 298 AR System Email Messages 108, 120, 307 AR System Email Security 306 AR System Email Templates 210 AR System Email User Instruction Templates 304 improving appearance 22 modifying an attachment 116 notifications, deleting automatically 104 priority in sending 90, 111 querying AR System 144 receiving 14 request processing, troubleshooting 261 sending 14 sending to the AR System 143 special forms 297 templates. See templates user forms 307 workflow forms 311 email account, definition 16 email engine administering (Webcast) 87 architecture 227 definition 14 email association 312 email attachments 310 email instruction parameters 311, 312 email messages 307 errors 231
Index
315
email engine (continued) forms 297 heap size, defining 252 installation UNIX 41 Windows 32 mail server, relation to 18 modify actions, configuring 73 overview 14 Remedy Mail Server configuration parameters 290 sample scenario 18 security 306 starting 47 startup parameters 235 stopping 47 templates 304 terminology 16 threads 227 UNIX starting 48 stopping 48 Windows starting 48 stopping 48 Email Messages form. See AR System Email Message form EmailDaemon.properties file configuring 237 invalid passwords, removing 255 performance and configuration 237 updating 235 using 233 Entry ID label 200 environment variables, setting UNIX 31 Windows 27 Error Logs form described 305 overview 229 troubleshooting email engine 229 errors AR System API 231 incoming email 181 internal email engine 231
errors (continued) logs 229 outgoing email 125 escalations. See workflow examples, copying and pasting into mail client 145 expiration date, security key 306 exporting email templates description 188 outgoing workflow 169
F
failures, transmission or instruction 230 fields notifications, defining in 91 order in notifications 92 files EmailDaemon.properties 233 logging.properties 231 filters. See workflow footer templates 198, 275 description 186 HTML 186 label 198 Form label 192 Format label 196 incoming email, using with 153 formats, template basic 200 HTML 201 label and values 200 variables 201 XML 201 forms administration forms 298 default workflow 64 entry interval times, changing 76 importing by default 297 sample for modify actions 168 system-generated forms 297 user forms 307 workflow forms 311 forms list AR System Email Association 311, 312 AR System Email Attachment Join 311
316 Index
forms list (continued) AR System Email Attachments description 310 HTML templates 212 outgoing email 115 AR System Email Error Logs 305 AR System Email Instruction Parameters 311, 312 AR System Email Instructions 311 AR System Email Mailbox Configuration 298, 302 AR System Email Messages 307 description 307 overview 108 variable replacements 120 AR System Email Security 306 AR System Email Templates 210 AR System Email User Instruction Templates 304
HTML (continued) outgoing email, sending 111 radio buttons 202 references and examples 112 result template sample code 271 result templates 186 status templates 186 templates 201 text fields 202
I
ID label 199 IMAP4 definition 15 incoming mailbox, configuring 60 Microsoft Exchange Server and 261 importing forms by default 297 incoming email advanced options 178 attachments 154 Format label, with queries 149 Format label, with submits 153 modifying entries 154 overview 143 qualifications, including 148 sample scenario 142 sending queries 144 submitting entries 150 syntax for label/value pairs 144 templates 185 templates, using 177 user instructions, sending 222 user-defined instructions 216 using 143 workflow triggered 144 incoming mailboxes, configuring See also incoming email, mailboxes advanced 61 description 59 IMAP4 60 MAPI 60 MBOX 61 POP3 60 security 69
G
global fields and variables 205 global parameter declarations in templates 203 glossary 16
H
header templates description 186 HTML 186 HTML banners in outgoing email 129 label 198 reply template, adding to 275 using 198 heap size, defining for email engine 252 HTML check buttons 202 field types, allowable 201 format email, using to 147 format of templates 201 header templates 186 input controls 113 menu fields 202 modify instructions, sending 161 notifications, sending from workflow 85 outgoing content templates 107
Index
317
incoming mailboxes, configuring (continued) testing 67 UNIX during installation 45 Windows during installation 36 incoming mailboxes, definition 17 installation See also preinstallation components 26 documentation, reviewing 26 email engine UNIX 41 Windows 32 Java, correct version needed 253 MAPI logon settings, entering 39 mailbox, changing login information 49 preparation 27 MBOX preparation 27 preinstallation steps 26 UNIX tasks 31 Windows tasks 27 setup 25 SSL 27 UNIX 41 basic information, entering 42 completing 47 configuration information, entering 45 environment variables, setting 31 Windows 32 basic information, entering 33 completing 40 configuration information, entering 35 environment variables, setting 27 worksheet, using 26 instruction or transmission failures 230 Instruction Parameters form 311, 312 instructions definition 17 modify, sending (HTML) 161 modify, sending (plain text) 157 Instructions form 311 internal email engine errors 231 Internet Message Access Protocol. See IMAP4 interval time, changing form entry 76
J
Java components required for installation 26 correct version needed for installation 253 JRE directory 32
K
Key label 199 key terms describing email engine 16 keywords content templates for outgoing emails in notifications, using in 99 submissions 153
L
label aliases Encryption and Encryption Key 199 Entry ID, EntryID, and RequestID 200 Footer and Footer Template 198 Header and Header Template 198 Query and Search 197 Result and Result Template 197 RPC Number 193 Schema 192 Status and Status Template 198 TCP 193 User, User Name, Name, and Login Name 193 label/value pairs See also templates definition 191 format, templates 200 syntax Action label 194 format 200 same as templates 144 sending email 108 labels Action 194 Authentication 193 Footer Template 198 Form 192 Format 196 incoming queries 149 incoming submits 153
318 Index
labels (continued) Header Template 198 Instruction 194 Key 199 Language 194 Login 193 Modify 157 !Name/ID! 199 Password 193 Qualification 197 incoming email, using with 148 Query 144 Request ID 200 Result Template 197 RPC 193 Server 192 Status Template 198 Submit incoming email 150 TCP Port 193 variables, substituting with 205 Language label 194 local parameter declarations in templates 203 local system accounts for email engine service 249 logging AR System Email Error Logs form 229 debugging 231 errors 229 logging.properties file 231 message information 125, 180 severity levels 305 system status 229 troubleshooting problems 250 Login label 193
M
mail server definition 16 email engine, relation to 18 troubleshooting 256 Mailbox Configuration form 298 mailboxes changing configuration 65
mailboxes (continued) configuration troubleshooting 259 configuration overview 52 creating 53 definition 16 polling interval 60, 239 See also incoming mailboxes UNIX AR System mailbox, setting up 287 outgoing mailboxes MAPI definition 15 email engine login information, changing after installation 49 incoming mailbox, configuring 60 logon settings, entering 39 outgoing mailbox, configuring 54 outgoing notifications, saving 75 preparation steps for installation 27 transport problems UNIX, fixing 258 Windows, fixing 257 upgrading 27 MBOX definition 15 incoming mailbox, configuring 61 preparation steps for installation 30 sample debug log 248 mechanism, used for notifications 90 menu fields, HTML 202 Message Information tab status information for incoming email 180 status information for outgoing email 125 messages AR System Email Messages form 307 content, determining 125 notifications, used in 94 overview 85 Messages form description 307 outgoing email overview 108 variable replacement 120 Messages tab, notifications 93 Messaging Application Programming. See MAPI MIME (Multipurpose Internet Mail Exchange) 15
Index
319
modify actions action label 195 additional restrictions 165 constraints 165 email engine, configuring 73 enabling 63 entries, using incoming email 154 HTML, using 161 instructions, sending (HTML) 161 instructions, sending (plain text) 157 Modify label, incoming email 157 plain text, using 157 querying entries 174 replying 160 sample form, creating 168 sample scenario 155 searching entries 174 modify key 195 Multipurpose Internet Mail Exchange. See MIME
N
Name label 199 non-root installations with UNIX 31 Notes displaying HTML in mail clients 128 Java version, correct version needed for installation 253 notifications, creating with join forms using Submit execute condition 86 Password field, do not modify 195 queries and optimizing performance 126 style sheets linked to HTML not supported 211 notes restricted use of keywords in content templates 99 notifications ARTask attachments, including 91 deleting automatically 104 direct access URLs 89 displaying date, time, or numeric values 104 field order 92 fields, defining 91 filter workflow, creating 168 groups, not using 90
notifications (continued) HTML, using 85 keywords, using in content templates for outgoing email 99 mechanism 90 Messages tab, using 93 messages, defining 94 permissions 92, 96 processing 14 replying 171 saving (MAPI) 75 subject lines 91 submit execute condition with join forms 86 templates definition 96 order used 99 tab, using 93 text 89, 169 user name 89 variable, using 205
O
outgoing email advanced options 117 attachment alternatives 124 errors 125 messages 125 templates 117 variable replacements 119 AR System Email Messages form 108 attachments, including 114 dynamically assigning templates 99 field value, replacing 120 HTML, sending in 111 message content, determining 125 plain text, sending in 109 professional appearance 126 result templates, using 131 sample scenario 82 syntax for label/value pairs 108 template types 185 templates, creating 105 troubleshooting 226 using header templates as banners 129 using HTML content templates 137
320 Index
outgoing email (continued) using status templates 138 XML templates 135 outgoing mailboxes, configuring See also mailboxes advanced 56 description 53 MAPI 54 security 71 SMTP 55 testing 65 UNIX during installation 46 Windows during installation 38 outgoing mailboxes, definition 17 overviews advanced email solutions 21 configuration 52 email engine 14 incoming email 143 modify instructions with incoming email 155 templates 184 workflow to modify requests, using 166
P
parameters email instruction 311, 312 startup 235 templates 203 Password label 193 passwords application service, specifying 235 identifying invalid 253 removing invalid 254 performance EmailDaemon.properties 237 queries, optimizing 126 retrieval time, changing form entry 76 permissions notifications 92, 96 verifying for Windows account 260 plain text modify instructions, sending 157 outgoing email, sending 109
polling interval minutes, configuring 60 seconds, configuring 239 POP3 definition 15 incoming mailbox, configuring 60 Microsoft Exchange Server and 261 Post Office Protocol. See POP3 postinstallation UNIX, stopping and starting email engine 48 Windows, stopping and starting email engine 48 preinstallation See also installation MAPI and MBOX 27 MAPI preparation steps 27 MBOX preparation steps 30 non-root user issues 31 Remedy mail server upgrade UNIX 31 Windows 30 upgrading UNIX from email engine 5.1 or 5.1.1 31 priority of emails sent 90, 111 processing notifications 14 professional looking email 126 protocols IMAP4 15, 261 MAPI 15 MBOX 15 POP3 15, 261 SMTP 15, 261
Q
Qualification label 197 qualifications incoming email, including 148 label/value pairs syntax 148 short hand syntax 149 templates, adding to 175 testing 148 query action description 195 incoming email 144 label 144
Index
321
query action (continued) modifying entry 174 performance 126 using 264
R
radio buttons in HTML format 202 receiving email 14 replying configuring email engine 72 modify actions, not changing 161 modify instructions 160 notifications 171 Request ID label 200 requests, submitting across time zones 260 restrictions when modifying entries 165 result templates description 186 HTML 186 label 197 outgoing email, using with 131 sample HTML 271 RPC Number label 193
S
sample scenarios email engine 18 incoming email 142 modify actions 155 outgoing email 82 user instructions 216 search. See query Secure Sockets Layer. See SSL security See also SSL article describing certification authority 77 certification authorities (CA) 76 configuring 69 email 306 keys 70 modify actions 73, 168 security key expiration date 306 Security form 306
sending email email engine, using 14 incoming email, using 143 Server label 192 servers stopping and starting AR System 259 wrong server specified 255 services local system account with email engine 249 troubleshooting 260 shorthand qualifications 149 Simple Mail Transfer Protocol. See SMTP Sm@rtCert client 33 SMTP configuring during installation 46 definition 15 gateway 261 outgoing mailbox 55 sample debug log 247 SSL See also security certification authorities (CA), configuring 76 configuring 76 installation 27 starting and stopping email engine server, stopping and starting 259 startup parameters 235 troubleshooting 253 UNIX 47 Windows 47 status information reserved variables 208 templates 208 status messages incoming email 180 outgoing email 125 status templates description 186 example 273 formatting email 152 HTML 186 label 198 outgoing email, HTML 138 subject lines in notifications 91
322 Index
submit actions action label 194 notifications with join forms 86 Submit label, incoming email 150 submitting requests across time zones 260 submitting email in filter workflow 170 entries, using incoming email 150 keywords 153 syntax formats of label/value pairs 200 incoming email label/value pairs 144 outgoing email label/value pairs 108 qualifications 148 shorthand qualification syntax 149 template label/value pairs 194 system status logs 229 system-generated forms 297
T
TCP port configuring 34 label 193 templates See also label/value pairs adding 210 AR System Email Templates form 209 attachments 211 modifying 214 Content 119 creating 185, 188, 209 data-driven workflow, using to set 97 date formats 206 definition 184 deleting attachments 214 dynamic assignment for outgoing email 99 examples 268269 exporting 188 exporting with attachments to another server 215 fields with, searching 265 Footer 198, 275 formats basic 200 HTML 201
templates (continued) formats (continued) labels and values 200 variables 201 XML 201 Header 198, 275 incoming email 177, 185 instruction 216 creating 219 labels and values 191 formats 200 misleading use of term 184 modifying 209 notifications, used in 96 order used in notifications 99 outgoing email 185 using 105 outgoing email, used with 119 overview 184 parameters 203 qualifications, adding to 175 requests with, searching 266 reserved variables 207 Result 197 Status 198 example 273 storing 209, 302 user instructions 219 syntax for label/value pairs 194 testing 219 tips 209 types of 185 User-Defined Instruction 187, 216 using after an upgrade 215 variables 203 formats 201 Templates form 210 Templates tab notifications 93 using 117 terminology 16 text fields HTML 202 notifications 89, 169
Index
323
threads, used in email engine 227 time zones, submitting requests across 260 tips copying and pasting examples into mail client 145 data-driven workflow, using 97 email engine, administering (Webcast) 87 Email Errors Log form, accessing 230 Email Messages form in browser, displaying 110 EmailDaemon.properties file, using 234 HTML, using to format email 147 incoming email can trigger workflow 144 multi-line syntax in variables 200 qualifications to template, adding 175 security keys with modify actions 73, 168 status templates, using to format email 152 templates, testing 219 templates, use of term slightly misleading 184 testing qualifications 148 XML file, validating 135 transmission or instruction failures 230 troubleshooting See also debugging advanced options for incoming email 178 API errors 231 configuration, testing 65 console output 250 debugging email engine 242 -Dmail.debug=true debug mode 242 Email Messages, using 226 email request processing 261 EmailDaemon.properties file performance and configuration settings 236 using 233 error logs 229 failures, transmission or instruction 230 fixing common problems 248 internal errors 231 invalid application service passwords determining 253 removing 254
troubleshooting (continued) logging problems 250 logging.properties file, using for debugging 231 mail server 256 mailbox configuration, making changes to 259 MAPI transport problems UNIX, fixing 258 Windows, fixing 257 notify filters 261 outgoing email 226 permissions for Windows accounts, verifying 260 sample debug log 243 starting email engine 253 startup parameters 235 submitting requests across time zones 260 system status logs 229 time zones, submitting requests across 260 transmission or instruction failures 230 wrong server specified 255 trusted email users 294
U
UNIX AR System mailbox, setting up 287 configuration during installation 45 debugging email engine 245 installation 41 basic information, entering 42 completing 47 incoming mailbox, configuring during 45 non-root 31 outgoing mailbox, configuring during 46 MAPI transport problems, fixing 258 notifications from server 86 preinstallation tasks 31 starting email engine 48 stopping email engine 48 upgrading from email engine 5.1 or 5.1.1 31 upgrading email engine 5.1 or 5.1.1, from 31 MAPI issues 27
324 Index
upgrading (continued) old templates, using 215 original template format, using from Remedy Mail Server 63 URLs, direct access in notifications 89 User Instruction Templates form 304 user instructions creating 220 incoming email, sending 222 results 222 sample scenario 216 variables, using 224 user name field, in notifications 89 User-Defined Instruction templates actions, user-defined 187 definition 187 overview 216 sample scenario 216 user-defined actions 196 users modify actions, using security keys 73, 168 trusted email 294
W
warnings domain names, not using 90 group notifications, not using 90 internal information should not be modified 311, 312 modify actions, not changing during reply 161 multiple AR System servers 34, 43 Windows accounts, verifying permissions 260 AR System, installing 33 debugging email engine 242 installation basic information, entering 33 completing 40 configuration during 35 description 32 incoming mailbox, configuring during 36 outgoing mailbox, configuring during 38 MAPI transport problems, fixing 257 notifications from server 86 preinstallation tasks 27 services, troubleshooting 260 software, loading for installation 32 starting email engine 48 stopping email engine 48 workflow data-driven templates, dynamically assigning 99 templates, setting 97 default form 64 dynamically assigning templates to outgoing email 99 messages in notifications, using 94 modify requests, creating to 167 notifications, defining in 86 notify action in filter 168 overview, using to modify requests 166 templates in notifications, using 96 triggered by incoming email 144 troubleshooting 261 UNIX servers 86 Windows servers 86 worksheet, preinstallation 26
V
values definition 191 field, replacing in outgoing email 120 format, templates 200 variables 203 Variable Replacement tab AR System Email Messages form 119 using 119 variables field values and qualifications, using with 205 formats 201 multi-line syntax 200 notifications, using in 205 reserved 207 templates with incoming email 177 templates, used in 203 user instructions, using with 224
Index
325
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*

Email Engine 700

Transféré par

Informations du document

Description originale:

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Email Engine 700

Transféré par

Droits d'auteur :

Formats disponibles

BMC Remedy Action Request System 7.

Administering BMC Remedy Email Engine

May 2006 Part No: 58475

BMC Software, Inc.

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

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

BMC Remedy Action Request System 7.0

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

Administering BMC Remedy Email Engine

Incoming email . . . . . . . . . . . . . . . . . . . . . . . . . 141

BMC Remedy Action Request System 7.0

Using email templates . . . . . . . . . . . . . . . . . . . . . 183

Administering BMC Remedy Email Engine

Examples of email templates . . . . . . . . . . . . . . . . . . 263

BMC Remedy Action Request System 7.0

Email engine installation worksheets . . . . . . . . . . . . . . 277

Setting up UNIX mailboxes . . . . . . . . . . . . . . . . . . . 287 Upgrading email option parameters. . . . . . . . . . . . . . . 289

BMC Remedy Email Engine forms . . . . . . . . . . . . . . . . 297

BMC Remedy Action Request System 7.0

Installing Getting Started

Form and Application Objects

Workflow Objects Configuring

Administering BMC Remedy Email Engine

Title Database Reference

Procedures for configuring the BMC Remedy Mid Tier. Administrators

BMC Remedy Action Request System 7.0

Learn about the AR System Developer Community

Why should you participate in the Developer Community?

How do you access the Developer Community?

Overview of the BMC Remedy Email Engine

Overview of the BMC Remedy Email Engine

BMC Remedy Action Request System 7.0

About the BMC Remedy Email Engine

14 Chapter 1Overview of the BMC Remedy Email Engine

Administering BMC Remedy Email Engine

About the BMC Remedy Email Engine

BMC Remedy Action Request System 7.0

Email engine terminology

16 Chapter 1Overview of the BMC Remedy Email Engine

Administering BMC Remedy Email Engine

Email engine terminology

BMC Remedy Action Request System 7.0

OverviewHow the email engine works

AR System Server HD Incident

6.3 Email Engine

instructions translated into API calls to server

Outgoing email is formatted and assembled

Email account 2 Users log in to mail server to receive new email

18 Chapter 1Overview of the BMC Remedy Email Engine

Administering BMC Remedy Email Engine

appropriate query information for the HD Incident form.

OverviewHow the email engine works

BMC Remedy Action Request System 7.0

20 Chapter 1Overview of the BMC Remedy Email Engine

Administering BMC Remedy Email Engine

OverviewImproving the appearance of your email

6.3 Email Engine

Abcdefg Hijklm Nopqrst

Schema: HD Incident Action: Impact: Submit Urgent

Urgent email sent to incoming mailbox.

Urgent email sent to Francie Frontline

OverviewImproving the appearance of your email

BMC Remedy Action Request System 7.0