Académique Documents
Professionnel Documents
Culture Documents
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.
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
Chapter 2
Contents
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
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
Contents
Chapter 6
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
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
Appendix C Appendix D
Appendix E
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
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
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
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.
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
12 Preface
Chapter
13
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.
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.
15
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.
17
Underlying Database
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
Incoming Mailbox
Outgoing Mailbox
3
Email engine parses query instructions
POP3 IMAP4 MBOX MAPI SMTP MAPI
Mail Server
Email account 1
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
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.
Email Templates
Field 1 Field 2 Field 3
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.
Field 1 Field 2 Field 3
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
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
25
Preinstallation steps
This section describes the preinstallation steps you should complete before you install 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.
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.
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.
Preinstallation steps
27
Note: You must be a Windows domain administrator or MS Exchange administrator to perform these steps.
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
At one of the following locations: On the same domain as the email engine. On a domain with appropriate trust relationships.
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
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.
Preinstallation steps
29
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
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.
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.
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.
Creating directories
Create the logging.properties and javamail.providers files.
Preinstallation steps
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.
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.
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.
33
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
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.
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.
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.
Incoming Mailbox screen. Different choices become enabled when you select the mail protocol (Server Type).
Figure 2-1: Incoming Mailbox screen
2 MAPI only:
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.
Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming.
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
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:
From: ARSystem [arsystem@remedy.com]
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.
39
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.
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.
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.
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.
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.
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.
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.
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.
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.
Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming.
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
Use a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming.
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.
outgoing emails.
owner of the mailbox. If you previously entered a display name of ARSystem and an email address of arsystem@remedy.com, the From: line would be:
From: ARSystem [arsystem@remedy.com]
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
Postinstallation steps
This section describes optional postinstallation steps.
Postinstallation steps
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.
2 Enter one of the following commands to start the email engine manually:
emaild.sh start &
or
# nohup emaild.sh start &
installation directory:
cd <email_engine_install_dir>
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
Services.
b Select the BMC Remedy Email Engine service. c Right-click the service and choose Start or Stop.
or
java -cp emaildaemon.jar;arapi70.jar;arutil70.jar;activation; jar;mail.jar;imap.jar;smtp.jar;pop3.jar; com.remedy.arsys.emaildaemon.EmailDaemon
Note: MAPI mailbox users only: If you did not configure your MAPI mailbox during installation, change the email engine login information in the Services window to your Windows user account.
Postinstallation steps
49
Chapter
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.
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
Outgoing mailboxes support the following mail protocols: MAPI and SMTP.
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.
b Enter the following information in the Basic Configuration tab:
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
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.
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
in step b on page 55 For example, if you entered a display name of ARSystem and an email address of arsystem@remedy.com, the From: line would be:
From: ARSystem [arsystem@remedy.com]
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
57
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
For more information about notifications and escalations, see Defining workflow to send email notifications on page 86
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
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.
b Enter the following information in the Basic Configuration tab:
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.
b Enter the following information in the Basic Configuration tab:
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.
4 When you have selected or entered your choices, click Save.
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.
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
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.
4 When you have selected or entered your choices, click Save.
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
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.
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
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.
69
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.
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
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
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
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.
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.
73
5 Click the Advanced Configuration tab of the incoming mailbox you want the
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
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.
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
where:
<AR_System-server> is the name of the AR System server associated with
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>
For more information about this property or the EmailDaemon.properties file, see Performance and configuration settings on page 236.
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
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
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
HD Incident
Escalation
Field 1 Field 2 Field 3 Abcdefg Hijklm Nopqrst
Email messages
Outgoing records
Email Engine
Outgoing Mailbox
3
Mail Server
Email account
Bob Backline
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
83
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
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.
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
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
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
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
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
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
Using notifications
91
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
Administering BMC Remedy Email Engine Figure 4-7: Including attachments with 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 notifications
93
BMC Remedy Action Request System 7.0 Figure 4-8: Notify filter or escalation dialog boxMessages tab
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.
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 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.
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.
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)
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
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
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.
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.
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.
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 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$$#
Using notifications
107
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.)
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
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.
111
outgoing message. See Using the Email Messages form to send outgoing email on page 108 for sample contents of an outgoing message, especially steps 2 through 6.
2 Click the HTML Body tab. 3 Enter HTML contents, as in the following example:
Server: polycarp<BR> Login:Francie Frontline<BR> Password <input type="password" name="Password" size="15" maxlength="14"> <BR> Key:1234<BR> Action: Modify<BR> Form:TestSecurityForm<BR> Request ID: 000000000000003<BR> Assigned To <input type="text" name="!4!" size="20" value="Assignee"> <BR> Short Description <input type="text" name="!8!" size="40" value="Enter a short description"> <BR> Status <input type="radio" value="New" name="!7!"/> New <input type="radio" value="Assigned" name="!7!" /> Assigned <input type="radio" value="Fixed" name="!7!"/> Fixed <input type="radio" value="Rejected" name="!7!"/> Rejected <input type="radio" value="Closed" name="!7!"/> Closed <BR>
In addition to HTML formats, any label/value pairs that you include must follow specific syntax requirements. For more information, see Chapter 6, Using email templates. See any standard HTML reference book or reputable online source (http:// www.w3.org/) for how to define HTML, especially input type controls. Additional HTML examples are demonstrated in Sending modify instructions in HTML on page 161.
4 Click Send to send the mail from the outgoing mailbox to the user.
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
20).
Figure 4-20: AR System Email Messages formAttachments tab
(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 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
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.
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.
Message form.
3 Select one of the advanced option tabs: Advanced Options, Message
Information, or Errors.
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.
Administering BMC Remedy Email Engine Figure 4-22: AR System Email Messages formAdvanced Options, 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.
For example, this content template (which modifies an entry) uses the following label/value pairs:
Server: polycarp Login: Password: Key: Action: Modify Form: TestSecurityForm
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$$#
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
121
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)
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
5 In the attachment pool, do the perform the following tasks: a Right-click an attachment field corresponding to the contents of the
system default. The system needs to be able to read and parse the contents of these attachments when it creates the outgoing email. You can attach only one of each type of alternative attachment to a message form. These attachments are stored as part of the message in the message form.
7 Send the outgoing email.
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.
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).
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.
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>
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.
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 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.
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.
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
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.
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
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.
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.
3 Open the outgoing mailbox entry in the AR System Email Mailbox
Configuration form.
4 UndertheAdvancedConfigurationtab,specifyRemedy_Picnic_Invite.htmlas
137
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
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.
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.
3 Open the outgoing mailbox entry in the AR System Email Mailbox
Configuration form.
4 Under the Advanced Configuration tab, specify Status_default.html as the
status template.
5 (Optional) Include a header or footer template.
The sample email shown in Figure 4-35 uses the default header template configured for the outgoing mailbox.
6 Send an incoming email to the BMC Remedy Email Engine that will generate
an outgoing status email, for example, a bogus query that returns no records. Figure 4-35 displays the outgoing status email generated by the BMC Remedy Email Engine.
Figure 4-35: Outgoing message with default header and HTML status templates
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
HD Incident
6.3 Email Engine
Printer Broken
4
Server creates ticket.
Email engine parses instructions. Instructions then translated into API calls to server.
Email account
Mail Server
2
"Printer broken!"
Joe User
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.
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.
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
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).
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
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"
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.
149
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.
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
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
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.
Underlying
Database
HD Incident
6.3 Email Engine
Outgoing
Field 1 Field 2 Field 3
4
Email Engine
Incoming Mailbox
Mail Server
Email account
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.
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
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
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).
4 Click Send to send the mail from the outgoing mailbox to the user.
159
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.
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.
4 Send the outgoing email.
The user will receive an email that looks like Figure 5-9.
Figure 5-9: Modify instruction (HTML format) sent to user
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
AR System Server
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.
167
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.
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.
169
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
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
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.
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.
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
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.
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
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
If you expect the value of a variable to span multiple lines, then enclose the variable with brackets:
[$$ $$]
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$$]
Administering BMC Remedy Email Engine Figure 5-17: Attachment alternatives information for incoming 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
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
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)
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.
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.
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.
OverviewEmail templates
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.)
OverviewEmail templates
187
BMC Remedy Action Request System 7.0 Figure 6-5: User-Defined instruction template
User-defined templates look the same as other templates and are stored in the AR System Email Templates form. For more information, see Action label on page 194 and 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.
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.
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.
6 Save your changes.
The template is saved as a single text file with an *.arm extension. Using the AR System Email Templates form, users can associate these files with their mail messages. The following example shows an email template exported using BMC Remedy Administrator.
# # File exported Fri Apr 30 09:54:36 2004 # Schema: HD Email Server: POLYCARP.eng.remedy.com Login: Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full
In general, lines beginning with a pound sign (#) are treated as comments, and can occur anywhere in the message. Comments are optional and can be retained or deleted.
Server that will be affected by the Yes instruction. User name used when executing Yes the instruction.
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
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
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.)
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.
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
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.
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
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.
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$$#
XML format
The XML format is as follows:
<Label>Value</Label>
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.
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.
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
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.
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$$#
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.
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$$#
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$$#
#$$ActionStatus.Type$$#Thetypeoferror,suchasSevere,Error,Warning. #$$ActionStatus.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
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
209
BMC Remedy Action Request System 7.0 Figure 6-8: AR SystemEmail Templates form
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
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.
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.
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
The AR System Email Attachments form opens as shown in the following figure.
Figure 6-10: AR System Email Attachments form for templates
8 Right-click in the attachment pool, and choose Add from the menu that
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
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.)
click the arrow next to the blank field at the bottom of the pane.
2 Select the attachment. 3 Click the Add Existing button.
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.
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.
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
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.
215
2 If only one form is used for email submissions, set the Default Workflow
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.
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
3
Email Engine Email Server
Results.
Underlying Database
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.
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
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
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
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
This is the value that will be used to identify this template when used in an incoming email, for example, Urgent.
221
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.
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
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
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
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.
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.
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 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.
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.
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
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
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.
231
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.
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.
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,
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.
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.
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>
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
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
and
Cho, Rick
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.
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
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.
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.
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. 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
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.
243
script:
-Dmail.debug=true
245
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
247
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.
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
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,
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
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.
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>
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
After the password is removed, the console output should show that the email daemon has successfully connected to the AR System server with no errors.
254 Chapter 7Troubleshooting
installation directory.
2 Locate the following line:
com.remedy.arsys.emaildaemon.<ar_system_server_name>.Password=<applic ation_service_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.
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.
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.
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
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;
These settings make sure that the JavaMail System uses the class created to support MAPI for both incoming and outgoing mailboxes.
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;
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.
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.
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.
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
261
Appendix
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)
263
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
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
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
265
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"
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
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.
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
attachment name including the extension is not supplied in the email template, the email submission will fail.
8 Send the email to the incoming mailbox.
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.
269
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.
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><!--DWLayoutTable--> <TBODY> <TR> <TD vAlign=top width=772 height=234> <TABLE borderColor=#cccccc cellSpacing=1 cellPadding=1 width="100%" border=0> <TBODY> <TR borderColor=#cccccc> <TD colSpan=5> <HR> </TD></TR> <TR borderColor=#cccccc> <TD width="11%"><B><I>Incident #</I></B></TD> <TD width="17%"><a href="http://polycarp/arsys/servlet/ ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request ID$$#">#$$Request ID$$#</a> </TD> <TD width="21%"> </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>
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.
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.
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.
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
277
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
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
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.
Note: For multiple AR System servers on the same
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.
Description Port number for your companys email server. Default values:
POP3: 110 POP3
Your value
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
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
Description Name of the user or administrator of the email account. Password associated with the server user.
Your value
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.
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. 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
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.
Note: If your display name is ARSystem and your
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).
Your value
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
Appendix
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.
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,
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
Appendix
289
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 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
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
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
(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
Function
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
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
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
Environment ARDATE
Not used.
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.
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
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.
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
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.
297
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.
299
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
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
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.
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.
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
User Name Force for Mailbox Mailbox Name Force from Email Addresses Email Addresses Expiration Date
Description
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
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.
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.
309
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.
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.
311
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