BMC Email Server.52101456

BMC Remedy Action Request System 7.6.
04
BMC Remedy Email Engine Guide
January 2011
www.bmc.com
Contacting BMC Software

You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada

Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000
Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000
If you have comments or suggestions about this documentation, contact Information Design and Development by email at doc_feedback@bmc.com.
Copyright 19912011 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. AIX and IBM are registered trademarks of International Business Machines Corporation. UNIX is the registered trademark of The Open Group in the US and other countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. BMC Software 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 for the product and the proprietary and restricted rights notices included in this documentation.
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.
Customer Support
You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or email. To expedite your inquiry, please see Before Contacting BMC Software.
Support website
You can obtain technical support from BMC Software 24 hours a day, 7 days a week at http://www.bmc.com/support. From this website, you can:

Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax numbers, and telephone numbers.
Support by telephone or email

In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 or send an email message to customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) Outside the United States and Canada, contact your local support center for assistance.
Before contacting BMC Software

Have the following information available so that Customer Support can begin working on your issue immediately:
Product information Product name Product version (release number) License number and password (trial or permanent)
Operating system and environment information Machine type Operating system type, version, and service pack System hardware configuration Serial numbers Related software (database, application, and communication) including type, version, and service pack or maintenance level
Sequence of events leading to the problem Commands and options that you used Messages received (and the time and date that you received them) Product error messages Messages from the operating system, such as file system full Messages from related software
License key and password information

If you have a question about your license key or password, contact Customer Support through one of the following methods:
E-mail customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local support center for assistance. Submit a new issue at http://www.bmc.com/support.
Contents
Preface 11
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 AR System documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Chapter 1 Introduction to the Email Engine 15 16 17 18 20 20 22 24 26 27 28 29 30 32 32 33 36 38 39 41 41 42 44 44 45 51 52 53 54 55

5
About the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email Engine terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email Engine architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Threading model for outgoing mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How the Email Engine works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Improving the appearance of your email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple mail server support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enhanced internationalization support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Configuring Email Engine mailboxes
Configuring outgoing mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic outgoing mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced outgoing mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring incoming mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic incoming mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced incoming mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Testing your mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About email security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring incoming mailbox security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring outgoing mailbox security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring the Email Engine for replying with results . . . . . . . . . . . . . . . . . . . . . Configuring the Email Engine for modify actions . . . . . . . . . . . . . . . . . . . . . . . . . . Saving outgoing notifications in MAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the form entry interval time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Configuring SSL for the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3 Outgoing email
How outgoing email works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining workflow to send email notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Dynamically assigning templates to outgoing email . . . . . . . . . . . . . . . . . . . . . . . . 66 Displaying date/time or numeric values in email notifications . . . . . . . . . . . . . . . 70 Deleting email notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Using templates with outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Using the Email Messages form to send outgoing email . . . . . . . . . . . . . . . . . . . . . . . . 74 Sending outgoing email in plain text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Sending outgoing email in HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Including attachments with outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Displaying advanced options for outgoing email. . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Determining message content of outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Character sets in outgoing mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Adding extra custom headers to outgoing SMTP emails. . . . . . . . . . . . . . . . . . . . . 89 Sending reply email: Giving a professional look to outgoing email. . . . . . . . . . . . . . . 89 Using header templates as a banner with outgoing email. . . . . . . . . . . . . . . . . . . . 91 Using HTML result templates with outgoing email. . . . . . . . . . . . . . . . . . . . . . . . . 93 Using XML result templates with outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Using HTML content templates with outgoing email . . . . . . . . . . . . . . . . . . . . . . . 97 Using status templates with outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 User-defined HTML or XML text in outgoing HTML emails . . . . . . . . . . . . . . . . . . . 102 Chapter 4 Incoming email 105
How incoming email works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Using incoming email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Sending a query instruction to the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Including qualifications in your email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Using shorthand qualification syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Using the Format label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Sending a submit instruction to the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Using keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Using the Format label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Including attachments with incoming email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Sending a Modify instruction to the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 How modify instructions work with incoming email . . . . . . . . . . . . . . . . . . . . . . 117 Sending modify instructions in plain text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Sending modify instructions in HTML. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Additional restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Using workflow to modify requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Creating workflow to modify requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Creating a security key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Creating a sample form for your modify example . . . . . . . . . . . . . . . . . . . . . . . . . 128 Creating filter workflow that triggers a Notify action . . . . . . . . . . . . . . . . . . . . . . 128 Exporting an email template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Creating a submit email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Replying to email notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Searching for an entry to modify: Advanced solution . . . . . . . . . . . . . . . . . . . . . . . . . 132 Using variables with templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Displaying advanced options for incoming email. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Message Information tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Errors tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6 BMC Remedy Email Engine Guide
Character sets in incoming mail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Chapter 5 Using email templates 139 140 141 141 143 143 144 146 147 147 147 148 148 149 150 151 151 151 152 152 153 153 153 156 156 161 161 162 165 165 165 166 166 167 168 169 170 171 172 173 174 174 176 176 176
7
Overview of Email Engine templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Types of templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Incoming and outgoing mail templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User-defined instruction templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting mail templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using label/value pairs in templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Form label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Login, Password, and TCP Port labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RPC Number and Authentication labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Language label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Action label. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Qualification label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result Template label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Status Template label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Header Template and Footer Template labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . !Name! or !ID! labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Key label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Request ID label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Label/value pair formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Global and local parameter declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tips for creating or modifying templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Storing templates in the AR System Email Templates form . . . . . . . . . . . . . . . . . . . . Adding attachments to HTML templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding a previously saved attachment to your template. . . . . . . . . . . . . . . . . . . Modifying an attachment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting an attachment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exporting templates with attachments to another server . . . . . . . . . . . . . . . . . . . Preparing email templates after an upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending incoming email with user instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating and storing a template for use with user instructions . . . . . . . . . . . . . . Creating user instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sending a user instruction in an incoming email . . . . . . . . . . . . . . . . . . . . . . . . . . Results of the user instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using variables with user instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 6 Troubleshooting
Troubleshooting outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Error and system status logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email transmission or instruction failures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System API errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Internal Email Engine errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Logging levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Debugging options for the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Using the EmailDaemon.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Updating the EmailDaemon.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 Performance and configuration settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Recommendation for using the SMTP timeout properties . . . . . . . . . . . . . . . . . . 192 Creating email debug batch files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Debugging the Email Engine on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Sample debug log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Debugging the Email Engine on UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Fixing common problems with the email engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Configuring mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Logging problems with the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Defining a heap size for the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Troubleshooting startup issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Determining problems with the mail server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Stopping and starting the AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Making changes to mailbox configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Submitting requests across different time zones. . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Verifying permissions for the Windows accounts . . . . . . . . . . . . . . . . . . . . . . . . . 209 Troubleshooting email request processing and notify filters . . . . . . . . . . . . . . . . 209 Fixing issues with notifications that fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Temporary directories and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Appendix A Appendix B Appendix C Setting up UNIX mailboxes Email engine upgrade parameters Examples of email templates 213 215 221
Creating email templates to search for Request ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Creating email templates to search for fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Creating email templates to perform searches using qualifications . . . . . . . . . . . . . . 224 Creating email templates that include attachments . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 Creating an email content template with Submit and Query actions. . . . . . . . . . . . . 226 Creating an email reply using result templates in HTML format. . . . . . . . . . . . . . . . 227 Sample HTML result template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Email status template in HTML format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Adding a header template and a footer template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Appendix D Email Engine forms 233
Email Engine administration forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 AR System Email Failover Mail Server Configuration form . . . . . . . . . . . . . . . . . 234 AR System Email Mailbox Configuration form. . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 AR System Email Templates form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 AR System Email User Instruction Templates form . . . . . . . . . . . . . . . . . . . . . . . . 240 AR System Email Error Logs form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 AR System Email Security form. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
Email Engine user forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Messages form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Error Messages form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Attachments form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Attachment Join form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Email Engine workflow forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Instructions form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Instruction Parameters form . . . . . . . . . . . . . . . . . . . . . . . . . . . AR System Email Association form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index
242 242 245 249 250 250 250 251 251 253
Contents
10
Preface
NOTE
The compatibility information in the product documentation is subject to change. See the compatibility matrix at http://www.bmc.com/support for the latest, most complete information about what is officially supported. Carefully read the system requirements for your operating system, especially the patch requirements. See the Installation Guide, Obtaining system requirements and software, page 12.
Audience
This guide is for administrators who install and maintain 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 Developer Studio, BMC Remedy User, and BMC Remedy Data Import. Make sure that you understand the terms and concepts discussed in the Configuration Guide, which contains all the information you require to set up and administer a basic AR System environment. For additional information, see the Installation Guide, the Form and Application Objects Guide, and the Workflow Objects Guide.
AR System documents
The following table lists documentation available for AR System 7.6.04. Unless otherwise noted, online documentation in Adobe Acrobat (PDF) format is available on AR System product installation DVDs, on the Customer Support website (http://www.bmc.com/support), or both.
Preface
11
BMC Remedy Action Request System 7.6.04
You can access product help through each products Help menu or by clicking Help links.
NOTE
The AR System product help has not been updated for version 7.6.04. The help topics still apply to version 7.6.03. For the most recent content, refer to the PDF documentation.
Title Concepts Guide1 Description Audience
Overview of AR System architecture and features; includes Everyone information about add-on products that extend AR System functionality and a comprehensive glossary for the entire AR System documentation set. Instructions for installing AR System. Information about the development of AR System applications, including an introduction to using BMC Remedy Developer Studio. Administrators Developers2
Installation Guide Introduction to Application Development with BMC Remedy Developer Studio
Form and Application Objects Information about AR System applications and their user Guide interface components, including forms, fields, views, menus, and images. Workflow Objects Guide
Developers
Information about the AR System workflow objects (active Developers links, filters, and escalations) and how to use them to create processes that enforce business rules. Information about configuring AR System servers and clients, localizing, importing and exporting data, and archiving data. Administrators
Configuration Guide
BMC Remedy Mid Tier Guide Information about configuring the mid tier, setting up applications for the mid tier, and using applications in browsers. Integration Guide
Administrators
Instructions for integrating AR System with external Administrators/ systems by using web services, plug-ins, and other products, Developers/ Programmers3 including LDAP, OLE, and ARDBC. Information about monitoring and maintaining AR System Administrators/ and AR System applications to optimize performance and Developers/ solve problems. Programmers Database administration topics and rules related to how AR System interacts with specific databases; includes an overview of the data dictionary tables. Information about implementing a distributed AR System server environment with BMC Remedy Distributed Server Option (DSO). Administrators/ Developers/ Programmers Administrators
Optimizing and Troubleshooting Guide Database Reference
BMC Remedy Distributed Server Option Guide BMC Remedy Flashboards Guide C API Reference C API Quick Reference
Instructions for creating, modifying, and administering Administrators/ flashboards to display and monitor AR System information. Developers Information about AR System data structures, C API function calls, and OLE support. Quick reference to C API function calls. Programmers Programmers
12
AR System documents
Title Java API
Description
Audience
Programmers Information about Oracle Java classes, methods, and variables that integrate with AR System. For the location of the JAR file containing this online documentation, see the information about the Java API in the Integration Guide. Information about Java classes, methods, and variables used Programmers to write plug-ins for AR System. For the location of the JAR file containing this online documentation, see the information about plug-ins in the Integration Guide. Instructions for configuring and using BMC Remedy Email Administrators Engine. Descriptions of AR System error messages. Administrators/ Developers/ Programmers Everyone Administrators
Java Plug-in API
BMC Remedy Email Engine Guide Error Messages Guide
Master Index BMC Remedy Approval Server Guide Release Notes Release Notes with Known Issues BMC Remedy User Help BMC Remedy Developer Studio Help BMC Remedy Data Import Help BMC Remedy Alert Help BMC Remedy Mid Tier Configuration Tool Help BMC Remedy Browser Help
Combined index of all books. Instructions for using BMC Remedy Approval Server to automate approval and signature processes in your organization. Information about new features, compatibility, and international issues.
Everyone
Information about new features, compatibility, international Everyone issues, installation planning, and open issues. Instructions for using BMC Remedy User. Instructions for using BMC Remedy Developer Studio to develop AR System forms, workflow objects, and applications. Instructions for using BMC Remedy Data Import. Instructions for using BMC Remedy Alert. Instructions for configuring BMC Remedy Mid Tier. Instructions for using AR System forms in browsers. Everyone Developers
Administrators Everyone Administrators Everyone Administrators / Developers Administrators / Developers
BMC Remedy Migrator 7.6.04 Outlines procedures for installing BMC Remedy Migrator, BMC emedy Migrator Guide setting options, and performing migration tasks. BMC Remedy Migrator online help Procedures for setting BMC Remedy Migrator options and performing migration tasks.
BMC Remedy Encryption Provides an overview of the BMC Remedy Encryption Administrators Security 7.6.04 BMC Remedy Security products and explains how to install and configure Encryption Security Guide them.
1
The full title of each guide includes BMC Remedy Action Request System 7.6.04 (for example, BMC Remedy Action Request System 7.6.04 Concepts Guide), except the BMC emedy Migrator Guide and BMC Remedy Encryption Security Guide. 2 Application developers who use BMC Remedy Developer Studio. 3 C and Java programmers who write plug-ins and clients for AR System.
Preface
13
14
Chapter
Introduction to the Email Engine

This chapter provides an overview of the BMC Remedy Email Engine (Email Engine). The following topics are provided: About the Email Engine (page 16) Email Engine terminology (page 17) Email Engine architecture (page 18) Threading model for outgoing mailboxes (page 20) How the Email Engine works (page 20) Improving the appearance of your email (page 22) Multiple mail server support (page 24) Enhanced internationalization support (page 26)
Chapter 1
15
About the Email Engine

The Email Engine is a service that transforms email into an interface that communicates with the AR System server. It is included as part of the AR System and does not require an additional license. The Email Engine enables users to instruct the AR System server to perform queries, submissions, or modifications to entries, all by using email. This feature is particularly useful for users without direct access (a high-speed network link) to the AR System server. The Email Engine also returns the results of such requests in email messages in the plain text, HTML, or XML formats. Additionally, the Email Engine can process notifications by using workflow actions such as filters or escalations.
NOTE
You must install the Email Engine to send notifications from the AR System server. The Email Engine is a stand-alone client program that you can install and run on any computer system as an independent service. It provides the following capabilities: Receiving mailThe Email Engine receives email messages from an email account on your company mail server. These email messages can include instructions that are 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. You can format these emails by 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 by using the following protocols: Internet Message Access Protocol (IMAP4)Used for incoming mails. When mail arrives, copies of messages are downloaded from the mail server to your local computer and the copy of each message remains on the server. However, when Email Engine is used, this copy is removed from the server. Post Office Protocol (POP3)Used for incoming mails. When mail arrives, messages are downloaded to your local computer and removed from the mail server. Simple Mail Transfer Protocol (SMTP)Used for outgoing mail transmissions.
16
Email Engine terminology
Messaging Application Programming Interface (MAPI)Used primarily with the Microsoft Exchange Server (Windows only), as an interface that enables different email applications to work together to distribute email.
NOTE
The MAPI protocol for incoming and outgoing mail is disabled for 64-bit Oracle Java Virtual Machine (Oracle JVM). MBOXUsed for storing mail messages on a UNIX platform. Messages are stored in a file of type mbox under the user name. All the settings for the Email Engine and all logging information (including errors, incoming emails, and outgoing emails) are stored in forms within the AR System server. The Email Engine only stores 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 more information, see Debugging options for the Email Engine on page 177. 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.
Email Engine terminology

Throughout this guide, the following familiar terms are used in specific ways:
Table 1-1: Email Engine terminology (Sheet 1 of 2) Term Mail server Meaning in the context of Email Engine A computer system within your environment that is running a third-party software program that processes incoming and outgoing email messages. Examples include the Microsoft Exchange server or the UNIX sendmail program.
Failover mail A mail server that acts as a failover system, assuring uninterrupted server processing of messages, when the primary mail server stops working. You can define this by using the AR System Email Failover Mail Server form. For more information, see Multiple mail server support on page 24. Email account A user account on a mail server that permits a user to transmit or receive email messages.
Note: An email account is not the same as an email address. An email
account consists of a user name and often includes a password. Users must log in to the mail server by using an email account before they can send and receive email.
Chapter 1
17
Table 1-1: Email Engine terminology (Sheet 2 of 2) Term Mailbox Meaning in the context of Email Engine An entry in the AR System Email Mailbox Configuration form, which resides on your AR System server. 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 sending or receiving mail, and email account information (if required). Mailboxes are configured to be either Incoming mailboxes or Outgoing mailboxes. Incoming mailbox A 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 messages in this email account are assumed to be 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. Outgoing mailbox A mailbox containing the information required by the Email Engine to create and send messages. The Email Engine uses 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. Instruction A term used in the following ways: In a broader sense, instructions see all the parameters contained in an email message that perform certain actions; for example, logging in to the server, querying for all tickets assigned to a user, and returning the results in HTML format. In a narrower sense, instructions see a specific set of actions used in an email message; for example, Query, Submit, or Modify. The term Instruction can also be used as an alias for Action in a label/value pair.
For more information about configuring mailboxes, see Configuring Email Engine mailboxes on page 27.
Email Engine architecture

The Email Engine consists of multiple modules that run in threads. All the modules of the Email Engine are designed to be thread safe, and to increase speed and scalability. All modules run as separate threads. An incoming mailbox uses two threads to process email in the message queuethe Receiver and Execution modules. An outgoing mailbox uses separate threads running for the Creator and Sender modules to format and send outgoing messages.
Email Engine architecture
Figure 1-1: Modules and threads in 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 Email Engine on page 177 and Using the EmailDaemon.properties file on page 179.
Table 1-2: The Email Engine modules Module Monitor Receiver 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 Configuration Runs as a separate thread, and sends formatted messages to the mail server. Logs messages, errors, and warnings to the AR System Email Errors form or local file. Maintains configuration information for the system specified in the AR System Mailbox Configuration form and EmailDaemon.properties file.
Chapter 1
19
Threading model for outgoing mailboxes

The Sender and Creator threads for every outgoing mailbox depend upon the value set for the NumberOfSenderThreads property and the number of configured outgoing mailboxes respectively. Depending upon the NumberOfSenderThreads value and the number of configured outgoing mailboxes, a connection pool is created. The Sender thread uses the connections from this connection pool for sending the outgoing messages.
NOTE
The number of connections for each configured outgoing mailbox depends upon the number of Sender threads. Figure 1-2 explains this concept in detail.
Figure 1-2: Threading model for multiple outgoing mailboxes
As per the above figure, there are 3 configured outgoing mailboxes and the value of NumberOfSenderThreads is assumed to be 2. Due to this, 2 Sender threads and a connection pool with 6 connections (2 connections for every mailbox) is created. The Sender threads send the outgoing messages from the common message queue created for the 3 Creator threads by using the connections from this connection pool.
How the Email Engine works

This section presents a sample scenario that demonstrates how the Email Engine interacts with the AR System and your mail server. Figure 1-3 on page 21 presents a sample environment for an Email Engine implementation, including the flow of activity.
20
How the Email Engine works
Figure 1-3: How the Email Engine interacts with the AR System server
AR System Server HD Incident
AR System Email Mailbox Configuration Form
Field 1 Field 2 Field 3
Underlying Database
Email Engine
Printer Broken
Abcd ef ghijkl mno
1
AR System admin installs and configures email engine
Email Engine
Query instructions translated into API calls to server
Server queries ticket on HD Incident form and returns results
Incoming Mailbox
Outgoing Mailbox
3
Email engine parses query instructions
POP3 MBOX IMAP4 MAPI SMTP MAPI
Outgoing email is formatted and assembled
Mail Server
Email account 1
Email account 2
7 2
Query email sent to incoming mailbox
Users log in to mail server to receive new email
Shelly
Katie
Mark
In the XYZ Company, Shelly needs a list of the latest issues stored in the Help Desk (HD) Incident form. She wants the results of this query to be returned in an easyto-read email. Also, Shelly wants to make sure that her coworkers, 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 administrator installs the Email Engine, configuring Incoming and
Outgoing mailboxes to work with the company mail server. After the Email Engine is started, it contacts the AR System server. The Email Engine then reads all the entries in the AR System Email Mailbox Configuration form and creates Incoming and Outgoing mailboxes based on that information.
Step 2 After the administrator notifies the user base that the Email Engine is running,
Shelly composes an email instructing the Email Engine to perform a query of the HD Incident form. She uses specifically formatted instructions to be read and understood by the Email Engine. She sends this message to an email account on the company mail server that the Email Engine polls for incoming.
Chapter 1 Introduction to the Email Engine 21
Step 3 After waiting for a prescribed polling period, the Email Engine logs in to the
company mail server by using the email account information gathered during step 1. Because the mailbox information tells the Email Engine that this email account is to be treated as an Incoming Mailbox, the Email Engine reads the most recent emails from this account, by using one of several email protocols (POP3, IMAP4, MBOX, or MAPI), including the email that Shelly sent.
Step 4 The Email Engine interprets the instructions and translates them into API calls to
the AR System server, attempting to fulfill her query request.

Step 5 The AR System server responds to the Email Engine API calls with the appropriate
query information for the HD Incident form.

Step 6 The Email Engine uses the formatting instructions in the Outgoing Mailbox to
construct an email message to the company mail server. The Email Engine then transmits the message with instructions to send the message to Shelly, Mark, and Katie, by using the outgoing email protocol (SMTP or MAPI).
Step 7 Shelly, Mark, and Katie log in to the mail server, and they find the email
constructed by the Email Engine, which contains a neatly formatted list of the most recent requests. This example illustrates the relationship between the Email Engine and other systems in a simplified environment. Your environment might differ from the one presented here. 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. Many of the configuration options available are explained in the upcoming chapters. Also, as you proceed through this guide, you will learn about the other Email Engine features for processing email.
Improving the appearance of your email

The administrator at XYZ is pleased by the response of the AR System user community to the Email Engine. Users feel comfortable using email to query the AR System server and to submit and modify entries. However, he hears occasional grumbling in the hallway. Why is Email Engine so featureless? Can it not look more like email that comes from a favorite online auction website or online bookstore? Figure 1-4 on page 23 illustrates a solution, showing how the Email Engine can assign HTML templates to outgoing email.
22
Improving the appearance of your email
Figure 1-4: Templates dynamically assigned through workflow

Underlying Database
AR System Server
Server executes filter workflow that triggers Notify action. Urgent header template is dynamically assigned.
Email Templates
Field 1 Field 2 Field 3 Abcdefg Hijklm Nopqrst
Template Components
Email Engine
2
Email engine parses instructions. Instructions then translated into API calls to server. Incoming Mailbox Outgoing Mailbox
Email Engine
4
Email Engine
Outgoing email is assembled according to formatting instructions: HTML header template HTML result template Field values returned from server
Mail Server
Email account 1
Email account 2
Schema: HD Incident Action: Submit Impact: Urgent
Email Engine
Urgent email sent to incoming mailbox.
Urgent email sent to Francie Frontline
Shelly
Francie Frontline
Realizing the importance of AR System notifications, the administrator takes steps to replace the plain text email generated by the Email Engine. To improve its look and feel, he designs attractive HTML pages to use as header, footer, result, and content templates. He works with a graphic artist to create interesting bitmaps. Most important, he designs a data-driven workflow that dynamically assigns the correct templates based on the tickets impact. The templates are designed so that users can quickly tell whether a tickets impact is urgent, high, medium, or low.
Chapter 1
23
The following steps illustrate the scenario:

Step 1 Shelly is visiting an important client in Chicago. She 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 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.
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 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 from 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 66.
Multiple mail server support

You can configure multiple mail servers for an Email Engine installation. For each configured mail server, you can specify a failover mail server. If the mail server being used stops working, the Email Engine switches to the available failover mail server and continues processing mails. Figure 1-5 on page 25 depicts this functionality.
24
Multiple mail server support
Figure 1-5: Multiple mail servers configured for failover

AR System Email Mailbox Configuration Form Default Mail Server: M1 AR System Email Fallover Mail Server Configuration Form M1 M2 M3
Email Engine
M1 working?
Mail Server 1: M1 Yes
No Mail Server 2: M2 Yes
M2 available?
No
M1 working?
No
M3 available?
No
Error. Processing stops.
Yes
Yes Mail Server 3: M3
In the illustration, M1 is specified as the primary mail server, and M2 and M3 are specified as failover servers. If the Email Engine detects that M1 is not working, it checks whether M2 is available, and if so, it switches to M2. The Email Engine then tries to connect to M1, and if that is not yet working, it connects to M2. Then, if the Email Engine detects that M2 is not working, it checks for the availability of M1. If M1 is still not working, it looks for the failover server for M2, which is M3. If M3 is available, it switches to M3 and continues processing messages as described in the preceding note. If none of the configured mail servers is working, the Email Engine produces an error and stops processing.
Chapter 1
25
When switching from a server being currently used to its failover server, an entry is added to the stderr.log (Windows) or emaild.sh_log (UNIX) file. However, when switching back from the failover server to the primary server, no change is made to stderr.log or emaild.sh_log.
NOTE
The multiple mail server support is currently available for the SMTP protocol only.
Enhanced internationalization support

The Email Engine supports internationalization through UTF-8 encoded locales by default. To accommodate multi-byte languages, the Email Engine supports internationalization in all the entities and attributes. Unicode settings are applicable to both the incoming and outgoing messages. The email engine always sends outgoing messages in the UTF-8 format. For incoming messages, the email engine attempts to retrieve the CHARSET of the MIME messages that were received. If the email engine receives the CHARSET form, it uses the same CHARSET to display email messages, otherwise it uses UTF-8.
NOTE
You cannot change the default UTF-8 settings of the Email Engine.
NOTE
The Email Engine does not provide UTF-8 support for the MAPI protocol.
26
Chapter
Configuring Email Engine mailboxes

This chapter explains how to create and configure Email Engine mailboxes and how to set security options. A mailbox is an entry in the AR System Email Mailbox Configuration form that contains 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. To send and receive email, you must create and configure outgoing and incoming mailboxes. You can configure them during or after the product installation. To set up advanced mailbox options (such as default values, parsing, and mailbox security), you can update the configuration as discussed in this chapter. Configuration information is stored in forms on the AR System database. For more information about Email Engine forms, see Appendix D, Email Engine forms. The following topics are provided: Configuring outgoing mailboxes (page 28) Configuring incoming mailboxes (page 32) Testing your mailbox configuration (page 36) About email security (page 38) Saving outgoing notifications in MAPI (page 44) Changing the form entry interval time (page 44) Configuring SSL for the Email Engine (page 45)
Chapter 2 Configuring Email Engine mailboxes
27
Configuring outgoing mailboxes

You must create at least one outgoing mailbox to process outgoing mail, as described in this section. Figure 2-1 illustrates how to set a mailbox as the default outgoing mailbox.
Figure 2-1: Setting the default outgoing mailbox
Set default outgoing mailbox
The Email Engine creates and sends messages based on the configuration options that you specify in the AR System Email Mailbox Configuration form. Outgoing messages can include results from actions specified in incoming messages, such as query or workflow results. You can also link outgoing mailboxes to incoming mailboxes, to send the results of any actions from a specific incoming mailbox to a specific outgoing mailbox.
NOTE
To use notifications with email, you must designate one mailbox as your default notification mailbox. For more information, see Using notifications on page 54.
28
Basic outgoing mailbox configuration

Outgoing mailboxes support the MAPI and SMTP mail protocols.
To create a basic configuration for your outgoing mailbox

1 Open the AR System Email Mailbox Configuration form. 2 Enter the following information in the fields above the tabs:
Mailbox NameEnter a name that describes the function of the mailbox. For example, enter ARSystemEmail - Outgoing. Mailbox FunctionSelect Outgoing. StatusSelect Enabled.
3 In the Basic Configuration tab, select either SMTP or MAPI as the Email Server
Type, and set the following values in the remaining fields: MAPI (for 32-bit JVM only): Server TypeSelect MAPI. Polling IntervalSelect a polling interval for the Email Engine to check for new outgoing email from the BMC Remedy AR System server. Profile NameEnter the name of the Microsoft Exchange profile that you created during the product installation. This field is required because a profile is used to see the MAPI email account configuration information. For more information about Microsoft Exchange profiles, see your Microsoft Exchange documentation. SMTP only: Server TypeSelect SMTP. Polling IntervalSelect a polling interval for the Email Engine to check for new outgoing email from the BMC Remedy AR System server. Email Server Requires SSLSelect Yes to enable Secure Sockets Layer (SSL). For more information, see Configuring SSL for the Email Engine on page 45. Email Server Name/IPEnter the name or IP address of your companys mail server. Email Server PortEnter the mail server port number, or click Set Default Email Server Port to accept the default port. Email Server UserIf your mail server requires authentication information before sending email, enter the email account user name. Email Server PasswordEnter the password corresponding to the server user.
4 Click Save.
29
Advanced outgoing mailbox configuration

This section describes how to specify default settings for an outgoing mailbox, including default addressing and templates. You can do this by using the Advanced Configuration tab of the AR System Email Mailbox Configuration form as shown in Figure 2-2.
Figure 2-2: Advanced configuration for outgoing mailboxes
You can specify only one default template of each type for a mailbox. The AR System Email Templates form must already contain the templates.
NOTE
Review the information about advanced configuration settings in Chapter 5, Using email templates, on page 139.
To create an advanced configuration for your outgoing mailbox

1 In the Advanced Configuration tab of the AR System Email Mailbox Configuration
form, enter the following information in the fields above the tabs: Associated Mailbox NameEnter the name the existing mailbox that will receive instructions from this outgoing mailbox. Default Outgoing MailboxSelect Yes to make this outgoing mailbox route all emails that do not have a specified outgoing mailbox associated with them. Display NameEnter a descriptive name that appears in the From: line of outgoing emails. This option is not used with MAPI.
30
Email AddressEnter the email address of the server user that you created during the product installation. For example, if you entered a display name of ARSystem and an email address of arsystem@bmc.com, the From: line would be:
From: ARSystem [arsystem@bmc.com]
This option is not used with MAPI. Reply To AddressSpecify an email address where replies to your outgoing emails will be sent, or accept the default server user email address already in this field. This option is not used with MAPI. OrganizationIf your email client displays your organizations name, enter the name of the organization or company. Delete Outgoing Notification MessagesTo have workflow-generated notification messages deleted from the AR System Email Messages form after they have been sent from this mailbox, select Yes. To save workflow-generated messages in the AR System Email Messages form, or if you are going to use email templates to modify records, select No. System administrators or other users with the appropriate permissions must delete manual messages.
2 Specify Default Addressing for notifications and escalations:
Default ToEnter all email addresses that should receive outgoing messages from this mailbox if no other email address is specified in the message. 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. 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 Specify Default Templates for notifications and escalations:
Header TemplateEnter the name of the template to use for the message header if no other header template is specified. Footer TemplateEnter name of the template to use for the message footer if no other footer template is specified. Status TemplateEnter name of the template to use for the status if no other status template is specified. Result TemplateEnter the name of the template to use for the result if no other result template is specified.
4 Click Save.
For more information about notifications and escalations, see Defining workflow to send email notifications on page 55.
31
Configuring incoming mailboxes

Based on the information that you enter in the AR System Email Mailbox Configuration form, the Email Engine polls incoming mailboxes for new messages, processes the messages, parses the contents if necessary, and performs the actions specified in the messages, such as modifying requests or executing queries. Incoming mailboxes support the MAPI, POP3, IMAP4, and MBOX mail protocols.
Basic incoming mailbox configuration

Basic configuration for your incoming mailbox consists of you enter the following information in the Basic Configuration tab on the AR System Email Mailbox Configuration form: Mailbox information, such as the mailbox name Server information, such as the mail protocol associated with the server and the server port number
To create a basic configuration for your incoming mailbox

1 Open the AR System Email Mailbox Configuration form. 2 Enter the following information in the fields above the tabs:
Mailbox NameEnter a name that describes the function of the mailbox. For example, enter ARSystemEmail - Incoming. Mailbox FunctionSelect Incoming. StatusSelect Enabled.
3 In the Basic Configuration tab, select MAPI, POP3, IMAP4, or MBOX as the Email
Server Type, and set the following values in the remaining fields: MAPI (for 32-bit JVM only): Server TypeSelect MAPI. 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 Microsoft Exchange profile that you created during the product installation. This field is required because a profile is used to see the MAPI email account configuration information. For more information about Microsoft Exchange profiles, see your Microsoft Exchange documentation.
32
POP3 or IMAP4 only: Server TypeSelect either POP3 or IMAP4. Polling IntervalSelect a polling interval for the Email Engine to check for new incoming email from the mail server. Email Server Requires SSLSelect Yes to enable Secure Sockets Layer (SSL). For more information, see Configuring SSL for the Email Engine on page 45. Email Server Name/IPEnter the name or IP address of your companys mail server. Email Server PortEnter the mail server port number, or click Set Default Email Server Port to accept the default port. Email Server UserIf your mail server requires authentication information before sending email, enter the email account user name. Email Server PasswordEnter the password corresponding to the server user. MBOX only: 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 Click Save.
Advanced incoming mailbox configuration

During advanced configuration, you enter information about associated mailboxes, templates, and forms, and information related to mailbox security. You can do this by using the Advanced Configuration tab of the AR System Email Mailbox Configuration form as shown in Figure 2-3.
33
Figure 2-3: Advanced configuration for incoming mailboxes
NOTE
Review the information about advanced configuration settings in Chapter 5, Using email templates, on page 139.
To create an advanced configuration for your incoming mailbox

1 In the Advanced Configuration tab of the AR System Email Mailbox Configuration
form, select an outgoing mailbox from the Associated Mailbox Name list to reply to incoming emails that require responses, such as queries.
2 In the Action Configuration section, specify:
Email ActionTo enable the Email Engine to detect and process instructions included in an incoming email message, select Parse. If you use templates to perform Submit, Modify, or Query actions, you must select Parse. For more information about templates and parsing, see Using label/value pairs in templates on page 146 and Incoming and outgoing mail templates on page 141. Use Original Template Format (enabled for upgrades from BMC Remedy Mail Server)To enable original parsing system processing, select Yes. 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 you use this option, the Email Engine returns an error when it encounters these types of fields or formats. To use normal parsing, select No.
NOTE
If you select No, make sure that multiple lines in emails are encapsulated with the [$$ and $$] multiple-line delimiters.
34
Reply with ResultTo enable the Email Engine to return the results of an action in an email, select Yes. This option allows the email sender to know if the incoming email succeeded or failed. For more information, see Action label on page 149. Reply with EntryTo return the complete entry of a submit or modify action, select Yes. Enable Modify ActionsTo enable the Email Engine to modify existing entries, select Yes. Default Workflow FormEnter the name of the default form on which the Email Engine executes instructions such as queries, form-entry modifications, and form submittals, from the incoming email message.
NOTE
If you define a default workflow form, incoming templates do not require the Form (or Schema) label. For more information, see Form label on page 147. Force Default Workflow FormTo confine all instructions from the incoming email message to the form that you specified in the Default Workflow Form field, select Yes.
NOTE
If an incoming template specifies a schema, the schema will not be processed and the default workflow form will be used instead.
3 In the Incoming Security Configuration section, 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 that you want. Use Security KeySelect Yes to enable a security key for incoming email. 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 use this option, you must create and configure the security key. See Configuring incoming mailbox security on page 39. Use Supplied User InformationTo use AR System server login information from the incoming email message to execute instructions in the incoming message, such as instructions to modify requests or submit queries, select Yes. For more information about login syntax, see Login, Password, and TCP Port labels on page 147. Use Email From AddressTo use the senders email address as a form of authentication, select Yes. 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 Click Save. Chapter 2 Configuring Email Engine mailboxes 35
Testing your mailbox configuration

You must test your mailbox configurations to make sure that your mailbox communicates with your mail server correctly.
NOTE
If your Email Engine requires a security key to authenticate incoming email, skip this section and see About email security on page 38. Use the following procedures to verify that you can send email from your outgoing mailbox and receive email in your incoming mailbox. If you complete the steps successfully, your outgoing and incoming mailboxes are configured correctly. If you are unable to complete the steps, see Chapter 6, Troubleshooting, for more information. Before you perform the test, obtain the correct email address for your email account or profile from your email server administrator.
To test your outgoing mailbox

1 In the Basic Configuration tab of the outgoing mailbox you are testing, set the
Polling Interval to one minute, to view the test results promptly.

2 In BMC Remedy User, open the AR System Email Messages form in New mode. 3 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 Reply To: fields, a
subject line, and the body content.
NOTE
Choose an email address that you can access with a third-party utility, such as Microsoft Outlook.
4 Click Send. 5 Open the AR System Email Messages form in Search mode. 6 Perform a query for the email message that you sent. 7 In the results table, check for the following information:
An entry corresponding to the email message. The value in the Send Message column is Yes, as shown in Figure 2-4. A Yes value indicates that the outgoing mailbox has queued your email to be sent.
36
Testing your mailbox configuration
Figure 2-4: An email message entry in the outgoing queue
8 Open the AR System Email Mailbox Configuration form in Search mode. 9 After the time specified for the outgoing mailboxs polling interval, open the
AR System Email Messages form in Search mode.

10 Enter the name of the outgoing mailbox, and click Search. 11 In the results table, check for the following information:
An entry corresponding to the email message. The value in the Send Message column is Sent. The value in the Date Sent column is the precise time that the email message was sent to the mail server.
12 Using a third-party email client, verify that the message was sent to the To address
that you specified in step 3c on page 36.
To test your incoming mailbox

1 In the Basic Configuration tab of the incoming mailbox you are testing, set the
Polling Interval to one minute, to view the test results promptly.

2 In BMC Remedy User, open the AR System Email Mailbox Configuration form. 3 Search for the name of the incoming mailbox to test. 4 Make sure that the email account or profile that your incoming mailbox uses
matches the email account that you obtained from your email server administrator, and change the form entry if necessary.
5 In a third-party email client, create an email containing a subject line and body
content.
6 Send the email to the email address that you verified in step 4. 7 After the time specified for the incoming mailboxs polling interval, open the
AR System Email Messages form in Search mode.

8 Select a mailbox name and perform a search. The results table displays the entry
corresponding to the message you sent, as shown in Figure 2-5 on page 38.
37
Figure 2-5: 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 that you sent, which indicates a successful test.
About email security

Incoming and outgoing emails use different security mechanisms: For validation, incoming email messages use security keys, the users login and password, or the users email address. As long as the email has one of these security mechanisms, the Email Engine executes the appropriate action. You can configure the Email Engine to use all three methods; however, if the email message requests a modify action, only a security key can validate the users request. Outgoing email messages, which can include the results of query actions, use AR System access control for forms and fields. If a user does not have access to the field or form being queried, the field and its contents are not included in the outgoing email message. The following sections provide instructions for creating security keys for incoming email, describe how security is handled for outgoing email, and provide instructions for configuring the Email Engine to allow modify actions.
38
Configuring incoming mailbox security

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

1 In BMC Remedy User, open the AR System Email Security form in New mode. Figure 2-6: The AR System Email Security form
2 Enter the following information in the fields, as shown in Figure 2-7:
StatusSelect Enabled to activate the key. 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.
39
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. User NameEnter the name of a valid AR System user to which the security key applies. Force for MailboxTo enable the security key for this mailbox only, select Yes. To enable the key for all mailboxes in your email environment, select No. Mailbox NameEnter the name of the incoming mailbox to which the security key applies. Force from Email AddressesTo require this key for emails received from specific email addresses, select Yes. Allows the key to work only if it comes from the mailbox contained in the email addresses field. Email AddressesEnter the email addresses to which the security key applies, if you enabled the Force from Email Addresses key. ExpiresTo specify an expiration date for the key, select Yes. The Expiration Date field is enabled. Expiration DateEnter an expiration date for this security key. After the key expires, you can either modify the expiration date in this form or select No for the Expires field. DescriptionEnter a description of the key. For example, explain why the key was created or include instructions to modify or delete it.
Figure 2-7: The AR System Email Security form
40
Configuring outgoing mailbox security

Outgoing email messages, which can include the results of query actions, use AR System access control for forms and fields. If a user does not have access to the field or form being queried, the field and its contents are not included in the outgoing email message. The email server uses the following criteria to define security for outgoing emails that contain query results: An email sent to only one user can contain only data that the user has permission to view in BMC Remedy User. An email sent to more than one user can contain only data that the user with the most restricted permissions can view in BMC Remedy User. 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 are included in the email. If the system locks a record by using the row-level access feature, the record are included only if all email recipients have access to it. If an email that includes query results is sent to a nonregistered AR System user, the form and fields queried must have Public access, and the AR System server must be configured to allow guest users.
Configuring the Email Engine for replying with results

When you set the Reply with Result and Reply with Entry fields on the AR System Email Mailbox Configuration form to Yes, the Email Engine sends reply email back to the sender. The email contains the information that was submitted, queried, or modified on the form.
To configure the Email Engine for replying with results

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

4 Click the Advanced Configuration tab of the outgoing mailbox. 5 (Recommended for testing purposes) Set the Delete Outgoing Notification
Messages field to No.

6 Save your changes. 7 Click the Advanced Configuration tab of the incoming mailbox from which you
want the modify instruction sent.
41
8 Set the following fields as indicated:
Email Action: Parse Use Original Template Format: No Reply With Result: Yes Reply With Entry: Yes Enable Modify Actions: No Force Default Workflow Form: No
9 Set one of the following fields to Yes:
Use Security Key Use Supplied User Information Use Email From Address
10 Save your changes.
Configuring the Email Engine for modify actions

Modifications are executed by sending a modify instruction or modify action to the Email Engine. Typically, you want only trusted users making changes to records, especially if they are using email as a client to the AR System server. For security reasons, incoming email with modify instructions do not work by default; you must configure the incoming mailbox to accept modify actions.
NOTE
You must provide a security key for every user who sends modify instructions to the Email Engine.
To configure the Email Engine for modify actions

Search mode.
2 Search for and open the records for your incoming and outgoing mailboxes. 3 Make sure that you have an incoming mailbox and an outgoing mailbox associated
with each other.

4 Click the Advanced Configuration tab of the incoming mailbox to which you want
the modify instruction sent.

5 Set the Email Action field to Parse. 6 Set the Enable Modify Actions field to Yes. 7 Set the Use Security Key field to Yes. 8 Save your changes. 9 Click the Advanced Configuration tab of the outgoing mailbox from which you
want the modify instruction sent.
42
10 Set the Delete Outgoing Notification Messages field to No. 11 Open the AR System Email Security form in New mode. 12 Create a user record as follows: a Set Status to Enabled. b Create a security key. c Make sure that the Force For Mailbox field is set to No (default). d Select either Yes or No for the Force From Email Address.
This field enforces the email address that is associated with the key to be used. If set to Yes, the From Address of the reply sent by the user is checked against the security key entrys From Address.
e Enter other information as needed, for example, an expiration date.
NOTE
A user making modifications must have a write license unless that user is the submitter or the Submitter Mode is set to Locked.
Figure 2-8 shows Francie Frontlines security key in the AR System Email Security form.
Figure 2-8: A user entry in AR System Email Security form
Set security key
43
Saving outgoing notifications in MAPI

If you use the MAPI email protocol and you want to save messages on the Exchange server, you must configure your outgoing mailbox to save outgoing notification emails in an Outlook folder. To save outgoing notifications, add the following line to the EmailDaemon.properties file:
ARSystemServer.MAPI_Sent_Folder= folderName ARSystemServer is the name of the AR System server associated with the Email
Engine.
folderName is the name of the folder that stores the outgoing notification emails. For example, enter Sent Items to save messages to your Sent Items folder in
Microsoft Outlook.
Changing the form entry interval time

When the Email Engine starts, it retrieves all the entries in the AR System Email Mailbox Configuration form and creates incoming and outgoing mailboxes. Every 30 minutes, the Email Engine automatically queries the form for changes to the form entries and updates the information. To enable changes to form entries before the next default query time, stop and restart the Email Engine.
NOTE
Changes to the Status field are not reflected automatically. If you have changed the value of this field, you must restart the Email Engine for the change to take effect. To shorten the default time interval in the EmailDaemon.properties file, set the polling parameter. For example, shorten the time to 5 minutes:
ARSystemServerName.Interval = 5
For more information about this property or the EmailDaemon.properties file, see Performance and configuration settings on page 182.
44
Configuring SSL for the Email Engine

Enterprise and stand-alone certification authorities (CAs) can issue certificates for secure email by using SSL. This section explains in general terms how to configure the Secure Sockets Layer (SSL) for use with Email Engine. There is no one size fits all CA solution. You must consider various factors when using SSL, for example, what CA to use. Configuration differs considerably between using a commercial CA authority like VeriSign and using a certificate server in a non-active directory environment using Microsofts Certification Authority management console.
NOTE
SSL is an open standard that Netscape Communications developed to establish and protect web communications and prevent the interception of critical information such as credit card numbers.
Figure 2-9: A digitally signed email message that uses SSL
Digitally signed message indicator in email message
To configure SSL for Email Engine

1 Set up a local CA or search for a CA to use with your mail server.
You must decide whether to use a commercial CA (for example, VeriSign) or use a CA created in-house. Most Windows system administrators can set up a CA on a Windows server in just a few minutes. The primary difference between a commercial or in-house CA is that a cert (certificate) issued by VeriSign is trusted far and wide, while a cert issued by an in-house CA is not trusted by anyone outside the organization.
45
2 In Microsoft Exchange System Manager (used by a Microsoft Exchange system
administrator only), return the properties for the IMAP virtual server.
a Use the Certificate Wizard to generate a cert request.
For the detailed procedure, see To generate a Certificate Signing Request (CSR) for a Microsoft Exchange server on page 47.
b Submit the cert request to the CA.
The procedures required to submit and receive a cert from a CA vary, depending on the CA. For more information, see To create a CA certificate from a CSR on page 48.
c Use the Certificate Wizard to install the cert received from the CA.
For more information, see To add an SSL certificate to a Microsoft Exchange server on page 49.
3 Make sure that email users obtain their own certificate. a Through the CA, generate a personal certificate that users will use for signing
and encrypting their email messages. With a local CA, you can retrieve and install the cert using a browser.
Figure 2-10: Selecting a cert to use with your IMAP account
b In the email client, open the Properties dialog for your IMAP account and select
the new cert to use for signing and encrypting email messages. 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.
46
Figure 2-11: A signed email message
Buttons in mail client used for signing and encrypting messages
Outlook Express provides the facility to sign and encrypt messages. 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.
To generate a Certificate Signing Request (CSR) for a Microsoft Exchange server

1 In Microsoft Exchange System Manager, expand Servers > the appropriate server
name > Protocols > IMAP4, and select Default IMAP4 Virtual Console. The same procedure applies to POP3 and SMTP.
2 On the Default IMAP4 Virtual Server Properties dialog, open the Access tab, and
click the Certificate button.

3 On the Web Server Certificate Wizard: a On the first page, click Next. b On the Server Certificate page, select Create a new certificate if you have not yet
created an SSL certificate for your web server, and click Next. If you already have an SSL certificate for your web server, select Assign an existing certificate, and click Next. A list of the existing SSL certificates installed on your web server appears; select the appropriate certificate and generate a CA from the CSR.
c On the Name and Security Settings page, enter a unique name for the certificate,
select 1024 as the bit length, and click Next. If you plan to install the trial certificate from VeriSign, do not select the Server Gated Cryptography (SGC) certificate check box. For more information about SGC, see your CA documentation on SSL algorithms.
47
d On the Organization Information page, select an Organization and the
Organizational unit, and click Next.

e On the Your Sites Common Name page, enter the common name for your site.
You can access the Microsoft Exchange server with this common name. This name will also be used to configure SSL on Outlook Express. Do not enter an IP address as the common name, otherwise the CA would create the SSL certificate successfully.
f On the Geographical Information page, select the appropriate Country/Region,
State/province, and City/locality, and click Next.

g One the Certificate Request File Name page, enter the absolute path and file name for the CSR (for example, certreq.txt), and click Next.
Make sure that you provide a location that is easy to remember and access.
h On the Request File Summary page, verify the information you provided so far,
and click Next if the information is accurate. Otherwise, click Back to navigate to the appropriate pages and change the necessary values.
i On the final page, click Finish to complete the process and close the wizard.
To create a CA certificate from a CSR

1 Open a browser and navigate to https://www.verisign.com/prod/srv/trial/ step1.html. 2 Enter the information required to create the trial SSL certificate. 3 When prompted for the CSR, copy the contents of certreq.txt file in the
appropriate text area.

4 Upon completing the steps, a certificate is generated and sent to the email address
that you entered in your information form.

5 Open a new file in a text editor, and copy the following contents from the email
you received from VeriSign:

-----Begin Certificate----<Encoded data> ... ... -----End Certificate-----
Make sure that you do not select blank lines or spaces before -----Begin Certificate-----and after -----End Certificate-----.
6 Save the file with the .cer extension, for example, web.cer.
48
To add an SSL certificate to a Microsoft Exchange server

name > Protocols > IMAP4, and select Default IMAP4 Virtual Console.
click the Certificate button.

3 On the Web Server Certificate Wizard: a On the first page, click Next. b On the Pending Certificate Request page, select Process the pending request
and install the certificate, and click Next.

c On the Process a Pending Request page, enter the absolute path and file name
that you provided when creating the CSR, and click Next.
To enable SSL communication on a Microsoft Exchange server

name > Protocols > IMAP4, and select Default IMAP4 Virtual Console.
click the Communication button.

3 On the Security dialog, select Require secure channel, and click OK.
If you plan to install the trial certificate from VeriSign, do not select Require 128-bit encryption.
To set up Microsoft Outlook Express and Email Engine

1 To use IMAPS (IMAP over SSL) for Outlook Express, open a browser and navigate to http://www.verisign.com/products-services/security-services/ssl/ buy-ssl-certificates/free-trial/test-root-ca/trialcainstall.html.
Follow the prompts on the screen and install the test root CA on the computer where you want to configure Outlook Express. When prompted to enter the IMAP server address, you must provide the common name you entered while creating the CSR. If you provide any other value or an IP address, the CN does not match with passed value warning appears.
2 To configure Email Engine to use SSL, import the test root CA certificate in
keystore by using following command:

javaHome\bin\keytool -import -alias testroot -keystore javaHome\lib\security\cacerts -file certFilePath/testroot.cer javaHome is the directory where JRE (not JDK) is installed.
NOTE
Find the appropriate keystore path before entering the command. Email Engine uses the location where Oracle Java Runtime Environment (Oracle JRE) is installed as the keystore path.
49
50
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: How outgoing email works (page 52) Using outgoing email (page 53) Using notifications (page 54) Using the Email Messages form to send outgoing email (page 74) Sending reply email: Giving a professional look to outgoing email (page 89) User-defined HTML or XML text in outgoing HTML emails (page 102)
Chapter 3 Outgoing email
51
How outgoing email works

Figure 3-1 presents a sample scenario that demonstrates how the Email Engine sends outgoing notifications.
Figure 3-1: How the Email Engine sends outgoing email notifications
Underlying Database AR System Server HD Incident
Email Engine
Escalation
AR System admin defines SLA
Server executes escalation workflow that triggers Notify action
Email messages
To: From: Message: Abcdefg Hijklm Nopqrstuvwxyz 1234567890
Outgoing records
Email Engine
Outgoing Mailbox
3
Mail Server
Outgoing email is formatted and assembled
Email account
User receives urgent ticket assigned to him
Bob Backline
In this scenario, John, the local AR System administrator, has decided to test the notification capabilities of the Email Engine.
Step 1 In the XYZ Company, the IT department has a service-level agreement (SLA) that
urgent HD incident tickets must have a response in one hour. The AR System 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 cannot respond to one of the urgent request in one hour. As a result, the AR System server triggers an escalation.
Using outgoing email
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 28 Defining workflow to send email notifications on page 55
Using outgoing email

NOTE
The examples of outgoing email in this chapter make extensive use of label/value pairs, aliases, variables, templates, and special keyword syntax as message content; the Email Engine ignores any other text. For more information, see the detailed reference material and examples of their use in Chapter 5, Using email templates. This section describes the different types of outgoing email in the Email Engine: NotificationsThe most important use of outgoing email is using workflow to send notifications to users. 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 54. Replies to sendersA common function of outgoing email is making replies to senders (who send email to the incoming mailbox) with results. When you created an incoming mailbox, one crucial task you performed was associating an outgoing mailbox, specifically for the purpose of replying to emails that require a response, for example, query results. For more information, see Sending reply email: Giving a professional look to outgoing email on page 89.
53
Messages formYou can 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 never sees or needs this form. For more information, see Using the Email Messages form to send outgoing email on page 74.
Using notifications
The most important use of the Email Engine is sending notifications to users because 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 3-2 illustrates a notification that a ticket was created and sent to a user. In the notification email, users can then click a URL to open the ticket in a browser and view additional details about the ticket.
Figure 3-2: An email notification sent by the Email Engine
User clicks direct access URL in notification email
Direct access URL opens email ticket in browser (also formatted in HTML)
54
Using notifications
If you choose Email as the delivery mechanism when creating a Notify filter or escalation, you can send the following types of information in an email notification: Text messages Contents of selected fields (if the user being notified has the appropriate permission for those fields) Attachments (if an attachment field exists on the form) Shortcut (if you select the Add Shortcut option in the Notify dialog box, a shortcut is 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 Email Engine. The Email Engine can be installed on a separate server from the AR System server processing the workflow. When you install Email Engine, point to the AR System server you intend to use. For more information about using filter or escalation workflow, see the Form and Application Objects Guide.
NOTE
If you create notifications using the Submit execute condition with join forms, the fields returned in the notification message will not be populated. This is because there is no Request ID with join forms during a Submit operation.
Defining workflow to send email notifications

When the filter or escalation is triggered (for example, from a filter submit or modify action, as shown in Figure 3-3 on page 56), the AR System server logs a message containing the notification text (and, optionally, field contents) on the AR System Email Messages form. The Email Engine then picks up the entries from the form, processes them, and sends the email notifications to the designated user or group.
55
Figure 3-3: The Filter window
In a Notify action from filter or escalation workflow (see Figure 3-4 on page 57), 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 Education Services. This webcast includes .def and data files you can download and modify for your own use. For more information, see the Education link at http://www.bmc.com. The 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.
To define workflow to send email

1 Make sure that you have an outgoing mailbox configured with Default Outgoing Mailbox set to Yes, or set Mailbox Name in the workflow to the configured
outgoing mailbox. Otherwise, you will not receive any notifications. For more information, see Chapter 2, Configuring Email Engine mailboxes.
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.
56
Using notifications
Figure 3-4: The Notify filter or escalation action
5 In the Text field, enter the text of the message.
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 3-5 demonstrates the use of a 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 URL appears in the notification email as a link that the user clicks to display the ticket in a browser (as shown in Figure 3-2 on page 54).
Figure 3-5: A direct access URL used in email notification
Direct access URL
For more information about creating and using URLs, see the BMC Remedy Mid Tier Guide, URLs for forms and applications, page 76.
57
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 3-9 on page 62). 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 Email addresses Include the email domain name if you are entering an 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.
8 To set properties in the EmailDaemon.properties file so that the Email Engine
sends high-priority emails first and then lower priority emails, change the following property as shown:
SortMessages=true
For more information about using the EmailDaemon.properties file, see Performance and configuration settings on page 182.
9 From the Mechanism field, select Email. The Fields, Messages, and Templates tabs
are activated. For more information, see Defining fields in email notifications on page 59 and Using the Messages and Templates tabs on page 61.
10 Select the Add Shortcut check box to include the originating request as an ARTask
attachment in the email that is sent.

11 Save the filter or escalation.
58
Using notifications
Defining fields in email notifications

Use the Fields tab to define the subject line of the email and to indicate which fields (if any) to include in the body of the email.
Figure 3-6: Subject line and fields in an email notification
Subject line of email
Fields included in email
To define the Fields tab

1 Enter the text that will appear in the subject line of the email.
Subject text can include the use of keywords, for example, $USER$. The field or keyword will be expanded when the notification is sent. If you enter a field name in the Subject Line field, the notification will contain the value of the field in the database. You can enter a maximum of 255 characters.
2 Select which fields have the content you want to select in the email (in addition to
the notification text).
NOTE
The Request ID of entries from display or vendor forms are not returned in notifications. The options are: NoneNone of the fields is included with the notification. AllAll of the fields in the request are included with the notification. SelectedSelected fields from the fields list are included with the notification. ChangedOnly fields that have changed in the current transaction are included with the notification.
NOTE
If you use a content template to format the email, the template will override any of the options that are selected. For example, if an administrator selected All, but the template only uses a few fields, only the fields in the template appear in the email.
59
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 156.) To be able to send the field contents, make sure that users being notified have the necessary permissions. See the Form and Application Objects Guide, Defining access control, page 21. The order of fields included in an email notification is strictly based upon their arrangement in the form view. Using their X and Y coordinates, the order of fields begins top left to right, then down (in a zigzag-like pattern). Fields excluded from the forms default view are randomly included at the bottom of the list. If a form includes page fields, the pages are ignored. The order of fields included in the notification is still based on their actual X and Y coordinates in the form.
3 To include attachments in an email notification, select the attachment fields from
the Fields list.

Figure 3-7: Including attachments with notifications
Attachment fields you can include in notifications
Make sure the receiver of the notification has permission to the attachment field on the AR System form. Figure 3-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 70.)
60
Using notifications
Using the Messages and Templates tabs

The Messages and Templates tabs allow you to determine at run time which user the email came from, which mailbox to use, which templates to use, and so on. The fields in these tabs are optional. If you leave these fields blank, the settings relating to the mailbox entered in the Mailbox Name field apply. Or, if the Mailbox Name field is empty, the default outgoing mailbox settings apply. The default outgoing mailbox is the first mailbox created, or you can specify another mailbox in the AR System Email Mailbox Configuration form. Any entries in the fields in the Messages and Templates tabs will override the default settings. If there are no entries in the Messages and Templates tabs, and no default mailbox exists, an error message will be generated.
Figure 3-8: The Notify filter or escalation dialogMessages tab
Defining messages in email notifications

Use the Messages tab to override your mailbox configuration settings for the Notify action. If you leave these fields blank, the values in your notification email default to your current mailbox configuration settings.
To define the Messages tab

1 In the Mailbox Name field, enter the name of the outgoing mailbox that you want
to handle the notifications if you do not want to use the default mailbox. You can use a field or a keyword to substitute the mailbox name. This mailbox name should correspond to a valid mailbox configured in the AR System Email Mailbox Configuration form.
61
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. The maximum size of these fields is 255 characters. You can use the following entries in the fields: AR System user logins AR System groups 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 Email Engine populates the equivalent fields in the AR System Email Messages form for the appropriate User Name (Figure 3-9).
Figure 3-9: The AR System Email Messages form
However, if the information for these fields in the AR System Email Messages form is supplied from the AR System Email Mailbox Configuration form (that is, a specified mailbox, or a default mailbox that has already been configured), you need to display and save the AR System Email Messages form before you see the entries.
3 In the From field, enter the name to be displayed to indicate where the mail is from.
If this field is blank and there are no entries in the From field on the Advanced tab of the AR System Email Mailbox Configuration form for the specified mailbox, or for the default mailbox, there will be no entry in the email to indicate who the email is from.
62
Using notifications
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 3-4 on page 57), the name or names specified in the CC and BCC fields on this form will appear only in the CC and BCC fields of the AR System Email Messages form entry for the first user listed in this User Name field. The permissions applied to the recipients of the CC and BCC fields will be the same as those of this first listed user. This might be a security issue, especially if you list a group name with some ambiguity about which is the first name on the list. You might list names individually in the User Name field so that you have more control over the permission status.
6 In the Organization field, enter a company name, an organization, a keyword, or a
field reference to a name that you would like to appear on the email.
Defining templates in email notifications

Use the Templates tab to define any templates to use in the email. If you leave these fields blank, the values in your notification email default to your current mailbox configuration settings. You could create workflow that substitutes a specially designed urgent template to alert a manager to the emails importance. Figure 3-10 on page 64 illustrates an email sent by the Email Engine if an urgent ticket is created and no user is assigned (( 'TR.Impact' = "Urgent") AND ( 'Impact' != 'DB.Impact') AND ( 'Assigned To' = $NULL$ )).
63
Figure 3-10: An Urgent email generated by the 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 66.
To define the Templates tab

1 In the Header, Content, and Footer fields, specify the names of the templates to use
for a header, content, or footer of the email notification. You can enter the name of the template directly, or enter a field reference or keyword that leads indirectly to a template name. The templates specified here must be stored in the AR System Email Templates form, and the name must be the same as that entered in the Template Name field of the AR System Email Templates form.
64
Using notifications
Figure 3-11: The Notify filter or escalation dialogTemplates tab
For more information about creating and using templates, see Chapter 5, 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 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$$#
To create a content template to show Status History when doing email notifications, represent the Status History in the following formats:
#$$Status History.New.USER$$# #$$Status History.Closed.TIME$$#
These formats are based on AR System core field ID 7. The Status History strings shown here as examples could also be displayed languages other than English.
NOTE
You cannot use AR System keywords in content templates for outgoing emails in notifications.
2 Click Add Action, and save your changes to the filter or escalation.
The system determines which templates to use in the following order:

a The template entries in this tab. b The templates set as defaults for the mailbox entered in the Mailbox Name field
of the Messages tab of the Notify action dialog box. (See Figure 3-8 on page 61.)
65
c The templates set as defaults for the default mailbox. d No templates are used.
If no template is used for the Content, the order of fields included in an email notification is strictly based upon their arrangement in the form view. Using their X and Y coordinates, the order of fields begins top left to right, then down (in a zigzag pattern). Fields excluded from the forms default view are randomly included at the bottom of the list. If a form includes page fields, the pages are ignored. The order of fields included in the notification is still based on their X and Y coordinates in the form.
Dynamically assigning templates to outgoing email

The Email Engine gives developers more control over the content and format of email sent from AR System. Content creation and formatting (including the use of graphics) are accomplished by designing and storing the templates and images in the AR System Email Templates form. The Email Engine then uses templates stored in this form to format outgoing email. The Notify filter and escalation 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 63, 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.
Table 3-1: The 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.
66
Using notifications
The following procedure assumes your Email Engine is properly configured, your users have their own email mailboxes set up, and you have created and stored your templates. 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 the incident form Filter using Set Fields and Notify actions Search menu for template form (optional)
To dynamically assign templates to outgoing email

1 Create a regular form (for example, XYZ Templates). 2 Add a selection field to the XYZ Templates form.
This field should use the same attributes you plan to use to determine template assignment. In this example, the Impact selection field attributes are usedLow, Medium, High, and Urgent.
3 Create a character field (for example, Template Name) to store the value of the
template to be used.
4 (Optional) Attach a character field search menu that queries the AR System Email
Templates form as a further enhancement.

5 Log in to BMC Remedy User and open the XYZ Templates form in New mode. 6 Create the records for each Impact type, selecting the proper value for the
Template Name field. Four records are createdone for each of the impact values. Figure 3-12 illustrates that the Urgent impact type uses the Header_Urgent.html template.
67
Figure 3-12: Template records
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 3-13). This field stores the name of the header template to be used with each incident when it is created or modified.
Figure 3-13: A form with hidden fields
Hidden fields to store templates
68
Using notifications
9 Create a filter to set the value for the Header Template field on the XYZ Incident
form.
a In the Basic tab, select XYZ_Incidents as the form. b Select Submit and Modify as the execute conditions. c Enter 'TR.Impact' != $NULL$ as the Run If qualification.
Here you want the filter to fire on Submit or Modify whenever the value of the Impact field changes (that is, when the filter detects there is a new transaction value in the Impact field).
10 In the If Action tab, create a Set Fields action with the following parameters: a Read the value for the field from the XYZ_Templates form. b Enter 'Impact' = $Impact$ as the Set Fields If qualification. c Select Header Template as the field name and $Template Name$ as its value.
With this workflow, the name of the proper template, based on its impact, is stored with each incident. Here you define the filter to query the XYZ Templates form created earlier where Impact = $Impact$, and you set the value of the Header Template field on the XYZ Incident form from the value of the template name field on the XYZ Templates form.
11 On the filter, create a Notify action. a Place the variable $Header Template$ in the Header field. b Enter other parameters as needed, for example, $Submitter$ as the user name,
relevant text (including request ID of the ticket), and so on. The result of this filter is data-driven automatic template assignment workflow.
12 In the XYZ Incidents form, create a new ticket (for example, for Joe User) and
assign it an urgent value. The filter workflow executes and creates a new ticket. This workflow will also create an email notification with the proper header template dynamically assigned based on its impact level. When Joe User opens his email client, he receives the following email:
69
Figure 3-14: An email notification with the Urgent header template
You could enhance this with a content template used specially for urgent tickets.
Displaying date/time or numeric values in email notifications

When the AR System server sends data to a client with a different locale, the format for numeric and date/time data might change to accommodate the client locale. For example, date/time or numeric values stored on the AR System server have a decimal separator, but when this data is relayed to a German client, the decimal separator is displayed as a comma. Email notifications do not go through this client transition; therefore, the data in the notification is in the same format as that stored on AR System server. This might result in incorrect date/time and numeric values being displayed in a notification to different locales. For more information, see Submitting requests across different time zones on page 208.
Deleting email notifications

Using the AR System Email Mailbox Configuration form, you can configure your email system to automatically delete notification messages from the AR System Email Messages form after they have been successfully sent. This default setting reduces the number of records stored in your message form.
70
Using notifications
TIP
Most of the time, you will use the AR System Email Messages form for troubleshooting the Email Engine. When you first start using the Email Engine, you might not want notifications automatically deleted to make sure they are sent to the expected users, outgoing email is formatted correctly, and so on. But after your Email Engine is running correctly, you should automatically delete email notifications, unless you are using email templates to modify records; otherwise, your server can quickly fill up with email notifications. If you configure the system to delete messages automatically, the Email Engine will not permit you to modify records. The Email Engine includes a security feature that checks the outgoing records to verify that incoming email with a modify action comes from the same server.
To delete email notifications

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

Figure 3-15: Option to delete outgoing notification messages
2 Set the Delete Outgoing Notification Messages field to Yes. 3 Save your changes.
For more information about configuring the email system, see Advanced outgoing mailbox configuration on page 30.
Using templates with outgoing email

Email templates can help you with outgoing mail from the Email Engine, for example, with email generated from notification actions or escalations. A mail template exported with BMC Remedy Developer Studio lists all the available field labels you could use, for example, in creating an outgoing email.
NOTE
Replies to incoming email are not discussed in this section. For information, see Sending reply email: Giving a professional look to outgoing email on page 89.
71
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 Developer Studio. 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 Email Engine 7.0.00 and later. As a result, $USER$ or $DATABASE$ in a content template will not be replaced with actual values. Field IDsField IDs are not substituted with entry values. As a result, #$$536870925$$# is incorrect. Instead, you should use #$$Id_Integer$$# where Id_Integer is the database name of the field. The following example illustrates a content template for outgoing notifications:
#$$AR Notification Text$$# CORE FIELDS: ----------------RequestId: #$$Request ID$$# EmployeeName:#$$Name_Char$$# Submitter:#$$Submitter$$# ShortDescr:#$$Short Description$$# LastModifiedBy:#$$Last Modified By$$# Modified Date:#$$Modified Date$$# Status:#$$Status$$# StatHist-User:#$$Status History.New.USER$$# StatHist-Time:#$$Status History.New.TIME$$# Employee Info General Fields: -----------------------------Employee Name : #$$Name_Char$$# Employee Id: #$$Id_Integer$$# Employee Salary in Decimal : #$$Salary_Decimal$$# Employee Salary in Currency : #$$Salary_Currency$$# 72 BMC Remedy Email Engine Guide
Using notifications
Employee Gender : #$$Gender_Dropdown$$# Employee Marital Status : #$$Marital Status_Radio$$# Employee Interests: #$$Interests_Dairy$$# Employee Skills : #$$Skills_CheckBox$$# Employee Vacation Left : #$$Vacation_real$$# PresentOrPermAddChoiceField : #$$PresentOrPermAddChoiceField$$# Joining Details: --------------JoiningDate_Date : #$$JoiningDate_Date$$# JoiningDateTime_DateTime : #$$JoiningDateTime_DateTime$$# Joininig Date_Time : #$$Joininig Date_Time$$#
XML outgoing content templates

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

You can specify outgoing content templates in HTML format. HTML outgoing content templates can contain graphic images. The following code is an example of HTML outgoing content template that contains a GIF image:
<html> <head> <meta http-equiv="Content-Language" content="en-us"> <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> <meta name="ProgId" content="FrontPage.Editor.Document"> <title>Lighthouse</title> </head> <body> <p><font face="Arial Black"> #$$AR Notification Text$$# </font></ p> <p><img border="0" src="./images/lighthouse.gif" width="174" height="188"></p> <p><font face="Arial Black"><b>Lighthouse</b></font></p> <p><font face="Arial Black"> RequestID: #$$Request ID$$# </font></ p>
73
<p><font face="Arial Black"> EmployeeName:#$$Name_Char$$#</font></ p> </body> </html>
Using the Email Messages form to send outgoing email

You can use the AR System Email Messages form to send outgoing email, as shown in Figure 3-16.
Figure 3-16: AR System Email Messages form
You can type the message, or specify content templates to use in the body of the email. To send email from the Email Engine, you must use a specific label/value pair syntax along with the Action label in the body of the email. 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 81.)
WARNING
When sending HTML messages, any content in Plain Text Body tab is ignored. To send plain text messages, make sure that all the required content is in the Plain Text Body tab and that the HTML Body tab is empty.
74
Sending outgoing email in plain text

You can use the Email Engine to send outgoing email in plain text. Plain text email can include the results of queries, submissions, or modifications to entries contained on your AR System server. These emails can be formatted using templates that specify the layout of a message in plain text, HTML, or XML.
To send outgoing email in plain text

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

Figure 3-17: AR System Email Messages form (displayed in browser)
TIP
To view the AR System Email Messages form in a browser, use this syntax: http://hostName/arsys/forms/serverName/formName. For more information, see the BMC Remedy Mid Tier Guide, URLs for opening forms and applications, page 76.
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 28.)
3 Select Outgoing from the Message Type list. Chapter 3 Outgoing email 75
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 Optionally, enter a priority number between 1 to 100 in the Priority field.
Use the following table to determine what value to use in the email message within AR System to get the desired Microsoft Outlook priority.
Table 3-2: Email Engine priorities mapped to Microsoft Outlook priorities Email Engine Priority 0 1 2 3 4 ... 100 Microsoft Outlook Priority Normal High importance High importance Normal (default) Low importance ... 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):
SortMessages=false
To use the priority:

SortMessages=true
For more information about using the EmailDaemon.properties file, see Performance and configuration settings on page 182.
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 5, Using email templates. To add an attachment, see Including attachments with outgoing email on page 79.
76
To send the email with a template other than the default templates for the specified mailbox, see Using the Templates tab on page 82. 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 83.
8 Click Send to send the mail from the outgoing mailbox to the user.
Sending outgoing email in HTML

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

1 Open the AR System Email Messages form in New mode to create an outgoing
message. For sample contents of an outgoing message, see Using the Email Messages form to send outgoing email on page 74.
2 Click the HTML Body tab. 3 Enter HTML content, as shown 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 5, Using email templates.
77
For how to define HTML, especially input type controls, see any standard HTML reference book or reputable online source (http://www.w3.org/). Additional HTML examples are demonstrated in Sending modify instructions in HTML on page 122.
The Email Engine generates the email, as shown in Figure 3-18.

Figure 3-18: An outgoing email in the 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 3-19.
Figure 3-19: A 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.
For information about encoding user-defined markup text in outgoing email messages, see User-defined HTML or XML text in outgoing HTML emails on page 102.
Including attachments with outgoing email

Attachments are sent with an email using the AR System Email Messages form and the AR System Email Attachments form. The AR System Email Attachments form (see Figure 3-21 on page 80) stores attachments for incoming and outgoing emails. It also stores attachments for templates, such as a graphic for an HTML template. The system associates the attachment with a specific email in the AR System Email Association form.
NOTE
Having a large number of records in the email messages and email attachment forms might degrade the performance of the Email Engine.
To add attachments to your email

1 In the AR System Email Messages form, click the Attachments tab (Figure 3-20 on
page 79).
Figure 3-20: The AR System Email Messages formAttachments tab
79
2 Click Add Attachment to open the AR System Email Attachments form (Figure 3-
21).
Figure 3-21: The AR System Email Attachments form
Attachment pool
3 Select Email from the Type list. 4 Right-click in the attachment pool and choose Add from the menu.
The Add Attachment dialog box appears.

5 Browse to the file you want to add and select it. 6 Click Open.
The file is added to the list of attachments. If you are using a Windows system, you can also drag and drop a file into the attachment pool.
7 Enter a name for the Attachment in the Attachment Name field.
If you do not specify a name, the system will see the attachment by its file name and location. To change the name:
a Select the item in the attachment pool, and click the edit button in the
Attachment Name field. The name of the attachment is displayed in the Attachment Name field.:
b Edit the file name as needed. 8 Click Save.
To add previously saved attachments to email

1 In the Attachments tab of the AR System Email Messages form, click the arrow
next to the blank field at the bottom of the pane.

2 Select the attachment. 3 Click the Add Existing button.
Your attachment is added to the list in the attachment pool. When you send or save your email, the email and the attachment are associated through the AR System Email Association form. The system will assign the association a unique ID.
80
Modifying an attachment
Use the following procedure to modify attachments in outgoing email.
To modify attachments
1 Click the Attachments tab in the AR System Email Messages form. 2 Select the attachment you want to modify. 3 Click the Modify Attachment button to open the AR System Email Attachments
form.
4 Click Search to locate the attachment.
The attachment appears on the attachment list.

5 Modify the attachment as required. You can also modify the Attachment Name. 6 Click Save to save your modification.
Deleting an attachment
Use the following procedure to delete attachments in outgoing email.
To delete attachments
1 Click the Attachments tab in the AR System Email Messages form. 2 Select the attachment you want to delete. 3 Click Delete Attachment to open the AR System Email Association form. 4 Close this form. 5 Click the Refresh Table button to refresh the table in the Attachments tab of the
AR System Email Messages form. The attachment is deleted from the list.
Displaying advanced options for outgoing email

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

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

The Advanced Options tab lets you replace templates, add variables, or use alternative attachments.
Using the Templates tab

The Templates tab enables you to include a content, header, or footer template with your outgoing email: Content templates replace the body of the email so that you do not have to enter anything in the body tab of the AR System Email Message form. The content can be associated with a specific form and contain the fields and their corresponding values relating to a specific record. You can create these templates in a text editor or export them using BMC Remedy Developer Studio. You can also specify actions to be performed when the Email Engine parses contents of the email. The content template can also contain formatting instructions. Header and footer templates are 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 Template fields blank, the system uses the default templates for the mailbox in the Mailbox Name field, or it uses the default mailbox and its settings if no Mailbox Name is entered. The template specified here will override those configured for the specified mailbox, or the default mailbox. For information about configuring your outgoing mailbox, see Configuring outgoing mailboxes on page 28.
To add templates to outgoing email

1 In the outgoing message, display the advanced options. 2 Click the Advanced Options tab, and then click the Templates tab. 3 Select templates from the relevant menu lists, or enter the name of a template as
defined in the AR System Email Templates form.
82
Figure 3-22: The AR System Email Messages formAdvanced Options, Templates tab
Using the Variable Replacement tab

The Variable Replacement tab (Figure 3-23) enables you to replace any variables in the template with a value at the time of execution. This applies only to the specific outgoing email and the templates specified in the Templates tab.
Figure 3-23: The AR System Email Messages formAdvanced Options, Variable Replacement tab
83
You can use the Field Values field or the Qualification field with a particular form to retrieve required data and substitute it in the email.
To replace a field value using a variable replacement

1 Create an outgoing message. 2 Fill in header information. 3 Enter Yes in the Display Advanced Options field. 4 Click the Advanced Options tab. 5 Click the Templates tab. 6 Select a content template.
For example, this content template (which modifies an entry) uses the following label/value pairs:
Server: polycarp Login: Password: Key: Action: Modify Form: TestSecurityForm Request ID: [$$#$$Request ID$$#$$] Submitter !2!: Short description !8!:
This template includes a variable value for the Request ID field by replacing the Request ID: 00000000001 label/value pair with Request ID:[$$#$$Request ID$$#$$].
7 Click the Variable Replacement tab. 8 Enter a value for a variable in the template in the Field Values field, as shown in
Figure 3-23. For example, with the following variable in your template:
Short Description !8!: #$$Short Description$$#
you would enter in the Field Values field:

!Short Description!: Create entry for new hire.
This value will then be substituted for the variable when the outgoing email is sent. When an entry is created in the Email Messages form for the outgoing message, the Field Values field of the Variable Replacement tab is populated with the database name of the field and its value in the entry. This database name is matched with the database name that is specified within #$$$$# in the content template, and a substitution is made accordingly. So, make sure to use the exact database name in the content template delimited by #$$$$#.
84
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.
9 Enter the name of the server on which the form resides. 10 Enter the name of the AR System form to which these values apply. 11 Enter any access information necessary in the AR System Server TCP Port field and
the AR System Server RPC Number field.

12 Enter a qualification in the Qualification field to search for the Request ID of a
record on which you want to perform an action (Figure 3-24 on page 85). This action will be specified in a Content template.
Figure 3-24: The AR System Email Messages formAdvanced Options, Variable Replacement tab
13 Send the outgoing email.
The Email Engine searches the specified form for the record, and then it substitutes the Request ID parameter in the Content template with the Request ID value (00000000001) found with the query (Figure 3-25).
85
Figure 3-25: An email messages with the qualification replaced
You can also make this static in the Content template by specifying Request ID: 00000000001 instead of the variable Request ID: [$$#$$Request ID$$#$$], but using the Variable Replacement feature allows more flexibility.
Using the Attachment Alternatives tab

Figure 3-26: The AR System Email Messages formAdvanced Options, Attachment Alternatives
Attachment field (for example, HTML) Attachment pool
The Attachment Alternatives tab enables you to add the content of your email as a plain text or HTML attachment, instead of typing it into the Body field in the Message tab. The contents of the attachment appear in the body of the email.
To add an attachment alternative

1 Create an outgoing message. 2 Fill in header information. 3 Enter Yes in the Display Advanced options. 4 Click the Advanced Options tab. 5 Click the Attachment Alternatives tab. 6 In the attachment pool, perform the following tasks: a Right-click an attachment field corresponding to the contents of the attachment,
as shown in Figure 3-26.

b Select Add to open the Add Attachment dialog box. c Select a file. 7 Select an encoding for the attachment or leave the field empty to use the system
default. The system needs to be able to read and parse the contents of these attachments when it creates the outgoing email. You can attach only one of each type of alternative attachment to a message form. These attachments are stored as part of the message in the message form.
Message Information tab

The Message Information tab records status information about the email, such as the Message ID, the dates sent and received, and if there is any delay in sending the message.
Errors tab
The Errors tab enables users to view error messages if an email is not sent correctly. For example, if the To field has an invalid character like a space, then an error is generated and is viewable in the Error tab.
87
Determining message content of outgoing email

When sending an email message, the message content is determined according to the following sequence:
Step 1 If you supply a template, the system uses it as the message body, and uses the
following rules for variables: If you supply an attachment in the Values attachment field of the Attachment Alternatives tab of the AR System Email Messages form, the attachment will be used to determine the values for variables contained in the template. If you do not supply an attachment in the Values attachment field, but you 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, 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).
Character sets in outgoing mail

The JavaToMimeMapping.properties file contains a list of character set conversions for your outgoing mail. You can find this file in the Email Engine installation directory.
88
Sending reply email: Giving a professional look to outgoing email
Adding extra custom headers to outgoing SMTP emails

Email Engine allows you to specify a custom header for outgoing SMTP messages using the AdditionalMailHeaders property. See Performance and configuration settings on page 182. You can also provide additional custom headers to an outgoing message.
To add an extra custom header

1 Create an entry in the EmailDaemon.properties file as follows: AdditionalMailHeaders=X-Loop-Detect, customHeader 2 Restart the Email Engine service. 3 Create an outgoing message using the AR System Email Messages form. a Specify the values for mandatory fields and add all the other information you
want to send.
b In the Subject field add the following lines: subjectName X-Loop-Detect:headerValue customHeader:headerValue c Send the email message.
To add multiple custom headers to emails, specify the comma-separated headers in EmailDaemon.properties, and specify their values when creating outgoing messages.
NOTE
Information about custom headers is present in the EmailDaemon.properties file, which cannot be updated dynamically. Hence, you can not provide additional headers for a message dynamically.

One of the major benefits of the Email Engine is the ability to send email messages that are professional looking. Email messages consist of header, content, result, and (optionally) footer components. Each component can be text or HTML. Usually, header and footer templates are used as defaults in the outgoing mailbox, and content templates are used in outgoing messages or filter notifications.
89
Figure 3-27: A reply email in ASCII format
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. This email, as illustrated in Figure 3-27, is a simple ASCII-format message generated by the Email Engine. It is functional but quite plain. Figure 3-28 on page 91 shows the same outgoing email generated by the Email Engine, but this time configured to use an HTML header template and an HTML result template when replying.
90
Figure 3-28: A 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. Assess which mail clients are supported in your organization before implementing a pure HTML solution.
Using header templates as a banner with outgoing email

Adding a header to outgoing email messages can enrich the user experience. With a basic knowledge of HTML, you can make your messages look professional. Adding a header requires creating a template, and then configuring the outgoing mailbox to use the new default header template.
NOTE
To add a footer template, you would use the same steps as described in the following procedure.
To add a header template

1 Create a header image for the banner in your outgoing message. 2 Create an HTML header file (header_default.html) that contains the LogoTriangle.gif bitmap.
91
The following sample HTML header file includes the bitmap:

<html> <head> <title>Default Header</title> </head> <body> <table width="816" bgcolor="#0069A5"> <tr> <td vAlign="top" width="196"><img src="LogoTriangle.gif" width="200" height="90" lowsrc="LogoTriangle.gif"></td> <td vAlign="top" width="608"> <div align="center"> <p> </p> <p><b><font face="Geneva, Arial, Helvetica, san-serif" size="4" color=white Email Engine Demo </font></b></p> </div> </td> </tr> </table><hr> </body> </html>
This HTML code creates the following header.

Figure 3-29: A header template
3 Create an entry in the AR System Email Templates form for your header template: a Select HTML as the template format, enter Header Default as the template name, and add header_default.html as an attachment. b Click Add Attachment in the Template Attachments tab. 4 In the AR System Email Attachments form, select Template as the type, enter LogoTriangle.gif as the attachment name, add LogoTriangle.gif as an
attachment, and save the email attachment entry.

5 In the AR System Email Templates form, click Refresh Table to display the bitmap
template attachment, and save the template entry. For more information, see Adding attachments to HTML templates on page 162.
6 In the AR System Email Mailbox Configuration form, open the outgoing mailbox
entry.
7 Under the Advanced Configuration tab, specify Header Default as the default
header template.
8 Send a sample outgoing email. Figure 3-30 displays the email sent by the Email
Engine to your mail client.

Figure 3-30: An outgoing message with a header template
Using HTML result templates with outgoing email

If you do not specify a result template for reply email, the Email Engine uses a default formatting for the returned data. To make this information easier to read, you can format this data by creating a result template with field variables. To allow users to see the formatted results of their email action, you can easily create a result template in a text editor. The following result template is a simple example that formats the returned text with field variables:
XYZ Corporation #$$Submitter$$# has successfully created a #$$Status$$# ticket. Ticket Number: #$$Request ID$$# #$$Assigned To$$# has been assigned to your request. Problem Description: #$$Short Description$$#
Using an HTML result template (as shown in Figure 3-31) gives you greater control over the appearance of the returned data and makes the return email look much more professional. For more information about data formats and labels, field variables, and result templates, see Chapter 5, 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.
93
To use HTML result templates with outgoing email

1 Make sure the Email Engine is properly configured to send reply results. For more
information, see Configuring the Email Engine for replying with results on page 41.
2 Create a result template for your reply email. Figure 3-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 3-31: An 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 162.
4 Export an email template from the HD Incident form.
For more information, see Exporting mail templates on page 144.

5 Create a new email in your email client and address the email to the Email Engine
inbox account.
6 Copy and paste the contents of the exported email template into the new email,
and then fill out the required information for the template.
7 Add the result template parameter to the email, and then make sure you filled in
all the required fields. Your email should look like the following example:
# # File exported Tue Sep 28 17:01:33 2004 # Schema: HD Incident Server: POLYCARP.eng.bmc.com Login: Demo Password: Action: Submit Result: Results Template Default # Values: Submit, Query
94
Format: Short # Values: Short, Full Last Name+ !536870916!: Stamps First Name !536870917!: Ivan Location !536870918!: Sunnyvale Email Address !536870920!: stamps3@eng.bmc.com Phone !536870919!: 408-555-1212 Category !536870913!: Networking Type !536870914!: VPN Item !536870915!: Cisco Problem Summary ! 8!: Need to install VPN Client. Status ! 7!: New # Values: New, Assigned, WIP, Resolved, Closed Submitter ! 2!: $USER$ Impact !536870927!: Low # Values: Low, Medium, High, Urgent 8 Send the email to the incoming mailbox.
If you properly configured the Email Engine and included all the required fields and the result template in your email, you should receive a reply email (as shown in Figure 3-32) that includes the results of your submission.
Figure 3-32: A reply with results email
For more information, see Creating an email reply using result templates in HTML format on page 227.
95
Using XML result templates with outgoing email

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

1 Create a template file (for example, result_employee.xml) using XML format: <?xml version="1.0" encoding="UTF-8" ?> <Employee name="#$$Employee Name$$#"> <age>#$$Age$$#</age> <salary>#$$Salary$$#</salary> <address> <street>#$$Street$$#</street> <city>#$$City$$#</city> <state>#$$State$$#</state> <zip>#$$Zip$$#</zip> </address> </Employee>
This simple example contains an XML attribute (name), an attribute value (#$$Employee Name$$#), and several elements (age) with their values (#$$Age$$#).
TIP
You can easily validate your XML file by displaying it in a browser.
2 Add the template as a text template to the AR System Email Template form.
The name of this XML template is employee. For information, see Storing templates in the AR System Email Templates form on page 161.
3 Send an incoming email to the Email Engine that queries the server and returns the
results using the XML template, for example:

Action:Query User: Demo Server:polycarp Schema:employee Result Template:employee Employee Name ! 536870913!:John Doe
This email specifies that the employee XML template be used in the outgoing email to return the results of the query. Figure 3-33 on page 97 displays the outgoing email generated by the Email Engine.
96
Figure 3-33: A reply from the Email Engine using an XML template
Observe how the query results of this email are displayed in XML format. If your outgoing mailbox is configured to include an HTML header, the resulting email (combining an HTML header template with an XML result template) would no longer be displayed in purely XML format.
Using HTML content templates with outgoing email

Rather than entering raw HTML into your outgoing email, you can create HTML templates to include content similar to header templates. For example, if you need to send a questionnaire seeking input from users, you can include HTML fields in the email message so that users can enter input using text boxes, radio buttons, and so on, instead of as plain text. For information about encoding user-defined markup text in outgoing email messages, see User-defined HTML or XML text in outgoing HTML emails on page 102.
To add content to an outgoing email message

1 Create an HTML template that you will include in your outgoing message.
The following sample HTML template defines font styles and colors in the <BODY> tag. You can include embedded styles in your content file, but the 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>BMC Picnic</TITLE> </HEAD>
97
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#FF0000" VLINK="#800000" ALINK="#FF00FF" BACKGROUND="?"> <i><font color=blue face="Arial, Helvetica"> <h1>BMC Company Picnic</h1></font></i><hr> <i><font color=#777777 face="Arial, Helvetica"><h3>Are you coming to the 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 <input type=text name="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, BMC_Picnic_Invite.html.
3 Open the outgoing mailbox entry in the AR System Email Mailbox Configuration
form.
4 Under the Advanced Configuration tab, specify BMC_Picnic_Invite.html as the
content template.
5 (Optional) Include a header or footer template.
Otherwise, your email will use any default templates configured for your outgoing mailbox.
6 Send a sample outgoing email.
Figure 3-34 displays the outgoing email sent by the Email Engine to your mail client.
Figure 3-34: An outgoing message with the header and HTML content templates
98
Using status templates with outgoing email

When an error occurs while executing instructions from an incoming email, the Email Engine automatically generates an outgoing email with relevant status information. This system-generated email is simple, containing only basic information, for example, the type of instruction that failed, error messages, and so on:
Instruction: Query Instruction Number: 1 Instruction Template: Message Type: Message Number: 24 Message Text: No matching requests (or no permission to requests) for qualification criteria. Appended Text: TestSecurityForm
By using an HTML status template, your outgoing email can look more professional as well. The following procedure shows you how to create an HTML template that formats status more attractively, as shown in Figure 3-35.
To include status templates with outgoing email

1 Create a status template.
The following sample HTML template is created to display status:

<html> <head> <title>Status Template</title> <meta http-equiv="Content-Type" content="text/html; charset=iso8859-1"> </head> <body bgcolor="#FFFFFF" text="#000000"> <table width="75%" border="1" cellspacing="1" cellpadding="3"> <tr> <td colspan="4"> <div align="center"><b>Your request to the AR Server returned the following error. If you have questions, contact your <a href="mail%20to:%20stamps1@eng.bmc.com">Administrator</a>.</b></ div> </td> </tr> <tr> <td width="12%">Error Number</td> <td width="28%">#$$ActionStatus.Number$$#</td> <td width="18%">Message 1</td> <td width="42%">#$$ActionStatus.Text$$#</td> </tr> <tr> <td width="12%">Error Type</td> <td width="28%">#$$ActionStatus.Type$$#</td> <td width="18%">Message 2</td> <td width="42%">#$$ActionStatus.AppendedText$$#</td> Chapter 3 Outgoing email 99
</tr> </table> </body> </html>
This HTML template defines a simple table with two rows for the error number and error types. It also includes an email address that users can respond to if they have questions. Of course, your HTML template could include color, special fonts, and so on.
2 Create an entry in the AR System Email Templates form for your status template, for example, Status_default.html.
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 3-35 uses the default header template configured for the outgoing mailbox.
6 Send an incoming email to the Email Engine that will generate an outgoing status
email, for example, a query that returns no records. Figure 3-35 displays the outgoing status email generated by the Email Engine.
Figure 3-35: An outgoing message with the default header and HTML status templates
100
Including incoming body in outgoing email

By default, outgoing error messages generated by Email Engine do not contain the body of the original incoming email request. To help users troubleshoot failed email requests for submit, modify, and query actions, use the variable #$$ORIGINALMAIL$$# to include the incoming body in outgoing messages.
To include the incoming body in outgoing email

1 Add the variable #$$ORIGINALMAIL$$# to a status template. 2 Associate the status template with your systems outgoing email messages.
See Using status templates with outgoing email on page 99. When Email Engine generates an error message based on a status template containing the variable #$$ORIGINALMAIL$$#, it replaces the variable with the body of the original email message. For example, a user submits an email request that includes this information:
Schema: HD Incident Server: reepicheep.eng.bmc.com Login: Demo Password: Action: Submit Description !8!: My mouse isnt working. StatusTemplate: MyStatusTemplate
The status template associated with the users request, MyStatusTemplate, includes these label/value pairs:
Error Error Error Error Number: #$$ActionStatus.Number$$# Type: #$$ActionStatus.Type$$# Text: #$$ActionStatus.Text$$# Appended Text: #$$ActionStatus.AppendedText$$#
Original Mail: #$$ORIGINALMAIL$$#
If the users submission fails, Email Engine generates an error message based on MyStatusTemplate. Because the value of the Original Mail label in that template is the variable #$$ORIGINALMAIL$$#, the original email body is put in place of that variable in the error message:
Error Error Error Error Number: 307 Type: 2 Text: Required field (without a default) not specified Appended Text: 2
Original Mail: Schema: HD Incident Server: reepicheep.eng.bmc.com Login: Demo Password:
101
Action: Submit Description !8!: My mouse isnt working. StatusTemplate: MyStatusTemplate
Including incoming attachments in outgoing email

To include attachments to incoming requests in outgoing error messages, the associated status template must contain the variable #$$ORIGINALMAIL$$#, and the incoming request must contain the following information: Correct login, password, server, and schema (form name) values IDs of the attachment fields Names of the attached files For example, a user submits an email request that includes this information:
Schema: HD Incident Server: reepicheep.eng.bmc.com Login: Demo Password: Action: Submit Description !8!: I need a new mouse for my computer. StatusTemplate: MyStatusTemplate !536880912!: file1.txt !536880913!: file2.txt
Using that information, Email Engine gets the appropriate HD Incident form from the specified server and then gets the attachment information from the specified attachment fields. If the HD Incident form does not contain field 536880913, Email Engine cannot get file2.txt. Thus, if the submission fails, the user receives an error message that includes the original email message and only one attachment, file1.txt.
User-defined HTML or XML text in outgoing HTML emails

You can encode user-defined markup text in outgoing email messages by enclosing the text within the following markers:
[#ENCODE_HTML_START#] ... [#ENCODE_HTML_END#]
IMPORTANT
You can only specify these markers directly in the HTML Body tab, or in an HTML content template, or both.
102
User-defined HTML or XML text in outgoing HTML emails
If you include user-defined markup text in outgoing HTML messages, the recipient client does not render the text as HTML. Instead, it displays the text as is. For example, consider that you enter the following markup in the message body:
<html> <body>Leave application <br> Approved <br> <Timespan=app.calendar string=$today$/> </body> </html>
When the message is received, the email client attempts to render the text as HTML. The output appears as follows:
Leave application Approved
You need to indicate that the following text is user-defined markup, which should not be rendered as HTML content:
<Timespan=app.calendar string=$today$/>
To indicate user-defined markup, construct the message body as follows:

<html> <body>Leave application <br> Approved <br> [#ENCODE_HTML_START#] <Timespan=app.calendar string=$today$/> [#ENCODE_HTML_END#] </body> </html>
When the message is received, the email client correctly renders the user-defined markup as follows:
Leave application Approved <Timespan=app.calendar string=$today$/>
103
104
Chapter
Incoming email
This chapter provides information and instructions for sending email messages to the AR System server by using the Email Engine. The following topics are provided: How incoming email works (page 106) Using incoming email (page 107) Sending a query instruction to the Email Engine (page 108) Sending a submit instruction to the Email Engine (page 113) Sending a Modify instruction to the Email Engine (page 117) Using workflow to modify requests (page 126) Creating workflow to modify requests (page 127) Searching for an entry to modify: Advanced solution (page 132) Using variables with templates (page 135) Displaying advanced options for incoming email (page 136) Character sets in incoming mail (page 138)
Chapter 4
Incoming email
105
How incoming email works

Figure 4-1 presents a sample scenario that demonstrates how the Email Engine receives incoming email.
Figure 4-1: How the Email Engine receives incoming email
Underlying Database AR System Server HD Incident
Email Engine
Printer Broken
AR System admin configured incoming mailbox in email engine.
4
Server creates ticket.
Incoming Mailbox
Email Engine
Email engine parses instructions. Instructions then translated into API calls to server.
Email account
Mail Server
"Printer broken!"
Submit email sent to incoming mailbox.
Joe User
Step 1 In the XYZ Company, the AR System administrator has configured the Email
Engine to receive email submissions by 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, and querying the status of their tickets.
106
Using incoming email
Step 2 Joe User cannot print his document because his 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 finds 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 113.
Using incoming email

Email sent to the Email Engine to access the AR System server must follow a specific syntax. The syntax is specified by a given set of labels that are recognized by the Email Engine. You can give different values to the labels. Using label/ value pairs in templates on page 146 provides a table of labels that you can use to send incoming email to the Email Engine.
NOTE
The examples of incoming email in this chapter make extensive use of label/value pairs, aliases, variables, templates, and special keyword syntax as message content; the Email Engine ignores any other text. For more information, see the detailed reference material and examples of their use in Chapter 5, Using email templates. 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 enter the content into the body of the email or 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.
Chapter 4
Incoming email
107
TIP
Like BMC Remedy User, incoming email can trigger workflow that fire on submit or modify. Email functions like any other AR System client to the AR System server. For example, if the transaction meets the filters Run If condition, the filter will fire, regardless of whether the client is BMC Remedy User or an email.
Sending a query instruction to the Email Engine

The easiest way to send queries to the Email Engine is to think of email as simply another client of AR System, like BMC Remedy User. When performing queries with BMC Remedy User, users must perform certain basic actions, for example, logging in, opening a form, and performing a query. Using email as a AR System client is no different. To execute query instructions to the Email Engine, the following information must be included: AR System server name AR System Login and Password to authenticate a user Form name on which to execute the instruction Query action The major difference between BMC Remedy User and an email client is that BMC Remedy User sends its queries directly to the AR System server, while incoming email is first processed by the Email Engine and then sent to the server.
To send a query
1 Create a new email message in your mail tool. 2 Address the email message to the incoming mailbox. 3 To execute a query that returns all fields of all entries in the HD Incident form,
enter the following information in your email message to the Email Engine:
Schema: HD Incident Server: polycarp Login: Francie Frontline Password: userPassword Action: Query
TIP
Copy and paste these examples into your mail client, and then modify them as needed. Figure 4-2 shows the minimum 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.
108
Figure 4-2: A query instruction email
4 Send your email. Figure 4-3: An incoming email received and an outgoing mail sent
5 Optionally, use the AR System Email Messages form to verify that the Email
Engine has received your 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 4-4 on page 110). Otherwise, the Email Engine will return an error message that indicates missing parameters or an error while parsing the qualifier.
Chapter 4
Incoming email
109
6 Open the returned email to see the results of your query (Figure 4-4). Figure 4-4: The query results returned
TIP
One benefit of the 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 4-4. For more information, see Incoming and outgoing mail templates on page 141. 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 the example, but certainly a performance impact on the server. You should always include a qualification in your email queries.
Including qualifications in your email

You can limit the entries that a query returns by using a label called Qualification. The syntax of the value given to the qualification is the same as what is used in the Advanced Search Bar in BMC Remedy User. As a result, any search that executes in the Advanced Search Bar in BMC Remedy User will also work with the Qualification label.
TIP
Create a user-defined instruction that runs the query. This allows the user to quickly execute queries based on instructions that the administrator has predefined.
110
To include qualifications in an incoming email message

1 Create an email. 2 To execute a query that returns all tickets that Francie Frontline submitted, 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: userPassword Action: Query Qualification: 'Submitter' = "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 by 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 of 2.
Qualification: '2' = "Francie Frontline"
In your qualification, you can include relational operators. The following qualification retrieves an entry whose employee ID = 9 and that was submitted by Francie Frontline.
Qualification: 'Employee_Id' = 9 AND 'Submitter' = "Francie Frontline"
Using shorthand qualification syntax

Like BMC Remedy User, which allows you to enter criteria into form fields themselves (without entering them into the Advanced Search Bar), the Email Engine supports a shorthand syntax of qualification criteria. For example, when the Submitter field has a field ID of 2, the following syntax produces the same results as if you had entered Francie Frontline in the Submitter field in BMC Remedy User:
!2!: Francie Frontline
You can use this same shorthand syntax to search for request IDs. The following template searches for request ID from the HD Incident form:
Schema: HD Incident Server: polycarp Login: Demo Password: Action: Query !1!:TT00000000119
Chapter 4
Incoming email
111
Your email query can include multiple fields to search for all new urgent requests:
File exported Tue May 21 21:38:47 2004 Schema: HD Incident Server: polycarp Login: Demo Password: Action: Query Status !7!: New Caller Impact !536870927!: Urgent
If the qualification does not match any entries, the email returned from the Email Engine will indicate this.
Using the Format label

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

1 Create an email. 2 To execute a query that returns only the fields specified in the results list, include
the Format label with the Short value in your email message to the Email Engine:
Schema: HD Incident Server: polycarp Login: Francie Frontline Password: userPassword 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.
112
Sending a submit instruction to the Email Engine

Like BMC Remedy User, you can use email as a client of AR System to submit entries on the server. To submit an entry into a AR System form, send an email with instructions with the Action label set to Submit. To execute submit instructions to the Email Engine, the following information must be included: AR System server name AR System Login and Password to authenticate a user Form name on which to execute the instruction Submit action Any mandatory fields
To use the Submit action label in an incoming email

1 Create a new email message in your mail tool. 2 Address the email message to the incoming mailbox. 3 To execute a submit action that creates an entry that contains the text Printer not
working in the Short Description field of the HD Incident form, enter the following information in your email message to the Email Engine:
Schema: HD Incident Server: polycarp Login: Francie Frontline Password: userPassword 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: userPassword Action: Submit
Chapter 4
Incoming email
113
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
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 33.) If the entry cannot be created, the Email Engine will return an error message (as shown in Figure 4-5) that indicates missing parameters. Make sure your incoming email includes all required fields, for example, Submitter.
Figure 4-5: An error message reply from the Email Engine
114
TIP
Another benefit of the Email Engine is that status from the Email Engine can be formatted, like the status template shown in Figure 4-5. For more information, see Incoming and outgoing mail templates on page 141.
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: userPassword Action: Submit !Submitter!: $USER$ !Short Description!: Printer not working
Using the Format label

Like the Query instruction, the Format label can specify whether a confirmation email from a Submit instruction should include all fields from the form or only the fields in the results list. To use the Format label, configure the incoming mailbox Reply With Entry parameter to Yes. If Reply With Entry is set to No, then the Format label is ignored and the confirmation email will contain only the Request ID number.
NOTE
Join forms do not send values of fields on Submit when the Reply with Entry parameter is set to Yes for the incoming mailbox. By default, the Format label is set to Full, which means all fields in the form are included in the confirmation email. To include only fields from the results list in the confirmation message, set the Format label to Short:
Schema: HD Incident Server: polycarp Login: Francie Frontline Password: userPassword Action: Submit Format: Short !Submitter!: Francie Frontline !Short Description!: Create entry for new hire.
Chapter 4
Incoming email
115
Including attachments with incoming email

Submit instructions can also include attachments.
NOTE
If you are using message/rfc822 attachments with a submit template, make sure the mail client you use is sending the file name of the attached message properly. To test this, send an incoming mail with a message attachment, then view the Attachment tab on the Email Messages Form for the name of the attached file. If you use Outlook Express to submit the message to the Email Engine and save the attachment by using the .msg extension, the file name remains intact.
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: password 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 cannot recognize which of the two filter.log files to insert into the 536880912 attachment field.
116
Sending a Modify instruction to the Email Engine

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

Figure 4-6 presents a sample scenario that demonstrates how to send modify instructions in an email message.
Figure 4-6: Using incoming email to modify requests
AR System admin configured email engine to allow modify entries.
Key: 1234 Action: Modify
Underlying Database
HD Incident
Outgoing
Email Engine
Jklm Nop Qrst

Abcd ef ghijkl mno
Email Messenger Form
AR System Server
Server modifies ticket.
Email engine parses modify instructions.
4
Email Engine
Incoming Mailbox
Mail Server
Email account
Key: 1234 Action: Modify Request ID: 55

Worklog: Service Patch 6
Key: 1234 Action: Modify Request ID: 55
Joe User replies to email.
Francie Frontline sends email with modify instructions.
Chapter 4
Incoming email
117
Step 1 The AR System administrator at XYZ completed the following tasks to enable the
Email Engine to modify entries in the AR System server: Associated the incoming and outgoing mailboxes Enabled the incoming mailbox to accept modify instructions Created and sent security keys to trusted users of AR System, for example, the IT department. For more information, see Configuring the Email Engine for modify actions on page 42.
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 work log 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 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 procedures.
Sending modify instructions in plain text

Executing a modify instruction is a two-step operation:
Step 1 The AR System administrator sends an outgoing message from the AR System
Email Messages form to the user who wants to modify an entry. The message can be sent in plain text or HTML format. (To use HTML, see page 122.)
Step 2 The user replies to the message with new values of the entry the user wants to
modify (see page 121).
Sending modify instructions

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

d Enter other information as needed, for example, an organization. 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, which the administrator can be supply in the outgoing message or the user can supply 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 Optionally, you can 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. The content of an outgoing message that a AR System administrator sent through the outgoing mailbox of the Email Engine is as follows:
Server: polycarp Login: Joe User Password: Key: Action: Modify
Chapter 4
Incoming email
119
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 4-7 shows an outgoing message you might send to a user.
Figure 4-7: A sample outgoing message sent by the administrator to a 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
Because 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 by using the Server Name, Schema Name, and Request ID (as shown in Figure 4-8 on page 121).
120
Replying to email containing modify instructions

To reply to an email containing modify instructions
1 Open your email client.
Joe User received an email that looks like Figure 4-8.

Figure 4-8: The Modify instruction sent to a user
2 Open a reply window for the email that contains the modify instructions.
NOTE
You must reply to the same mailbox as the one from which the email was sent.
3 In the reply, modify parameters as needed.
For example, you could assign values for !8!, the Problem Summary field.
WARNING
The user who is replying cannot add additional submit, query or modify instructions to the email. Do not change the Request ID, Schema name, or Server label/value pairs when replying to the administrators email.
4 Fill in any missing parameters as neededLogin, Password (if there is a
password), and Key. (For information about creating security keys, see Testing your mailbox configuration on page 36.)
Chapter 4
Incoming email
121
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 returns the results to the email client. Otherwise, the Email Engine returns an error message that indicates any missing parameters or other problems.
Sending modify instructions in HTML

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

1 Using the AR System Email Messages form, create an outgoing message in New
mode. For sample contents of an outgoing message, see Sending modify instructions in plain text on page 119.
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> 122 BMC Remedy Email Engine Guide
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 tasks with 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. With HTML format, you can also include 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. 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
To learn how to define input type controls, see any standard HTML reference book or reputable online source (http://www.w3.org/).
The user receives an email that looks like Figure 4-9 on page 124.
Chapter 4
Incoming email
123
Figure 4-9: A Modify instruction (HTML format) sent to the user
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 4-10: Responding to the Modify instruction (HTML format) sent to a 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 4-10).
124
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.
Chapter 4
Incoming email
125
Using workflow to modify requests

Figure 4-11 presents a sample scenario that demonstrates how to use workflow to modify requests.
Figure 4-11: Using workflow to modify requests
AR System Server
AR System verifies security mechanisms and modifies the request.
1
AR System admin configured incoming mailbox to accept modify actions. Created security key. Email Engine
AR System receives submit request. Filter workflow triggers Notify action. Email sent includes Modify template.
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 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 AR System. For more information, see Configuring the Email Engine for modify actions on page 42.
NOTE
The incoming and outgoing mailboxes in the Email Engine can be one physical mailbox, performing both the incoming and outgoing functions.
126
Creating workflow to modify requests
Step 2 AR System receives a submit request. A filter uses email to send a notification that
a request has been received. This email is formatted by 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 clicks 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.

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

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

1 In BMC Remedy User, open the AR System Email Security form in New mode. 2 Set the Status field to Enabled. 3 In the Key field, define your security key, for example, patience. 4 Enter Demo as the User Name. 5 Set the Force For Mailbox field to No. 6 Set the Force From Email Addresses to No. 7 Set the Expires field to No. 8 Leave the rest of the fields blank and save the record. Chapter 4 Incoming email 127
Creating a sample form for your modify example

You are creating a sample form used exclusively for the purposes of this exercise. Later you will create and modify a record in this form to verify the workflow process.
To create a sample form

1 Create a new form and name it appropriately, for example, Modify Email Workflow. 2 Do not add any new fields. 3 Save the form.
Creating filter workflow that triggers a Notify action

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

1 Create a filter. 2 Enter a filter name, for example, Modify Email Filter. 3 Select Modify Email Workflow as the Form Name. 4 Select Submit as the Execute On condition. 5 Leave the Run If condition blank. After you verify that you can use your filter
workflow to modify requests, you can add a Run If qualification later.

6 Click the If Action tab. 7 From the New Action list, select Notify. 8 In the User Name field, enter Demo. 9 From the Mechanism list, select Email. 10 In the Subject field, enter Modify Email Workflow. 11 In the Text field, enter the following information as the text of the message: Login: Password: Key: Action: Modify Form: Modify Email Workflow Request ID: $Request ID$ Submitter!2!: $Submitter$ Short Description:!8!: $Short Description$
The Modify action in the text of the outgoing message is the special instruction that allows the Email Engine to modify an entry on the AR System server. The Modify action is valid only in Reply with Result emails. For more information, see Modify action on page 149.
12 Save your filter. 128 BMC Remedy Email Engine Guide
Exporting an email template

Export an email template from the Modify Email Workflow form. For more information, see Exporting mail templates on page 144.
To export email templates

1 Log in BMC Remedy Developer Studio as a AR System administrator. 2 In the AR System Navigator, right-click serverName, and choose Export > Mail
Template.
3 In the Export Mail Template dialog, click the ellipsis [...] button next to the Form
field.
4 In the Form Selector dialog, select Modify Email Workflow form, and click OK. 5 In the Export Mail Template dialog, perform the following actions: a In the View Details table, select the views your want to use in the template. b Click the ellipsis [...] button next to the To File field to specify the file name and
location where you want the templates stored.

c Click Finish. 6 Open the email template in a text editor.
Creating a submit email

Here you open a new email message and paste the contents of the exported mail template into the new email. You use this email to submit a record to the Modify Email Workflow form.
To create a test email

1 Create a new email in your email client. 2 Address the email to the Email Engine inbox account. 3 Enter a subject line, for example, Modify Email Workflow. 4 Copy and paste the contents of the exported email template into the new email,
and then enter the required information for the template, for example:
# # File exported Tue Sep 21 15:34:56 2004 # Schema: Modify Email Workflow Server: POLYCARP.eng.bmc.com Login: Demo Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full Submitter !2!: Demo Short Description !8!: Email Test 5 Send the email to the incoming mailbox. Chapter 4 Incoming email 129
Replying to email notifications

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

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

Figure 4-12: Incoming and outgoing messages in the Email Messages form
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 4-13) from the filter that you created previously.
130
Figure 4-13: A notification email (sent from filter) with the modify key
Figure 4-13 shows the modify key added to the notification:

##Modify##:[$$ckI2UoIK4gNQ0qROehOucPFOokiXb/DfA07EiNObusaHtOquCV/ FSA==$$]
WARNING
You cannot modify a record through email without this ##Modify## key. Do not edit this key in any way!
6 Reply to the returned email. 7 Enter the following information into the body of the email: Login: Demo Password: Key: patience Action: Modify Form: Modify Email Workflow Request ID: 000000000000002 Submitter!2!: Demo Short Description:!8!: Modifying requests with workflow is great! ##Modify##:[$$ckI2UoIK4gOt6aqHF2QE9x5d1nqwf6FJLifugKurp68lQH9XRehn Ew==$$]
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. Chapter 4 Incoming email 131
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 4-14).
Figure 4-14: A Modify message returned to the incoming mailbox
10 In BMC Remedy User, refresh the query results of the Modify Email Workflow
form. The modify action should have modified the Short Description in the record.
Searching for an entry to modify: Advanced solution

This advanced solution builds on all the information you have learned up to now, for example, sending query and modify instructions to the Email Engine, the use of templates, and so on. The procedure assumes you have created a form named TestSecurityForm, which contains at least the core fields.
To search for an entry to modify

1 Make sure you have an incoming mailbox and an outgoing mailbox configured
and associated with one another.

2 Set Enable Modify Actions to Yes in the AR System Email Mailbox Configuration
form for the incoming mailbox.

3 Make sure you have a valid security key. 4 Create a template (for example, TestModify) that includes a modify action. 132 BMC Remedy Email Engine Guide
Searching for an entry to modify: Advanced solution
You will use this template for the reply email; see the Result Template label in step 6.
Server: polycarp Login: Password: Key: Action: Modify Form: TestSecurityForm Request ID: [$$#$$Request ID$$#$$] !2!: !8!:
Because this template replaces the hard-coded label/value pair (Request ID: 000000000000026) with a variable value (Request ID:[$$#$$Request ID$$#$$]), you can construct an email that gives you the flexibility to search for a specific parameter.
5 Add the TestModify template to the AR System Email Templates form. 6 Use your mail client to create an incoming mail. Include a Query action in the body
of your email. For example:

Server: polycarp Login: Demo Password: Action: Query Form: TestSecurityForm Qualification: 'Request ID' = "000000000000026" Result Template: TestModify
This email provides all the information required for the Email Engine to perform the query action, and then to perform the modify action in the TestModify template.
TIP
If the Qualification was part of the TestModify template, you could have omitted the Qualification line from the email.
7 Send your email to the incoming mailbox.
The Email Engine generates a reply (Figure 4-15) to the Query action, by 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, by using the variable in the template. 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.
Chapter 4
Incoming email
133
Figure 4-15: A reply email generated from the Email Engine
Request ID variable substituted in reply, based on template
Key included in reply email generated by Email Engine
8 Open the reply email and modify the parameters as required. For example, add
values in !2! (a different name) and !8! (modifying the short description). Do not change the Action, Form, and Request ID label/value pairs.
9 Fill in any essential missing parametersLogin, Password (if there is a password),
and Key.
10 Send the email reply with the modifications included. Figure 4-16: A confirmation email that the modify action was successful
134
Using variables with templates
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 4-16. You can perform a search on the form to verify the result.
Using variables with templates

With incoming email, you can use variables in templates. Variables are useful when you need to substitute values for the fields to submit an entry. Use the following syntax for variables:
#$$Variable Name$$#
If you expect the value of a variable to span multiple lines, then enclose the variable with brackets:
[$$ $$]
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. Because the variable might span multiple lines, it is enclosed by 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$$]
Chapter 4
Incoming email
135
Displaying advanced options for incoming email

For incoming email, the most important use of the Advanced Options tab is to view message information and errors of incoming email. The Attachment Alternatives tab (Figure 4-17) displays any attachments in the incoming email. The tab displays the links to each message as it is rendered by the Email Engine in plain text, HTML, and email client formats.
Figure 4-17: Attachment alternatives information for incoming email
Formats of incoming email message displayed
To display advanced options

1 Open the AR System Email Messages form in Search mode. 2 Select an incoming email message. 3 Select Yes in the Display Advanced Options field of the AR System Email Message
form.
4 Select one of the advanced option tabs: Advanced Options, Message Information,
or Errors.
NOTE
For incoming email, you typically will not see information under the Templates and Variable Replacement tabs.
136
Displaying advanced options for incoming email

The Message Information tab records status information about incoming email, such as its Message ID, the date the email was received, and how the message was parsed, as shown in Figure 4-18.
Figure 4-18: Message information for incoming email
Errors tab
The Errors tab enables users to view error messages if incoming email is not received correctly. If a request fails to submit or query, the original message is returned, along with an error message that indicates the reason for the failure.
Figure 4-19: Error information for incoming email
Chapter 4
Incoming email
137
Figure 4-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.
Character sets in incoming mail

The MimeToJavaMapping.properties file contains a list of character set conversions for your outgoing mail. You can find this file in the Email Engine installation directory.
138
Chapter
Using email templates
This chapter provides information and instructions for creating and using templates for outgoing and incoming email. The following topics are provided: Overview of Email Engine templates (page 140) Types of templates (page 141) Creating templates (page 143) Exporting mail templates (page 144) Using label/value pairs in templates (page 146) Tips for creating or modifying templates (page 161) Storing templates in the AR System Email Templates form (page 161) Adding attachments to HTML templates (page 162) Preparing email templates after an upgrade (page 166) Sending incoming email with user instructions (page 167)
Chapter 5 Using email templates
139
Overview of Email Engine 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 by using BMC Remedy Developer Studio. A variety of email templates also 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 by 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 by 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.
140
Types of templates
Types of templates
You can create specific templates for various functions. This section presents an overview of the different types of templates, which are all described in more detail later in this chapter.
Incoming and outgoing mail templates

You can create separate templates to specify different formats for incoming and outgoing mail. Content templatesUsed for outgoing messages. These templates can be associated with a specific form and contain the fields and their corresponding values relating to a specific record. They can also contain plain text or reserved variables. You can create these templates in a text editor (shown in the following figure), or export them by using BMC Remedy Developer Studio, selecting the form and fields that are to be contained in the template. The content template can also contain formatting instructions and label/value pairs to specify a header, footer, result, or status template. A content template is attached by using the AR System Email Messages form or by using workflow with filters and escalations.
Figure 5-1: A plain text content template
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 5-3 on page 142. Header and footer templatesUsed to place lines of text or a graphic at the beginning or end of a message. 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.
141
Figure 5-2: An HTML header and footer template
Result templatesDefines 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 5-3: Result templateHTML
Status templatesUsed when the execution of an incoming instruction results in an error. 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 159.)
Figure 5-4: An HTML Status template
142
Creating templates
User-defined instruction templates

User-defined instruction templates enable administrators to associate a template with an incoming email by way of an entry in the AR System Email User Instruction Templates form. When the user sends an email with the appropriate entries, the Email Engine executes the relevant template. Using this feature, the administrator can set up variable substitutions to be used in an email with minimal input from the user. The associated template supplies the rest of the information. For example, the template shown in Figure 5-5 logs the user Demo in to the server reepicheep, queries the HD Incident form for all tickets with an urgent status, and returns the full information about all fields that this user has access to. But all that the user needs to do is send an incoming email with the Action label/value pair that identifies the user instruction, for example, Action: Urgent.
Figure 5-5: A 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 149 and Sending incoming email with user instructions on page 167.
Creating templates
In BMC Remedy Developer Studio, 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 by 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.
143
Exporting mail templates

The mail template displays all of the fields that are visible in the selected view and that all users have permission to update. Therefore, make sure that all fields that require a value are visible in the selected view and that the Allow Any User To Submit check box is selected before performing the following procedure. The Export operation generates fields in the same order as in the default administrator view of the form. Hidden fields are omitted from templates even though they might have public permissions and are set to enable any user to submit. You can add any of the fields that are not exported to the template. The user can gain access to these fields if their security key, supplied user information, or their email address connects to the correct user name and depending on how the mailbox was configured. If the user name used by the Email Engine has access to this field, then the field is accessible.
To export mail templates

1 Log in BMC Remedy Developer Studio as a AR System administrator. 2 In the AR System Navigator, right-click serverName, and choose Export > Mail
Template.
Figure 5-6: The Export Mail Template dialog
3 In the Export Mail Template dialog, click the ellipsis [...] button next to the Form
field.
4 In the Form Selector dialog, select the form for which you want to generate mail
templates, and click OK.
144
Exporting mail templates
5 In the Export Mail Template dialog, perform the following actions: a In the View Details table, select the views your want to use in the template. b Click the ellipsis [...] button next to the To File field to specify the file name and
location where you want the templates stored. If you specify an existing folder and file name, you have two choices: OverwriteOverwrites the mail template of an existing file. This option is useful when you are re-exporting a template that has changed. AppendAppends the contents to an existing file. If several templates are in a single file, the mail processor will not be able to process the request. The template is saved as a single text file with an *.arm extension. Using the AR System Email Templates form, users can associate these files with their mail messages. The following example shows an email template exported by using BMC Remedy Developer Studio.
# # File exported Fri Apr 30 09:54:36 2004 # Schema: HD Email Server: POLYCARP.eng.bmc.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.
145
Using label/value pairs in templates

For the most part, email templates consist of a label/value pair surrounded by text or graphics, depending on the format of the template. The label is a keyword such as Action. The value consists of data or commands (for example, Submit). A value can be specified in the templates or obtained from the configuration information. The Email Engine is not case sensitive when parsing the labels. The following table lists valid labels; each label is discussed in more detail following the table.
Table 5-1: Label/value pairs in templates (Sheet 1 of 2) Label Form Server Login Description Name of a AR System form. Server that will be affected by the instruction. User name used when executing the instruction. Incoming Yes Yes Yes Outgoing No No No User User Name Name Login Password TCP Port RPC Number Authentication Language Action Format Qualification Password used when executing the Yes instruction. TCP port used when logging in to the AR System server. Yes No No No No No No Yes No No No Query Search Result ResultTemplate Status StatusTemplate No No Yes Yes Header HeaderTemplate Footer FooterTemplate page 152 page 152 page 151 page 151 Instruction TCP RPC page 147 page 147 page 148 page 148 page 148 page 149 page 150 page 151 Aliases Schema Page page 147 page 147 page 147
RPC number used when logging in Yes to the AR System server. Authentication string used when Yes logging in to the AR System server. Language used when logging in to Yes 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
Result Template The name of the template to use in Yes the reply. Status Template The name of the template to use when Status Information is returned. Header Template The template to be used as the header in the reply email. Yes
Footer Template The template to be used as the footer in the reply email.
146
Table 5-1: Label/value pairs in templates (Sheet 2 of 2) Label !Name/ID! Key Request ID Description The database name or ID of a 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. Incoming Yes Yes Yes Outgoing Yes No No Encryption Key Encryption Entry ID EntryID RequestID page 153 Aliases Page page 152 page 153
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:formName.
Server label
The Server label identifies the server that the instruction will affect. 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:serverName. (For more information, see Updating the EmailDaemon.properties file on page 180.)
Login, Password, and TCP Port labels

The Login and Password labels identify the user name and password used when executing the instruction. You can configure exactly how the user name is to be determined for an incoming email: Set a security key in the AR System Email Security form. You must add Key:securityKey to the email. If Key:securityKey matches an entry in the AR System Email Security form, then the corresponding user name is used. Use the supplied user information: user login name, password, possible authentication, possible language, possible RPC, and possible TCP inside the email by using the appropriate labels and values. Use the senders email address. The Email Engine searches through the User form for the appropriate user name by searching for the email address. It uses the first user it finds whose email address corresponds. The passwords and security keys are encrypted in the AR System Email Messages form. The aliases for Login are User, User Name, Name, and Login Name.
147
NOTE
If you try to send an email in an HTML template, do not use a colon in the Login, Name, or Password labels. For example, do not use:
Login: <input type="text" name="!536870918" size=50/>
Instead, use the format:

Login <input type="text" name="!536870918" size=50/> With this format, the Email Engine can parse correctly that Login is a label for a
field on the form and not an instruction. The TCP Port label identifies the TCP/IP port of the AR System server, if your AR System server is not using the AR System portmapper. The alias for TCP Port is TCP.
RPC Number and Authentication labels

The RPC Number and Authentication labels define the RPC number for the destination server (usually involved when the user is connecting to private queues) and the name of the external authentication service that is used to authenticate the user. These values are the same as those used when logging in to the AR System server. The alias for RPC Number is RPC.
Language 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 Developer Studio and other AR System clients. The format of the Language label/value pair is Language:localeLanguage, for example, Language:en_US.
148
Action label
The Action label defines the operation to perform on a specific AR System form. The Action label/value pair is required in the incoming email so that the parser can generate valid instructions. Valid actions are Submit, Query, Modify, and a userdefined value. If no value is given for the label, the email is only logged and no actual execution takes place. An alias for Action is Instruction. Valid values for this label are in Table 5-2, and explained in detail after the table.
Table 5-2: Values applied to AR System action labels Value Submit Query Modify Description Submits a new entry on a specific AR System form. This is valid within any incoming email. The syntax is Action:Submit. Searches for entries on a specific AR System form. The syntax is Action:Query. Modifies a specific entry contained within a specific AR System form. This is only valid in reply emails (that is, emails that have been sent to the user from a AR System server). The syntax is Action:Modify. An instruction that the administrator defines. The syntax is Action:adminDefinedText.
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 113.
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 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 Configuration Guide, Limit Number of Items Returned, page 102. For sample templates with Search (Query) actions, see Sending a query instruction to the Email Engine on page 108.
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 a 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.
Chapter 5 Using email templates 149
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 42. 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 Email Engine inserts the following special label and value into the email if the email contains a Modify action:
##Modify##:[$$the encrypted information$$]
The encrypted value contains information, which the 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 Using workflow to modify requests on page 126 and Sending a Modify instruction to the Email Engine on page 117.
User-defined instruction
A user-defined instruction is a text string that the AR System administrator determines and that 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 Sending incoming email with user instructions on page 167.
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, use only 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.
150
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. A sample qualification string:
Qualification: 'Source' = "Phone" OR 'Source' = "email"
A null value will be treated as if it is a return all records query, such as 1 = 1. Aliases for this label are Query and Search.
Result Template label

If the Email Engine is configured to send an email reply, you can specify a result template that formats the reply for you. You include the Result Template label, and specify the template name as the value. The Result Template label defines the template to use when replying to an incoming email containing query instructions. The Result template is usually associated with a particular form. This template consists of label/value pairs and variables (described on page 156) that correspond to fields on the AR System form being queried. These variables are replaced by the data found on the form based on the instruction being executed. For example, you can include variables in your template that let users click a direct access URL to open a specific Request ID:
<TD width="17%"><a href="http://polycarp/arsys/servlet/ ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request ID$$#">#$$Request ID$$#</a> </TD>
Figure C-3 on page 229 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 Email Engine receives this label and value, it retrieves the template file and uses it as required. Aliases for this label are Result and ResultTemplate. An example of a result template label/value pair is Result:resultTemplateName. For more instructions, see Using HTML result templates with outgoing email on page 93 and Creating an email reply using result templates in HTML format on page 227.
Status Template label

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

The Header Template and Footer Template labels define the templates used in the header and footer of outgoing email. If the templates are used within a Query action blockthat is, after an Action: Query label/value pairthen the header or footer or both are inserted before or after (or both before and after) each entry that is retrieved when the action is executed. In this way, entries are clearly separated from each other. The Header and Footer templates typically contain basic text, or they can be HTML documents with logos, graphics, and decorative typefaces. The value given for this label is the name or Request ID of a template contained on the AR System Email Template form. When the Email Engine receives this label/value pair, it retrieves the template and uses it as required. The label/value pair method is used when requesting results from a server by way of email. Aliases for the Header Template are Header and HeaderTemplate; aliases for the Footer Template are Footer and FooterTemplate. An example of a header template label/value pair is HeaderTemplate:headerTemplateName.
!Name! or !ID! labels

The !Name! and !ID! labels indicate a AR System field or the value of a variable. The exclamation marks are required to surround the field name or the ID number. For example, field ID 8 is !8!. A colon (:) is placed after the second exclamation point as a delimiter, for example:
!8! : Short description information
Blanks are acceptable. If any characters other than digits and spaces are between the exclamation points, the reference is not recognized as a field ID. The argument to the ID/name label should be of the same data type as that of the field (data type information need not be included explicitly as the parser will determine the appropriate data type of the field by default). If this is a query action, and the argument is of a different data type 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$
152
In the previous example, the Email Engine treats the text Submitter as regular text. The field ID !2! is parsed and the variable $USER$ is 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. 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 are 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:testKey. For more information, see Configuring incoming mailbox security on page 39.
Request ID label
The Request ID label is only valid for the Modify action and defines the Request ID or Entry ID of an entry on the corresponding form against which the Modify action is to be executed. The Request ID is required for a Modify action as it serves to identify the specific form entry you want to modify. Aliases for the Request ID are Entry ID, EntryID, and RequestID. An example of a request ID label/value pair is RequestID:0000012345.
Label/value pair formats

Your email must use specific syntax for label/value pairs so that the parser can extract the required information. Each of the following formats can be used in plain text, HTML, or XML documents.
Basic format
The basic format is the simplest. You can associate a label with a constant value or a variable value. The labels and associated constant values are written as follows:
Label:[$$Value$$]
The opening and closing $$ enable the parser to extract the value from the email, including situations where the value incorporates multiple lines. If the value does not incorporate multiple lines, the label/value pair can be written as follows:
Label:Value
153
TIP
You should use the [$$ ... $$] variable syntax when the Email Engine needs to parse multi-line values. Strictly speaking, you do not need to use this multi-line syntax for all label/value pairs, but it is a good practice to adopt if you think the values in a variable might exceed a single line. The label and value do not have to be left justified, and can be prefaced by text on the same line. You do not have to surround the label with any special characters. You can associate a label with a variable also. A variable is written as follows:
#$$variable_name$$#
When used in a label/value format:

Label:[$$#$$variable_name_Value$$#$$]
XML format
The XML format is as follows:
<Label>Value</Label>
AR System fields are treated differently. The format is as follows:

<Field ID="!Field_ID!">Field Value</Field>
or:
<Field Name="!Field_Name!">Field Value</Field>
Variables are referenced as #$$variable_name$$# as in the Basic format. To view a template using XML, see Using XML result templates with outgoing email on page 96.
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 automatically generates 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 by using HTML field types, see Sending outgoing email in HTML on page 77. The name tag represents the label, and the value tag represents the value.
154
Text field
In HTML, a text field typically looks like this:
<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
Radio buttons 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 is not used because the word checked is not included in the definition. But in the second example, the label and value is used because the box was checked. This field can give the user the ability to select the parameters that are valid and those that are not.
Menu field
The menu field acts as a selection box where you will be able to create a label from which any specific value can be selected from a range. In the following example, the Action label has possible values of Modify, Submit, and Query.
<select size="1" name="Action"> <option value="Modify">Modify the entry</option> <option selected value="Submit">Submit the entry</option> <option value="Query">Query the entry</option> </select>
155
The type is a select HTML field; the label is Action; and the values are Modify, Submit, and Query. The tag containing the word selected determines the label/ value paid to be used. The menu field also allows the user to specify different visible text in the field with the correct field values defined underneath.
Global and local parameter declarations

Any parameter defined in the email before an Action label is regarded as global and applies to all the actions within the email. As a result, you do not have to repeat parameters, such as login information or form names, for each instruction. If the parameter is defined again after an action statement, then that parameter takes precedence over the global parameter for that action only. For more information, see Creating an email content template with Submit and Query actions on page 226.
Variables
Variables allow the administrator to create generic templates. Variables are used only with templates that are to be used as one of the following types of templates: User-defined instruction templates for incoming email. Result templates for incoming email. Content templates for new outgoing email. Variables 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$$#
When used in a label/value format, use the following syntax:

Label:[$$#$$Value$$#$$]
For more information about label/value formats, see page 153. The name of the variable can be the same as a AR System field, so there are no restrictions if used in the context of a 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.
156
In content templates used for outgoing emails, variables for field values must use the field database name, not the field ID. For specific examples, see Using variables with notifications on page 158. 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 is used to determine the values for variables contained in the template. For more information about how to do this, see Using the Attachment Alternatives tab on page 86.
Step 2 If you do not supply an attachment in the Values attachment field, but supply
information in Field Values, or obtain a value by using a qualification in the Qualification field of the Variable Replacement tab of the AR System Email Messages form, the information is used to determine values for variables contained in the template. For more information, see Using the Variable Replacement tab on page 83.
Step 3 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 is 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 example shows 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 in 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$$]
157
NOTE
Variables can be used only for form field values and qualifications. 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. Only local fields (fields after the Action label) can be substituted. Global fields (fields before the Action label) cannot be substituted. Labels like Server, Schema, Login, Password, or Key are considered to be global and cannot be substituted.
Using variables with notifications

When creating templates to be filled in using notifications, the template variables for field values must use the fields database name (not the field ID) as the variable name. This is because the server uses the field name (database name) to assign the values in the AR System Email Messages form. For example, if the user has a template to mail out the user information through a notification that looks like the following, it will not work for notifications:
Login Name : #$$101$$# Password : #$$102$$# Group List : #$$104$$# Full Name : #$$8$$# Default Notify Mechanism : #$$108$$# Email Address :#$$103$$#
To use this template in notifications, the user must change it so that it looks like the following example:
Login Name : #$$Login Name$$# Password : #$$Password$$# Group List : #$$Group List$$# Full Name : #$$Full Name$$# Default Notify Mechanism : #$$Default Notify Mechanism$$# Email Address :#$$Email Address$$#
Add the following core fields to the template:

Req Id:#$$Request ID$$# Submitter:#$$Submitter$$# Create Date:#$$Create Date$$# Assigned To:#$$Assigned To$$# Stat:#$$Status$$# ShortDescr:#$$Short Description$$# StatHist:#$$Status History.New.USER$$#
158
NOTE
Do not use the Request ID to return entries from display or vendor forms in a notification. If you construct a content template by using the #$$Request ID$$# variable and use the content template in the Templates tab of notifications on display or vendor forms, the system will not generate errors, but it also will not return the Request IDs.
Date formats supported in email templates

Table 5-3: Date and time formats supported by the email templates Format SHORT Description A numerical date that includes the numerical month, day, and year (for example, 06/18/04). The order of each component is based on the Regional Options properties in the Control Panel. An alphanumeric date that includes the day of the week, month, day, and year (for example, Friday, June 18, 2004). The order of each component is based on the Regional Options properties in the Control Panel. Completely specified numerical date description, for example, Tuesday, April 12, 1952 AD.
MEDIUM Longer numerical date description, for example, Jan 12, 1952. LONG
FULL
You cannot mix 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 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 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 or Query. #$$Action.Number$$#The position of the action within the entire
execution list.
159
#$$Action.Form$$#The name of the AR System form involved in this
action.
#$$Action.Query$$# The qualification (if any) associated with the
instruction. (This reserved variable is valid only for User Defined Instruction templates.) Status informationUsed to store the results of system-generated errors. The following formats are valid:
#$$ActionStatus.Number$$#The error or warning number. #$$ActionStatus.Type$$#The type of error, such as Severe, Error,
Warning.
#$$ActionStatus.Text$$#The message text. #$$ActionStatus.AppendedText$$#The associated appended text.
These are also values that you would define in a status template; they are common to all forms. Figure 5-7 displays an email that includes these reserved variables for status information. This particular email uses the HTML status template found on page 142.
Figure 5-7: Reserved variables for status information used in outgoing email
#$$ActionStatus. Number$# #$$ActionStatus.Type$#
#$$ActionStatus.Text$# #$$ActionStatus.AppendedText$#
The following rules apply for specific Status History information in the templates: You must use the fully qualified status history name, for example:
Status-History.New.USER Status-History.New.TIME
You can also use numeric values, for example:

15.0.USER Status-History.0.USER 15.New.USER
The USER and TIME identifiers are case sensitive.
160
Tips for creating or modifying templates
Tips for creating or modifying templates

You might find the following tips helpful when using email templates: Diary fields and character fields with a maximum length of over 50 characters can use multiple lines of text. Values can be entered anywhere after the delimiting character. Leading and trailing blanks are ignored when the Email Engine reads a value. Comments are optional. Because the Email Engine ignores any lines that do not contain a valid label/value pair, you do not have to add a # symbol in front of comments. If the user does not enter a value into a field that has a default value defined, then the default value is loaded. If the user does not enter a value into a required field and there is no default value defined for it, an error will result.
Storing templates in the AR System Email Templates form

When you create or export templates, they must be stored in the AR System Email Templates form to be used recurrently in emails.
Figure 5-8: The AR System Email Templates form
161
To add a template to the AR System Email Templates form

1 Create or export your template. 2 Open the AR System Email Templates form in new mode in BMC Remedy User. 3 Click the Template Information tab. 4 Select the template format (Text or HTML) from the Template Format list. 5 Specify the Encoding so that the Email Engine can parse the templates. If you leave
the Encoding field empty, the default encoding of the local system is employed.
6 Right-click in the attachment pool, and choose Add from the menu that appears.

7 Browse to the template file you want to add and select it. 8 Click Open.
The file is added to the list of attachments in the Email Templates form. You can also click and drag a template to the attachment pool if you are using a Windows system.
9 Select the item in the attachment pool, and click the edit button next to the
Template Name field. The name of the attachment is displayed in the Template Name field. For example:
template_attachment1.htm.
You can edit the file name, for example, to template1.htm.

10 (Optional) Enter a description.
It is useful to enter a description indicative of the function of the template.

11 Click Save.
The system assigns a Template ID number to the template. (The Template ID field is hidden.) If an HTML template contains a reference to a graphic file, you should add the graphic file as an attachment. For more information, see the following section.
Adding attachments to HTML templates

Use the AR System Email Attachments form to make sure that a specific attachment is always included with any message that makes use of a specific template. You can add graphics to HTML templates by using this form. This is particularly useful for header templates if you want to add a company logo to the header information in your email.
WARNING
You can only use graphic type files as attachments.
162
NOTE
The Email Engine does not support linking your HTML template to a cascading style sheet.
To add attachments to HTML templates

1 Open the AR System Email Templates form in new mode in BMC Remedy User. 2 From the Template Format menu, choose HTML.
This activates the buttons on the Template Attachments tab to add attachments to your template.
3 Add a template file as an attachment. 4 Click Save. 5 Click the Template Attachments tab. Figure 5-9: The AR System Email Templates formTemplate Attachments tab
Add Attachment button
6 Click the Add Attachment button.
The AR System Email Attachments form opens.
163
Figure 5-10: The AR System Email Attachments form for templates
Select Template as the attachment Attachment pool
7 Select Template from the Type menu. 8 Right-click in the attachment pool, and choose Add from the menu that appears.

9 Browse to the file you want to add and select it. 10 Click Open.
The file is added to the list of attachments on the AR System Email Attachments form. If you are using a Windows system, you can also click and drag an attachment to the attachment pool.
NOTE
If you attach multiple images (such as .gif or .jpg files) with a template and use the same name for each image, the Email Engine will use only the first attachment.
11 Select the item in the attachment pool, and click the edit button next to the
Attachment Name field. The name of the template attachment is displayed. For example:
template_attachment1.htm
You can edit the file name.

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

13 Your attachment will be added to the list in the AR System Email Templates form.
You might need to right-click and select Refresh to see the attachment listed.
14 Click Save in the AR System Email Templates form.
The Email Engine will give the template attachment an ID. (The Attachment ID field is hidden.)
164
Adding a previously saved attachment to your template

To add a previously saved attachment to your template
1 In the Template Attachments tab of the AR System Email Templates form, click the
arrow next to the blank field at the bottom of the pane.

2 Select the attachment. 3 Click the Add Existing button.
Your attachment is added to the list in the attachment pool.

4 Click Save.
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 5-10 on page 164).
4 Click Search to locate the attachment.
The attachment appears on the attachment list.

5 Modify the attachment as required. You also can modify the Attachment Name. 6 Click Save.
Deleting an attachment
To delete an attachment
1 Click the Attachments tab in the AR System Email Templates form. 2 Select the attachment you want to delete. 3 Click Delete Attachment. 4 Click the Refresh Table button to refresh the table in the Attachments tab.
The attachment is deleted from the list.
165
Exporting templates with attachments to another server

You can export an HTML template from one server and then import the template onto another server.
To export templates with attachments to another server

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

If you have upgraded from BMC Remedy Mail Server (release 5.1 or earlier), you might have to modify your existing templates to use the features in release 7.0.00 or later, for example, the ability to use HTML in your templates. However, there is a configuration setting that allows you to continue using email templates from release 5.1 or earlier as is with release 7.0.00 and later. For more information, see the Use Original Template Format feature on page 34. To use your old email templates after an upgrade to Email Engine 7.0.00 or later, use the following procedure.
To prepare email templates after an upgrade

1 Verify the following settings in the AR System Email Mailbox Configuration form:
Incoming mailbox is Enabled. Email Action for your incoming mailbox is set to Parse. Use Original Template Format is set to Yes, if you want to use your original templates for your incoming mailbox as is without using the 7.0.00 and later email template features. Use Supplied User Information field is set to Yes.
2 If only one form is used for email submissions, set the Default Workflow Form to
that form name.

3 To guarantee that no other form is used for email submissions, set Force Default
Workflow Form to Yes.

4 If the original templates do not include a user name, user password, or form name,
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 Sending incoming email with user instructions on page 167.
Sending incoming email with user instructions

A good analogy for understanding user instructions is that they are macros for email. You can make Email Engine interaction easier for your users by creating custom actions that reduce the need to learn the Email Engine syntax of label/ value pairs, variables, and so on. These custom actions are called user instructions. Figure 5-11 on page 167 provides a sample scenario of how to create user instructions for your user community. 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 through an entry in the AR System Email User Instruction Templates form.
Figure 5-11: Overview of using instruction templates
User sends email with user-defined instructions.
3
Email Engine Email Server
Template associated with user instructions.
Creates user instructions.
AR System Server Primary Configuration
Results.
Underlying Database
Admin creates and stores email templates.
167
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 the same as any other template.
Step 2 The administrator creates a user instruction in the AR System Email User
Instruction Templates form by entering an instruction name in the Instruction field.

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
(Action label/value pair) to the Email Engine. The email contains an Action label and a value corresponding to the valid character string in the Instruction field of the Email User Instruction Templates form. The value for the variable that appears after the Action label is extracted from the email, and the associated template is then executed.
Step 5 As a result, the Email Engine constructs a message according to the template
instructions and sends the message to the user.
Creating and storing a template for use with user instructions

As an administrator, you can use a text editor to define templates by creating a text file with an extension of .arm, and then attaching the .arm file to an entry in the AR System Email Templates form.
To create templates for use with user instructions

1 Use a text editor to define a template, and name the file with an .arm extension.
The following example is a template file (IN_Install_AllUrgent.arm) that queries all urgent records in the TestSecurityForm form.
Schema: TestSecurityForm Server: polycarp Login: Demo Password: Action: Query Format: Full Header Template: Header_Urgent.html Result Template: Default Content Qualification: 'Status' <= 2 AND 'Impact' = 3
A template can contain one or more instructions. For more information, see Creating templates on page 143.
TIP
Test the template by sending email to the incoming mailbox and see if it returns the expected results.
168
2 In BMC Remedy User, open the AR System Email Templates form in New mode. Figure 5-12: Storing a template
3 Attach your IN_Install_AllUrgent.arm file to an entry in the AR System Email
Templates form.
4 Click the Template Attachments tab to add any header, footer, and result
templates that are used with your template.

Your UrgentRequests template was created and now stored.
Creating user instructions

After storing your templates, you must associate a name with the User Instruction by creating an entry in the AR System User Instruction Templates form. The User Instruction name will be used as a value for the Action Label in the email the user sends to the incoming mailbox.
NOTE
You can associate more than one user instruction with a template containing one or more instructions.
To create a user instruction

In BMC Remedy User, open the AR System User Instruction Templates form in New mode, and complete the form as follows:
1 Do not enter a template ID. The system will create the unique ID in the Instruction
Template ID field when you save the entry.
169
2 From the Template Name menu, select the template that contains that actions you
want to associate with the user instruction. You can use only 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 168.)
3 To restrict the user instruction to one incoming mailbox, select a mailbox from the
Mailbox Name menu.

4 Enter a character string value for the Instruction field. This value is used to identify this template when used in an incoming email, for example, Urgent. Figure 5-13: Creating an entry using the User Instruction Template form
Sending a user instruction in an incoming email

All authorized users can send an email to the incoming mailbox of the Email Engine with the name of the User Instruction as the value of the Action Label.
To send a user instruction

1 Create a new email message in your mail tool. 2 Address the email message to the incoming mailbox. 3 Enter the user instruction in the email.
The user instruction consists of an Action label and value equal to the string defined in the Instruction field in the AR System Email User Instruction Templates form (Urgent). The power of customized user instructions is that your email could simply consist of the following text:
Action: Urgent
The email should include any values for the variables if any variables exist in the template associated with the user instruction.
4 Send the email.
170
Results of the user instruction

The Email Engine will then retrieve all records of urgent requests from the AR System server and list them in the email, as shown in Figure 5-14.
Figure 5-14: The email response to a user instruction
After receiving an incoming email, the Email Engine processes a user instruction as follows:
1 Retrieves the associated user instruction entry from the AR System Email User
Instruction Templates form and determines which template is associated with the instruction.
2 Retrieves the associated template from the AR System Email Templates form. 3 Replaces the variables in the template with the values defined by the information
in the email.
4 Executes the template with substituted values in the incoming email.
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.
171
Using variables with user instructions

You can also use variables with user instructions. Variables are useful when you need to send different values for the fields to submit an entry. For example, you can create a user instruction that submits information into the User Instruction form. The user might send a user instruction in the following email:
Login:Frank Frontline Password:mypassword Action: Submit !Employee_Name!: [$$Joe Smith$$]
The characters between the exclamation marks match the variable name in the template that is associated with the user instruction (Submit). The Email Engine will then:
1 Match the string between exclamation marks in the email with the variable name
in the template.
2 Retrieve the database name or field ID between the exclamation marks in the
template.
3 Substitute the field with that database name with the value sent in the email.
172
Chapter
Troubleshooting
This chapter contains troubleshooting information. The following topics are provided: Troubleshooting outgoing email (page 174) Error and system status logs (page 174) Debugging options for the Email Engine (page 177) Using the EmailDaemon.properties file (page 179) Creating email debug batch files (page 192) Fixing common problems with the email engine (page 198) Temporary directories and files (page 210)
Chapter 6 Troubleshooting
173
Troubleshooting outgoing email

You will find the AR System Email Messages form especially helpful in troubleshooting outgoing email. Performing a search in the form lets you see the current status of email messages, for example, if outgoing messages are being processed, if they were sent, or if there was an error.
Figure 6-1: Status of email messages
NOTE
If the Email Engine sends system-generated email (for example, due to a bounced email), the email body will be in English only. (System generated emails are also called non-delivery reports [NDRs].)
Error and system status logs

The AR System Email Error Logs form stores error and system status information. This information can be useful in troubleshooting email transmission or email formatting problems, as well as email system environment problems.
174
Error and system status logs
Figure 6-2: AR System Email Error Logs form
Error logs include information such as: Email transmission or instruction failures. AR System API errors. Internal Email Engine errors. System status logs include information about: All incoming emails. (The email is included in the logging message as an attachment.) All outgoing email. (The email is included in the logging message as an attachment.) Connection status information for email servers. Connection status information for the AR System server containing the configuration, logs, and email forms. Date and time the Email Engine was started or stopped. Changes to the configuration of the Email Engine.
TIP
You can access the Email Error Logs form from the BMC Remedy User Object List or the Email Messages form. The Advanced tab in the Email Messages form includes an Errors tab that displays the same log data that is 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 240.
175
Email transmission or instruction failures

When an email transmission fails or an instruction cannot be executed, the system generates an error message and stores it in the AR System Email Error Logs form. Examples of errors include instructions that see a nonexistent form or an invalid server name. In the following sample error message, a form called XYZForm, referenced in two instructions, could not be found on the servereither the form name was entered incorrectly, or the form does not exist.
Instruction: Submit Instruction Number: 1 Instruction Template: Message Type: Message Number: 303 Message Text: Form does not exist on server Appended Text: XYZForm Instruction: Query Instruction Number: 2 Instruction Template: Message Type: Message Number: 303 Message Text: Form does not exist on server Appended Text: XYZForm
AR System API errors

The Email Engine logs any AR System API errors that occur while executing instructions in an email. See the Optimizing and Troubleshooting Guide, API log, page 51.
Internal Email Engine errors

Any internal problems with the Email Engine itself (for example, if the system runs out of disk space) are logged.
Logging levels
Information added to the logs at the minimum logging level (SEVERE) also appears in logs created by using the maximum level (FINEST). The higher levels provide more detailed information, further to that provided by the lower logging levels.
SEVERE
The minimum logging level for Email Engine is SEVERE. When you set this logging level, only severe issues are written to the logs.
176
Debugging options for the Email Engine
INFO
INFO is the next logging level for the Email Engine. Logs created by using this level help trace the flow of execution easily. They include the following types of information: Mailbox names and thread names Entry into and exit from functions Creation of inline or template attachments Creation of AR System server users Initialization of modules
Debugging options for the Email Engine

The logging.properties file that you use for debugging the Email Engine is usually found in the Java lib directory. For specific issues, see Fixing common problems with the email engine on page 198. The following options are available:
Table 6-1: Debugging options for the Email Engine (Sheet 1 of 2) Setting Global Property Handlers handlers = java.util.logging.ConsoleHandler Global Property Handlers handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler Global Logging Level java.util.logging.FileHandler.level = FINER Definition Sets the places where logs can go. In this example, it has been set to send logs only to the console. Enables file logging with console logging. In UNIX, all console output is directed to emailEngineInstallDir/logs/emaild.sh_log, but file logging can also be switched on. Logging level for the file output. You can set the logging level to Finer in the Java logging.properties file to obtain every log message generated by the system. You can also use the keyword ALL, which means all logs are to be sent to the output.
Note: Use this option with care because the contents of
the AR System Email Error Logs form can become very large. Handler Specific Properties java.util.logging.FileHandler.pattern = %h/java%u.log Handler Specific Properties java.util.logging.FileHandler.limit = 50000 Handler Specific Properties java.util.logging.FileHandler.count = 1 File to where logs are made. You can reference the Java documentation on this format, as it is specified by Java 1.5.x logging. Maximum size of the log file in bytes. If the file size exceeds this length, a new file is created. Number to start with. This is appended to the end of the file name.
177
Table 6-1: Debugging options for the Email Engine (Sheet 2 of 2) Setting Definition
Use an XML formatter to format the output, or you can Handler Specific Properties java.util.logging.FileHandler.formatte use java.util.logging.SimpleFormatter with console logging. r = java.util.logging.XMLFormatter Logging level for the file output. Console Handler Specific Properties java.util.logging.ConsoleHandler.level = INFO XML formatter for console logging. Console Handler Specific Properties java.util.logging.ConsoleHandler.forma tter = java.util.logging.SimpleFormatter Main Application Level Level for the entire Email Engine. This setting for the com.bmc.arsys.emaildaemon.level = INFO 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, because 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, and you can set the levels for the different modules independently. Module Levels com.bmc.arsys.emaildaemon.moduleName. level ConfigurationModule.level = FINER CreatorModule.level = FINER ExecutionModule.level = FINER ReceiverModule.level = FINER SenderModule.level = FINER MonitorModule.level = FINER Levels for application modules. You can specify the logging levels for the various modules independently from the entire Email Engine logging level, for only the modules you are interested in troubleshooting. These application modules allow you to combine main application and module logging. For example, if the main application level is set to INFO and you set the level for the Receiver Module to FINER, then you will see only FINER information in the log for the Receiver module. If there is no entry in the logging.properties file for a particular module, then the system defaults to the application level (that is, INFO).
Note: The level for one of the outputs must be at least
FINER, such as the ConsoleHandler, to actually see the log. Application Levels com.bmc.arsys.emaildaemon.ARSystem Handler.level = WARNING Level for the outputs to the BMC Remedy Email Error form. You cannot disable this handler. This level could also be overridden if the application level defined previously is higher.
178
Using the EmailDaemon.properties file
You can change the logging levels of the email engine debugging options at runtime by using the following command:
java -jar EmailAdminAgent.jar setLog debuggingOption loggingLevel
IMPORTANT
Make sure you do not include .level in the debuggingOption when using it in this command. Also, to change the logging level at run time you must set the following in values in logging.properties for the JRE being used:
com.bmc.arsys.emaildaemon.debuggingOption.level = FINEST java.util.logging.ConsoleHandler.level = INFO

TIP
The term email daemon is frequently used when discussing the internal components of the Email Engine. 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 like sending and mails, 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, the Email Engine as synonymous with the email daemon. When the Email Engine is installed, the EmailDaemon.properties file is created in the Email Engine installation directory and is populated with the name of your organizations email server, user name, and password. The main purpose of the EmailDaemon.properties file is to identify the AR System server your Email Engine communicates with.
179
Figure 6-3: Sample contents of EmailDaemon.properties file
To use the EmailDaemon.properties file, see Fixing common problems with the email engine on page 198.
Updating the EmailDaemon.properties file

If your email environment changesfor example, if you need to change a server name or a TCP portthe EmailDaemon.properties file must be updated. The following procedure explains how to update the file.
To update the EmailDaemon.properties file

To update the value of one property at a time, open a command prompt, navigate to the Email Engine installation directory, and execute the following command: For Windows:
JREInstallDir\java -cp jarFileNamesSeparatedBySemicolons; com.bmc.arsys.emaildaemon.EmailDaemon parameter
For UNIX:
JREInstallDir/java -cp jarFileNamesSeparatedByColons: com.bmc.arsys.emaildaemon.EmailDaemon parameter JREInstallDir is the path of your JRE installation.
180
jarFileNamesSeparatedBySemicolons or jarFileNamesSeparatedByColons
are the jar files listed in the command line of the command line from
EmailStart.bat or emaild.sh file.
NOTE
To use this command, you must properly set the library path for all UNIX platforms. To update the values of multiple properties simultaneously, add them to EmailStart.bat (Windows) or emaild.sh (UNIX) and running the executable.
Table 6-2: Email Engine startup parameters Parameter -s -u -p Description Server where the email forms (and the configuration information) are located. User name AR System Application Service password. The Email Engine requires the same password that is supplied on the Connection Settings tab of the AR System Administration: Server Information form. 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. Use this parameter 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.) Authentication 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. Encrypts the given string and returns the value to the command line. The temporary directory to be used for internal Email Engine files. 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. (For 32-bit JVM only) MAPI sent folder where sent mail should be stored. Displays the client version; does not take any parameter.
-t -r
-l -a -d
-i
-e -f -m
-o -v
NOTE
Changing property values does not affect the current instance of the email engine. To use the updated property values, you must restart the email engine service manually. When using EmailStart.bat or emaild.sh to restart the service, make sure to remove all the parameters you used to update the property values.
181
Performance and configuration settings

The email engine internally uses most configuration settings with their default values. The EmailDaemon.properties file lets you specify values other than the defaults for these settings. Table 6-3 lists the properties and their permissible values that you can specify in EmailDaemon.properties to adjust the performance of the email engine. After adding or altering these settings, you must stop and restart the email engine for the changes to take effect. For specific troubleshooting issues, see Fixing common problems with the email engine on page 198.
Table 6-3: Performance and configuration settings for the Email Engine (Sheet 1 of 10) Settings Definitions Values Related Related Functiona Protocol lity Outgoing SMTP
Default value: com.bmc.arsys.ema Specifies additional email headers. ildaemon.Addition Separate the additional email headers with X-LoopDetect alMailHeaders commas. See Adding extra custom headers to outgoing SMTP emails on page 89. com.bmc.arsys.ema Specifies the date and time format that the ildaemon.ARDATE Email Engine uses for parsing date and time strings given in the incoming mails. MMMMM dd, yyyy HH:mm:ss z is equivalent to December 21, 2009 12:08:56 PDT. com.bmc.arsys.ema Specifies the date format that the Email ildaemon.ARDATEON Engine uses for parsing date strings given in incoming mails. MMMMM dd, yyyy is LY equivalent to December 21, 2009. com.bmc.arsys.ema This setting lets you specify the time ildaemon.ARTIMEON format used by the Email Engine for parsing time strings given in incoming LY mails. HH:mm:ss z is equivalent to 12:08:56 PDT. com.bmc.arsys.ema This setting indicates whether to send the ildaemon.ContentT charset property in the Content-Type ypeWithCharset header of an outgoing message. If you do not want the charset string to be present in the Content-Type header, set this property to False. com.bmc.arsys.ema Specifies the number of entries to return Default value: ildaemon.ChunkSiz when the Email Engine makes a call to the 100 e AR System server.
Incoming All Supported
True (Default) Outgoing All Supported False
Outgoing All Supported
182
Table 6-3: Performance and configuration settings for the Email Engine (Sheet 2 of 10) Settings Definitions Values Related Related Functiona Protocol lity
com.bmc.arsys.ema ildaemon.CommaVal idAddressSeparato r
Specifies whether you can use a comma as a separator when entering multiple addresses in the To and CC fields. If user names in the mail server contain commas, set this property to false (usually needed only when using the MAPI protocol). For example, if names are stored on the mail server as: Smith, John and Cho, Rick You would need to use semicolons to separate the addresses: Smith, John; Cho, Rick
True (Default) Incoming All and Supported False Outgoing
Default value: 1 Incoming All com.bmc.arsys.ema Specifies the amount of time in supported ildaemon.Exchange milliseconds for which the Email Engine waits before processing the next incoming -Wait-Time message, when there are more messages residing on the Exchange Server. com.bmc.arsys.ema ildaemon.FetchUse rGroupInfoOnDeman d Specifies whether to fetch the user and group information on demand as opposed to loading all users and groups at startup. If there are many users or groups, you might want to set this property to true to reduce the startup time for email. True Incoming All Supported False (Default) and Outgoing
183
com.bmc.arsys.ema Determines whether the outgoing message ildaemon.getReply header should contain the Reply To field ToWithFromAddress and what its value should be. getReplyToWithFromAddress is not used by default. If you want the email engine to use this property, you must add it to EmailDaemon.properties and set its value to true. If you add the property but do not specify a value, it is considered as false. The effect of using this property is as follows: If no values are provided in the Reply To Address field of the outgoing mailbox configuration form and the Reply To field of the messages form, and the value of this property is: false (or not provided)the Reply To field is not included in the outgoing message header. truethe Reply To field is included in the outgoing message header, and its value is the address in the From field of the messages form. If the Reply To Address field of the outgoing mailbox configuration form or the Reply To field of the messages form contains a value, the message header will contain the Reply To header value as set in the message, irrespective of value of this property. com.bmc.arsys.ema ildaemon.Incoming ConnectionRecycle Size Specifies the default number of email messages the email engine receives before the connection is closed and reopened. In the 5.1 and 5.1.1 releases of the email engine, the connection with the mail server was closed only after reading all incoming messages. Consequently, if the email engine crashed or hung before the connection was closed, it was possible that messages marked for deletion would not be deleted from the mail server. This property helps you avoid that situation.
Default value: 100
184
Table 6-3: Performance and configuration settings for the Email Engine (Sheet 4 of 10) Settings Definitions Values Related Related Functiona Protocol lity Incoming All Supported
com.bmc.arsys.ema Specifies the message queue size (number Default value: 100 ildaemon.Incoming of emails). MessagesQueueSize The Receiver module writes messages to the queue, and the Execution module reads messages from this queue to parse and execute. The Receiver module still writes messages to the 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. com.bmc.arsys.ema Specifies the number of instructions to be ildaemon.instruct stored in the cache, which is used to improve performance. ionCacheSize If the value of this property is set to 15, the cache already contains 15 instructions, and another instruction is to be added, then the oldest instruction is removed to accommodate the newest one.
Note: If any changes are made to the
Default value: 20
AR System Email Instructions form, the instruction cache is flushed based on the setting of the serverName.Interval property. com.bmc.arsys.ema If you run multiple instances of the email ildaemon.Mailboxe engine on a single server, this property s specifies which mailboxes should the email engine process. The value of this property should contain comma-separated mailbox names; the email engine only processes these mailboxes. If you do not specify a value, the email engine processes all of the mailboxes configured for the server. Incoming All and Supported Outgoing
185
com.bmc.arsys.ema ildaemon.MailboxP ollingUnitIsMinut es
Specifies whether the polling interval is to be considered in minutes (as configured in AR System Email Configuration) or seconds. The email engine interprets the value of this property as follows: trueConsider the polling interval in minutes. falseConsider the polling interval in seconds.
Note: Whatever measure of unit you select
True (Default) Incoming All and Supported False Outgoing
applies to all configured mailboxes that are enabled. com.bmc.arsys.ema Specifies the attachment types that you ildaemon.MaxAttac want to permit in an email message and the maximum size of each attachment. hSize MaxAttachSize specifies the maximum com.bmc.arsys.ema size limit for attachments, whereas ildaemon.MaxAttac MaxAttachSizeFileExtensions hSizeFileExtensio specifies the file types by using commaseparated extensions. These properties ns must be used together to impose limits on email attachments of specific file types. For example, to set the maximum size of .doc, .pdf, and .xls attachments to 1000000 bytes (1 MB), use the following syntax: and com.bmc.arsys.emaildaemon.MaxAt tachSize=1000000 com.bmc.arsys.emaildaemon. MaxAttachSizeFileExtensions=doc ,pdf,xls The size limit is not imposed on files whose extensions are not specified by using MaxAttachSizeFileExtensions. Email messages with attachments that exceed this limit are logged to the AR System Email Error Logs form. Optionally, you can create workflow for this form to process such messages separately. True Incoming All Supported False (Default)
186
com.bmc.arsys.ema The email engine interprets the value of ildaemon.MBOXFrom this property as follows: LineWith-At-ThetrueEmail Engine fetches only those Rate-Sign messages that contain the @ sign in the from line (from address). falseEmail Engine fetches all the messages. com.bmc.arsys.ema Specifies the interval in minutes between ildaemon.Monitor checks to see if all the threads are functioning properly.
Note: If the monitoring system detects that
True Incoming MBOX False (default) and Outgoing
Default value: 30 minutes
Incoming All and Supported Outgoing
a thread has failed, it restarts the thread. com.bmc.arsys.ema Specifies the number of sender threads ildaemon.NumberOf that the email daemon uses for each SenderThreads outgoing mailbox. Permissible Outgoing All range of values: Supported 1 through 20
The optimum number of threads depends on many factors including the number of Default value: 4 mailboxes, the hardware configuration, and so on. com.bmc.arsys.ema Specifies the size of the queue that the ildaemon.Outgoing email daemon maintains for outgoing MessagesQueueSize messages. The optimum number of message queue size to be specified depends on the load on the email daemon.
Note: This value is used to determine when
Default value: 100
to query the database. If you set a very high value, the database is queried too often, which might reduce the performance. com.bmc.arsys.ema Specifies the port number for remote ildaemon.RMIPORT method invocation (RMI). = 1100 This feature is used with the EmailAdminAgent.jar file to stop, suspend, resume, or change logging level of the email engine at runtime. com.bmc.arsys.ema Specifies whether to retain messages in the ildaemon.SaveSent Email Messages form after sending. Item To delete sent messages from the Email Messages form, set this property to False. Default value: 1100 Incoming All and Supported Outgoing
187
Table 6-3: Performance and configuration settings for the Email Engine (Sheet 7 of 10) Settings Definitions Values Related Related Functiona Protocol lity Incoming All and Supported Outgoing
com.bmc.arsys.ema Specifies the number of security keys to be Default value: 20 ildaemon.security stored in the cache. CacheSize If the value of this property is set to 15, the cache already contains 15 security keys, and another key is to be added, then the oldest key is removed to accommodate the newest one.
AR System Email Security form, the security cache is flushed based on the setting of the serverName.Interval property. com.bmc.arsys.ema Specifies the number of outgoing emails to Default value: ildaemon.SendEmai query at a time. 100 lSetSize com.bmc.arsys.ema Specifies a string if your AR System server ildaemon.serverNa requires authentication information before me.Authentication handling requests. com.bmc.arsys.ema Specifies the interval in minutes after ildaemon.serverNa which to check with the server for the me.Interval following: Configuration updates (for example, if you modified records in the AR System Email Mailbox Configuration form) Updates to the templates (for example, if you modified templates in the AR System Email Templates form) Any changes done to the forms on the server (for example, if you added or deleted any field on any form) com.bmc.arsys.ema Specifies the language that the email ildaemon.serverNa engine must use. me.Language com.bmc.arsys.ema Specifies the RPC port number that the ildaemon.serverNa AR System server uses if you have me.RPC configured a private server to be used with the email engine. com.bmc.arsys.ema Specifies the TCP port number that the ildaemon.serverNa AR System server uses if it is not using the me.TCP BMC Remedy AR System portmapper. com.bmc.arsys.ema Specifies the name of the AR System server ildaemon.Servers that the email engine interacts with. Default value: en_US Default value: 30 Outgoing All Supported
188
com.bmc.arsys.ema Specifies whether to wait before cancelling ildaemon.SMTPTime an attempt to connect to the mail server out and generating an error. In case of an SMTP timeout, the email engine waits for the timeout interval and then marks the queued message as erroneous. SMTPTimeout is not used by default. If you want the email engine to use this property, you must add it to EmailDaemon.properties and set its value to true. If you add the property but do not specify a value, it is considered as false.
Note: See Recommendation for using the
True Outgoing SMTP False (Default)
SMTP timeout properties on page 192. com.bmc.arsys.ema Specifies the duration in number of ildaemon.SMTPTime seconds to wait before cancelling an attempt to connect to the mail server and outPeriod generating an error. In case of an SMTP timeout, the email engine waits for this interval and then marks the queued message as an erroneous. SMTPTimeoutPeriod is not used by default. If you want the email engine to use this property, you must add it to EmailDaemon.properties and set its value to any positive integer (upper limit depends on the platform). If you add the property but do not specify a value, it is considered as half the polling interval that is set for outgoing mailboxes.
Note: SMTPTimeoutPeriod is dependent
Outgoing SMTP
on SMTPTimeout; it works only when SMTPTimeout is set to true.

Note: See Recommendation for using the
SMTP timeout properties on page 192. com.bmc.arsys.ema Specifies whether to process messages ildaemon.SortMess with a higher priority setting first. ages True Outgoing All Supported False (Default)
189
com.bmc.arsys.ema Specifies whether to store instructions and ildaemon.StoreIns instruction parameters in the AR System tructions server. If set to true, the email engine retains data in the Email Instructions and Instruction Parameters forms for troubleshooting. Then, you must delete this data explicitly. The 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.bmc.arsys.ema This property is not available by default. ildaemon.Synchron You can add it if required. izedLoggingMode If this property is not present in EmailDaemon.properties, or if it is present but set to false, the bulk API logging mode is used. If this property is present in EmailDaemon.properties and its value set to true, then the synchronized logging mode is used.
Note: The email engines performance
True Incoming All supported False (Default)
Incoming All True Supported False (Default) and Outgoing
might degrade when synchronized logging is enabled, because all the email engine threads are suspended while processing the synchronized logs. Synchronized logging continues to occur periodically, and control is restored to the threads only after the logging is over. com.bmc.arsys.ema Specifies the number of email templates to Default value: ildaemon.template be stored in the cache to improve the 20 CacheSize performance. If the value of this property is set to 15, the cache already contains 15 templates, and another template is to be added, then the oldest template is removed to accommodate the newest one.
AR System Email Templates form, the templates cache is flushed based on the setting of the serverName.Interval property.
190
com.bmc.arsys.ema Specifies whether an <a href> tag is ildaemon.URLWithH placed around a URL in an HTML refTag message. If the setting is true, the <a href> tag is used. If the setting is false, the URL is not enclosed in an <a href> tag. com.bmc.arsys.ema Specifies whether to retain display names ildaemon.UseNameI that do not have email addresses associated fNoEmailAddress with them in the To, CC, or BCC fields. If the setting is true, the display names are not removed from the To, CC, or BCC fields. If the setting is false, the display names are removed from the To, CC, or BCC fields.
Note: The email engine checks for email
addresses associated with display names only on the User form and not on the Exchange server. com.bmc.arsys.ema Specifies the number of users (records ildaemon.UserChun from the User form) to retrieve from the kSize AR System server at one time. This setting can be used to tune the email engines performance. com.bmc.arsys.ema Specifies the email address of the ildaemon.AdminAdd administrator. If a database transaction fails while storing an incoming message, resses the email engine forwards the original mail to this email address, so that it is retained. An example of a transaction failure could be when the database is full and cannot save anymore incoming email messages. You can specify multiple addresses separated by commas.
Note: This property can be used only when
Default value: 5000
Default value is Incoming All Supported set to the administrator address specified during installation.
the Email Engine does not capture the error out incoming email messages in the AR System Email Error Messages Form.
191
Recommendation for using the SMTP timeout properties

If you use the email engine properties SMTPTimeout and SMTPTimeoutPeriod, you might encounter problems with outgoing email messages. After a timed out connection is restored, messages marked as Error (in the Send Message field) are not sent consistentlysome messages are sent successfully, while others are not. This seems to be a JavaMail issue (SW00364840 in the Release Notes) for which we do not yet have a workaround. To avoid facing this issue, you might want to refrain from using these properties until a solution is made available. If you use the SMTPTimeout and SMTPTimeoutPeriod properties, BMC recommends the following configurations to avoid encountering the issue:
Number of messages 40000 70000 100000 Value of SMTPTimeoutPeriod 30 seconds 60 seconds 90 seconds
NOTE
These settings can work properly with the maximum permissible number (20) of Sender threads. However, BMC recommends using a value that is optimum for your configuration.
Creating email debug batch files

Creating a debug email batch file by using the -Dmail.debug=true debug mode can help resolve issues that might not show up in the email error log. You accomplish this by setting the debug mode for the Java process that runs the Email Engine. You might find this procedure useful for debugging the Email Engine in contrast to using the AR System Email Error Logs form. The contents of the AR System Email Error Logs form can become very large.
192
Debugging the Email Engine on Windows

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

1 In the EmailStart.bat file, add the -Dmail.debug=true option as follows: "%JavaPath%\java" -Dmail.debug=true -cp emaildaemon.jar;arapireleaseNum.jar;arutilreleaseNum.jar;activatio n.jar;mail.jar;imap.jar;smtp.jar;pop3.jar;armapireleaseNum.jar com.bmc.arsys.emaildaemon.EmailDaemon
The default location of the EmailStart.bat file is

C:\Program Files\BMC Software\ARSystem\AREmail. 2 Save the batch file as another name, for example, emaildebug.bat. 3 Make sure that the Email Engine service is stopped in the Services window. 4 Open a command prompt, change the directory to the location of the AR System
install directory, and run the new batch file. This batch file adds debug information to the screen when the Email Engine is started from a command prompt. You can also direct the output to a file by adding > c:\temp\debug.out to the end of the previous Java statement.
Sample debug log

The contents of a sample debug log follow.
C:\Program Files\BMC Software\ARSystem\AREmail>echo off Application has started Version: 07.00.00 Using JRE: 1.5.0_11 Checking connection to server: polycarp ... loaded library Successfully connected. DEBUG: JavaMail version 1.3 DEBUG: successfully loaded file: C:\Program Files\Java\j2re1.5.0_11\lib\javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/emaildaemon.jar!/META-INF/javamail.providers DEBUG: Bad provider entry: DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/emaildaemon.jar!/META-INF/ javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/imap.jar!/META-INF/javamail.providers DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/imap.jar!/META-INF/ javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/smtp.jar!/META-INF/javamail.providers
193
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.jar!/META-INF/ javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/pop3.jar!/META-INF/javamail.providers DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/pop3.jar!/META-INF/ javamail.providers DEBUG: successfully loaded resource: /META-INF/ javamail.default.providers DEBUG: Tables of loaded providers DEBUG: Providers Listed By Class Name: {com.bmc.mail.mapi.MAPITransport=javax.mail.Provider[TRANSPORT,map itransport,com.bmc.mail.mapi.MAPITransport,mapi@bmc.com], com.bmc.mail.mapi.MAPIStore=javax.mail.Provider[STORE,mapistore,co m.bmc.mail.mapi.MAPIStore,mapi@bmc.com], com.sun.mail.smtp.SMTPTransport=javax.mail.Provider[TRANSPORT,smtp ,com.sun.mail.smtp.SMTPTransport,Sun Microsystems, Inc], com.sun.mail.imap.IMAPStore=javax.mail.Provider[STORE,imap,com.sun .mail.imap.IMAPStore,Sun Microsystems, Inc], com.sun.mail.pop3.POP3Store=javax.mail.Provider[STORE,pop3,com.sun .mail.pop3.POP3Store,Sun Microsystems, Inc]} DEBUG: Providers Listed By Protocol: {imap=javax.mail.Provider[STORE,imap,com.sun.mail.imap.IMAPStore,S un Microsystems, Inc], mapistore=javax.mail.Provider[STORE,mapistore,com.bmc.mail.mapi.MA PIStore,mapi@bmc.com], mapitransport=javax.mail.Provider[TRANSPORT,mapitransport,com.bmc. mail.mapi.MAPITransport,mapi@bmc.com], pop3=javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Su n Microsystems, Inc], smtp=javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTran sport,Sun Microsystems, Inc]} DEBUG: successfully loaded resource: /META-INF/ javamail.default.address.map DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/smtp.jar!/META-INF/javamail.address.map DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.jar!/META-INF/ javamail.address.map DEBUG: java.io.FileNotFoundException: C:\Program Files\Java\j2re1.5.0_11\lib\javamail.address.map (The system cannot find the file specified) DEBUG: JavaMail version 1.3 DEBUG: successfully loaded file: C:\Program Files\Java\j2re1.5.0_11\lib\javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/emaildaemon.jar!/META-INF/javamail.providers DEBUG: Bad provider entry: DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/emaildaemon.jar!/META-INF/ javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/imap.jar!/META-INF/javamail.providers 194 BMC Remedy Email Engine Guide
DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/imap.jar!/META-INF/ javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/smtp.jar!/META-INF/javamail.providers DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.jar!/META-INF/ javamail.providers DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/pop3.jar!/META-INF/javamail.providers DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/pop3.jar!/META-INF/ javamail.providers DEBUG: successfully loaded resource: /META-INF/ javamail.default.providers DEBUG: Tables of loaded providers DEBUG: Providers Listed By Class Name: {com.bmc.mail.mapi.MAPITransport=javax.mail.Provider[TRANSPORT,map itransport,com.bmc.mail.mapi.MAPITransport,mapi@bmc.com], com.bmc.mail.mapi.MAPIStore=javax.mail.Provider[STORE,mapistore,co m.bmc.mail.mapi.MAPIStore,mapi@bmc.com], com.sun.mail.smtp.SMTPTransport=javax.mail.Provider[TRANSPORT,smtp ,com.sun.mail.smtp.SMTPTransport,Sun Microsystems, Inc], com.sun.mail.imap.IMAPStore=javax.mail.Provider[STORE,imap,com.sun .mail.imap.IMAPStore,Sun Microsystems, Inc], com.sun.mail.pop3.POP3Store=javax.mail.Provider[STORE,pop3,com.sun .mail.pop3.POP3Store,Sun Microsystems, Inc]} DEBUG: Providers Listed By Protocol: {imap=javax.mail.Provider[STORE,imap,com.sun.mail.imap.IMAPStore,S un Microsystems, Inc], mapistore=javax.mail.Provider[STORE,mapistore,com.bmc.mail.mapi.MA PIStore,mapi@bmc.com], mapitransport=javax.mail.Provider[TRANSPORT,mapitransport,com.bmc. mail.mapi.MAPITransport,mapi@bmc.com], pop3=javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Su n Microsy stems, Inc], smtp=javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTran sport,Sun Microsystems, Inc]} DEBUG: successfully loaded resource: /META-INF/ javamail.default.address.map DEBUG: URL jar:file:/C:/Program%20Files/BMC%20Software/ARSystem/ AREmail/smtp.jar!/META-INF/javamail.address.map DEBUG: successfully loaded resource: jar:file:/C:/Program%20Files/ BMC%20Software/ARSystem/AREmail/smtp.jar!/META-INF/ javamail.address.map DEBUG: java.io.FileNotFoundException: C:\Program Files\Java\j2re1.5.0_11\lib\javamail.address.map (The system cannot find the file specified) DEBUG: getProvider() returning javax.mail.Provider[STORE,pop3,com.sun.mail.pop3.POP3Store,Sun Microsy stems, Inc] POP3: connecting to host "essmail2", port 110 S: +OK Microsoft Exchange 2000 POP3 server version 6.0.6249.0 (essmail2.eng.bmc.com) ready. Chapter 6 Troubleshooting 195
C: USER stamps3 S: +OK C: PASS password S: +OK User successfully logged on. C: STAT S: +OK 0 0 C: QUIT S: +OK Microsoft Exchange 2000 POP3 server version 6.0.6249.0 signing off
To generate debug log using the Windows Email Engine service

1 From the Services window, stop the Email Engine service. 2 Open the Windows registry, and navigate to HKEY_LOCAL_MACHINE > SYSTEM > CurrentControlSet > Services > Email Engine > machineName > Parameters. 3 Create a new String Value, name it JVM Option Number 4, and set its value to -Dmail.debug=true. 4 Change the value of JVM Option Count to 5. 5 Start the Email Engine service.
The debug log is available in the emailEngineInstallDir\Logs\stdout.log file.
Debugging the Email Engine on UNIX

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

1 In the emaild.sh script, add the following option to the line that starts the Java process in the emaild.sh script: -Dmail.debug=true 2 Edit the emaild.sh script from: exec ${JAVA_BIN}/java -Djava.library.path=${InstallPath} -cp ${CP_PATH} com.bmc.arsys.emaildaemon.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1
to the following content:

exec${JAVA_BIN}/java -Djava.library.path=${InstallPath} -Dmail.debug=true -cp ${CP_PATH} com.bmc.arsys.emaildaemon.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1 3 Stop and start the Email Engine.
196
Example of outgoing email using SMTP

The contents of a sample debug log for outgoing email follow.
DEBUG: getProvider() returning javax.mail.Provider[TRANSPORT,smtp,com.sun.mail.smtp.SMTPTransport ,Sun Microsystems, Inc] DEBUG SMTP: useEhlo true, useAuth true DEBUG: SMTPTransport trying to connect to host "cruiser", port 25 DEBUG SMTP RCVD: 220 cruiser.bmc.com ESMTP Sendmail 8.11.6+Sun/ 8.11.6; Mon, 10 Feb 2004 12:19:35 -0800 (PST) DEBUG: SMTPTransport connected to host "cruiser", port: 25 DEBUG SMTP SENT: EHLO cruiser.bmc.com DEBUG SMTP RCVD: 250-cruiser.bmc.com Hello cruiser.bmc.com [10.4.30.23], pleased to meet you 250-ENHANCEDSTATUSCODES 250-EXPN 250-VERB 250-8BITMIME 250-SIZE 250-DSN 250-ONEX 250-ETRN 250-XUSR 250 HELP DEBUG SMTP Found extension "ENHANCEDSTATUSCODES", arg "" DEBUG SMTP Found extension "EXPN", arg "" DEBUG SMTP Found extension "VERB", arg "" DEBUG SMTP Found extension "8BITMIME", arg "" DEBUG SMTP Found extension "SIZE", arg "" DEBUG SMTP Found extension "DSN", arg "" DEBUG SMTP Found extension "ONEX", arg "" DEBUG SMTP Found extension "ETRN", arg "" DEBUG SMTP Found extension "XUSR", arg "" DEBUG SMTP Found extension "HELP", arg "" DEBUG SMTP: use8bit false DEBUG SMTP SENT: MAIL FROM: DEBUG SMTP RCVD: 250 2.1.0 ... Sender ok DEBUG SMTP SENT: RCPT TO: DEBUG SMTP RCVD: 250 2.1.5 ... Recipient ok Verified Addresses rsteck@bmc.com DEBUG SMTP SENT: DATA DEBUG SMTP RCVD: 354 Enter mail, end with "." on a line by itself DEBUG SMTP SENT: DEBUG SMTP RCVD: 250 2.0.0 h1AKJZh09819 Message accepted for delivery
197
Example of incoming email using MBOX

The contents of a sample debug log for incoming email follow. You can see the lock file get createdthe file is read and saved, and then the lock is removed.
# tail -f emaild.sh_log DEBUG: java.io.FileNotFoundException: /usr/java1.5.0/j2se/jre/lib/ javamail.address.map (No such file or directory) DEBUG: getProvider() returning javax.mail.Provider[STORE,mbox,gnu.mail.providers.mbox.MboxStore,d og@gnu.org] mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock mbox: creating /var/mail/arsystem.lock mbox: reading /var/mail/arsystem mbox: saving /var/mail/arsystem mbox: removing /var/mail/arsystem.lock
Fixing common problems with the email engine

This section describes how to diagnose and solve some problems you might encounter with the Email Engine. The Email Engine can be a powerful and useful tool if configured and used correctly.
Configuring mailboxes
A common problem that users experience with the Email Engine is that they cannot send or receive email. A straightforward way to troubleshoot this problem is to verify that you have properly configured your incoming and outgoing mailboxes.
198
Testing your incoming mailbox

If you were unable to test your incoming mailbox configuration successfully, verify the following conditions: The Email Engine is running. The mail server is running. The Status field of the mailbox is set to Enabled. The email account used by the Incoming Mailbox is a valid account on the mail server (POP3/IMAP4), or the Exchange profile specified for this mailbox is accessible on the system the Email Engine is running on (MAPI).
NOTE
By default, the Email Engine service is launched as the local system account. However, if you elected to configure a MAPI mailbox during installation, you must change the login information (in the Services control panel) for the Email Engine service from the local system account to the appropriate account. The port number in the mailbox entry is the proper port number for communicating with your mail server. You entered the correct 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 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
The Email Engine might not immediately recognize changes you make to your mailbox in an effort to troubleshoot possible configuration problems. For more information, see Changing the form entry interval time on page 44.
Testing your outgoing mailbox

If you were unable to test your outgoing mailbox configuration successfully, verify the following conditions: The Email Engine is running. The mail server is running. The Status field of the mailbox is to Enabled. Determine if the mail server requires authentication for messages to be sent. If your mail server requires authentication, then you must make sure that you have provided valid email account information for this mail server in the Basic Configuration tab for this mailbox (SMTP) or the name of a valid Exchange profile (MAPI).
Chapter 6 Troubleshooting 199
The port number in the mailbox entry is the proper port number for communicating with your mail server. You entered the correct password for the email account in the Outgoing Mailbox Basic configuration tab (SMTP) or you logged in to the system as the domain user account that has permission to use the Microsoft Exchange profile (MAPI). You waited for a period of time not less than that indicated by the Polling Interval before checking the AR System Email Messages form to see if your message was sent.
NOTE
The Email Engine might not immediately recognize changes you make to your mailbox in an effort to troubleshoot possible configuration problems. For more information, see Changing the form entry interval time on page 44.
Logging problems with the Email Engine

The reason you have problems sending or receiving email can depend on when the error occurs and the frequency at which it occurs. The best way to troubleshoot these problems is by creating log files and examining your console output.
To use the Email Engine logs and console output

1 Stop the Email Engine, and then re-start it from the command line by using debug
mode. For more information, see Creating email debug batch files on page 192.
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 you look 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, emailEngineInstallDir\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 UNIX, the console output is placed under the emailEngineInstallDir/ logs directory, but is stored in only one file called emaild.sh_log.
200
4 Make sure that console logging is turned on in the logging.properties file, located in the javaInstallDir/lib directory. 5 Enable the console output with the following handler property: handlers = java.util.logging.ConsoleHandler 6 Set the level for console logging.
By default, the level is usually set to INFO, which locates most problems with the Email Engine. You set this level with the following line:
java.util.logging.ConsoleHandler.level = INFO 7 Set the level for the entire application. Make sure that the following two lines are located in the logging.properties file: com.bmc.arsys.emaildaemon.level = INFO com.bmc.arsys.emaildaemon.ARSystemHandler.level = INFO
The first line sets the level for the entire application; the second line sets the level for logging to the AR System Email Error Logs form. The level for the form logging should never be set lower than this. Otherwise, the table will fill up very quickly and use unnecessary space.
Defining a heap size for the Email Engine

Release 7.5.00 onwards, the initial minimum (-Xms256m) and maximum (-Xmx1024m) Java heap sizes are set at the time of installation by updating the appropriate: Email Engine registry key and the value in the EmailStart.bat file, on Windows Value in the emaild.sh file is updated, on UNIX If you run out of memory, you should adjust your heap size according to your memory needs.
NOTE
BMC cannot recommend the exact heap sizes to suit your environment; try to modify the minimum and maximum settings, and then stop and restart the Email Engine. You might see dramatic improvements in performance.
201
Changing the heap size on Windows

You can change the minimum and maximum values for the Java heap size in two ways, depending on how you run the Email Engine: If you use the Email Engine service, modify the registry as follows: Key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BMC
Remedy Email Engine - serverName instanceNumber\Parameters where instanceNumber is the number assigned to the instance of the Email
Engine for which you want to change the Java heap size. Tag: JVM Option Number 2 (minimum) or JVM Option Number 3 (maximum) Value: -XmsSize (minimum) or -XmxSize (maximum) When both the minimum and maximum Java heap size values are set in the registry, the JVM Option Count will be 4. If you use EmailStart.bat, then edit the minimum and maximum Java heap size values in that file. For example, the line for this setting might look like:
set JAVA_OPTS=-Xms256m -Xmx1024m
Changing the heap size on UNIX

To change the minimum and maximum Java heap size values, edit the emaild.sh file to include the options:
-XmsSize to specify the minimum heap size -XmxSize to specify the maximum heap size
For example, the line for this setting might look like:
java -Xms256m -Xmx1024m com.bmc.arsys.emaildaemon.EmailDaemon
Troubleshooting startup issues

After installing the new Email Engine, users might find that email has not been sent or received. In this situation, new email, ready to be sent, has the status set to Yes, but the status does not change to Error or Sent. The following troubleshooting sections describe some common scenarios and their possible solutions.
202
Restarting a Windows system where the AR System server and Email Engine are installed
The BMC Remedy Email Engine service runs independent of the AR System server service. You might not encounter any problems if you start the Email Engine service while the AR System server is running. However, if you start the Email Engine service and the AR System server is not available for some reason, then the Email Engine fails to connect with the AR System server and generates ARERR 90. This situation could occur when you restart the Windows system where the AR System server and Email Engine are installed, and the Startup Type for both services is Automatic. This problem did not occur in the earlier releases, because you could not start the Email Engine service unless the AR System server was already running.
Identifying invalid application service passwords

When viewing the AR System Email Error Logs form, you might not find any errors. Further, it might seem that the email daemon is not working at all. In this situation, the most likely problem is that the Email Engine is not able to communicate with the AR System server. If you encounter ARERR 623, you might have supplied an invalid application service password during installation. The Email Engine uses the Application Service Password to communicate with the AR System server. When that password is changed at the server, you must change it for the Email Engine by updating the EmailDaemon.properties file. For more information about the EmailDaemon.properties file, see Updating the EmailDaemon.properties file on page 180.
To identify and correct an invalid password

1 Start the Email Engine from the command line. 2 Open the stdout.log (Windows) or emaild.sh_log (UNIX) file to note the JRE
version used by Email Engine. The JRE version should be 1.5.0 or higher. Typically, a functioning email daemon outputs the following status information:
Checking connection to server: ARSystemServerName ... Application has started Version: emailEngineVersionNUmber Using JRE: JREVersionNumber Successfully connected
If stdout.log or emaild.sh_log is not present, these messages are displayed on the console.
NOTE
Installing Java version 1.5.0 (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.5.0 (or later).
203
If the email daemon was unable to connect to the AR System server, you might see the following error:
Checking connection to server: ARSystemServerName ... ERROR (623): Authentication failed; Cannot connect.
If you see this, the Application Service Password you supplied during installation is incorrect.
3 To fix the problem, run the EmailStart.bat (Windows) or emaild.sh (UNIX) script by passing the -p applicationServicePassword parameter.
This updates the system with the correct password by applying the changes to the EmailDaemon.properties file. You can also change the application service password by editing and then running the script. If you do so, make sure to remove this parameter from the script afterwards, and restart the email daemon.
Determining if the wrong AR System server is specified

Another common problem is that you specified the wrong AR System server name when you installed the Email Engine. You can fix this problem by executing a search and replace on the contents of the EmailDaemon.properties file.
To determine if a wrong AR System server is specified

1 Open the EmailDaemon.properties file. 2 Replace all references to the incorrect server name with the correct server name.
Because the file uses the server name in several places, the search and replace functionality is required.
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.bmc.arsys.emaildaemon.ARSystemServerName.TCP=4040 com.bmc.arsys.emaildaemon.ARSystemServerName.RPC=0
Remember that the ARSystemServerName tag is the name of the server against which the Email Engine is running and could be an alias like production (for example, com.bmc.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.
204
Determining problems with the mail server

If the email daemon is able to connect to the AR System server, but incoming email is not logged and outgoing emails have not been sent, errors should be logged in the form and on the console, assuming that console logging has been enabled properly. Some error messages you might encounter with the mailbox include: Unknown Host Exception Authentication Failed Exception Connect Exceptions, such as Connection Refused In these situations, the problem is usually because the mailbox has not been configured properly in the AR System Email Mailbox Configuration form. The connection exception error might also occur if the email server (such as Microsoft Exchange) is too busy to handle the connection or you have connected too many times in a given time period (due to a DOS attack). Use the following procedure to check the mail server.
To determine problems with the mail server

Search mode.
2 Open the entries for both the incoming and outgoing mailboxes. 3 Check the email server name. Confirm that you can ping or connect from the
system by using an email client, such as Microsoft Outlook Express.

4 Confirm the email server supports the protocol you supplied, for example, MAPI
or SMTP.
5 Confirm the email server port. 6 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.
7 Check the User Name and Password. Retype them if necessary.
WindowsFixing MAPI transport problems

When using the Email Engine on Windows, your primary email server is Microsoft Exchange, and you have specified MAPI as the protocol to use, you might encounter the following MAPI transport error when starting the email daemon:
Application has started Version: 07.00.00 Using 1.5.0_11 loaded library 8-Apr-2004 12:00:36 PM javax.mail.Session getService SEVERE: mapitransport javax.mail.NoSuchProviderException: mapitransport at javax.mail.Session.getService(Session.java:760) at javax.mail.Session.getTransport(Session.java:685) at javax.mail.Session.getTransport(Session.java:628) Chapter 6 Troubleshooting 205
at javax.mail.Session.getTransport(Session.java:608) at com.bmc.arsys.emaildaemon.SenderModule.openTransport (SenderModule.java:103) at com.bmc.arsys.emaildaemon.CreatorModule.doWork (CreatorModule.java:323) at com.bmc.arsys.emaildaemon.ThreadBase.run (ThreadBase.java:259) at java.lang.Thread.run(Thread.java:536)
You typically see this problem when the Oracle JavaMail system does not know what transport setting to use for MAPI, and the library cannot locate the correct class to use for MAPI.
To fix the MAPI transport problem (Windows)

1 Locate the javamail.providers file in the lib directory of the JRE installation. This is the same location as the logging.properties file. You can create this file
if necessary.
2 On the first line, verify (or add) the following text: protocol=mapistore; type=store; class=com.bmc.mail.mapi.MAPIStore; vendor=mapi@bmc.com; 3 On the second line, verify (or add) the following text: protocol=mapitransport; type=transport; class=com.bmc.mail.mapi.MAPITransport; vendor=mapi@bmc.com; 4 Stop and re-start the Email Engine.
These settings make sure that the JavaMail system uses the class created to support MAPI for both incoming and outgoing mailboxes.
NOTE
The MAPI protocol for incoming and outgoing mail is disabled for 64-bit JVM.
BMC Remedy Email Engine behavior with PLAIN Authentication mode

BMC Remedy Email Engine did not work with the PLAIN authentication mode.
NOTE
This is not an issue, but by design. BMC Remedy Email Engine does not support the PLAIN authentication mode; instead, it uses the LOGIN command mechanism to connect to the Microsoft Exchange Server. Therefore, if Exchange Server uses PLAIN authentication, you need to add the following parameters to the registry for the email engine to work:
mail.imap.auth.login.disable=false mail.imap.auth.plain.disable=true
206
If you start the email engine in the debug mode, you need to add the following parameters to the Emailstart.bat (Windows) or emaild.sh (UNIX) file:
-Dmail.imap.auth.login.disable=false -Dmail.imap.auth.plain.disable=true
Using these parameters forces the Exchange Server and the email engine to disable PLAIN authentication and enable the simple LOGIN command mechanism.
WARNING
BMC Remedy Email Engine does not support the PLAIN authentication mode with the IMAP protocol.
Stopping and starting the AR System server

If you stop AR System, the email daemon stops all the appropriate threads until the AR System server is started again. During this time, the email daemon stops all the threads monitoring this AR System server for new outgoing emails and also all the associated mailboxes for new incoming emails. After these threads have been stopped, the email daemon goes to sleep for the configured time period (the default setting is 30 minutes). When that time expires, the email daemon then checks if the AR System server is running and takes one of two actions based on the results: If the AR System server is still down, the email daemon will go back to sleep for the configured time period. If the AR System server is running, the email daemon will restart all the appropriate threads and continue to run as it normally should. You can adjust the configuration time that the email daemon monitors the AR System server by modifying the following line in the EmailDaemon.properties file:
com.bmc.arsys.emaildaemon.Monitor=monitorInterval monitorInterval is any valid integer, and this parameter is measured in minutes. If you set monitorInterval 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.
207
Making changes to mailbox configuration

If you make changes to the configuration of any mailbox or remove the mailbox by deleting the entry for this mailbox, you do not need to restart the Email Engine. The email daemon will notice the change, but not immediately. The email daemon usually checks for configuration changes every 30 minutes (the default setting). To shorten this time, add or modify the following line in the EmailDaemon.properties file:
com.bmc.arsys.emaildaemon.ARSystemServerName.Interval= configChangeCheckInterval
Where configChangeCheckInterval represents an integer value and the parameter is measured in minutes.
NOTE
By shortening the time, the email daemon will make more frequent calls to the AR System server. If you are not making many changes to the configuration, you should wait the default 30 minutes, or manually restart the entire Email Engine system after making the configuration changes. The same process applies when you make changes to an existing user, if you change the Internet email address on the form. The email daemon notices this change based on the predefined interval.
Submitting requests across different time zones

A user who submits an email request or query using a date/time field from a computer that is located in a different time zone than the computer where the Email Engine is installed, might experience the following problems: The query result might not be the same as a BMC Remedy User query result. The query result might not be correct. A request might be registered with an unexpected date or time. These problems occur because the time zone is not adjusted between the Email Engine and the email client computer. To avoid these problems, users should submit requests and queries to an Email Engine computer located in the same time zone. For more information, see Displaying date/time or numeric values in email notifications on page 70.
208
Verifying permissions for the Windows accounts

If the Email Engine will not run as a Windows service, verify that it can be run manually using the following procedure.
NOTE
If you are using MAPI, log in to the server as the Windows account used to start the Email Engine service.
To verify permissions for Windows accounts

1 Open a command prompt. 2 Change directories to the AR System email installation directory. 3 At the prompt, run EmailStart.bat. 4 If the mail process does not run, verify that the Email Engine user account has the
advanced user rights and necessary permissions as described in the Installation Guide, BMC Remedy Email Engine worksheet, page 102.
5 If you are not using MAPI, verify that the Email Engine user account has the
appropriate file system permissions on the AR System directory.
NOTE
If you are using an Microsoft Exchange server with SMTP and either POP3 or IMAP4, verify that your Exchange server has the SMTP gateway enabled as well as either POP3 or IMAP4 functionality.
Troubleshooting email request processing and notify filters

The Email Engine can experience problems if email submissions are not formatted correctly. If an incorrect email address is specified on an outgoing email notification, or an out-of-office reply is received, items that are not valid email submissions will reside in the AR System mail server mailbox. To avoid such problems, create a rule in your email program that checks the body of the message for text you require users to include in submissions, such as query or submit. If the message does not contain this text, set the rule to forward the email to the AR System administrator and delete it. This rule performs these functions: It prevents problems with the Email Engine due to improper request formatting. It prevents undeliverable messages from firing duplicate notify filters. If a message triggers a notify filter and is returned as undeliverable, it is returned to the mail queue, where it causes the filter to fire again. It alerts the administrator to the types of messages being submitted incorrectly, so the administrator can instruct users as to the correct procedures for formatting and submitting messages.
209
Fixing issues with notifications that fail

When you send an email from the Email Engine to another domain, this is called relaying. If relaying is turned off or disabled, then external emails will fail. This is a security feature to keep your server from sending thousands of unsolicited messages (or spam) in your company's name. To make sure that the Email Engine can send external emails, turn relaying on in your mail server. For example, in Microsoft Exchange, open the Relay Restrictions dialog box, add the AR System server, and select the check box Allow all computers which successfully authenticate to relay. To learn how to turn on relaying, see your mail server documentation.
Temporary directories and files

The Email Engine uses temp directories to store intermediate files for email messages, attachments, templates. Under normal conditions, the Email Engine cleans up these temporary files. However, if the Email Engine terminates abnormally for some reason, you should remove these files manually. Some patterns of the temporary file names that the Email Engine creates are:
AT*.tmp Email*.eml Email*.txt chk*.tmp Email*.html RED*.tmp E*.tmp Email*.rtf
Using the system temp directory

By default, the Email Engine uses the system temp directory to manage the temporary files. You can locate this directory as follows: On Windows, check the Windows default temp directory. On UNIX, check the /var/tmp or /tmp directories. Alternatively, use the TEMP, TMP, or TEMPDIR environment variables to identify the system temp directory on any operation system.
210
Temporary directories and files
Using an alternate temp directory

You can make the Email Engine point to an alternate temp directory, if the system temp directory does not have enough space.
To use an alternate temp directory

On Windows, add -Djava.io.tmpdir to the EmailStart.bat file as follows:
"%JavaPath%\java" Djava.io.tmpdir=directoryPath -cp emaildaemon.jar;arapi%LIBVER%.jar;arutil%LIBVER%.jar;activation. jar;mail.jar;imap.jar;smtp.jar;pop3.jar;armapi%LIBVER%.jar com.bmc.arsys.emaildaemon.EmailDaemon
For Unix add Djava.io.tmpdir to the emaild.sh file as follows:

exec ${JAVA_BIN}/java -Djava.io.tmpdir=directoryPath -Djava.library.path=${InstallPath} -cp ${CP_PATH} \com.bmc.arsys.emaildaemon.EmailDaemon -d ${InstallPath} >${LogFile} 2>&1 directoryPath is the fully qualified path where the temporary files are created.
TIP
BMC recommends that you monitor these directories for files that are no longer needed, which the Email Engine does not clean up.
211
212
Appendix
Setting up UNIX mailboxes
You can use the following procedure to establish a mailbox address for Email Engine on the UNIX operating system. These are meant only as generic guidelines. If you have questions about implementation, you should consult your UNIX system administrator for details. To set up the AR System mailbox, you must have UNIX superuser (root user) access on the UNIX server.
To set up UNIX mailboxes

1 Set up an ARSystem user account in the /etc/passwd file, as in the following
example (new entry in bold):

root:x:0:1:0000-Admin(0000):/:/sbin/sh daemon:x:1:1:0000-Admin(0000):/: bin:x:2:2:0000-Admin(0000):/usr/bin: sys:x:3:3:0000-Admin(0000):/: adm:x:4:4:0000-Admin(0000):/var/adm: lp:x:71:8:0000-lp(0000):/usr/spool/lp: smtp:x:0:0:mail daemon user:/: uucp:x:5:5:0000-uucp(0000):/usr/lib/uucp: listen:x:37:4:Network Admin:/usr/net/nls: nobody:x:60001:60001:uid no body:/: noaccess:x:60002:60002:uid no access:/: ARSystem:x:50:10:AR System mail user:/home/ARSystem:/bin/sh 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/.
Appendix A Setting up UNIX mailboxes 213
NOTE
On some UNIX platforms, you need to run the newaliases command to have the ARSystem aliases recognized. If you have questions or problems, see your UNIX system administration documentation or UNIX system administrator. 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 (HP-UX), by performing the following command: # touch /usr/spool/mail/ARSystem 4 Change the group name to daemon, or to the owner of the mailbox alias name, as
in the following example:

# chgrp daemon /usr/spool/mail/ARSystem
NOTE
The group name varies between UNIX platforms. For most UNIX platforms, it is the group daemon, while on HP-UX, it is mail. To verify the proper group name to use, check the group name for the mail directory by using the command ls -ldg.
5 Change the mailbox permissions so they are readable and writable by all, as in the
following example:
# chmod 666 /usr/spool/mail/ARSystem ls -laF /usr/spool/mail/ARSystem -rw-rw-rw-- 1 daemon 0 May 30 16:55 /usr/spool/mail/ARSystem
214
Appendix
Email engine upgrade parameters

This appendix describes the AR System configuration parameters used in the Email Engine 5.1 or earlier and their equivalents (if available) in Email Engine 7.0.00 or later.
Table B-1: Upgrade parameters for the Email Engine (Sheet 1 of 6) 5.1 (or earlier) email options Address (UNIX operating system only) Function The address the mail process watches for AR System messages. 6.0 (or later) 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 Sending incoming email with user instructions on page 167.
Note: The value that is set in the user
Default-Password
The AR System password to use if no password is specified in the submitted message.
instruction template will not be overwritten by the incoming email. Default-Schema The form to use if no form is specified in This is defined in the Default Workflow the submitted message. Form field in the incoming mailbox Advanced Configuration tab. The AR System server to use if no server The AR System server that the Email is specified in the submitted message. Engine connects to that is defined in the EmailDaemon.properties file.
Default-Server
Appendix B
215
Table B-1: Upgrade parameters for the Email Engine (Sheet 2 of 6) 5.1 (or earlier) email options Default-User Function 6.0 (or later) Email Engine equivalent
The AR System login to use if there is no Must be specified by using a user login specified in the submitted message. instruction template. For more information, see Sending incoming email with user instructions on page 167.
Note: The value that is set in the user
instruction template will not be overwritten by the incoming email. Include-OriginalOn-Failure Include-OriginalOn-Success A flag indicating whether to include the Not used. full text of the original message in a reply to a failed submission. A flag indicating whether to include the Not used. full text of the original message in a reply to a successful submission. Valid values are T and F. Not used. Indicates the full path name for the mailntfy 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 Microsoft Exchange clients operation. The Microsoft Exchange mailbox name referenced in your Exchange clients profile configuration (found in the Microsoft 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. Defines the maximum number of matches 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. This parameter is set in the AR System Email Mailbox Configuration form in the Basic Configuration tab for MAPI Email Server Type only. 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. Not used.
MailNotifyDir (Windows only)
Exchange-Profile (Windows only)
Exchange-Mailbox (Windows only)
Poll-Interval
Query-Match-Full
216
Table B-1: Upgrade parameters for the Email Engine (Sheet 3 of 6) 5.1 (or earlier) email options Query-Match-Short Function 6.0 (or later) Email Engine equivalent
Not used. Defines the maximum number of matches 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 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). Set Reply-Failure to Discard if / dev/null does not work for your system. For Windows, set the address to Discard. Not used.
Reply-Failure
Reply-Success
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.
Not used.
Appendix B
217
Table B-1: Upgrade parameters for the Email Engine (Sheet 4 of 6) 5.1 (or earlier) email options Required-Schema Function 6.0 (or later) Email Engine equivalent
The only form for which submissions are If the Force Default Workflow form is set accepted. If there is a Schema line in the to Yes, then the Default Workflow form submitted message, it must contain this will be the required schema. form name, or the submission is rejected. If there is no Schema line, the DefaultSchema setting in the configuration file must match this form name, or the submission is rejected. A flag indicating whether to save email See Saving outgoing notifications in items that AR System sends. Valid values MAPI on page 44 and Performance and for this option are T and F. The default configuration settings on page 182. value is F (do not save sent items). The only server for which email message This can be enforced by setting the requests can be submitted. Messages are application password or by 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. See the Installation Guide, Upgrade of the Email Engine, page 73. The name of the domain in which the Exchange account resides. Do not modify this parameter. Windows only: Used during installation. The name of the Exchange mail server account. Do not modify this parameter. Windows only: Used during installation. The encrypted password for the Exchange account. Do not modify this parameter. The sender name to use for filtergenerated email notifications where no subject is specified. Only trusted email users can use this name. This field is limited to 29 characters. See the Installation Guide, Upgrade of the Email Engine, page 73. See the Installation Guide, Upgrade of the Email Engine, page 73.
SaveSentItem
Required-Server
ExchangeNTDomain
ExchangeNTAccount
ExchangeNTPasswor d
Email-Notify-From
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.
LogoffSleep Max-Notify-MailLine-Len UseDateCheckOnFro m 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).
Not used.
218
Table B-1: Upgrade parameters for the Email Engine (Sheet 5 of 6) 5.1 (or earlier) email options Environment ARDATE Function 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. ARDATEONLY 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. For information about defining an RPC socket in a template, see Using label/ value pairs in templates on page 146. Not used. 6.0 (or later) Email Engine equivalent Not used.
Appendix B
219
Table B-1: Upgrade parameters for the Email Engine (Sheet 6 of 6) 5.1 (or earlier) email options ARTIMEONLY Function The time format used by the program. UNIX only: This value consists of a string of operators as defined by the strftime library call. (Some combinations are displayed successfully but cannot be translated for input.) If you do not set this variable, the system uses the date format for the language specified by the LANG environment variable. Windows only: This value consists of a string of operators as defined by Regional Settings. If you do not set this variable, the system uses the date format specified in the Regional Settings of the user account that runs the service. MAIL UNIX only: The directory where email files are stored. The default is /usr/ mail (for the HP-UX and Oracle Solaris operating systems) or /var/spool/ mail (for the IBM AIX operating system). This is set using the inbox path. If the inbox path is not set, then the mail environment variable is used. 6.0 (or later) Email Engine equivalent Not used.
220
Appendix
Examples of email templates
The examples in this appendix demonstrate how you can use templates to execute a specific set of instructions on a 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 5, Using email templates. The following topics are provided: Creating email templates to search for Request ID (page 222) Creating email templates to search for fields (page 223) Creating email templates to perform searches using qualifications (page 224) Creating email templates that include attachments (page 225) Creating an email content template with Submit and Query actions (page 226) Creating an email reply using result templates in HTML format (page 227) Sample HTML result template (page 229) Email status template in HTML format (page 231) Adding a header template and a footer template (page 232)
Appendix C
221
Creating email templates to search for Request ID

You must use the Query Action label (or its alias) to perform a search action. The following examples use templates that have been exported using BMC Remedy Developer Studio and show how to modify them. You can, however, create the template using a text editor.
To create an email template to search for a request ID

1 Export the email template for the form that you want to make available for
searching. A sample of an exported mail template appears as follows:

# File exported Tue May 21 21:38:47 2004 Schema: vacation Server: polycarp Login: Password: Action: Submit Values: Submit, Query Format: Short Values: Short, Full Submitter !2!: Short-Description !8!: 2 Edit the exported file. a Change the Action:Submit to Action:Query. b In the fields section of the email template, define only the Request ID. It must
have a field ID value of 1.

c Enter the Request ID of the entry to be retrieved. d Remove all other fields from the mail template. (The only field in the body should be !1! requestIDNumber.)
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
222
Creating email templates to search for fields
Creating email templates to search for fields

To create an email template to search for a field
searching. An example of a mail template for a form follows.

# File exported Tue May 21 21:38:47 2004 Schema: AR-HD Calls Server: polycarp Login: Password: Action: Submit #Values Submit, Query Format: Short #Values Short, Full Source !5368737933!: Phone #Values: Phone, AR System, email, NMP, ACD Caller Impact !5368783455!: Low Values: High, Medium, Low Last Name !5386753452!: Phone Number !5386748345!: 2 Edit the exported file. a Change the Action:Submit to Action:Query. b To use a format other than the default (Short), set the Format option. 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
Appendix C
223
Creating email templates to perform searches using qualifications

To create an email template to search using a qualification
searching. The following example shows a mail template for a form:

# File exported Tue May 21 21:38:47 2004 Schema: AR-HD Calls Server: polycarp Login: Password: Action: Submit Values: Submit, Query Format: Short Values: Short, Full Source !5368739331!: Phone Values: Phone, AR System, email Caller Impact !5368783455!: Low Values: High, Medium, Low Last Name !5386753452!: Phone Number !5386748345!: 2 Edit the exported file. a Change the Action:Submit to Action:Query. b Remove all fields in the message and include a Qualification label.
The following example shows an exported file that was modified to search using the Qualification label.
Schema: AR-HD Calls Server: polycarp Login: Password: Action: Query Format: Short Qualification: 'Source' = "Phone" OR 'Source' = "email"
224
Creating email templates that include attachments
Creating email templates that include attachments

This section contains a sample email template that includes an attachment field.
To create an email template that includes attachments

submitting. Make sure that the form contains an attachment pool and a valid attachment field.
2 Edit the template to include the label and value for an attachment field (for example, Attach!536880912!:), as shown here: # File exported Fri Mar 07 10:30:40 2004 Schema: Email Submit Server: polycarp Login: Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full Submitter ! 2!: Short Description ! 8!: Attach!536880912!: <====== (Manually add this line based upon the attachment field name and database ID)
NOTE
Make sure that you use the ID of the attachment field, not the attachment pool.
3 In a third-party client tool such as Microsoft 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. A user email template filled out with a

Schema: Email Submit Server: polycapr Login: Demo Password: Action: Submit # Values: Submit, Query Format: Short # Values: Short, Full
filter.log
file attached appears as follows:
Appendix C
225
Submitter ! 2!: Demo Short Description ! 8!: Submitting email with attachment file. Attach!536880912!: filter.log 7 Insert your filter.log attachment file anywhere in the email. If the attachment
name including the extension is not supplied in the email template, the email submission will fail.
8 Send the email to the incoming mailbox.
Creating an email content template with Submit and Query actions

The following example submits an entry into a form, then queries that same form. When creating or modifying templates, any values that are defined before the Action label are global and apply to all the actions specified. Any value declared after the Action statement takes precedence over the global definition for that action only. In the following example, the Schema and Server label/value pairs are global, and therefore apply to both the Submit and Query actions.
Schema: HD Incident Server: polycarp Login: Demo Password: Action: Submit # Values: Submit, Query Format: Full # Values: Short, Full Submitter ! 2!: $USER$ Short Description ! 8!: Need to create new post office box. !Last Name!: Stampovich !First Name!: Ivan !Email!: stampovic@bmc.com !Location!: Sunnyvale !Phone!: 222-3333 !Status!: Assigned !Impact!: Medium !Item!: Email !Category!: Applications !Type!: Office !Problem Summary!: Need to create new post office box. !536870920!: boot.ini Action: Query Qualification: 1=1
226
Creating an email reply using result templates in HTML format
If you did not specify a template for the email reply, the Email Engine would reply with the results shown in Figure C-1:
Figure C-1: Reply to an action template using the default format
The Query action returns the Submit entry to the user, along with any other entries that meet the qualification. Because no template was defined as a Results Template, the Email Engine uses the default internal text format.
Creating an email reply using result templates in HTML format

For the Email Engine to include a Result Template in the reply email, enter the Result Template label/value pair as a global declaration in the body of your email, as in the following extract:
Schema: HD Incident Server: polycarp Result: HDIN Content Login: Demo Password: ....
Appendix C
227
When the Email Engine sends the reply email, it will use the result template shown in Figure C-2.
Figure C-2: Reply to an action email using a result template
For a detailed example, see Using HTML result templates with outgoing email on page 93. 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 161. 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 162. 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 156. When you send your email, the 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 151.
228
Sample HTML result template
Sample HTML result template

If you create your result templates with HTML, you can professionally format the reply results that users see.
Figure C-3: An HTML result template
The following HTML code was used to create the result template shown in Figure C-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=iso8859-1"> <META content="MSHTML 6.00.2800.1126" name=GENERATOR></HEAD> <BODY> <TABLE cellSpacing=0 cellPadding=0 width=772 border=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> Appendix C Examples of email templates 229
<TD width="14%"> </TD> <TD width="37%"> </TD></TR> <TR borderColor=#cccccc> <TD colSpan=5><B><FONT color=#008000 size=3><U>Requester Information_______________________________________________________ _____________________</U></FONT></B></TD></TR> <TR borderColor=#cccccc> <TD width="11%" height=56> <DIV align=center><IMG height=40 src="people.gif" width=38></DIV></TD> <TD width="17%" height=56><B><FONT size=3>Last Name</ FONT></B></TD> <TD width="21%" height=56><FONT size=3>#$$Last Name$$#</ FONT></TD> <TD width="14%" height=56><B><FONT size=3>Email</FONT></ B></TD> <TD width="37%" height=56><FONT size=3>#$$Email Address$$#</FONT></TD></TR> <TR borderColor=#cccccc> <TD colSpan=5><FONT size=3><B><FONT color=#008000><U>Incident Information_______________________________________________________ _______________________</U></FONT></B></FONT></TD></TR> <TR borderColor=#333333> <TD borderColor=#cccccc width="11%" rowSpan=3> <DIV align=center><FONT size=3></FONT><FONT size=3><B><IMG height=43 src="tools.gif" width=46></B></FONT></DIV></TD> <TD borderColor=#cccccc width="17%"><B><FONT size=3>Impact</FONT></B></TD> <TD borderColor=#cccccc width="21%"><FONT size=3>#$$Impact$$#</FONT></TD> <TD borderColor=#cccccc width="14%"><B><FONT size=3>Status</FONT></B></TD> <TD borderColor=#cccccc width="37%"><FONT size=3>#$$Status$$#</FONT></TD></TR> <TR> <TD width="17%"><B><FONT size=3>Category</FONT></B></TD> <TD width="21%"><FONT size=3>#$$Category$$#</FONT></TD> <TD width="14%"><B><FONT size=3>Type</FONT></B></TD> <TD width="37%"><FONT size=3>#$$Type$$#</FONT></TD></TR> <TR> <TD width="17%"><B><FONT size=3>Item</FONT></B></TD> <TD width="21%"><FONT size=3>#$$Item$$#</FONT></TD> <TD width="14%"><B><FONT size=3>Assigned To</FONT></B></ TD> <TD width="37%"><FONT size=3>#$$Assigned To$$#</FONT></ TD></TR> <TR> <TD borderColor=#cccccc colSpan=5> <HR>
230
Email status template in HTML format
<FONT size=3></FONT></TD></TR></TBODY></TABLE></TD></ TR></TBODY></TABLE><B><FONT color=#008000 size=3></FONT></B></BODY></HTML>
Email status template in HTML format

For the Email Engine to include a Status Template in the reply email (for example, to format the reply if there is an error) enter the Status Template label/value pair as a global declaration in the body of your email, as in the following extract:
Schema: HD Incident Server: polycarp Status Template: Status Default Login: Demo Password: ....
Similarly, the Status Template must be stored in the AR System Email Template form. For more information about status templates, see Status Template label on page 151. When you send your email, the 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 C-4. The Email Engine substitutes values for the variables.
Figure C-4: A reply with the status template
Appendix C
231
Adding a header template and a footer template

To cause the Email Engine to include a Header Template (or Footer Template) in the reply email, enter the Header Template label/value pair as a global declaration in the body of your email, as in the following extract:
Schema: HD Incident Server: polycarp Result Template: Result Template Header Template: Default Header Footer Template: Default Footer ... Figure C-5: A reply with the 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. Use the template fields on the AR System Email Messages form to determine the templates used when creating an outgoing message. The label/value pair method is used when requesting results from a server by email. 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 161. If graphics are included, and these are not contained in the HTML file, you must also add the graphics using the Template Attachments tab of the AR System Email Templates form. For more information, see Adding attachments to HTML templates on page 162. For more information, see Header Template and Footer Template labels on page 152.
232
Appendix
Email Engine forms
The Email Engine provides a set of administration, user, and workflow forms for configuring and processing email from your mail server. These forms are generated when you install the Email Engine.
NOTE
If any of the email forms are deleted after you install the Email Engine, you must import those forms manually. They are not imported when you restart the AR System server.
WARNING
BMC recommends that you do not archive or audit the forms containing core fields. The following topics are provided: Email Engine administration forms (page 234) Email Engine user forms (page 242) Email Engine workflow forms (page 250)
Appendix D
Email Engine forms
233
Email Engine administration forms

This section describes the following administration forms that are available with the Email Engine: AR System Email Failover Mail Server Configuration AR System Email Mailbox Configuration AR System Email Templates AR System Email User Instruction Templates AR System Email Error Logs AR System Email Security
AR System Email Failover Mail Server Configuration form

Each mail server can have only one failover server. However, you can also specify a failover server for each failover server. For more information, see Multiple mail server support on page 24.
Table D-1: AR System Email Failover Mail Server Configuration form Field Mail Server Name/IP Failover Mail Server Name/IP Description The name or IP address of the mail server that the Email Engine can use to send or receive emails. The name or IP address of the mail server that acts as a failover system for the other mail server mentioned on this form.
IMPORTANT
The Email Engine does not resolve the mail server if either Mail Server Name/IP or Failover Mail Server Name/IP contains a new line character. You should use either the server name or the IP address in both fields. If you use the server name in one field and the IP address in the other, an error message is displayed and you are not allowed to save the form. You should use similar naming conventions for both the AR System Email Configuration form and the AR System Email Failover Mail Server form. You should not provide the IP address in one form and the server name in the other. If you use different naming conventions in these forms, no error is displayed, but the failover mail server is not used successfully if the primary mail server stops working. When you search for failover mail servers using the AR System Email Failover Mail Server Configuration form, the results are displayed as shown in Figure D-1 on page 235.
234
Figure D-1: AR System Email Failover Mail Server Configuration search results
AR System Email Mailbox Configuration form

Use the AR System Email Mailbox Configuration form to create mailboxes and specify their use. For each mailbox, the form provides a name and email address for the mailbox administrator, actions associated with the mailbox, connection and security provisions, and defaults. For more information, see Configuring outgoing mailboxes on page 28 and Configuring incoming mailboxes on page 32.
Incoming mailboxBasic and Advanced Configuration tabs

Table D-2: AR System Email Mailbox ConfigurationBasic and Advanced (Sheet 1 of 3) Field name Mailbox Name Status Description Enter the name of the incoming mailbox. Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled.
Mailbox Function Select whether mailbox is Incoming or Outgoing.
Appendix D
Email Engine forms
235
Table D-2: AR System Email Mailbox ConfigurationBasic and Advanced (Sheet 2 of 3) Field name Description
Email Server Type Select the email protocol. Incoming mailboxes include following protocols: For 32-bit JVM: POP3 IMAP4 MBOX MAPI For 64-bit JVM: POP3 IMAP4 MBOX Polling Interval (Minutes) Email Server Requires SSL Inbox Path Email Server Name/IP 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. Enter the name or IP address of the mail server used in your organization. Used only with POP3 and IMAP4.
Email Server Port Enter the port used for connecting to the mail server. The default port number is determined by the protocol selected and whether Secure Sockets Layer (SSL) is selected. Used only with POP3 and IMAP4. If you do not enter a port number, the following default values will be used: POP3: 110 POP3 with SSL: 995 IMAP4: 143 IMAP4 with SSL: 993 Email Server User Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4. Email Server Password Profile Name Associated Mailbox Name Email Action Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4. Enter the name of the Microsoft Exchange profile to be used for incoming mailbox. Used only with MAPI. Enter the name of an outgoing mailbox used to reply to incoming emails that require a response. 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 (BMC Remedy Mail Server release 5.1 or earlier) and thus ignore special HTML fields and XML formats.
Use Original Template Format
236
Table D-2: AR System Email Mailbox ConfigurationBasic and Advanced (Sheet 3 of 3) Field name Description
Reply With Result Select Yes to enable the results of an Action to be included with an email reply, or select No if results should not be included. Reply With Entry Select Yes to return the complete entry of a submit or modify action. Select No to use the default single-line entry. Enable Modify Actions Select Yes to enable modify actions, or No to prevent modify actions from being performed.
Default Workflow Enter the name of the form upon which the Email Engine will execute Form instructions found within the incoming email message if no specific form is specified in the email message. Force Default Workflow Form Use Security Key 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.
Use Supplied User Select Yes to use AR System server login information that might be Information included within the incoming email message. Use Email From Address Select Yes to use the email address of the sender as a form of authentication.
Note: If the database is case sensitive, make sure that the character
case of the email address from the user form and email address of the sender is the same.
Outgoing mailboxBasic and Advanced Configuration tabs

Table D-3: Basic and advanced configuration for outgoing mailboxes (Sheet 1 of 3) Field name Mailbox Name Status Description Enter the name of the outgoing mailbox. Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled.
Mailbox Function Select whether mailbox is Incoming or Outgoing.
Basic Configuration tab Email Server Type Select the email protocol. Outgoing mailboxes include the following protocols: For 32-bit JVM: SMTP MAPI For 64-bit JVM: SMTP Polling Interval (Minutes) Enter the number of minutes after which the Email Engine will check for new outgoing mail waiting to be sent from this mailbox.
Appendix D
Email Engine forms
237
Table D-3: Basic and advanced configuration for outgoing mailboxes (Sheet 2 of 3) Field name Email Server Requires SSL Email Server Name/IP Description Enables the secure socket layer. Used only with SMTP. Enter the name or IP address of the mail server used in your organization. Used only with SMTP.
Email Server Port Enter the port used for connecting to the mail server. The default port number is determined by the protocol selected and whether Secure Sockets Layer (SSL) is selected. Used only with SMTP. If you do not enter a port number, the following default values will be used: SMTP: 25 SMTP with SSL: 465 Email Server User Enter the user name of the administrator or user for this email account. Used only with SMTP. Email Server Password Profile Name Associated Mailbox Name Enter the user name of the administrator or user for this email account. Used only with SMTP. Enter the name of the Microsoft Exchange profile to be used for the outgoing mailbox. Used only with MAPI. Enter the name of the incoming mailbox that will be used to receive instructions or notifications.
Advanced Configuration tab
Default Outgoing Select Yes so that all outgoing messages for which an outgoing Mailbox mailbox is not specified will be sent using information in this entry. Display Name Email Address 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.
Reply To Address Enter the Reply-to email address for the mailbox owner or administrator, if you plan to enable users to reply to notification messages sent from this mailbox. Organization Delete Outgoing Notification Messages Default Addressing Default To Default CC Default BCC For email clients that display an organization name, enter the name of the mailbox owner, or administrators organization. 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.
238
Table D-3: Basic and advanced configuration for outgoing mailboxes (Sheet 3 of 3) Field name Description
Default Templates If a user creates a message without specifying a template in the Templates tab for either Notify filter or escalation actions, then this template will be used by default. Header Template Footer Template Status Template Result Template 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.
AR System Email Templates form

Use the AR System Email Templates form to create, display, and modify templates applied to email messages. You can use this form to create standard templates that users can access for creating specific types of messages. For each template, this form provides: the unique template ID; the format used and a name and description for the template; the language encoding used; and information about attachments associated with this template. To include graphic elements in your email, you can add these as attachments to the template in the AR System Email Templates form. You must store templates in the AR System Email Templates form before you can use them. For more information, see Storing templates in the AR System Email Templates form on page 161.
Table D-4: Fields on the AR System Email Templates form (Sheet 1 of 2) 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 (Optional) Select the template files from the Attachment field. Includes size and label information.
Template Name
Add Attachment button Click to open the AR System Email Attachments form in New (HTML templates only) mode. Lets you select and add an attachment (for example, HTML file or bitmap) that is always used with a specific template.
Appendix D
Email Engine forms
239
Table D-4: Fields on the AR System Email Templates form (Sheet 2 of 2) Field name Modify Attachment button Delete Attachment button (HTML templates only) Refresh Table button Add Existing menu (HTML templates only) Click to refresh the table after you have added, modified, or (HTML templates only) deleted an attachment. Adds an existing attachment to the template. Description
Click to open the AR System Email Attachments form in Search mode so you can modify an attachment. The template will not (HTML templates only) be available for use until the Email Engine cache is updated. Click to delete the attachment from AR System Email Attachments form.
AR System Email User Instruction Templates form

Use the AR System Email User Instruction Templates form to store administratordefined instructions for specific actions, and to associate those instructions with a template defined in the AR System Email Templates form. These instructions can include variables whose values are provided when the instructions are executed. For each instruction template, the form provides the template name, name of the mailbox with which the instructions are associated, and the instructions themselves. For more information, see Sending incoming email with user instructions on page 167.
Table D-5: Fields on the AR System Email User Instruction Templates form Field name Instruction Template ID Description System-generated unique ID. The contents of this field are read-only.
Template Name Menu lets you select template that is executed as the content of user instruction and used in the email. Mailbox Name Instruction Menu lets you associate incoming mailbox used with user instruction. Valid character string consisting of Action label and value used to access user instruction field.
AR System Email Error Logs form

Use the AR System Email Error Logs form to store logs of errors that have occurred during email transmissions, as well as all incoming and outgoing mail messages, log connection status information for email servers and the AR System server, start and stop times for the Email Engine, and configuration changes. Each log entry includes the ID for the mailbox and the message, the message type, message number, how the error message was generated, and the text of the error message.
240
For more information, see Error and system status logs on page 174.
Table D-6: Fields on the AR System Email Error Logs form Field name Description
Log Message ID Message ID and date on which error was created. and 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 28 and Configuring incoming mailboxes on page 32. 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.
AR System Email Security form

Use the AR System Email Security form to either create and enable or disable security keys for incoming mail. A security key can be assigned to an individual incoming mailbox, or to all incoming mailboxes. For more information, see Configuring incoming mailbox security on page 39.
Table D-7: Fields on the AR System Email Security form (Sheet 1 of 2) Field name Security ID Status Key User Name Description System-generated unique ID. The contents of this field are read-only. Menu that lets you activate the key. Select Disabled to keep the key disabled. Name of key consisting of a set of alphanumeric characters. You can use almost any combination of letters and numbers for a security key. Name of a valid AR System user to whom the security key should apply.
Force for Mailbox Enables the security key for this mailbox only. Select No to enable the key for all mailboxes in your email environment.
Appendix D
Email Engine forms
241
Table D-7: Fields on the AR System Email Security form (Sheet 2 of 2) Field name Mailbox Name Force from Email Addresses Email Addresses Expiration Date Description Name of the Incoming Mailbox to which you want this security key applied. Key required for mail received from specific email accounts. If you select Yes, the Email Address field becomes enabled. Option that verifies incoming messages from a set of specific email accounts using a security key. Expiration date for this security key. After the key expires, you can either modify the expiration date in this form, or set the Expires field to No. Description for the key, such as why it was created or instructions for modifying or deleting it.
Description
Email Engine user forms

This section describes the user forms available with the Email Engine: AR System Email Messages AR System Email Error Messages AR System Email Attachments AR System Email Attachment Join
AR System Email Messages form

Use the AR System Email Messages form to store information for outgoing and incoming email messages. Each message is stored as an entry in the AR System Email Messages form. For each message, this form provides the name of the mailbox from which the message was generated, the message type, name and organization of the mailbox owner; names of recipients sent to and copied; the text of the message (in HTML, plain text format, or a combination of both); and (under a separate tab) a list of any attachments included with the message. For information about using the Email Messages form to troubleshoot traffic between incoming and outgoing email, see Chapter 3, Outgoing email.
Table D-8: Fields on the AR System Email Messages form Field name Mailbox Name Mailbox Type Display Advanced Options Description Name of configured mailbox. Select whether mailbox is Incoming or Outgoing. Select Yes to display the advanced options available for viewing email information and errors.
242
Message tab
Table D-9: Fields on the AR System Email Messages formMessages 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. 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 Microsoft Outlook priority. Numbers from 1 to 100 are acceptable.
Organization: To: CC: BCC: Subject: Priority:
Attachments tab
Table D-10: Fields on the AR System Email Messages formAttachments tab Field name Add Attachment Modify Attachment Delete Attachment Refresh Table Add Existing Description Includes attachment with outgoing email. Lets you modify attachment or attachment name. Removes attachment from outgoing email. Refreshes table after you have added, modified, or deleted an attachment. Includes previously saved attachment with outgoing email.

Table D-11: Fields on the AR System Email Messages formAdvanced Options tab (Sheet 1 of 2) Field name Templates tab Header Template Footer Template Field Values Template to be used as the header template. Template to be used as the footer template. Value for a variable in the template. Content Template Template to be used as the content template. Variable Replacement tab Description
Appendix D
Email Engine forms
243
Table D-11: Fields on the AR System Email Messages formAdvanced Options tab (Sheet 2 of 2) Field name Description
AR System Server With qualification variables, name of the server on which the form resides. AR System Server With qualification variables, any access information necessary. TCP Port AR System Server With qualification variables, any access information necessary. RPC Number AR System Form Qualification 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 Alternatives tab Attachment Attachment pool enables you to add the content of your email as a Alternatives plain text, HTML, or RTF attachment, instead of typing it into the (attachment pool) Body field in the Message tab. Plain Text Content Language encoding used. Attachment Encoding HTML Content Attachment Encoding RTF Content Attachment Encoding Values Attachment Encoding Language encoding used.
Language encoding used.

Table D-12: Fields on the AR System Email Messages formMessage Information tab (Sheet 1 of 2) Field name Message ID Date Received Date Sent Execute/Send At Description The unique value that identifies the message. The date on which the message was sent; this value is retrieved from the Date header of the incoming message. The date on which the message was sent; applicable to outgoing messages only. The timestamp of when the incoming message was executed, or when the outgoing message was sent.
244
Table D-12: Fields on the AR System Email Messages formMessage Information tab (Sheet 2 of 2) Field name Parse Message Description The parsing status of the message; applicable to incoming messages only. The options and their meanings are: NoThe message has not yet been parsed. YesThe message is still in the incoming queue. ErrorAn error occurred when parsing the message. Parsed & ExecutedThe message was successfully parsed and executed. Send Message The sending status of the message; applicable to outgoing messages only. The options and their meanings are: NoThe message has not yet been sent. YesThe message is still in the outgoing queue. ErrorAn error occurred when sending the message. SentThe message was successfully sent. Error Sending-RetryingThe Email Engine is trying to send the message again, because an error occurred at the previous attempt.
Errors tab
Enables users to view error messages if their email is not sent correctly. Table D-13: Fields on the AR System Email Messages formErrors tab Field name Description
Log Message Type If a request fails to submit, the original message is returned as an attachment. Log Message Number Create Date The error message number. The creation date of the error message.
Log Message Text If a request fails to submit, the error message that indicates the reason for the failure is returned.
AR System Email Error Messages form

In the BMC Remedy AR System 7.6.02 release, a new AR System Email Error Messages form has been introduced. Any incoming email message that has not been processed correctly due to any runtime error, is stored in this form with the error details.
NOTE
This form stores information only for incoming email messages. After manually rectifying the errors, you can copy these incoming messages to the AR System Email Messages form.
Appendix D
Email Engine forms
245
NOTE
BMC recommends that you perform the rectification process individually on every error out email message. Do not perform the rectification process on more than one email message at the same time using the Modify All option.
WARNING
(For incoming mails that have not been processed correctly due to any runtime error) The Email Engine considers the HTML format, by default. If the incoming message is in a plain text format, Email Engine first checks for the HTML format and when not found, considers the plain text format. But, if the incoming mail is in a plain text as well as HTML format, the Email Engine only considers the HTML format. For the Email Engine to consider the plain text format, change the HTML format to a plain text format (without any spaces) or clear the HTML format.
To copy the rectified incoming messages to the AR System Email Messages form
1 From the Message Information tab, change the status of the message to Yes. 2 Click on the Copy to AR System Email Messages Form button.
After the rectified messages are copied to the AR System Email Messages form, the Email Engine processes the incoming actions at the next polling interval. However, if there are messages in the incoming queue, the rectified messages are parsed at the next polling interval. Increase the time of the polling interval, if you want to parse the rectified messages in spite of the messages in the incoming queue. The messages stored on the AR System Email Error Messages form, are not deleted even after they are moved to the AR System Email Messages form. The administrator can configure the period and the conditions for deleting these mails using the Clean AR System Email Error Messages escalation.
NOTE
This escalation is disabled by default.
To enable the Clean AR System Email Error Messages escalation

1 Go to Escalation -> Execution Options. 2 Change the value of the State field to Enabled using the drop-down menu. 3 (Optional) Change the Escalation period as per your requirements from the default
value of 15 days.
NOTE
Additional conditions can be set using the Run Process field. All the messages in the AR System Email Error Messages form will be deleted depending upon the conditions set in the escalation.
246
For each message, this form provides the name of the mailbox from which the message was generated, the message type, name and organization of the mailbox owner; names of recipients sent to and copied; the text of the message (in HTML, plain text format, or a combination of both); and (under a separate tab) a list of any attachments included with the message.
Table D-14: Fields on the AR System Email Error Messages form Field name Mailbox Name Mailbox Type Description Name of configured mailbox. Select whether mailbox is Incoming or Outgoing.
Message tab
Table D-15: Fields on the AR System Email Error Messages formMessages 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. 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 Microsoft Outlook priority. Numbers from 1 to 100 are acceptable.
Organization: To: CC: BCC: Subject: Priority:
Attachments tab
Table D-16: Fields on the AR System Email Error Messages formAttachments tab Field name Add Attachment Modify Attachment Delete Attachment Refresh Table Add Existing Description Includes attachment with outgoing email. Lets you modify attachment or attachment name. Removes attachment from outgoing email. Refreshes table after you have added, modified, or deleted an attachment. Includes previously saved attachment with outgoing email.
Appendix D
Email Engine forms
247

Table D-17: Fields on the AR System Email Error Messages formAdvanced Options tab Field name Templates tab Header Template Footer Template Field Values Template to be used as the header template. Template to be used as the footer template. Value for a variable in the template. Content Template Template to be used as the content template. Variable Replacement tab AR System Server With qualification variables, name of the server on which the form resides. AR System Server With qualification variables, any access information necessary. TCP Port AR System Server With qualification variables, any access information necessary. RPC Number AR System Form Qualification 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. Description
Attachment Alternatives tab Attachment Attachment pool enables you to add the content of your email as a Alternatives plain text, HTML, or RTF attachment, instead of typing it into the (attachment pool) Body field in the Message tab. Plain Text Content Language encoding used. Attachment Encoding HTML Content Attachment Encoding RTF Content Attachment Encoding Values Attachment Encoding Language encoding used.

Table D-18: Fields on the AR System Email Error Messages formMessage Information tab (Sheet 1 of 2) Field name Message ID Date Received Description The unique value that identifies the message. The date on which the message was sent; this value is retrieved from the Date header of the incoming message.
248
Table D-18: Fields on the AR System Email Error Messages formMessage Information tab (Sheet 2 of 2) Field name Date Sent Execute/Send At Parse Message Description The date on which the message was sent; applicable to outgoing messages only. The timestamp of when the incoming message was executed, or when the outgoing message was sent. The parsing status of the message; applicable to incoming messages only. The options and their meanings are: NoThe message has not yet been parsed. YesThe message is still in the incoming queue. ErrorAn error occurred when parsing the message. Parsed & ExecutedThe message was successfully parsed and executed.
Errors tab
Enables users to view error messages if their email is not sent correctly.
Table D-19: Fields on the AR System Email Error Messages formErrors tab Field name Description
Log Message Type If a request fails to submit, the original message is returned as an attachment. Log Message Number Create Date The error message number. The creation date of the error message.
Log Message Text If a request fails to submit, the error message that indicates the reason for the failure is returned.
AR System Email Attachments form

Use the AR System Email Attachments form to create, display, and modify information about attachments used with emails and templates, including incoming email. For each attachment, the form provides a unique ID, the type of attachment (for example, a text file), the name of the attachment, whether the attachment is an email attachment or a template attachment, the file name, size, and label.
Appendix D
Email Engine forms
249
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.
Table D-20: Fields on the AR System Email Attachments form 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 Name of attachment. File Name Enables users to view error messages if their email was not sent (attachment pool) correctly.
AR System Email Attachment Join form

The Email Engine uses the AR System Email Attachment Join form for mapping attachments to email messages.
WARNING
Because this information is used internally by the Email Engine, you should not create or modify entries in this form.
Email Engine workflow forms

This section describes the workflow forms available with the Email Engine. AR System Email Instructions AR System Email Instruction Parameters AR System Email Association
AR System Email Instructions form

The Email Engine uses the AR System Email Instructions form to store instructions obtained when incoming email is parsed.
WARNING
250
Email Engine workflow forms
AR System Email Instruction Parameters form

The Email Engine uses the AR System Email Instruction Parameters form to store parameters specified for administrator-defined instructions.
WARNING
Because the information in this form is used internally by the Email Engine to store instructions, you should not create or modify entries in this form.
AR System Email Association form

The Email Engine uses the AR System Email Association form to store associations between an email message and one or more attachments, or between a template and one or more attachments. For incoming messages, this information includes the association between the message and any attachments included with the message. For outgoing messages, this information includes associations for attachments that should be included when the message is sent. For each association, the form provides: Unique ID. Source type (email or template). If the source type is template, the form reflects the association between a template and any attachments that should be included when that template is used. An example is an HTML template with graphics that must be included to make sure that the message is displayed correctly. Source ID (the ID of the email or template). Destination type (email attachment). Destination ID (the ID of the attachment). This association enables multiple emails to be associated with one attachment, or one email to be associated with multiple attachments.
WARNING
Appendix D
Email Engine forms
251
252
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index
Symbols
!ID! label 147, 152 !Name! label 147, 152 AR System Email Instructions form 250 AR System Email Mailbox Configuration form 235 AR System Email Messages form 54, 74, 242 AR System Email Security form 241 AR System Email Templates form 161, 239 AR System Email User Instruction Templates form 240 AR System server identifying which one email engine uses 179 stopping and starting 207 troubleshooting 204 architecture, email engine 18, 20 Attachment Alternatives tab fields 244, 248 incoming mail 136 outgoing mail 86 attachments adding mail content as 86 adding to HTML templates 162 configuration form 249 creating templates that include 225 deleting in outgoing mail 81 deleting templates 165 exporting templates with 166 including in incoming mail 116 including in notifications 60 including in outgoing mail 79 including incoming in outgoing mail 102 mapping to email messages 250 modifying in outgoing mail 81 modifying template 165 Attachments tab 79, 243, 247 audience for this guide 11 Authentication label 146, 148
A
accounts email 17 permissions for Windows 209 Action label 146, 149 actions Modify 42, 149 Notify 56, 61, 128 Query 149, 226 Submit 113, 149, 226 administrator-defined instructions storing 240 storing parameters 251 Advanced Configuration tab incoming mailbox 33, 235 outgoing mailbox 30, 237 Advanced Options tab fields 243, 248 incoming mail 136 outgoing mail 82 API errors 176 appearance, improving outgoing mail about 89 example 22 Application Levels debug option 178 application service passwords identifying invalid 203 AR System Email Association form 251 AR System Email Attachment Join form 250 AR System Email Attachments form 249 AR System Email Error Logs form 240 AR System Email Error Messages form 245 AR System Email Failover Mail Server Configuration form 234 AR System Email Instruction Parameters form 251
B
banners, adding to outgoing mail 91 Basic tab incoming mailbox 235 outgoing mailbox 237
Index
253
batch files, creating email debug 192 BMC Remedy Email Engine. See email engine BMC Software, contacting 2 body, including incoming in outgoing mail 101 buttons HTML checkbox 155 HTML radio 155 options for email engine 177 declarations, global and local parameter 156 default outgoing mailbox 28 deleting attachments in outgoing mail 81 notifications 70 template attachments 165 documentation, AR System 11 dynamically assigning templates to outgoing mail 66
C
character sets incoming mail 138 outgoing mail 88 checkbox buttons, HTML 155 compatibility matrix 11 Configuration module 19 configurations advanced incoming mailbox 33 advanced outgoing mailbox 30 basic incoming mailbox 32 basic outgoing mailbox 29 changing mailbox 208 testing mailbox 36 troubleshooting mailbox 198 Console Handler Specific Properties debug option 178 content templates about 141 creating with Submit and Query actions 226 using HTML with outgoing mail 97 content, message adding as attachment 86 determining outgoing 88 Creator module 19 customer support 3
E
email accounts 17 Email Association form 251 Email Attachment Join form 250 Email Attachments form 249 email engine about 16 adjusting performance 182 AR System server and 179 architecture 18, 20 Configuration module 19 configuring for Modify actions 42 configuring SSL 45 configuring to reply with results 41 Creator module 19 debugging 177 Execution module 19 internal errors 176 Logging module 19 modifying configuration 182 Monitor module 19 Receiver module 19 Sender module 19 sending queries to 108 specifying heap size 201 terminology 17 upgrading 215 Email Error Logs form 240 Email Failover Mail Server Configuration form 234 Email Instruction Parameters form 251 Email Instructions form 250 Email Mailbox Configuration form 235 Email Messages form 242, 245 email messages. See messages Email Security form 241 Email Templates form 239 Email User Instruction Templates form 240 email. See mail EmailDaemon.properties file adjusting email engine performance 182 updating 180
D
date/time values displaying in notifications 70 formats supported in templates 159 debugging Application Levels option 178 Console Handler Specific Properties option 178 creating batch files for 192 email engine on UNIX 196 email engine on Windows 193 Global Logging Level option 177 Global Property Handlers option 177 Handler Specific Properties option 177, 178 Main Application Level option 178 Module Levels option 178 254 BMC Remedy Email Engine Guide
using 179 Enhanced UTF-8 support 26 entries retrieving from configuration form 44 searching for to modify 132 error logs 174 error messages viewing incoming mail 137 viewing outgoing mail 87 errors API 176 internal email engine 176 Errors tab fields 245, 249 incoming mail 137 outgoing mail 87 examples creating user instructions 167 creating workflow to modify requests 127 HTML result template 229 improving appearance of outgoing mail 22 incoming mail 106 modifying requests with workflow 126 outgoing mail 52 template variables 157 templates 221 using incoming mail to modify requests 117 using workflow to modify requests 126 Execution module 19 exporting templates 129, 144 templates with attachments 166 Format label about 146, 150 using 112, 115 formats date/time in templates 159 label/value pairs 153 forms AR System Email Association 251 AR System Email Attachment Join 250 AR System Email Attachments 249 AR System Email Error Logs 240 AR System Email Failover Mail Server Configuration 234 AR System Email Instruction Parameters 251 AR System Email Instructions 250 AR System Email Mailbox Configuration 235 AR System Email Messages 54, 74, 242, 245 AR System Email Security form 241 AR System Email Templates 161, 239 AR System Email User Instruction Templates 240 Modify Email Workflow 128
G
Global Logging Level debug option 177 global parameter declarations 156 Global Property Handlers debug option 177
H
Handler Specific Properties debug option 177, 178 Header Template label 146, 152 header templates about 141 adding 232 using as banners 91 heap, specifying size of email engine 201 HTML adding attachments to templates 162 checkbox buttons 155 label/value pair format 154 mail status template 231 menu fields 155 radio buttons 155 sending modify instructions 122 sending outgoing mail in 77 text fields 155 HTML content templates 73, 97 HTML result templates example 229 outgoing mail 93 Index 255
F
failover mail servers about 17 configuration form 234 fields creating templates to search for 223 HTML menu 155 HTML text 155 including in notifications 59 Fields tab 59 filters triggering Notify actions 128 troubleshooting notify 209 Footer Template label 146, 152 footer templates about 141 adding 232 Form label 146, 147
I
IMAP4 protocol 16 incoming mail about 106 character sets 138 displaying advanced options 136 including attachments 116 including body in outgoing mail 101 including incoming attachments in outgoing mail 102 including qualifications 110 keywords and 115 replying to mail with modify instructions 121 sending modify instructions 117 sending queries to email engine 108 sending with user instructions 167, 170 status information 137 storing 242, 245 Submit action and 113 templates 141 using 107 using to modify requests 117 using variables in templates 135 viewing error messages 137 incoming mailboxes about 18 advanced configuration 33 basic configuration 32 configuration form 235 configuring 32 security 39 testing 36, 199 INFO logging level 177 instructions about 18 about user 150, 167 creating user 169 failures 176 modify 42 replying to mail containing modify 121 results of user 171 sending modify in HTML 122 sending modify in plain text 119 sending modify to email engine 117 sending query to email engine 108 sending user in incoming mail 167, 170 storing administrator-defined 240 storing administrator-defined parameters 251 Submit 113 user templates 143 user variables 172
Internet Message Access Protocol. See IMAP4 protocol intervals, changing form entry retrieval 44
J
JavaToMimeMapping.properties file 88
K
Key label 147, 153 keys creating security 39, 127 security configuration form 241 keywords labels and 140, 146 using in submit instructions 115
L
label/value pairs basic format 153 HTML format 154 using in templates 146 XML format 154 labels !ID! 147, 152 !Name! 147, 152 about 140 Action 146, 149 Authentication 146, 148 Footer Template 146, 152 Form 146, 147 Format 112, 115, 146, 150 Header Template 146, 152 Key 147, 153 Language 146, 148 Login 146, 147 Password 146, 147 Qualification 146, 151 Query Action 222 Request ID 147, 153 Result Template 146, 151 RPC Number 146 RPC Port 148 Server 146, 147 Status Template 146, 151 TCP Port 146, 147 using in templates 146 Language label 146, 148 levels, logging 176
256
local parameter declarations 156 localizing notifications 70 logging API errors 176 email engine problems 200 Email Error Logs form 240 errors 174 generating logs on Windows 196 INFO level 177 instruction failures 176 internal email engine errors 176 levels 176 logging.properties file 17 SEVERE level 176 system status 174 transmission failures 176 Logging module 19 logging.properties file 17, 177 Login label 146, 147 menu fields, HTML 155 Message Information tab fields 244, 248 incoming mail 137 outgoing mail 87 Message tab 243, 247 messages See also error messages defining in notifications 61 mapping attachments to 250 Messages tab 61 Messaging Application Programming Interface protocol. See MAPI protocol Modify action about 149 configuring email engine for 42 Modify Email Workflow form 128 modify instructions 117 replying to mail containing 121 sending in HTML 122 sending in plain text 119 modifying attachments in outgoing mail 81 requests with incoming mail 117 requests with workflow 126, 127 template attachments 165 Module Levels debug option 178 modules Configuration 19 Creator 19 Execution 19 Logging 19 Monitor 19 Receiver 19 Sender 19 Monitor module 19
M
mail creating submit 129 creating test 129 incoming 106 outgoing 52 receiving 16 sending 16 templates 140 mail servers about 17 configuring multiple 24 troubleshooting 205 mailboxes See also incoming mailboxes, outgoing mailboxes about 18, 27 changing configuration 208 configuration form 235 configuring 27 incoming 18 outgoing 52 setting up UNIX 213 testing 36 Main Application Level debug option 178 MAPI protocol 17 fixing transport problems 205 generating logs on Windows 196 saving outgoing notifications 44 mapping attachments to email messages 250 matrix, compatibility 11 MBOX protocol 17
N
notifications about 54 creating workflow for 55 defining messages in 61 defining subject line 59 defining templates in 63 deleting 70 displaying date/time values 70 displaying numeric values 70 including attachments 60 including fields 59 localizing 70 numeric values in 70 Index 257
outgoing mail and 53 processing 16 replying to 130 saving outgoing 44 troubleshooting failures 210 troubleshooting notify filters 209 using with email 28 variables and 158 Notify action overriding mailbox configuration for 61 triggering with workflow 56, 128 notify filters creating 128 troubleshooting 209 advanced configuration 30 basic configuration 29 configuration form 235 configuring 28 configuring security 41 specifying default 28 testing 36, 199
P
parameter declarations, global and local 156 Password label 146, 147 passwords identifying invalid application service 203 permissions, verifying Windows account 209 plain text sending modify instructions 119 sending outgoing mail in 75 POP3 protocol 16 Post Office Protocol. See POP3 protocol product support 3 protocols IMAP4 16 Internet Message Access Protocol 16 MAPI 17 MBOX 17 Messaging Application Programming Interface 17 POP3 16 Post Office Protocol 16 Simple Mail Transfer Protocol 16 SMTP 16
O
outgoing mail about 52 adding banners 91 adding templates 82 advanced options 81 AR System Email Messages form and 74 character sets 88 creating workflow for 56 custom headers for SMTP 89 deleting attachments 81 determining message content 88 dynamically assigning templates to 66 error messages 87 HTML content templates 73, 97 HTML result templates 93 improving appearance 22, 89 including attachments 79 including incoming attachments 102 including incoming body 101 modifying attachments 81 notifications 53, 54 replies 53 sending 74 sending in HTML 77 sending in plain text 75 status information 87 status templates 99 storing 242, 245 templates 71, 141 troubleshooting 174 using 53 XML content templates 73 XML result templates 96 outgoing mailboxes about 18 258 BMC Remedy Email Engine Guide
Q
Qualification label 146, 151 qualifications creating templates to search with 224 including in incoming mail 110 shorthand syntax 111 queries Format label and 112 limiting returned data 110 sending to email engine 108 Query action about 149 creating content template with 226 Query Action label 222
R
radio buttons, HTML 155 Receiver module 19 receiving mail 16 replies, creating HTML result template for 227 Reply with Entry field 41 Reply with Result field 41 replying to mail containing modify instructions 121 notifications 130 Request ID label 147, 153 request IDs, creating templates to search for 222 requests creating workflow to modify 127 example of modifying with workflow 126 using incoming mail to modify 117 reserved variables in templates 159 Result Template label 146, 151 result templates about 142 creating HTML for mail reply 227 using HTML with outgoing mail 93 using XML with outgoing mail 96 results, replying with 41 RPC Number label 146, 148
S
searching for entries to modify 132 entries with qualifications 224 fields with templates 223 request IDs with templates 222 Secure Sockets Layer. See SSL security configuration form 241 configuring email 38 creating keys 39, 127 Sender module 19 sending incoming mail with user instructions 167 mail 16 modify instructions in HTML 122 modify instructions in plain text 119 outgoing mail 74 outgoing mail in HTML 77 outgoing mail in plain text 75 queries to email engine 108 user instructions in incoming mail 170 Server label 146, 147 servers
See also failover mail servers, mail servers identifying AR System for email engine 179 SEVERE logging level 176 shorthand qualification syntax 111 Simple Mail Transfer Protocol. See SMTP protocol SMTP protocol about 16 custom headers for outgoing mail 89 SSL, configuring for email engine 45 startup, troubleshooting email engine 202 status HTML template 231 incoming mail 137 outgoing mail 87 system logs 174 Status Template label 146, 151 status templates about 142 outgoing mail 99 storing email messages 242, 245 templates 161 Submit action about 149 creating content template with 226 sending instruction to email engine 113 support, customer 3 syntax label/value pair 153 shorthand qualification 111 system status logs 174
T
tabs Advanced Configuration, incoming mailbox 33, 235 Advanced Configuration, outgoing mailbox 30, 237 Advanced Options, fields 243, 248 Advanced Options, incoming mail 136 Advanced Options, outgoing mail 82 Attachment Alternatives, fields 244, 248 Attachment Alternatives, incoming mail 136 Attachment Alternatives, outgoing mail 86 Attachments, fields 243, 247 Attachments, outgoing mail 79 Basic Configuration, incoming mailbox 32 Basic, incoming mailbox 235 Basic, outgoing mailbox 237 Errors, fields 245, 249 Errors, incoming mail 137 Index 259
Errors, outgoing mail 87 Fields 59 Message 243, 247 Message Information, fields 244, 248 Message Information, incoming mail 137 Message Information, outgoing mail 87 Messages 61 Template Attachments 163 Templates on Advanced Options tab 82, 243, 248 Templates on notify filter 61, 64 Variable Replacement 83, 243, 248 TCP Port label 146, 147 technical support 3 Template Attachments tab 163 templates about 140 adding attachments to HTML 162 adding footer 232 adding header 232 adding to outgoing mail 22, 82 adding to outgoing mail dynamically 66 configuration form 239 content 141 creating 143 creating content with Submit and Query actions 226 creating for user instructions 168 creating reply with HTML result 227 creating to search for request IDs 222 creating to search with qualifications 224 date/time formats 159 deleting attachments 165 examples 221 exporting 129, 144 exporting with attachments 166 footer 141 header 141 header as banner 91 HTML outgoing content 73, 97 HTML outgoing result 93 including attachments 225 instruction 143 mail status in HTML format 231 modifying attachments 165 notifications and 63 outgoing mail and 71 replacing variables with values 83 reserved variables 159 result 142 searching for fields 223 status 142 status for outgoing mail 99 storing 161 tips 161 types 141 upgrading 166 user instruction 143, 167 value/label pairs and 146 variables and 135, 156 XML outgoing content 73 XML outgoing result 96 Templates tab on Advanced Options tab 82, 243, 248 Templates tab on notify filter 61, 64 terminology, email engine 17 testing incoming mailbox 199 mail 129 mailbox configurations 36 outgoing mailbox 199 text fields, HTML 155 time zones, submitting requests across 208 transmission failures 176 troubleshooting API errors 176 AR System server 204 creating debug batch files 192 debugging email engine 177 EmailDaemon.properties file 179 instruction failures 176 logging email engine problems 200 logs 174 mail servers 205 mailbox configuration 36, 198, 208 notification failures 210 notify filters 209 outgoing mail 174 request processing 209 startup 202 time zone issues 208 transmission failures 176
U
UNIX changing heap size 202 debugging email engine 196 setting up mailboxes 213 upgrading email engine 215 templates 166 user instructions about 150, 167 creating 169 creating templates for 168
260
results 171 sending in incoming mail 167, 170 templates 143 variables 172
V
Variable Replacement tab 83, 243, 248 variables notifications and 158 replacing template with values 83 reserved in templates 159 template 156 user instructions and 172 using in incoming mail templates 135 viewing error messages, incoming mail 137 error messages, outgoing mail 87
W
Windows changing heap size 202 debugging email engine 193 fixing MAPI transport problems 205 generating email engine logs 196 verifying account permissions 209 workflow creating for notifications 55 creating to send mail 56 using to modify requests 126
X
XML label/value pair format 154 outgoing content templates 73 outgoing result templates 96
Index
261
262
*969381* *969381* *969381* *969381*
*183969*

BMC Email Server.52101456

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

BMC Email Server.52101456

Hochgeladen von

Copyright:

Verfügbare Formate

BMC Remedy Action Request System 7.6.

BMC Remedy Email Engine Guide

Contacting BMC Software

United States and Canada

Outside United States and Canada

Restricted rights legend

Support by telephone or email

Before contacting BMC Software

License key and password information

BMC Remedy Email Engine Guide

BMC Remedy Action Request System 7.6.04

Optimizing and Troubleshooting Guide Database Reference

BMC Remedy Email Engine Guide

Title Java API

Java Plug-in API

BMC Remedy Email Engine Guide Error Messages Guide

Administrators Everyone Administrators Everyone Administrators / Developers Administrators / Developers

BMC Remedy Action Request System 7.6.04

BMC Remedy Email Engine Guide

Introduction to the Email Engine

Introduction to the Email Engine

BMC Remedy Action Request System 7.6.04

About the Email Engine

BMC Remedy Email Engine Guide

Email Engine terminology

Email Engine terminology

Introduction to the Email Engine

BMC Remedy Action Request System 7.6.04

Email Engine architecture

Email Engine architecture

Figure 1-1: Modules and threads in Email Engine

Introduction to the Email Engine

BMC Remedy Action Request System 7.6.04

Threading model for outgoing mailboxes

How the Email Engine works

BMC Remedy Email Engine Guide

How the Email Engine works

Query instructions translated into API calls to server

Server queries ticket on HD Incident form and returns results

Outgoing email is formatted and assembled

Users log in to mail server to receive new email

BMC Remedy Action Request System 7.6.04

the AR System server, attempting to fulfill her query request.

query information for the HD Incident form.

Improving the appearance of your email

BMC Remedy Email Engine Guide

Improving the appearance of your email

Figure 1-4: Templates dynamically assigned through workflow

Schema: HD Incident Action: Submit Impact: Urgent

Urgent email sent to incoming mailbox.

Urgent email sent to Francie Frontline

Introduction to the Email Engine

BMC Remedy Action Request System 7.6.04

The following steps illustrate the scenario:

Multiple mail server support

BMC Remedy Email Engine Guide

Multiple mail server support

Figure 1-5: Multiple mail servers configured for failover

Mail Server 1: M1 Yes

No Mail Server 2: M2 Yes

Error. Processing stops.

Yes Mail Server 3: M3

Introduction to the Email Engine